AgentTool: Sub-Agent Scheduler

AgentTool is the core scheduling component of Claude Code. It encapsulates "task decomposition, sub-agent execution, and lifecycle management" into a formal tool, marking this framework's architectural evolution from a single-threaded code assistant to a multi-task agent system. Through a controlled dispatch mechanism, independent context trimming, and complete workflow binding, it solves issues of parallel processing and main thread context pollution in complex task scenarios.

AgentTool is one of the most representative tools in Claude Code. It doesn't solve single-point capabilities like "reading files" or "running commands," but rather:

When the main thread model determines that a task is too large, too complex, or ideally suited for parallelization, how to decompose part of the work for another agent to handle. This is one of the core dividing lines between Claude Code and standard code assistants. Many AI tools rely on a single main thread model running straight through, whereas Claude Code explicitly supports:

• Research-oriented subtasks
• Background execution
• Multi-agent collaboration
• Local/remote sub-agents

tools/AgentTool/AgentTool.tsx exposes its core parameters right from the start:

const baseInputSchema = z.object({
  description: z.string().describe('A short (3-5 word) description of the task'),
  prompt: z.string().describe('The task for the agent to perform'),
  subagent_type: z.string().optional(),
  model: z.enum(['sonnet', 'opus', 'haiku']).optional(),
  run_in_background: z.boolean().optional(),
})

These fields clearly illustrate its positioning:

• description: a brief title for the subtask
• prompt: the actual work handed off to the sub-agent
• subagent_type: selecting a specifically typed agent
• model: switching models when necessary
• run_in_background: executing asynchronously in the background In essence, AgentTool is a task dispatcher.

Within Claude Code's overall tool pool, it is placed at the very front:

export function getAllBaseTools(): Tools {
  return [
    AgentTool,
    TaskOutputTool,
    BashTool,
    ...
  ]
}

This doesn't necessarily mean "most frequently called," but it does indicate that Anthropic views it as a foundational core capability. Because once AgentTool is available, other tools are no longer just "for the main thread to use directly" but can be further invoked by sub-agents. Its position in the system:

Looking at the imports in AgentTool.tsx reveals that this tool actually bridges numerous subsystems behind the scenes:

import { enhanceSystemPromptWithEnvDetails, getSystemPrompt } from '../../constants/prompts.js'
import { assembleToolPool } from '../../tools.js'
import { runAgent } from './runAgent.js'
import { registerAsyncAgent } from '../../tasks/LocalAgentTask/LocalAgentTask.js'
import { registerRemoteAgentTask } from '../../tasks/RemoteAgentTask/RemoteAgentTask.js'

This means AgentTool does at least four things:

1. Regenerates the sub-agent's system prompt
2. Reassembles a dedicated tool pool
3. Determines whether it's a local or remote task
4. Registers the sub-agent within the task system Its true nature is better described as:

Starting a controlled work thread with task context, leveraging Claude Code's runtime framework.

If it simply forked a model blindly, the system would quickly spiral out of control. Claude Code constrains it through several layers of mechanisms:

• Each sub-agent has its own input schema
• Each sub-agent reconstructs its own prompt
• Each sub-agent's tool pool is filtered independently
• Each sub-agent is registered into the task system, supporting status tracking, output retrieval, cancellation, and notifications Thus, AgentTool is not a "free-form cloning tool," but a controlled dispatcher. The call chain can be examined in more detail:

Claude Code doesn't let sub-agents run secretly in the background; it treats them as formal tasks:

• Output is viewable
• Capable of background execution
• Can be stopped/cancelled
• Can be resumed/recovered This is precisely why TaskOutputTool immediately follows AgentTool. They natively function as a pair:
• AgentTool handles task dispatching
• TaskOutputTool handles result retrieval

A typical path can be understood as follows:

1. The main thread identifies that "this problem requires deep investigation into a specific subsystem"
2. The main thread invokes AgentTool
3. The sub-agent independently searches, reads files, reasons, and executes
4. The sub-agent delivers a compressed conclusion
5. The main thread takes this conclusion to continue advancing Compared to "the main thread executing all searches itself," the greatest advantages are:

• Reduced main context pollution
• Easier parallelization
• Better suited for heavy research and deep-dive troubleshooting tasks

• Works with TaskOutputTool: reads sub-agent output
• Works with SendMessageTool: enables mutual communication in multi-agent mode
• Works with BashTool, Read, and Edit: allows the sub-agent to continue completing tasks independently
• Works with SkillTool: certain skills are executed within an independent sub-agent

No. It is a definitive tool invocation, complete with schema, task lifecycle, and result injection.

Also no. A sub-agent's prompt, tool pool, and execution mode can all differ.

• AgentTool is not a single-point capability tool, but rather the scheduling hub encapsulating task decomposition, subprocess execution, and lifecycle management within Claude Code.
• Through independent schemas, prompt restructuring, tool pool isolation, and binding to the Task system, sub-agents are strictly constrained as controlled dispatch targets, rather than autonomous clones.
• Naturally paired with TaskOutputTool, it forms a standardized workflow of "main thread dispatch → context-isolated processing → result return".
• The core business value lies in reducing main context pollution and enabling native parallelism, providing architectural-level support for research-oriented and deep investigation tasks.