[Bug] Prompt cache invalidation: tools array mutation and TTL downgrade during session

Independent confirmation with a second, more frequent trigger — and the fix already exists in the API.

We run a MITM proxy in front of api.anthropic.com and capture every /v1/messages body pre- and post-pipeline (~2.5 GB/day of captures, CC 2.1.220, linux). Same class as your LSP observation, but the dominant trigger on our corpus is deferred tool loading: every ToolSearch load re-sends a different tools[], and since tools[] heads the cache prefix, one load at deep context re-bills the whole context (measured up to ~700k tokens for a single tool load).

The part worth flagging to the CC team: CC 2.1.220 ships the documentation for the mid-conversation-tool-changes-2026-07-01 beta inside its own binary (the docs state availability "Opus onward"), but never uses it on the wire — zero tool_addition blocks from CC across our entire corpus. That beta is precisely the fix for this issue: announce the added tool in a tool_addition block at the tail, leave tools[] byte-stable, cache survives.

We've implemented exactly that as a proxy extension and run it in production: cnighswonger/claude-code-cache-fix#273. Two findings transferable to a native CC fix:

• Support is per model family and an unsupported model rejects the whole request with a 400 (measured: sonnet-5, haiku-4.5 — haiku's error names the gating capability: "requires a model that supports mid-conversation system content"). A native implementation needs the same per-model gate; we measured opus-5 and fable-5 accepting with byte-level wire evidence.
• The announcement message must be re-injected at a stable anchor on every subsequent request (the API is stateless), or the injection itself becomes a new bust class.

🤖 Generated with Claude Code

Update (same day): the full verification toolchain behind these numbers is now also PR'd — pre-pipeline request capture (cnighswonger/claude-code-cache-fix#275) and the replay/census/harvest gate (cnighswonger/claude-code-cache-fix#276) — so the measurements above are reproducible against anyone's own traffic, not just ours.

Method note, since it generalizes: the census in that toolchain classifies every consecutive same-conversation request pair by divergence shape (append-only / splice / replace-edit / tools-delta / …) and prices each class in re-billed bytes — so it surfaces and ranks invalidation causes you have not named yet, rather than confirming known ones. That is how the mid-history classes in this thread were found.

One more measured trigger for this thread: deferred tool schema loads. In a session running with tool search / deferred tools, one mid-session load of a deferred tool's full schema grew tools[] from 32,398 to 49,133 bytes in a single step (+16.7 KB, +52%). tools[] sits at the very front of the cached prefix, so that step is a full prefix invalidation, priced like any cold start. Sanitized before/after snapshot: test/fixtures/harvested/growth-s-633915a8-toolsBytes-2026-07-30.json on our fork.

Sharpened conclusion for this thread: lazy/deferred tool machinery is a cache-invalidation machine as long as the loaded definitions land inside tools[]. Either the schemas a session may load are declared up front, or deferred definitions need a delivery path that does not rewrite the cached prefix front.

🤖 Generated with Claude Code

ISSUE B (the TTL downgrade) appears to have intensified in 2.1.218+. Your capture shows intra-session switching between 1h and 5m on 2.1.220, but on 2.1.218+ the 1h TTL is gone entirely — not a switch, but a complete removal.

Measured across 236 primary sessions (2026-07-21 to 2026-08-05, 2.1.215 to 2.1.222):

• 2.1.215: 19/28 sessions had ephemeral_1h_input_tokens > 0 on all records (1h-only)
• 2.1.218+: 0 sessions with any 1h cache; all records are ephemeral_5m-only

So the "downgrade" in ISSUE B is no longer a session-internal event — it's the steady state. The intra-session switching you observed on 2.1.220 may be a separate mechanism (e.g., compaction-adjacent), but the baseline has shifted to 5m-only.

Filed as #84253 with the full version-by-version breakdown.

✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)

@carrotRakko — on "the 1h TTL is gone entirely on 2.1.218+": I can't reproduce that on 2.1.221. It is still being sent on roughly two-thirds of requests.

I run a local proxy that records every outbound request before anything mutates it, so what follows is Claude Code's own bytes on the wire, not something my side added. Two sessions from today, each version-bound by reading its full transcript rather than the tail — session A carries 2.1.221 on all 3,957 entries from 08:03:56Z to 20:18:34Z, session B on all 1,389 from 15:33:14Z to 19:03:17Z, and each range brackets its capture window. Neither session contains any other version, so these counts are not mixing releases.

Counted per REQUEST, because a long conversation re-sends its whole history every turn and marker instances scale with history length:

| | session A (1,924 req) | session B (666 req) |
|---|---|---|
| ≥1 ttl:"1h" marker | 1,204 (62.6%) | 452 (67.9%) |
| ≥1 default (5m) marker | 656 (34.1%) | 199 (29.9%) |
| ≥1 scope:"global" | 1,207 (62.7%) | 452 (67.9%) |
| no cache_control at all | 64 (3.3%) | 15 (2.3%) |

So if it disappeared on 2.1.218, it came back by 2.1.221 — or the trigger is narrower than a version cutoff, which would be worth pinning down before this is filed as a regression.

Two things in that output I have not seen mentioned in this thread:

1. "scope": "global" is a third field on the marker, and it tracks the 1h shape almost exactly (1,204 vs 1,207; 452 vs 452). Session A has three requests carrying {"type":"ephemeral","scope":"global"} with no ttl, so the two fields are not strictly bound — but they travel together. Anyone comparing "the TTL" across 2.1.218 and 2.1.221 should split those shapes, or the comparison will be noisier than the underlying behavior.
2. Both TTL forms coexist within a single session. This is not a session-wide setting that flips; in session A all four marker shapes appear across the same conversation.

Withdrawn: an earlier version of this comment carried a side note claiming that a cache_control marker moving between requests costs nothing, from a corpus measurement of my own. I have since measured a 610k re-bill whose only pre-pipeline difference is exactly that — a marker leaving the last message — so the note is not safe to stand and I have removed it rather than defend it. It was tangential to this issue either way. The TTL numbers above are unaffected: they are counts of what Claude Code sends, not claims about what it costs.

Happy to run a targeted count if someone can name the 2.1.218 condition more precisely — the capture corpus is queryable.

🤖 Generated with Claude Code — measurements are mine, wording is AI-assisted.

https://claude.ai/code/session_01Ro6h9yyyFPbubuHURLAvDP