Use it now
Useful3 Signal4
An agent file can set its own prompt cache lifetime under experimental cacheTtl.
What's wrong with this entry?
Anonymous. No account, no email.
cacheTtlexperimental
What
An agent definition file can declare a prompt cache time-to-live under experimental: { cacheTtl }, and that value is carried into the query as an agent-level override of how long the prompt cache entry lives. It only takes effect when no higher-precedence setting is present, so agents that leave it out behave exactly as before. Nothing like this existed in the previous build.
Details
- The
CLAUDE_CODE_PROMPT_CACHE_TTLenvironment variable and thepromptCacheTtlsetting both win over the frontmatter value, which applies only when thesubagentPromptCacheTtlsetting and its environment variable are both absent, and is recorded with the reasonagent_frontmatter. - A value of
"1h"is rejected when the caller is in a mode where a one-hour cache is not permitted, and the field's own description notes that a one-hour value is ignored while a Claude subscription is in overage. - The
experimentalobject is permissive: unrecognised keys inside it are ignored rather than rejected by the otherwise strict agent frontmatter check. - The override is only passed along when the agent actually sets it, so the default path is unchanged.
Evidence
{ ttl: t, reason: "agent_frontmatter" }, agentCacheTtlOverride, Experimental per-agent options; unknown keys are ignored.
Strings lifted out of the shipped bundle, so the claim above can be checked against them.