Task Tool

Delegate tasks to specialized subagents

Task Tool (task)

The task tool enables delegation of complex, multi-step tasks to specialized subagents that work autonomously with their own tool access.

Overview

Tool Name: task

Display Name: Task

Kind: Other

Description: Launches specialized subagents to handle complex tasks autonomously. Supports parallel execution and real-time progress updates.

Parameters

interface TaskParams {
  description: string;     // Required: Short (3-5 word) description
  prompt: string;         // Required: Detailed task instructions
  subagent_type: string;  // Required: Type of subagent to use
}

Usage

Basic Task Delegation

task({
  description: 'Code review',
  prompt: 'Review the authentication module for security issues and best practices',
  subagent_type: 'code-reviewer',
});

Detailed Instructions

task({
  description: 'Refactor module',
  prompt: `Refactor the user management module:
  1. Convert callbacks to async/await
  2. Add proper error handling
  3. Update tests
  4. Update documentation`,
  subagent_type: 'general-purpose',
});

Multiple Parallel Tasks

// Launch multiple subagents concurrently
task({
  description: 'Code review',
  prompt: 'Review recent changes for code quality',
  subagent_type: 'code-reviewer',
});

task({
  description: 'Run tests',
  prompt: 'Execute test suite and analyze failures',
  subagent_type: 'test-runner',
});

task({
  description: 'Update docs',
  prompt: 'Generate API documentation for new endpoints',
  subagent_type: 'documentation-writer',
});

Available Subagents

Subagents are configured in your project or user settings. Common types:

Built-in Subagents

General Purpose

name: general-purpose
description: Handles complex multi-step tasks with full tool access
tools: [all tools]

Use for:

• Complex refactoring
• Feature implementation
• Multi-file changes
• General development tasks

Code Search

name: code-search
description: Find code patterns and definitions across the codebase
tools:
  - read_file
  - grep_search
  - glob
  - list_directory

Use for:

• Finding function definitions
• Locating usage patterns
• Searching across multiple files
• Code exploration

Custom Subagents

Create your own subagents for specific needs. See Subagents System for details.

Viewing Available Subagents

In Qwen Code CLI:

/agents list

This shows all available subagents with their descriptions and tool access.

Task Execution Flow

1. Initialization

User/Model
    │
    v
Task Tool
    │
    ├─ Load subagent configuration
    ├─ Create SubAgentScope
    ├─ Initialize tool registry (subset)
    └─ Set up event emitter

2. Execution

SubAgent
    │
    ├─ Receive task prompt
    │
    ├─ Process with model
    │
    ├─ Execute tools (with confirmation if needed)
    │
    ├─ Iterate until complete
    │
    └─ Return final result

3. Termination

Task Tool
    │
    ├─ Receive final result
    ├─ Emit finish event
    ├─ Clean up resources
    └─ Return to parent agent

Real-time Progress Updates

The task tool provides live updates:

Event Types

enum SubAgentEventType {
  START = 'start',              // Subagent started
  ROUND = 'round',             // New conversation round
  TOOL_CALL = 'tool_call',     // Tool being called
  TOOL_RESULT = 'tool_result', // Tool result received
  APPROVAL_REQUEST = 'approval_request', // User confirmation needed
  FINISH = 'finish',           // Task completed
  ERROR = 'error',             // Error occurred
  USAGE = 'usage',             // Token usage update
}

UI Display

Progress is shown in the CLI:

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Subagent: code-reviewer            ┃
┃ Status: Running                    ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┨
┃ ▶ read_file(src/auth.ts)          ┃
┃ ✓ grep_search(pattern="function") ┃
┃ ▶ read_file(src/auth.test.ts)     ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Round 2/10 | Tokens: 1.2K/10K

When to Use Task Tool

Good Use Cases

✅ Complex multi-step tasks

task({
  description: 'Feature implementation',
  prompt: 'Implement user authentication with OAuth, including tests and docs',
  subagent_type: 'general-purpose',
});

✅ Specialized expertise

task({
  description: 'Security audit',
  prompt: 'Audit the API endpoints for security vulnerabilities',
  subagent_type: 'security-auditor',
});

✅ Parallel execution

// Launch 3 tasks simultaneously
task({ description: 'Task 1', prompt: '...', subagent_type: 'type1' });
task({ description: 'Task 2', prompt: '...', subagent_type: 'type2' });
task({ description: 'Task 3', prompt: '...', subagent_type: 'type3' });

✅ Autonomous workflows

task({
  description: 'Fix failing tests',
  prompt: 'Run test suite, identify failures, and fix them',
  subagent_type: 'test-fixer',
});

When NOT to Use

❌ Simple file reads

// ❌ DON'T use task
task({
  description: 'Read file',
  prompt: 'Read src/index.ts',
  subagent_type: 'code-search',
});

// ✅ DO use read_file directly
read_file({ absolute_path: '/path/to/src/index.ts' });

❌ Single-step operations

// ❌ DON'T use task
task({
  description: 'List files',
  prompt: 'List files in src/',
  subagent_type: 'general-purpose',
});

// ✅ DO use list_directory
list_directory({ path: '/path/to/src' });

❌ Interactive tasks

• Tasks requiring back-and-forth communication
• Tasks needing user input during execution
• Exploratory tasks with unclear requirements

Subagent Configuration

Subagents need proper configuration to work effectively.

Configuration Structure

---
name: my-agent
description: What this agent does and when to use it
tools:
  - read_file
  - write_file
  - grep_search
modelConfig:
  model: qwen-coder-plus
  temperature: 0.3
runConfig:
  max_turns: 15
  max_time_minutes: 10
---

# System Prompt

You are a specialized agent for [purpose].

