Prompt caching

How Claude's prompt cache keys a request, what the cache read and cache write token fields count, and what a cache miss costs.

Verified 2026-09-04: three independent investigations (/investigate, run wf_6d36f04f-246) merged adversarially against primary sources and jq-mined local transcripts, recomputing a review-skill run whose tokens exploded. FACT: primary source or reproduced. HYPOTHESIS: unproven; the runbook measures it. Session-level numbers: Token usage.

Method and sources

The API has no memory

The Messages API is stateless: Anthropic keeps no session. Every call resends the whole conversation in order (tool definitions, system prompt, all messages), and the model processes all of it before generating a token. A 60-turn Claude Code session processes turn 1's content ~60 times, turn 2's ~59; uncached, each pass pays full input price.

Prompt caching stores the processed state of a request's beginning, the prefix; the next request computes only the new end, the suffix.

request N:   [tools][system][msg1][msg2]...[msgK]
             └────────── prefix ─────────┘
request N+1: [tools][system][msg1][msg2]...[msgK][asst reply][new msg]
             └── identical to request N, cached ──┘└─ new suffix ──┘

How cache keys are created

FACT From the prompt-caching docs.

1. Mark breakpoints

   cache_control marks a breakpoint, at most 4 per request. Claude Code sets them; you never do.

2. Hash the prefix

   The server hashes everything from the request's start to each breakpoint: tools, system, messages, in order, byte for byte. The hash is the cache key; it stores key → processed model state.

3. Match the longest key

   The next request matches the longest stored key equal to its beginning, checking breakpoint positions backward within a ~20-position lookback window. Everything up to the match comes from cache.

The four usage fields

FACT Each response's usage splits the request into three input buckets plus output (docs semantics, verbatim).

Why input_tokens is about 2 in Claude Code

Claude Code puts a breakpoint at essentially every request's end, so the whole conversation lands in the two cache buckets; ~2 tokens of structural wrapper remain. FACT input_tokens ≤ 2 on all ~470 sampled Claude Code calls.

A raw API call without a breakpoint at the end (no cache_control) reports the whole prompt as input_tokens, both cache fields 0. In Claude Code the new suffix (new message, previous assistant reply, new tool results) bills once as cache_creation, then as cache_read on every later call.

Worked example: cache hits

A fresh Claude Code session; system prompt, CLAUDE.md and tool definitions total ~5,000 tokens.

1. Call 1: a 100-token question

   Request [5,000 system/tools][100 user], cold, breakpoint at the end. Stores a 5,100-token key over system, tools and question.

   usage: input=2, cache_creation=5,100, cache_read=0, output=300

2. Call 2: a tool runs

   Resent with the 300-token assistant reply (the tool call) and a 400-token tool result appended. Call 1's key matches: 5,100 served at 0.1×, the new 700 processed fresh, a new key covers 5,800.

   usage: input=2, cache_read=5,100, cache_creation=700, output=250

3. Call 3: the next tool result, 1,000 tokens

   cache_read=5,800, cache_creation=1,250 (prev output 250 + result 1,000), input=2

Each token is written once, on its first turn, and read on every later call: at 200k context every call, even "say ok", pays ~200k cache-read tokens.

Worked example: cache miss

Same session, call 40, context 115,000 tokens. Between calls 39 and 40 you toggle a hook, changing the system prompt at about token 2,000. Every long key hashed the old bytes; the longest surviving match is a breakpoint before the change, perhaps the tools block.

FACT Real event from a local transcript, 2026-07-14T19:04:24:

call 39: cache_read=114,903  cache_creation=1,850   input=2   ← normal
call 40: cache_read=32,852   cache_creation=88,743  input=2   ← MISS
call 41: cache_read=121,595  cache_creation=...     input=2   ← healed (32,852+88,743 exactly)

Call 40 read the 32,852 tokens before the change at 0.1× and re-wrote the other 88,743 (everything from the changed byte on, messages unchanged) at the 2× write rate. Misses never bill at base rate or show in input_tokens, which stays 2. Call 41 resumes the recurrence on the rebuilt cache.

FACT The invalidation hierarchy is tools → system → messages: a change invalidates its level and everything after.

Switching thinking levels mid-session

FACT Per the docs' "What invalidates the cache" table (fetched 2026-09-04), the thinking configuration (mode on/off, budget_tokens) is rendered into the prompt. Changing it invalidates the messages-level cache, plus tools and system on models that render it ahead of them. Messages are almost all of a long session's context: treat a mid-session thinking or effort change as a near-full-context 2×-rate rebuild on the next call.

Same for the speed setting (system and message caches), tool_choice and image changes (message blocks).

