DEV Community

Cover image for The Task Tool: Claude Code's Agent Orchestration System
Bilal Haidar
Bilal Haidar

Posted on

The Task Tool: Claude Code's Agent Orchestration System

#claudecode #ai #automation

Table of Contents

Introduction

The Task tool is Claude Code's most powerful feature for handling complex, multi-step operations. Think of it as Claude's ability to spawn specialized "colleagues" - autonomous sub-agents that can work independently while you continue with other tasks.

Key Insight: Claude Code isn't just one AI - it's a system that can orchestrate multiple AI agents, each with specialized skills and tools, working in parallel or sequence to accomplish complex goals.

What is the Task Tool?

The Task tool is a function that allows Claude to:

  1. Spawn sub-agents: Create separate Claude instances with specialized capabilities
  2. Delegate work: Assign specific tasks with detailed instructions
  3. Run autonomously: Sub-agents work independently until task completion
  4. Execute in background: Long-running tasks don't block your workflow
  5. Return results: Completed work is reported back to the main session

Architecture 

Main Claude Session (You interact here)
    ↓
    ├─→ Task Tool invocation
    │       ↓
    │   Sub-Agent (Specialized Claude instance)
    │       ├─→ Has own context & memory
    │       ├─→ Access to specific tools
    │       ├─→ Works autonomously
    │       └─→ Returns results when done
    │
    └─→ You continue working (if background)
Enter fullscreen mode Exit fullscreen mode

How It Works

Basic Invocation

When Claude calls the Task tool:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="description">Short task description</parameter>
  <parameter name="prompt">Detailed instructions for the sub-agent</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="model">haiku</parameter> <!-- Optional: use faster model -->
</invoke>
Enter fullscreen mode Exit fullscreen mode

What Happens

  1. Agent Creation: New Claude instance spawned with specified type
  2. Context Loading: Agent receives the prompt with all necessary instructions
  3. Autonomous Execution: Agent uses its available tools to complete the task
  4. Result Reporting: Agent returns findings/outputs to main session
  5. Cleanup: Agent terminates after completion

Key Parameters

Parameter Required Description
subagent_type ✅ Yes Which specialized agent to use
description ✅ Yes 3-5 word summary of task
prompt ✅ Yes Detailed instructions for agent
run_in_background ❌ No Run async (true) or blocking (false)
model ❌ No sonnet (default), opus, or haiku
resume ❌ No Resume a previous agent by ID

Available Agent Types

1. General-Purpose Agent

Tools Available: All tools (Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, etc.)

Best For:

  • Complex research tasks
  • Multi-step file operations
  • Web scraping and analysis
  • Tasks requiring multiple tool types
  • Open-ended exploration

Example Use Cases:

- "Search the codebase for all API endpoints and document them"
- "Research best practices for implementing OAuth 2.0"
- "Find all TODO comments and create GitHub issues"
- "Analyze dependencies and identify outdated packages"
Enter fullscreen mode Exit fullscreen mode

When Claude Uses It:

  • You ask for research that requires multiple searches
  • Complex codebase analysis spanning many files
  • Tasks that need both web research and code inspection

2. Explore Agent

Tools Available: Glob, Grep, LS, Read, NotebookRead, WebFetch, WebSearch (NO Edit/Write)

Best For:

  • Fast codebase exploration
  • Finding files by patterns
  • Searching code for keywords
  • Answering "where/how" questions about code
  • Read-only analysis

Thoroughness Levels:

  • quick: Basic searches, first match priority
  • medium: Moderate exploration, multiple locations
  • very thorough: Comprehensive analysis, all possibilities

Example Use Cases:

- "Where are errors from the client handled?"
- "What is the codebase structure?"
- "Find all files that use the Authentication service"
- "How does the payment processing flow work?"
Enter fullscreen mode Exit fullscreen mode

When Claude Uses It:

  • You ask exploratory questions about the codebase
  • Need to understand architecture or flow
  • Searching for patterns across many files
  • Read-only investigation needed

Performance: Faster than general-purpose for search tasks because it has fewer tools to consider.

