claude-code - 💡(How to fix) Fix [DOCS] Stop hook docs omit consecutive block cap and override env var

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

Stop hook input and decision control, plus the stop-hook troubleshooting guidance

Current Documentation

The docs currently say:

In addition to the common input fields, Stop hooks receive stop_hook_active and last_assistant_message. The stop_hook_active field is true when Claude Code is already continuing as a result of a stop hook. Check this value or process the transcript to prevent Claude Code from running indefinitely.

And the troubleshooting guide says:

Claude keeps working in an infinite loop instead of stopping.

Your Stop hook script needs to check whether it already triggered a continuation. Parse the stop_hook_active field from the JSON input and exit early if it's true:

What's Wrong or Missing?

Changelog v2.1.143 introduced a built-in safeguard for repeatedly blocked stop hooks, but the hooks documentation does not describe that behavior.

A. The built-in cap is not documented

The current hooks docs explain how to avoid indefinite looping by checking stop_hook_active, but they do not say that Claude Code now ends the turn with a warning after 8 consecutive stop-hook blocks instead of continuing forever.

B. The override is not documented

The release entry names CLAUDE_CODE_STOP_HOOK_BLOCK_CAP as the override for that threshold, but the environment variable reference does not document this variable.

C. User-visible behavior is missing

The docs do not tell users what happens when the cap is reached, so someone debugging a repeatedly blocking Stop hook has no documentation explaining why the turn stopped with a warning.

Suggested Improvement

Add a short note to the Stop / SubagentStop documentation explaining the built-in circuit breaker, for example:

Claude Code limits repeated Stop-hook continuations. After 8 consecutive blocks, the turn ends with a warning instead of continuing indefinitely. To change that threshold, set CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Also update the troubleshooting section in https://code.claude.com/docs/en/hooks-guide so the "Stop hook runs forever" section mentions that newer versions end the turn after the consecutive-block cap is reached, and add CLAUDE_CODE_STOP_HOOK_BLOCK_CAP to https://code.claude.com/docs/en/env-vars.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.143

Exact changelog entry: "Fixed stop hooks that block repeatedly looping forever - the turn now ends with a warning after 8 consecutive blocks (override via CLAUDE_CODE_STOP_HOOK_BLOCK_CAP)"