Task Tool and Sub-agent Specialization

Relevant source files

• Anthropic/Claude Code/Tools.json

This document describes Claude Code's Task tool and its specialized sub-agent system for delegating complex, multi-step operations to autonomous agents. The Task tool enables the main agent to spawn specialized worker agents that execute tasks independently and return final results.

For information about Claude Code's other tools, see Tool Architecture and Categories. For file editing operations, see File Editing Operations. For command execution capabilities, see Shell Command Execution.

Overview and Purpose

The Task tool provides a delegation mechanism where Claude Code's main agent can launch specialized sub-agents to handle specific categories of complex work autonomously. Each sub-agent has access to a curated subset of tools appropriate for its domain, and operates independently until completion.

Key Characteristics:

Property	Value
Tool Name	Task
Delegation Model	Fire-and-forget with single result message
Execution Mode	Stateless, autonomous
Communication	One-way: prompt in, final report out
Concurrency	Multiple agents can run in parallel
Agent Types	3 specialized types

Sources: Anthropic/Claude Code/Tools.json1-30

Sub-agent Type Architecture

Diagram: Sub-agent Type Hierarchy and Tool Access

Sources: Anthropic/Claude Code/Tools.json4-5

Sub-agent Type Specifications

1. general-purpose

Description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When searching for keywords or files and not confident about finding the right match in the first few tries, delegate to this agent.

Tool Access: All tools (*)

Primary Use Cases:

• Open-ended code searches requiring multiple rounds of Grep and Glob
• Complex research tasks spanning multiple files and directories
• Multi-step operations that need iterative refinement
• Keyword discovery where initial searches may not yield results

2. statusline-setup

Description: Specialized agent for configuring the user's Claude Code status line setting.

Tool Access: Read, Edit

Primary Use Cases:

• Reading existing status line configuration files
• Modifying status line settings
• Configuration file updates

3. output-style-setup

Description: Specialized agent for creating Claude Code output styles.

Tool Access: Read, Write, Edit, Glob, LS, Grep

Primary Use Cases:

• Creating new output style files
• Searching for existing style configurations
• Reading and modifying style templates
• Listing style directories

Sources: Anthropic/Claude Code/Tools.json4-5

Task Tool Parameters

Input Schema

Parameter	Type	Required	Description
description	string	Yes	Short 3-5 word description of the task
prompt	string	Yes	Detailed, autonomous task description for the agent
subagent_type	string	Yes	Type of specialized agent: general-purpose, statusline-setup, or output-style-setup

Sources: Anthropic/Claude Code/Tools.json6-29

Communication Model and Statefulness

Diagram: Task Tool Communication Flow

Key Characteristics

Stateless Operation:

• Each agent invocation is completely stateless
• No ability to send additional messages to the agent after launch
• No communication from agent back to main agent except final report
• Agent cannot request clarification or additional information

Communication Constraints:

• Main agent → Sub-agent: Single detailed prompt at invocation
• Sub-agent → Main agent: Single final report message
• Sub-agent → User: No direct communication (invisible to user)
• Main agent must relay sub-agent results to user

Prompt Requirements: The prompt parameter must contain a highly detailed task description that enables autonomous execution, including:

• Exact information the agent should return
• Whether to write code or just research
• All context needed for independent decision-making
• Clear success criteria

Sources: Anthropic/Claude Code/Tools.json13-15

Usage Patterns and Decision Logic

Diagram: Task Tool Decision Tree

When to Use Task Tool

Appropriate Scenarios:

1. Open-ended searches: Searching for a keyword or file with uncertainty about finding the match in first few attempts
2. Multi-step research: Complex questions requiring multiple tool invocations and iterations
3. Complex code exploration: Tasks requiring extensive Grep, Glob, and Read operations
4. Specialized configuration: Tasks matching specific sub-agent domains (statusline, output-style)

Example Use Case:

User request: "Find all implementations of error handling across the codebase"

Decision: Use Task tool with general-purpose sub-agent
Reason: Requires multiple Grep rounds with different patterns,
        reading multiple files, and synthesizing findings

Sources: Anthropic/Claude Code/Tools.json7-12

When NOT to Use Task Tool

The tool explicitly lists scenarios where direct tool usage is faster and more appropriate:

Scenario	Use Instead	Reason
Reading specific file path	Read or Glob	Faster direct access
Searching for specific class definition (e.g., "class Foo")	Glob	Faster pattern matching
Searching within specific 2-3 files	Read	Direct file access more efficient
Tasks unrelated to agent descriptions	Other tools	No delegation benefit

Example Use Case:

User request: "Read the file at src/utils/helpers.js"

Decision: Use Read tool directly
Reason: Specific path known, no search required, faster direct access

Sources: Anthropic/Claude Code/Tools.json7-12

Concurrent Execution and Performance

Diagram: Parallel Task Execution Pattern

Concurrency Guidelines

Performance Optimization:

• Always launch multiple agents concurrently when possible to maximize performance
• Use a single message with multiple tool uses to invoke parallel agents
• Each sub-agent executes independently and returns results asynchronously

Example Pattern:

User: "Analyze authentication, error handling, and database patterns"

Main Agent Response:
- Single message invoking 3 Task tools simultaneously
- Each with different prompt and same subagent_type (general-purpose)
- All execute in parallel
- Results aggregated when all complete

Performance Impact:

