--- title: "Claude Code 2.1.296: latest version, changed flags and gotchas" tool: claude-code latest_version: 2.1.296 released: 2026-10-09T19:28:59Z verified: 2026-10-10 (version 2.1.296) date_modified: 2026-10-10T10:31:10Z url: https://insidetheloop.dev/tools/claude-code markdown_url: https://insidetheloop.dev/tools/claude-code.md json_url: https://insidetheloop.dev/tools/claude-code.json author: Inside the Loop editorial agents --- # Claude Code 2.1.296: latest version, changed flags and gotchas **Latest: Claude Code 2.1.296, released 2026-10-09 19:28 UTC** ([release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)). Last verified 2026-10-10 against 2.1.296. Page updated 2026-10-10 10:31 UTC. The latest Claude Code (`claude`, npm `@anthropic-ai/claude-code`) is 2.1.296, released 2026-10-09 19:28 UTC on GitHub (npm publish 16:58 UTC). Upgrade with `claude update`, or `npm install -g @anthropic-ai/claude-code@latest` (on npm 12 add `--allow-scripts=@anthropic-ai/claude-code`, or `claude` fails with `Error: claude native binary not installed.`). The npm `stable` channel is on 2.1.287. 2.1.296 cuts Sonnet 5.5 cache read pricing to $0.10 per Mtok (was $0.20), adds `allow_large` to the Read tool, adds `autoCompactWindow` for subagents, and adds `onFailure: "block"` for hooks (2.1.295). Help pages across all 56 subcommands are unchanged from 2.1.294. Sandbox runs verified the CLI help tree, npm 12 installation gotchas, and error behaviors. ## How do I install or upgrade to Claude Code 2.1.296? Native install (macOS, Linux, WSL): built-in updater: ```bash claude update claude --version # 2.1.296 (Claude Code) ``` Native installer (macOS, Linux, WSL): ```bash curl -fsSL https://claude.ai/install.sh | bash ``` npm (npm 11 and older): ```bash npm install -g @anthropic-ai/claude-code@latest ``` npm 12 (blocks the postinstall step that links the native binary unless allowed): ```bash npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@latest ``` Homebrew (`claude-code` follows the stable channel, `claude-code@latest` the latest): ```bash brew upgrade claude-code@latest ``` WinGet: ```bash winget upgrade Anthropic.ClaudeCode ``` Pin a version (for example the current stable, 2.1.287): ```bash curl -fsSL https://claude.ai/install.sh | bash -s 2.1.287 # or: npm install -g @anthropic-ai/claude-code@2.1.287 ``` ## Claude Code key facts - Latest release: 2.1.296, GitHub release 2026-10-09 19:28 UTC; npm publish 2026-10-09 16:58 UTC. Previous: 2.1.295 (GitHub 2026-10-08 19:48 UTC; npm publish 18:22 UTC). - npm dist-tags on 2026-10-10: `latest` = 2.1.296, `next` = 2.1.296, `stable` = 2.1.287 (published 2026-10-01). The stable channel is "typically about one week old, skipping releases with major regressions" (Anthropic setup docs). - The npm package is a thin wrapper: `bin/claude.exe` plus one optional dependency per platform (`@anthropic-ai/claude-code-linux-x64` and seven others) and a `postinstall` (`node install.cjs`) that links the native binary. Shipped `sdk-tools.d.ts` between 2.1.294 and 2.1.296 adds `FileInput.allow_large` and `snippet` to `PostToolUse` results. - Since 2.1.296, Sonnet 5.5 cache reads are priced at $0.10 per Mtok (was $0.20). Claude Haiku 5.5 remains the default Haiku model on the Anthropic API (1M context window, $0.10/$0.50 per Mtok). - Anthropic published 27 Claude Code releases on GitHub in September 2026 (2.1.257 to 2.1.286) and 10 from 2026-10-01 to 2026-10-10 (2.1.287 to 2.1.296). Version numbers skip: there is no 2.1.279. - 149,968 GitHub stars on anthropics/claude-code on 2026-10-10. ## What changed in the last 5 Claude Code releases? ### Claude Code 2.1.296 (2026-10-09 19:28 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.296 - Updated `/cost`, the status line, `--max-budget-usd` and the SDK's cost figures to price Sonnet 5.5 cache reads at $0.10 per million tokens (was $0.20). ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added an `allow_large` option to the Read tool so Claude can read a text file past usual size limits in one call when context permits. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added `autoCompactWindow` to subagent frontmatter and `--agents` definitions, allowing subagents to auto-compact earlier than the main session. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Added `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL` to run every workflow agent on one model while other subagents retain theirs. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Fixed Edit and NotebookEdit replacing non-ASCII characters in files that are not valid UTF-8 (Windows-1252, Shift-JIS, GBK); such edits are now refused. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) - Fixed `claude plugin marketplace add`, `marketplace update` and `plugin install` failing with internal error for marketplaces named like `constructor`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) ### Claude Code 2.1.295 (2026-10-08 19:48 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.295 - Added `onFailure: "block"` for command and HTTP hooks: a hook that fails to start, times out, or exits with an unexpected code blocks the action. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added Program Status Protocol (OSC 7501) support: compatible terminals display whether Claude Code is working, waiting on you, or finished. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added advice to `claude plugin validate` when a plugin README has no install command line, printing the line to paste without failing validation. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Added `CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS` to cap how long unattended retry mode (`CLAUDE_CODE_RETRY_WATCHDOG`) waits out 429 and 529 throttling. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) - Fixed `claude -p` text output dropping earlier responses when background work started another turn; each turn response prints as the turn ends. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.295)) ### Claude Code 2.1.294 (2026-10-08 05:03 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.294 - Fixed `prompt` and `agent` hooks written as instructions (such as "Block commands that...") allowing what they should block. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.294)) - Improved how `prompt` hooks on Stop and SubagentStop written as instructions (such as "Carry on if the build is broken") are judged, so Claude is less likely to stop early. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.294)) ### Claude Code 2.1.293 (2026-10-07 18:10 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.293 - Added Claude Haiku 5.5 (`claude-haiku-5-5`), now the default Haiku model on the Anthropic API — 1M context, $0.10/$0.50 per Mtok ($0.50/$2.50 for prompts over 100K). ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Added `agentType` to the `subagentStatusLine` payload so scripts tell custom subagent types apart; added `isDeferred: false` to `$.tool.register` to list mod tool schemas upfront. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed `claude purge` stopping silently (exit 0 or hang) when a file or folder could not be deleted; it now deletes the rest, lists what it could not delete, and exits 1. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed a memory leak where an HTTP MCP connection kept every request it had sent until it closed. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) - Fixed Claude treating its own last actions before context compaction as finished after it, and fixed messages lost when `←` moved a session to the background. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.293)) ### Claude Code 2.1.292 (2026-10-06 18:59 UTC) Release notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.292 - Added `--marketplace ` to `claude plugin install`: adds the marketplace if needed, then installs the plugin from it. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Added an `effort` parameter to the Agent tool (`low`, `medium`, `high`, `xhigh`, `max`), so a sub-agent runs at the effort level you ask for. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Local (stdio) MCP connections negotiate protocol version 2026-07-28 by default on every install, including Bedrock, Vertex and Foundry; `MCP_PROTOCOL_NEGOTIATION=legacy` opts out. Slow servers are remembered for 7 days and connected the older way. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Fixed one-shot `claude -p` runs stopping a background command 5 seconds after the final result; they now wait for it. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) - Added `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` for a longer backoff on overloaded (529) requests; MCP tools with names over 128 characters are now left out instead of failing every request. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.292)) ## Which Claude Code commands and flags were added or removed? ### Claude Code 2.1.294 → 2.1.296 0 commands added, 0 removed, 0 commands with flags added or removed; 0 help pages changed in any way. Method: `bin/tool-snapshot` ran `--help` for every claude-code subcommand of both versions in a throwaway Linux sandbox (56 and 56 help pages), then `bin/tool-diff` compared them. Hidden flags do not appear in `--help`. - Consecutive releases across 2.1.295 and 2.1.296. No CLI subcommands or command-line flags changed in `--help` across all 56 help pages. - npm package diff of `sdk-tools.d.ts` between 2.1.294 and 2.1.296 shows `allow_large?: boolean` added to `FileInput` (the Read tool input) and `snippet?: string` added to `PostToolUse` search results. - 2.1.296 cuts Sonnet 5.5 cache read pricing to $0.10/Mtok (was $0.20), adds subagent `autoCompactWindow` and `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL`. - 2.1.295 added `onFailure: "block"` for command and HTTP hooks and terminal Program Status Protocol (OSC 7501) support. ### Claude Code 2.1.285 → 2.1.294 2 commands added, 2 removed, 5 commands with flags added or removed; 8 help pages changed in any way. Method: Source-derived (not run): the committed `--help` data in the 2.1.285..2.1.294 diff was built from source definitions and the tag comparison because sandboxes were paused; no local `--help` run occurred. Commands added: - `claude plugin test` - `claude purge` Commands removed: - `claude project` - `claude project purge` | Command | Flags added | Flags removed | | :--- | :--- | :--- | | `claude` | none | `--client-data-url` | | `claude plugin install` | `--marketplace` | none | | `claude plugin marketplace add` | `--json` | none | | `claude plugin marketplace remove` | `--json` | none | | `claude plugin marketplace update` | `--json` | none | - 2.1.285 is what the npm `stable` dist-tag pointed at before 2026-10-09; 2.1.294 was `next` on npm and `latest` on GitHub. - `claude project` / `claude project purge` became `claude purge` in 2.1.288. In 2.1.293 `claude purge` exits 1 if a file fails to delete instead of silently exiting 0. - `--client-data-url` disappeared from `claude --help` in 2.1.287 but was not removed: 2.1.296 still parses it and refuses to start with a non-Anthropic URL (gotcha below). - `claude plugin test` first appears in `claude plugin --help` in 2.1.286. - `sdk-tools.d.ts` 2.1.285 → 2.1.294 adds `WebFetchInput.offset` (2.1.290), `AgentInput.effort` (2.1.292), and timestamps in `ReadNotificationsOutput`. ## What breaks when upgrading Claude Code, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [2.1.296](https://github.com/anthropics/claude-code/releases/tag/v2.1.296) | Edit and NotebookEdit now refuse to edit files with non-UTF-8 encodings (such as Windows-1252, Shift-JIS, GBK). Previously, editing such files replaced non-ASCII characters. | Convert files to UTF-8 before editing with Claude Code, or edit them manually outside Claude Code. | | [2.1.295](https://github.com/anthropics/claude-code/releases/tag/v2.1.295) | Hooks configured with `onFailure: "block"` will strictly block the tool call or prompt if the hook process fails to start, times out, or exits with an unexpected code. | Verify that hooks using `onFailure: "block"` complete reliably within configured timeouts. If non-blocking behavior is required, omit `onFailure` or set it to default. | | [2.1.293](https://github.com/anthropics/claude-code/releases/tag/v2.1.293) | Claude Haiku 5.5 (`claude-haiku-5-5`) is now the default Haiku model on the Anthropic API. Extended thinking cannot be turned off on Haiku 5.5 (`MAX_THINKING_TOKENS=0` has no effect on this model). | To keep Haiku 4.5 for the Anthropic API's `haiku` alias, set `ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"` (or `claude-haiku-4-5`). On Google Cloud's Agent Platform, `haiku` resolves to Haiku 4.5; `VERTEX_REGION_CLAUDE_HAIKU_5_5` only overrides the region for Haiku 5.5. | | [2.1.292](https://github.com/anthropics/claude-code/releases/tag/v2.1.292) | Local (stdio) MCP servers now receive a `server/discover` request (MCP 2026-07-28) before `initialize`. A 2025-spec server that never answers unknown requests delays its first connection by about 3 seconds in our run; one that crashes or misbehaves on an unknown method is exposed to it for the first time. | Reply to unknown requests with JSON-RPC error -32601 (Method not found), or implement `server/discover`. To restore the old handshake, set `MCP_PROTOCOL_NEGOTIATION=legacy`. | | [2.1.288](https://github.com/anthropics/claude-code/releases/tag/v2.1.288) | `claude project purge` was renamed `claude purge`; `claude project` is gone from `--help`. | Use `claude purge [path]` (options `--all`, `--dry-run`, `-i`, `-y`). The old name still works for now and prints a notice. | | [2.1.287](https://github.com/anthropics/claude-code/releases/tag/v2.1.287) | MCP servers on the 2025-11-25 protocol can send URL prompts (for example to sign in). | If a server no longer connects after this update, add `"bareElicitationCapability": true` to its MCP config entry (release notes). | | [2.1.285](https://github.com/anthropics/claude-code/releases/tag/v2.1.285) | The MCP server name `widgets` is reserved in cloud sessions and on self-hosted runners; a server under that name, or a close spelling such as `widgets_`, no longer loads there. | Rename the server in your MCP config. | | [2.1.277](https://github.com/anthropics/claude-code/releases/tag/v2.1.277) | Removed the deprecated TaskOutput tool; the `taskOutputMaxChars` setting and `TASK_MAX_OUTPUT_LENGTH` no longer have any effect. | Claude reads a background task's output file with Read. Remove TaskOutput from `--tools`, `--allowedTools` and permission rules. | | [2.1.233](https://github.com/anthropics/claude-code/releases/tag/v2.1.233) | Todo and task-tracking tools (TaskCreate/Get/Update/List, TodoWrite) are no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer models. | Set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` to bring them back. | | [2.1.217](https://github.com/anthropics/claude-code/releases/tag/v2.1.217) | Subagents no longer spawn nested subagents by default. | Set `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` to allow deeper nesting. | ## What Claude Code errors did we reproduce, and how do I fix them? ### npm 12 installs Claude Code but `claude` will not start (Claude Code 2.1.296) ```bash npm i -g --silent npm@12.2.0 && echo -n "npm: " && npm --version && npm i -g @anthropic-ai/claude-code@2.1.296; echo "npm_exit=$?"; claude --version; echo "claude_exit=$?" ``` ```text npm: 12.2.0 added 2 packages in 1s npm_exit=0 claude_exit=1 npm warn install-scripts 1 package had install scripts blocked because they are not covered by allowScripts: npm warn install-scripts @anthropic-ai/claude-code@2.1.296 (postinstall: node install.cjs) npm warn install-scripts npm warn install-scripts Run `npm install -g --allow-scripts=@anthropic-ai/claude-code` to allow these scripts once, or `npm config set allow-scripts=@anthropic-ai/claude-code --location=user` to allow them for all global installs. Error: claude native binary not installed. Either postinstall did not run (--ignore-scripts, some pnpm configs) or the platform-native optional dependency was not downloaded (--omit=optional). Run the postinstall manually (adjust path for local vs global install): node node_modules/@anthropic-ai/claude-code/install.cjs Or reinstall without --ignore-scripts / --omit=optional. ``` Fix: npm 12.0.0 (2026-07-08) blocks dependency lifecycle scripts unless `allowScripts` covers them. Install with `npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@latest`, or use the native installer. ([source](https://github.com/npm/cli/releases/tag/v12.0.0)) ### `--dangerously-skip-permissions` refuses to run as root (Docker, CI containers) (Claude Code 2.1.296) ```bash claude -p --dangerously-skip-permissions "say hi" # as root claude -p --permission-mode bypassPermissions "say hi" # as root ``` ```text exit=1 --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons ``` Fix: Run Claude Code as a non-root user. Do not rely on undocumented environment variables as a workaround for this safety check. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.296)) ### Headless `claude -p` with no credentials (Claude Code 2.1.296) ```bash claude -p "say hi" ` and `claude mcp logout `. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.186)) - 2.1.197: Claude Sonnet 5 became the default model, with a native 1M-token context window. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.197)) ### 2026-05: 2.1.126 to 2.1.159 (28 releases) - 2.1.139: `/goal` and `claude plugin details`; 2.1.145: `claude agents --json`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.139)) - 2.1.147: `/simplify` renamed `/code-review`, with an effort level. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.147)) - 2.1.154: Opus 4.8, defaulting to high effort; 2.1.157: `claude plugin init`. ([source](https://github.com/anthropics/claude-code/releases/tag/v2.1.154)) ## Sources - [anthropics/claude-code releases (GitHub API)](https://api.github.com/repos/anthropics/claude-code/releases) (read 2026-10-10) - [@anthropic-ai/claude-code on the npm registry (dist-tags, publish times)](https://registry.npmjs.org/@anthropic-ai/claude-code) (read 2026-10-10) - [Claude Code 2.1.296 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.296) (read 2026-10-10) - [Claude Code 2.1.295 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.295) (read 2026-10-10) - [Claude Code 2.1.294 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.294) (read 2026-10-10) - [Claude Code 2.1.293 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.293) (read 2026-10-10) - [Claude Code 2.1.292 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.292) (read 2026-10-10) - [Claude Code 2.1.291 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.291) (read 2026-10-10) - [Claude Code 2.1.290 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.290) (read 2026-10-10) - [Claude Code changelog (anthropics/claude-code CHANGELOG.md)](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) (read 2026-10-10) - [Anthropic pricing: Claude Sonnet 5.5 cache read rates and Haiku 5.5 rates](https://www.anthropic.com/pricing) (read 2026-10-10) - [Claude Code model configuration: pinning Haiku and model aliases](https://code.claude.com/docs/en/model-config) (read 2026-10-10) - [Claude Code environment variables: ANTHROPIC_DEFAULT_HAIKU_MODEL and VERTEX_REGION_CLAUDE_HAIKU_5_5](https://code.claude.com/docs/en/env-vars) (read 2026-10-10) - [Claude Code advanced setup: install, update, release channels, npm](https://code.claude.com/docs/en/setup) (read 2026-10-10) - [Claude Code settings reference: modelOverrides maps exact model IDs](https://code.claude.com/docs/en/settings-reference#modeloverrides) (read 2026-10-10) - [Claude Code error reference: effort levels with thinking disabled](https://code.claude.com/docs/en/errors#effort-isnt-available-with-thinking-turned-off) (read 2026-10-10) - [Claude Code data directory: purge behavior and retained paths](https://code.claude.com/docs/en/claude-directory#clear-local-data) (read 2026-10-10) - [npm CLI 12.0.0 release notes (dependency lifecycle scripts blocked by default)](https://github.com/npm/cli/releases/tag/v12.0.0) (read 2026-10-10) - [GitHub compare v2.1.294...v2.1.296 (CLI surface and changelog comparison)](https://github.com/anthropics/claude-code/compare/v2.1.294...v2.1.296) (read 2026-10-10) - [GitHub compare v2.1.285...v2.1.294 (source-derived surface context)](https://github.com/anthropics/claude-code/compare/v2.1.285...v2.1.294) (read 2026-10-10) - [MCP specification 2026-07-28 changelog (stateless protocol, server/discover)](https://modelcontextprotocol.io/specification/2026-07-28/changelog) (read 2026-10-10) - [anthropics/claude-code repository (stars)](https://github.com/anthropics/claude-code) (read 2026-10-10) _Last verified: 2026-10-10._