Claude Code’s Hidden Advisor Tool

In a typical multi-agent setup, the smartest model is in charge. It plans, decomposes the task, and sends smaller pieces to cheaper workers.

The advisor pattern does something different. A cheaper executor keeps driving the task. It reads files, calls tools, follows the thread, and writes the final answer. The stronger model only steps in briefly at a decision point, offering a course correction before handing control back.

A lot of agentic coding work is not frontier reasoning. Much of it is search, inspection, convention-following, and synthesis. The expensive mistakes happen at branch points: choosing the wrong abstraction, misunderstanding which part of a system owns a behavior, or deciding too early that the investigation is complete.

Anthropic's Platform docs describe the advisor as a server-side tool. The executor emits a server_tool_use block named advisor, the server runs a separate advisor-model pass over the full transcript, and the result comes back as advisor_tool_result.

The advisor does not call tools and does not produce the user-facing final answer. It advises; the executor continues.

The advisor strategy post says Sonnet or Haiku drives while Opus advises. I wanted to see how that feels inside Claude Code.

Setup

I used Claude Code 2.1.139 on a clean local codebase.

The task was read-only: inspect a moderately sized project and identify the most important architectural paths related to a cross-cutting behavior. It was a useful small test because the answer was not sitting in one obvious file. The model had to distinguish between orchestration, local implementation details, aggregated accounting, and reporting layers.

The successful advisor run used this command:

CLAUDE_CODE_ENABLE_EXPERIMENTAL_ADVISOR_TOOL=1 \
  claude -p \
  --verbose \
  --output-format stream-json \
  --no-session-persistence \
  --model claude-sonnet-4-6 \
  --settings '{"advisorModel":"claude-opus-4-6"}' \
  --mcp-config '{"mcpServers":{}}' \
  --strict-mcp-config \
  --disallowedTools 'Bash,Edit,Write,NotebookEdit'

In claude -p, stream-json does not work unless --verbose is set. Without it, Claude Code exits before the model runs.

Surprisingly Haiku did not work as the executor in Claude Code, despite the Platform docs currently listing Haiku 4.5 plus Opus 4.7 as a valid API pair. With the experimental advisor flag enabled, the debug log said:

[AdvisorTool] Skipping advisor - base model claude-haiku-4-5-20251001 does not support advisor

So the cleanest local experiment was “Sonnet asks Opus.”

Baseline

I first ran the same investigation with the advisor disabled and only read/search tools available.

The baseline held up. Sonnet found the broad structure and gave a coherent explanation of the relevant code paths. It cost 0.4428085.

That keeps the claim honest. The advisor did not turn a bad answer into a good one. The baseline already understood the general architecture, so the advisor’s effect was narrower than a simple quality jump.

I also had one false baseline: if the Task tool is available, Claude Code can delegate to its own local Explore agent. For this comparison, I removed that path and limited the run to Read, Grep, Glob, and LS.

What Worked in Practice

With Sonnet 4.6 and advisorModel: claude-opus-4-6, Claude Code produced the server_tool_use event the API docs describe:

{"type":"server_tool_use","name":"advisor","input":{}}

Then the advisor result arrived as:

{"type":"advisor_tool_result","content":{"type":"advisor_result","text":"..."}}

In the local investigation, Sonnet read the project overview and several source files, then called the advisor before writing the final answer. The advisor did not appear as a normal listed Claude Code tool in system/init; it showed up as a server-side event in the stream.

The advisor’s correction was specific. Sonnet was about to describe one broad architectural path too smoothly. Opus pushed it to separate the system more precisely: one layer coordinated the workflow, another layer accumulated information across several places, and a later layer reported or summarized that information rather than producing it.

That correction made the final answer better. Not because Opus did the work, but because it intervened at the exact point where the executor was about to collapse adjacent concepts into one explanation.

The baseline had most of the pieces. The advisor run sharpened the framing.

Cost Breakdown

According to Claude Code’s result JSON, the best advisor run cost 0.68501755.

The model breakdown:

Sonnet 4.6 executor: 0.34979954999999996 USD
Opus 4.6 advisor:   0.33468 USD
Haiku auxiliary:    0.0005380000000000001 USD

The clean no-advisor baseline cost was 0.4428085.

On this small task, the advisor run cost more. The tradeoff was accuracy and steering: an extra Opus pass reduced the chance that the executor would commit to a slightly wrong architectural interpretation.

The key detail is the usage.iterations[] entry for the advisor. It appeared separately, with its own record:

{
  "type": "advisor_message",
  "model": "claude-opus-4-6",
  "input_tokens": 61741,
  "output_tokens": 1039
}

The API docs warn that top-level usage is not enough for cost accounting. You need the per-iteration breakdown because advisor tokens are billed at the advisor model’s rate.

How It Shows Up

This is not yet a polished public Claude Code feature, at least not in the obvious way. The advisor tool did not appear in the normal system/init tool list. The public Claude Code tools reference page I checked also omitted it.

I had to enable:

CLAUDE_CODE_ENABLE_EXPERIMENTAL_ADVISOR_TOOL=1

and pass advisorModel in settings to use it.

Also, advisorModel: opus resolved to Opus 4.7 locally, and Opus 4.7 returned overloaded in my Sonnet runs. Explicitly setting claude-opus-4-6 worked.

The practical implication is narrower than the product story:

The API docs describe the official tool, the Claude Code binary already contains the feature, and local Claude Code behavior has its own compatibility quirks.

Why It Matters

Honestly, I think it currently doesn't matter that much, because Haiku can't use it and Sonnet is quite capable on it's own already. So I would guess that Anthropic will soon release a new version of Haiku (or some other smaller/cheaper model) that will be able to use the advisor tool. This is when it will get interesting.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com