In short: a prompt cache-break is when one change atop your prompt prefix — a fresh timestamp, a reordered tool block — makes the cache miss from there down, so cached reads silently re-bill as fresh input. cache_break.py hashes each prefix segment, localizes the break, and fails CI. On my fixture, one timestamp dropped the estimated cache-hit-rate 100% to 40%.
AI disclosure: I drafted this with an AI writing assistant. The tool, the two fixtures, and every number below come from a real local run on tiktoken o200k_base — I ran it, checked the exit codes, hashed the output twice to confirm it's deterministic, and edited every line before publishing.
Turning on prompt caching feels like a free win. It usually isn't the win you think.
Here's the trap. Anthropic and OpenAI both price a cache read at a fraction of a fresh input token — Anthropic quotes cached reads at roughly $0.30/M vs $3.00/M for fresh, about a 10x gap on the cached portion (Anthropic prompt caching docs). Flip the feature on, watch the dashboard, move on. But that discount is only paid for a prefix that is byte-for-byte identical to what's already cached. Change one character near the top and the cache misses from there down. You still have caching on. You're just not hitting it. And nothing in your config screams about it.
