Claude's prompt cache dies quietly in agent loops: the 20-block lookback nobody configures

A run starts healthy, cache reads climbing, and then a dozen tool calls later the reads drop to zero while cache creation jumps to the full conversation length on every subsequent turn, with the prefix byte-identical and nothing reordered ^[3]. According to a dev.to post on Claude prompt caching, the cause is that cache lookup is bounded: a `cache_control` breakpoint searches backward through at most 20 content blocks to find an existing entry, and if the previously cached block sits further back than that, the request is treated as cold even though a valid entry exists ^[1].

Count what one agentic turn actually appends. The assistant message contributes one thinking block, one text block, and N `tool_use` blocks; the user message contributes N `tool_result` blocks ^[5]. Eight parallel tool calls therefore append 18 blocks in a single round trip, and after two such turns a lone trailing breakpoint is 36 blocks past the last cached point ^[6]. Eleven parallel calls emit 22 or more blocks and blow the window in one turn, after which the whole prefix is rewritten at the 1.25x write multiplier ^[2]. There is no error and no warning field, only `cache_read_input_tokens: 0` and a creation charge for the full history ^[4].

This is why chat products never report the problem. One user turn is one text block and one assistant turn is one text block, so it would take ten round trips to travel 20 blocks, and most implementations mark a breakpoint every turn anyway ^[7].

The money is the reason to care. The post prices Claude Opus 5 at $5/MTok input, a cache read at about $0.50/MTok, and a five-minute cache write at about $6.25/MTok ^[15]. That write price is exactly 1.25 times base input, consistent with the stated multiplier ^[20], and read against write it is a 12.5x per-turn swing ^[16] on a setting nobody chose.

The prescribed fix is not one marker on the last block but a rotating chain: a stride of roughly 15 blocks, with one of the four available breakpoints spent on the last system block and the other three rotated through the message list ^[9]. The budget is hard at four per request across tools, system, and messages ^[8]. Since every breakpoint is both a write point and a read point ^[10], three markers at a 15-block stride cover about the last 30 blocks of history and keep consecutive markers inside the 20-block window ^[19]. Placement has constraints: only `text`, `image`, `tool_use`, `tool_result`, and `document` blocks can carry `cache_control`, so thinking blocks must be skipped ^[17], and you cannot set the field on an SDK response object without round-tripping it through `model_dump()` first ^[18].

Two related items from the same post. Invalidation is tiered rather than all-or-nothing: `tool_choice` changes, images, and toggling thinking preserve the tools-plus-system cache, while only tool-definition changes and model switches force a full rebuild ^[12]. Because render order is tools, then system, then messages, a breakpoint on the last system block caches both together ^[11]. Editing the system prompt mid-run invalidates everything downstream unless you append a `{"role": "system"}` message to `messages[]` instead, which the post says works on Claude Opus 5, Opus 4.8, and Fable 5 but not Sonnet 5 ^[13].

Watch your metering before you watch anything else. `input_tokens` in the usage block is the uncached remainder only, and total prompt size is `input_tokens + cache_creation + cache_read`, so a dashboard graphing `input_tokens` alone will show a flat line while the cache-write line runs away ^[14].