Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

Playbooks · Coding tasks

Run Sonnet with an Opus advisor in Claude Code

Written November 5, 2026

Sonnet does the routine work; Opus advises at decision points. How the advisor tool works, what it costs, and where it doesn't apply.

Running Opus on every turn burns money, but Sonnet alone can lock in a bad plan. The advisor tool splits the difference: Sonnet runs the session, and Opus — or another stronger model — is consulted at the moments that matter. The advisor is a server-side tool on Anthropic's infrastructure. It receives the full conversation, including every tool call and result, and returns guidance that Claude applies before continuing. Claude decides when to call it: before committing to an approach, when an error keeps recurring, or before declaring a task done.

Enable it three ways

The advisor documentation gives three ways to set the advisor model:

After the session starts, Claude Code shows an Advisor Tool (experimental) is on and may use more tokens · /advisor notification. To disable the advisor tool entirely, set CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1.

Which pairings work

An advisor must rank at or above the session's main model. The accepted pairings for the models most people run:

Main modelAccepted advisors
Haiku 4.5Fable, Opus, Sonnet, Haiku 5.5
Sonnet 4.6Fable, Opus, Sonnet, Haiku 5.5
Opus 4.6Fable, Opus, Sonnet 5 or later, Haiku 5.5
Sonnet 5 or Haiku 5.5Fable, Opus 4.7 or later, Sonnet 5 or later, Haiku 5.5
Opus 4.7 or Opus 4.8Fable, Opus 4.7 or later, Sonnet 5.5
Sonnet 5.5Fable, Opus 5 or later, Sonnet 5.5
Opus 5 or Opus 5.5Fable, Opus 5 or later
Fable 5Fable 5.1 or Fable 5
Fable 5.1Fable 5.1

Set the advisor as fable, opus, or sonnet. Those aliases resolve to Claude Code's built-in default version for each model family, which advances with new releases. You can also pass a full model id such as claude-opus-5-5. Two rules to know: Haiku 4.5 can call the advisor but cannot act as one, and subagents inherit the configured advisor with the same pairing check against their own model. A few pairings need newer versions: Fable 5.1 needs v2.1.257 or later, Sonnet 5.5 as the advisor for an Opus 4.7 or 4.8 main model needs v2.1.287 or later, and Haiku 5.5 as main or advisor needs v2.1.293 or later.

If the advisor ranks below the main model, Claude Code does not attach it to the main model's requests — the session runs without the advisor, and a notification says so. If the API refuses a pairing that Claude Code did attach, Claude Code resends the request without the advisor and the conversation continues with no error and no advisor calls.

The three-model split

The pairing that fits most long tasks is Sonnet as the main model with Opus as the advisor: Sonnet handles routine work and escalates planning, ambiguous failures, and completion checks to Opus. The documentation lists exactly that pairing in its common pairings table.

One pattern circulating in posts about the advisor adds a third model: Sonnet as the main model, read-only subagents on Haiku 5.5 for search, grep, and docs, and Opus as the advisor. That split is a community pattern matched against the documentation, not Anthropic's recommendation. What the documentation does support is each part of it: subagents can be set to run on Haiku with a model field, the built-in Explore subagent is read-only with Write and Edit denied, and subagents inherit the configured advisor. If you use the split, set the subagent model explicitly — the default Explore subagent runs on the main conversation's model unless you define one with model: haiku.

What you see during a session

When Claude calls the advisor, the transcript shows an Advising line with the advisor model name while the call is in progress. When the result returns, the line reports whether the advisor gave guidance:

Claude generally follows the advisor's guidance, but adapts when its own evidence contradicts a specific claim: if a recommended step fails when tried, or the file contents contradict the advice, Claude surfaces the conflict rather than following the guidance unconditionally.

What it costs

When Claude calls the advisor, the advisor model reads the conversation, so each call consumes tokens at the advisor model's rates in addition to your main model's usage. On API billing, you pay the advisor model's input and output rates for advisor tokens. On subscription plans, advisor usage counts toward your plan's usage limits — except that a Fable advisor bills to usage credits on plans where Fable usage does. Advisor usage counts toward the session totals shown by /usage.

Two cost details matter. First, there is no setting to cap or force advisor calls: Claude decides when to consult, and you can ask for a consultation in your prompt the same way you would request any tool, for example consult the advisor before you continue. Second, each advisor call re-reads the full transcript uncached. Toggling the advisor does not invalidate your main model's prompt cache, but the advisor's own read of the conversation is not cached — every call processes the full transcript anew. The documentation says pairing a faster main model with a stronger advisor typically costs less than running the stronger model throughout. That is the documentation's claim, not a measured saving: no cost measurement exists for the pairing.

Where it doesn't apply

Advisor, opusplan, or subagents

The advisor is one of several ways to combine model strengths. The documentation compares them:

ApproachWhen the stronger model runsHow it starts
Advisor toolAt decision points mid-taskClaude calls it when it needs guidance
opusplanDuring plan mode when allowed by availableModels, then switches to Sonnet for executionYou enter plan mode
Subagents with model setFor the entire delegated subtaskClaude delegates, or you invoke the subagent
/modelFrom the next request onwardYou switch models

Use the advisor when most turns are routine but plan quality determines the outcome — large refactors, debugging sessions where an error keeps recurring, and tasks you want independently checked before Claude declares them done. It adds less value on short tasks where there is little to plan, or on work where every turn needs the strongest model. For the difference between forked and parallel subagents, see run parallel subagents in Claude Code. For staying inside a plan's allowance while the advisor adds usage, see baseline usage before a shared allowance.

Limits

Related playbooks

Sources

Back to: Coding playbooks hub · Also: Run parallel subagents in Claude Code · Claude Code 2.1.318: sign-in expiry and fork effort · Baseline usage before a shared allowance