[FEATURE] Add circuit-breaker for hook failures to prevent runaway usage consumption

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Plugin hooks in Claude Code have no failure limit. When a hook script has a bug that causes it to
fail on every invocation, Claude Code continues to invoke it indefinitely on every trigger event
(PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, etc.), consuming API credits with each
failed attempt.

I'm a plugin author porting my plugin from macOS to Windows. A path conversion bug caused all my hook
invocations to fail. I stepped away from my machine for ~2.5 hours, and during that time with no
user present:

• ~1,962 hook invocations fired and failed
• 321 API requests were made
• 15%+ of my weekly usage was consumed
• My 5-hour window usage limit was exceeded

There is currently no way for users or plugin authors to protect against this class of failure.

Proposed Solution

Implement a circuit-breaker pattern for hooks:

• Track consecutive failures per hook
• After N consecutive failures (e.g., 3-5), automatically disable the hook for the remainder of the

session

• Display a visible warning to the user: "Hook [hook_name] has been disabled after N consecutive

failures"

• Optionally allow plugin authors to configure failure thresholds in their hook definitions
• Provide a command or setting to re-enable disabled hooks if the user wants to retry

Alternative Solutions

There are no effective workarounds. A plugin author could add internal retry limits to their hook
scripts, but:

• This doesn't protect against the script itself failing to execute (e.g., path not found)
• It places the burden on every individual plugin author rather than solving it at the platform level
• It doesn't help users who install third-party plugins

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

1. A plugin author develops a plugin with hooks on macOS where everything works
2. They begin porting it to Windows and encounter a platform-specific bug (e.g., path conversion)
3. They step away from their machine mid-development
4. The hooks continue firing on every Claude Code event, failing each time
5. With a circuit-breaker, after 3-5 failures the hooks would be automatically disabled and the user

would see a clear warning upon return

1. This would have prevented the loss of 15%+ weekly usage credits from non-interactive, failed API

calls

Additional Context

• Circuit breakers are a well-established resilience pattern in distributed systems
• This affects any platform where a hook script can fail, though Windows path handling makes it more

likely

• The usage consumed produced zero useful work — every API call was processing a hook failure
• This is especially important as the plugin ecosystem grows and more users install third-party

plugins where they may not be able to quickly diagnose hook failures

• If there is any possibility of restoring the usage credits consumed during this incident, I would

greatly appreciate it. The usage was entirely non-interactive with no human at the keyboard, and none
of the API calls produced any useful output.