fix(coding-agent): skip context-incompatible fallbacks

packages/coding-agent/CHANGELOG.md

@@ -24,12 +24,19 @@
 
 ### Added
 
+- Extensions can subscribe to `retry_fallback_exhausted` to receive bounded,
+  structured diagnostics when no configured fallback can hold the live
+  conversation, including a full-error SHA-256 correlation digest, enabling
+  fresh-context delegation without parsing TUI errors.
 - New `gpt-6-astra` prompt preset, written from scratch against the GPT-6 Astra prompting guide: every `gpt-6-astra` model id (bare, `-fast`, dated snapshots, provider-prefixed, Bedrock `openai.gpt-6-astra`, display name "GPT-6 Astra") now gets a full-core system prompt with an initiative section (bias to action, approval as the last step on a concrete result), explicit instruction precedence for skills and project files, an asynchronous-work section mapping Astra's async-tool training onto background sessions, monitors, child tasks, and detached eval cells (end the turn to wait; no wait tool), calibrated test-first verification, and an engineer-prose writing style with the guide's slop-phrase ban. `promptPreset: "gpt-6-astra"` forces it.
 
 ### Changed
 
 ### Fixed
 
+- Retry fallback now skips context-incompatible model rungs, continues to later
+  candidates, settles when none fit, and never persists a rejected automatic
+  fallback switch or leaks its prompt/tool state into the parent session.
 - Anthropic Messages requests that carry deferred (`defer_loading`) tools no longer fail with `invalid_request_error: tools.N.tool_search_tool_bm25_20251119.name: Input should be 'tool_search_tool_bm25'`. The injected native tool-search server tool is now named `tool_search_tool_bm25` as the API contract requires; the local `tool_search` custom tool is unchanged.
 - Prompt surfaces no longer ship the same guidance twice per turn: the `Task_Management` section stops re-sending the todo tool description, `update_goal` points at the goal audits instead of restating them, and the bash timeout policy hands the waiting doctrine to the terminal section. Roughly 1.5K tokens leave every turn with no rule removed.
 - The shared GPT eval-routing bridge no longer routes multi-call work to the `exec`/`wait` Code Mode tools that were removed in favor of detached `eval` cells; every GPT preset now points at `eval` only.

packages/coding-agent/docs/extensions.md

@@ -825,6 +825,42 @@ pi.on("thinking_level_select", async (event, ctx) => {
 
 Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
 
+#### retry_fallback_exhausted
+
+Fired when retry fallback has a configured chain but no remaining rung can
+continue the parent turn. `exhaustionReason` distinguishes a spent chain from
+one whose candidates cannot hold the live conversation.
+
+```typescript
+pi.on("retry_fallback_exhausted", (event, ctx) => {
+  if (event.exhaustionReason !== "no-context-compatible-candidate") return;
+
+  const candidate = event.rejectedCandidates.find(
+    (rejected) => rejected.reason === "context-unusable",
+  );
+  ctx.ui.notify(
+    `Fresh-context recovery is available through ${candidate?.selector ?? event.chainKey}`,
+    "warning",
+  );
+});
+```
+
+The payload includes `sessionId`, `chainKey`, `from`, `lastError`,
+`lastErrorSha256` (the full pre-truncation error digest),
+`exhaustionReason`, and `rejectedCandidates`. Diagnostics delivered to
+extensions are bounded to 64 KiB of serialized UTF-8: at most 8,192 bytes for
+the terminal error, 16 rejected candidates, 512 bytes per session or
+selector-bearing field, and 2,048 bytes per candidate error.
+Consumers can correlate the bounded `lastError` to a persisted failed message
+by hashing that message's complete error and comparing `lastErrorSha256`.
+The original session event remains available to TUI/RPC listeners with its
+existing `{ chainKey, lastError }` shape.
+
+This hook is notification-only. Senpi starts handlers without waiting for them,
+so a slow or non-settling recovery extension cannot block retry cleanup. An
+extension that delegates should enforce its own exactly-once ownership and
+return quickly after starting background work.
+
 ### Tool Events
 
 #### tool_call