CLAUDE_CODE_STOP_HOOK_BLOCK_CAP

Updated October 13, 2026 by Alex Sorokoletov

CLAUDE_CODE_STOP_HOOK_BLOCK_CAP is a Claude Code environment variable: Cap how long a stop hook can block session termination. If you've ever hit Ctrl+C and had Claude Code hang before actually closing — this is why, and this is the fix. A stop hook making an API call or running a slow cleanup script used to hold the session indefinitely. Added between v2.1.138 and v2.1.143 and still present in v2.1.294. It is listed in the official reference.

How to set it

For one session, export it in the shell that starts Claude Code:

export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=<value>
claude

To apply it to every session, add it to the env object of a settings file:

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_STOP_HOOK_BLOCK_CAP": "<value>"
  }
}

Release notes that mention it

• Claude Code v2.1.143 — 27 New Env Vars, /goal, Agent View, and a Free Model Upgrade
• Claude Code Version Tracker: Undocumented Env Vars, Feature Gates & Models

Related variables

• CLAUDE_CODE_EXIT_AFTER_STOP_DELAY: Delay before exit after stop signal (ms).
• CLAUDE_CODE_PARKED_STOP_RETIRES
• CLAUDE_SCRIPT_HOOK_ACK
• ANTHROPIC_BETAS: Comma-separated beta feature headers.
• ANTHROPIC_CUSTOM_HEADERS: Custom HTTP headers (newline-separated Key: Value).
• ANTHROPIC_FEDERATION_RULE_ID
• ANTHROPIC_ORGANIZATION_ID
• ANTHROPIC_WORKSPACE_ID

Frequently asked questions

All variables, searchable: Claude Code environment variables.