No way to set the prompt-cache TTL for built-in or Workflow subagents; subagents blocked in Bash lose the 5-minute cache every ~10 minutes

Environment: Claude Code 2.1.289, Claude desktop app (Code tab), macOS, mostly claude-opus-5-5. Numbers below come from the usage fields of my own session transcripts over the last 30 days.

Related: #99360, #74318 (same root cause, different angle).

Summary

Subagents default to the 5-minute prompt cache while the main session uses the 1-hour cache. I looked at 30 days of my own transcripts to see where that actually costs me. Almost all of the damage comes from a small number of subagent turns that arrive more than five minutes after the previous one, because each of those turns rewrites the entire context from scratch. The obvious fix is to raise the TTL for subagents, but right now there is no way to do that selectively, and a blanket change turns out to be a poor trade for my workload.

What causes the misses

Most of these cache misses were not caused by slow API responses. They came from subagents blocking in a single Bash call while waiting for a background job, for example a loop that polls an output file with sleep. The Bash tool cuts the call off at about ten minutes even when a longer timeout is requested, so the subagent wakes up, finds the cache expired, and pays for the full context again, then starts the same wait over. In the worst stretch the same subagent did this a dozen times in a row.

| | |
|---|---|
| Subagent turns that missed the cache after a >5 min gap | 332 |
| ...of which the previous turn was a Bash call | 299 (about 92% of the rewritten tokens) |
| Median Bash duration for those calls | 600 s |
| Median time from Bash result to the next request | 6 s |
| ...of which were until ...; do sleep N; done style polling | 148 |

Over the most recent 7 days, only about 3% of subagent turns had a gap over five minutes (cache hit rate for those turns: 7.9%), yet they were about 78% of all subagent cache-write tokens. Every subagent cache write in my transcripts was ephemeral_5m; every main-session write was ephemeral_1h.

Why I can't just fix it with a setting

The only per-agent control today is experimental.cacheTtl in a custom agent's frontmatter. It does not reach the built-in agents or the subagents that the Workflow tool spawns, and subagentPromptCacheTtl in settings.json is a single global value. In my data the built-in general-purpose agent is where raising the TTL would pay off, while the many short-lived Workflow subagents would simply pay the higher write price for nothing. I created a same-named general-purpose.md in the user agents directory during a running session and it had no effect (I have not tested after a restart).

Estimated effect of switching to 1h, at list prices (assuming 1.25x / 2x write multipliers for 5m / 1h):

| Agent type | Subagents | 30-day cost now | With 1h TTL |
|---|---|---|---|
| general-purpose | 250 | about $1,636 | about $1,191 |
| Workflow subagents | 2,518 | about $1,535 | about $1,818 |
| All subagents | | | net saving of about 5% |

So a global 1h setting only saves about 5% overall, while per-type settings would save considerably more.

Request

1. Let subagentPromptCacheTtl (or a similar setting) be scoped by agent type or origin, for example { "general-purpose": "1h", "workflow": "5m" }.
2. Allow a user or project agent file to override a built-in agent's frontmatter, or document that it cannot.
3. Consider making a subagent's Bash wait not silently truncate at about ten minutes, or at least surface a warning, since that truncation is what turns every long wait into a full cache rewrite.