3. Plan Agent

Tools Available: All tools EXCEPT Task, ExitPlanMode, Edit, Write, NotebookEdit

Best For:

  • Designing implementation strategies
  • Creating step-by-step plans
  • Identifying critical files before coding
  • Considering architectural trade-offs
  • Planning complex features

Workflow:

  1. Agent explores codebase
  2. Analyzes existing patterns
  3. Designs implementation approach
  4. Returns detailed plan for approval
  5. Main Claude executes plan after approval

Example Use Cases:

- "Plan implementation of user authentication"
- "Design a strategy for migrating to a new database"
- "Create a refactoring plan for the API layer"
- "Plan how to add real-time notifications"
Enter fullscreen mode Exit fullscreen mode

When Claude Uses It:

  • Tasks require architectural decisions
  • Multiple valid implementation approaches exist
  • Large-scale changes affecting many files
  • User explicitly enters "plan mode"

4. Bash Agent

Tools Available: Bash only

Best For:

  • Git operations
  • Command execution
  • Terminal tasks
  • Running scripts
  • System operations

Example Use Cases:

- "Run git operations to create a feature branch"
- "Execute npm install and build"
- "Run database migrations"
- "Clean up temporary files"
Enter fullscreen mode Exit fullscreen mode

When Claude Uses It:

  • Git-heavy workflows
  • Command-line only operations
  • No file reading/editing needed

5. Feature Development Agents

code-reviewer

Best For: PR reviews, bug detection, security analysis, code quality

code-explorer

Best For: Deep feature analysis, tracing execution paths, understanding dependencies

code-architect

Best For: Feature architecture design, implementation blueprints, build sequences

6. Specialized Plugin Agents

  • statusline-setup: Configure Claude Code status line
  • claude-code-guide: Answer questions about Claude Code features
  • agent-sdk-dev: Verify Agent SDK applications
  • plugin-dev: Plugin creation and validation
  • code-simplifier: Refactor code for clarity
  • laravel-simplifier: PHP/Laravel specific refactoring

Background vs Foreground Execution

Foreground (Default)

Behavior:

  • Blocks main session until completion
  • You wait for results before continuing
  • Claude pauses until agent finishes

Use When:

  • Task takes <30 seconds
  • You need results immediately to continue
  • Task is prerequisite for next steps

Example:

"Search for all API endpoints" (blocks for 10 seconds, returns results, you continue)
Enter fullscreen mode Exit fullscreen mode

Background (run_in_background: true)

Behavior:

  • Agent runs asynchronously
  • You can continue with other work
  • Notification when complete
  • Output saved to file

Use When:

  • Task takes >1 minute
  • You don't need results immediately
  • Task is independent of current work
  • Long-running operations (builds, tests, research)

Example:

"Run comprehensive test suite" (launches in background, you continue coding, notified when done)
Enter fullscreen mode Exit fullscreen mode

How to Request Background Execution

Option 1: Natural language

"Spawn a background agent to run web research for Laravel packages"
Enter fullscreen mode Exit fullscreen mode

Option 2: Keyboard shortcut

Press Ctrl+Shift+B when invoking a task
Enter fullscreen mode Exit fullscreen mode

Option 3: Explicit instruction

"Run this as a background task: analyze the entire codebase for security issues"
Enter fullscreen mode Exit fullscreen mode

When to Use Which Agent

Decision Tree 

Do you need to WRITE or EDIT code?
├─ YES → general-purpose or feature-dev agents
└─ NO → Continue...

Is it codebase EXPLORATION?
├─ YES → Explore agent
└─ NO → Continue...

Is it PLANNING before implementation?
├─ YES → Plan agent
└─ NO → Continue...

Is it ONLY bash commands?
├─ YES → Bash agent
└─ NO → general-purpose agent
Enter fullscreen mode Exit fullscreen mode

Quick Reference

Task Type Agent Background?
Find files/patterns Explore No (fast)
Answer code questions Explore No (fast)
Web research general-purpose YES
Multi-file refactor general-purpose Maybe
Plan feature Plan No
Run tests Bash YES
Build project Bash YES
Code review code-reviewer Maybe
Security audit code-reviewer YES

