Claude Code 2.1.293 至 2.1.302：值得啟用的設定

The three changes in Claude Code 2.1.293 to 2.1.302 that matter most are idle compaction (2.1.299), the 12-hook concurrency cap plus fork subagents on by default in headless mode (2.1.302), and onFailure: "block" for hooks (2.1.295). Between 7 and 16 October 2026 the Claude Code team shipped eight releases to npm: 2.1.293, 2.1.294, 2.1.295, 2.1.296, 2.1.299, 2.1.300, 2.1.301 and 2.1.302.[1] Versions 2.1.297 and 2.1.298 never appear in the changelog or on npm. Most entries are fixes for the VS Code panel, cloud sessions and Claude Tag, so this post skips those and covers only what changes your bill, your cache hit rate or what your hooks do when they break. It is the follow-up to the August and September settings roundup.

TL;DR

Idle compaction compacts a 200K+ token conversation after about 54 idle minutes, before the one-hour prompt cache expires. It is on by default in the terminal; "idleCompaction": false turns it off.
Prompt and agent hooks now run at most 12 at a time per event, and fork subagents are on by default in claude -p, the Agent SDK, the desktop app and VS Code.
Add onFailure: "block" to any security hook, so a hook that crashes or times out stops the action instead of waving it through.
Sonnet 5.5 cache reads are now priced at $0.10 per million tokens in /cost and the SDK (was $0.20), and Haiku 5.5 is the default Haiku model.
Upgrade with claude update. Native installs also update themselves in the background.

Every release from 2.1.293 to 2.1.302 at a glance

Dates below are the npm publish dates (UTC).[2] The change column is a paraphrase of the official changelog.[1]

Version	Published	Change that matters	Who should care	Setting or env var

| 2.1.296 | 9 Oct | Sonnet 5.5 cache reads priced at $0.10 per million (was $0.20) in cost figures; autoCompactWindow in subagent frontmatter; default MCP description limit raised from 2,048 to 4,096 | Anyone watching spend; subagent authors | autoCompactWindow, --max-budget-usd |

| 2.1.299 | 14 Oct | Idle compaction in the terminal; /usage warnings for max effort, workflows, always-on context and large tool results; CLAUDE_CODE_DISABLE_FILE_MENTIONS | Anyone who leaves long sessions open over lunch | idleCompaction, CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS |

| 2.1.300 | 14 Oct | updatedInput from PreToolUse and PermissionRequest hooks is now validated; gzip on large API requests; cache-write split by 5m and 1h in OpenTelemetry | Hook authors; people running telemetry | CLAUDE_CODE_GZIP_REQUEST_BODIES=0 |

| 2.1.301 | 15 Oct | Switching to a model with a smaller context window summarizes the conversation with the previous model first; classifier_verdict in OpenTelemetry tool events | Anyone who switches models mid-session | none |

| 2.1.302 | 16 Oct | CLAUDE_CODE_AUTO_MODE_MODEL; fork subagents on by default in headless, SDK, desktop and VS Code; prompt and agent hooks capped at 12 per event; an "Idle compaction" row in /config | Auto mode users; anyone running claude -p in CI | CLAUDE_CODE_AUTO_MODE_MODEL, CLAUDE_CODE_FORK_SUBAGENT=0 |

1. Idle compaction: the one that touches your bill

Prompt caching has a one-hour lifetime on the long setting. If you step away for 70 minutes and send another message, the whole conversation is processed again at full input price instead of the cache-read price. 2.1.299 added a fix for the terminal: a conversation of 200K or more tokens that has been idle for about 54 minutes is compacted before the cache expires, so your next message reprocesses a short summary and not the whole history.[1]

It is on by default. 2.1.302 added an "Idle compaction" row to /config so you can flip it without editing a file, and the notice that appears after an idle compaction now tells you how to turn it off.

The trade-off is real. A compacted conversation loses detail. If you keep a long session open on purpose, with exact file contents and tool output you expect Claude to quote back, compaction at minute 54 can drop that. Two knobs exist:

{
  "idleCompaction": false
}

That goes in settings.json and turns the feature off. To keep it on but change the 200K-token minimum, set the environment variable. Both need version 2.1.290 or later, per the changelog:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "400000"
  }
}

