If you run Claude Code on a Pro or Max plan, your main conversation already gets a one-hour prompt cache. Your subagents probably do not. The prompt caching docs split every request into two TTL buckets, and only one of them gets the hour by default. That matters most for exactly the work subagents are good at: long fan-outs, slow research agents, and reviewers that sit idle while you read their output.
This post covers what the two buckets are, the settings that move them, the precedence order when several apply, when paying for the one-hour write is worth it, and how to check which TTL your requests actually got. That last part matters more than it sounds, because at least one public report shows the docs and the transcripts disagreeing.
The two buckets
Claude Code decides the cache TTL per request. Every request falls into one of two buckets:
- Main conversation: your interactive turns,
-pruns, Agent SDK turns, and the helpers Claude Code runs inline with them. - Everything else: subagents, workflows, in-process teammates, forks, compaction and session titles.
Defaults, per the docs:
- Claude subscription, within plan usage: main conversation gets one hour. Everything else gets five minutes, except a small set of helper requests that Anthropic controls server-side.
- Usage credits, API key or cloud provider: five minutes for both buckets.
The docs say it directly in the subagents section: subagents fall outside the main-conversation bucket, "so they get five minutes even on a subscription" until you choose otherwise. A subagent also starts with its own system prompt and tools, so its first request never reads the parent’s cache. It warms its own, and that cache dies after five idle minutes.
What the hour costs
The one-hour TTL is not free. On the API, a five-minute cache write costs 1.25x the base input price, a one-hour write costs 2x, and a cache read costs 0.1x (with lower read multipliers on some models). Here are the current per-million-token rates from the API prompt caching page for the two models most people run subagents on:
So the trade is simple. The hour costs an extra 0.75x of base input on every write. In return, a gap between 5 and 60 minutes becomes a cache read instead of a full rewrite. Take a subagent with a 50k-token prefix on Opus 5.5:
- Five-minute TTL, no idle gap: write $0.25, next turn reads for $0.01. Total $0.26.
- One-hour TTL, no idle gap: write $0.40, read $0.01. Total $0.41.
- Five-minute TTL, one gap over five minutes: write $0.25, expire, write again $0.25. Total $0.50.
- One-hour TTL, same gap: write $0.40, read $0.01. Total $0.41.
One avoided expiry per prefix pays for the hour. If the subagent never pauses for five minutes, the hour is pure overhead. Those dollar figures are API billing; on a subscription the same tokens count against your plan usage instead, but the shape of the trade is the same. The API docs list the same use cases for the hour: prompts reused less often than every five minutes but more often than every hour, such as "an agentic side-agent" that takes longer than five minutes.
When to set it to 1h
- A subagent you resume later. The docs note a resumed subagent’s first request can read the cache the original run warmed, but only if it is still alive.
- Long fan-outs where agents sit waiting on tools, builds or test runs for more than five minutes between turns.
- A reviewer or auditor agent whose results you read, think about, then send back for a second pass.
When to leave it at 5m
- Short, busy subagents that finish in a few back-to-back turns. Each turn resets the five-minute timer, so they never expire.
- One-shot explorers whose cache is never read again.
- Anything billed through usage credits where you have not measured idle gaps yet.
The settings
Each control takes 5m or 1h; Claude Code ignores any other value. The settings and environment variables require Claude Code v2.1.242 or later.
- Main conversation:
promptCacheTtlsetting orCLAUDE_CODE_PROMPT_CACHE_TTL. - Everything else:
subagentPromptCacheTtlsetting orCLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL.
For all subagents in every project, add it to ~/.claude/settings.json (or .claude/settings.json for one project):
{
"subagentPromptCacheTtl": "1h"
}For a single session, use the environment variable:
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h claudeOn an API key, the main conversation is also on five minutes by default, so you probably want both:
{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "1h"
}Per-subagent: the experimental cacheTtl
Usually only one or two agents idle long enough to justify the hour. Since v2.1.248 a subagent file can set its own TTL inside the experimental map (not at the top level of the frontmatter). Save this as .claude/agents/repo-auditor.md:
---
name: repo-auditor
description: Audits a large repository and reports what it finds
tools: Read, Glob, Grep
experimental:
cacheTtl: 1h
---
You audit the repository. Report findings with file paths and line numbers.Two caveats from the docs: Claude Code reads this field only from subagent files, and it ignores 1h there while your Claude subscription is drawing on usage credits.
