Agents

pragma-cli agent <command>

This is the API agent hooks use to render status into the app. Every command reads the agent id from --agent and the worktree/tab context from the environment.

start / status

pragma-cli agent start --agent <ID> [--worktree <ID>] [--model <ID> [--reasoning <ID>]]
  [--mode <ID>] [--permission-mode <ID>] [--slash-command <NAME>] [--prompt <PROMPT>] [--headless]
pragma-cli agent options --agent <ID>
pragma-cli agent status [--worktree <ID>] [--watch]

start launches a catalog agent through the gateway: with the app open it opens a tab there, and with --headless (or the app closed) the host runs the session itself. --mode and --permission-mode default to the agent's first entry; --slash-command runs that command with --prompt as its input. Every selection is checked against the catalog first. options lists what an agent accepts — models (with reasoning levels), modes, permission modes (defaults marked), and slash commands. status reads the current statuses directly from the server and works while the app is closed; --watch follows changes.

report

pragma-cli agent report --agent <ID> <subcommand>

session-name and session-id are status-less and independent: one renames the tab, the other stores the resume pointer. Report both on session create, rename, and switch; the id is opaque to Pragma, so report the value your harness's own resume flag accepts. Every report from a launch Pragma tracked also carries the run id from PRAGMA_AGENT_RUN_ID as agentRunId, which is how the host attributes it to the right invocation.

attention carries what the user must act on:

• --kind question --question "..." --options '[{"label":"Yes","description":"..."}]' --request-id <id> — a question with tappable options (multi-question forms use --questions with a JSON array).
• --kind command --command "<cmd>" --request-id <id> — a command approval.

Always pass a --request-id and block on the answer (below) — the same prompt renders in the desktop and on paired phones.

Tracked launches

pragma-cli agent run --run-id <ID> -- <argv...>

Internal: do not run it by hand. When Pragma launches an agent whose integration supports resume, the host records the invocation before the command is written and wraps the argv in this wrapper. It sets PRAGMA_AGENT_RUN_ID in the child, reports the start before the spawn and the finish after the child's real exit (never from a cleared status), and exits with the child's code. The host uses that record plus the reported session-id to restore an interrupted session after a crash or server restart — see Sessions & recovery.

ask and answer

# agent side: publish, then block
pragma-cli agent await-decision --agent <ID> --request-id <ID> [--timeout 300]
pragma-cli agent await-answer --agent <ID> --request-id <ID> [--timeout 300] [--dismiss-output <VALUE>]

# publisher side: resolve someone else's request
pragma-cli agent decide --agent <ID> --request-id <ID> (--allow | --deny)
pragma-cli agent answer --agent <ID> --request-id <ID> (--text <REPLY> | --dismiss)

# interjection (fire and forget)
pragma-cli agent input --agent <ID> --text "<message>" [--request-id <ID>]

await-decision prints allow/deny and exits 0; on timeout it prints nothing and exits non-zero, so a harness hook can fall back to its native prompt. await-answer prints the reply text; --dismiss-output turns a dismissal into a normal exit with a value of your choosing.

agent message --agent <ID> (--payload '<JSON>' | --stdin) publishes a rich AgentMessage.

verify

pragma-cli agent verify --agent <ID> [--scenario <ID>] [--jobs <N>] [--headed]
  [--model <ID> | --pick-model-cmd "<args>"] [--attempts <N>] [--fail-fast]

A conformance suite that launches your agent and exercises the whole reporting surface — reply, session naming, command approvals (allowed and denied), question forms, message submit, subagents, aborts, interrupts, usage limits, slash commands, and stream integrity. --scenario slash-commands checks only that the catalog lists well-formed slash commands, and needs no worktree. Scenarios are skipped automatically when the agent's catalog entry declares excludeFeatures. Pass --headed to watch, --prompts <FILE> to override scenario prompts, --jobs (max 16) to parallelize.