[FEATURE] Expose the advisor tool's `caching` parameter in Claude Code

Preflight Checklist

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

Problem Statement

Every advisor call in Claude Code re-reads the entire conversation uncached, at the advisor model's rates. The Claude Code advisor docs state this directly:

The advisor model's own read of the conversation is not cached. Each advisor call processes the full transcript anew, with no reuse between calls.

The underlying API server tool (advisor_20260301) already supports advisor-side prompt caching via a caching parameter, but Claude Code neither sets it nor exposes a way for users to set it.

This hits hardest in exactly the sessions the advisor is designed for. Long refactors and debugging sessions run well past three advisor calls — the tool is prompted to consult before committing to an approach, when stuck, and before declaring a task done — and each of those calls re-reads a transcript that only grows. The cost is worst for the pairings where the advisor is most valuable: an Opus main model with a Fable 5 advisor (which bills to usage credits on plans where Fable 5 usage does), or an Opus main with an Opus advisor on a long session.

On subscription plans this is invisible and unfixable from the user side. Advisor usage counts toward plan limits with no per-call token accounting surfaced, so it presents as the usage bar draining faster with the advisor on, with no lever to pull.

The asymmetry is also confusing given that the executor side already caches carefully — toggling /advisor mid-session deliberately keeps the main model's cached prefix intact. Users reasonably assume the advisor side behaves the same way.

Proposed Solution

A settings key that maps to the API's existing caching parameter, defaulting to off so current behavior is preserved:

{
  "advisorModel": "opus",
  "advisorCaching": { "type": "ephemeral", "ttl": "1h" }
}

Details:

• Accept false or omitted (current behavior), or the {"type": "ephemeral", "ttl": "5m" | "1h"} object the API already takes.
• Hold the value constant for the life of a conversation. The API docs warn that toggling caching mid-conversation causes cache misses, so a change should apply from the next session or the next /clear rather than immediately.
• Surface advisor cache reads alongside the existing per-session prompt cache line in /cost, so users can tell whether it's actually helping.

The server-side mechanism already exists and is documented, including the tradeoff: the advisor's prompt on the Nth call is the (N-1)th call's prompt with one segment appended, so the prefix is stable; each call writes a cache entry and the next reads up to that point and pays only for the delta. Anthropic's own guidance is that this costs more than it saves at two or fewer advisor calls, breaks even at roughly three, and improves from there.

Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#advisor-side-caching

Alternative Solutions

• Heuristic auto-enable. Claude Code could turn caching on automatically once a session crosses its third advisor call, matching Anthropic's documented break-even point and requiring no user-facing setting. Arguably the better default; an explicit opt-in is just simpler to ship and easier to reason about.
• A custom advisor subagent. Not a substitute. A subagent starts with a fresh context window and only sees the parent's framing, which removes the independence that makes advisor guidance useful precisely when the main model has misread something.
• Prompting the advisor for shorter output. Helps, but only addresses output tokens. The uncached input read is untouched.
• Turning the advisor off on long sessions. What I currently do, and it's the wrong tradeoff — long sessions are where a second opinion is most valuable.

Priority

Medium - Would be very helpful

Feature Category

Performance and speed

Use Case Example

A concrete session from my own workflow:

1. I start Claude Code on a multi-file refactor with Opus as the main model and an advisor configured. The session is expected to run an hour or more.
2. Early on, after a few orientation reads, Claude consults the advisor before committing to an approach. The advisor reads the transcript — at this point maybe 20k tokens — and returns a plan.
3. Over the next 40 minutes Claude works through the refactor. The transcript grows with file reads, edits, and test output.
4. A test keeps failing in a way Claude can't resolve, so it consults the advisor again. The advisor re-reads the now much larger transcript from scratch. None of the tokens it already processed in step 2 are reused.
5. Claude finishes the work and consults the advisor a third time before declaring done. Another full uncached read, larger still.
6. By the end, three advisor calls have collectively re-processed overlapping copies of the same conversation, and my usage bar reflects it.

With advisorCaching enabled, steps 4 and 5 would read the stable prefix from cache and pay only for what was appended since the previous call. Per Anthropic's own break-even guidance, this session — three calls, growing transcript — is squarely in the range where caching wins.

The workaround today is to either drop the advisor on exactly the sessions that benefit most, or run my own agent loop against the Messages API where caching is available. Neither is a good answer for a subscription CLI user.

Additional Context

Related issues:

• #50502 — separate effortLevel configuration for the advisor model (different ask, same gap: advisor-specific knobs aren't exposed)
• #64660 — advisorModel is a flat global setting with no executor scoping

Technical considerations:

• The parameter is already implemented server-side and documented, so this is plumbing rather than new capability.
• Defaulting to off preserves current behavior and billing for everyone who doesn't opt in.
• The advisor tool is labeled experimental, so adding an opt-in setting seems consistent with its current stage.