Agent & Task Tools - Claude Code

Claude Code’s multi-agent subsystem is exposed through a family of related tools. At the core is AgentTool for spawning sub-agents; surrounding it are tools for agent-to-agent communication, team management, structured task tracking, plan mode, and git worktree isolation.

AgentTool

Spawn a sub-agent to work on a parallel or specialised task

SendMessageTool

Send messages between agents and teammates

Team tools

Create and delete multi-agent teams

Task tools

Structured task lifecycle management (TodoV2)

TodoWriteTool

Simple session-scoped to-do list

Plan mode

Enter / exit plan mode for design-before-code workflows

Worktree tools

Git worktree isolation for safe exploratory changes

AgentTool

Spawns a sub-agent (a full Claude loop) to carry out a task independently. Sub-agents inherit the parent’s tool set, permission context, and working directory by default, but can be given their own isolation boundary. Tool name: Agent
Concurrency-safe: no (each sub-agent runs asynchronously but shares session state)
Destructive: depends on the task

Parameters

prompt

string

required

The task for the sub-agent to perform. Be explicit and self-contained — the sub-agent does not share the parent’s conversation history.

description

string

required

A short (3–5 word) description of the task shown in the UI.

subagent_type

string

The name of a specialised agent definition to use (loaded from .claude/agents/ directories). Omit to use the general-purpose agent.

model

string

Optional model override: "sonnet", "opus", or "haiku". Takes precedence over the agent definition’s model setting and the parent’s model. If omitted, inherits the parent’s model.

run_in_background

boolean

default:"false"

Run the sub-agent as a background task. The parent receives a notification when the agent completes. Only available when background tasks are not disabled.

name

string

Human-readable name for the spawned agent. Makes the agent addressable via SendMessage({ to: name }) while it is running.

team_name

string

Team name for spawning as part of a multi-agent team. Uses the current team context if omitted.

mode

string

Permission mode for a spawned teammate, e.g. "plan" to require plan-mode approval before destructive actions.

isolation

string

Isolation mode:

"worktree" — creates a temporary git worktree so the agent works on an isolated copy of the repository. Changes must be merged back explicitly.

cwd

string

Absolute path to run the agent in. Overrides the working directory for all filesystem and shell operations within the sub-agent. Mutually exclusive with isolation: "worktree".

When to use

Parallelism — run independent tasks (e.g. “write tests for module A” and “write tests for module B”) concurrently.
Specialisation — delegate to a domain-specific agent definition (linter, code reviewer, documentation writer).
Isolation — use isolation: "worktree" to let a sub-agent experiment freely without risking the main working tree.

Usage example

{
  "tool": "Agent",
  "input": {
    "description": "Write unit tests",
    "prompt": "Write comprehensive unit tests for all exported functions in src/utils/date.ts. Use Vitest. Place tests in src/utils/__tests__/date.test.ts.",
    "subagent_type": "test-writer"
  }
}

SendMessageTool

Sends a message from the current agent to another agent or teammate by name. Supports point-to-point messages, broadcasts ("*"), and structured protocol messages (shutdown requests/responses, plan approval responses). Tool name: SendMessage
Concurrency-safe: no
Destructive: no

Parameters

string

required

Recipient address. Options:

A teammate name (e.g. "researcher")
"*" to broadcast to all teammates

message

string | object

required

The message payload. Either a plain-text string or a structured message object with a type discriminator:

{ type: "shutdown_request", reason?: string } — request a teammate to shut down
{ type: "shutdown_response", request_id, approve, reason? } — respond to a shutdown request
{ type: "plan_approval_response", request_id, approve, feedback? } — respond to a plan approval request

summary

string

A 5–10 word preview shown in the UI. Required when message is a plain string.

Usage example

{
  "tool": "SendMessage",
  "input": {
    "to": "test-runner",
    "summary": "All changes committed, run tests",
    "message": "The implementation is complete. Please run the full test suite and report results."
  }
}

Team Tools

Team tools manage the lifecycle of multi-agent teams. A team is a named group of agents with a designated lead.

TeamCreateTool

Creates a new team and registers the current agent as its lead. Tool name: TeamCreate

Parameters

team_name

string

required

Name for the new team.

description

string

Optional human-readable description of the team’s purpose.

agent_type

string

Role/type of the team lead (e.g. "researcher", "test-runner"). Used for team file metadata and inter-agent coordination.

Return value

team_name

string

The resolved team name (may differ if the provided name was already taken).

team_file_path

string

Path to the team configuration file.

lead_agent_id

string

Agent ID of the team lead.

TeamDeleteTool

Disbands an existing team and cleans up its associated state. Tool name: TeamDelete

Parameters

team_name

string

required

Name of the team to delete.

Task Tools (TodoV2)

Task tools implement a structured task lifecycle with statuses, dependencies, and ownership. They replace the simpler TodoWriteTool when the TodoV2 feature is enabled.

Creates a new task in the shared task list.Tool name: TaskCreate

Parameters

subject

string

required

Brief title for the task.

description

string

required

What needs to be done.

activeForm

string

Present-continuous form shown in the spinner when the task is in_progress, e.g. "Running tests".

metadata

object

Arbitrary key-value metadata to attach to the task.

Returns { task: { id, subject } }.

Updates an existing task’s status, subject, description, owner, dependencies, or metadata.Tool name: TaskUpdate

