Blog · 2026-11-06

Claude Code subagents and effort: half of repos with project subagents pin a model and set no effort level

Since 2.1.317, a subagent on another model no longer runs at your session's effort level. We read 10,413 subagent files in 1,346 public repos: 82% of the ones that pin a model set no effort. Precedence tested on 2.1.314.

Summary

If a Claude Code subagent names its own model, give it an effort line too.

The reason is simple. Since version 2.1.317 (November 3), a subagent that runs on a different model from your conversation no longer follows the effort level you pick with /effort. It uses that model’s saved level, or the model’s default if you never saved one. So you can raise the session to high and your model: opus reviewer still runs at whatever Opus defaults to.

How many subagents are written that way? We read the subagent files in 5,864 active public repos. 1,346 repos have at least one. 82% of the subagent files that pin a model set no effort, and half of the repos with subagents have at least one like that.

Effort for subagents changed five times in a month:

Version	Date	Change
2.1.292	Oct 6	The Agent tool takes an `effort` parameter, so Claude can run one subagent at a level you ask for
2.1.296	Oct 9	`autoCompactWindow` in subagent frontmatter, so a subagent can compact earlier than the main conversation
2.1.312	Oct 27	A subagent’s `autoCompactWindow` can now lower the window set by `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, where before it had no effect
2.1.316	Oct 31	`CLAUDE_CODE_SUBAGENT_EFFORT` sets the level for subagents when nothing else names one
2.1.317	Nov 3	A subagent on a different model uses that model’s saved level or default, not the session’s

How we tested

The precedence. In an empty project we defined a subagent that runs one Bash command, plus a PreToolUse hook that records the effort field Claude Code passes to hooks. We ran claude -p --model haiku --effort low on Claude Code 2.1.314 and asked Claude to start the subagent. Four cases:
- Subagent sets effort: high: it ran at high.
- Same, with CLAUDE_CODE_EFFORT_LEVEL=medium in the environment: it ran at medium.
- Subagent sets no effort and inherits the model: it ran at low, the session’s level.
- Subagent sets model: sonnet and no effort: it ran at low. That is the behaviour 2.1.317 changed. We did not test 2.1.316 or later, so the newer rules below come from the changelog and the docs.
The repos. The same sample as our hooks and project settings reviews: 5,864 public repos with at least 5 stars, pushed to since October 7, not forks, as of November 6, 2026. We downloaded every .claude/agents/*.md at the commit we sampled, 10,413 files in 1,346 repos (23.0%), and read their frontmatter as YAML. 9,317 files had frontmatter our parser could read.
Files that never load. The docs list frontmatter problems that make Claude Code skip a subagent file without telling you. We checked each rule, and for YAML errors we ran claude plugin validate on the files our own parser rejected, because Claude Code’s parser is more lenient: it flagged 30 of 470.

Results

What a subagent’s effort level comes from

From the docs, highest first:

CLAUDE_CODE_EFFORT_LEVEL in the environment
The effort Claude passes when it starts that subagent
The effort field in the subagent’s frontmatter
With none of these: on the main conversation’s model, your session level; on another model, that model’s saved level or its default

CLAUDE_CODE_SUBAGENT_EFFORT from 2.1.316 sets the level when nothing else names one. It is in the changelog but not yet in the environment variable reference, so where it sits against rule 4 on another model is undocumented.

What 9,317 subagent files set

Field	Files
`model` set	57.5% (sonnet 24.9%, opus 14.3%, inherit 6.7%, haiku 5.2%, a full model ID 4.7%, fable 1.2%)
`effort` set	10.3% (high 4.3%, medium 3.6%, low 1.2%, xhigh 0.8%, max 0.2%)
`tools` set	63.9%; the rest get every tool available to subagents
`autoCompactWindow` set	3 files, in 1 repo

Quick guess: of the 4,736 files that name a specific model, how many say how hard it should think? 846. The other 3,890, 82.1%, set no effort. Since 2.1.317, whenever your session runs a different model family, they run at the named model’s own level. A model: opus subagent in an Opus session still follows your level, because the alias resolves to your exact model.

By repo (of 1,346 with subagents)

	Repos
At least one subagent pins a model	781 (58.0%)
At least one pins a model and sets no effort	682 (50.7%)
At least one sets effort	165 (12.3%)
At least one has no `tools` list	417 (31.0%)
At least one subagent file Claude Code skips without saying so	55 (4.1%)

Files that never load

196 files, 1.9%, have one of the problems the docs list: no name (77), a name but no description (64), YAML that Claude Code can’t parse (30), an opening --- that isn’t on the first line (15), or an invalid name (10). Another 611 have no frontmatter at all, which Claude Code treats as documentation; most of those look like READMEs and notes.

Our picks

What we now do with each subagent definition:

Pair model with effort. A reviewer on opus gets effort: high, a fast searcher on haiku gets effort: low. Then the level doesn’t depend on which model your session happens to use.
Leave both out when the subagent should just follow you. With no model and no effort, it runs on your model at your level, unless Claude passes a model when it starts the subagent or you set CLAUDE_CODE_SUBAGENT_MODEL.
Check with /tasks. While a subagent runs, its row shows the model and the effort level set for it.
Use CLAUDE_CODE_EFFORT_LEVEL only when you want one level everywhere. It overrides every subagent’s own setting, including the per-call parameter.
Run claude plugin validate .claude/agents. It finds frontmatter that doesn’t parse. Check for a name and a description yourself, since validate doesn’t flag a missing name.

Which of your subagents names a model, and what level does it run at today?

What to ignore

autoCompactWindow for now. Three files in our sample use it, and the docs and the changelog disagree about how it combines with CLAUDE_CODE_AUTO_COMPACT_WINDOW: the subagents page says the variable wins, while 2.1.312 says the field can now lower it. If you set it, write a plain integer such as 200000. The docs warn that 200k in frontmatter is read as 200 and ignored.

Extra keys. color, type, priority, version and similar fields appear in many files. Claude Code reads only the fields it supports, so they are harmless.

Limitations

Old version for the live test. We tested on 2.1.314. The rules from 2.1.316 and 2.1.317 come from the changelog and the docs, not from our runs.
Haiku for the session. The level a model accepts depends on the model, and a Haiku session may not show every level.
Static reading of files. We counted what frontmatter says. We did not run the repos’ subagents.
A sample. Active repos with 5 or more stars, as of November 6, 2026, chosen by code search relevance. It is not a random sample.

Reproduce it

The counts are in subagent-effort-2026-11.json, with repo names and file contents left out. To check your own subagents, run /tasks while one is working, or open .claude/agents/ and look for a model line without an effort line.

For the hooks in the same repos, see Claude Code hooks let the call through when they fail.