Claude Code v2.1.295: hook failures can block, MCP reconnect backoff, and a retry-wait cap#
Published by Alex Sorokoletov
Part of the Claude Code Version Tracker series. | Official Env Vars | Official Changelog
Claude Code v2.1.295 adds onFailure: "block" for command and HTTP hooks: a hook that cannot start, times out, or exits with an unexpected code now blocks the action instead of letting it through.[1] It also backs off MCP reconnection after repeated drops and adds CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS to cap how long unattended retries wait out rate limits, alongside more than 140 other fixes and refinements.
Hooks, status, and the headless prompt#
The onFailure: "block" option gives a failing hook teeth. Before this release a hook that crashed or timed out was treated as non-blocking; now command and HTTP hooks can be set so that a failure stops the action they guard.[1]
Terminals gain a status signal: with Program Status Protocol (OSC 7501) support, a terminal that implements it can show whether Claude Code is working, waiting on you, or done.[1] For scripted runs, a claude -p session that stays open after its last turn now prints a line on stderr (when stderr is a terminal) saying what it is waiting for.[1]
MCP and plugin reliability#
Remote MCP servers in headless and SDK sessions reconnect more reliably: connections that stayed dropped after an outage longer than 15 seconds now reconnect, and a server that drops each connection right after it connects is backed off up to 30 seconds instead of being retried in a tight loop.[1] Two general MCP fixes also land: servers that repeat a pagination cursor are no longer asked for the same page up to 20 times per connect, and CSS, JavaScript, and XML files returned by MCP tools are saved with their own extensions rather than as .bin, which the Read tool refused.[1]
Plugin handling gets safer. The /plugin Errors tab no longer removes a marketplace that failed to load, and uninstalls its plugins, on Enter without asking first. claude plugin marketplace add now refuses a marketplace whose name no plugin can be installed under instead of reporting success, and plugin install, enable, disable, and marketplace add warn when the settings file they write to does not load.[1]
New environment variables#
Two of these are named in the release notes; two are present in the build but not mentioned there.
| Variable | What It Does |
|---|---|
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS | Caps the total time unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits through 429 and 529 responses. Once the elapsed wait passes the cap, the request stops with a capacity-wait-exhausted error rather than retrying further. Default is no cap. Named in the v2.1.295 release notes.[1] |
CLAUDE_RUNNER_FETCH_SERVER_PROGRESS_CAP_MS | On a self-hosted runner, caps how long a git fetch keeps waiting while the server is still reporting progress on a large repository. Takes milliseconds, clamped between a two-minute floor and a thirty-minute ceiling; 0 or off removes the cap. Default is ten minutes. Named in the v2.1.295 release notes.[1] |
CLAUDE_CODE_RESTRICT_PERSONAL_CONFIG | Limits what a session's own Claude Code files may do. With it set, a user's own agents cannot define their own MCP servers or widen their permission mode, the user's own hooks must succeed, and launching a cloud agent is refused because a cloud session would not carry the limits (it points to isolation worktree instead). Not named in the v2.1.295 release notes. |
CLAUDE_CODE_WEBSEARCH_CITATIONS | Returns web-search results as structured citation blocks carrying source URLs instead of ending the answer with a plain Sources: link list. In a non-interactive session it also joins each run of adjacent text blocks into one and attaches character-span positions for every citation. Not named in the v2.1.295 release notes. |
What These Tell Us#
The through-line is hardening the paths where Claude Code hands control to something outside itself. A hook can now block on its own failure, a server-managed session can fence off what a user's personal agents, hooks, and MCP definitions are allowed to do, and the retry and git-fetch waits that unattended runs depend on became bounded rather than open-ended.
The MCP work reads the same way. The reconnect backoff targets remote MCP servers in headless and SDK sessions. Personal-config restriction and structured web-search citations ship in v2.1.295 without a release-note entry.
Sources#
- Claude Code Official Changelog, v2.1.295 release notes
This analysis is conducted for educational and research purposes under fair use principles. All trademarks and software referenced belong to their respective owners.
Related Versions#
- Claude Code v2.1.294: natural-language prompt and agent hooks now enforce their rule
- Claude Code v2.1.293: Haiku 5.5, subagent status-line agentType, deferred-tool control for mods
- Claude Code v2.1.292: one-command marketplace plugin installs, sub-agent effort levels, and network-path read fixes
- Claude Code v2.1.291: permission-prompt and session-quit regression fixes
- Claude Code v2.1.290: WebFetch paging, scheduled tasks survive resume, web-search refill control
Previous Claude Code analysis: v2.1.294 (October 14, 2026)
Next Claude Code analysis: v2.1.296 (October 14, 2026)
All 70 Claude Code analyses: Claude Code Version Tracker · Official Claude Code changelog