Module runner 

Unified agent runner — one-shot Claude Code spawn for the drone Agent block.

Spawns claude --print --output-format=stream-json as a non- interactive subprocess, drains its stdout through ClaudeTranslator, forwards each AgentEvent on the caller’s tx, and resolves the handle’s final_result with the structured AgentRunResult once the stream emits Done.

Headless and one-shot by design — the drone Agent block’s contract is “send task, wait for done, return result.” The interactive agent pane has its own PTY-based controller in blockcontroller/shell.rs; that path is NOT routed through this runner (see docs/specs/SPEC_UNIFIED_AGENT_TYPES_2026_05_13.md §4.2 — what’s shared is the translator + event shape, not the spawn function).

Structs

AgentRunHandle

Handle returned by run_agent. The caller already holds the mpsc::UnboundedReceiver<AgentEvent> they paired with the tx passed into run_agent; this handle adds the structured terminal value via final_result (drone Agent block’s downstream output) and the instance_id of the backing db_agent_instances row.

Enums

AgentError

Error returned by the runner.

Constants

DEFAULT_CLAUDE_BIN 🔒

ENV_CLAUDE_BIN 🔒

Override the default claude binary name. Set to a full path (or a different binary) for testing or non-PATH installs.

Functions

drain_and_collect 🔒

Drain stdout line-by-line through ClaudeTranslator, forward every emitted event on tx, accumulate the terminal Cost / Done event payloads into an AgentRunResult, wait for the child to exit, and return the result.

drain_async_reader 🔒

Drain an arbitrary async reader of newline-delimited stream-json frames, forward every emitted AgentEvent on tx, and return an accumulator capturing the terminal Cost and Done values.

run_agent

Spawn claude --print --output-format=stream-json per the given AgentTask and AgentRef, drain its stdout through the shared ClaudeTranslator, forward each AgentEvent on tx, and resolve the returned handle’s final_result with an AgentRunResult constructed from the terminal Cost + Done events.

run_agent_with_bin 🔒

Internal entry point — same as run_agent but takes the claude binary path explicitly. Lets tests inject a known-nonexistent path to exercise the spawn-failure path without touching env vars (Rust 1.81+ flags std::env::set_var as unsound under concurrent test execution). The public run_agent is a thin shim that resolves the binary from $AGENTMUX_CLAUDE_BIN or the default.