Per-subagent `advisor` frontmatter field (pair each subagent's executor with its own advisor)

Status Open

Maintainer reply None cached

Activity 4 comments · opened Jul 2, 2026

Problem

The advisor tool is currently exposed only at the session level (advisorModel setting, /advisor, --advisor), and subagents automatically inherit that single session advisor. Multi-agent orchestration frameworks assign different executor models per role via the subagent model: frontmatter field — a cheap model for mechanical agents, a stronger model for planning/review. They cannot extend that per-role tiering to advisors: every subagent is forced to share the one session-wide advisor (or none). There is no way to express, for example, "no advisor on the Haiku mapping agent, but a Fable 5 advisor on the Sonnet executor agent."

Proposed solution

Add an advisor: (and/or advisorModel:) subagent frontmatter field in .claude/agents/*.md, a sibling to the existing model: field, that overrides the inherited session advisor for that subagent — including an explicit value to opt a subagent out (no advisor). Enforce the same executor/advisor pairing rules already validated at the session level.

Why

Lets orchestration layers apply advisor tiering per role, spending advisor tokens only where a stronger reviewer pays off — matching the advisor tool's own cost guidance. The underlying primitive already exists (session-level advisor); this makes it addressable per subagent instead of all-or-nothing per session.

Current state (for reference)

Session-level knobs today: /advisor <model>, advisorModel setting, --advisor, CLAUDE_CODE_DISABLE_ADVISOR_TOOL.
Subagents inherit the session advisor automatically.
Supported subagent frontmatter fields do not include any advisor field.

Downstream use case

GSD (https://github.com/open-gsd/gsd-core) assigns per-agent model tiers via model: frontmatter and a model-profile system; a per-subagent advisor field would let it pair each agent's executor with an appropriate advisor. This is the primitive an orchestration layer needs to make advisor tiering per-role instead of session-wide.

References

Advisor tool (API): https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool
Claude Code advisor docs: https://code.claude.com/docs/en/advisor

View original on GitHub ↗

4 Comments

behruznassre · 2 months ago

Downstream tracking issue in GSD (the orchestration framework referenced above): open-gsd/gsd-core#1872 — it documents the passive session-level advisor inheritance today and defers per-agent advisor tiering to this request.

k421s · 2 months ago

+1 — with measured data from a personal multi-agent setup that makes the case for per-subagent advisor control.

Setup: Opus 4.8 main thread with advisorModel: opus. The capability-pairing rule attaches the advisor to every Sonnet subagent, so orchestrated fleets make one advisor round-trip per agent whether the agent needs review or not.

Measured across all local transcripts since enabling advisor (2026-07-01 → 2026-07-02), using a transcript scanner that flags server_tool_use: advisor blocks with no matching advisor_tool_result:

91 advisor calls across 67 transcripts
80 returned a result (88%)
11 orphaned (result never arrived) — of which 3 were fatal (turn died on the orphaned call: API Error: Response stalled mid-stream ×2, plus one hang killed manually); the other 8 were dropped results the agent survived
Per-call fatality ≈ 2–3%, which compounds per fleet: an 18-agent workflow where each agent calls advisor once has a ~30–40% chance of losing ≥1 agent per run. Observed: exactly 1 agent death in an 18-agent workflow run.

Because the advisor is server-side (no hook events — #70611, no tools: gating, no permissions.deny target), the only control today is the global CLAUDE_CODE_DISABLE_ADVISOR_TOOL kill switch — which also removes the advisor from the main thread, where its reviews are consistently worth keeping. Per-subagent frontmatter would let failure-sensitive fleets opt out (or pair down) while keeping the advisor where it adds the most value.

zan-xhipe · 1 month ago

This would be a great addition. At the moment I am catching Explore and Plan agents using the advisor. This defeats the purpose of the Explore agent since now it is slow and expensive, and the Plan agent doing it results in essentially double calling the advisor since it is called to review the plan by the Plan agent, and then the main agent calls it again to review the plan before presenting it.

coryleeio · 1 month ago

came here looking for this feature :)