tools/AgentTool/ — Sub-Agent Orchestration Tool

Contents

Architecture

flowchart TD
  A["Parent Agent"] -->|"tool_use: Agent"| B["AgentTool.call()"]
  B --> C{"Fork enabled?"}
  C -->|"yes + no subagent_type"| D["buildForkedMessages()"]
  C -->|"no / explicit type"| E{"team_name set?"}
  E -->|"yes"| F["spawnTeammate()"]
  E -->|"no"| G["resolveAgentTools()"]
  D --> H["runAgent() with fork context"]
  F --> I["Multi-agent spawn"]
  G --> J["filterToolsForAgent()"]
  J --> K["loadAgentMemoryPrompt()"]
  K --> L["runAgent() async generator"]
  L --> M["Stream events + progress"]
  M --> N{"Background?"}
  N -->|"yes"| O["Register LocalAgentTask"]
  N -->|"no"| P["finalizeAgentTool()"]
  O --> P

Agent Type Hierarchy

flowchart LR
  AD["AgentDefinition"] --> BA["BuiltInAgentDefinition"]
  AD --> CA["CustomAgentDefinition"]
  AD --> PA["PluginAgentDefinition"]
  BA --> EX["Explore agent"]
  BA --> PL["Plan agent"]
  BA --> FK["Fork agent"]
  CA --> MD["Markdown config"]
  CA --> JS["JSON settings"]
  PA --> MCP["MCP plugin agents"]
  style BA fill:#1a3a2a,stroke:#3fb950
  style CA fill:#2a2a1a,stroke:#d29922
  style PA fill:#2a1a2a,stroke:#f85149

Key Classes & Functions

Data Structures

Interactions

Agent Source Priority

When multiple sources define agents with the same type, higher-priority sources override lower ones. The resolution order (highest to lowest):

1. CLI argument agents — Passed via command-line flags, highest priority
2. User agents — Defined in ~/.claude/agents/ (markdown or JSON)
3. Project agents — Defined in .claude/agents/ (shared via VCS)
4. Local agents — Machine-specific, not in version control
5. Managed agents — Organization-provided agent definitions
6. Plugin agents — Loaded from MCP plugin servers
7. Built-in agents — Explore, Plan, Fork (lowest priority, always available)

Configuration

Directory Map

AgentTool/
├── AgentTool.tsx              ← Main tool definition: call(), fork routing, team spawn, worktree
├── UI.tsx                     ← React rendering: agent progress, status badges, color display
├── agentColorManager.ts       ← Color assignment for multi-agent UI grouping (8 colors)
├── agentDisplay.ts            ← Agent deduplication, override resolution, source grouping
├── agentMemory.ts             ← MEMORY.md loading with user/project/local scopes
├── agentMemorySnapshot.ts     ← Project snapshot sync: initialize, replace, mark synced
├── agentToolUtils.ts          ← Tool filtering, resolution, finalization, async lifecycle
├── built-in/                  ← Built-in agent prompt templates and definitions
├── builtInAgents.ts           ← Explore, Plan, Fork agent definitions with feature gates
├── constants.ts               ← AGENT_TOOL_NAME, ONE_SHOT types, disallowed tool lists
├── forkSubagent.ts            ← Fork experiment: message building, cache sharing, guards
├── loadAgentsDir.ts           ← Multi-source agent loading: markdown, JSON, plugins, CLI
├── prompt.ts                  ← Agent list injection, formatting, system prompt generation
├── resumeAgent.ts             ← Background agent resumption from persisted state
└── runAgent.ts                ← Core execution engine: MCP, tools, streaming (973 LOC)

Deep-Dive Highlights

Core mechanisms from AgentTool have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Agent Tool Resolution with Wildcards

// agentToolUtils.ts — Resolve agent tool spec to actual tools
export function resolveAgentTools(
  agentDef: AgentDefinition,
  availableTools: Tools,
): ResolvedAgentTools {
  const toolSpec = agentDef.tools ?? ['*'];
  const hasWildcard = toolSpec.includes('*');

  if (hasWildcard) {
    // Expand '*' to all available tools minus restricted set
    const restricted = new Set([
      ...ALL_AGENT_DISALLOWED_TOOLS,
      ...(agentDef.disallowedTools ?? []),
    ]);
    return {
      hasWildcard: true,
      validTools: availableTools
        .filter(t => !restricted.has(t.name))
        .map(t => t.name),
      invalidTools: [],
      resolvedTools: availableTools.filter(t => !restricted.has(t.name)),
    };
  }

  // Explicit tool list — validate each name exists
  const validTools: string[] = [];
  const invalidTools: string[] = [];
  for (const name of toolSpec) {
    if (name.startsWith('mcp__') || availableTools.find(t => t.name === name)) {
      validTools.push(name);
    } else {
      invalidTools.push(name);
    }
  }
  return { hasWildcard, validTools, invalidTools,
    resolvedTools: availableTools.filter(t => validTools.includes(t.name)) };
}

Example: Fork Message Building for Cache Sharing

// forkSubagent.ts — Build byte-identical prefixes for fork children
export function buildForkedMessages(
  directive: string,
  assistantMessage: AssistantMessage,
): MessageType[] {
  // All fork children share identical placeholder results for tool_use blocks
  // Only the final directive text differs per child → maximizes cache hits
  const placeholderResults = assistantMessage.content
    .filter(block => block.type === 'tool_use')
    .map(block => ({
      type: 'tool_result' as const,
      tool_use_id: block.id,
      content: 'Fork started — processing in background',
    }));

  return [
    ...historyMessages,
    { role: 'assistant', content: assistantMessage.content },
    { role: 'user', content: [
      ...placeholderResults,
      { type: 'text', text: buildChildMessage(directive) },
    ]},
  ];
}