Practical Examples

Example 1: Codebase Exploration

User Request: "Where is authentication handled?"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Explore</parameter>
  <parameter name="description">Find authentication handling</parameter>
  <parameter name="prompt">
    Search the codebase to find where authentication is handled.
    Look for:
    - Auth middleware
    - Login controllers
    - Authentication services
    - JWT/session handling

    Return file paths and brief descriptions.
  </parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Why Explore?: Read-only search, no edits needed, fast results.

Example 2: Deep Web Research

User Request: "/research-via-web 'Laravel latest packages'"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="description">Research Laravel packages</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="prompt">
    Use Claude in Chrome to access claude.ai Research feature.

    Steps:
    1. Navigate to claude.ai
    2. Enable Research toggle
    3. Submit query: "Laravel latest packages 2026"
    4. Wait 5-30 minutes for completion
    5. Extract full results with citations
    6. Save to ./docs/research/[timestamp]-laravel-packages.md

    Return summary when complete.
  </parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Why general-purpose + background?:

  • Needs browser automation tools
  • Takes 5-30 minutes
  • Complex multi-step workflow
  • User can continue working

Example 3: Feature Planning

User Request: "Add dark mode to the application"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Plan</parameter>
  <parameter name="description">Plan dark mode implementation</parameter>
  <parameter name="prompt">
    Design an implementation plan for adding dark mode.

    Explore:
    - Current styling approach (CSS/Tailwind/CSS-in-JS)
    - Existing theme infrastructure
    - Components that need updates

    Plan:
    - Theme toggle component
    - State management approach
    - CSS variable strategy
    - Component modifications needed

    Return step-by-step implementation plan.
  </parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Why Plan?: Architectural decision, multiple approaches possible, user should approve before implementation.

Example 4: Running Tests

User Request: "Run the test suite"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">Bash</parameter>
  <parameter name="description">Run test suite</parameter>
  <parameter name="run_in_background">true</parameter>
  <parameter name="prompt">
    Execute the test suite:

    1. Run: npm test (or appropriate test command)
    2. Capture full output
    3. Report:
       - Pass/fail summary
       - Failed test details
       - Coverage metrics if available
  </parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Why Bash + background?:

  • Command-line only
  • May take several minutes
  • User doesn't need to wait

Example 5: Security Review

User Request: "Review this PR for security issues"

Claude's Decision:

<invoke name="Task">
  <parameter name="subagent_type">code-reviewer</parameter>
  <parameter name="description">Security review PR #123</parameter>
  <parameter name="prompt">
    Review PR #123 for security vulnerabilities:

    Check for:
    - SQL injection risks
    - XSS vulnerabilities
    - Authentication bypasses
    - Insecure dependencies
    - Exposed secrets

    Use confidence-based filtering - only report high-priority issues.
  </parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Why code-reviewer?: Specialized for security analysis, confidence filtering, review workflows.

Managing Background Tasks

View All Tasks 

/tasks
Enter fullscreen mode Exit fullscreen mode

Or:

Show status of all background agents
Enter fullscreen mode Exit fullscreen mode

Output:

Background Tasks:
- ac88940: Research Laravel packages (running, 18 min)
- ac88941: Run test suite (completed, 3 min ago)
Enter fullscreen mode Exit fullscreen mode

Check Task Progress

Option 1: Read output file

Read /private/tmp/claude/-Users-you-project/tasks/ac88940.output
Enter fullscreen mode Exit fullscreen mode

Option 2: Tail live output

tail -f /private/tmp/claude/-Users-you-project/tasks/ac88940.output
Enter fullscreen mode Exit fullscreen mode

Option 3: Wait for notification

(Claude automatically notifies you when complete)
Enter fullscreen mode Exit fullscreen mode

Kill a Task 

Kill background task ac88940
Enter fullscreen mode Exit fullscreen mode

Or use the KillShell tool if it's a Bash background task.

Resume a Task

