[DOCS] Which sessions write 1-hour vs 5-minute prompt cache is not documented; headless `-p` workers pay the 2x write rate
Documentation Type: Pricing / CLI reference
Documentation Location: Prompt caching pricing page; Claude Code headless (-p) and SDK docs
Section/Topic: Cache TTL selection by session type
Current Documentation: The pricing page documents the 1-hour cache write rate (2x base) and the 5-minute rate (1.25x). Nothing in the Claude Code docs says which TTL a given session type uses.
What's Wrong or Missing? On Claude Code 2.1.292, interactive sessions and headless claude -p sessions write 1-hour cache (cache_creation.ephemeral_1h_input_tokens), while subagents launched with the Agent tool write 5-minute cache (ephemeral_5m_input_tokens). A team that dispatches workers by script (headless) pays 2x on every cache write; a team that uses subagents pays 1.25x, for the same job (measured: 79k 1-hour writes vs 96k 5-minute writes for one brief). Nothing tells them.
Suggested Improvement: One sentence in the headless/SDK docs and one in the subagent docs naming the TTL each uses, and whether it is configurable.
Impact: Cost planning for anyone running headless workers at scale; the difference is invisible without reading transcript usage blocks.
Additional Context: Claude Code 2.1.292, macOS 26.7.1 arm64, Anthropic API, Fable 5.1 parent, Sonnet 5.5 workers.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