pmux_agent_turn
Send a prompt to an agent, poll for completion evidence, and return the recovered response. Retries transient busy/starting states and uses fallback on timeout.
Instructions
Primary agent orchestration tool for one full turn: send a prompt, poll for completion evidence, then return the recovered response. Safe to call immediately after a previous turn; transient pre-send busy/starting states are retried within the same pollTimeoutMs budget. Use pmux_agent_capture with the returned marker to resume after timeout; use pmux_send_input/pmux_capture_pane only as low-level fallbacks. Completion evidence from a valid report file or pane markers wins over readiness/runtime-error signals. Without completion evidence, ready plus runtimeError returns status:"agent_error".
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). | |
| pollMs | No | Polling interval in ms after a successful send. Defaults to 2000; minimum 500. | |
| 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. | |
| pollTimeoutMs | No | Total polling timeout in ms after a successful send. Defaults to 120000; max 300000. | |
| 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. |