The Art of Cloning: The Agent Tool and Subagents

Everything we have discussed so far takes place inside a single conversation loop — one Claude instance thinking, acting, and observing within a single context window. But when tasks grow large and complex, one agent may not be enough. This is where subagents enter the picture.

The Agent Tool: Summoning Clones

Among Claude Code’s tool set, there is a special tool called Agent (also referred to as Task or Subagent). Its purpose is to spawn a brand-new Claude instance with its own independent context window and tool permissions, dedicated to completing a specific subtask.

// Core parameters of the Agent tool
{
"tool": "Agent",
"prompt": "Search all files in the project that use deprecated APIs, list file paths and line numbers",
"allowedTools": ["Read", "Grep", "Glob", "Bash"]
}

When the main agent invokes the Agent tool, the system:

1. Creates a new context window — the subagent starts from scratch, receiving only the prompt passed by the main agent
2. Assigns tool permissions — the subagent can only use explicitly allowed tools
3. Executes independently — the subagent enters its own agentic loop, thinking and acting on its own
4. Returns results — once complete, the subagent reports its findings back to the main agent

Why Subagents?

You might ask: why not let the main agent do everything itself? The answer involves three core concerns:

Context isolation. Each subagent has its own context window. When you need to search a large codebase, the search process generates massive amounts of intermediate data — file contents, grep output, error messages. If all of this piled up in the main agent’s context, it would fill the window quickly. A subagent processes these details and returns only a concise summary.

Parallel execution. Multiple subagents can work simultaneously. Imagine needing to refactor three independent modules at once — three subagents can process them in parallel rather than one after another.

Focus and specialization. Each subagent concentrates on a single, well-defined task. This focus reduces errors because there is no irrelevant information cluttering the context.

Built-in Agent Types

Claude Code provides several preset agent modes:

General-purpose subagent. The default mode with a full tool set, capable of handling any type of task. Suitable for compound tasks requiring file reading, writing, and command execution.

Explore agent. Specialized for codebase search and comprehension. It is given read-only tools like Read, Grep, and Glob, and excels at answering questions like “Where is this function defined?” or “Which files depend on this module?”

Plan agent. Focused on architecture analysis and solution design. It can read code and understand structure but will not make any modifications. Ideal for thinking through an approach before execution.

How Subagents Work

Let us look more closely at a subagent’s lifecycle:

Main agent's context window
┌─────────────────────────────────────────────┐
│ User: "Refactor the auth module and update   │
│        all tests"                            │
│                                              │
│ Thinking: This can be split into two         │
│           independent subtasks...            │
│                                              │
│ Call Agent("Analyze current auth structure")  │
│       ↓                                      │
│ Call Agent("Find all auth-related tests")     │
│       ↓                                      │
│ [Waiting for both subagents to return...]     │
│                                              │
│ Results received → Plan refactor → Execute    │
└─────────────────────────────────────────────┘

Inside each subagent:

Subagent's context window (independent, isolated)
┌─────────────────────────────────────────────┐
│ System: You are a subagent. Your task is...  │
│ Prompt: "Analyze current auth structure"     │
│                                              │
│ Think → Glob("src/auth/**") → Read files     │
│       → Analyze dependencies → Build map     │
│                                              │
│ Return: "Auth module has 5 files, entry      │
│          point is auth.ts, depends on        │
│          jwt.ts and..."                      │
└─────────────────────────────────────────────┘

The key insight: a subagent’s intermediate steps (which files it read, how many searches it ran) never enter the main agent’s context. The main agent sees only the final summary.

Context Isolation: One-Way Communication

The subagent communication model is strictly one-way: the main agent sends a prompt, the subagent returns a result. There is no bidirectional communication, no shared intermediate state, no “conversation.”

Specifically:

• The subagent cannot see the main agent’s context — it does not know what the user said, what the conversation history looks like, or what other tools returned
• Subagents cannot communicate with each other — Subagent A has no idea Subagent B exists, let alone send it a message
• The main agent receives only the final text — the subagent’s internal tool calls, reasoning process, and intermediate results are all discarded

┌─────────────────────────────────────────────┐
│  Main Agent Context                          │
│  ┌─────────────────────────────────────┐    │
│  │ User messages, history, tool results │    │
│  │                                     │    │
│  │  prompt ──────▶ ┌──────────────┐    │    │
│  │                 │  Subagent A  │    │    │
│  │                 │  own context │    │    │
│  │  result ◀────── │  no main ctx │    │    │
│  │                 └──────────────┘    │    │
│  │                                     │    │
│  │  prompt ──────▶ ┌──────────────┐    │    │
│  │                 │  Subagent B  │    │    │
│  │  result ◀────── │  own context │    │    │
│  │                 └──────────────┘    │    │
│  │                                     │    │
│  │  ⚠️ A and B cannot communicate      │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

This design has three critical implications:

The prompt is the only input. A subagent receives nothing but a system prompt and the prompt text you pass to it. It does not know who the user is, what the prior conversation contained, or that other subagents exist.

The result is the only output. The main agent receives a single text result. How many files the subagent read, how many tools it called, how many wrong turns it took — all of that is discarded. The main agent has no way of knowing.

This is why prompt quality is paramount. The prompt you give a subagent must contain all the context it needs, because it has no other way to obtain it. A vague prompt leads to a subagent stumbling in the dark; a precise prompt enables efficient, targeted execution.

Subagent vs Multi-Agent Team

Claude Code uses the Subagent pattern, but this is not the only multi-agent architecture. Let us compare two different approaches:

1. Subagent Pattern (Claude Code’s current approach)

