Claude Code can now set effort per sub-agent. Spend it where the work is hard

Until this week, a Claude Code sub-agent’s thinking depth was set in two places: the session’s effort level, or an effort line in the agent’s frontmatter. Version 2.1.292, released October 6, adds a third. According to the release notes , the Agent tool now takes an effort parameter, “so Claude runs a sub-agent at the effort level you ask for.”

That means the choice can be made per delegation, in the prompt, instead of per agent definition.

Why split effort at all

Effort controls how much the model reasons on each step. Anthropic’s model configuration docs say higher levels cost more tokens and take longer but test more edge cases and verify more of their work. Lower levels get you a starting point sooner.

Most delegated work doesn’t need the same depth as the thing delegating. A sub-agent that greps for every caller of a function is doing retrieval. A sub-agent that decides whether a locking change is safe is doing the hard part. Running both at one level means overpaying for the first or under-thinking the second.

The docs’ own guidance maps neatly onto this. low is for quick exchanges you review step by step. high is for work where verification matters or edge cases are likely, such as bug fixes in an existing codebase. max is for hard problems you want worked through autonomously, though the docs warn it may show diminishing returns and tends to overthink.

How to ask for it

The parameter belongs to the tool call, so you set it by telling Claude what you want. A prompt along these lines works:

Use one sub-agent at low effort to list every caller of
PaymentClient.refund() with file and line. Then use a second
sub-agent at high effort to review the retry logic in
payments/refund.py for double-refund bugs. Report both separately.

Claude decides how to fill in the call from that. You don’t write the parameter yourself.

If a role is always the same, keep using frontmatter instead. The sub-agent docs define effort there with the values low, medium, high, xhigh and max:

---
name: security-reviewer
description: Reviews code changes for security issues
model: opus
effort: high
---

Per-call effort is for the cases frontmatter can’t cover: the same general-purpose helper used once for a lookup and once for a judgment call.

What the docs don’t say

Two things are unconfirmed, so test them before you rely on them.

First, precedence. The docs say frontmatter effort overrides the session level but not the CLAUDE_CODE_EFFORT_LEVEL environment variable. They don’t say how a per-call value ranks against frontmatter, and the release note is one line. If you’ve exported that variable, assume it may win and check.

Second, model limits. Levels depend on the model. If you ask for one the active model doesn’t support, Claude Code uses the highest supported level at or below it, so xhigh becomes high on Opus 4.6 and Sonnet 4.6. You won’t get an error, just less than you asked for.

To see what a running sub-agent actually got, open /tasks. Per the docs it shows the effort level on the agent’s row when the definition, or the skill it forked from, sets one. I haven’t confirmed that a per-call value shows up there too.

Where low effort bites

Low is cheaper because it checks less. Anthropic’s Haiku 5.5 prompting guide says that at low effort the model is more likely to stop early or skip checks. That is a fine trade for a read-only search and a bad one for anything that edits files.

So the rule is simple. Low for sub-agents that find and report. High for the ones that change code or judge it. Leave max for the one problem per week that earned it.

Opus 5.5, Sonnet 5.5 and Haiku 5.5 already default to medium, so dropping a search helper to low saves less than it would on a model that defaults to high. The bigger win is raising the one reviewer that matters.