CLAUDE_CODE_STOP_HOOK_BLOCK_CAP in Claude Code 2.1.143

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

The official v2.1.143 release notes describe a fix for Stop hooks that repeatedly block completion. After eight consecutive blocks, the turn ends with a warning. CLAUDE_CODE_STOP_HOOK_BLOCK_CAP is the environment-variable override named by that release.

This is a loop limit. It does not define which files an agent may edit, grant permission to a tool, or make a written policy enforceable. The earlier version of this article discussed general team conventions without explaining the actual setting; that was not a useful answer to the title.

Diagnose why the Stop hook keeps blocking

Record the installed Claude Code version, the relevant hook configuration and the messages from each block. Inspect the hook’s completion condition. Does it require a file that the task cannot create, depend on unavailable test infrastructure, or keep requesting work that does not change its own result?

Reproduce the behavior in a disposable repository with no production credentials. Give the hook one condition that can be satisfied, then verify that satisfying it lets the turn finish. Test an unsatisfied condition separately and observe the warning at the configured cap. Keep the command output so another maintainer can distinguish a hook loop from a tool failure.

A higher cap gives the loop more attempts. It does not repair an impossible condition. Change the hook when its requirement is wrong; change the cap only when the additional attempts have an understood purpose. Record the previous value and restore the intended configuration after the experiment.

Keep the controls separate

Use repository instructions to explain the expected workflow. Use permissions and sandbox settings for access restrictions, and choose an appropriate hook event when a check must run before a tool call. A Stop hook checks whether the turn should finish; do not treat it as proof that an earlier action was authorized or harmless.

Keep the investigation with the issue or pull request that changes the hook. Durable instructions can link to the relevant test command and owner, without accumulating every failed run in CLAUDE.md.

Updated 21 September 2026: replaced the generic convention advice with the documented cap behavior, corrected the environment-variable name, and added a reproducible diagnostic procedure.