Parameters

taskId

string

required

ID of the task to update.

status

string

New status. One of "pending", "in_progress", "completed", "blocked", or "deleted" (removes the task).

subject

string

New task title.

description

string

New task description.

activeForm

string

Updated spinner label for in_progress state.

owner

string

Agent name that owns this task.

addBlocks

string[]

Task IDs that this task blocks (adds to dependency graph).

addBlockedBy

string[]

Task IDs that block this task (adds to dependency graph).

metadata

object

Metadata keys to merge. Set a key to null to delete it.

Retrieves a single task by ID.Tool name: TaskGet

taskId

string

required

ID of the task to retrieve.

Lists all tasks in the current session’s task list, with optional status filtering.Tool name: TaskList

status

string

Optional status filter: "pending", "in_progress", "completed", "blocked".

Stops a running background task (agent or shell task).Tool name: TaskStop

task_id

string

required

ID of the task to stop.

Reads output from a background task, optionally waiting for it to complete.Tool name: TaskOutput

task_id

string

required

The task ID to get output from.

block

boolean

default:"true"

Whether to wait for the task to complete before returning.

timeout

number

default:"30000"

Maximum wait time in milliseconds (0–600 000).

Returns { retrieval_status, task } where retrieval_status is "success", "timeout", or "not_ready".

TodoWriteTool

A simpler session-scoped to-do list used when TodoV2 is not enabled. Replaces the entire list atomically on each call. Tool name: TodoWrite
Concurrency-safe: yes
Destructive: no (replaces existing list; previous state can be reconstructed from the return value)

Parameters

todos

array

required

The complete updated to-do list. Each item has:

id — unique identifier
content — task description
status — "pending", "in_progress", or "completed"
priority — "high", "medium", or "low"

Return value

oldTodos

array

The to-do list before the update.

newTodos

array

The to-do list after the update. Empty when all items are "completed".

Usage example

{
  "tool": "TodoWrite",
  "input": {
    "todos": [
      { "id": "1", "content": "Read existing tests", "status": "completed", "priority": "high" },
      { "id": "2", "content": "Write new unit tests", "status": "in_progress", "priority": "high" },
      { "id": "3", "content": "Update README", "status": "pending", "priority": "low" }
    ]
  }
}

Plan Mode Tools

Plan mode restricts Claude Code to read-only operations, forcing all proposed changes to be reviewed and approved before execution. It is intended for complex tasks that require exploration and design before coding.

EnterPlanModeTool

Requests permission to enter plan mode. Claude Code switches the session’s permission mode to "plan" and prompts the user for approval before any write or execute operation. Tool name: exit_plan_mode (the tool that enters plan mode; the name reflects the user action that ends it) Takes no parameters. Returns { message } confirming plan mode was entered.

Plan mode is automatically exited when the user approves a proposed change. The session’s permission mode is restored to its previous value.

ExitPlanModeTool

Exits plan mode and returns to the previous permission level. Tool name: exit_plan_mode Takes no parameters.

Worktree Tools

Worktree tools provide in-session git worktree isolation. When active, all filesystem and shell operations within the session are redirected to a temporary git worktree branched off the current HEAD.

EnterWorktreeTool

Creates a new git worktree and switches the current session into it. Tool name: EnterWorktree

Parameters

name

string

Optional name for the worktree. Each /-separated segment may contain letters, digits, dots, underscores, and dashes; maximum 64 characters total. A random name is generated if omitted.

Return value

worktreePath

string

Absolute path to the created worktree.

worktreeBranch

string

Branch checked out in the worktree (if applicable).

message

string

Human-readable confirmation.

ExitWorktreeTool

Exits the current worktree and returns the session to the original working directory. The worktree is removed from disk. Tool name: ExitWorktree Takes no parameters.

Exiting the worktree discards any uncommitted changes inside it. Commit or stash changes before calling ExitWorktreeTool if you want to preserve them.

Usage example

{
  "tool": "EnterWorktree",
  "input": {
    "name": "feature/add-auth"
  }
}

Built-in Tools

Slash Commands

Analysis Reports

AgentTool

SendMessageTool

Team tools

Task tools

TodoWriteTool

Plan mode

Worktree tools

​AgentTool

​Parameters

​When to use

​Usage example

​SendMessageTool

​Parameters

​Usage example

​Team Tools

​TeamCreateTool

​Parameters

​Return value

​TeamDeleteTool

​Parameters

​Task Tools (TodoV2)

​Parameters

​Parameters

​TodoWriteTool

​Parameters

​Return value

​Usage example

​Plan Mode Tools

​EnterPlanModeTool

​ExitPlanModeTool

​Worktree Tools

​EnterWorktreeTool

​Parameters

​Return value

​ExitWorktreeTool

​Usage example

Build docs developers (and LLMs) love

AgentTool

Parameters

When to use

Usage example

SendMessageTool

Parameters

Usage example

Team Tools

TeamCreateTool

Parameters

Return value

TeamDeleteTool

Parameters

Task Tools (TodoV2)

Parameters

Parameters

TodoWriteTool

Parameters

Return value

Usage example

Plan Mode Tools

EnterPlanModeTool

ExitPlanModeTool

Worktree Tools

EnterWorktreeTool

Parameters

Return value

ExitWorktreeTool

Usage example