AgentTool

Entity ID: ent-20260410-4e4b9f933705
Type: tool
Scope: shared
Status: active
Aliases: agent tool, sub-agent spawning

Description

The sub-agent spawning tool — creates child agent instances that run with their own context, tools, and permission scope. AgentTool is the primary mechanism for parallelism in Claude Code: background research, worktree-isolated PoCs, forked agents sharing the parent's prompt cache, and coordinator-managed workers.

See agent-lifecycle for the complete spawn-to-completion lifecycle, including AsyncLocalStorage isolation, fork path cache sharing, and optimizations (omitClaudeMd, gitStatus drop).

Implementation: src/tools/AgentTool/AgentTool.tsx (765 lines)

Input parameters

Parameter	Type	Purpose
`prompt`	string	Task description for the agent
`description`	string	3-5 word label
`subagent_type`	string?	Agent type (Explore, Plan, general-purpose, worker)
`model`	enum?	Model override (sonnet/opus/haiku)
`run_in_background`	boolean?	Async spawn — returns immediately
`name`	string?	Addressable name for SendMessage routing
`team_name`	string?	Team context for multi-agent
`mode`	enum?	Permission mode override
`isolation`	'worktree'?	Filesystem isolation via git worktree

Two execution paths

Synchronous — agent runs inline within the parent's turn. Blocks parent completion. Can be auto-backgrounded after 120 seconds.

Asynchronous — agent runs in a detached closure. Returns immediately with agentId and outputFile path. Parent continues working. Forced for coordinator mode workers.

Agent resolution

Explicit subagent_type wins over defaults
Fork experiment gate can route untyped spawns to Fork subagent
Recursive fork spawning is guarded against
Agent definition lookup applies permission filtering

Key claims

Primary mechanism for parallelism (background agents, worktree isolation, coordinator workers)
Fork path shares parent's prompt cache for cost savings
Coordinator mode forces all spawns to async
Sub-agents get isolated context (no-op setAppState, fresh file cache, linked abort controller)

Relations

rel-agent-lifecycle: AgentTool --[implements]--> agent-lifecycle
rel-agent-coordinator: coordinator-mode --[spawns-via]--> AgentTool
rel-agent-tasks: AgentTool --[registers]--> task-system (LocalAgentTask)

Sources

Source code at src/tools/AgentTool/AgentTool.tsx, src/tools/AgentTool/runAgent.ts