Your Subagents Forget in Five Minutes: Prompt Cache TTL in Claude Code

I lean on Claude Code subagents a lot: one to sweep a codebase, one to fact-check a claim, one to babysit a slow build. While checking the facts for one of these posts, I learned that my subagents were not running on the same prompt cache rules as my main session. On my subscription, the main conversation gets a one-hour cache. Subagents get five minutes.

That difference matters as soon as a subagent stops talking to the model for a while. This post explains what the TTL is, when five minutes costs you, and how to ask for an hour.

What the prompt cache TTL is

Every request Claude Code sends starts with the same long prefix: tool definitions, system prompt, then the conversation so far. Anthropic's API can cache that prefix. The first request writes it to the cache, and later requests with an identical prefix read it instead of paying full price for those input tokens again.

The cache entry has a time to live. The API docs are explicit: by default the cache lives for five minutes, and it is refreshed at no extra cost every time it is used. A one-hour option exists, requested with "ttl": "1h" on cache_control.

The prices relative to the base input price are the part worth remembering:

• 5-minute cache write: 1.25×
• 1-hour cache write: 2×
• Cache read: 0.1× (lower on some newer models)

A read is cheap. A write is expensive. Every time the cache expires, the next request pays the write price again, for the whole prefix.

Two buckets, two defaults

Claude Code's prompt caching page splits requests into two buckets. The main conversation covers your interactive turns, -p runs and Agent SDK turns. Everything else covers subagents, workflows, teammates, forks, compaction and session titles.

I checked my own setup on Claude Code 2.1.296 with a subscription:

claude -p "hello" --output-format json
# ... "cache_creation":{"ephemeral_1h_input_tokens":36586,"ephemeral_5m_input_tokens":0}

The main conversation wrote its 36.5k-token prefix to the one-hour cache. The docs are just as clear about the other bucket: subagents "get five minutes even on a subscription until you choose a longer one". On an API key or a cloud provider, both buckets default to five minutes. On a subscription, the main conversation also drops to five minutes once you start drawing on usage credits.

The pause costs you, not the runtime

My first instinct was "a subagent that runs longer than five minutes costs more". That is not quite right, and the difference is the whole point. The TTL refreshes on every read, so a subagent that calls tools every few seconds keeps its cache warm for as long as it runs. A two-hour subagent with no long gaps never pays a rewrite.

The cost comes from a gap of more than five minutes between two of the subagent's own requests. When that happens, the cache entry has expired, and the next request writes the entire prefix again at 1.25×. Late in a run, that prefix includes everything the subagent has read so far.

The gaps I actually run into:

• A single tool call that takes a long time: a full test suite, a Docker build, a slow sbt compile.
• A subagent waiting for me to approve a permission prompt while I am in a meeting.
• A subagent I resume later with a follow-up message. The docs note that a resumed run can read the cache the original run warmed, but only if that cache is still alive.

When an hour pays off

The one-hour TTL is not free. It changes the price of every cache write the subagent makes, including the small incremental writes as the conversation grows, from 1.25× to 2×. So it is a trade:

• If a subagent writes W tokens to the cache over its run, one hour costs an extra 0.75 × W.
• A single expiry with a prefix of P tokens costs an extra 1.25 × P.

One hour wins when 1.25 × P > 0.75 × W, which means when the prefix at the pause is more than about 60% of everything the subagent writes. One long pause in the second half of a run usually crosses that line. A short, busy subagent with no pauses only pays the premium.

My rule: leave fast research and search subagents on five minutes. Give one hour to the subagents whose job involves waiting.

How to raise it

For every subagent, set it in settings.json:

{
  "subagentPromptCacheTtl": "1h"
}

For a single launch, use the environment variable, which takes precedence over the setting:

$env:CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL='1h'; claude

For just the agents that wait, use the experimental frontmatter field. This is the option I prefer, because it puts the premium only where the pauses are:

---
name: build-runner
description: Runs the slow test suite and reports failures
experimental:
  cacheTtl: 1h
---

A few details from the docs to keep in mind:

• The only accepted values are 5m and 1h.
• FORCE_PROMPT_CACHING_5M=1 overrides every one of these.
• The frontmatter 1h is ignored while a subscription is drawing on usage credits.
• Through an LLM gateway set with ANTHROPIC_BASE_URL, the gateway must forward the anthropic-beta header unchanged, or the one-hour request is lost.
• /cost prompt cache statistics cover the main conversation only, not subagents. To see what a subagent got, look at its usage, where ephemeral_1h_input_tokens and ephemeral_5m_input_tokens are reported separately.

Or skip the cold start

A fresh subagent never reads its parent's cache, because its system prompt and tools differ. Its first request is always a write. A fork inherits the parent's system prompt, tools and history exactly, so its first request reads the parent's cache. When a side task needs the context I already have, a fork is cheaper before the TTL even comes into play.

The short version: five minutes is fine for subagents that keep busy. For the ones that wait on builds, on resumes or on me, an hour is a one-line change, and now I know which line.