Audit of our `ClaudeProvider` against the current Anthropic prompt caching documentation revealed several gaps that reduce or eliminate caching effectiveness.

Child issues

• fix(cache): Block 1 base prompt (~377 tokens) is below minimum cache threshold #1083 — [HIGH] Block 1 base prompt (~377 tokens) is below minimum cache threshold — caching silently fails
• fix(cache): tool definitions lack cache_control — tools invalidate system cache without savings #1084 — [MEDIUM] Tool definitions not marked with `cache_control` — tools invalidate system cache without benefit
• chore(cache): remove outdated anthropic-beta prompt-caching-2024-07-31 header #1085 — [MEDIUM] Outdated `anthropic-beta: prompt-caching-2024-07-31` header should be removed
• feat(cache): adopt automatic caching for multi-turn ACP sessions #1086 — [LOW] Consider automatic caching for multi-turn ACP sessions
• feat(cache): add message-level cache_control for long ACP conversations #1087 — [LOW] Message-level `cache_control` for long conversations (20-block lookback)

Context

Issue #1079 fixed marker ordering in `rebuild_system_prompt` (PR #1081). This epic tracks remaining compliance gaps found by auditing the current docs.

Recommended fix order

1. chore(cache): remove outdated anthropic-beta prompt-caching-2024-07-31 header #1085 (remove outdated header) — safe, no behavior change
2. fix(cache): Block 1 base prompt (~377 tokens) is below minimum cache threshold #1083 (fix token threshold) — restores actual caching
3. fix(cache): tool definitions lack cache_control — tools invalidate system cache without savings #1084 (cache tool definitions) — additional savings
4. feat(cache): adopt automatic caching for multi-turn ACP sessions #1086 (automatic caching) — long-term simplification
5. feat(cache): add message-level cache_control for long ACP conversations #1087 (message caching) — only for very long sessions