FACT Thinking blocks cache like other content and count as input when read back. Opus 4.5+ and Sonnet 4.6+ keep previous-turn thinking blocks by default, so a normal user message keeps the cache valid. Older Opus/Sonnet and all Haiku strip prior thinking blocks on non-tool-result user content: the bytes change, invalidating from there.

Switching models mid-session

The docs are silent on whether entries are model-specific. Measured: claude-fable-5 and claude-opus-4-8 share them, on two transcripts with mid-session /model-style switches (8d6cc0a1 in the smine worktree, 5f9a7ba3 in remove-agent-worktree-bug).

fable-5:    in=2  cw=687      cr=187,489    ← last fable call, context ~188k
--- switch ---
opus-4-8:   in=2  cw=0        cr=162,961    ← first opus call READ 163k from
opus-4-8:   in=2  cw=18,659   cr=162,961      cache written by fable, wrote 0
--- switch back ---
fable-5:    in=2  cw=23,317   cr=190,576    ← fable read opus's writes back

The read prefix holds the session's own unique messages, so only the other model can have written it: cross-model reads in both directions.

The full rebuild 2.4h after a switch in 8d6cc0a1 was TTL expiry, not the model change.

Pricing reference

FACT Opus 5 prices.

FACT Fable/Mythos 5.1 reads cost 0.025× ($0.125), 4× cheaper than the 0.1× of non-.1 models.

Rate limits vs plan usage windows

Two systems meter cache tokens differently.

Mining usage from transcripts

jq -s '[group_by(.message.id)[] | map(.message.usage) | {
    in: .[0].input_tokens, cw: .[0].cache_creation_input_tokens,
    cr: .[0].cache_read_input_tokens, out: (map(.output_tokens) | max)}] |
  {calls: length, input: (map(.in)|add), cache_write: (map(.cw)|add),
   cache_read: (map(.cr)|add), output: (map(.out)|add)}' \
  <(jq -c 'select(.message.usage != null and .message.id != null)' SESSION.jsonl)

Verdicts on the review-skill diagnosis

The peeked diagnosis plan's claims, checked against the transcripts.

Also refuted: "cache hits don't count against your limit" holds only for API ITPM, not plan windows; a fresh session need not start cold (cache keys); misses never bill as base-rate input_tokens.

Runbook: measure the plan-window weighting

Does the Team-plan 5-hour window drain per raw or per price-weighted token? Each cell isolates one variable in a fresh 5-hour window: read /usage before and after, compute drain per token from the transcript, deduped as in Mining.

1. Cell 0: control

   Fresh window, zero activity, same wall clock as cell 1. Bounds /usage display drift.

2. Cell 1: cache-read-heavy

   Build ~150k context (paste a large file), then loop ~30 one-liners ("say ok"): each re-reads ~150k with minimal write and output, ~5M cache_read in total. The /usage delta gives drain per cache_read token. Transcript:

   ls -t ~/.claude/projects/<project-dir>/*.jsonl | head -1

3. Cell 2: fresh-input-heavy

   Fresh window, same volume as truly uncached input: unique content per turn so no prefix matches, or prompts under the 512-token floor. Wall clock and output matched; decision rule pre-registered below.

4. Cell 3: write-heavy

   Force misses: toggle a hook (system-prompt change) several times in a large-context session, each a 2×-rate rebuild. Compare drain per write token with cell 1's per read token; pricing predicts ~20×.

5. Cell 4: output-heavy

   Small stable prompt, long generations. Drain per output token; pricing predicts ~5× the input rate.

6. Cell 5: TTL checks

   Subagent TTL: fan out Task subagents without subagentPromptCacheTtl, check each subagent transcript's ephemeral_5m vs ephemeral_1h split (docs predict 5m); repeat with subagentPromptCacheTtl: "1h", confirm the flip. Main-session TTL: idle 50 min → full cache_read (1h intact); idle 70 min → full-context cache_creation rebuild.

   jq -s '[.[] | select(.message.usage.cache_creation) | .message.usage.cache_creation] |
     {m5: (map(.ephemeral_5m_input_tokens)|add), h1: (map(.ephemeral_1h_input_tokens)|add)}' \
     <(jq -c 'select(.message.usage != null)' SESSION.jsonl)

Practical consequences

• Context size costs on every call. Levers: short-lived conversations (file handoff, not chat plumbing), capped context growth, fewer calls.
• Avoid miss triggers in big-context sessions (hook, settings or tool changes, compaction): each is a ~20×-rate rebuild consuming full ITPM.
• Never compare raw token counts across categories ("output <1% of reads"); weight by pricing multipliers first.
• Subagent-heavy runs on a subscription: consider subagentPromptCacheTtl; subagents default to a 5m TTL and can miss on slow fan-outs.
• Transcript mining: dedup by message.id, per-id max for output_tokens, ignore iterations.