Skip to content

Claude Code

Claude Code 2.1.295 hooks can fail closed when they break

7 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →

Claude Code 2.1.295 adds one setting for command and HTTP hooks, onFailure: "block". With it, a hook that can’t start, times out or exits with an unexpected code blocks the action it was guarding. Until now, that action went through.

The release notes on GitHub, published October 8, list well over a hundred entries. The hooks setting is the one that changes how you should configure things. Most of the rest is gateway plumbing, MCP reliability fixes and a long run of terminal and plugin bugs.

What fail-closed changes

A hook gets JSON describing the event, on stdin for a command hook or as the POST body for an HTTP hook, and can return a decision. A PreToolUse hook runs before every tool call and can stop it, the Claude Code hooks documentation says.

A hook that broke instead of answering used to let the action through, which is the case the new setting covers. Community guardrail hooks are built to block destructive git and filesystem commands, secret file access and PII leaving the machine, and one tool in the awesome-claude-code-hooks list is documented as one that “fails open on internal errors”.

onFailure: "block" reverses that behaviour for the hooks you mark. The notes give three triggers: the hook can’t start, it times out, or it exits with a code it isn’t supposed to return. The setting is opt-in and covers command and HTTP hooks only. With it on, a guard whose endpoint times out will block the tool call instead of letting it run.

The setting comes one release after a fix for prompt hooks written as “Block commands that...” allowing the very commands they were meant to stop. Several entries in this release also touch guards and permission checks:

  • A mod’s hook could get a deeply nested tool input cut short with no error, “so a guard could pass content it never saw”.
  • Calls a mod made while it reloaded during a plugin hooks worker restart could get past another mod’s guard hook if that hook had a .catch. Those calls are now refused.
  • --tools and --restricted didn’t apply to built-in tools that register after launch, and deprecated tool names could reach tools outside the caller’s tool set.
  • Bash permission checks for for-loops over glob patterns are now more accurate.
  • A tampered cache of server-managed settings could make someone’s own plugin count as organization-managed on machines whose managed settings list or enable plugins.
  • An async hook’s JSON output was ignored when it was printed over several lines.

One wording change also affects anyone who writes guards. When a mod denies a tool call after the tool has already run, Claude and the user are now told that the tool ran and a plugin withheld its result.

Gateway knobs for cloud upstreams

The Claude apps gateway gets the most new configuration. timeouts.upstream_ttfb_ms now works on Bedrock, Vertex, Foundry and other cloud upstreams. It sets how long a stream may take to start before the gateway fails over or returns a 502. Each upstream can also take an optional models list. Only the listed models go to that upstream, on failover too, and a single * in an entry works as a wildcard.

On Amazon Bedrock, token counting behind the gateway, which /context and large file reads use, now calls AWS’s CountTokens API. Before, it sent a one-token model request. The gateway needs the bedrock:CountTokens permission for this. Bedrock regions outside AWS’s US geography also behave differently for models not listed under models:. AWS always refused those requests. The gateway now tries the model in your own region, and a refusal names the model to add.

Background requests behind a gateway now go to Haiku 4.5 instead of the session’s model, and fall back to the session’s model where the gateway doesn’t serve Haiku 4.5. Support cases get easier to trace. The inference audit event carries upstream_request_id, the request ID from Bedrock, the Anthropic API or another upstream. Successful responses carry a request-id header, so request_id in Claude Code telemetry matches the gateway’s audit log.

Smaller operator changes:

  • While its PostgreSQL database is read-only, the gateway logs a warning every 30 seconds that says what fails and how to recover.
  • It now starts with a warning and serves a desktop policy key its bundled Claude Desktop schema doesn’t know, so new Desktop settings don’t need a gateway upgrade.
  • forceLoginMethod: "gateway" and forceLoginGatewayUrl work in your own user settings on machines with no managed settings, so /login opens on that gateway.
  • CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC no longer hides the gateway spend limit in /usage and the status line.
  • Every request on a [1m] model failed when a gateway, Bedrock, Vertex or Foundry refused the context-1m beta. Claude Code now resends without it.

MCP: longer descriptions, calmer reconnects

MCP tool descriptions that the model loads through tool search are now cut at 16,384 characters. The old limit was 2,048.

Remote MCP servers in headless and SDK sessions could stay disconnected after an outage longer than 15 seconds. They could also reconnect in a tight loop to a server that drops every connection right after it connects. Repeated drops now back off, up to 30 seconds. Connections were also being dropped when a server’s error reply happened to contain the name of a network error. Servers that repeat a pagination cursor were asked for the same page up to 20 times on every connect.

Two transport changes may need action. claude.ai connectors now negotiate MCP protocol version 2026-07-28 by default on installs that fetch no flags, and MCP_PROTOCOL_NEGOTIATION=legacy opts out. WebSocket MCP servers now close the connection on any message over 16 MiB, the limit the other transports already had. CSS, JavaScript and XML files returned by MCP tools were saved as .bin, which the Read tool refuses to open. They now get proper extensions, and so do font and icon files.

Headless runs and the terminal

Terminals that implement Program Status Protocol (OSC 7501, an escape sequence a program uses to report its state) can now show whether Claude Code is working, waiting on you or done. For scripted use, claude -p prints a line on stderr, when stderr is a terminal, saying what the run is waiting for if it stays open after its last turn. Its text output also stopped dropping earlier responses when background work started another turn: each turn’s response now prints when that turn ends. CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS limits how long unattended retry mode waits out 429 and 529 errors.

Subagents now preload at most 32 skills from their skills field, each one once. A subagent with the Skill tool can still invoke the rest. Subagents in their own linked worktree had been shown the parent session’s git branch, status and recent commits. Commands and hooks in background sessions had inherited FORCE_COLOR=3, which put color escape codes into the output Claude reads. Both are fixed.

Several fixes deal with freezes: the terminal locked up, ignoring ctrl+c, when a response ran to tens of thousands of lines. Replies whose quotes nested deeper every few lines froze it for seconds and used gigabytes of memory. Syntax highlighting of very long lines, long runs of blank lines, or unclosed strings and heredocs could stall it for minutes. The remaining entries cover plugin installs, Windows drive-letter casing, vim mode, VS Code focus, cloud sessions, Claude Tag in Slack and Code Review. The full list is in the release notes.

If you run a guard hook today, the change is one line on that hook’s config: onFailure: "block". If you use the Bedrock gateway, grant bedrock:CountTokens so /context gets its counts from AWS.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.