feat: honor MCP CallToolResult _meta.cache_hint to opt out of prompt caching per result

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet (see prior discussion below)
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code unconditionally applies prompt caching to all MCP tool results. In non-interactive and subagent workflows, the cache is written once, the session ends, and it is never read. The result is pure cost overhead with no benefit.

Each subagent run is an independent session; cache written in run N is never read by run N+1. The only workaround available today is DISABLE_PROMPT_CACHING=1, a global flag that also disables caching for tools and context that genuinely benefit from it.

Proposed Solution

Honor cache_hint: "no-cache" in CallToolResult._meta as a per-result opt-out:

{ "content": [...], "_meta": { "cache_hint": "no-cache" } }

The MCP spec reserves _meta for client-only metadata not forwarded to the model, making it the correct extension point. Claude Code would skip adding a cache breakpoint after any result carrying this hint. Results without the field keep existing behavior unchanged.

This key is being standardized in the MCP specification via SEP-2419, which is open and awaiting sponsor review. Implementing it in Claude Code now is backward-compatible and consistent with the direction of the spec.

Alternative Solutions

DISABLE_PROMPT_CACHING=1 is the only current workaround. It disables all caching globally, including for tools that return large, stable, reusable context where caching is genuinely beneficial. A per-result hint gives servers fine-grained control without requiring users to choose between all-or-nothing.

Priority

High - Significant impact on productivity

Feature Category

MCP server integration

Use Case Example

1. A subagent session calls 10 MCP tool results during a one-shot analysis run
2. Claude Code writes cache breakpoints after each result (~98K cache_write tokens total)
3. The session ends; the cache is never read
4. At Bedrock pricing ($1.00/M cache_write vs $0.80/M input), this adds ~63% to effective cost with zero benefit
5. With per-result cache_hint: "no-cache", the MCP server opts out and the overhead is eliminated

Additional Context

Benchmark evidence from aptu-coder on Bedrock:

| Condition | Median cache_write tokens | Cost/quality point |
|--------------|--------------------------|-------------------|
| Native + MCP | ~98 K | $0.0353 |
| Native only | ~49 K | $0.0216 |

After switching to DISABLE_PROMPT_CACHING=1 globally (v9 onward), all 30+ subsequent telemetry files show cache_creation_tokens: 0, cache_read_tokens: 0, confirming the overhead was real and avoidable.

The emit side of this proposal already exists in crates/aptu-coder/src/lib.rs via the no_cache_meta() helper, applied on all tool result paths. The missing piece is Claude Code honoring the hint on the receive side.

Prior discussion: #34334, closed by the stale bot after 30 days of inactivity.