fix(claude-sdk): preserve SDK loop on terminator delivery failure via SDK's native error pipeline

[claudiusthebot]

Summary

When a turn-terminator tool (end_turn, strict react) failed to deliver — Telegram rejected for "Message too long", invalid chat_id, network blip — the PostToolBatch hook terminated the SDK loop anyway. The model saw the error in its tool result but had no turn left to react. End result: silent dropped turn, user sees nothing.

Canonical incident (2026-05-13 13:11Z, Pandario reply 226264): end-of-turn delivery of a 4326-char message hit Telegram's 4096 cap, bridge returned {ok:false, error:\"Message too long...\"}, hook fired regardless, user pinged the bot 24 min later asking what happened.

Supersedes #158 (closed). That PR took a content-sniffing approach in the hook (parse tool_response looking for \"ok\":false). Dylan flagged three real problems: frontend coupling (Telegram bridge shape baked into a generic SDK hook), schema drift (if the bridge envelope changes the check goes blind), false positives (any string containing \"ok\":false would trigger the recovery). This PR uses the SDK's native error pipeline instead.

How it works

1. end_turn.execute and react.execute THROW on {ok:false} instead of returning the failure object silently. A new throwIfFailed helper raises Error(\"<tool> delivery failed: <bridge error>\"). The "what counts as a failure" decision now lives in the tool implementation, where the contract is owned.

2. SDK observes the throw and fires PostToolUseFailure with a typed {tool_name, tool_input, tool_use_id, error, is_interrupt} payload. No string sniffing, no unknown parsing.

3. New PostToolUseFailure hook records the failed tool_use_id in a per-session Set<string>. Ignores interrupts (is_interrupt: true) and non-terminator failures (send, etc).

4. PostToolBatch hook consults the Set — if the terminator's tool_use_id was flagged, deletes the flag and returns {continue: true} to keep the SDK loop alive. Otherwise terminates as before (PR fix(claude-sdk): terminate SDK loop on end_turn (MCP-prefix match + PostToolBatch hook) #122's perf win preserved on the happy path).

5. Hooks share state via closure — buildTurnTerminatorHooks() creates a fresh Set per buildSdkOptions() call. Concurrent chat sessions stay isolated.

Why this is better than #158

• Frontend-agnostic: any frontend whose tools throw on delivery failure gets the same recovery behaviour. The hook never sees bridge envelope shapes.
• Type-safe: PostToolUseFailureHookInput has named fields (tool_name, error, is_interrupt). No unknown parsing.
• No false positives: a tool returning \"ok\":false\" somewhere in its payload no longer accidentally triggers the recovery path. Only a thrown exception counts.
• Schema-drift resistant: changing the bridge envelope shape doesn't break the hook. The tool's execute() decides what's a failure, and the SDK propagates that.

Test plan

• 9 new PostToolUseFailure + PostToolBatch coordination cases:
  • Failed end_turn → loop preserved
  • Failed strict react → loop preserved
  • Successful end_turn → terminates as usual
  • is_interrupt: true ignored (not a real failure)
  • Non-terminator failure (send) ignored
  • Soft react (end_turn: false) failure ignored
  • Defensive: non-PostToolUseFailure events return {continue: true}
  • Flag consumed on first match (no stale-flag bug)
  • Per-session isolation (chat A failure doesn't preserve chat B)
• 8 new messaging-tools cases:
  • end_turn throws on text path / buttons path / missing error field
  • end_turn success path unchanged (returns the bridge result)
  • react strict throws on {ok:false}
  • react soft (end_turn: false) also throws on {ok:false}
  • react success path unchanged
  • react still strips the end_turn param before bridging
• All 33 existing PostToolBatch hook tests still pass.
• npm run typecheck clean
• npm run lint — no new warnings
• npm run test — 2001/2014 pass, 1 pre-existing package.functional flake (verified same flake on main when running tests on a host where Talon daemon is up).

🤖 Generated with Claude Code