spawn_agent
Spawn a managed agent or terminal, or resume a captured agent on a fresh surface preserving its ID. Resume: {resume_agent_id:"..."}.
Instructions
Spawn a managed agent or terminal, or resume a captured agent on a fresh surface preserving its ID. Resume: {resume_agent_id:"..."}. Omit new-spawn fields: repo, cli, model, effort, cwd, prompt, boot_prompt_path, worktree, mcp_profile, role, placement, authority, collab_path, parent_agent_id, max_cost_per_agent; these cause INVALID_RESUME_SPEC. Optional resume controls such as force, workspace, focus, report_path and verbose remain supported. Resume restores session context; it does not resend a task. For a new task, check current readiness, then use send_to separately. ok:true/state:started means lifecycle started, not ready or task delivered. At a chooser or permission prompt, inspect the current frame with read_screen before acting; never blindly send Return or assume success. pending_verify leaves delivery unverified; follow wait_for guidance in warning when present; do not resend blindly. Placement is deterministic; boot_prompt_timeout_ms also bounds pane placement. Default successes have at most six fields: ok, agent_id, surface_id, state (spawn outcome), delivered (boot prompt), and optional warning. Use verbose:true for contract_path, report_path, done_marker, transport, worktree, and diagnostics; report_path and done_marker are also in the issued contract file. Failures always keep full detail.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cli | No | New spawn only; omit on resume. CLI tool to launch | |
| cwd | No | Initial working directory for type=terminal | |
| repo | No | New spawn only; omit on resume. Repository name (e.g. 'brainlayer', 'golems') | |
| role | No | Agent job function: implementor, reviewer, or gatherer. Lead callers may omit it to spawn an implementor with worker authority on the right by default; explicit roles and axes still apply. Legacy orchestrator/worker aliases remain accepted. Other Claude callers require an explicit role. | |
| type | No | Spawn an AI agent or a plain terminal | agent |
| focus | No | Leave focus on the created tab instead of restoring the exact origin after initialization. Resume and bare terminals: false forbids focus and fails closed if background initialization is unavailable; omitted may temporarily focus to initialize, then restore the origin. Fresh managed agents retain legacy initialization focus. | |
| 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>`. New spawn only; omit on resume and send a new task separately with send_to after checking readiness. 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 success receipt, including contract_path, report_path, done_marker, transport, worktree, and diagnostics; defaults to at most six fields. Failures always keep full detail. | |
| 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 and verifies closure against it. Pass a distinct FILE path per child (never a directory) to place a report somewhere you already watch. report_path, done_marker, contract_path, coordination_footer_delivered and coordination_footer_note are verbose:true-only fields; the default warning contains any required relay instruction with its exact issued paths or marker. For resume_agent_id calls, coordination_footer_note is folded into warning: the pointer was deliberately not re-delivered, so relay only if the restored session lost its original context. For new spawns, when contract_path is present and folded pointer submission was queued or unverified, warning includes the pointer. 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. When contract_path is absent, inline mode is active or the contract file could not be written, so warning tells YOU to 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. Use {resume_agent_id:"..."}; omit all new-spawn fields listed in the tool description. Optional resume controls remain supported. Check current readiness before sending a new task separately with send_to; no task is automatically resent. | |
| boot_prompt_path | No | New spawn only; omit on resume. 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
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| cwd | No | ||
| role | No | ||
| type | No | ||
| state | No | ||
| title | No | ||
| version | No | ||
| warning | No | ||
| agent_id | No | ||
| delivered | No | ||
| surface_id | No | ||
| cwd_receipt | No | ||
| done_marker | No | ||
| next_action | No | ||
| report_path | No | ||
| retry_count | No | ||
| 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 |