Claude Code puts cache metrics in /cost: your bill is misses

If you run coding agents, your invoice is not mostly a function of how much you asked for. It is a function of how often the model had to re-read context it already had. Claude Code 2.1.251, shipped August 28, finally puts that number where you can see it: /cost now reports per-session prompt-cache hit ratio, misses, tokens re-cached, and warm/cold state. This is a small changelog line with a real budget consequence.

What actually happened

Per the Claude Code changelog, version 2.1.251 "Added a per-session prompt-cache line to /cost (hit ratio, misses, tokens re-cached, warm/cold) and a matching prompt_cache object for status line scripts." The same release added a spend limit bar to /usage and a rate_limits.spend_limit status line field for developers behind a Claude apps gateway with spend limits.

The release before it is the more instructive one. Version 2.1.248, from August 27, "Fixed a prompt-cache miss (and lost extended-thinking context) roughly once an hour in long sessions, caused by tool definitions being re-rendered after an OAuth token refresh." Read that plainly: a token refresh in the auth layer was silently invalidating the cache and forcing a full re-read of every long session's context, once an hour, for anyone who never noticed. That release also added experimental.cacheTtl ("5m" or "1h") to agent frontmatter, so a per-agent cache TTL can be set where no subagent TTL is configured.

Two releases, one theme. The cache was a black box, it was leaking, and now there is a gauge on it.

Why cache misses matter for your business

Cached input tokens cost a fraction of fresh ones. That is the entire economics of running an agent against a large codebase or a long-lived session: the first read is expensive and every subsequent turn should be cheap. When something invalidates the cache — a tool definition changing, a session resuming cold, an auth refresh — you pay the expensive read again, and nothing in the UI told you it happened. An hourly re-cache across a team of five developers in long sessions is not a rounding error.

What to do with the new number, in order:

Look at it once, honestly. Run /cost at the end of a real working session. If your hit ratio is poor, the fix is structural — stable tool definitions, fewer mid-session config changes, longer sessions rather than many cold starts — not prompt golf.

Put it in the status line. The prompt_cache object means the metric can sit in front of your developers all day instead of being something they query after the fact. Costs you notice are costs you manage.

Upgrade before you argue about spend. If you are on anything older than 2.1.248, some of your bill is the OAuth refresh bug, and no amount of policy will fix that.

This is what good tooling looks like: a vendor exposing the meter that makes its own product look expensive. Take the number and use it.

Sources: Claude Code changelog.