The value 400000 above is an example, not a recommendation. Raising the minimum means only larger conversations get compacted, which suits people whose sessions are mostly short and who only care about the expensive ones. If you want the actual dollar effect of all this, the Claude Max API credits planner lets you plug in your own session counts, and Claude Code Spend Guard adds budget guardrails on top.

2. Cache-read pricing and the Haiku 5.5 default

2.1.296 updated /cost, the status line, --max-budget-usd and the SDK cost figures to price Sonnet 5.5 cache reads at $0.10 per million tokens, down from $0.20.[1] Read the wording carefully: this is the client's cost estimate catching up to a price. If you used --max-budget-usd as a hard stop, the same cache-heavy session now counts for less cache-read spend than before, so a budget you set earlier may be tighter than it needs to be. Check any budget numbers you set before October.

2.1.293 made Claude Haiku 5.5 (claude-haiku-5-5) the default Haiku model on the Anthropic API, with a 1M context window and a price of $0.10 input and $0.50 output per million tokens, rising to $0.50 and $2.50 for prompts over 100K tokens.[1] That 100K cliff is the part people miss. Our Haiku 5.5 pricing breakdown walks through what it does to agent workloads that stuff large files into a cheap model.

3. Fork subagents and the 12-hook cap

Two changes in 2.1.302 affect anyone who runs Claude Code outside an interactive terminal.

Fork subagents are now on by default in more places

A fork subagent (subagent_type: "fork") inherits the parent conversation instead of starting blank. It was already on in the terminal. As of 2.1.302 it is also on in claude -p, the Agent SDK, the desktop app and VS Code. claude mcp serve never offers them.[1] The same release changed the desktop app and VS Code to always run the main conversation's subagents in the background, and a subagent's own Agent calls in headless, SDK, desktop and VS Code now run in the foreground by default.

If a CI job or SDK script of yours depended on the old behaviour, pin it:

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

Turn it off only if you see a reason, such as a cost spike or a change in output. The changelog does not quantify the cost effect, so measure a few runs before deciding.

Prompt and agent hooks: 12 at a time

Prompt hooks and agent hooks now run at most 12 of the same event at once; the rest wait their turn.[1] This only matters if you have a lot of them, for example one per plugin on a PostToolUse event. Each prompt hook is a model call, so 40 of them used to fire in parallel and now fire in batches. Expect batches to queue behind each other if you stack many. The cap applies to prompt and agent hooks, and the changelog does not say it covers command hooks.

4. Make hooks fail closed with onFailure

Before 2.1.295, a command or HTTP hook that could not start, timed out, or exited with an unexpected code let the action through. That is the wrong default for a guardrail. 2.1.295 added onFailure: "block": a hook that fails in any of those ways now blocks the action.[1]

Here is a PreToolUse hook that checks Bash commands and refuses to run them if the checker itself breaks. The hook path is a placeholder for your own script:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/check-bash.sh",
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

Use it for hooks that enforce something: secret scanning, blocking writes to production config, license checks. Do not use it for hooks that are conveniences, like a desktop notification, because a flaky notifier would then block your work. 2.1.300 tightened the same area from the other side: updatedInput returned by PreToolUse and PermissionRequest hooks is now validated like Claude's own tool input, unknown keys are dropped, and input the tool rejects denies the call.

5. Pick the model your auto mode classifier uses

2.1.302 added CLAUDE_CODE_AUTO_MODE_MODEL to choose the model the client-side auto mode classifier uses. It does not change the model for server-side auto mode.[1] The classifier is the check that decides whether a tool call is safe to run without asking you. A smaller model makes that check cheaper and faster; a bigger one is less likely to misjudge a risky command.

{
  "env": {
    "CLAUDE_CODE_AUTO_MODE_MODEL": "claude-haiku-5-5"
  }
}

Think twice before running the classifier on the cheapest model in repositories that touch production credentials. The changelog gives no accuracy numbers for classifier models, so any claim that one is "good enough" is a judgement call you should test on your own tool-call history. The same release also improved server-side auto mode: a conversation too long for the safety check is now compacted, rather than every checked tool call being denied. And 2.1.301 added classifier_verdict and permission_mode to OpenTelemetry tool_decision events, which is how you would measure the question above.