Star topology. All communication must pass through the main agent; subagents cannot communicate directly with each other. The main agent is the sole coordinator and information hub. Best suited for tasks that can be decomposed into independent subtasks.

2. Multi-Agent Team Pattern (future direction / other frameworks)

Mesh topology. Agents can communicate with each other, share state, or pass messages directly. Coordination can be decentralized, with each agent capable of initiating collaboration. Best suited for complex tasks that require agents to collaborate closely.

Subagent Pattern (Star)       Multi-Agent Team (Mesh)

   ┌───┐                         ┌───┐
   │ A │                         │ A │◄──────┐
   └─┬─┘                         └─┬─┘      │
     │                              │        │
┌────┴────┐                    ┌────┴────┐   │
│  Main   │                    │  Main   │   │
└────┬────┘                    └────┬────┘   │
     │                              │        │
   ┌─┴─┐                         ┌─┴─┐      │
   │ B │                         │ B │───────┘
   └───┘                         └───┘

A ↔ Main ↔ B                  A ↔ Main ↔ B
A ✗ B (cannot communicate)    A ↔ B (can communicate)

Claude Code’s choice of the Subagent pattern is a deliberate design decision. Here is why:

• Easier to reason about: Star topology means all information flows through a single central point. There are no complex multi-party coordination problems, no “telephone game” where agents misinterpret each other
• Context isolation prevents “pollution”: Each subagent’s context is clean, uncontaminated by other agents’ intermediate state, making each subtask’s execution more reliable
• The main agent maintains a clear global view: Because all results converge at the main agent, it always holds the most complete global picture and can make better coordination decisions
• Easier to debug: When something goes wrong, the chain of responsibility is clear — was the main agent’s prompt poorly written, or did the subagent execute incorrectly? Star topology makes this investigation straightforward

Parallel Execution

Multiple subagents can run simultaneously, providing a massive efficiency boost:

Main Agent
  │
  ├──→ Subagent A: "Refactor auth module"
  │
  ├──→ Subagent B: "Refactor database module"
  │
  └──→ Subagent C: "Update API docs"

  [All three working simultaneously]

  ←── A done: "Auth refactored, 3 files changed"
  ←── B done: "Database refactored, 5 files changed"
  ←── C done: "API docs updated, 2 new endpoints"

  Main Agent: Consolidate results, check consistency

This pattern is especially useful for:

• Parallel refactoring of independent modules
• Searching for multiple unrelated pieces of information simultaneously
• Running multiple independent tests or validation tasks in parallel

Custom Agents

You can define your own agent types by customizing their behavior through system prompts and tool restrictions:

// Define custom agents in settings.json
{
"agents": {
  "security-reviewer": {
    "systemPrompt": "You are a security audit expert. Check code for vulnerabilities including SQL injection, XSS, sensitive data exposure, etc.",
    "allowedTools": ["Read", "Grep", "Glob"],
    "model": "claude-sonnet-4-20250514"
  },
  "test-writer": {
    "systemPrompt": "You are a test engineer. Write comprehensive unit tests for the given code.",
    "allowedTools": ["Read", "Write", "Grep", "Glob", "Bash"],
    "model": "claude-sonnet-4-20250514"
  }
}
}

With custom agents, you can build a team of specialists — security auditing, test writing, documentation generation, performance analysis — each with clear responsibilities and permission boundaries.

Worktree Isolation

When multiple subagents need to modify code simultaneously, a problem arises: they might conflict with each other. One agent editing auth.ts while another also modifies it.

The solution is Git Worktree isolation:

Project directory: /project
  │
  ├── /project (main worktree - main agent)
  │
  ├── /project-worktree-1 (Subagent A)
  │   └── independent working copy
  │
  └── /project-worktree-2 (Subagent B)
      └── independent working copy

Each subagent works in its own worktree without interference. Once complete, the main agent can merge changes from each worktree back to the main branch. It is like each clone working in its own parallel universe, with results consolidated at the end.

Hierarchy: The Main Agent Orchestrates, Subagents Execute

                  ┌──────────────┐
                  │  Main Agent  │
                  │ (Commander)  │
                  └──────┬───────┘
                         │
            ┌────────────┼────────────┐
            │            │            │
      ┌─────┴─────┐ ┌───┴────┐ ┌────┴──────┐
      │  Explore   │ │Execute │ │  Review   │
      │  (Scout)   │ │(Worker)│ │ (Auditor) │
      └───────────┘ └────────┘ └───────────┘
            │                       │
       Search codebase         Check quality
       Analyze deps            Verify coverage
       Return intel            Return report

The main agent’s role is commander:

• Understand the user’s high-level intent
• Decompose complex tasks into subtasks
• Dispatch subagents for execution
• Consolidate results and make final decisions
• Handle coordination between subagents

The subagent’s role is executor:

• Focus on a single, well-defined task
• Work efficiently in an isolated context
• Return a concise result summary
• No need to understand the big picture

When to Use Subagents

Good candidates for subagents:

• Tasks that can be clearly decomposed into independent subtasks
• Searching large codebases where only a summary is needed
• Multiple independent tasks that can run in parallel
• Tasks involving large intermediate data that should not be kept in the main context

Not ideal for subagents:

• Simple tasks where doing it directly is faster than decomposing
• Subtasks with strong dependencies that cannot execute independently
• Situations requiring continuous context sharing (subagents cannot communicate directly with each other)
• Results requiring precise contextual understanding rather than summaries

Remember: subagents are not free. Each subagent consumes additional tokens, and creating and waiting for subagents takes time. A good commander knows when to send out clones and when to handle things personally.