pmux_agent_start
Launches an interactive agent CLI in a new terminal tab, checks shell readiness via boot echo, and provides a boot ID for confirmation. Wait for readiness before sending commands.
Instructions
Primary agent orchestration tool: create a terminal tab, poll briefly for shell readiness, then send an interactive agent CLI command. ORCHESTRATOR CONTRACT: before launching, ask the user which model/effort (and codex sandbox / claude permissionMode) each subagent should use, unless the user already specified them. Use pmux_send_input/pmux_capture_pane only as low-level fallbacks. Returns recommendedFileOutput: false for read-only/plan agents that should be sent fileOutput:false. Boot verification: returns bootId — by default (bootstrapEcho:true) the CLI is launched with a fixed initial prompt that makes the model print a DONE marker (req=bootId), and a SessionStart hook writes a boot-signal file; verify with pmux_agent_wait_ready {bootId, expectEcho:true}, then send user work from turn=1 (bootstrap consumed turn 0; do not pass expectPrevTurnEnd on turn 1). bootstrapEcho costs one tiny model turn — pass false to skip. codex hook trust (실측 2026-07-08): the FIRST launch that wires the boot hook requires a one-time interactive trust approval in the codex TUI — until approved, boot.fileSeen stays false while the echo still works; treat fileSeen:false + echoSeen:true on codex as this case, not a failure. This is non-blocking: after a successful start return, use pmux_agent_wait_ready before sending work. wait_ready launch_failed is meaningful only after start has successfully sent the command; an idle shell before command send is indistinguishable to the stateless wait tool. Session lifetime contract: keep the tab open until the task is finished, then close it with pmux_close_tab. Codex command: codex --no-alt-screen -s ; Claude permissionMode choices are based on claude 2.1.201 and intentionally exclude bypassPermissions; claude effort maps to the --effort flag (claude >=2.1.202).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional display name for the terminal tab. | |
| model | No | Optional model id. Must satisfy ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$; invalid values return ToolError. | |
| effort | No | Optional reasoning effort. codex: -c model_reasoning_effort=<v>; claude: --effort <v> (claude >=2.1.202). | |
| sandbox | No | Codex-only sandbox. Defaults to read-only in the command profile. | |
| provider | Yes | Agent CLI provider: codex or claude. | |
| workspaceId | Yes | Target workspace id (from pmux_list_workspaces). | |
| bootstrapEcho | No | Defaults to true. Appends a fixed single-line initial prompt (positional arg, auto-submitted by both CLIs) asking the agent to print the bootstrap DONE marker, so pmux_agent_wait_ready with {bootId, expectEcho:true} can verify the LLM actually responds — evidence-based boot readiness. Costs one tiny model turn; set false to skip. | |
| permissionMode | No | Claude-only permission mode; bypassPermissions is intentionally excluded. | |
| shellTimeoutMs | No | How long pmux_agent_start waits for the new terminal shell prompt before returning not_shell_ready. Defaults to 5000; max 30000. |