Module process 

tokio::process wrapping of the claude binary.

I/O architecture

The subprocess’s stdin and stdout each run inside a dedicated tokio task; the Subprocess surface talks to them over mpsc channels. Two properties fall out:

• Cancel-safe reads. [tokio::io::AsyncBufReadExt::read_line] is documented as not cancel-safe, but [mpsc::Receiver::recv] is. Driving stdout through a reader task lets callers tokio::select! over Subprocess::read_line without losing already-consumed bytes.
• Concurrent writes. Cloning the writer-side mpsc is cheap and Send + 'static. The Subprocess::clone_writer helper hands out a clonable writer backed by the same writer task, so detached control-request dispatch can write concurrently with the reader without serialising on &mut self.

Re-exports

use std::process::Stdio; 🔒

use std::sync::Arc; 🔒

use tokio::io::AsyncBufReadExt; 🔒

use tokio::io::AsyncWriteExt; 🔒

use tokio::io::BufReader; 🔒

use tokio::process::Child; 🔒

use tokio::process::ChildStderr; 🔒

use tokio::process::ChildStdin; 🔒

use tokio::process::ChildStdout; 🔒

use tokio::process::Command; 🔒

use tokio::sync::mpsc; 🔒

use tokio::sync::oneshot; 🔒

use tokio::task::JoinHandle; 🔒

use tracing::debug; 🔒

use tracing::warn; 🔒

use crate::Error; 🔒

use crate::argv::build_args; 🔒

use crate::options::Options; 🔒

use crate::options::WireTee; 🔒

Structs

SharedWriter 🔒

Cloneable writer half of Subprocess - pushes onto the writer task’s mpsc. Multiple clones can write concurrently; the writer task serialises onto the child’s stdin in arrival order.

StderrTail 🔒

The most recent drained stderr lines, capped at STDERR_TAIL_CAP bytes. Oldest lines are dropped first: a failing CLI puts its reason last.

Subprocess

A live claude subprocess driven over channels.

Enums

Closed 🔒

Why the writer task’s stdin is gone, kept beside it so a later write names the cause rather than blaming a call that never ran.

WriterCmd 🔒

A write-side command dispatched to the writer task.

Constants

CLOSE_WAIT_TIMEOUT

Default upper bound on close() wait-for-exit. After this elapses, the child is SIGKILL’d. 5s is generous for a CLI that’s draining in-flight turns; tests that want to verify the kill path drive against a process that ignores stdin EOF. Public so a consumer timing a wait over a session’s teardown can derive it from this budget rather than guess.

LOGGABLE_FLAGS 🔒

Every flag build_args can emit. A user-defined extra_args name is not covered, except where it collides with one of these - forge routes --effort that way, so the collision is the common case rather than a corner.

STDERR_TAIL_CAP 🔒

Upper bound on the drained stderr retained for Error::Process. Large enough for a CLI failure message and its context, small enough that a chatty child can’t pin unbounded memory for the life of the process.

STDIN_WRITE_BOUND 🔒

How long one write to the CLI’s stdin, and its ack, may take before the write fails.

Functions

check_cli_version

Check that the reported claude version is at least min_version. Compares the parsed (major, minor, patch) components numerically.

closed_stdin 🔒

The error a write gets once the stream is closed, naming why it closed.

drain_stderr 🔒

Background drain for the subprocess stderr pipe. Reads lines as UTF-8 (lossy on invalid bytes) and logs each, so the pipe never blocks.

flag_names 🔒

The recognised flag names in an argv, and a count of the -- tokens that are neither recognised nor a declared extra_args name.

kill_group 🔒

SIGKILL every process left in pgid, reporting a failure a caller should tell someone about.

label_stderr_tail 🔒

Prefix the retained tail so it reads as the last thing the CLI wrote rather than as the cause. Nothing here can tell whether it is causal: a session whose only stderr was a startup warning attaches that warning to an exit hours later.

parse_semver_triple 🔒

Parse "<major>.<minor>.<patch>" (any trailing non-numeric suffix ignored). Missing minor/patch default to 0.

query_cli_version

Run <binary> --version synchronously and return the stdout.

spawn_error 🔒

Name what actually failed. A spawn that cannot find the program and one that cannot enter current_dir both surface as ENOENT, so the cwd is re-checked here - this is the only point that holds it.

spawn_reader_task 🔒

spawn_writer_task 🔒

write_one 🔒

Write one line and flush it, as the writer task’s unit of work.

write_stalled 🔒

A stdin write, or its ack, that outlived STDIN_WRITE_BOUND.

Type Aliases

IoAck 🔒

Outcome of one writer-task operation. Sent back over a oneshot the caller provides.