If a task was interrupted or you want to continue work:

<invoke name="Task">
  <parameter name="subagent_type">general-purpose</parameter>
  <parameter name="resume">ac88940</parameter>
  <parameter name="prompt">Continue from where you left off...</parameter>
</invoke>
Enter fullscreen mode Exit fullscreen mode

Use Case: Agent hit rate limits, network issues, or you want to add follow-up instructions.

Best Practices

1. Choose the Right Agent

❌ Don't: Use general-purpose for simple searches

"Find the User model" → general-purpose agent (overkill)
Enter fullscreen mode Exit fullscreen mode

✅ Do: Use Explore for read-only searches

"Find the User model" → Explore agent (faster, appropriate)
Enter fullscreen mode Exit fullscreen mode

2. Be Specific in Prompts

❌ Don't: Vague instructions

"Research authentication"
Enter fullscreen mode Exit fullscreen mode

✅ Do: Detailed, structured prompts

"Research OAuth 2.0 implementation best practices for Laravel.
Include:
- Authorization code flow setup
- Token storage strategies
- Security considerations
- Popular Laravel packages
Provide code examples and cite sources."
Enter fullscreen mode Exit fullscreen mode

3. Use Background for Long Tasks

❌ Don't: Block for minutes

"Run full test suite" → foreground (you wait 5 minutes)
Enter fullscreen mode Exit fullscreen mode

✅ Do: Background long operations

"Run full test suite in background" → continue working, notified when done
Enter fullscreen mode Exit fullscreen mode

Rule of Thumb: If task takes >30 seconds, run in background.

4. Model Selection

Sonnet (default): Best quality, moderate speed

Complex tasks, code generation, architectural decisions
Enter fullscreen mode Exit fullscreen mode

Haiku: Fast, cost-effective

Simple searches, quick analysis, repetitive tasks
Enter fullscreen mode Exit fullscreen mode

Opus: Maximum capability (rarely needed)

Extremely complex reasoning, critical decisions
Enter fullscreen mode Exit fullscreen mode

Example:

<parameter name="model">haiku</parameter>  <!-- For quick file search -->
Enter fullscreen mode Exit fullscreen mode

5. Don't Nest Tasks Unnecessarily

❌ Don't: Task within task within task

Main → Task → Sub-Task → Sub-Sub-Task (complexity explosion)
Enter fullscreen mode Exit fullscreen mode

✅ Do: Flatten when possible

Main → Task with comprehensive instructions
Enter fullscreen mode Exit fullscreen mode

Exception: Legitimate parallel work (e.g., Plan agent explores, then reports to main Claude who executes).

6. Provide Context

Agents don't automatically see your full conversation history. Give them what they need:

❌ Don't:

"Fix the bug we discussed earlier"  (agent has no idea)
Enter fullscreen mode Exit fullscreen mode

✅ Do:

"Fix the bug in src/api/users.js:45 where user.name is undefined.
Error: Cannot read property 'name' of undefined.
This happens when the API returns null for deleted users.
Add null check before accessing properties."
Enter fullscreen mode Exit fullscreen mode

Common Patterns

Pattern 1: Explore → Plan → Execute 

User: "Add user authentication"

Step 1: Explore agent
  → Understand current auth infrastructure
  → Find related files
  → Identify patterns

Step 2: Plan agent
  → Design implementation strategy
  → Return plan for approval

Step 3: Main Claude
  → Execute approved plan
  → Write code
  → Run tests
Enter fullscreen mode Exit fullscreen mode

Pattern 2: Parallel Background Tasks 

User: "Prepare for deployment"

Launch simultaneously:
- Background Task 1: Run test suite
- Background Task 2: Build production assets
- Background Task 3: Run security audit
- Background Task 4: Update dependencies

All complete → Review results → Deploy
Enter fullscreen mode Exit fullscreen mode

Pattern 3: Research → Implement 

User: "Implement rate limiting"

Step 1: general-purpose agent (background)
  → Research rate limiting strategies
  → Find Laravel packages
  → Best practices documentation

