spawn_agent
Launch managed AI agents or terminals, or resume captured agents on fresh surfaces while preserving their IDs, with deterministic placement and evidence-backed boot receipts.
Instructions
Spawn a managed agent or terminal, or resume a captured agent on a fresh surface while preserving its ID. Placement is deterministic; boot_prompt_timeout_ms also bounds pane placement. Boot prompts return evidence-backed receipts. Successful receipts are lean by default; verbose=true restores full transport and diagnostic detail. Failures always keep full detail.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cli | No | CLI tool to launch | |
| cwd | No | Initial working directory for type=terminal | |
| repo | No | Repository name (e.g. 'brainlayer', 'golems') | |
| role | No | Agent job function: implementor, reviewer, or gatherer. Legacy orchestrator/worker aliases remain accepted for compatibility. Claude requires this field explicitly. | |
| type | No | Spawn an AI agent or a plain terminal | agent |
| focus | No | Leave focus on the created agent tab instead of restoring the exact origin after initialization. | |
| force | No | With resume_agent_id only: override missing or inconclusive proof that the old session is not running (no recorded pid, an unproven pid, an unreadable topology or process table) after the caller deliberately verifies the old agent is gone. Does not bypass session or terminal-state requirements. | |
| model | No | OPTIONAL — leave UNSET so the launcher pins the top-tier model. For cli:'codex', an explicit model is checked against Codex's runtime model list before any worktree or surface is created, then passed through to the launcher. Never pass 'opus' for claude — the top Claude model is already the default. | |
| title | No | The caller-supplied agent pane title is applied verbatim (for example `cmuxlayer-WORKER · run1 name-the-tabs`); when omitted or blank, the existing agent-id/surface fallback is retained. Managed identity comes from the agent registry, not this display title (#479/#492). | |
| effort | No | Required for codex new agent spawns: low, medium, high, xhigh, max, ultra. Choose deliberately: medium for well-specified lanes, high for security/open-ended; xhigh and above cost more. Omit on resume (the session keeps its effort) and for other CLIs (effort is invalid). | |
| prompt | No | Max 2-3 short lines. Longer payloads BREAK the receiving pane — write the payload to a file and send one line: `Read and follow <path>`. Inline task prompt to send after the agent is ready. Capped at 500 inline UTF-8 bytes by default; use boot_prompt_path for larger prompts. Mutually exclusive with boot_prompt_path. | |
| verbose | No | Return the full legacy spawn response instead of the lean default. | |
| version | No | SpawnSpec schema version | |
| worktree | No | When set, create or reuse a git worktree before launch. Pass a string such as "tool-usage" as the worktree name, true for a generated name, or an object with name, path, branch, base, create, and reuse. When repoGolem registers the repo with an absolute path, that path is the repo root; otherwise the root is resolved from CMUXLAYER_REPO_HOME, the running checkout, or ~/Gits. true uses <registered-root>/.worktrees/<generated-name> (legacy ~/Gits/<repo>.wt read-fallback until ~2026-09). If a later spawn step fails before a recoverable surface exists, a newly created worktree and branch are rolled back. | |
| authority | No | Authority axis, independent from job function and placement | |
| force_new | No | When true, suppress same repo/workspace/role duplicate-lane warnings. Default false so collab leads see reusable existing agents before spawning another lane. | |
| placement | No | Physical placement axis: left or right. It must agree with authority (lead=left, worker=right). Legacy orchestrator/worker aliases remain accepted. | |
| workspace | No | Target workspace ref. Omit to use the caller/current workspace; pass only when intentionally spawning in a different workspace. | |
| collab_path | No | Lead coordination file; workers inherit their parent lead collab_path unless explicitly supplied. | |
| mcp_profile | No | MCP profile hint for worktree launches. Defaults to inherit. Use sterile/skill_eval or include/exclude lists for narrower evals. | |
| report_path | No | Optional ABSOLUTE override for the engine-issued report path. Omit in almost all cases: the engine issues ~/.cmux/agents/<agent_id>/report.md, returns it here, and verifies closure against it. Pass a distinct FILE path per child (never a directory) to place a report somewhere you already watch. Check coordination_footer_delivered. For resume_agent_id calls, false means the pointer was deliberately not re-delivered: follow coordination_footer_note and relay only if the restored session lost its original context. For new spawns, if false and contract_path is present, folded pointer submission was queued or unverified. Inspect the pane, then relay with send_to({agent_id, text:"Read and follow <contract_path>", press_enter:true}); do not use raw cmux send/send-key. If false and contract_path is absent, inline mode is active or the contract file could not be written, so YOU must relay report_path and done_marker. | |
| halt_escalation | No | Notify the nearest live ancestor when this agent remains awaiting input, idle without done evidence, or wedged past its dwell threshold. Set false for deliberate debugging lanes. | |
| parent_agent_id | No | ID of the parent agent for hierarchical spawning. Normally inferred from the managed caller surface; pass explicitly only when no managed caller supplies the hierarchy. Parent must exist. | |
| resume_agent_id | No | THE way to revive an agent: resume this captured session on a fresh surface, keeping its public agent ID and re-issuing its coordination contract. cmuxlayer never revives a pane by itself (#492) -- a pane you close stays closed -- so a lead that wants an agent back asks here, by id. Refused with a reason when the session transcript is not on disk, rather than opening an empty pane. Mutually exclusive with new-spawn fields. | |
| boot_prompt_path | No | Optional readable prompt-file path. Checked before spawning; multiline or over-cap files are submitted as one `Read and follow <path>` pointer and one final return after readiness. Mutually exclusive with prompt. | |
| allow_long_inline | No | Bypass the inline prompt length cap for a deliberate raw boot-prompt send. Prefer boot_prompt_path for large prompts. | |
| max_cost_per_agent | No | Maximum cost cap in USD for this agent | |
| auto_archive_on_done | No | Deprecated compatibility flag. TASK_DONE updates agent state only; cmuxlayer does not auto-close panes. | |
| boot_prompt_timeout_ms | No | Optional timeout override in milliseconds for pane placement, initial shell readiness, agent launch readiness, and the boot prompt. When omitted, each phase keeps its established default (45s placement, 10s shell, 15s launch, 60s boot prompt). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| cwd | No | ||
| role | No | ||
| type | No | ||
| title | No | ||
| version | No | ||
| agent_id | No | ||
| surface_id | No | ||
| cwd_receipt | No | ||
| done_marker | No | ||
| next_action | No | ||
| report_path | No | ||
| retry_count | Yes | ||
| spawn_state | No | ||
| workspace_id | No | ||
| contract_path | No | ||
| delivered_chars | No | ||
| parent_agent_id | No | ||
| boot_prompt_bytes | No | ||
| boot_prompt_receipt | No | ||
| update_menu_skipped | No | ||
| boot_prompt_delivered | No | ||
| update_menu_text_hash | No | ||
| coordination_footer_note | No | ||
| coordination_footer_bytes | No | ||
| boot_prompt_submit_verified | No | ||
| coordination_footer_delivered | No |