claude-code - 💡(How to fix) Fix Notification hook matcher for non-recoverable API-error / rate-limit termination [1 comments, 2 participants]

I'm a daily Opus 4.7 / 1M-context user running long-form delivery-cycle skills (30-120 min, parallel subagents, remote control + push notifications). Periodically I hit "Server is temporarily limiting requests · Rate limited" or Request rejected (429). I've applied the official mitigation:

"env": {
  "CLAUDE_CODE_MAX_RETRIES": "15",
  "CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY": "4"
}

That helps. But when the error still surfaces after retries are exhausted, the turn dies silently and I only notice minutes/hours later — especially in unattended remote sessions where the orchestrator state is gone by the time I check.

Ask

Please document and stabilize a Notification hook matcher for non-recoverable API-error events. Proposed name: error_notification (or api_error). It would fire when Claude Code's internal retry loop has exhausted and the turn is about to terminate. Payload should include error class, retry count exhausted, model ID, and timestamp — enough for a user-side handler to play a sound, post to Teams/Slack, or write to a log.

Use case

Long-running orchestrators (delivery cycles, multi-agent reviews, transcription pipelines) survive /compact and re-anchor checkpoints fine — but a silent 429 termination leaves me discovering a dead session way after the fact. A Notification hook firing on termination = proactive awareness without changing recovery semantics.

Why NOT a recovery request

I understand recovery is architecturally outside the hook surface — the retry loop is inside the CLI binary, below any user hook. The ask is AWARENESS, not RECOVERY. Fire-and-forget Notification, same model as the existing permission_prompt matcher.

GitHub #57134 ("Claude Code should surface retry state and handle 429s gracefully") was closed as duplicate and the underlying ask is broader. This request is intentionally narrower: just expose the termination event to the Notification hook surface so user-side observability becomes possible. No CLI behavior change, no retry semantics change.

Environment

• Windows 11 LTSC 2024, single-user dev workstation
• Subscription (not API-key); model opus[1m]
• Claude Code current GA, env block above applied 2026-05-13
• Heavy use: 4 hooks active (Notification, PostToolUse, Stop, SessionStart), 5 MCP servers, ~440 user rules, ~100 user skills

Happy to provide repro details, hook telemetry, or beta-test a documented matcher.

Thanks — 4.7 and the 1M context have reshaped how I work.