Claude's 20-block cache lookback silently kills agent loops —

Your agent run starts clean: cache_read_input_tokens at 40K and climbing. Twelve tool calls later, reads drop to zero and cache_creation_input_tokens spikes to the full conversation length — every single turn. Prompt didn't change. No timestamp, no reordered tools, no model switch. The prefix is byte-identical.

You just hit the 20-block lookback ceiling. It's the single most expensive gotcha in Claude prompt caching that nobody puts in their retro.

Why the lookup fails mid-loop

Cache lookup is bounded. A cache_control breakpoint walks backward at most 20 content blocks hunting for an existing entry. One agentic turn with 8 parallel tool calls emits:

• Assistant: 1 thinking + 1 text + 8 tool_use = 10 blocks
• User: 8 tool_result = 8 blocks
• Total: 18 blocks in one round trip

Two turns and your single trailing breakpoint sits 36 blocks past the last cached point. Silent miss — no error, no warning field, just cache_read_input_tokens: 0 and a full-prefix cache-write charge at 1.25× the read price. On Opus 5 ($5/MTok input) that's ~$0.50/MTok read vs ~$6.25/MTok write. A 12× swing per turn triggered by a config detail you never set.

Chat apps never see this — one user turn = one block, one assistant turn = one block. You'd need ten round trips to move 20 blocks. Agent loops are a different beast entirely.

Tiered invalidation — what actually busts the cache

| Trigger | Cache impact |
|---------|--------------|
| tool_choice change, images added/removed, thinking toggle | Preserves tools+system cache |
| Tool definitions change, model switch | Full rebuild |
| System prompt replaced mid-run | Nukes everything downstream |

Workaround for system-prompt edits (Opus 5, Opus 4.8, Fable 5 only): append {"role": "system", ...} to messages[] instead of replacing the top-level system field. Sonnet 5 doesn't support this.

Rolling breakpoints — the pattern that holds

Stop putting one marker on the last block. Rotate a small set through the message list at a stride shorter than the lookback window. Every breakpoint is both a write point and a read point, so a trailing chain means each new request always finds a prior entry within 20 blocks.

Budget: 4 breakpoints per request total (tools + system + messages). Spend one on the last system block — it caches tools and system together since render order is tools → system → messages. Rotate the remaining three.

CACHEABLE = {"text", "image", "tool_use", "tool_result", "document"}
STRIDE = 15  # blocks apart, safely under the 20-block lookback

def add_rolling_breakpoints(messages: list[dict], stride: int = STRIDE) -> None:
    """Mutates plain-dict messages in place. Round-trip SDK objects with .model_dump() first — you cannot set cache_control on a response object."""
    flat = []
    for msg in messages:
        for block in msg.get("content", []):
            if block.get("type") in CACHEABLE:
                flat.append((msg, block))

    # clear existing
    for _, block in flat:
        block.pop("cache_control", None)

    # place markers every STRIDE blocks from the end
    for i, (_, block) in enumerate(reversed(flat)):
        if i % stride == 0:
            block["cache_control"] = {"type": "ephemeral"}

# usage each turn:
add_rolling_breakpoints(messages)
response = client.messages.create(model="claude-opus-4-20250514", messages=messages, ...)

The system+tools breakpoint stays fixed. The three message breakpoints leapfrog: newest turn gets one, the two prior turns keep theirs. Next turn, the oldest drops off, the new one lands — always three live markers spaced ≤15 blocks apart. Lookup never misses.

Dashboard trap

input_tokens in the usage block is uncached remainder only. Total prompt size = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Grafana panels graphing input_tokens alone show a flat line while you burn cache writes at 12× the read cost. Add the other two series or you're flying blind.

---

Bottom line: the 20-block limit isn't documented in the quickstart. If you run multi-tool agent loops on Claude, rolling breakpoints every ~15 blocks is the difference between a $0.50/MTok read path and a $6.25/MTok rewrite every turn. Ship the snippet, watch cache_read stay non-zero, and stop lighting money on fire.