6. Smaller wins worth a minute

Subagent auto-compaction

2.1.296 added autoCompactWindow to subagent frontmatter and to --agents definitions, so a subagent can auto-compact earlier than the main conversation's window.[1] A research subagent that reads 30 files does not need to carry all 30 forward. The changelog does not state the unit or valid range for the value, so check the sub-agents documentation for your version before setting it.

---
name: repo-researcher
description: Reads many files and reports a short summary
autoCompactWindow: 100000
---

The number above is a placeholder to show where the key sits.

MCP descriptions are no longer clipped

Two limits moved. 2.1.296 raised the default cap on MCP tool descriptions sent up front, and on MCP server instructions, from 2,048 to 4,096 characters. 2.1.295 raised the cut-off for descriptions the model loads through tool search from 2,048 to 16,384.[1] If you wrote an MCP server with a long, careful description and wondered why Claude ignored the second half, this is the fix. It also means more tokens per tool, so trim descriptions you no longer need.

Switching to a smaller-context model

2.1.301 changed what happens when you switch to a model with a smaller context window than your conversation. The previous model now summarizes the conversation first, so it fits. Before, you could hit a hard failure.

New /usage warnings

2.1.299 added /usage warnings for max effort, workflows, always-on context and large tool results. These are the four things that most often explain a surprise bill. Run /usage once after upgrading.

What to turn off, and why

Setting	Turn it off when	Cost of leaving it on

| idleCompaction | You keep a long session open on purpose and need exact earlier output preserved | Detail lost after about 54 idle minutes on a 200K+ token conversation |

| Fork subagents (CLAUDE_CODE_FORK_SUBAGENT=0) | A CI or SDK script depended on blank-context subagents | Different subagent output and token use in headless runs |

| Gzip on API requests (CLAUDE_CODE_GZIP_REQUEST_BODIES=0) | A proxy or gateway chokes on compressed bodies | 2.1.300 compresses large requests to api.anthropic.com even with telemetry off |

| onFailure: "block" | The hook is a convenience, not a guardrail | A broken notifier stops real work |

One more option sits in the other direction. If you share a machine with large attachments and want Claude to read files itself, CLAUDE_CODE_DISABLE_FILE_MENTIONS (2.1.299) makes @ mentions pass the file path instead of the contents.

How to upgrade and check you are on the right version

Native installations update themselves in the background, and the update takes effect the next time you start Claude Code. To pull the update now, run:[3]

claude update
claude --version
claude doctor

claude doctor reports the result of the last update attempt. Homebrew, WinGet and Linux package manager installs do not self-update by default, so use your package manager there. If you installed through npm and the global directory is not writable, Claude Code shows a one-time notice at startup. For the commands you will use after upgrading, keep the Claude Code cheat sheet open; and if you are on a team and pay per token, the Opus 5.5 Claude Code plugin and Spend Guard are the two WOWHOW products built for this workflow.

Frequently asked questions

Why is there no 2.1.297 or 2.1.298?

Neither version appears in the official changelog or in the npm version history. The changelog jumps from 2.1.296 to 2.1.299. The sources do not say why, and it is common for version numbers to be skipped when a release is cancelled or folded into the next one.

Does idle compaction apply to the VS Code extension and the desktop app?

The 2.1.299 changelog entry says "in the terminal". It does not claim the VS Code panel or desktop app compact on idle, so assume it does not apply there until the docs say otherwise.

Will fork subagents change my headless Claude Code bill?

It can, in either direction. A fork starts with the parent's context, which can mean more input tokens up front. Compare a few representative runs with CLAUDE_CODE_FORK_SUBAGENT=0 and without it, using the cost figure from the SDK result.

Does the 12-hook cap affect command hooks?

The changelog describes it for prompt and agent hooks only. Command and HTTP hooks are not mentioned in that entry.

Is Haiku 5.5 really cheaper for agents?

Below 100K tokens per prompt, yes: $0.10 in and $0.50 out per million. Above 100K the rates become $0.50 and $2.50, five times higher. Long-context agent loops can cross that line without anyone noticing.

Sources

3. Claude Code setup and update documentation (code.claude.com)

Originally published at wowhow.cloud