Claude Code Subagent Effort Levels: Run Low-Effort Scouts and High-Effort Reviewers (v2.1.292+)

Introduction

Before Claude Code v2.1.292, every subagent inherited the effort level of your session. Run the main session hot for a hard refactor, and every file-searching, test-running scout it spawned ran hot too. Since the October 7, 2026 update, you can assign effort per subagent: cheap low-effort scouts do the broad searches, and one careful high-effort reviewer handles the part that needs judgment. This tutorial shows the prompt pattern that started it, how to make it durable in subagent definitions, how to combine it with model pinning, and how to check that it actually saved you money. It is written for developers who already run multi-agent work in Claude Code and are watching their usage budget.

Quick answer

In Claude Code v2.1.292+, name the effort level when you ask for subagents: run low-effort scouts to search the code, then one high-effort reviewer to check error handling. Effort can also be pinned per agent in subagent frontmatter.

Evidence

The feature arrived as a one-line announcement. On October 7, 2026, Lydia Hallie, who works on Claude Code at Anthropic, wrote: “You can now ask Claude to run subagents at a specific effort level! Make sure you’re on v2.1.292+.” The attached example was: “Find every payments API call with low effort subagents, then have a high effort one check the error handling.” That sentence is the whole technique in miniature, and it is worth treating as the canonical example because it comes from the team that built the feature.

The release notes back it up. The official v2.1.292 changelog states: “Added an effort parameter to the Agent tool, so Claude runs a sub-agent at the effort level you ask for.” Before this version, a subagent inherited the session’s effort, which is why the old habit was to run the whole session at one level and eat the cost on every scout.

The durable syntax lives in the official subagent documentation. According to Claude Code’s subagents documentation, a subagent definition can carry an effort frontmatter field with options low, medium, high, xhigh, and max. It overrides the session effort level, but not the CLAUDE_CODE_EFFORT_LEVEL environment variable, and the note adds that available levels depend on the model. That precedence chain is the most important thing to memorize from this tutorial, because it is also the most common reason the feature appears to be ignored.

Effort itself has a stable official definition. Anthropic’s guide to choosing a Claude model and effort level in Claude Code frames the two dials as “knowing more versus trying harder”: the model is the fixed weights, and effort is how much work Claude does on your request. A separate API-side effort parameter reference documents the five levels for supported models. Per-subagent effort is that same dial, moved from the session level down to the individual agent.

Two measured numbers justify the fuss about costs, both as of October 2026. Anthropic’s cost-optimization notes bundled with Claude Code (summarized in independent source audits) report that on Fable 5 research benchmarks, low effort gave up 1 to 3 points of score for roughly a third to a half off the cost per task, while medium matched the default at 70 to 85 percent of its cost. The same guidance measured a run-everything-at-low strategy with failures re-run at the default: about 93 percent pass for about $0.70 per task, versus 91.7 percent for $1.39 at the default. Independent measurements of subagent runs add the counterweight: each subagent builds its own context, so total tokens rise with parallelism even when the wall-clock time falls. Mixed effort does not make subagents free; it aims the spending at the steps where reasoning pays.

Prerequisites

• Claude Code v2.1.292 or later. Run claude --version and update if the number is lower. The npm install (npm install -g @anthropic-ai/claude-code) is the documented way to get the current build.
• A Claude plan or API billing with enough usage headroom to experiment. Mixed effort is a cost-control feature, and the savings only show on runs large enough to matter.
• Basic familiarity with Claude Code subagents: the idea that Claude can delegate a bounded task to a fresh agent whose summary returns to the main session. If you have not defined custom agents before, the official subagents documentation is the reference to read first.

Step-by-step guide

Step 1: Confirm the version and current effort

Open a terminal and check the build:

claude --version

You want 2.1.292 or anything later. On an older build, per-agent effort silently does nothing and every subagent keeps inheriting the session level, which is the pre-2.1.292 behavior.

Inside a session, type /effort to see the current session level. Leave the session at your normal setting, usually medium or high depending on the model. The point of this tutorial is that the session level no longer has to cover the scouts.

Step 2: Ask for effort in plain language

The announcement’s pattern has three parts: name the work, name the effort, and say how the results combine. Adapt it to your codebase:

Find every place we call the payments API using low effort subagents,
one per top-level package. Then run a high effort subagent over the
combined list to check that each call handles timeouts, retries and
idempotency keys. Report only the calls that are unsafe.

Three more recipes follow the same shape:

Use low effort subagents to summarize each service directory in two
sentences. Then have one high effort subagent read the summaries and
propose where the module boundaries are wrong.

Use low effort subagents to reproduce each failing test and classify
the cause as flaky, environment or real. For the real failures only,
use a high effort subagent per failure to propose a fix.

Split this diff by directory. Use medium effort subagents to review each
slice for style and obvious bugs. Use one high effort subagent to look
for cross-slice problems such as changed interfaces.

Two habits improve the results. State the effort once per phase, not in every sentence, so the instruction is unambiguous. And demand a terse, structured format from the scouts, a flat table or a short list, because verbose scout output is what the expensive reviewer then has to read. Most of the savings come from that last habit, not from the effort level itself.

Step 3: Pin effort in subagent frontmatter

Plain-language prompts work per session. For a standing convention, define custom agents with a pinned effort. Create .claude/agents/scout.md in your project (or ~/.claude/agents/ for your user scope):

---
name: scout
description: Fast read-only code searcher. Finds call sites, summarizes files, classifies issues. Use when the task needs broad coverage of a codebase and the answers are lists, not judgments.
tools: Grep, Glob, Read
model: inherit
effort: low
---

You are a code search scout. You do not write code and you do not
redesign anything. Your job is breadth, not depth: find every match,
report file and line for each, and keep the output to a flat list or
table. Never return prose summaries of what you found.

