[FEATURE] Surface the cache-read to output ratio, the number that actually predicts token burn

Environment

• CLI 2.1.247, macOS darwin-arm64, Max 20x, main loop Opus 5

The gap

The stats panel reports raw counters, including cache-read. What it does not give is the one derived number that tells a user whether their session is healthy: cache-read divided by output. There is no per-session value, nothing live while a session runs, no documented healthy range, and no attribution of the ratio to the behavior producing it.

That derived number matters because the raw counter alone reads as normal. Cache-read is always large. Without a denominator there is no way to tell a session doing heavy productive work from a session re-sending the same conversation on every tool call.

What it looks like when you compute it yourself

45 days on one machine, summed from the usage records in the transcripts:

                files    turns   cache-read     output    ratio
MAIN SESSIONS     226   50,886     8,929.2M      62.0M    143:1
SUBAGENTS       1,444   43,653     3,606.8M      30.0M    120:1
COMBINED        1,670   94,539    12,536.0M      92.0M    136:1

12.5 billion tokens of re-read against 92 million of output. 99.3% of all tokens moved in that window were re-reads of conversation already sent.

An earlier week on the same machine measured 19,034 requests carrying an average of 211,302 tokens each, and 93% of that week's usage was re-reading history. Clearing sessions did not change it, because the refill rate is the problem rather than the size of any one window. Without the ratio there is no way to learn that from the product. The user's instinct is to clear, and clearing is the thing that does not work.

I am aware cache reads bill at a discount. That is not the point. The volume still moves against rate limits, still sets wall-clock latency, and it is the dominant term by two orders of magnitude. A user optimizing anything else is optimizing noise.

Why this is the highest-leverage instrument

Every other cost problem shows up in this number first. One large read early in a session is re-sent on every subsequent tool call, so the cost of a mistake is paid repeatedly and silently. The ratio is what makes that visible while there is still time to change course, rather than at the end of a billing period.

Ask

1. Show cache-read : output for the current session in /context, live.
2. Show it per session and per agent in the stats panel, alongside the existing raw counters.
3. Document a healthy range. From this data set, under 60 is healthy and over 150 means bulk is landing in the conversation window rather than being delegated.
4. Ideally, attribute the ratio to what drove it, so "one 40k read at turn 3" is visible as the cause rather than just the total.

Existing workaround

A local script that walks ~/.claude/projects/**/*.jsonl, sums cache_read_input_tokens against output_tokens, and prints the ratio with a red/yellow/green verdict, plus a SessionStart hook that puts the current value in front of the model at the top of every session. Roughly 80 lines. Every number in this report came out of it. It should not need to exist.