[FEATURE] Let a subagent opt out of the advisor (per-agent key or settings scope)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

A subagent gets a task that the caller has already scoped, yet it inherits the advisor and calls it — and there is no supported way to turn that off for subagents only.

The advisor is expensive per call because its read of the transcript is uncached (stated in the advisor docs and quoted in #91110). Measured across my fleet for 2026-09-14 00:00 → 2026-09-16 05:45 (2.24 days, 4 hosts, 23,454 API calls, Claude Code 2.1.270–2.1.273):

| | |
|---|---|
| advisor calls | 434 |
| of those, made by subagents | 292 (67%) |
| average uncached input per call | ~138k tokens |
| share of total token weight in the window | 24% |

Weight is measured as a public-price equivalent (a proxy for how much of the budget a call consumes, not an actual bill — this is a subscription). On that scale one advisor call cost ~$1.83 against ~$0.219 for an Opus call and ~$0.045 for a Sonnet call in the same window: one advisor call ≈ 8 Opus calls ≈ 40 Sonnet calls.

Per subagent type, the advisor is a surcharge on top of the work the agent was asked to do:

| Agent | Its own work | Its advisor calls | Surcharge |
|---|---:|---:|---:|
| coder (Sonnet) | $751 | 120 calls / $191 | +25% |
| reviewer (Opus) | $386 | 131 calls / $183 | +47% |

The advisor is genuinely useful in the main session, which chooses its own approach. A coder subagent handed "apply this described edit" does not need a second opinion on an approach it did not pick — and if the task is ambiguous it is supposed to report back to the caller, who has the wider context and can consult the advisor itself.

No supported switch exists for this. Verified on 2.1.273:

• The agent-definition frontmatter accepts disallowedTools (schema: "Array of tool names to explicitly disallow for this agent"), but it does not gate the advisor. Probe with a concurrent control: a coder with disallowedTools: advisor still made an advisor call of 42,960 input tokens; an untouched runner did the same (42,534). The advisor is a server-side tool (beta advisor-tool-2026-03-01, arriving as server_tool_use with name: "advisor"), so the client-side tool filter never sees it.
• The only configuration switch is the environment variable CLAUDE_CODE_DISABLE_ADVISOR_TOOL, which is process-wide — it would remove the advisor from the main session too, which is exactly where it earns its cost.
• The agent definition has no advisor key of any kind (same observation as #91715).

Proposed Solution

Either of these solves it; the first is the smaller change.

1. A per-agent opt-out in the agent definition frontmatter.

---
name: coder
model: sonnet
tools: Read, Edit, Write, Bash, Grep, Glob
advisor: false        # or: advisorModel: off
---

This also composes with #91715 (per-agent advisorModel:): if that key lands, off/false as an accepted value gives the opt-out for free, and the two requests collapse into one implementation.

2. A settings key that scopes the advisor to the main thread.

{
  "advisorModel": "opus",
  "advisorScope": "main"
}

with "main" (main session only) and "all" (current behavior, default) — so existing setups are unchanged and the fleet-wide policy lives in one place instead of every agent file.

Whichever shape, the advisor instruction block should not be injected into a context where the advisor is disabled — otherwise the agent is told to consult a tool it cannot use.

Alternative Solutions

Tried, and why each fails:

• disallowedTools: advisor in the agent frontmatter — accepted by the schema, no effect (measured above): server-side tools are outside the client tool pipeline.
• permissions.deny and PreToolUse hooks — do not cover server-side tools at all; that is the subject of #93182, which reports the deny-rule casing conflict and hooks never firing for this tool.
• CLAUDE_CODE_DISABLE_ADVISOR_TOOL — works, but process-wide: it takes the advisor away from the main session too.
• Prompt instructions — what I run now: a "never call the advisor tool" line as the first rule in coder/reviewer/runner definitions plus one line in the globally loaded rules so built-in agent types (Explore, Plan, general-purpose, the catch-all agent) get it too. I verified by grepping a fresh subagent's transcript that both lines are delivered and that it made no advisor call. But this is prompt text against a harness that re-injects the tool's call-it-first instruction into every agent context — it is a soft preference, not a gate, it cannot be audited except after the fact, and it spends context budget in every single agent run to say "do not use a tool you were just told to use".

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

A routine session on an implementation task:

1. The main session (Opus) plans the change and consults the advisor twice — this is the advisor working as intended, and I want to keep it.
2. It dispatches six coder subagents (Sonnet) for the individual edits and two reviewer subagents (Opus) for the diff.
3. Each of those eight subagents independently consults the advisor at least once, because the same instruction to consult before substantive work and before declaring done is present in their context too.
4. Those eight calls re-send eight full transcripts uncached. In my window that pattern was 292 calls and 24% of the token weight, for second opinions on tasks whose approach was already fixed by the caller.
5. With advisor: false on those three agent definitions, the advisor stays where it pays for itself and the subagent budget goes to the actual work.

Additional Context

• Measured with a small script over ~/.claude/projects/**/*.jsonl, deduplicating by message.id and splitting usage.iterations[] by type (advisor_message vs message). Worth noting for anyone reproducing this: the top-level usage of a multi-iteration message is the sum of its message iterations, so per-call context must be read from the iterations, not from the top level — and advisor iterations are not included in the top-level usage at all.
• Related, but each asks for something different:
• #91715 — per-agent advisorModel, i.e. which model advises a given agent. It does not ask for "no advisor", and its proposed key would not by itself provide an off value.
• #93182 — bug: server-side tools cannot be blocked by deny rules or PreToolUse hooks. Same root cause for why disallowedTools fails here; that issue asks for blocking to work session-wide, not for a subagent-scoped policy.
• #91110 — expose the advisor's caching parameter. That reduces the cost of each call; this request removes calls that are not wanted in the first place. They are complementary.
• Environment: Claude Code 2.1.273, Linux (WSL2), subscription plan; the measurement window spans 2.1.270–2.1.273; the same behaviour observed on a separate Linux server host.