## 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](https://github.com/agentclientprotocol/agent-client-protocol/blob/4034a8cbc99bc48fd4579f70a3407b07907e0eb6/docs/protocol/v2/prompt-lifecycle.mdx#L801-L839).
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.
