[FEATURE] Release a prompt cache early and get back the unused part of the 1-hour TTL premium

Summary

Let a client tell the API "this cached prefix will not be read again" and evict it right away. In return, refund the part of the 1-hour TTL write premium that covers the time the entry no longer has to be kept. Users pay less for cache they no longer need, and Anthropic frees accelerator memory or cache storage that would otherwise sit idle for up to an hour.

The problem

A 1-hour cache write costs 2× the base input price, against 1.25× for the 5-minute TTL. The extra 0.75× pays for keeping the entry alive longer. Every read restarts the timer, so after the last request of a conversation the entry is always kept for a full hour, and nothing will read it again.

Claude Code hits this constantly:

• Subagents. A subagent's transcript is almost never resumed once it returns its report. Its cache, written at 1-hour TTL, stays for an hour after the subagent has finished.
• /clear, /compact, exiting the session. The old conversation prefix is dead the moment the command runs, and Claude Code knows it.
• Finished agent tasks in the Agent SDK and in headless claude -p runs: the process exits and the cache outlives it by an hour.

In each case the client knows the cache is dead, the server does not, and the user has already paid for the hour.

Proposal

1. A release call. For example POST /v1/messages/cache/release taking the id of the last response, or a flag on the final request such as cache_control: {"type": "ephemeral", "release_after": true}. It evicts the cache entries this conversation wrote.
2. A prorated refund. Return the share of the 1-hour premium matching the unused remaining TTL, e.g. refund = (2× − 1.25×) × base input × tokens × remaining / 60 min. For subscription plans, credit it back to the usage limit instead of money.
3. Claude Code calls it automatically when a subagent returns, on /clear and /compact (for the discarded prefix), and on session exit. An env var could switch it off.

Example

A subagent on Claude Opus 5.5 ($4/MTok input) writes 300k tokens to the 1-hour cache during its run. The 1-hour premium over the 5-minute price is 0.75 × $4 × 0.3 = $0.90. If the subagent releases its cache right after its last request, nearly all of that $0.90 is for an hour nobody will use. With parallel subagents and several tasks a day, this adds up to a noticeable share of the cache bill. On subscription plans it shows up as usage limits running out sooner.

Why this is good for Anthropic too

• Cache capacity comes back as soon as the work is done, instead of after up to an hour. Agent workloads, which are the main users of the 1-hour TTL, are exactly where the client knows when a prefix dies.
• Today the cheap way out is the 5-minute TTL plus max_tokens: 0 keep-alive pings. A cheap release makes the 1-hour TTL safe to use by default, without the extra pings.

Open questions

• Shared prefixes. The system prompt and tool definitions are cached once and shared by many conversations in an org. Release should only drop entries no other request has read since they were written, and the refund should apply only to those. Otherwise one client could evict a cache that someone else is using.
• Abuse. The refund never goes above the premium actually paid for that entry, and only the remaining time is refunded. A write followed by a release then costs at least as much as a 5-minute write, so there is nothing to game.
• No refund at all would still help: an explicit eviction call without a refund frees capacity for Anthropic and could later be the basis for a cheaper "1-hour, releasable" TTL tier.

Related

• Existing issues on cache TTL choice in Claude Code (5-minute vs 1-hour, subagents writing 1-hour cache) are about which TTL gets requested. This proposal is about what happens after the last request, so it applies whichever TTL is chosen.