[DOCS] prompt-caching.md says subagents use the 5-minute TTL, but transcripts show 100% 1-hour cache-creation tokens

[DOCS] prompt-caching.md says subagents use the 5-minute TTL, but transcripts show 100% 1-hour cache-creation tokens

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

The "Subagents and the cache" section of the prompt-caching docs (https://code.claude.com/docs/en/prompt-caching#subagents-and-the-cache) states:

Subagents use the five-minute TTL even on a subscription, since the automatic one-hour TTL applies to the main conversation.

This does not match what the actual API usage data in local session transcripts shows. Every response's usage.cache_creation field reports two buckets, ephemeral_1h_input_tokens and ephemeral_5m_input_tokens, which is the ground truth for which TTL a given request actually got.

I checked this across many subagent transcripts (~/.claude/projects/*/subagents/agent-*.jsonl and the equivalent nested subagent folders) spanning several different projects and sessions, all on a Claude subscription with no ENABLE_PROMPT_CACHING_1H / FORCE_PROMPT_CACHING_5M overrides set. Every single cache_creation entry checked landed entirely in ephemeral_1h_input_tokens, with ephemeral_5m_input_tokens at 0. Examples (one per file):

"cache_creation":{"ephemeral_1h_input_tokens":14705,"ephemeral_5m_input_tokens":0}
"cache_creation":{"ephemeral_1h_input_tokens":15745,"ephemeral_5m_input_tokens":0}
"cache_creation":{"ephemeral_1h_input_tokens":4364,"ephemeral_5m_input_tokens":0}
"cache_creation":{"ephemeral_1h_input_tokens":205,"ephemeral_5m_input_tokens":0}
"cache_creation":{"ephemeral_1h_input_tokens":4323,"ephemeral_5m_input_tokens":0}

I also asked a live subagent (general-purpose, spawned via the Agent tool) whether it had any visibility into its own cache TTL. It correctly reported it has no such information in its own context — so this isn't something a subagent can self-report; it has to be checked from the transcript's usage data, which is what I did.

This looks related to #54006 (closed, auto-stalled), which reported the opposite direction: subagent sessions stuck on 0% one-hour / 100% five-minute, treated as a bug because subagents were expected to get the 1-hour TTL like the parent. One commenter on that thread (oliver-kriska) found a version-correlated gradient where older Claude Code releases had much higher one-hour adoption for subagents than newer ones at the time. My data now shows 100% one-hour adoption for subagents, which is consistent with that trend continuing (or reverting) rather than subagents being hardcoded to 5m. Either way, the current docs page describing 5-minute TTL as intentional subagent behavior does not reflect what's actually happening for at least some class of subagent sessions today.

What Should Happen?

One of:

1. If subagents are actually intended to get the 1-hour TTL when the parent session has it (which the evidence here suggests is now the real behavior), the docs page should be corrected to say so instead of asserting a hardcoded 5-minute TTL.
2. If 5-minute TTL is still the intended behavior for some subagent types/paths and what I'm seeing is itself a bug (subagents getting 1h TTL when they shouldn't), then this needs a code-side look, and the docs are at least currently describing the intended-but-not-actual behavior.

Either way, right now the docs and the observed behavior disagree, and that should be reconciled by either fixing the docs or fixing the underlying behavior.

Error Messages/Logs

No error messages. See the cache_creation breakdown above, sourced from ~/.claude/projects/<project>/subagents/agent-*.jsonl (or ~/.claude/projects/<project>/<session-uuid>/subagents/agent-*.jsonl) transcript files.

Steps to Reproduce

1. Use Claude Code on a Claude subscription (no ENABLE_PROMPT_CACHING_1H / FORCE_PROMPT_CACHING_5M set).
2. Spawn any subagent via the Agent tool (or /agents) that does enough work to produce more than one API turn.
3. Locate the subagent's transcript file under ~/.claude/projects/<project>/.../subagents/agent-*.jsonl.
4. grep -oE '"cache_creation":\{[^}]*\}' <file> | sort -u
5. Observe ephemeral_1h_input_tokens populated and ephemeral_5m_input_tokens at 0, contradicting the docs' claim that subagents always use the 5-minute TTL.

Claude Code Version

2.1.222

Platform

Claude subscription (not API key / Bedrock / Foundry)

Is this a regression?

Unclear — possibly related to the version-correlated trend noted in #54006's discussion, but in the opposite direction (higher, not lower, one-hour adoption than the docs describe).