Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [BUG] ToolSearch unlock invalidates prompt-cache prefix mid-session [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#53132•Fetched 2026-04-26 05:23:33
View on GitHub
Comments
1
Participants
2
Timeline
7
Reactions
0
Author
s6yohos6yoho
Participants
s6yohos6yohotruffle-devtruffle-dev
Timeline (top)
labeled ×6commented ×1
RAW_BUFFERClick to expand / collapse

Preflight Checklist

  • I have searched existing issues and this hasn't been reported yet
  • This is a single bug report
  • I am using the latest version of Claude Code (2.1.119)

What's Wrong?

The first time ToolSearch(select:...) unlocks a deferred tool's schema in a session, the next request invalidates the prompt-cache prefix from the tool registry onward. cache_creation_input_tokens on that turn equals the entire conversation accumulated so far, not the unlocked-schema delta.

Distinct from #42309 (same mechanism on --resume, fixed v2.1.90 for the resume path only) and from the content-drift family (#48734 / #49585 / #40652 / #49038) — trigger here is the registry mutation itself, not byte drift in historical messages.

Evidence

Single session, 80 deduped API turns, 97.4% overall cache_read share. One invalidation event:

turncache_readcache_creationnote
#2467,6212,066normal incremental growth
#2514,75662,594prev step: ToolSearch(select:TaskCreate,TaskUpdate)
#2677,3501,449back to normal

The two unlocked schemas are a few hundred tokens combined; the 62K cache_creation is the entire suffix re-caching. Every other large cache_creation in the session was monotonic growth (cache_read keeps rising), not invalidation.

Mechanism

Tool definitions sit right after the system prompt. Unlocking a deferred tool changes the tool registry block, so the cache prefix from that byte onward stops matching and the entire suffix (system-prompt tail + tools + message history) is rewritten at the cache-write rate. Cost scales linearly with session length at unlock time.

Steps to Reproduce

  1. Run a session long enough to accumulate non-trivial cache_read.
  2. Have the model call ToolSearch(select:<any-deferred-tool>) for a tool not yet unlocked in this session.
  3. Observe the next request: cache_creation_input_tokens ≈ full conversation prefix up to that point; cache_read_input_tokens collapses to roughly the tools-block size.

What Should Happen

Unlocking a deferred tool should not invalidate prefix cache for content unrelated to that tool's schema (system prompt, message history). The incremental schema bytes should be the only cache_creation cost.

Claude Code Version

2.1.119

Platform

Anthropic API

Operating System

Other Linux

extent analysis

TL;DR

The issue can be mitigated by adjusting the cache invalidation logic to only account for the incremental schema changes when unlocking a deferred tool.

Guidance

  • Review the cache invalidation mechanism to ensure it only considers the changed schema bytes, rather than the entire suffix.
  • Verify that the cache_creation_input_tokens only includes the unlocked schema delta, not the entire conversation prefix.
  • Investigate the ToolSearch function to determine why it's causing the cache prefix to be invalidated.
  • Consider implementing a more fine-grained cache invalidation strategy to reduce the impact of tool unlocks on cache performance.

Example

No code example is provided as the issue description does not include specific code snippets.

Notes

The issue seems to be specific to the Anthropic API and Claude Code version 2.1.119. The provided evidence and steps to reproduce suggest a clear understanding of the problem, but a more detailed analysis of the cache invalidation mechanism is required to determine the root cause.

Recommendation

Apply a workaround to adjust the cache invalidation logic, as the issue is not fixed in the current version (2.1.119) and no clear upgrade path is mentioned. This will help mitigate the performance impact of unlocking deferred tools until a more permanent solution is available.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#embedding generation#cache error#pipeline error#runtime error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [BUG] ToolSearch unlock invalidates prompt-cache prefix mid-session [1 comments, 2 participants]