[BUG] Prompt caching is disabled for SDK query() and V2 sessions — only enabled for REPL

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The prompt caching feature (prompt-caching-scope-2026-01-05) is gated on querySource and only activates for repl_main_thread. SDK consumers using query() or unstable_v2_createSession() never get prompt caching, even though their usage pattern (repeated calls with the same system prompt) is the ideal caching scenario.

Location in cli.js (beautified, ~line 455180):

The caching logic checks querySource and only proceeds for REPL sessions. SDK sessions (querySource: "sdk") skip the cache control headers entirely.

Measured Impact

We ran controlled tests with 7 concurrent agents, each making multiple API calls per minute with identical system prompts (~2000+ tokens).

Without prompt caching (SDK default):

Turn 1: cache_write=60K, cache_read=0      → efficiency: 0%
Turn 2: cache_write=45K, cache_read=15K    → efficiency: 25%
Turn 3: cache_write=50K, cache_read=15K    → efficiency: 23%
Average cache efficiency: ~25%

With prompt caching enabled (patched):

Turn 1: cache_write=60K, cache_read=0      → efficiency: 0% (cold start)
Turn 2: cache_write=2K,  cache_read=58K    → efficiency: 97%
Turn 3: cache_write=2K,  cache_read=60K    → efficiency: 97%
Average cache efficiency: ~91%

The ~25% baseline comes from system prompt being the only part that occasionally matches across process invocations. With caching enabled on V2 persistent sessions (same process = byte-identical system-reminder injection), cache efficiency jumps to 82-100%.

Cost impact: For our 7-agent deployment on Claude Max, this is the difference between hitting rate limits constantly and running comfortably within quota.

What Should Happen?

Prompt caching should be enabled for SDK consumers, not just REPL. The prompt-caching-scope check should include querySource: "sdk" (or simply not gate on querySource at all).

SDK usage is actually a better caching candidate than REPL:

• Programmatic agents send the same system prompt repeatedly
• V2 persistent sessions guarantee byte-identical cache prefixes across turns
• The cache_write cost is amortized over many more calls than a typical REPL session

Workaround

We patch cli.js (~line 455180) to extend the caching condition to include SDK querySource. Single-line change.

Related Issues

• #32102 — SDK consumers cannot control prompt cache segmentation (related: cache control gaps in SDK)
• #34629 — Prompt cache regression in --print --resume (different mode, same symptom: caching not working)

Environment

• @anthropic-ai/claude-agent-sdk: 0.2.77
• Claude Code CLI: 2.1.77
• Runtime: Bun 1.3.10
• OS: macOS (Darwin 25.2.0, arm64)