Module claude_proc 

claude -p --output-format stream-json subprocess client.

Unit 9 substrate: drive a claude subprocess, parse its stream-json output, reconstruct assistant text into lines, and capture the concatenated text to .omne/var/runs/<run_id>/nodes/<node_id>.out. The sentinel scanner (Unit 10) and node executor (Unit 11) consume the reconstructed-line iterator exposed here.

The module is intentionally split into two layers:

• StreamParser — a generic BufRead → AssistantLine iterator. Unit tests and downstream reuse (future replay/inspection tooling) drive this directly with canned fixtures; no subprocess required.
• ClaudeProcess — the subprocess wrapper that owns a Child, drains its stderr on a background thread (so the pipe buffer can never deadlock a long-running claude -p on a quiet run), and delegates iteration to a StreamParser<BufReader<ChildStdout>>.

Reconstruction contract (plan R8, spike 2026-04-15):

• Each stream-json line is one envelope. We only care about {"type":"assistant", "message": { "id": ..., "content": [...] }} entries. All other top-level types are skipped — including system.hook_response, which SessionStart hooks emit under -p (spike-confirmed noise) and which must never leak into the sentinel scanner.
• claude -p may split a single logical message across multiple envelopes that share message.id. Text blocks are therefore accumulated into a per-id buffer and flushed when a new id is observed or the stream ends. Flushing splits the buffer on \n, trims each line, drops empties, and yields them in order.
• All received text blocks are written verbatim to the capture file as they arrive. No per-line rewriting: the capture is the raw concatenation of every text block from every assistant message, which matches the plan’s “concatenated assistant text” contract.

Structs

AssistantLine

One reconstructed line of assistant text.

ChildKiller

Cloneable handle that can kill a live ClaudeProcess.

ClaudeProcess

Subprocess wrapper around a live claude -p Child that yields AssistantLine values and, on ClaudeProcess::finish, returns the child’s exit status and captured stderr.

SpawnOpts

Arguments used to build a claude -p invocation.

StreamParser

Parses stream-json envelopes from any BufRead and yields AssistantLine values, while capturing all reconstructed text to a backing file.

Enums

CaptureMode

How StreamParser opens the capture file.

Error

Errors surfaced by the claude -p subprocess client.

Session

Session lifecycle for one claude -p invocation.

Constants

DEFAULT_BIN

Default binary name probed on PATH.

PREFLIGHT_TIMEOUT

Wall-clock budget for preflight (i.e. claude --version). Long enough for a slow Windows process spawn; short enough to fail fast when the host binary is wedged. Runtime invocations (stream) have no timeout at this layer — Unit 11’s executor owns node-level deadlines.

Functions

build_command

Build the Command that spawn would launch. Exposed so tests and Unit 11’s executor can inspect / adjust the argv without actually spawning.

preflight

Run claude --version and return the reported version string.

spawn

Spawn claude -p per SpawnOpts and return the Child.

stream

Wire a live Child into a ClaudeProcess that yields AssistantLine values and writes the reconstructed text to capture_path (truncating any prior content).