Claude Prompt Caching: Why Age... Note

Claude Prompt Caching: Why Agent Loops Miss the 20-Block Lookback

Claude prompt caching is hindered by a 20-block lookback window for cache entries. Agentic turns with multiple tool calls can quickly exceed this limit, causing cache misses and expensive full prompt rewrites. To maintain caching, place rolling breakpoints every approximately 15 blocks, rather than a single marker at the end. You have a budget of four breakpoints per request, with one reserved for system and tools. Ensure stale breakpoints are cleared before each new request. Thinking blocks cannot serve as cache anchors, so choose cacheable content types instead. Cache invalidation is tiered, affecting only the changed tier and subsequent ones, except for tool definition changes and model switches which invalidate everything. Appending system messages to the message list, rather than editing the top-level system prompt, preserves the cache. Log all three usage fields—input_tokens, cache_creation_input_tokens, and cache_read_input_tokens—to accurately diagnose cache performance. When making parallel requests, initiate subsequent requests only after the first one begins streaming to leverage its cache write. Tool call latency exceeding five minutes can expire cache entries, necessitating a longer TTL. The minimum cacheable prefix length varies by model, so smaller prefixes might not cache at all.