Claude Code Subagent Effort & ultrathink: Tuning Cost vs Quality

Short version: since Claude Code 2.1.316 (31 October 2026), subagents no longer have to copy whatever effort level your main session runs at. A new environment variable, CLAUDE_CODE_SUBAGENT_EFFORT, sets a default level for every subagent that nothing else configures. Combine it with the per-agent effort field and the one-turn ultrathink keyword, and you can run cheap, fast scouts and expensive, careful reviewers inside the same session.

This guide walks through every effort control Claude Code has for subagents, the order in which they win, and a working setup that spends tokens only where extra thinking actually pays off. If you want the cross-vendor picture first, our explainer on Gemini thinking levels vs Claude effort covers how the two reasoning dials differ.

What You'll Have at the End

• A clear mental model of what effort changes, so you stop raising it for problems it can't fix.
• A default subagent level set once with CLAUDE_CODE_SUBAGENT_EFFORT, instead of every helper inheriting your session's level.
• Two or three custom subagents with their own effort field: a low-effort explorer, a medium implementer and a high or xhigh verifier.
• A habit for ultrathink: one deep turn when you need it, without changing anything permanent.
• A way to check, with /tasks, what each subagent is actually running at.

What Effort Actually Controls in Claude Code

Effort is not just "thinking time". Anthropic's guide on choosing a Claude model and effort level describes it as how much work Claude does on a request overall: how many files it reads, how many tools it calls and how many steps it takes before checking back with you. Thinking, tool calls and the text you read are all ordinary output tokens from the same loop, billed at the same rate.

That matters for subagents because each subagent is its own loop. A research helper that reads 40 files at high when low would have found the answer in five is pure waste, multiplied by however many helpers you spawn. The same guide offers a simple diagnostic:

• Raise effort when Claude got it wrong by skipping a file, not running the tests or not double-checking its work.
• Switch to a bigger model when Claude had the right context, clearly tried, and still got it wrong.

Honest answer: most "Claude is being lazy" complaints in subagents are the first case, and most "Claude is confidently wrong" complaints are the second. Effort fixes thoroughness, not knowledge.

The levels and what each one is for

Per the Claude Code model configuration docs, current Fable, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8 and Opus 4.7 models accept low, medium, high, xhigh and max. Opus 4.6 and Sonnet 4.6 skip xhigh. If you name a level a model doesn't support, Claude Code drops to the highest supported level below it.

One detail people miss: the effort scale is calibrated per model, so high on Haiku 5.5 is not the same amount of work as high on Opus 5.5. Pick levels per agent and model, not as one global number.

Where the Evidence Says Extra Effort Pays Off

The most useful data point comes from Anthropic's own write-up, Using Claude Code: Spending your effort. Looking at Terminal-Bench 3.0 runs, the author's main takeaway is that higher effort helps most on tasks with lots of hidden edge cases. It reduces failures from missed edge cases, but it does not rescue a model that picked the wrong approach.

The post breaks Fable 5.1's pass rate down by task category, pooling the lowest settings against the highest:

Read that chart as a routing table for subagents. Security and hardware-style work, where one missed case breaks everything, gains 20 to 40 points. General software work gains 13. So a security reviewer subagent deserves xhigh; a helper that lists which files import a module does not.

The same post describes a feature loop that maps neatly onto subagents: have Claude interview you about the spec, implement on low effort while you review and steer, then run verification on high effort. That last step is exactly what a dedicated verifier subagent is for. We cover how to split work across agents in more depth in our guide to multi-agent workflows with Claude Code.

The Four Ways to Set a Subagent's Effort

Claude Code now gives you four subagent-specific controls, plus the session settings they fall back to. Here is each one, then the order they win in.

1. The effort field in a subagent definition

Every custom subagent is a Markdown file with YAML frontmatter, in .claude/agents/ for a project or ~/.claude/agents/ for your user. The subagents docs list effort as an optional field that takes low, medium, high, xhigh or max. It overrides the session level while that subagent runs.

---
name: security-reviewer
description: Reviews a diff for injection, auth and secrets issues. Use after any change touching auth, input parsing or SQL.
model: opus
effort: xhigh
tools: Read, Grep, Glob, Bash
---
You review diffs for security problems. Reproduce each suspected issue
with a concrete input before reporting it. Report findings as:
severity, file:line, the input that triggers it, and the fix.

This is the control to reach for first. It travels with the agent, it's in version control, and anyone on the team who uses the agent gets the same behaviour.

2. A per-invocation effort parameter

Since Claude Code v2.1.292, when you ask Claude to run a non-fork subagent at a specific level ("run the test-writer at high effort on this module"), it can pass an effort parameter on that one Agent tool call. That parameter beats the agent's own field and sticks if the subagent is resumed. Use it for the one-off: a normally cheap explorer that needs to dig harder this time.

3. CLAUDE_CODE_SUBAGENT_EFFORT, the new default