Step 2: Main Claude (after research completes)
  → Review research findings
  → Choose approach with user
  → Implement solution
Enter fullscreen mode Exit fullscreen mode

Pattern 4: Iterative Exploration 

User: "How does the payment flow work?"

Step 1: Explore agent
  → Find PaymentController
  → Returns initial findings

Step 2: Explore agent (resume or new)
  → "Now trace what happens in PaymentService"
  → Returns service details

Step 3: Explore agent
  → "Check the webhook handlers"
  → Complete picture emerges
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Issue: Task Takes Too Long

Symptoms: Background task running for hours

Solutions:

  1. Check output file: tail -f /path/to/task.output
  2. Look for stuck browser operations, infinite loops, or waiting
  3. Kill and relaunch with refined prompt
  4. Use faster model (haiku) if appropriate

Issue: Task Fails Immediately

Symptoms: Error returned right away

Common Causes:

  • Missing required parameters
  • Invalid agent type
  • Malformed prompt
  • Tool access restrictions

Solution: Check error message, verify agent has needed tools

Issue: Agent Can't Find Files

Symptoms: "No files found" despite files existing

Solutions:

  1. Verify working directory in prompt
  2. Check file paths are correct
  3. Use absolute paths instead of relative
  4. Try different search patterns (glob vs grep)

Issue: Background Task Not Notifying

Symptoms: Task completes but you don't see results

Solutions:

  1. Manually read output file
  2. Check /tasks for completion status
  3. Verify run_in_background: true was set
  4. Look in task output directory

Issue: Out of Context/Tokens

Symptoms: Agent fails with context limit error

Solutions:

  1. Break task into smaller sub-tasks
  2. Use more specific search parameters
  3. Limit file reads to essential sections
  4. Use haiku model for smaller context

Advanced Techniques

Technique 1: Chained Agents

Run agents sequentially where each builds on previous:

Agent 1 (Explore): Find all API endpoints → saves to api-list.md
Agent 2 (general-purpose): Read api-list.md, generate OpenAPI spec
Agent 3 (code-reviewer): Review OpenAPI spec for completeness
Enter fullscreen mode Exit fullscreen mode

Technique 2: Parallel Research

Launch multiple research agents simultaneously:

Background Agent 1: Research authentication methods
Background Agent 2: Research authorization patterns
Background Agent 3: Research session management

All complete → Synthesize findings → Choose approach
Enter fullscreen mode Exit fullscreen mode

Technique 3: Recursive Exploration

Agent explores, finds new areas, spawns new agents:

Explore Agent: "Map the application architecture"
  → Finds frontend/, backend/, mobile/
  → Reports back

Main Claude spawns 3 new Explore agents:
  → Agent A: Explore frontend/
  → Agent B: Explore backend/
  → Agent C: Explore mobile/

All report back → Main Claude synthesizes complete map
Enter fullscreen mode Exit fullscreen mode

Technique 4: Progressive Refinement

Use agent results to refine next agent's instructions:

Agent 1: "Find authentication code"
  → Returns 50 files

Agent 2: "Focus on JWT implementation in these 10 files: [list]"
  → Returns detailed JWT analysis

Agent 3: "Check these 3 security concerns in the JWT code: [specifics]"
  → Returns security audit
Enter fullscreen mode Exit fullscreen mode

Conclusion

The Task tool transforms Claude Code from a helpful assistant into an orchestration system for autonomous AI agents. By understanding:

  • Which agent to use (Explore for searching, general-purpose for complex work, Plan for architecture)
  • When to use background (tasks >30 seconds, independent work)
  • How to write effective prompts (specific, structured, with context)
  • Managing task lifecycle (viewing, monitoring, killing, resuming)

You can tackle increasingly complex workflows while maintaining productivity.

Key Takeaway: Don't think of Claude Code as a single AI - think of it as a team of specialized AIs you can deploy in parallel to accomplish sophisticated goals.

Further Reading:

  • Claude Code documentation: https://claude.com/code
  • Agent SDK for building custom agents
  • Plugin development for extending agent capabilities

Top comments (0)