A cache breakpoint missed because of the 20-block lookback limit

The symptom

A cache breakpoint that worked reliably for months starts missing on a specific kind of turn — usually a long agentic step that produces an unusually large number of tool calls and results in one go — while every other turn in the same conversation keeps caching normally. There's no error, just a cache read that should have hit and didn't.

What a breakpoint is actually searching for

A cache breakpoint doesn't scan the entire prior conversation to find a matching prior entry — it looks back a fixed distance in content blocks from where it's placed. That's an efficient design for the overwhelming majority of turns, where the content added in a single turn is modest. It becomes a problem specifically when one turn adds more distinct content blocks than that lookback distance covers — the breakpoint simply never reaches far enough back to find the entry it should have matched, and the request proceeds as an ordinary cache miss with no indication of why.

Why agentic turns are the ones that trip this

A single agentic step that fires several tool calls and receives several results back can add far more content blocks in one turn than a normal conversational exchange does, and it's exactly that kind of turn — long, tool-heavy, high block count — that's most likely to push a breakpoint past its lookback range. A conversation that's been caching cleanly through ordinary back-and-forth can hit this the first time it runs a genuinely large tool-use step.

The fix

Where a single turn is likely to add an unusually large number of content blocks, place a cache breakpoint after that turn rather than relying on one set earlier in the conversation to still be within reach — moving the breakpoint closer to the content it needs to cover is the direct fix, since the lookback distance itself isn't something a request can extend. See why your prompt caches on one model and not another for the related set of caching gotchas worth checking alongside this one.