Struct ClaudeDriver 

pub struct ClaudeDriver;

The modular driver for Claude (37-02): owns the stream-json launch, legacy prompt rendering, the pre-31 single-document builder, and the checkpoint-resume relaunch command.

Implementations

impl ClaudeDriver

pub fn exec_command_single_document(prompt: &str) -> (&'static str, Vec<String>)

The pre-31 single-document launch: -p <prompt> positionally with --output-format json.

This is a live path, not a deprecated leftover. Two things select it, and both are deliberate:

• D-09/D-10’s sequencing gate. The stream-json launch is rolled out one stage at a time, starting at Stage::Code. Every stage not yet widened launches through here. That is a sequencing choice about rollout order, which constraint 1 permits — it is emphatically not a prediction about which stages background work, which constraint 1 forbids.
• D-11’s opt-out. An explicit flag (off by default) can force this shape back on for recovery without cutting a release. Automatic fallback on parse failure is rejected: a silent downgrade is the same invisible-degradation class as the bug Phase 31 exists to fix.

The argv is the pre-31 single-document launch body verbatim, so the shipped capture shape (CaptureKind::SingleDocEnvelope) and the 30b isolation tests that guard it (D-12) keep holding bit-for-bit.

pub fn exec_resume_command( session_id: &str, instruction: &str, ) -> (&'static str, Vec<String>)

Build the resume relaunch command for a confirmed checkpoint auto-decide (D-03/D-04, 28-03). Not a trait method — --resume is a Claude-CLI-specific, documented feature (D-05: Claude-only, no Codex/OpenCode accommodation).

Argv order (RESEARCH.md § “Architecture Patterns / Pattern 4”, confirmed): the print flag, the instruction, the resume flag immediately followed by the session id (so the id is parsed as the flag’s value, not a positional argument), the output-format flag with its JSON value, and the permission-bypass flag.

Pitfall 1 (RESEARCH.md, T-28-02) — load-bearing, do not “clean up”: a claude --resumed session restores NEITHER the permission mode NOR the output format from the original launch. Both are re-passed here explicitly even though they look redundant with exec_command’s launch above. Omitting either reintroduces the exact headless hang this phase exists to close: the resumed session halts on a permission prompt with no operator present to answer it, and the prompt is not guaranteed to even reach the captured stdout. resume_command_includes_permission_bypass is the named regression test guarding this specifically — do not delete it as “obviously redundant” with the launch-contract tests above; it guards a DIFFERENT command construction path. Note the resume argv keeps --output-format json and a POSITIONAL instruction even though exec_command no longer does: a resumed session is a single-document relaunch, not a stream-json one.

Trait Implementations

impl AgentDriver for ClaudeDriver

fn build_command( &self, _phase: PhaseId, _prompt: &str, _extra_writable_roots: &[PathBuf], ) -> (&'static str, Vec<String>)

Build the headless stream-json launch (Phase 31, constraint 1).

The prompt is deliberately absent from the returned argv. Under --input-format stream-json the CLI takes its initial user turn from stdin as a JSON document, not from a positional argument; the monitor writes that turn via crate::monitor::user_turn_line. The prompt parameter is kept in the signature for the shared AgentDriver shape — it is unused here on purpose, not by oversight.

--verbose is load-bearing, not decoration: every archived Phase-30 trial that produced a usable capture carried it, and dropping it is untested territory. Do not “clean it up”.

The switch is unconditional and stage-blind — which stages route here is a rollout-order choice made at the call site (claude_stream_launch_enabled), not a prediction this builder makes.

fn name(&self) -> &'static str

Human-readable driver name.

fn render_prompt(&self, intent: &StageIntent) -> String

Render the stage prompt for this agent from a crate::prompt::StageIntent.

fn capabilities(&self) -> DriverCapabilities

Capabilities this driver declares (as-needed; default empty).

fn parse_completion(&self, _output: &str) -> Option<AgentResult>

Parse this agent’s completion signal out of captured output; None when the transport is process-exit (no event stream to scan).

fn health(&self, _state: &State) -> Result<(), String>

Driver-specific pre-launch health check.

fn environment(&self) -> Vec<(String, String)>

Extra environment variables for the agent process tree.

fn sandbox_requirements(&self) -> SandboxRequirements

Sandbox requirements for this agent’s launch.

fn discover(&self) -> Result<(), String>

Discover capabilities from the installed CLI (e.g. codex features list).

fn test_contract(&self) -> Vec<ContractResult>

The conformance suite every driver must pass (37-04).

fn interactivity_mode(&self, _stage: Stage) -> InteractivityMode

The interactivity requirement for running stage headless.

fn workflow_root(&self) -> String

The directory holding this agent’s GSD workflow files, used by the workflow-reference renderer. Defaults to the Codex install; a driver with a different install (e.g. Pi) overrides it.

fn health_classification(&self, state: &State) -> DriverHealth

Classify this driver’s health (the pass/fail AgentDriver::health mapped onto the richer DriverHealth).