[DOCS] ScheduleWakeup tool description claims "5-minute TTL" but subscription main sessions use 1-hour TTL
Description:
The built-in description of the ScheduleWakeup tool states: "The Anthropic prompt cache has a 5-minute TTL. Sleeping past 300 seconds means the next wake-up reads your full conversation context uncached" — and derives pacing guidance from it (e.g. "Under 5 minutes (60s–270s): cache stays warm").
Expected: Per the official docs (prompt-caching → Cache lifetime), on a Claude subscription the main session requests the one-hour TTL automatically. The tool description should reflect this (or state that TTL depends on authentication).
Actual: The description unconditionally states 5 minutes.
Evidence: On my machine (subscription, desktop app, no ENABLE_PROMPT_CACHING_1H / FORCE_PROMPT_CACHING_5M set), all cache_creation entries in session transcripts land in the ephemeral_1h_input_tokens bucket (371/371 records checked; ephemeral_5m_input_tokens = 0).
Impact: The stale description misleads the model into designing wake-up/keep-alive cadences around a 5-minute window. In my case the agent scheduled keep-alive beats every ~220s to "keep the cache warm" — pure wasted quota, since the cache had a 1-hour lifetime. Given the TTL regression history (#46829) and the env-var doc gaps (#48082), tool-description accuracy matters here: agents act on tool descriptions directly.
Suggestion: Make the description authentication-aware ("5-minute TTL on API keys; 1-hour on subscription main sessions; subagents always 5m"), or point to the prompt-caching doc instead of hardcoding a number.
Related: #48082, #46829
Showing cached comments. Read the full discussion on GitHub ↗
3 Comments
The 2.1.215-era behavior you documented (371/371 records on 1h TTL) no longer holds on 2.1.218+. Measured across 236 sessions: 2.1.218+ has
ephemeral_1h_input_tokens= 0 on all records, 5m-only.This means the ScheduleWakeup tool description's "5-minute TTL" claim is now accurate for subscription main sessions too — which is the problem, not the fix. The 1h TTL that the description was wrong about in 2.1.215 is now genuinely gone, so the description is accidentally correct and the behavior is accidentally bad.
The doc fix you suggested ("authentication-aware: 5-minute TTL on API keys; 1-hour on subscription main sessions") would now need to be "5-minute TTL on everything since 2.1.218" — unless the 1h TTL is restored.
Filed as #84253.
✍️ Author: Claude Code with @carrotRakko (AI-written, human-approved)
Thank you for re-checking this across 236 sessions. Your follow-up prompted me to re-check my own setup, where I'm seeing a different result — so rather than leave the thread with two unreconciled claims, here's what I found.
On the description itself. In my locally installed 2.1.216 CLI binary there are two
Picking delaySecondsvariants rather than one, selected by a runtime branch — the minified source reads… : t === false ? "## Picking delaySeconds\nThis session's requests use the default 5-minute …". Both are phrased as "This session's requests use…" rather than stating a global constant:This session's requests use a 1-hour Anthropic prompt-cache TTL, …This session's requests use the default 5-minute Anthropic prompt-cache TTL. …My current subscription session receives the 1-hour variant. I can't determine from the minified code what signal drives that branch, so whether it always selects correctly is a separate question — but the unconditional wording this issue was originally about does appear to have been addressed by that version.
On the 5m-only finding. I can't reproduce it here, which makes me think something differs between our environments rather than one of us having measured wrong.
My transcript data comes from subscription desktop-app sessions, grouped by each assistant record's own
versionfield — not by the version my separately installed CLI reports. For 2.1.222 I see 1,980 records with 1-hour cache creation and none with 5-minute creation, the latest on 2026-08-07; 2.1.219 and 2.1.221 look the same (23,094 and 7,454 records respectively, zero in the 5m bucket).The reported bucket doesn't directly observe server-side expiry, so I also compared adjacent requests after deduping by
requestId, excluding pairs spanning a model switch and keeping only pairs where the earlier record hadcache_read_input_tokens≥ 20k. Counting a "retained read" as ≥ 90% of the prior cached-token count, on 2.1.218+:The same overall shape holds at 0.8, 0.9 and 0.95 thresholds. This is only a behavioral proxy, not a direct observation of server-side expiry — but under a universal 5-minute TTL I wouldn't expect a 94% retained-read rate across those 5–30 minute gaps.
One thing that might explain the difference. #84253 lists Platform as Anthropic API. If that data came from API-key auth rather than a subscription login, 5m would be expected rather than a regression — which is close to the distinction this issue started from. Were the 2.1.215 baseline and the 2.1.218+ samples collected under the same authentication method, and were any prompt-caching override variables set in either case? If they differed, version alone might not account for the gap; if they were identical and it still reproduces, that's a real divergence worth pinning down.
Happy to compare other cuts of the data if that helps narrow down the difference.
Thanks for the detailed report. This was fixed in v2.1.207: the ScheduleWakeup tool's pacing guidance now reflects the prompt-cache lifetime your session actually uses (one hour on a subscription main session, five minutes on API keys and for subagents), rather than always stating five minutes.
See the changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
Cache lifetime rules: https://code.claude.com/docs/en/prompt-caching#cache-lifetime
🤖 Generated with Claude Code