Claude Code 2.1.296: latest version, changed flags and gotchas

Claude Code 2.1.296 (2026-10-09 19:28 UTC)

• 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)
• 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)
• Added autoCompactWindow to subagent frontmatter and --agents definitions, allowing subagents to auto-compact earlier than the main session. (source)
• Added CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL to run every workflow agent on one model while other subagents retain theirs. (source)
• 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)
• Fixed claude plugin marketplace add, marketplace update and plugin install failing with internal error for marketplaces named like constructor. (source)

Claude Code 2.1.295 (2026-10-08 19:48 UTC)

• 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)
• Added Program Status Protocol (OSC 7501) support: compatible terminals display whether Claude Code is working, waiting on you, or finished. (source)
• Added advice to claude plugin validate when a plugin README has no install command line, printing the line to paste without failing validation. (source)
• 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)
• Fixed claude -p text output dropping earlier responses when background work started another turn; each turn response prints as the turn ends. (source)

Claude Code 2.1.294 (2026-10-08 05:03 UTC)

• Fixed prompt and agent hooks written as instructions (such as "Block commands that...") allowing what they should block. (source)
• 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)

Claude Code 2.1.293 (2026-10-07 18:10 UTC)

• 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)
• 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)
• 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)
• Fixed a memory leak where an HTTP MCP connection kept every request it had sent until it closed. (source)
• 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)

Claude Code 2.1.292 (2026-10-06 18:59 UTC)

• Added --marketplace <source> to claude plugin install: adds the marketplace if needed, then installs the plugin from it. (source)
• 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)
• 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)
• Fixed one-shot claude -p runs stopping a background command 5 seconds after the final result; they now wait for it. (source)
• 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)

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

• 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.

npm 12 installs Claude Code but `claude` will not start (Claude Code 2.1.296)

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=$?"

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)

`--dangerously-skip-permissions` refuses to run as root (Docker, CI containers) (Claude Code 2.1.296)

claude -p --dangerously-skip-permissions "say hi"   # as root
claude -p --permission-mode bypassPermissions "say hi"   # as root

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)

Headless `claude -p` with no credentials (Claude Code 2.1.296)

claude -p "say hi" </dev/null   # fresh machine, no login, no ANTHROPIC_API_KEY

Not logged in · Please run /login
exit=1

Fix: Set ANTHROPIC_API_KEY, or sign in once with claude auth login; claude setup-token creates a long-lived token for a Claude subscription. With --bare, only ANTHROPIC_API_KEY or an apiKeyHelper from --settings is read (claude --help). (source)

`claude purge` on non-existent project directory exits with code 1 (Claude Code 2.1.296)

claude purge --dry-run /root/p

exit=1
No Claude Code project state found for /root/p under /root/.claude.

Fix: Ensure the path passed to claude purge matches an existing project directory tracked under ~/.claude/projects. Since 2.1.293, failed purges exit with code 1 instead of silently succeeding. (source)

`--client-data-url` is hidden from `--help` but still enforced (Claude Code 2.1.296)

claude --client-data-url https://example.invalid/cfg -p "say hi"

exit=1
Error: --client-data-url: the URL must be the https://downloads.claude.ai/ address Anthropic gave you, exactly as given. Claude Code does not start without the configuration it was given; to start without it, remove the flag, or remove CLAUDE_CODE_CLIENT_DATA_URL from your environment or settings.

Fix: Remove the flag or unset CLAUDE_CODE_CLIENT_DATA_URL unless Anthropic gave you that URL. The flag left claude --help in 2.1.287 without a release note. (source)

An unknown `--effort` value is ignored with a warning, not rejected (Claude Code 2.1.296)

claude -p --effort ultra "say hi" </dev/null

Warning: Unknown --effort value 'ultra' — ignoring it and using the default effort. Valid values: low, medium, high, xhigh, max.

Fix: Use one of low, medium, high, xhigh, max. The run continues at the default effort, so a typo in a CI script does not fail the job. (source)

2026-10: 2.1.287 to 2.1.296 (10 releases to 2026-10-10)

• 2.1.296: Sonnet 5.5 cache read price cut to $0.10/Mtok ($0.20 earlier), Read tool allow_large flag, autoCompactWindow for subagents, CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL. (source)
• 2.1.295: onFailure: "block" for hooks, terminal OSC 7501 Program Status Protocol, claude plugin validate install line advice. (source)
• 2.1.294: fixed instruction-based prompt and agent hooks allowing blocked commands; refined Stop/SubagentStop hook judging. (source)
• 2.1.293: Haiku 5.5 default ($0.10/$0.50 Mtok), agentType in subagent status line, isDeferred: false for mods, claude purge exits 1 on failure. (source)
• 2.1.292: server/discover probe for stdio MCP servers (protocol 2026-07-28), Agent tool effort, claude plugin install --marketplace. (source)
• 2.1.290: WebFetch offset for pages over 100,000 characters; WebSearch budget refills at 100 calls/hour. (source)

2026-09: 2.1.257 to 2.1.286 (27 releases)

• 2.1.259: --permission-prompts none for unattended headless hosts; --json on claude plugin validate. (source)
• 2.1.269: claude plugin eval runs a plugin's eval suite and reports scored results. (source)
• 2.1.277: removed the TaskOutput tool; 2.1.280: default model on Pro and Team Standard plans changed from Sonnet to Opus. (source)
• 2.1.285: claude --desktop and claude plugin configure. (source)

2026-08: 2.1.221 to 2.1.252 (27 releases)

• 2.1.222: removed ultraplan; 2.1.224: removed the 200-subagents-per-session cap. (source)
• 2.1.233: todo and task tools no longer available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5 and newer (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 restores them). (source)
• 2.1.248: --restricted (or CLAUDE_CODE_RESTRICTED=1) removes the tools that run commands or code. (source)

2026-07: 2.1.198 to 2.1.220 (22 releases)

• 2.1.198: removed the /agents wizard; ask Claude or edit .claude/agents/ instead. (source)
• 2.1.211: --forward-subagent-text; 2.1.212: claude auto-mode reset. (source)
• 2.1.217: subagents no longer spawn nested subagents by default (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). (source)

2026-06: 2.1.160 to 2.1.197 (29 releases)

• 2.1.169: --safe-mode (all customizations off) and /cd. (source)
• 2.1.186: claude mcp login <name> and claude mcp logout <name>. (source)
• 2.1.197: Claude Sonnet 5 became the default model, with a native 1M-token context window. (source)

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)
• 2.1.147: /simplify renamed /code-review, with an effort level. (source)
• 2.1.154: Opus 4.8, defaulting to high effort; 2.1.157: claude plugin init. (source)