Your responsibilities:
1. [Task 1]
2. [Task 2]

Guidelines:
- [Guideline 1]
- [Guideline 2]

Creating Subagents

See Subagents System for detailed instructions on:

• Creating custom subagents
• Configuring tool access
• Setting model parameters
• Defining system prompts
• Managing subagent lifecycle

Tool Access Control

Subagents only have access to tools specified in their configuration:

tools:
  - read_file      # ✅ Can read files
  - grep_search    # ✅ Can search code
  - glob           # ✅ Can find files
  # write_file not listed ❌ Cannot write files
  # edit not listed ❌ Cannot edit files

This provides isolation and security:

• Read-only agents: Only read/search tools
• Editor agents: Read + write/edit tools
• Full-access agents: All tools (use carefully)

Execution Limits

Subagents have configurable limits:

runConfig:
  max_turns: 20              # Max conversation rounds
  max_time_minutes: 30       # Max execution time
  terminate_mode: graceful   # Or 'immediate'

Reaching Limits

Max Turns:

Subagent terminated: Maximum turns (20) reached
Partial result: [what was completed]

Timeout:

Subagent terminated: Maximum time (30 minutes) exceeded
Partial result: [what was completed]

Graceful vs Immediate Termination

• Graceful: Allows subagent to summarize results
• Immediate: Stops immediately and returns current state

Result Handling

Subagents return a single final message:

interface SubagentResult {
  result: string;           // Final result message
  success: boolean;         // Whether task completed successfully
  statistics: {
    totalDurationMs: number;
    rounds: number;
    toolCalls: number;
    tokens: number;
  };
}

The parent agent receives this result and can:

1. Use it directly in response
2. Process it further
3. Delegate to another subagent
4. Present it to the user

Statistics and Monitoring

Task execution is tracked:

interface TaskStatistics {
  totalDurationMs: number;      // Total execution time
  rounds: number;               // Conversation rounds
  totalToolCalls: number;       // Tools called
  successfulToolCalls: number;  // Successful calls
  failedToolCalls: number;      // Failed calls
  inputTokens: number;          // Input tokens used
  outputTokens: number;         // Output tokens used
  totalTokens: number;          // Total tokens
  estimatedCost: number;        // Estimated cost
}

Statistics are logged (respecting privacy settings) for analytics and optimization.

Error Handling

Task Errors

try {
  const result = await task({
    description: 'Complex task',
    prompt: 'Do something',
    subagent_type: 'unknown-agent',  // Error: not found
  });
} catch (error) {
  // Handle SubagentError
  console.error(error.code);  // 'NOT_FOUND'
  console.error(error.message);  // 'Subagent "unknown-agent" not found'
}

Execution Errors

If a subagent encounters an error:

Subagent error: [error message]

Partial work completed:
- [action 1]
- [action 2]

Suggested next steps:
- [suggestion 1]
- [suggestion 2]

Best Practices

1. Clear, Detailed Prompts

✅ Good:

task({
  description: 'Refactor module',
  prompt: `Refactor the authentication module:
  1. Extract JWT logic into separate file
  2. Add input validation
  3. Update tests
  4. Add JSDoc comments
  
  Files to modify: src/auth/*.ts
  Keep existing API unchanged.`,
  subagent_type: 'general-purpose',
});

❌ Bad:

task({
  description: 'Fix auth',
  prompt: 'Fix the auth stuff',
  subagent_type: 'general-purpose',
});

2. Choose Right Subagent

Match task to subagent capabilities:

// ✅ Specialized agent for specialized task
task({
  description: 'Security review',
  prompt: 'Review for SQL injection vulnerabilities',
  subagent_type: 'security-auditor',
});

// ❌ General agent for specialized task
task({
  description: 'Security review',
  prompt: 'Review for SQL injection vulnerabilities',
  subagent_type: 'general-purpose',  // Less effective
});

3. Provide Context

Include relevant context in the prompt:

task({
  description: 'Fix bug',
  prompt: `Fix the bug in user login:
  
  Symptom: Users can't log in with email addresses containing '+'
  Location: src/auth/validator.ts
  Error: "Invalid email format"
  
  The email validation regex needs to accept '+' character.
  Update tests after fixing.`,
  subagent_type: 'general-purpose',
});

4. Set Appropriate Limits

Configure limits based on task complexity:

# Simple tasks
runConfig:
  max_turns: 10
  max_time_minutes: 5

# Complex tasks
runConfig:
  max_turns: 30
  max_time_minutes: 20

5. Monitor Progress

Watch the progress updates to ensure the subagent is on track:

• Check tool calls are relevant
• Verify approach makes sense
• Abort if going in wrong direction

Implementation

Location: packages/core/src/tools/task.ts

Tool Class

export class TaskTool extends BaseDeclarativeTool<TaskParams, ToolResult> {
  static readonly Name = ToolNames.TASK;
  private subagentManager: SubagentManager;
  private availableSubagents: SubagentConfig[] = [];

  constructor(private readonly config: Config) {
    super(
      TaskTool.Name,
      ToolDisplayNames.TASK,
      'Launches specialized subagents...',
      Kind.Other,
      { /* schema */ },
      true,  // isOutputMarkdown
      true,  // canUpdateOutput
    );

    this.subagentManager = config.getSubagentManager();
    this.subagentManager.addChangeListener(() => {
      void this.refreshSubagents();
    });

    this.refreshSubagents();
  }

  async refreshSubagents(): Promise<void> {
    this.availableSubagents = await this.subagentManager.listSubagents();
    this.updateDescriptionAndSchema();
  }
}

Next Steps

• Subagents System - Deep dive into subagents
• File System Tools - Tools available to subagents
• Shell Tool - Command execution
• Memory Tool - Persistent storage