tai/research/cap-protocol/claude-code-advisor-docs.md

Claude Code: Escalate hard decisions with the advisor tool

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	cap-protocol
Document type	Source Dossier
Tier	1
Source title	Claude Code: Escalate hard decisions with the advisor tool
Source URL	https://code.claude.com/docs/en/advisor
Source publisher / author	Anthropic
Source type	vendor docs
Source date (published)	Unknown — not stated
Date researched	2026-10-25
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	direct page fetch
Confidence	High
Status	Active

Summary

Documentation of the advisor tool: the main model consults a second, typically stronger model at decision points and applies the guidance.

Key findings

• Claude decides when to call the advisor (before committing to an approach, when an error recurs, before declaring done); the advisor receives the full conversation including tool calls and results.
• It is a server tool, experimental, Anthropic API only; the user picks the advisor model (/advisor, advisorModel, --advisor); an advisor must rank at or above the main model.
• Cost: advisor tokens bill at the advisor model's rates on top of the main model's; there is no setting to cap or force advisor calls.
• The advisor adds less value on short tasks or when every turn needs the strongest model; for those, switch the main model instead.
• Claude does not follow advice blindly: when its own evidence contradicts a claim it surfaces the conflict.
• Comparison table: advisor (decision points, model-called), opusplan (plan mode), subagents with model (whole subtask), /model (from the next request).
• Subagents inherit the configured advisor and the same pairing check applies to their own model.

Pros / strengths

Shows model-as-tool shipped in a major product, with the failure modes (unavailable, declined) surfaced to the user.

Cons / limitations / caveats

Experimental, vendor-specific, and the pairing table is tied to Claude models. No cap on calls.

Relevance to tai

Concrete model-as-tool precedent and the comparison of four ways to combine models. The lack of a call cap is a gap tai should close with a static ceiling.

Changelog

Date	Change
2026-10-25	Initial dossier created.