Struct ClaudeAgent 

pub struct ClaudeAgent;

Implementations

impl ClaudeAgent

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 AgentAdapter::exec_command 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 with no equivalent on AgentAdapter (D-05: Claude-only, no Codex/OpenCode accommodation, AgentAdapter itself is untouched).

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 AgentAdapter for ClaudeAgent

fn exec_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 because AgentAdapter is shared with adapters that DO pass it positionally (Codex, OpenCode) — it is unused here on purpose, not by oversight.

Evidence: all three archived Phase 30 harnesses (.planning/phases/30-keep-the-session-alive-past-turn-end/, 30b/30c/30d) launch with exactly this flag set and no positional prompt, then write {"type":"user","message":{"role":"user","content":<prompt>}} to the child’s stdin. 30c-monitor-env-harness.py’s DEFAULT_CLI_ARGV is the literal argv reproduced here.

--verbose is load-bearing, not decoration: every archived 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 — constraint 1 forbids predicting at launch time which stages will background work. The sequencing choice about which stages route here lives at the call site (claude_stream_launch_enabled in pipeline_launch.rs); the shape a not-yet-widened stage gets instead is ClaudeAgent::exec_command_single_document, which is a live path rather than a deprecated one.

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

Human-readable adapter name.

fn completion_signal_detected(&self, _output: &str) -> bool

Detect an agent-specific completion signal in captured output.

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

Extra environment variables for the agent process tree. Codex uses this to disable commit/tag signing inside its sandbox: the operator’s signing agent (ssh-agent/gpg-agent) is unreachable there, so signed commits fail headless with a passphrase error (13-06 dogfood finding — same rationale as the unsigned VersionBump tags). GIT_CONFIG_* env scoping keeps the override out of every repo/global config.

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

Adapter-specific pre-launch readiness check (D-13/D-14 adapter hook, Phase 17c). The default is a no-op — most adapters have nothing extra to check, mirroring Self::extra_env’s empty-default shape. The Err variant is a human-readable failure reason that flows into the preflight gate’s context (run_preflight in devflow-cli/src/main.rs). This is the trait surface Phase 18’s Hermes adapter implements to enforce a non-empty reviewer/receiver set — no built-in adapter (Claude/Codex/OpenCode) overrides it in Phase 17 because no reviewer-set storage exists yet in state.rs/config.rs (review consensus #6).