[BUG] cache-diagnosis beta is requested on every call but the response is never read

[iceteaSA]

cache-diagnosis-2026-04-07 is in the beta list at packages/core/src/claude-code.ts:174, :185 and :197, so it goes out on every request — I confirmed it on the wire in 432/432 captured requests on my install.

Nothing reads the result. Grepping the source for cache_diagnosis, cacheDiagnosis, cache_miss_reason or cacheMissReason returns no hits outside tests, and the dump capture is request-only: each dump writes .body.json, .meta.json and .request.json, and meta.json carries status but no response payload or headers. So whatever the server reports about a cache miss is discarded before anything can see it.

That matters because it's the one channel that answers "why did this prefix miss" without inference. Concretely, from my install today:

ses_024c9cc48  23:24:38 -> 23:34:52   gap 10.2 min   read=372,687   hit
ses_024c9cc48  23:35:40 -> 23:42:38   gap  7.0 min   read=0  write=377,673   miss

Same session, same model (claude-opus-5), same account and route, ttl:"1h" on all four breakpoints in both requests, and the request bodies are byte-identical for the first 200,000 bytes (cmp puts the first difference at byte 967,183, which is the new turn). The shorter gap missed and the longer one hit. I eliminated TTL expiry, prefix drift, breakpoint movement, model switch and account migration from local artifacts, and I still can't tell you why it missed — because the answer was in a response we asked for and threw away.

Suggested direction: read the diagnostic on the response path and log it at debug, alongside the actual cache_read_input_tokens / cache_creation_input_tokens. There's already a response-header read in that path — normalizeQuotaHeaders at packages/opencode/src/index.ts:1158 harvests anthropic-ratelimit-unified-* — so the plumbing to observe a response exists and this is a small addition rather than a new seam. Capturing a response artifact in the dumps when dumping is enabled would make the same information available after the fact.

Is the beta deliberate and the consumption just not built yet, or is it vestigial? Happy to send a PR once you say which, since the shape depends on whether you want it logged, dumped, or surfaced in the sidebar.

[iceteaSA]

More data on why this matters, from a full day on one install.

I pulled every large-context turn from opencode.db and classified the full busts (tokens.cache.read == 0 with write > 50k) by the gap since the previous assistant turn in the same session:

27 full busts / 4,621 large-context turns

 3   gap > 1h (68.8 / 117.7 / 179.7 min)  legitimate expiry
 5   first turn in session                 expected cold
 1   model change
18   gap < 1h, same model                  unexplained

Some of those unexplained gaps are 0.2, 0.5, 1.3 and 3.0 minutes. Nothing expires in twelve seconds, and 3.0 minutes is inside even the default 5-minute TTL, let alone the ttl:"1h" that was on the wire for all of them.

Two of the busts cluster into groups hitting many distinct sessions within a few minutes of each other — nine sessions inside 4.5 minutes in one case. For that first cluster there's a plausible cause: a change to an always-injected prompt file at the cluster's midpoint, which is a genuine prefix change. For the second I compared the last request before and the first request after, same session and same model, and the bodies are byte-identical for the first 200,000 bytes with identical breakpoint placement — so no prefix change, 7-minute gap, and still a full re-cache.

A collaborator running the same analysis across a wider fleet finds bust rate forms a gradient by idle time rather than a cliff — roughly 0.2% under 5 min, 6.7% at 5–10, 13.5% at 10–20, plateauing near 14% beyond 20 — plus cache hits after multi-hour idles. A TTL produces a cliff; a gradient that rises with idle and plateaus well below 100% looks like eviction pressure rather than expiry.

I tried to explain that away as an artifact of the keepalive covering some sessions and not others, and it doesn't hold: every one of the 12 sessions that busted today was an active CacheKeep target, per the lease records under cachekeep-sessions. No bust landed on an uncovered session.

That leaves a real question about CACHE_KEEP_TTL_MS = 60 * 60_000 with CACHE_KEEP_PREWARM_LEAD_MS = 5 * 60_000 — a target is re-warmed about 55 minutes after its last write, which is right if residency is an hour, but today's busts are at 3 to 11 minutes of idle on covered sessions. If actual residency is much shorter than the nominal TTL, the keepalive can't reach these regardless of coverage.

I can't close any of this locally, which is the point of this issue: the miss reason is in a response we request and discard. Suggested acceptance criteria for a fix:

