The Advisor Tool — Pairing a Fast Model with a Stronger One Mid-Task

Source: raw/reddit-1unl2si.md

The advisor tool is a native Claude Code feature (v2.1.98+, Anthropic API only) that lets a fast, cheap main model consult a stronger advisor model at key decision points mid-task — before committing to an approach, when an error keeps recurring, or before declaring the task done — then keep executing with that guidance applied. It surfaced on r/ClaudeCode as a tip most users had missed, and Anthropic’s own documentation confirms it as a shipped, currently-documented feature rather than a rumor. It sits alongside opusplan, subagents, and manual /model switching as another way to get a stronger model involved in a session, but it is the only one of the four that Claude invokes itself, mid-turn, without you re-entering a mode or switching your main model.

Key Takeaways

• A fast/cheap main model consults a stronger advisor model mid-task for strategic guidance, then keeps executing itself — the advisor never takes over the task or calls tools directly.
• Three ways to set the advisor: the /advisor <model> command (mid-session, persists across sessions), the advisorModel setting in your settings file (a persistent default), and the --advisor <model> flag (single-session, overrides the saved setting).
• Claude decides when to consult, not a fixed rule — typically before committing to an approach, when stuck on a recurring error, or before declaring a task complete.
• Accepted pairings follow a capability floor: the advisor must be at least as capable as the main model, per an explicit acceptance table.
• Billed separately: advisor calls consume tokens at the advisor model’s own rates on top of main-model usage; API billing charges advisor input/output separately, and subscription usage counts against plan limits.
• Toggling the advisor mid-session does not invalidate the main model’s prompt cache — unlike switching model or effort level, both of which do.
• Requires Claude Code v2.1.98+ and the Anthropic API — not available on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. Fable 5 as either main or advisor model needs v2.1.170+ and org-level Fable 5 access.
• Two kill switches: /advisor off clears your saved advisor; CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 disables the tool entirely.

How to Enable It

• /advisor command. Run bare to open a picker listing available advisor models, or pass the model directly: /advisor opus. The selection saves to advisorModel in your user settings and persists across sessions. If your organization’s availableModels allowlist excludes the saved advisor, it stays saved but inactive until you pick an allowed model; if your current main model doesn’t support the advisor, the selection still saves and activates once you switch to a compatible main model.
• advisorModel setting. Set a persistent default directly in your Claude Code settings file without needing an interactive session: {"advisorModel": "opus"}.
• --advisor flag. Launch a single session with a one-off advisor without touching your saved setting: claude --advisor opus. This takes precedence over the advisorModel setting for that session only, and exits with an error if the main model doesn’t support the advisor or the requested advisor is excluded by an org allowlist.
• Model aliases. Set the advisor as opus, sonnet, or fable — these resolve to the latest version of each model — or pass a full model ID such as claude-opus-4-8.
• Subagents inherit it. Subagents pick up the configured advisor and have the same pairing check applied against their own model.
• Turning it off. /advisor off (or “No advisor” in the picker) clears your saved advisorModel. For a full kill switch, set CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1: the /advisor command disappears, any saved advisorModel is ignored, and the --advisor flag becomes a silent no-op — existing scripts that pass it keep working without erroring.

Accepted Model Pairings

The advisor must be at least as capable as the main model. Anthropic’s acceptance table:

Main model	Accepted advisors	Notes
Haiku 4.5	Fable, Opus, Sonnet	Haiku can call the advisor but cannot act as one
Sonnet 4.6	Fable, Opus, Sonnet
Sonnet 5	Fable, Opus, Sonnet 5	A Sonnet 4.6 advisor is rejected
Opus 4.6	Fable, Opus, Sonnet 5	Sonnet 5 and Opus 4.6 are ranked as equally capable, so an Opus 4.6 main accepts a Sonnet 5 advisor
Opus 4.7 or later	Fable, Opus 4.7, Opus 4.8	Opus 4.7 and Opus 4.8 are ranked as equally capable, so either accepts the other as an advisor. An Opus 4.7 main with an Opus 4.6 or Sonnet 5 advisor is rejected
Fable 5 (v2.1.170+)	Fable	An Opus or Sonnet advisor is rejected

