[benbrandt]

Summary

Report terminal ACP v2 foreground failures through the standard idle / stopReason: "error" shape, with an error object containing a code and user-facing message. This is the next isolated package after #649 and #650, based on main.

• Carry terminal failure independently of AIR negotiation and of the v1-shaped prompt result. Preserve v1 responses, AIR session-failure metadata, quota, and usage.
• Cover ordinary prompted turns, local commands, compact/review commands, implementation follow-ups, and agent-initiated turns.
• Before insertion, keep the JSON-RPC error response as well as the idle error when foreground work ends. After insertion, keep the successful messageId response and report the work outcome through idle.
• Preserve cancellation precedence, including runtime errors raised while aborting. Retried model errors, individual failed tools, unrelated-turn errors, and idle background errors do not become terminal foreground failures.
• Close unfinished v2 tool calls before the idle failure instead of clearing their tracker first.
• Omit opaque error data from the new standard error object; use safe messages for process loss and unexpected internal exceptions. V2 fallback text for process loss is sanitized too.
• Keep resume snapshots free of failure details so reconnecting does not replay a terminal incident as a new completion.

The specification checked was 4034a8c: v2 failure semantics.

Initial commands, system prompts, and standard subagent sessions remain separate work packages. Existing AIR subagent behavior is unchanged.

Validation

• npm run typecheck — passed, including examples.
• npm test — 1,815 passed; 36 skipped.
• npm run build — passed.
• npm run test:integration — 5 passed against real Codex app-server with a local mock model.
  • The real-process v2 test now verifies terminal HTTP 401 -> idle/error with code -32000, then clears the mock failure and verifies a successful prompt and all resume modes. The mock holds the error across Codex's authentication retry rather than accidentally returning an unrelated error.
• Focused wire/snapshot coverage checks AIR and non-AIR failures, pre-insertion authentication, cancellation races, failed-tool cleanup, implementation failures, unrelated errors, and resume behavior.
• npm run codex-test — live-model smoke test from an empty scratch directory completed with end_turn (backward-compatibility check).
• git diff --check — passed.

The full live-model E2E suite was not run. Failure scenarios use the local model mock rather than changing real credentials or provoking failures against an external provider.