This is the 31 October addition. The 2.1.316 changelog describes it as setting "the effort level subagents run at when nothing else names one, instead of inheriting the session's". Before it existed, a subagent with no effort field simply ran at whatever you had picked with /effort or --effort. Push your main session to xhigh for a hard design discussion, and every throwaway search helper spawned in that session ran at xhigh too.

Set it once in the env block of your settings file:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_EFFORT": "low"
  }
}

Or export it in your shell before launching: export CLAUDE_CODE_SUBAGENT_EFFORT=medium. Agents with their own effort field, and invocations that pass one, keep their level. Everything else uses yours.

Pro tip: As of today the variable is documented only in the changelog; the environment variables reference page doesn't list it yet. Check that it took effect with /tasks (below) rather than assuming, and confirm you're on 2.1.316 or later with claude --version.

4. CLAUDE_CODE_EFFORT_LEVEL, the override that flattens everything

This older variable sets the session's level and, per the docs, takes precedence over the subagent effort field and the per-invocation parameter. If you have it exported in your shell profile, your carefully tuned agents all run at that one level. It's the most common reason a "high-effort reviewer" behaves like a low-effort one.

Which Setting Wins: The Resolution Order

Putting the docs and the changelog together, a subagent's effort resolves roughly like this, first match wins:

1. CLAUDE_CODE_EFFORT_LEVEL, if set (it overrides the agent field and the per-call parameter).
2. The per-invocation effort parameter Claude passes when spawning the subagent.
3. The effort field in the subagent's definition.
4. CLAUDE_CODE_SUBAGENT_EFFORT, the new default for agents nothing else configures.
5. Without it: the session level from /effort or --effort, but only when the subagent runs on the main conversation's model. On a different model, that level doesn't carry over and the subagent's own model default applies.

Two caps sit on top of all of this. Your own maxEffortLevel setting and any organisation effort limit still bound what a subagent can run at, so an effort: max agent under an xhigh cap runs at xhigh.

Point 5 surprises people. If your session runs Opus 5.5 at high and a subagent is defined with model: haiku and no effort, it does not get high. The docs say the session level doesn't apply on another model, so it runs at Haiku's own level instead (Haiku 5.5 defaults to medium). Set effort in the definition and you never have to guess. Model choice and effort choice interact, which is why our post on choosing thinking level and effort for real workloads treats them as one decision.

Model selection has its own parallel order (per-invocation model, then the frontmatter model, then CLAUDE_CODE_SUBAGENT_MODEL, then the main model), and you can force one model everywhere with CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. There is no documented "force" switch for effort apart from CLAUDE_CODE_EFFORT_LEVEL itself.

Where ultrathink Fits

ultrathink is the keyword you type into a prompt to get deeper reasoning on that turn without changing your saved effort. Claude Code recognises it and adds an in-context instruction. Since v2.1.311, typed in the terminal on Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.1 through Anthropic's API, it also raises that turn to xhigh, and the word turns rainbow-coloured when it can. Since 2.1.316 the VS Code extension behaves the same way.

A few rules from the docs worth knowing:

• Only ultrathink is a keyword. "think", "think hard" and "think more" are passed through as plain prompt text.
• It won't fire inside quotes, brackets, a file path, a command, or a prompt that starts with /.
• If CLAUDE_CODE_EFFORT_LEVEL is set below xhigh, or a cap sits below it, the word can't raise the turn.
• On Amazon Bedrock and some other providers the word can't raise effort; set the level directly instead.
• New in 2.1.316: CLAUDE_CODE_DISABLE_ULTRATHINK turns the keyword off, useful on shared machines or where an org wants predictable spend.

My take: treat ultrathink as a main-thread tool. The docs describe it raising the turn you type it in, and they don't say it changes the level of subagents spawned during that turn. If a delegated task needs more depth, ask for it explicitly ("spawn the reviewer at max effort"), which uses the documented per-invocation parameter.

A Cost-Aware Setup in Six Steps

Here's the configuration we'd start from for a typical repository. Adjust the levels after a week of watching /tasks, not before.

Step 1: Update and check your baseline

Run claude --version and update if you're below 2.1.316. Then run /effort status to see the level your main session sends. If your shell exports CLAUDE_CODE_EFFORT_LEVEL, decide now whether you really want it, because it overrides every subagent setting below.

Step 2: Set a cheap subagent default

If you are still deciding which jobs deserve their own agent, our guide to Claude skills vs MCP tools vs subagents helps you draw that line. Add "CLAUDE_CODE_SUBAGENT_EFFORT": "low" to the env block of ~/.claude/settings.json. Most ad-hoc helpers do searching and summarising, which low handles well. If you find helpers skipping files they should have read, step it up to medium.

Step 3: Give exploration a cheaper model too

The built-in Explore subagent runs on your main conversation's model (on a Claude subscription, an Opus model when your main session runs Fable). The subagents docs suggest defining your own user or project subagent named Explore with model: haiku; it overrides the built-in and keeps its own model.

---
name: Explore
description: Fast read-only codebase search. Finds files, symbols and call sites and reports paths with one-line summaries.
model: haiku
effort: low
tools: Read, Grep, Glob
---
Search the codebase and report what you found as a list of
path:line with a one-line note each. Don't propose changes.

