[DOCS] Stop hook docs omit consecutive block cap and override env var

+1 — ran into the 8-block cap last week while testing a Stop hook that gates session-end on verification (.claude/state/stop-verify.log must contain a VERIFIED entry from the last 5 min, otherwise exit 2). When the model loops trying to log-then-stop-then-log, the cap kicks in and the user just sees the turn end silently.

Two concrete docs requests from the user side:

1. Surface the cap warning text in the docs verbatim, so people searching for it can find the connection. Right now if you search for the warning message you get nothing in the official docs.
2. Document the JSON contract for "block but don't count toward cap" (if it exists) — e.g. for diagnostic Stop hooks that report but don't actually want to consume cap slots, it would help to know whether decision: "approve" + stderr message is the right shape.

For anyone hitting this in the wild before docs land: I open-sourced the Stop hook pattern I'm using at https://github.com/ianymu/claude-verify-before-stop (pure bash, MIT) — the relevant bit is using exit 2 for the block + checking stop_hook_active to avoid stacking blocks. The cap behavior caught me by surprise too; would love this documented.

Issue #59583 Verification

Title: [DOCS] Stop hook docs omit consecutive block cap and override env var
Issue Date: 2026-05-16
Verification Date: 2026-06-04
Status: RESOLVED

---

Issue Summary

This issue reports that the Stop hook documentation did not explain the built-in cap that ends a turn after repeated Stop-hook blocks, did not document the CLAUDE_CODE_STOP_HOOK_BLOCK_CAP override, and did not describe the warning users see when that cap is reached.

---

Verification Results

Claim 1: The main hooks page does not document the built-in Stop-hook block cap

Status: RESOLVED

At https://code.claude.com/docs/en/hooks, line 2053 now states: 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 avoid blocking on a condition that will never resolve. Claude Code overrides the hook and ends the turn after 8 consecutive blocks.

Verdict: The main hooks page now documents the built-in circuit breaker and its default threshold of 8 consecutive blocks.

---

Claim 2: The documentation does not describe the user-visible warning behavior when the cap is reached

Status: RESOLVED

At https://code.claude.com/docs/en/hooks-guide, lines 918-920, the troubleshooting guide now says: Claude keeps working instead of stopping, then ends the turn with a warning that the Stop hook blocked too many consecutive times. It then states: Claude Code overrides a Stop hook after it blocks 8 times in a row without progress. At line 931, the same section adds: If your hook legitimately needs more than eight iterations to converge, raise the cap with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

Verdict: The troubleshooting guide now documents both the warning users see and the capped Stop-hook behavior.

---

Claim 3: The environment variable reference does not document CLAUDE_CODE_STOP_HOOK_BLOCK_CAP

Status: RESOLVED

At https://code.claude.com/docs/en/env-vars, line 246, the environment variable table now includes: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP | Maximum number of consecutive times a Stop or SubagentStop hook may block the turn from ending before Claude Code overrides it and ends the turn anyway (default: 8). Set to 0 to disable the cap.

Verdict: The override variable is now documented with its purpose, default behavior, and disable option.

---

Current State

| Claim | Status |
|-------|--------|
| Main hooks page omits the built-in Stop-hook block cap | RESOLVED |
| User-visible warning behavior is missing from the docs | RESOLVED |
| Environment variable reference omits CLAUDE_CODE_STOP_HOOK_BLOCK_CAP | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/hooks
• Lines 2051-2055: The Stop input section now states that Claude Code overrides the hook and ends the turn after 8 consecutive blocks.

• URL: https://code.claude.com/docs/en/hooks-guide
• Lines 916-931: The troubleshooting section explains that the turn ends with a warning after repeated Stop-hook blocks and points users to CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

• URL: https://code.claude.com/docs/en/env-vars
• Lines 246-246: The environment variable table now documents CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, its default of 8, and that 0 disables the cap.

• URL: https://code.claude.com/docs/en/changelog
• Lines 427-427: The changelog entry for v2.1.143 matches the now-documented behavior: the turn now ends with a warning after 8 consecutive blocks (override via CLAUDE_CODE_STOP_HOOK_BLOCK_CAP).

---

Conclusion & Recommendation

Primary Concern: The docs previously failed to explain the Stop-hook consecutive-block cap, the warning shown when that cap is hit, and the override environment variable.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current hooks, troubleshooting, and environment variable pages now document the cap, the warning behavior, and the override variable. The issue's reported documentation gaps are no longer present.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.