Subagent Runtime
Claude Code ships a few built-in agents, and a set of rules limits every subagent. The rules cover tool filters, forks, background runs, depth limits, and agent teams. For example, a subagent cannot start another one past the depth limit, which is 3 by default. A fork is a subagent that inherits the whole conversation and shares the prompt cache with its parent.
Your own agent file replaces a built-in one of the same name. Limits come from env vars and settings. The switches are CLAUDE_CODE_FORK_SUBAGENT, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS, and CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS.
Example
Limit nesting to one level. Run every subagent in the foreground.
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
claude
Built-In Agents
The program lists 14 names. Six are in the docs. The rest are internal or are not agents.
| Agent | Status | What it does | Notes |
|---|---|---|---|
Explore | Documented: An official docs page names this item. | A fast read-only search agent. | Uses the main model, with omit and no git status. Denies Agent, Edit, Write, Notebook, and two more internal tools. A user agent named Explore overrides it. CLAUDE_ removes it (2.1.198). |
Plan | Documented: An official docs page names this item. | A research agent for plan mode. | Model inherit. The same disallowed as Explore. omit is true. |
general- | Documented: An official docs page names this item. | A capable agent for multi-step work. | tools:. Model: CLAUDE_ or the main model. The default when you omit subagent_. CLAUDE_ removes it in -. |
claude | Documented: An official docs page names this item. | A catch-all agent with every tool. | tools:, append true, no model of its own. Also the default agent for a dispatched background session. |
statusline- | Documented: An official docs page names this item. | Configures the status line for /. | Tools Read and Edit. Model sonnet. Color orange. Interactive. |
claude- | Documented: An official docs page names this item. | Answers questions about Claude Code. | Model haiku (checked: the interactive screen sent claude-). Mode dont. Tools Bash, Read, Web, Web. The prompt also lists your custom skills, agents, MCP servers, plugin skills, and the names of your settings keys. Claude Code leaves it out when CLAUDE_ is sdk-, sdk-, or sdk- (a - run reports sdk-). So it exists only in the interactive CLI. Prompt text: Subagent, Claude Code Guide. |
fork | Documented: An official docs page names this item. | A fork of the main conversation. | Inherits the system prompt, tools, model, and history. Cannot start a fork. At the depth limit it keeps Agent, but the tool returns an error. Needs fork mode. Since 2., forks started together are each told which launch is their own, so they are less likely to start each other's work (release notes). In the interactive screen the Agent tool accepted fork (Fork started) with no extra setting in the probe run; the switch was not looked for. |
workflow- | Undocumented: Only the program shows this item. It can change without notice. | The agent that Workflow scripts use. | Workflow scripts start their agents with this type. The model is CLAUDE_ if set (and not inherit), then CLAUDE_, then the main model. Both win over a model option in agent(). The prompt tells the agent that its final text goes back to the script as a string. You cannot start it with the Agent tool, in - or in the interactive screen (Agent type 'workflow-). Source: the program and Probes. |
comment- | Undocumented: Only the program shows this item. It can change without notice. | Analyzes artifact comment threads. | One tool. Model inherit. max 6. omit true. Only the artifact comment pipeline starts it (the definition says it is not for direct spawning). It is not in the agent list in any entry point. |
web- | Undocumented: Only the program shows this item. It can change without notice. Gated: Works only behind a flag or a server gate. CLAUDE_CODE_WEB_FETCH_AGENT | Fetches URLs for a caller. | Prompt "web-reading specialist". max 15. Color blue. omit true. Model haiku or inherit, by a flag (a probe run inherited the main model). The agent exists only when CLAUDE_ is on (or its server flag). With default settings the interactive screen also answers Agent type 'web-. Then the main session loses its own Web tool and calls this agent instead. The agent has only Web. It is off when you set CLAUDE_ or CLAUDE_. Source: the program and Probes. |
note
In -p and the SDK entry points the spawnable built-in types are claude, Explore, general-purpose, Plan, and statusline-setup, plus web-fetch when it is on. In the interactive screen with default settings the list is claude, claude-code-guide, Explore, general-purpose, Plan, and statusline-setup, plus fork. comment-thread-analyst and workflow-subagent are not spawnable with Agent in either place (Agent type '...' not found). The artifact comment pipeline starts comment-thread-analyst, and Workflow scripts start workflow-subagent.
The names worker, renewal, killed, decorations, and main-session also appear in the program. They are not spawnable agent types as far as anyone read.
See Probes.
Tools and Context of a Subagent
| Rule | Status | What it does | Notes |
|---|---|---|---|
| First filter | Documented: An official docs page names this item. | Removes tools from every subagent. | Removed: Agent at the depth limit (not for a fork), Ask, End, Enter, Exit (kept in plan mode), Schedule, Wait, Workflow. Forks skip both filters. |
| Second filter | Documented: An official docs page names this item. | The built-in tools that a background subagent keeps. | File and search tools, shell tools, web tools, Todo, Skill, Tool, the worktree tools, Monitor, Task, Send, Artifact, Subagent, and every MCP tool. |
| Foreground or background | Documented: An official docs page names this item. | How Claude Code places a start. | A teammate start and CLAUDE_ run in the foreground. Fork mode and background: run in the background. Otherwise the default is background, and Ctrl+B backgrounds a running task. |
| Resume | Documented: An official docs page names this item. | Continues a finished subagent. | Use Send with the name or agent ID. A per-call model also applies on resume (2.1.211). |
| Initial context | Documented: An official docs page names this item. | What a non-fork subagent loads. | The agent prompt, the task message, CLAUDE. files (unless omit), git status (not for Explore and Plan), preloaded skills, and a roster of siblings with Send. No output style and no auto memory. |
Limits and Switches
| Item | Status | What it does | Notes |
|---|---|---|---|
CLAUDE_ | Documented: An official docs page names this item. | Layers of nesting below the main session. | Default 3. At the limit Agent is withheld, except from a fork. 1 turns nesting off. Earlier defaults: 5 (2.1.172), 1 (2.1.217). |
CLAUDE_ | Documented: An official docs page names this item. | The most subagents running at once. | Default 20. The error is Concurrent subagent limit reached. Ultracode sessions are exempt. Resumes and / forks take a slot but are not blocked. |
CLAUDE_ | Documented: An official docs page names this item. | Fork mode. | On in interactive sessions (since 2.1.232), off in - and the SDK. 1 forces on, 0 forces off. In fork mode every subagent runs in the background, and Agent has no run_. |
CLAUDE_ | Documented: An official docs page names this item. | Runs all subagents in the foreground. | Set 1. Also removes run_. |
CLAUDE_ | Documented: An official docs page names this item. | The stall timeout. | Default 600000. |
CLAUDE_ and -- | Documented: An official docs page names this item. | Sends subagent text in stream-. | Print mode only. |
CLAUDE_, CLAUDE_ | Documented: An official docs page names this item. | The default model, and forcing it. | See model on Subagent Frontmatter. |
CLAUDE_, subagent | Documented: An official docs page names this item. | The cache TTL for subagent requests. | 5m or 1h. Frontmatter experimental. is the third source. See Request and Cache. |
CLAUDE_, CLAUDE_, CLAUDE_, CLAUDE_, CLAUDE_ | Undocumented: Only the program shows this item. It can change without notice. | Other subagent variables in the program. | -- (or --, print mode only, hidden) adds text to the end of every subagent system prompt. It turns on CLAUDE_, and the variable alone changes nothing. Using both flags gives an error. CLAUDE_ turns the startup notice that your config asks for subagents on (1) or off (0). CLAUDE_ adds the prompt- beta to a subagent's last request, on a first-party login. CLAUDE_ and CLAUDE_ showed no change in print mode. Source: the program and Probes. |
Settings agent, teammate, subagent | Documented: An official docs page names this item. | agent sets the main-session agent. teammate picks the teammate display. subagent sets a status line for subagents. | teammate takes auto, tmux, iterm2, or in- (source: the program). |
All variables are also listed on Environment Variables for Agents and Teams.
Agent Teams
An agent team is a group of Claude sessions that work as teammates.
| Item | Status | What it does | Notes |
|---|---|---|---|
| Agent teams | Gated: Works only behind a flag or a server gate. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Experimental: The program or the official docs call this experimental or beta. | Several sessions work as teammates. | A named subagent started in an interactive team session starts as a teammate. team_ and mode on Agent are deprecated. Claude Code ignores them. |
| Teammate tools | Gated: Works only behind a flag or a server gate. Same switch as agent teams. | Extra tools for a teammate. | Teammates keep Task, Task, Task, Task, Cron, Cron, Cron. Send routes by name, main, or agent ID. |
Teammate hook | Documented: An official docs page names this item. | Runs when a teammate is about to go idle. | Exit 2 or continue: keeps it working. See Hook Events. |
Task, Task hooks | Documented: An official docs page names this item. | Task lifecycle events. | Task also fires when a teammate finishes its turn. |
agent. mod event | Documented: An official docs page names this item. | Fires before a subagent or teammate starts. | e. is true for a teammate. next({... sets the model. See Plugin Mods Reference. |
CLAUDE_ | Documented: An official docs page names this item. | The wait at exit for team teardown. | 1000 to 60000 ms in print mode. |
How It Works
Related Pages
- Subagents: where agent files live.
- Subagent Frontmatter: the keys of an agent file.
- Hook Events: the agent and task events.
- Environment Variables for Agents and Teams: the full variable list.
- Agents and Tasks Tools for
Agent.
Source: Create Custom Subagents, Environment Variables, Hooks Reference, and the program (the agent definitions and the Agent tool schema).