Claude Code v2.1.299 Update: Idle Compaction and 50+ Fixes Explained

Claude Code has released version 2.1.299, a large-scale maintenance update following 2.1.296. The changelog lists dozens of additions, fixes, and changes, with the "idle compaction" mechanism and the file mentions environment variable standing out as the most noteworthy. This article breaks down the changes with the biggest impact on developers' day-to-day usage.

Idle Compaction: Solving Cache Expiry in Long Conversations

This is the most practically valuable new feature in this update.

When using Claude Code in the terminal, if a conversation exceeding 200K tokens sits idle for about 54 minutes, the system proactively compacts it before its one-hour prompt cache expires. This means the next message doesn't require reprocessing the entire context, saving both time and tokens.

Several ways to control this behavior:

• Adjust the minimum token count that triggers compaction via CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS (default 200K)
• Set "idleCompaction": false in settings.json to disable it entirely
• Both options require v2.1.290 or later

For developers who often leave Claude Code running on large projects while heading off to a meeting or doing something else, this mechanism significantly reduces the "I come back, ask one question, and have to wait forever" scenario.

Prompt caching is a capability of the Anthropic API: when the prefix portion of a request (system prompt, message history, tool definitions, etc.) is identical to the previous request, the server can directly reuse the already-computed intermediate state, skipping redundant prefill computation. This makes multi-turn long conversations faster to respond and cheaper to bill for input tokens. But it has a time-to-live limit — roughly 1 hour in the Claude Code scenario. Once it expires, the next request has to process the entire context from scratch — for a 200K-token-level conversation, this means considerable wait time and token cost. Idle compaction is designed precisely for this time window: proactively summarize and compact the conversation history before the cache expires, continuing the session with a shorter new context, so that even if the cache expires, the rebuild cost is much smaller. Understanding that "compaction" and "caching" are two distinct layers of mechanism helps you judge when to enable or disable this feature.

New Environment Variables for File Mentions and Media Handling

A new CLAUDE_CODE_DISABLE_FILE_MENTIONS environment variable has been added. When enabled, Claude receives the file path rather than the file content when using @ file mentions, and reads it through its own file tools. This is more controllable when dealing with large or sensitive files.

Another addition is $.prompt.media, which allows the prompt.submit hook of mods installed via managed settings to read image or document bytes attached to the prompt. Combined with the new $.session.identity() (used to determine session login method, organization, and email), the plugin ecosystem is now more complete in terms of permissions and context awareness.

Improved Interaction Between Model and Effort Controls

New /effort and /fast commands have been added to the Agent view, used to set default parameters for new sessions. Typing /model, /effort, or /fast directly opens a selector.

/usage also gained warning prompts for max effort, workflows, always-on context, and large tool results. Additionally, a bug where /usage and the status bar sometimes displayed usage exceeding 100% has been fixed.

For background sessions, the peek panel in the agents view now has a "safe mode" status line, displayed when a session is started with --safe-mode. A bug where background sessions started with --safe-mode silently exited safe mode after being awakened or restarted has also been fixed.

Stability Fixes for Networking, MCP, and the Proxy Layer

This batch of fixes targets enterprise environments and self-hosted scenarios.

Streaming requests through a custom ANTHROPIC_BASE_URL that received no data within 180 seconds would be aborted; this has now been extended to 300 seconds, regardless of whether feature flags are loaded. A bug where feature flag, startup, fast mode, profile, and feedback requests sent to Anthropic incorrectly carried third-party gateway API keys has also been fixed — Anthropic's own API key is still sent normally.

On the MCP side, several edge cases have been fixed:

• MCP servers named constructor or prototype previously could never connect; this is now fixed
• MCP servers blocked by policy checks are no longer started and are directly reported as blocked
• A bug where HTTP connections would hang for 30 seconds when the server doesn't end the response body has been fixed

MCP (Model Context Protocol) is an open protocol led by Anthropic that lets Claude connect to external tools and data sources in a unified way. Claude Code uses it to connect to databases, code hosting platforms, internal systems, and more. Each MCP server is registered by name, and the client invokes it by name. The constructor and prototype issue mentioned above is a classic prototype chain pollution edge case: since these names are also prototype properties of JavaScript objects, using them as keys to look up the table would hit members on the prototype chain rather than actual registered entries, causing the connection logic to be incorrectly skipped. ANTHROPIC_BASE_URL, meanwhile, is the entry point for directing requests to a custom gateway — enterprises often use it to route through their own proxies for auditing, rate limiting, or regional routing — so issues like "feature flag and other requests mistakenly carrying third-party gateway API keys" carry higher risk in self-hosted environments and are fixes worth prioritizing in an upgrade.

The Three Fixes Developers Should Care About Most

The changelog runs nearly 60 entries; the following three have the most direct impact on daily development experience:

Fixes for 2.1.296 regressions. In cloud and headless sessions, when a new message arrived during a restart recovery, already-approved tool calls could be executed twice. A bug where Edit/Retry in Cowork and claude.ai cloud sessions failed to stop the message while a hook was running has also been fixed.

Debug memory leaks. The memory growth issue under heavy debug logging (--debug, --debug-file) has been fixed, along with unbounded memory growth when debug output was written to stderr and the parent process stopped reading, and exit hangs when the debug log was on a disk or network mount that stopped accepting writes.

Terminal wide-character rendering. A series of terminal rendering defects have been fixed, including CJK and emoji mixed text losing the last line or leaving blank lines on wrap, text adjacent to wide characters being truncated, and emoji disappearing at color transitions. For Chinese users, the perceptible improvement from these fixes should be fairly noticeable.

Summary

v2.1.299 is a relatively low-level maintenance release with no disruptive new features, but the introduction of idle compaction fills a gap in the long-session experience. The large number of fixes for MCP edge cases, enterprise proxy configurations, and terminal rendering indicates the project is in a phase of large-scale polish. Teams using custom gateways or MCP servers are advised to upgrade as soon as possible.

One-line Summary

Claude Code v2.1.299 introduces an idle compaction mechanism and fixes numerous MCP, proxy, and terminal rendering issues.

Paragraph Summary

Claude Code has released v2.1.299, a large-scale maintenance update following 2.1.296. The most noteworthy new feature is "idle compaction": when a conversation exceeding 200K tokens sits idle for about 54 minutes, it proactively compacts before the 1-hour prompt cache expires, avoiding reprocessing the entire context on the next question. It can be controlled via CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS and the idleCompaction switch in settings.json. Another addition is CLAUDE_CODE_DISABLE_FILE_MENTIONS, which makes @ file mentions pass only the path, not the content. The Agent view adds /effort and /fast, and /usage gains several usage warnings. On the fix side, coverage includes the 2.1.296 duplicate tool execution regression, memory leaks under heavy debug logging, and terminal rendering issues with mixed CJK and emoji, plus a batch of stability improvements for self-hosted gateways and MCP edge cases.