Follow Discord
Sweep 22 Oct 2026 · 21:04Z Build v2.1.309 528 read Stable v2.1.308 Latest v2.1.308 Next v2.1.309 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI 3 Sep 2026
One change · claude-code

Create custom subagents changedsub-agents

Nearest release: v2.1.259, published 6 hours before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here
Lines+31added
Lines−6removed
From line 32 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits91to this page, all time

#### Run every subagent on one model

The whole hunk

from line 32, old and new numbered
/
lines
from line 32
3232 <Tab title="Explore">
3333 A fast, read-only agent optimized for searching and analyzing codebases.
3434 
35 * **Model**: inherits from the main conversation, capped at Opus on the Claude API, so Explore never runs on a more expensive model than the one you already chose for the session, unless you [force `CLAUDE_CODE_SUBAGENT_MODEL` onto it](#choose-a-model)
35 * **Model**: inherits from the main conversation, capped at Opus on the Claude API, so Explore never runs on a more expensive model than the one you already chose for the session, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
3636 * **Tools**: read-only tools; Write and Edit are denied
3737 * **Purpose**: file discovery, code search, codebase exploration
3838 
from line 48
4848 <Tab title="Plan">
4949 A research agent used during [plan mode](/docs/en/permission-modes#analyze-before-you-edit-with-plan-mode) to gather context before presenting a plan.
5050 
51 * **Model**: inherits from the main conversation, unless you [force `CLAUDE_CODE_SUBAGENT_MODEL` onto it](#choose-a-model)
51 * **Model**: inherits from the main conversation, unless you set `CLAUDE_CODE_SUBAGENT_MODEL` and [force it onto every subagent](#run-every-subagent-on-one-model)
5252 * **Tools**: read-only tools; Write and Edit are denied
5353 * **Purpose**: codebase research for planning
5454 
from line 58
5858 <Tab title="General-purpose">
5959 A capable agent for complex, multi-step tasks that require both exploration and action.
6060 
61 * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order and how to force the variable onto subagents
61 * **Model**: the [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) model if you set one and nothing assigns a model another way, otherwise the main conversation's model; [Choose a model](#choose-a-model) states the full order, and [Run every subagent on one model](#run-every-subagent-on-one-model) shows how to make the variable override those sources
6262 * **Tools**: every tool [available to subagents](#available-tools)
6363 * **Purpose**: complex research, multi-step operations, code modifications
6464 
from line 347
3473473. The [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables) environment variable, when you set it to a model alias or model ID
3483484. The main conversation's model
349349 
350Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself doesn't change the model the built-in Explore and Plan subagents run on.
350Setting `CLAUDE_CODE_SUBAGENT_MODEL` by itself doesn't change the model the built-in Explore and Plan subagents run on. To change it, see [Run every subagent on one model](#run-every-subagent-on-one-model).
351351 
352352Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order and overrode both the per-invocation parameter and the frontmatter, including `model: inherit`.
353353 
354354Setting the variable to `inherit` is the same as leaving it unset. Before v2.1.196, that value forced subagents onto the main conversation's model and ignored the other sources.
355355 
356Set [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/en/env-vars) to run subagents, [teammates](/docs/en/agent-teams#specify-teammates-and-models), and [workflow agents](/docs/en/workflows) on `CLAUDE_CODE_SUBAGENT_MODEL` whatever model their definition or invocation names, the built-in Explore and Plan definitions included. A [fork](#fork-the-current-conversation), and a [skill that runs in a subagent](/docs/en/skills#run-skills-in-a-subagent) with `model: inherit`, still run on the main conversation's model. When you haven't set `CLAUDE_CODE_SUBAGENT_MODEL`, subagents, teammates, and workflow agents run on the main conversation's model, and the built-in Explore subagent keeps its [model cap](#built-in-subagents). Requires Claude Code v2.1.257 or later.
357 
358356Claude Code checks the per-invocation parameter, frontmatter, and environment variable values against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. For a blocked value, it substitutes another model:
359357 
360358* When the blocked value is a family alias such as `opus`, Claude Code runs the subagent on the newest version of that family the allowlist permits, following the same [substitution rules and provider scope](/docs/en/model-config#restrict-model-selection) as `/model`. Before v2.1.222, Claude Code ran the subagent on the inherited model for a blocked family alias as well.
from line 365
367365A per-invocation `model` parameter also applies when the subagent is [resumed or sent a follow-up message](#resume-subagents), so the subagent stays on that model. Before v2.1.211, resuming dropped the per-invocation value and the subagent reverted to its definition's `model` field or, without one, the main conversation's model.
368366 
369367As of v2.1.198, subagents also inherit the main conversation's [extended thinking](/docs/en/model-config#extended-thinking) configuration: if thinking is on in your session, it's on for the subagent, and if it's off, it stays off. There is no per-subagent thinking setting. Before v2.1.198, subagents ran with extended thinking disabled regardless of the main conversation's setting.
368 
369#### Run every subagent on one model
370 
371`CLAUDE_CODE_SUBAGENT_MODEL` is a default, so a subagent's definition or a model Claude passes still takes precedence over it. To apply one model to every subagent, [teammate](/docs/en/agent-teams#specify-teammates-and-models), and [workflow agent](/docs/en/workflows), also set `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` to `1`. Requires Claude Code v2.1.257 or later.
372 
373* If you set both variables, subagents run on the model in `CLAUDE_CODE_SUBAGENT_MODEL`.
374* If you set only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, subagents run on the main conversation's model.
375 
376For example, to run every subagent on Haiku, set both variables in the `env` block of a [settings file](/docs/en/settings):
377 
378```json theme={null}
379{
380 "env": {
381 "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
382 "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
383 }
384}
385```
386 
387To check that the setting took effect, run [`/tasks`](/docs/en/commands) while a subagent is running. The subagent's row shows the model it runs on.
388 
389While `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is [on](/docs/en/env-vars), Claude Code ignores the `model` field of every subagent definition, including the built-in Explore and Plan subagents, and Claude can't pass a model when it starts a subagent. Two kinds of subagent still run on the main conversation's model:
390 
391* A [fork](#fork-the-current-conversation)
392* A [skill that runs in a subagent](/docs/en/skills#run-skills-in-a-subagent) with `model: inherit`
393 
394When you set only `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, the built-in Explore subagent keeps its [model cap](#built-in-subagents).
370395 
371396### Control subagent capabilities
372397 
Feedback