[DOCS] Hooks: add stability warning for many parallel hooks on the same matcher

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks and https://code.claude.com/docs/en/hooks-guide

Section/Topic

Parallel hook execution behavior and limitations

Current Documentation

The hooks documentation states:

"All matching hooks run in parallel, and identical handlers are deduplicated automatically." — hooks.md, hooks-guide.md

And for output merging:

"Multiple hooks' values are concatenated" — hooks.md (SessionStart additionalContext field)

No limitations, caveats, or recommended maximums are mentioned for the number of parallel hooks per matcher.

What's Wrong or Missing

When many hooks (6 in my case) match the same event (e.g., PreToolUse with matcher Bash), Claude Code runs all 6 in parallel and merges their outputs. This intermittently causes sessions to stop mid-execution with no error message. The failure is non-deterministic and only manifests with multiple concurrent hooks — individual hooks always pass in isolation.

Observed behavior:

• 6 PreToolUse:Bash hooks registered, all fire on every Bash tool call
• Sessions intermittently die mid-execution with no error, no stack trace, no log entry
• Controlled reproduction failed because single-hook tests always pass
• Reducing to 1 hook (a dispatcher that runs the 6 sequentially as subprocesses) eliminates the problem entirely

This suggests the race condition is in Claude Code's internal hook output merging layer, not in the hooks themselves. Users have no way to debug or fix this — the only workaround is to reduce the number of parallel hooks.

Suggested Improvement

Add a warning to both hooks.md and hooks-guide.md in the section about parallel execution. Suggested text:

Stability note: All matching hooks run in parallel and their outputs are merged. When many hooks (roughly 4+) match the same event, the parallel output merging may cause intermittent session instability. If you experience unexplained session crashes with multiple hooks on the same matcher, consider consolidating them into a single dispatcher hook that runs them sequentially as subprocesses.

Additionally, a brief "Dispatcher pattern" example in the hooks guide would help users who hit this:

Dispatcher pattern: If you need many hooks on the same matcher, register a single hook that reads stdin once and runs your individual hooks sequentially via subprocess, merging their outputs before returning a single response to Claude Code. This avoids parallel merging while preserving all hook behaviors.

Impact

High - Prevents users from using a feature

Sessions silently dying with no error is a severe failure mode. Users with custom hook setups (the target audience of the hooks feature) are likely to register multiple hooks per matcher and have no way to diagnose the resulting crashes.

Additional Context

• Environment: Claude Code 2.1.x, macOS, 6 PreToolUse:Bash hooks
• Workaround: Single Python dispatcher that runs all 6 hooks sequentially as subprocesses, returning merged output. Eliminates the race condition by ensuring only 1 hook is registered per matcher.
• Reproduction difficulty: Non-deterministic. Occurs under normal usage with 6 hooks but cannot be reliably triggered on demand.