Claude Code validates the pairing before sending a request: if the advisor is less capable than the main model, it simply isn’t attached (the /advisor output and a notification surface this), though a subagent running a more-capable model of its own may still use it.

Six common pairings and when each fits, per the original tip:

Pairing	When to use
Sonnet main + Opus advisor	Sonnet handles routine work and escalates planning, ambiguous failures, and completion checks to Opus
Sonnet main + Fable advisor	Fable 5 guidance at decision points without running Fable 5 throughout. Requires v2.1.170+ and Fable 5 access
Haiku main + Opus advisor	Lowest-cost main model with strong planning. Expect higher cost than Haiku alone but lower than switching the main model to Sonnet or Opus
Opus main + Opus advisor	A second Opus reviews the first. Useful for high-stakes tasks where an independent check matters more than cost
Fable main + Fable advisor	Highest-capability pairing when Fable 5 is available. Fable is a higher tier than Opus and Sonnet, so it’s the only accepted advisor for a Fable main model
Sonnet main + Sonnet advisor	A lower-cost second opinion for catching routine oversights

When Claude Consults the Advisor

• Model-driven, not rule-based: Claude tends to consult before committing to an approach, when an error keeps recurring, and before declaring a task done.
• There’s no setting to cap or force advisor calls — to get more or fewer consultations than Claude volunteers on its own, say so directly in the prompt (e.g. “consult the advisor before you continue”).
• The transcript shows an Advising line with the advisor model’s name while the call is in progress; press Ctrl+O to expand and read the full guidance once it returns.
• Claude generally follows the advisor’s guidance but adapts when its own evidence contradicts it — a recommended step that fails when tried, or file contents that contradict the advice, get surfaced as a conflict rather than followed unconditionally.

Cost and Prompt-Cache Behavior

• Each advisor call sends the full conversation to the advisor model, consuming tokens at that model’s own input/output rates on top of the main model’s usage. On subscription plans, advisor usage counts toward plan limits and shows up in /usage session totals.
• Because Claude only calls the advisor at decision points rather than on every turn, pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout the whole task — the same escalate-rather-than-run-throughout economics as the underlying Messages API tool this feature wraps (see The Advisor Strategy for published benchmark deltas).
• Prompt caching is unaffected: enabling or disabling the advisor mid-session does not invalidate the main model’s cached prefix, unlike changing model or effort level. The advisor’s returned guidance is cached as part of the transcript for later turns, but each individual advisor call re-reads the full conversation fresh — there’s no cache reuse between advisor calls themselves.

Requirements and Platform Restrictions

• Claude Code v2.1.98 or later (claude update to upgrade).
• Anthropic API only. The advisor is a server-executed tool — not available on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry. Through an LLM gateway configured with ANTHROPIC_BASE_URL, availability depends on whether the gateway forwards the request intact to the Anthropic API.
• Supported main models: Opus 4.6 or later, Sonnet 4.6 or later, or Haiku 4.5. Fable 5 also qualifies (as main model or advisor) on Claude Code v2.1.170 or later, given org-level Fable 5 access.

Compared to opusplan, Subagents, and Model-Switching

Anthropic’s own docs frame the advisor as one of four ways to combine model strengths, distinguished by when the stronger model runs and how it gets invoked:

Approach	When the stronger model runs	How it starts
Advisor tool	At decision points mid-task	Claude calls it when it needs guidance
opusplan	During plan mode, then switches to Sonnet for execution	You enter plan mode
Subagents with model set	For the entire delegated subtask	Claude delegates, or you invoke the subagent
/model	For all subsequent turns	You switch models

