Claude Code v2.1.300: prompt-cache TTL control, PDF read caps, gzip on by default#

Published by

Part of the Claude Code Version Tracker series. | Official Env Vars | Official Changelog

Claude Code v2.1.300 adds environment variables that pin the messages prompt cache to a five-minute lifetime and cap how many PDF pages the Read tool loads per message and per turn. It turns on gzip for large requests to api.anthropic.com by default, splits cache-write telemetry by lifetime, and ships the advisor tool on Claude Platform on AWS. It follows v2.1.299, with fixes across worktrees, session resume, and cloud sessions.[1]

Smaller requests, cache writes split by lifetime#

Large requests to api.anthropic.com now use gzip compression by default, including when telemetry is turned off; set CLAUDE_CODE_GZIP_REQUEST_BODIES=0 to turn it off.[1] The OpenTelemetry api_request event now reports cache_creation_5m_tokens and cache_creation_1h_tokens separately, so cache writes are counted by their lifetime instead of as a single figure.[1] The new CLAUDE_CODE_MESSAGES_PROMPT_CACHE_TTL variable sits on the other side of that split: set to 5m, it forces the messages prompt cache to the five-minute lifetime. Trace spans also gained GenAI semantic-convention attributes such as gen_ai.provider.name, gen_ai.conversation.id, gen_ai.tool.name and error.type.[1]

PDF reads get a page budget#

The note Claude 3 models get about an @-mentioned PDF was improved so they less often answer without reading it.[1] Two new variables bound how much of a PDF the Read tool pulls in: CLAUDE_CODE_FILE_READ_MAX_PDF_PAGES_PER_MESSAGE caps the pages loaded in a single message, and CLAUDE_CODE_FILE_READ_MAX_PDF_PAGES_PER_TURN caps the running total across a turn.

The advisor tool, and more mod hooks#

The release adds an advisor tool on Claude Platform on AWS; no advisor runs until you pick one with /advisor, advisorModel or --advisor, and CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 turns it off.[1] Mods gained virtualText prompt decorations (text drawn in the prompt box that never enters the submitted prompt), the prompt.change hook (raised when the prompt box changes without a typed edit), and $.ui.view({ agentId }) to show an agent's transcript in the main view. The agent.spawn hook can now rewrite a workflow agent's prompt and model, where before it could only refuse workflow agents.[1]

New Environment Variables#

VariableWhat It Does
CLAUDE_CODE_MESSAGES_PROMPT_CACHE_TTLSet to 5m to force the messages prompt cache to a five-minute lifetime. It sits beside the existing CLAUDE_CODE_PROMPT_CACHE_TTL and CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL controls and pairs with the new 5m/1h cache-write split in telemetry.
CLAUDE_CODE_FILE_READ_MAX_PDF_PAGES_PER_MESSAGECaps how many PDF pages the Read tool loads within a single message. A value below the built-in limit trims the pages pulled in per message.
CLAUDE_CODE_FILE_READ_MAX_PDF_PAGES_PER_TURNCaps the running total of PDF pages the Read tool loads across a turn, working with the per-message cap above.
CLAUDE_CODE_ATTACHMENTS_BY_PATHWhen set, the attachment handler takes the by-path route instead of an upload mode, so attachments are referenced by their file path rather than having their contents uploaded.
CLAUDE_CODE_HIDE_REPLY_SERVER_NAMEWhen the app's own tool server (the one that serves the tools you reply with) cannot sign in, this hides that server's name from Claude, so it does not name or describe the failing server.
CLAUDE_CODE_DISABLE_ADVISOR_TOOLSet to 1 to turn the advisor tool off.

A broad fix pass#

Most of v2.1.300 is corrections. --worktree sessions sometimes started from the wrong commit when a tag or branch was named like a commit ID, and --worktree failed to reopen a worktree in repositories using git's reftable ref storage; both are fixed.[1] Resuming a headless or Agent SDK session could lose the recent messages a compaction had kept, or bring back pre-compaction history, after a reply was cut at the output token limit or retried; those paths were fixed for compactions from this version on.[1] Cloud sessions no longer hang five minutes per turn when the organization's policy cannot be read, and claude daemon stop --any now waits for and force-kills a stuck background service instead of printing "stopped" while it keeps running.[1]

What These Tell Us#

The tuning surface added in v2.1.300 bounds context and cache behavior. A per-message and per-turn page cap limits how much of a PDF the Read tool pulls into a turn, and the messages prompt-cache TTL control pins cache writes to the five-minute lifetime. The telemetry split into cache_creation_5m_tokens and cache_creation_1h_tokens makes those two lifetimes separately measurable.

Request handling changed alongside it: gzip now compresses large requests to api.anthropic.com by default, no longer tied to whether telemetry is on, with an environment-variable opt-out.[1]

The mods API gained prompt-box hooks and view control, and agent.spawn can now rewrite a workflow agent's prompt and model rather than only refuse it. Around those additions, the bulk of the release is fixes: worktree and branch handling in reftable repositories, session resume and compaction history, and cloud-session behavior each got corrections.[1]

Sources#

  1. Claude Code Official Changelog, v2.1.300 release notes

This analysis is conducted for educational and research purposes under fair use principles. All trademarks and software referenced belong to their respective owners.

Let's Connect

BlueskyLinkedInThreads

Previous Claude Code analysis: v2.1.299 (October 14, 2026)

All 72 Claude Code analyses: Claude Code Version Tracker · Official Claude Code changelog

← Back to all posts