AI Assistant

Agent & Task Tools

Claude Code's multi-agent system is built on a set of tools for spawning subagents, inter-agent messaging, and task lifecycle management.

AgentTool

The primary tool for spawning subagents that perform work in isolated contexts. AgentTool supports both foreground (blocking) and background (async) execution modes.

Parameters

promptstringrequired

The task for the agent to perform.

descriptionstringrequired

A short (3-5 word) description of the task. Displayed in the UI.

subagent_typestring

The type of specialized agent to use. Maps to agent definitions loaded from the agents directory. Defaults to a general-purpose agent.

modelenum

Model override: "sonnet", "opus", or "haiku". Takes precedence over the agent definition's model.

run_in_backgroundboolean

Run the agent in the background. You will be notified when it completes.

isolationenum

Isolation mode: "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo. "remote" launches in a remote environment (internal only).

cwdstring

Absolute path to run the agent in. Overrides the working directory. Mutually exclusive with isolation: "worktree".

namestring

Name for the spawned agent. Makes it addressable via SendMessage({to: name}) while running.

Execution Modes

The default mode. The parent agent blocks while the subagent runs. The subagent's result is returned directly. Progress is streamed to the UI.

Agent Types

Agents can be specialized through agent definitions loaded from the .claude/agents/ directory. Each definition specifies:

  • A system prompt or instructions
  • Model preferences
  • Required MCP servers
  • Tool restrictions

Built-in agent types include a general-purpose agent and a one-shot verification agent.

When background tasks are disabled (CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true) or fork subagent mode is enabled, the run_in_background parameter is hidden from the schema.

Auto-Background

Foreground agents automatically transition to background after 120 seconds (when enabled via CLAUDE_AUTO_BACKGROUND_TASKS or the tengu_auto_background_agents feature flag). The 2-second progress threshold controls when the background hint appears in the UI.

Key Properties

  • Read-only: No
  • Concurrency-safe: No
  • maxResultSizeChars: 100,000

SendMessageTool

Sends messages between agents in a multi-agent team setup.

Parameters

tostringrequired

Recipient: a teammate name, "*" for broadcast to all teammates, "uds:<socket-path>" for local peers, or "bridge:<session-id>" for Remote Control peers.

messagestring | objectrequired

Plain text message content, or a structured message object (shutdown_request, shutdown_response, plan_approval_response).

summarystring

A 5-10 word summary shown as a preview in the UI. Required when message is a string.

Structured Messages

SendMessageTool supports typed message payloads for protocol-level communication:

type StructuredMessage =
  | { type: 'shutdown_request', reason?: string }
  | { type: 'shutdown_response', request_id: string, approve: boolean, reason?: string }
  | { type: 'plan_approval_response', request_id: string, approve: boolean, feedback?: string }

Routing

Messages are routed through the teammate mailbox system. The tool resolves recipient names against the current team context, finds the matching teammate's agent ID, and queues the message for delivery.

Task Management Tools

The Task tools provide CRUD operations for a shared task list used to coordinate work across agents.

Task tools are enabled when isTodoV2Enabled() returns true. They replace the older TodoWriteTool for structured task management.

TaskCreate

Creates a new task in the shared task list.

subjectstringrequired

A brief title for the task.

descriptionstringrequired

What needs to be done.

activeFormstring

Present continuous form shown in the spinner when in progress (e.g., "Running tests").

metadataRecord

Arbitrary metadata to attach to the task.

TaskUpdate

Updates an existing task's fields.

taskIdstringrequired

The ID of the task to update.

subjectstring

New subject for the task.

descriptionstring

New description.

statusstring

New status: "pending", "in_progress", "completed", or "deleted".

ownerstring

New owner for the task.

addBlocksstring[]

Task IDs that this task blocks.

addBlockedBystring[]

Task IDs that block this task.

TaskGet

Retrieves a single task by ID. Returns the task's subject, description, status, and dependency information (blocks, blockedBy).

taskIdstringrequired

The ID of the task to retrieve.

TaskList

Lists all tasks in the shared task list. Takes no parameters. Returns tasks with their ID, subject, status, owner, and blocking dependencies. Completed tasks' IDs are automatically filtered from other tasks' blockedBy arrays.

TaskStop

Stops a running background task by ID. Works for both background shell tasks and background agent tasks.

task_idstring

The ID of the background task to stop.

shell_idstring

Deprecated: use task_id instead. Kept for backward compatibility with the old KillShell tool name.

Key Source Files

  • src/tools/AgentTool/AgentTool.tsx: Agent spawning with sync/async/worktree modes
  • src/tools/AgentTool/runAgent.ts: Agent execution loop
  • src/tools/SendMessageTool/SendMessageTool.ts: Inter-agent messaging
  • src/tools/TaskCreateTool/TaskCreateTool.ts: Task creation
  • src/tools/TaskUpdateTool/TaskUpdateTool.ts: Task updates with status transitions
  • src/tools/TaskGetTool/TaskGetTool.ts: Single task retrieval
  • src/tools/TaskListTool/TaskListTool.ts: Task listing
  • src/tools/TaskStopTool/TaskStopTool.ts: Background task termination
Web Tools PreviousPlanning ToolsNext