• vs. Plan Mode: opusplan front-loads the stronger model into a single planning phase, then hands off entirely to the cheaper model for execution — one switch, one direction, at the start of the task. The advisor stays available throughout and gets re-consulted at every decision point Claude judges warrants it, not just once up front. ^[inferred]
• vs. Subagents: a subagent with a model override runs the stronger model for an entire delegated subtask — downward decomposition, where the main model hands off a scoped piece of work. The advisor is upward consultation instead: the main model keeps driving the whole task and briefly asks a stronger model for a plan or correction without handing off any work to it. ^[inferred]
• vs. manual /model switching: switching models applies to all subsequent turns and can invalidate the prompt cache. The advisor leaves the main model — and its cache — in place, and only pulls in the stronger model for the moment it’s consulted.
• The advisor tool in Claude Code is the CLI-level configuration surface for the same underlying escalate-upward pattern documented in The Advisor Strategy (the advisor_20260301 Messages API server tool) — same “small model drives, stronger model consults instead of decomposing to workers” framing, exposed here as session settings and slash commands rather than a raw API tool declaration. ^[inferred]

Related

• The Advisor Strategy (advisor_20260301) — the underlying Messages API server tool this Claude Code feature configures; covers the beta header, benchmarks, and raw API usage pattern.
• Claude Code Subagents — downward delegation for an entire subtask, contrasted above with the advisor’s upward mid-task consultation.
• Plan Mode — Claude Code Planning Surface — covers opusplan, the plan-then-execute alternative Anthropic’s docs compare directly against the advisor.
• Session Architecture — the harness/server-tool architecture the advisor runs on top of.
• Claude Sonnet 5 — one of the accepted main/advisor models; a Sonnet 5 main model rejects a Sonnet 4.6 advisor under the capability-floor rule.
• Claude Fable 5 and Claude Mythos 5 — a Fable 5 main model only accepts a Fable advisor; as an advisor it requires v2.1.170+ and org access.
• Opus 4.7 Best Practices for Claude Code — effort-level and model-routing guidance for the same Claude Code surface the advisor tool configures.
• Getting more out of the Claude Platform (Puneet Shah, Code with Claude London 2026) — names the advisor strategy as one of five stack-ranked cost-optimization levers, with a concrete per-task cost reduction example.

Open Questions

• What happens if the advisor model itself errors out or times out mid-consultation — does Claude retry, skip, or surface the failure to the user?
• Does the advisor tool work inside Claude Managed Agents sessions, or is it Claude Code CLI-only?
• Is there a way to review a session’s full advisor-consultation history after the fact, beyond scrolling back through the transcript?

Try It

1. On a long refactor or a debugging session where the same error keeps recurring, start with Sonnet as the main model and run /advisor opus mid-session — watch for the Advising line before Claude commits to an approach or declares the task done, then press Ctrl+O to read the full guidance.
2. Set a persistent default for cost-sensitive projects by adding "advisorModel": "opus" to your settings file, so every Sonnet or Haiku session gets an Opus safety net without remembering to invoke it each time.
3. For a single high-stakes one-off session, launch with claude --advisor opus instead of touching your saved settings.
4. If you want more or fewer consultations than Claude volunteers on its own, say so directly in the prompt — e.g. “consult the advisor before you touch any file outside the test directory.”
5. Run the same non-trivial task two ways — Plan Mode with opusplan (Opus plans, Sonnet executes) vs. Sonnet main with an Opus advisor throughout — and compare which one catches more mid-task course-corrections when the task turns out harder than it looked.
6. If a script or CI job passes --advisor for automation, remember CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 silently no-ops it rather than erroring — safe to leave as an org-wide kill switch without breaking existing invocations.
7. Read the official docs at https://code.claude.com/docs/en/advisor for the full requirements list and the availableModels allowlist interaction — the Open Questions above are the gaps that page doesn’t cover.