Step 4: Create a medium-effort implementer

For scoped edits that follow a plan you've already agreed, medium on Sonnet 5.5 is the sweet spot Anthropic's own table points to: day-to-day engineering with a clear scope.

---
name: implementer
description: Implements one well-specified change from an agreed plan. Use for edits, not design decisions.
model: sonnet
effort: medium
---
Implement exactly the change described. Run the relevant tests.
If the plan is ambiguous, stop and list your questions instead of guessing.

Step 5: Create a high-effort verifier

This is where the extra tokens earn their keep. Edge-case hunting is what higher effort measurably improves.

---
name: verifier
description: Verifies a finished change. Use after implementation, before commit.
model: opus
effort: xhigh
tools: Read, Grep, Glob, Bash
---
Assume the change has a bug until you've shown otherwise.
1. Reproduce the original problem or requirement.
2. Run the full test suite and any linters.
3. Write at least three adversarial test cases the author likely missed.
4. Report: what you ran, what failed, and whether the change is safe to merge.

Step 6: Check what actually ran

While a subagent is working, run /tasks. Since v2.1.242, each subagent's row names the model it runs on and the effort level set for it, if any. This is the only reliable way to catch an exported CLAUDE_CODE_EFFORT_LEVEL or an org cap quietly overriding your frontmatter.

What It Costs: Model Price Times Effort

Effort doesn't change the per-token price; it changes how many tokens a task burns. Model choice changes the price per token. Your bill is both multiplied together. Here are the current list prices from Anthropic's API pricing page, which apply if you run Claude Code on an API key:

Because thinking tokens bill as output, effort mostly moves the expensive column. Anthropic's model-and-effort guide illustrates one prompt where the high-effort path generated roughly 7x more tokens than the low-effort path; it's an illustration, not a benchmark, but the direction is the point. On a subscription the same logic applies to your usage limits rather than dollars. If you're deciding between plans, our comparison of Claude Ultra vs Max vs Pro covers how limits differ, and Claude Code API pricing and rate limits covers the pay-as-you-go side.

A rough rule of thumb: an exploration helper on Haiku at low costs a rounding error; a verifier on Opus at xhigh is the most expensive thing in the session, so you want exactly one of it, running once, at the end.

Common Mistakes and How to Spot Them

An exported CLAUDE_CODE_EFFORT_LEVEL overriding everything

If every row in /tasks shows the same level regardless of frontmatter, check echo $CLAUDE_CODE_EFFORT_LEVEL. Remove it from your shell profile and use /effort or settings for the session instead.

Raising effort to fix missing context

Anthropic's guide is blunt about this: if you're raising effort on a task that shouldn't need it, the fix is usually upstream, in your prompt, your CLAUDE.md or how the task is scoped. A subagent that keeps missing your conventions needs a better system prompt, not max. Our context engineering patterns for Claude Code are the better lever there. Remember too that the built-in Explore and Plan subagents start without your CLAUDE.md files.

Using max everywhere

The docs warn that max may show diminishing returns and is prone to overthinking. It also only persists across sessions when set through CLAUDE_CODE_EFFORT_LEVEL; picked in-session, it applies to that session only. Reserve it for narrow, high-stakes reviews.

Assuming a level means the same thing on every model

Levels are calibrated per model. When Anthropic moved Opus 5.5's default to medium, it noted that Opus 5.5 at medium matched or beat Opus 5 at high on its coding and knowledge-work evaluations. If you migrated agents from Opus 5 or 4.8, start them at the new default rather than carrying old levels over; our Opus 4.8 to Opus 5.5 migration guide covers the rest of that move before fast mode on Opus 4.8 is removed on 30 November.

Forgetting that research subagents need good inputs

A low-effort research helper is only as good as what it can fetch. For agents that pull docs or web pages, a structured scraping tool usually helps more than extra effort; see our list of the best MCP servers for Claude Code.

When You Shouldn't Bother

If you rarely use subagents, or your session already runs at the model's default, you can skip all of this. Anthropic's own advice is to use default effort for most tasks and treat effort as a general preference rather than a per-task decision. The new variable earns its place when you regularly raise your main session above default and spawn many helpers, or when you run long autonomous sessions where helper volume dominates the bill. Before adding more agents, ask whether the job needs a separate loop at all.

Verdict

My take: CLAUDE_CODE_SUBAGENT_EFFORT is a small change with an outsized effect on long sessions. Set it to low or medium, give your two or three important agents an explicit effort field, keep ultrathink for single hard turns in the main thread, and keep CLAUDE_CODE_EFFORT_LEVEL unset unless you truly want one level everywhere. Then let /tasks tell you whether reality matches the plan. Spend effort where edge cases live, in review, security and verification, and save it everywhere else.

Keep Reading

• Gemini Thinking Levels vs Claude Effort: How Reasoning Controls Differ
• Claude Code vs Google Antigravity: Which Coding Agent Wins?
• How to Use Claude Code for Free