Module failure 

Classification of agent (Claude CLI) run failures into a small, stable taxonomy with a human-readable explanation.

classify() is a pure function: it takes the exit code, the terminating signal, the tail of the child’s stderr, and an optional terminal result frame, and returns an AgentFailure. It does no IO and is exhaustively unit-tested against the real Anthropic error phrasings, so the “why” behind a non-zero exit can be surfaced to the user instead of a bare exit 1.

See docs/specs/SPEC_AGENT_FAILURE_DIAGNOSTICS_2026_06_11.md. This is the P1 (capture + classify) slice; live-stream emission and UI banners are P2/P3.

Structs

AgentFailure

A classified agent failure: the class, a user-facing title + detail, the raw exit evidence, the stderr tail, and whether a retry is worth attempting.

Enums

FailureClass

Stable failure taxonomy. Wire format is snake_case to match the rest of the agent event surface (frontend/types/srv-types.d.ts).

Functions

build 🔒

capitalize_provider 🔒

Title-cases a raw provider id (“claude” -> “Claude”) for the spawn-gate message. reagent P2 on PR #2413: the raw lowercase slug read poorly next to catalog.ts’s real display names (“Claude Code”, “Gemini CLI”); this doesn’t reach for those (Rust has no access to the frontend catalog and duplicating/syncing the full display-name table across languages is disproportionate for one error string) — just enough prettification that the message reads as a proper noun.

classify

Classify an agent run failure.

extract_ambient_home_provider 🔒

Pulls the provider id out of SpawnGateError::AmbientHomeDirNotAllowed’s own Display wording (“this agent’s {provider} identity points directly at your personal …” — identity/resolver/errors.rs). Same “return None on any mismatch rather than guessing” contract as extract_spawn_gate_provider above.

extract_claude_md_seed_provider 🔒

Pulls the provider id out of SpawnGateError::ClaudeMdSeedFailed’s own Display wording (“could not isolate this agent’s {provider} config directory (…): …”).

extract_spawn_gate_provider 🔒

Pulls the provider id out of SpawnGateError::MissingCredentials’s own Display wording (“no credentials for {provider}: the bound account was deleted or is unresolvable. Bind an account for this provider in Connectors → Accounts.” — identity/resolver/errors.rs). Returns None on any mismatch (e.g. that wording drifts) rather than guessing — callers fall back to generic phrasing instead of asserting a specific, possibly wrong, provider name.

first_cli_error 🔒

The first entry of a result frame’s errors list, where Claude Code puts its own failures before any turn (“No conversation found with session ID: …”).

frame_error_text 🔒

Best-effort error text from a terminal stream-json result frame: error.message, else a string error/result, else the subtype.

frame_or_stderr_line 🔒

The one line of text that carries a single-live-instance refusal, with any [AgentMux] prefix removed — the row’s detail. Falls back to the whole trimmed text.

is_error_result_frame 🔒

True if a terminal result frame represents a failure.

mentions_http_status 🔒

True if hay mentions HTTP status code in a status-like context (e.g. “http 429”, “status 429”, “error 429”, “[429]”). Anchoring on a context word avoids the false positives a bare substring would hit — an ISO date like 2026-04-29 contains “429”. (reagent P2 on #1353.)

tail_lines 🔒

Last max_lines non-empty lines of s, further capped to the last max_chars characters (char-safe — never slices mid-codepoint).