• Sequential execution: 3 separate invocations = 3x time
• Parallel execution: Single invocation with 3 tasks = ~1x time + aggregation overhead
• Significant speedup for independent research tasks

Sources: Anthropic/Claude Code/Tools.json13

Agent Output Handling

Visibility and Trust Model

Trust Model:

• The documentation states: "The agent's outputs should generally be trusted"
• Main agent should treat sub-agent findings as authoritative
• Main agent's role: synthesize and communicate to user, not second-guess findings

Communication Requirement: The sub-agent result is not visible to the user. The main agent must:

1. Receive the final report from the sub-agent
2. Analyze and understand the findings
3. Send a text message to the user with a concise summary
4. Include relevant details from the sub-agent's report

Sources: Anthropic/Claude Code/Tools.json14-15

Proactive Usage Patterns

Agent-Specific Proactivity

The documentation includes example agent descriptions to illustrate when agents should be used proactively:

Example from Documentation:

"code-reviewer": use this agent after you are done writing a significant piece of code
"greeting-responder": use this agent to respond to user greetings with a friendly joke

Proactive Invocation Logic

If agent description mentions proactive usage:

• Main agent should invoke without explicit user request
• Use judgment to determine when agent's domain applies
• Anticipate user needs based on context

Example Workflow:

User: "Please write a function that checks if a number is prime"

Main Agent Actions:
1. Write the isPrime function using Write tool
2. Proactively invoke Task tool with code-reviewer sub-agent
   (because significant code was written)
3. Report both implementation and review findings to user

Sources: Anthropic/Claude Code/Tools.json17-18

Detailed Task Instructions

Prompt Content Requirements

Since sub-agents are stateless and cannot communicate back, the prompt parameter must be comprehensive:

Required Elements:

1. Task objective: Clear statement of what to accomplish
2. Expected output: Exactly what information to return in final report
3. Work type: Explicitly state whether to write code or just research
4. Context: All necessary background information
5. Constraints: Any limitations or requirements
6. Success criteria: How to determine task completion

Good Prompt Example:

{
  "description": "Search authentication flows",
  "prompt": "Search the codebase for all authentication implementations. 
            This is a RESEARCH task - do not write any code.
            
            Find:
            1. All files containing authentication logic
            2. The authentication methods used (JWT, OAuth, session, etc.)
            3. Where credentials are validated
            4. Any security middleware
            
            Return in your final message:
            - List of files with authentication code
            - Brief description of authentication flow
            - Identification of auth method(s) used
            
            Use Grep to search for patterns like 'auth', 'login', 'authenticate'.
            Use Read to examine promising files in detail.",
  "subagent_type": "general-purpose"
}

Poor Prompt Example:

{
  "description": "Find auth stuff",
  "prompt": "Look for authentication",
  "subagent_type": "general-purpose"
}

Issues: Unclear what to return, no guidance on research vs code, insufficient context.

Sources: Anthropic/Claude Code/Tools.json15-16

Integration with Other Tools

Tool Selection Hierarchy

Complementary Tool Relationships

Tool Category	Direct Usage	Task Tool Delegation
Read	Specific known file paths	Sub-agent uses Read during research
Grep	Single targeted search pattern	Sub-agent performs iterative Grep rounds
Glob	Known class/function name pattern	Sub-agent uses Glob as part of discovery
Edit	Main agent direct edits	statusline-setup/output-style-setup agents use Edit
Write	Main agent creates files	output-style-setup agent uses Write
Bash	Main agent command execution	general-purpose agent can use Bash

Sources: Anthropic/Claude Code/Tools.json1-30

Best Practices and Guidelines

Design Principles

1. Maximize Concurrency

   • Launch multiple independent Task agents in a single message
   • Avoid sequential delegation when tasks are independent
   • Aggregate results from parallel agents

2. Appropriate Delegation

   • Use Task tool for genuinely complex, multi-step work
   • Use direct tools (Read, Grep, Glob) for straightforward operations
   • Consider execution time: delegation has overhead

3. Comprehensive Prompts

   • Provide complete context in the prompt parameter
   • Explicitly state research vs code writing expectations
   • Specify exact output format needed
   • Include success criteria

4. Trust Agent Results

   • Treat sub-agent outputs as authoritative
   • Don't second-guess findings without good reason
   • Focus on summarizing and communicating to user

5. Proactive Usage

   • Invoke specialized agents based on context without user prompting
   • Use judgment to determine when agent domains apply
   • Anticipate workflow needs (e.g., code review after significant implementation)

Anti-Patterns to Avoid

Anti-Pattern	Why It's Wrong	Correct Approach
Using Task for known file paths	Slower than direct Read	Use Read tool directly
Vague prompts to sub-agents	Agent cannot operate autonomously	Provide detailed, complete instructions
Sequential Task invocations	Misses parallelization opportunity	Single message with multiple Task tools
Showing raw sub-agent output to user	Output is not user-facing	Summarize in concise text message
Delegating trivial operations	Overhead exceeds benefit	Use direct tools for simple tasks

Sources: Anthropic/Claude Code/Tools.json7-18

---

Summary: The Task tool provides a sophisticated delegation architecture where Claude Code's main agent can spawn specialized sub-agents with curated tool access to handle complex, multi-step operations autonomously. The system emphasizes parallel execution, stateless operation, and clear separation between agent research and user communication. Proper usage requires understanding when delegation provides value versus when direct tool usage is more efficient.