Per-agent Claude cache lifetime with guidance for long-running test workers

[Vergil333]

Problem

Long-running Claude workflow/subagents can spend more than five minutes waiting for tests or browser QA. Their default five-minute prompt cache can expire during the tool wait, causing the next request to rewrite a large conversation. Extending caching globally also affects short tasks that do not benefit from its higher write cost.

In one locally investigated case, an agent waited about 513 seconds for QA. Its next response recorded 145,456 five-minute cache-write tokens and only 6,165 cache-read tokens. This supports cache expiry as a contributor; it is not evidence of a billing defect or a measured subscription quota percentage.

Existing Claude support

Claude supports a per-named-subagent definition:

experimental:
  cacheTtl: 1h

This requires Claude Code v2.1.248 or later and is read only from subagent files. Higher-precedence settings/environment controls can override it, and the frontmatter's one-hour choice is ignored when a subscription is using usage credits.

The Claude defaults distinguish main conversation requests from subagent/workflow requests. This matters when a T3 child is implemented as a separate SDK session versus a native Claude subagent.

Proposed behavior

• Expose a capability-advertised, per-child option such as cacheTtl: default | 5m | 1h through delegation and workflow agent creation. Keep default unchanged.
• Apply the override only to the selected child process/session using supported provider controls. Do not edit shared user or project settings or leak the override into sibling runs. Explicitly define whether descendants inherit it.
• Handle the appropriate Claude request bucket for the child implementation, rather than assuming all children use the subagent bucket.
• Include brief parent-agent guidance: prefer the default for short research/review tasks; consider one hour for repeated test or browser waits longer than five minutes in a large-context agent. Duration alone does not justify one hour, and the higher write cost matters.
• Expose effective cache lifetime, cache read/write counters, and any detectable override/unsupported status. Do not claim exact weekly quota remaining unless the provider supplies reliable telemetry.
• Unsupported providers or versions should advertise no override and report a clear limitation rather than silently ignoring the choice.

Acceptance criteria

Starting one child with 1h and another with default preserves independent effective policies without changing global configuration. Resuming the chosen child retains its policy. Effective policy and usage counters are visible to the parent. Provider precedence rules are respected, and the parent receives concise selection guidance.

References

• https://code.claude.com/docs/en/prompt-caching#which-ttl-each-request-gets
• https://code.claude.com/docs/en/prompt-caching#choose-the-ttl-yourself
• https://code.claude.com/docs/en/sub-agents#frontmatter-reference

Related: #7590 covers cache-window visibility; this proposal adds per-child policy selection and parent-agent guidance.