pmux_agent_send
Send a prompt to an agent after validating readiness and optionally checking previous turn completion markers, with support for file-based or pane output.
Instructions
Primary agent orchestration tool: validate provider-specific readiness/busy/error state, optionally verify a previous DONE signal or END marker, append the v2.1 PMUX footer, and send the prompt. Use pmux_send_input/pmux_capture_pane only as low-level fallbacks. For fileOutput=true previous turns, pass expectPrevTurnEnd together with expectPrevRequestId so shortened req-keyed markers can be matched. On turn <= 1 only, pane fallback input_queued is treated as a composer placeholder and sent with validation.warning; later turns remain strict. fileOutput defaults true: requestId is generated when omitted, workspaceDir is resolved from workspaces[].directories[0], and expectedReportFile is returned. Use fileOutput:false when pmux_agent_start returned recommendedFileOutput:false; read-only/plan agents cannot write report files. fileOutput=false uses the pane BEGIN/END fallback. agent_busy returns {sent:false, reason:"busy"}. Caller contract: if pmux_agent_capture returns partial/working, do not call pmux_agent_send again until the current turn completes or is explicitly abandoned.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| turn | Yes | Caller-owned turn number. turn=0 is recommended for bootstrap. | |
| tabId | Yes | Target tab id (from pmux_list_tabs / pmux_create_tab). | |
| prompt | Yes | Prompt body to send before the standard PMUX sentinel footer. | |
| agentId | Yes | Caller-owned agent id: ^[a-z0-9][a-z0-9_-]{0,31}$. | |
| provider | Yes | Provider used for readiness/busy checks: codex or claude. | |
| requestId | No | Optional caller-owned request id using the same format as agentId. | |
| fileOutput | No | Defaults to true. true writes response content to the v2.1 report file; false uses pane BEGIN/END fallback. | |
| busyPattern | No | busyPattern regex override. Max 200 chars; compile errors become ToolError. | |
| workspaceId | Yes | Target workspace id (from pmux_list_workspaces). | |
| errorPattern | No | errorPattern regex override. Max 200 chars; compile errors become ToolError. | |
| readyPattern | No | readyPattern regex override. Max 200 chars; compile errors become ToolError. | |
| skipReadyCheck | No | Skip prompt-readiness gating, but still reject launch/error patterns. | |
| maxResponseLines | No | Line limit inserted into the sentinel footer. Defaults to 40. | |
| expectPrevTurnEnd | No | If set, the pane must contain the previous turn's completion marker before sending. For fileOutput=true turns, pair this with expectPrevRequestId. | |
| expectPrevRequestId | No | Optional previous turn request id. Use with expectPrevTurnEnd for fileOutput=true prior-turn validation. | |
| runtimeErrorPattern | No | runtimeErrorPattern regex override. Max 200 chars; compile errors become ToolError. |