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/gotypes.d.ts).

Functions

build 🔒

classify

Classify an agent run failure.

frame_error_text 🔒

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

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).