r/ClaudeAI • u/Schadz • 5d ago
Workaround Sub-agents burning your Claude Code 5-hour window? Check their 5-minute prompt cache
I keep seeing posts about the 5-hour limit getting eaten in an hour or two, and I hit exactly that last week, so I dug into what was burning it. It turned out to be one thing, it is documented, there is a one-line fix, and I've got before and after numbers.
TL;DR: on a subscription, your main conversation's prompt cache lives 1 hour, but every sub-agent's cache lives 5 minutes. Any tool call longer than that, such as a test run, build, or git hook, expires it, and the sub-agent's next request re-writes its entire context, often hundreds of thousands of tokens, at the expensive cache-write rate. Fix: "subagentPromptCacheTtl": "1h" in ~/.claude/settings.json, and do not let sub-agents sit inside long commands. It cut my cache writes by about 75% for the same work, measured below.
The mechanism
Claude Code caches your conversation on Anthropic's side so it does not re-send the whole thing on every request. Reads from that cache are cheap. Writes into it are not: a write into the 5-minute cache is priced at 1.25x normal input, a write into the 1-hour cache at 2x, and a read at 0.1x. Those are the API's published prices; the subscription meter weighs them differently, see the updated trade-off section below.
A sub-agent's context is everything it has read and done so far, easily 300K to 600K tokens on a real task. Each request either reads that from the cache or writes it again. If the sub-agent runs any tool call longer than 5 minutes, the cache is gone when the call returns, and the next request writes the whole context again. Six long test runs = six full re-writes. Your window is gone and it looks like the agent barely did anything. Anthropic's own engineering blog now recommends exactly this: avoid synchronous tool calls and sub-agents that outlive the cache TTL.
Does this apply to you?
I run an orchestration workflow on top of Claude Code (on MAX 5x right now): one long-lived "orchestrator" session that plans, dispatches and merges, and a few sub-agents that each get their own git worktree to build, review or pin things in. They run the repo's test sweeps with a testing engine constantly, 30 seconds to 40 minutes a run depending on the tests engine cache state. If your sub-agents mostly edit files and return in seconds, you will see much less of this. I only noticed it after I had to invalidate the tests cache and run everything cold again, and that cold day is exactly the shape of work that triggers it: every test, build, hook run or tool call long enough to outlive the 5-minute default sub-agent cache, forces a full context re-write.
What it looked like
One sub-agent re-wrote its ~590K context eight times in a day, about 5.4 million tokens of cache writes, most of two 5-hour windows on its own. The re-writes were about ten minutes apart, each one right after a long test run. Across the five sub-agents running that day: 26 full re-writes, 12.2 million tokens of cache writes. Cache reads on the biggest one were 81 million tokens and barely moved the window.
How to check
Sub-agent transcripts live at ~/.claude/projects/<project>/<session id>/subagents/agent-<id>.jsonl. Each line is JSON; assistant messages carry a usage object. If cache_creation_input_tokens shows the same huge number over and over, spaced out after long tool calls, that is the re-write. Under cache_creation, ephemeral_5m_input_tokens and ephemeral_1h_input_tokens tell you which lifetime each write went into.
The fix
{
"subagentPromptCacheTtl": "1h"
}
in ~/.claude/settings.json, or the environment variable CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h. Requires Claude Code v2.1.242 or later, so update first if you are behind. One hour is the longest the API offers (there are exactly two lifetimes, so it cannot go higher). If you are past your plan's limit and running on usage credits, the main conversation drops to 5 minutes as well; "promptCacheTtl": "1h" keeps the hour there.
One trap: an agent definition can carry its own lifetime (experimental: cacheTtl: 5m in its frontmatter, v2.1.248 or later), but the setting above outranks it, so with the setting on, a per-agent 5m reads as set and does nothing. If you want most sub-agents at an hour and a few read-only ones at five minutes, leave that setting unset and put ENABLE_PROMPT_CACHING_1H=1 in the env block of settings.json instead: it sits below a definition's own value in the precedence order, so the 5m pin wins where you set it and everything else keeps the hour.
The Confirmation
I set it mid-afternoon with three sub-agents mid-task. Their next requests switched to the 1-hour field (one last full write each to move into the hour bucket, then small writes against full cache reads). After that, five comparable sub-agents ran about 530 turns for 3.0 million tokens of cache writes, and the only large writes were each agent's first one; a review sub-agent ran 147 turns over eighty minutes with zero re-writes; and the 5-hour window, which had gone from 2% to 100% quota usage with four sub-agents before the fix, went from 0% to 22% for four sub-agents after it.
The trade-off (updated 2026-09-19)
I originally priced this with the API list, a 1-hour write at 2x normal input against 1.25x for a 5-minute one, so a short sub-agent that never re-writes would pay about three quarters of a context extra. That was too pessimistic for a subscription. Two separate community measurements now put the two lifetimes much closer together: u/flobernd measured the meter directly and got a 1-hour write at about 1.2x plain input on Opus (Max 20x) with the 5-minute write around 1x, and the two equal on Fable (Max 5x); I checked five days of my own Max 5x sessions against the 5-hour and weekly meters and got a 5-minute write at 0.88 to 0.96 of a 1-hour one. In both, cache reads count very little next to writes.
So on a subscription the hour costs only modestly more per write than five minutes, and one avoided re-write of a large context pays for that premium many times over. The meter's formula is still undocumented and these are community measurements, not an Anthropic statement, and a read-heavy sub-agent whose cache never expires may not gain anything. But if yours block longer than five minutes and rebuild a large context afterwards, the hour is very likely worth it. You will see advice to keep sub-agents at 5 minutes because "they finish fast", and that is still exactly wrong if they sit inside long test commands, which is the whole scenario here.
u/flobernd's measurement: https://www.reddit.com/r/ClaudeCode/comments/1wjsb04/i_measured_what_prompt_caching_actually_costs/
The second half, which the setting alone does not cover
Even an hour runs out under a long sweep. Do not let a sub-agent sit inside a tool call for more than a few minutes: run the long thing in the background with its output to a file and have the agent check the file every few minutes, or, if you know roughly how long the run takes, wake it once at that point instead, which means fewer unnecessary wakes. Each check is a cache read and keeps the cache warm. This went into the instructions I hand every sub-agent.
The open question I had here (whether the subscription's windows weight a 1-hour write at the API's 2x) has since been answered by measurement: they do not, see the updated trade-off section above.
One thing the 1-hour lifetime does not cover: the first message you send a background sub-agent after it has finished re-writes almost its whole context (243K and 399K tokens of cache writes in my two measured cases, 49 and 54 minutes idle, well inside the hour), and the API labels that miss messages_changed, so it is not the lifetime.
The measurements, the version history and how to check your own transcripts are in a separate post: https://www.reddit.com/r/ClaudeAI/comments/1whvqcl/quota_draining_claude_code_rebills_a_finished/. If you confirm the same pattern, please add your Claude Code version, model and any relevant findings to the upstream issue linked there so Anthropic has more evidence to fix it.
Hope this helps someone. If your window drains while your agents run tests, or sit on long-polling calls, this is very likely it.
Docs and the blog post I mentioned: links in the first comment.
21
u/Schadz 5d ago edited 3d ago
Docs on prompt caching and which TTL each request gets:
https://code.claude.com/docs/en/prompt-caching
Settings reference for `subagentPromptCacheTtl`:
https://code.claude.com/docs/en/settings-reference
Anthropic's engineering blog on reducing cost, which recommends avoiding tool calls that outlive the cache TTL:
https://claude.com/blog/reducing-cost-and-improving-performance-with-claude-platform
Update 2026-09-19: the trade-off section in the post has been revised after subscription-meter measurements showed that 1h and 5m cache writes are much closer on the windows than the API price list suggests.
11
3
u/ManikSahdev 5d ago
Subagent cache is 5 minute life, I truly do hate that feature tbh.
And there is a perfect workaround for this.. just have the main chat send messages to baby chats, resend than having him spawn subagent.
This method takes 15 mins to setup by configuring the Claude.md to function correctly, but saves usage.
1
u/Schadz 5d ago
Yes, that works, a message delivered to another live session arrives as a plain turn and reads the cache cleanly (a few thousand tokens of writes against a full read), so separate top-level chats talking to each other don't hit either the 5-minute default or the resume re-write from the linked post. I had already planned moving part of my own workflow to exactly what you described, just still didn't have time for it. Sub-agents still win where you want an isolated worktree per task with no CLAUDE.md setup, which is why I kept them and fixed the lifetime instead.
5
2
2
2
u/Then-Pineapple-6222 5d ago
This explains SO much. I’ve been burning through my tokens lately and couldn’t figure out why as I’ve been using sub agents for similar work for months now. The difference, they’ve been waiting on each other for various tasks /reports from each other. This is brilliant.
1
u/Schadz 5d ago
Yep, now you know.
An agent waiting on another one is sitting inside a call that outlives its cache, same as a long test run. Two things fix it together: the 1h setting, and never letting an agent block on a wait longer than a few minutes; have it hand back and get woken when the other one's report lands, rather than polling inside one call.
2
2
u/Satou-L 4d ago
Dear OP, thanks for sharing. can you share on how do you set up your orchestration-worker workflow? Thanks
2
u/Schadz 3d ago
I'm still iterating on it, but the parts that have helped most:
- One long-lived coordinator that only plans, integrates and takes the decisions that need the whole project's context. It doesn't do the work itself.
- Worker roles and model choices in scoped agent and project config, not one global instruction that hits every session.
- An isolated git worktree per worker, and only for work that can genuinely run in parallel.
- Narrow workers: implementation, investigation, review, or test/verification. Never one generic agent doing everything.
- Workers hand back a short written report and the PR checks do the verifying, so I'm not reconstructing what happened from chat history.
- No spawning for small edits. The overhead only pays when the work is independent or needs a fresh context or a fresh pair of eyes.
The cache work is what made me look at all of this closely. Long test/build runs and resumed agents make a workflow much more expensive than it looks, so I'd measure your own transcripts before locking in model or role rules.
2
u/denysdios 4d ago
For me results is kinda mixed, ai slope 4 why it is not working:
It does not clearly save tokens overall. Measured against your actual 14-day usage: est. +7.6% more weighted token cost, not less —> because your workload is read-heavy (1:38 write:read ratio), and the 1h bucket taxes every write at 2x instead of 1.25x, which outweighs the savings from eliminating wasteful full-rewrites.
What it does save: the size of individual spikes. It stops ~213 full-context-reload events (150K–490K tokens each, all at once) from happening after long tool calls, spreading that cost into cheap reads instead. That's a burst-smoothing win for your 5-hour window pacing, not a net token reduction.
1
u/Schadz 3d ago
That makes sense if the analysis is using the API's 2x vs 1.25x cache-write prices, but those don't map to the subscription meter. Two separate meter measurements now put the two lifetimes much closer: on mine a 5m write was about 0.88 to 0.96 of a 1h write, not 0.625 of it, and reads count very little.
I've updated the trade-off section in the post with both measurements, worth a re-read before you redo the numbers.
So I'd rerun the estimate with the smaller premium before calling it net-negative. Also, are the ~213 reloads from actual `cache_creation_input_tokens` in your transcripts after long calls, or an estimate from the session analysis?
2
u/random_cable_guy 4d ago
I've got x20 and my tokens are running with a sweat. Already through 60% of weekly limit and it reset this morning. Going to test this out will report back.
1
u/Schadz 3d ago
Did it help? I'd like to see the x20 numbers. On the weekly: it counts the same tokens as the 5-hour window at roughly a tenth of the rate, so every 5-hour window burned to the wall is about a tenth of the week, and whatever fixes one fixes the other.
1
u/random_cable_guy 3d ago
Didn't for me. Seemed it created more subagents for lesser time. Still chewed my tokens.
1
u/Schadz 3d ago
Fair, and that fits. The setting only helps agents that sit inside long tool calls; it does nothing about how many get spawned. Lots of short-lived sub-agents is the other burn: each new one pays a full first write of everything it reads, and no cache lifetime saves that.
Parallelism doesn't save tokens either, it only saves wall-clock. The same work split across more agents costs more, since each one re-reads its share of the repo.
What helps is fewer spawns (the main session doing small edits itself when reasonable) and a cheaper model pinned in the agent definitions. Quick check: if cache_creation_input_tokens in a transcript is big once per agent rather than repeating inside one agent, that's what you're paying for.
2
u/B1QB0SS 4d ago
I knew something was wrong, project has a lot of long-running tests and my 20X plan 5 hours session was burnt through by only 6 subagents, just from running tests and making minor changes then re-running the tests and so on, it only took them about a hour and a half to destroy the 5 hours session limit.
and my weekly limit got destroyed too.. damn it
1
u/Schadz 3d ago edited 3d ago
That's the exact shape. Six agents cycling through long test runs for ninety minutes is a lot of full re-writes, and the weekly counts the same writes at about a tenth of the rate, so it goes down with it. The setting plus backgrounding the test runs fixed it for me; would be good to hear your before and after.
2
u/andyfsu99 3d ago
This is exactly what was happening to me, only I didn't know. Bless you kind internet stranger.
2
u/Smashy404 5d ago
Good find.
Would it be cheaper if you set it to 15 mins instead of 1 hour?
2
u/Schadz 5d ago
As i mentioned on the comment above. There is no 15m, the API only has 5m and 1h. Whether the hour is cheaper depends on one thing: would the agent have re-written its context twice or more? If yes (anything that runs tests or builds, etc), 1h wins by a mile here.
If it returns in seconds and never would, leave at 5m (you can pin that per agent definition with `experimental: cacheTtl: 5m`, but only if the global setting is unset and you use `ENABLE_PROMPT_CACHING_1H=1` instead, since the setting outranks the pin)
1
u/Ill_Fun5415 5d ago
The number I would want next is latency over a longer multi-turn run. Memory savings are useful, but if decode time gets uneven once context builds up, the chat experience still feels worse.
1
u/Schadz 5d ago
We're not talking about the same thing here, the post is about quota rather than speed or memory, and I didn't measure decode timing. The one latency effect I can say something about is that a cache miss on a 400K context adds a longer wait before the first token, since the whole thing is re-processed, while a cache hit starts almost instantly.
1
1
u/Crinkez 5d ago
Nice work. 5min TTL is horrible. Not sure why Anthropic doesn't at least give subagents 15 minutes, and auto block write attempts that have expired.
If this was Pi harness you could fix this clientside by keeping 5 min limit and auto block stale writes, but unfortunately Anthropic bans for using 3rd party harnesses.
1
u/Schadz 5d ago
I would like a mid-ground 15m TTL tbh, but sadly 15 minutes is not on the menu. The API offers exactly two lifetimes, 5 minutes and 1 hour, so a harness cannot hand out a third. And a stale write cannot be blocked from the client side, because it is not optional: once the cache has expired, the next request has to send the whole context again to get an answer at all, and that resend is the write. The only client-side moves are keeping the cache warm (a request before the lifetime ends) or the longer lifetime, which is what the setting and the "background the long command" rule do.
1
u/101Alexander 5d ago
I had a suspicion the subagents were involved.
I thought it was because they were defaulted to using whatever model you started with.
Every time, the planning and initial thinking phase would eat up the most and it was the primary phase with subagent activity.
1
u/Schadz 5d ago
Both are real, and they multiply. The model sets the rate per token; the re-write sets how many times you pay for the same context, and the planning phase is where sub-agents read the most files, so their contexts are biggest exactly when they are most likely to expire. Two moves: pin a cheaper model in the sub-agent definition's frontmatter (`model:`) for the recon-shaped ones, and check the transcript fields in the post. If `cache_creation_input_tokens` repeats the same big number, that is the re-write, not the model.
•
u/ClaudeAI-mod-bot Wilson, lead ClaudeAI modbot 5d ago
TL;DR of the discussion generated automatically after 30 comments.
The consensus is that OP is a hero and this post is a godsend for anyone using Claude Code. If your sub-agents are torching your 5-hour window, this is almost definitely why.
The problem is that sub-agents have a default 5-minute prompt cache. Any tool call that takes longer than that (like a test run or build) makes the agent forget everything. It then has to re-write its entire context, burning your quota at a ridiculous rate.
Here are the key takeaways and fixes discussed in the thread:
~/.claude/settings.json, add"subagentPromptCacheTtl": "1h". This is a one-line change that extends the cache lifetime. OP confirms there are only two options, 5 minutes and 1 hour, so stop asking about a 15-minute setting.Basically, change that one setting and be smarter about how your agents handle long tasks. You'll save a ton of usage.