1. capture shipped — server miss reason plus actual cache_read_input_tokens / cache_creation_input_tokens on the response path
2. miss reasons correlated across both cluster types and the idle-gradient set
3. the evicted-vs-expired split reported — if the field distinguishes them, one field settles the mechanism
4. residency measured directly: time from cache write to first observed miss on a covered session, which is the number the keepalive cadence should key off and is currently unmeasurable

Related, same blind spot: prewarm requests aren't dumped either. The smallest body among 444 captured requests is 757 KB at max_tokens: 32000 — all real traffic — so the keepalive's own requests bypass the dump path. The mechanism responsible for maintaining residency is invisible in the artifacts used to reason about residency. Mentioning it here rather than opening another issue since it's the same defect.

Happy to do the work if you're open to the direction. Worth saying plainly: if the reason comes back "expired" on a 3-minute gap with ttl:"1h" on the wire, that's an upstream contradiction worth taking to Anthropic with the captures attached, not a plugin bug.

[iceteaSA]

Retracting the central claim in my original post. I said the server reports why a cache missed and we discard it. That's wrong — I checked it against the live API and the beta returns nothing.

What I ran: replayed a real captured request shape (real headers including the real beta list, real four-block system, ~24.8K cacheable tokens) against api.anthropic.com, on Haiku, with the prefix pinned so nothing drifted between calls.

1. warm the prefix                       read=24,829  write=0       diagnostics: absent
2. same prefix (validity check)          read=24,829  write=0       diagnostics: absent
3. changed prefix -> forced miss         read=0       write=24,842  diagnostics: absent
4. back to same prefix                   read=24,829  write=0       diagnostics: absent

Step 3 forces a miss against a confirmed-warm entry by changing one system block, and step 4 shows the original entry was still resident — so step 3 is a pure prefix-change miss, not an eviction. That's the most diagnosable event this beta could exist for, and the response carried nothing. cache-diagnosis-2026-04-07 was in the sent beta header on all four calls. Streaming is the same: message_start.message has keys content, id, model, role, stop_details, stop_reason, stop_sequence, type, usage and no diagnostics. Nothing in the response headers either.

So the accurate version of this issue is narrower: we send a beta on every request that appears to return nothing. My "the answer is right there and we throw it away" framing was wrong, and I'd rather correct it than let it sit — anyone reading this issue would otherwise go looking for a field that isn't there.

Two questions, and the second is really the point of this comment:

Have you ever seen this beta return anything? You added it, so you may know something I don't — an account tier, an entitlement, a request shape that lights it up. I tested one OAuth account on Haiku. If it's inert everywhere, dropping it from the beta list is a one-line change. I'd rather ask than rip it out.

Would you take a PR capturing the usage block instead? That part turns out to be more useful than I realised. The response carries:

"cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 24829 }

That's the server stating which TTL bucket it actually wrote. It doesn't explain a miss, but it does let you verify that a block sent with ttl:"1h" was genuinely banked as 1h rather than silently downgraded — which is the thing I originally wanted the diagnostic for. Right now that's discarded along with cache_read_input_tokens / cache_creation_input_tokens, and the dumps are request-only, so none of it is recoverable after the fact.

Scope I'd propose, if you're open to it: read those numbers on the response path (the same seam that already harvests anthropic-ratelimit-unified-* headers), log one machine-readable line per request, and write a response artifact when dumping is enabled. Explicitly not included — no cadence changes, no reacting to the data, nothing in the sidebar. Measure first.

The diff-baseline gap in #158 stands unchanged; that one didn't depend on this premise.

[iceteaSA]

Correcting my previous comment — I was wrong, and the original issue was closer to right than my retraction was.

The beta isn't inert. My probe was invalid. Cache diagnostics requires an opt-in field in the request body, not just the beta header:

"diagnostics": { "previous_message_id": "<id of the previous response>" }

The doc's response-format table spells out exactly what I saw:

field absent — The request did not include diagnostics, or the beta header was missing.

I sent the header with no body field, so an absent diagnostics was the documented correct response to what I actually sent. I tested the feature without enabling it and concluded it was dead.

So the accurate version of this issue is the third framing, not the first two:

• "the server states why on every miss and we discard it" — wrong, nothing is being discarded
• "the beta returns nothing on this account" — wrong, mine, from an invalid probe
• the plugin sends cache-diagnosis-2026-04-07 on every request but never sends the diagnostics opt-in, so a documented diagnostic channel stays dormant

The fix is smaller than I thought, because the identifier is already there. opencode's assistant message ids are Anthropic message ids (msg_01bfaf8400013qVDGihR0u27Up), so previous_message_id is just the previous assistant message id for the session — no new tracking state, no id mapping.

What the response gives back, per the doc: cache_miss_reason.type as one of model_changed, system_changed, tools_changed, messages_changed, previous_message_not_found, unavailable, plus cache_missed_input_tokens on the four *_changed types. On streaming it arrives on message_start, which is all of this plugin's traffic.

Two things worth knowing before anyone builds on it:

unavailable explicitly covers the case where a prompt-affecting parameter differs, and the doc lists the set of active anthropic-beta headers among those parameters. This plugin varies its beta list by request type — structured-output requests drop several — so some unavailable responses are expected and shouldn't be read as failures.

Fingerprints for previous_message_id lookup expire after a short period and are scoped to one organization and workspace, so long-idle turns may come back previous_message_not_found rather than a reason. That's the case I most wanted this for, so it may not answer it. Still worth having for the short-gap cases.

Revised scope I'd propose:

1. send diagnostics.previous_message_id on eligible requests, threading the previous assistant message id
2. read diagnostics off message_start and log one machine-readable line, keeping the four states distinct — absent, null, {cache_miss_reason: null} (comparison still running), and populated all mean different things
3. capture the usage block alongside it, including cache_creation.{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens} — the server stating which TTL bucket it actually wrote, which independently verifies that a ttl:"1h" block was banked as 1h
4. write a response artifact when dumping is enabled, and dump prewarm requests too, tagged distinctly so they're distinguishable from real traffic

Still measure-only — no cadence changes, nothing acting on the data.

Two questions before I send a PR. Is the missing opt-in deliberate, or was the beta added expecting the header alone to be sufficient? And would you want the opt-in behind the existing /claude-dump flag or always-on given it's a documented no-op when the fingerprint is missing?

Apologies for the churn on this issue — three framings in one day is two too many. The diff-baseline gap in #158 is unaffected.

[iceteaSA]

One correction to my last comment, on the implementation cost rather than the premise.

I said previous_message_id was already to hand because opencode's assistant message ids are Anthropic message ids. That's wrong. opencode generates its own ids in the same shape:

anthropic            msg_01abbbe0c001FucQbaNDKf5RCF
deepseek             msg_01b33ae4d001mgjaPU6Ah7zi1h
openai               msg_01aa10ffa001S0CKrXLEpH4O7K
minimax-coding-plan  msg_01bfab1b4001282Gi0V304w8VE

Anthropic doesn't issue ids for DeepSeek responses, so these are opencode's own. They also sort chronologically, which Anthropic's don't. And the provider's response id isn't persisted anywhere on the message — the stored payload contains exactly one msg_-shaped string, its own id.

The trap worth flagging: a real Anthropic id is msg_011CeCtgiNcx3zCPy3nY5mQh. Same msg_01 prefix. The two are not distinguishable by eye, which is how I talked myself into it. The structural difference is that opencode's carry a literal 001 at a fixed offset and sort chronologically; Anthropic's are random.

This matters more than a normal mistake would, because sending the wrong id fails as previous_message_not_found — which the doc lists as an expected, benign outcome for an expired fingerprint. A broken implementation would look like the feature working and returning null results. Worth a guard.

So the revised scope, unchanged in intent but honest about cost:

1. capture message_start.message.id from the response and hold it per session (in-memory, one id per session — this is new state, small, and can't be sourced from opencode)
2. send it as diagnostics.previous_message_id on the next request for that session
3. read diagnostics off message_start, keeping the four states distinct
4. capture the usage block including cache_creation.{ephemeral_5m_input_tokens, ephemeral_1h_input_tokens}
5. response artifact when dumping is enabled; prewarms dumped and tagged

Worth adding as a self-check: previous_message_not_found on a short-gap turn means the id capture broke, not that a fingerprint expired. That distinguishes a broken implementation from a legitimate negative, and it's free.

Everything else from the previous comment stands — the opt-in is required, the plugin doesn't send it, and the unavailable/beta-header-set and fingerprint-expiry caveats are unchanged.