And .claude/agents/reviewer.md:

---
name: reviewer
description: Careful reviewer for error handling, concurrency, and security-sensitive diffs. Use when a change needs judgment about edge cases and failure modes.
tools: Read, Grep, Glob
model: inherit
effort: high
---

You are a reviewer. Read the actual code around every item the scouts
flagged, not only their summaries. For each item, answer: what happens
on a network error, a partial response, a duplicate submission, and an
expired token? Return only the items that are genuinely unsafe, with a
suggested fix for each. If the evidence does not support a finding, drop it.

Two details from the official documentation matter here. First, model: inherit keeps the subagent on the session’s model; you can name a model instead. Second, the effort field overrides the session level but loses to the CLAUDE_CODE_EFFORT_LEVEL environment variable, so if your agents ever seem to ignore the pinned level, that variable is the first thing to check. If your scouts or reviewer need to call external tools, connect the servers first using the Claude Code MCP setup guide; effort and tools are independent dials on the same agent.

This scout-and-reviewer pairing is the multi-agent cousin of the agent orchestration in Anthropic’s dynamic workflows, where a lead agent splits work and specialized agents handle each phase, except here it runs locally in Claude Code with no platform billing.

Step 4: Combine effort pinning with model pinning

Effort and model are two separate dials, and the cheapest quality-per-token setup turns both. Two mechanisms exist:

• CLAUDE_CODE_SUBAGENT_MODEL pins the model for all subagents, or per-agent model frontmatter pins one agent. A scout on Haiku at low effort is the cheapest reader you can field; the docs note that available effort levels depend on the model, so check what your chosen model supports.
• Since v2.1.296, CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL runs every workflow agent on one model while other subagents keep theirs, per the release notes. If you run Claude Code’s dynamic workflows, this is how you keep the workflow fleet on a cost-effective model while your hand-defined scout and reviewer agents follow their own frontmatter.

A common starting lineup: scouts on a fast model at low, the reviewer on the session’s model at high, and the final sign-off on the main agent at your normal effort. Keep max out of automated setups; it is the level for the rare step where you want the deepest reasoning and are willing to pay for it.

Step 5: Measure with /usage and adjust

After a run, type /usage and compare with a similar run at a uniform effort. Check three things. First, whether the scouts’ coverage matches a quick grep for the obvious pattern, because a low-effort agent can skim past a call site hidden behind a wrapper. Second, whether the reviewer’s flagged items survive when you read the underlying code yourself. Third, the total token bill, because more subagents means more context overhead no matter what effort they run at.

If the bill went up, the usual culprit is verbose scouts, not the effort levels. Tighten the output contract first, cut the scout count second, and only then touch effort.

Troubleshooting

The subagent ignores the effort I asked for

This has two documented causes. The boring one is the version: anything before 2.1.292 has no per-agent effort, and subagents inherit the session level. Run claude --version first. The subtle one is the environment: if CLAUDE_CODE_EFFORT_LEVEL is exported in your shell, it overrides both the session setting and every subagent’s frontmatter effort, per the official docs. Check with:

echo $CLAUDE_CODE_EFFORT_LEVEL

Unset it (or remove it from your shell profile) and the per-agent levels start applying again. This is also why a team that pins effort in shared agent files should audit everyone’s shell exports, not just the repo.

A low-effort scout missed a real call site

This is the known failure mode of the pattern, and the fix is procedural, not a bigger model. Make the scouting step produce evidence instead of conclusions: file, line, and the matching text for every hit. Then spot-check coverage with an independent method, usually a plain grep or rg for the client library name, and compare counts. If the miss rate is real on your codebase, raise the scouts to medium for that phase. The rule of thumb from the community: low for pattern matching on well-named code, medium for anything where a wrapper or indirection could hide the target. Never paper over missed coverage by spawning more low-effort scouts; that spends tokens without fixing recall.

The run cost more than a uniform-effort run

Expect this on your first attempt. Each subagent builds its own context, and if ten scouts each return a page of prose, the high-effort reviewer pays full price to read it all. The fix order is: tighten scout output to flat lists, reduce the scout count by widening each scout’s scope, and keep the expensive review step to a single agent unless the work genuinely splits. Also watch for a second trap: a confident wrong summary from a cheap scout that the reviewer accepts without checking. The reviewer prompt above guards against it by requiring the reviewer to read the flagged code itself. Saving tokens on a step that later needs a redo is the most expensive mistake in this whole setup.

Everything feels slow because the session is on max

This is the pre-2.1.292 habit surviving into the new world. Running the whole session at max makes every spawned scout run at max too, which is exactly what per-agent effort replaces. Drop the session back to your normal level and put the hard work in the agents that need it. If a run needs deep reasoning only in one phase, one high-effort reviewer is almost always cheaper than a max session with five max scouts.

FAQ

The six questions above cover the essentials: which levels subagents accept, whether low effort always costs less, the precedence chain, mixing models with effort, whether plain language is the only syntax, and when to skip the pattern entirely.

Conclusion

Per-subagent effort levels turn Claude Code’s multi-agent runs from a single dial into a small control panel. The pattern is simple enough to state in one line: low-effort scouts for breadth, a high-effort reviewer for judgment, with the output format doing most of the cost control. Pin the convention in subagent frontmatter once it works, audit CLAUDE_CODE_EFFORT_LEVEL when it seems not to, and measure every change in /usage. As a next step, the same scout-and-reviewer discipline ports naturally to Claude Code mods, which let you intercept tool calls and approve permission requests, and to n8n workflows exposed as MCP tools in Claude Code, where the same effort thinking applies to agent-driven pipelines. If you want the managed-platform version of this idea, see Claude dynamic workflows.

Frequently asked questions