Feature request: user-configurable cache breakpoint hierarchy in settings.json

Feature request: user-configurable cache breakpoint hierarchy in settings.json

Summary

Expose the prompt-cache breakpoint placement to Claude Code's settings.json so production users can control which sections of the assembled prompt are treated as cache anchors. Today the placement is internal; users can only influence cache hit rates indirectly (by keeping CLAUDE.md / AGENTS.md stable).

Motivation

In a production agentic-coding harness (Qapnova monorepo, ~50 sessions/week, multi-developer), we measured the per-session startup context budget at approximately:

• Tool definitions: ~3-4 KB
• System prompt: ~variable
• Root CLAUDE.md: 188 lines (≈3 KB) — recently trimmed from 324 lines per Anthropic 200-line guideline
• MEMORY.md: 48 lines (~600 tokens)
• Skill catalog list: ~3-4 KB
• AGENTS.md (path-glob loaded): variable

The first ~10-12 KB of every session is structurally stable across sessions for the same workspace. Anthropic's prompt-caching API (cache_control checkpoints) supports up to 4 breakpoints, and the public DEV.to "RCA -90% cost" case and Anthropic's own SpringAI 5-strategy guidance both demonstrate that placing breakpoints on stable prefixes (tools → system → CLAUDE.md → messages-tail) reliably gets > 80% cache hit rate.

We cannot configure this from inside Claude Code today. Per my reading of the docs (https://code.claude.com/docs/en/settings), there is no cachingPolicy.breakpoints or equivalent. The harness places breakpoints automatically; the placement is opaque to the user.

What I'd like to configure

A schema along these lines in settings.json:

{
  "cachingPolicy": {
    "breakpoints": [
      {"at": "tools", "ttl": "1h"},
      {"at": "systemPrompt", "ttl": "1h"},
      {"at": "claudeMd", "ttl": "1h"},
      {"at": "messagesTail", "ttl": "5m"}
    ]
  }
}

Or more abstractly, an enum like "strategy": "hierarchical-4" that selects a named strategy from a known catalogue.

Why this matters specifically for agentic coding harnesses

In a multi-feature monorepo with paths: frontmatter on AGENTS.md (Cursor MDC pattern), the per-feature AGENTS.md is what varies — but tools + system + root CLAUDE.md are byte-stable. Without explicit breakpoint control, a small CLAUDE.md edit (e.g., a one-line typo fix) cascades to invalidate every downstream cache section. Explicit breakpoints would let us freeze the cheap-to-invalidate sections (CLAUDE.md) downstream of the expensive-to-rebuild sections (tools, system).

The current opaque behaviour means a daily CLAUDE.md edit pattern can drop cache hit rate from ~80% to ~30% without any visible warning. We've measured this empirically: a session immediately after a CLAUDE.md commit pays a ~5k-token cold-cache cost vs the same session on the same prompt 5 minutes prior.

What I've already done internally

We've trimmed CLAUDE.md to 188 lines (under the Anthropic 200-line guideline), split oversized AGENTS.md files, added description: / tags: / paths: frontmatter to per-feature AGENTS.md (forward-compat with agents.md v1.1 progressive-disclosure), and unwired self-counter-acting hooks. All this helps cache hit rate at the margin but does not give us direct control over breakpoint placement.

Workaround for now

We're treating CLAUDE.md drift as a daily cache-bust event and budgeting one cold session per agent-day per developer. The cost is bearable but not invisible — would prefer explicit control.

Reference reading

• https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• https://claude.com/blog/lessons-from-building-claude-code-prompt-caching-is-everything

Happy to provide more concrete usage data if useful.

🤖 Filed by Claude Opus 4.7 (1M context) acting on behalf of the Qapnova engineering team.