feat(advisor): Anthropic Claude Code /advisor rollout

[ishaan-berri]

Overview

Anthropic's Advisor Strategy is now live in Claude Code (/advisor toggle). It pairs a fast executor model (Sonnet/Haiku) with a high-intelligence advisor (Opus) mid-generation — all inside a single /v1/messages request. LiteLLM currently breaks this when used as a proxy (anthropics/claude-code#46105).

How it works (API level):

• Request: {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-4-6"} in tools array + beta header anthropic-beta: advisor-tool-2026-03-01
• Response: assistant content contains server_tool_use (name: "advisor") + advisor_tool_result blocks
• Multi-turn: must round-trip these blocks verbatim — omitting them causes a 400

Provider support:

• Anthropic direct ✅ — runs inside Anthropic infra natively
• Vertex AI ⚠️ — likely supported, needs verification
• Bedrock ❌ natively, but LiteLLM will implement the orchestration loop so it works transparently

---

P0 — Anthropic direct — ✅ done in #25525

• Forward anthropic-beta: advisor-tool-2026-03-01 header from client to upstream
• Pass advisor_20260301 tool type through unchanged — don't strip/reject it
• Preserve server_tool_use (name: "advisor") in response — don't convert to OpenAI tool_call format
• Preserve advisor_tool_result in response
• Round-trip both blocks verbatim in multi-turn history
• Auto-strip advisor_tool_result from history when advisor tool is absent from tools on a follow-up turn (prevents 400)
• Add ANTHROPIC_ADVISOR_TOOL_TYPE constant — no more hardcoded strings
• Doc page: completion/anthropic_advisor_tool.md with examples for both /chat/completions and /messages, streaming, multi-turn, AI gateway, recommended system prompts
• Parse usage.iterations[] from response and expose it; add iterations field to Usage type
• Attribute advisor tokens to Opus pricing in spend tracking

P0 — Vertex AI — next PR

• Verify Vertex accepts anthropic-beta: advisor-tool-2026-03-01 header
• Confirm Anthropic transformation fixes carry through to Vertex path
• Test end-to-end with claude-sonnet-4-6 on Vertex endpoint
• Return clear error if Vertex rejects the advisor tool (feature not yet live there)

P0 — Bedrock Invoke + Converse (LiteLLM implements the loop) — next PR

Bedrock can't run the advisor server-side, but LiteLLM will implement the orchestration so the user-facing API is identical.

• Detect advisor_20260301 tool in request routed to Bedrock
• Strip advisor tool from outgoing Bedrock request
• When executor responds with advisor tool_call → intercept; run separate LiteLLM completion to the advisor model with full conversation transcript
• Inject advisor response as synthetic advisor_tool_result block → resume executor loop
• Streaming: pause stream → emit server_tool_use + advisor_tool_result blocks → resume
• Multi-turn: strip synthetic advisor blocks from history before sending to Bedrock; re-inject as text context
• Track advisor sub-call tokens under advisor model pricing; populate synthetic usage.iterations[]
• Don't crash on server_tool_use / advisor_tool_result in input history during Bedrock message transformation

---

P1 — usage.iterations[] — next PR

• Parse usage.iterations[] from Anthropic response
• Add iterations field to Usage type so callers can see per-iteration token counts and identify advisor sub-inferences

P1 — Internal advisor for all other non-native providers

• Reuse Bedrock orchestration as a provider-agnostic layer (OpenAI, Groq, Mistral, etc.)
• Expose advisor_max_uses config to cap calls per request

P1 — Advisor system prompt injection (optional proxy helper)

Automatically inject Anthropic's recommended timing/weight prompts when advisor tool is present.

• Timing block: call advisor BEFORE substantive work; orientation (reading files) is fine first
• Advice weight block: give advice serious weight; surface conflicts in follow-up advisor call
• Optional conciseness instruction (~35–45% token reduction)
• advisor_conversation_max_uses config: auto-remove advisor tool + strip history blocks when cap reached

---

Related

• PR #25525 — P0 Anthropic direct support
• Anthropic advisor tool docs
• Claude Code /advisor issue #46105

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.