One read of Claude Code CLIclaude-code-20260815T050701Z
11 pages moved out of 187 read.
Pages moved
11
significant first
Pages read
187
in this capture
Captured
05:07 UTC
Corpus hash
76accd7fc0d9
corpus-hash
What this read moved
1-11 of 11agent-sdk/python Changed · +11 / -1 lines
from line 2842
28422842**Tool name:** `TodoWrite`
28432843
28442844<Note>
2845 As of Claude Code v2.1.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`.
2845 On Python Agent SDK 0.2.139 and later, the following tools aren't available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, or later versions of those families unless you opt in:
2846
2847 * `TodoWrite`
2848 * `TaskCreate`
2849 * `TaskGet`
2850 * `TaskUpdate`
2851 * `TaskList`
2852
2853 On other models, Claude Code provides the Task tools by default and `TodoWrite` only when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
2854
2855 See [Model availability](/docs/en/agent-sdk/todo-tracking#model-availability) to opt in and [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code.
28462856</Note>
28472857
28482858**Input:**
agent-sdk/todo-tracking Changed · +35 / -13 lines
### Model availability
from line 5
55The Claude Agent SDK includes built-in todo functionality that helps organize complex workflows and keep users informed about task progression.
66
77<Note>
8 As of TypeScript Agent SDK 0.3.142 and Claude Code v2.1.142, sessions use the structured Task tools `TaskCreate`, `TaskUpdate`, `TaskGet`, and `TaskList` instead of `TodoWrite`. The Python SDK gets this change from the Claude Code CLI it launches, not from the Python package version: the switch applies once that CLI — the copy bundled inside the pip package, or one you point to with `cli_path` — is v2.1.142 or later. See [Migrate to Task tools](#migrate-to-task-tools) for how monitoring code changes. The examples on this page set `CLAUDE_CODE_ENABLE_TASKS=0` to keep showing `TodoWrite` for sessions that have not migrated yet.
8 On TypeScript Agent SDK 0.3.233 and later, or Python Agent SDK 0.2.139 and later, the following tools aren't available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, or later versions of those families unless you opt in:
9
10 * `TodoWrite`
11 * `TaskCreate`
12 * `TaskGet`
13 * `TaskUpdate`
14 * `TaskList`
15
16 On other models, Claude Code provides the Task tools by default and `TodoWrite` only when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
917</Note>
1018
19### Model availability
20
21On the [models that don't get the task-tracking tools](/docs/en/tools-reference#task-tool-availability), you see no `tool_use` blocks for them in the message stream unless you opt in. If you point `cli_path` in Python or `pathToClaudeCodeExecutable` in TypeScript at your own Claude Code install, you get whichever tools that install provides. To get the same tools as on other models, do one of the following:
22
23* Name one of the tools in the [`allowedTools`](/docs/en/agent-sdk/permissions#allow-and-deny-rules) option, `allowed_tools` in Python
24* List the tools in the `tools` option, which restricts the session's built-in tools to the ones it names. Include the tools you want alongside the other built-in tools you use
25* Set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in the `env` option, as the examples on this page do. In TypeScript, `env` replaces the subprocess environment, so spread `...process.env` to keep inherited variables. In Python, `env` is merged on top of the inherited environment
26
1127### Todo Lifecycle
1228
1329Claude moves each todo through a predictable lifecycle:
from line 64
4864 for await (const message of query({
4965 prompt: "Optimize my React app performance and track progress with todos",
5066 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
51 // Task tools instead and these tool_use blocks never appear.
52 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
67 // Task tools instead and these tool_use blocks never appear. ENABLE_TODO_TOOLS
68 // keeps the tools on models where Claude Code otherwise doesn't provide them.
69 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0", CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } }
5370 })) {
5471 // Todo updates are reflected in the message stream
5572 if (message.type === "assistant") {
from line 102
85102 async for message in query(
86103 prompt="Optimize my React app performance and track progress with todos",
87104 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
88 # Task tools instead and these tool_use blocks never appear.
89 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
105 # Task tools instead and these tool_use blocks never appear. ENABLE_TODO_TOOLS
106 # keeps the tools on models where Claude Code otherwise doesn't provide them.
107 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0", "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}),
90108 ):
91109 # Todo updates are reflected in the message stream
92110 if isinstance(message, AssistantMessage):
from line 163
145163 try {
146164 for await (const message of query({
147165 prompt,
148 // Re-enable TodoWrite, which this tracker watches for.
149 options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
166 // On every model, re-enable TodoWrite, which this tracker watches for.
167 options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0", CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } }
150168 })) {
151169 if (message.type === "assistant") {
152170 for (const block of message.message.content) {
from line 229
211229 try:
212230 async for message in query(
213231 prompt=prompt,
214 # Re-enable TodoWrite, which this tracker watches for.
215 options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),
232 # On every model, re-enable TodoWrite, which this tracker watches for.
233 options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0", "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}),
216234 ):
217235 if isinstance(message, AssistantMessage):
218236 for block in message.content:
from line 255
237255
238256## Migrate to Task tools
239257
240The Task tools split the single `TodoWrite` call into `TaskCreate` for each new item and `TaskUpdate` for each status change, with `TaskList` and `TaskGet` available for the model to read back the current list. Your monitoring code still inspects `tool_use` blocks in the assistant stream, but maintains a map keyed by task ID instead of replacing the whole list on every call. The Task tools are the default as of TypeScript Agent SDK 0.3.142 and Claude Code v2.1.142, so no `options.env` change is needed.
258The Task tools split the single `TodoWrite` call into `TaskCreate` for each new item and `TaskUpdate` for each status change, with `TaskList` and `TaskGet` available for the model to read back the current list. Your monitoring code still inspects `tool_use` blocks in the assistant stream, but maintains a map keyed by task ID instead of replacing the whole list on every call.
241259
242260| With `TodoWrite` | With Task tools |
243261| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 264
246264| Item shape: `{ content, status, activeForm }` | `TaskCreate` input: `{ subject, description, activeForm?, metadata? }`. `TaskUpdate` input: `{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`. `status` is `"pending"`, `"in_progress"`, or `"completed"`; set `status: "deleted"` to delete |
247265| Render `block.input.todos` directly | Accumulate items across calls, or read a snapshot from a `TaskList` tool result |
248266
249The assigned task ID is not in the `TaskCreate` input. It comes back in the matching `tool_result` as `{ task: { id, subject } }`, so capture it from the result block to key your map. The following example shows the minimal change to the [Monitoring Todo Changes](#monitoring-todo-changes) loop. It reads only `tool_use` inputs and skips capturing IDs from `tool_result` blocks. To render a complete list, watch for a `TaskList` tool result in the stream or accumulate `TaskCreate` results and `TaskUpdate` inputs into a map.
267The assigned task ID is not in the `TaskCreate` input. It comes back in the matching `tool_result` as `{ task: { id, subject } }`, so capture it from the result block to key your map.
250268
269The following example shows the minimal change to the [Monitoring Todo Changes](#monitoring-todo-changes) loop. It leaves `CLAUDE_CODE_ENABLE_TASKS` unset, because the Task tools are the default, and sets only `CLAUDE_CODE_ENABLE_TODO_TOOLS=1`, the [opt-in](#model-availability) for the models that otherwise don't get the tools. It reads only `tool_use` inputs and skips capturing IDs from `tool_result` blocks. To render a complete list, watch for a `TaskList` tool result in the stream or accumulate `TaskCreate` results and `TaskUpdate` inputs into a map.
270
251271The streamed `tool_use` input is the raw shape the model emitted. Claude Code repairs some close-but-incorrect key names before execution, mapping `id` or `task_id` to `taskId` and `active_form` to `activeForm`, but that repair is not reflected in the stream. Read `TaskUpdate` input fields defensively, as the samples below do, rather than assuming the canonical name is always present.
252272
253273<CodeGroup>
from line 277
257277 try {
258278 for await (const message of query({
259279 prompt: "Optimize my React app performance and track progress with todos",
260 options: { maxTurns: 15 },
280 // Keeps the Task tools on models where Claude Code otherwise doesn't provide them.
281 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } },
261282 })) {
262283 if (message.type !== "assistant") continue;
263284 for (const block of message.message.content) {
from line 313
292313 try:
293314 async for message in query(
294315 prompt="Optimize my React app performance and track progress with todos",
295 options=ClaudeAgentOptions(max_turns=15),
316 # Keeps the Task tools on models where Claude Code otherwise doesn't provide them.
317 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}),
296318 ):
297319 if not isinstance(message, AssistantMessage):
298320 continue
agent-sdk/typescript Changed · +22 / -2 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 2516
25162516Creates and manages a structured task list for tracking progress.
25172517
25182518<Note>
2519 As of TypeScript Agent SDK 0.3.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`.
2519 On TypeScript Agent SDK 0.3.233 and later, the following tools aren't available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, or later versions of those families unless you opt in:
2520
2521 * `TodoWrite`
2522 * `TaskCreate`
2523 * `TaskGet`
2524 * `TaskUpdate`
2525 * `TaskList`
2526
2527 On other models, Claude Code provides the Task tools by default and `TodoWrite` only when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
2528
2529 See [Model availability](/docs/en/agent-sdk/todo-tracking#model-availability) to opt in and [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code.
25202530</Note>
25212531
25222532### TaskCreate
from line 3441
34313441Returns the previous and updated task lists.
34323442
34333443<Note>
3434 As of TypeScript Agent SDK 0.3.142, `TodoWrite` is disabled by default. Use `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList` instead. See [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code, or set `CLAUDE_CODE_ENABLE_TASKS=0` to revert to `TodoWrite`.
3444 On TypeScript Agent SDK 0.3.233 and later, the following tools aren't available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, or later versions of those families unless you opt in:
3445
3446 * `TodoWrite`
3447 * `TaskCreate`
3448 * `TaskGet`
3449 * `TaskUpdate`
3450 * `TaskList`
3451
3452 On other models, Claude Code provides the Task tools by default and `TodoWrite` only when you set `CLAUDE_CODE_ENABLE_TASKS=0`.
3453
3454 See [Model availability](/docs/en/agent-sdk/todo-tracking#model-availability) to opt in and [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) to update your monitoring code.
34353455</Note>
34363456
34373457### TaskCreate
from line 4474
44544474
44554475### `SDKTaskStartedMessage`
44564476
4457Emitted when a background task begins. The `task_type` field is `"local_bash"` for background Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, or `"remote_agent"`.
4458
4459```typescript theme={null}
4460type SDKTaskStartedMessage = {
4461 type: "system";
4462 subtype: "task_started";
4463 task_id: string;
4464 tool_use_id?: string;
4465 description: string;
4466 task_type?: string;
4467 uuid: UUID;
4468 session_id: string;
4469};
4470```
4471
4472### `SDKTaskProgressMessage`
4473
4474Emitted periodically while a subagent or background task is running. The `summary` field is populated only when [`agentProgressSummaries`](#option
4477Emitted when a background task begins. The `task_
agent-teams Changed · +10 / -8 lines
from line 35
3535 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" />
3636</Frame>
3737
38| | Subagents | Agent teams |
39| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |
40| **Context** | Own context window; results return to the caller | Own context window; fully independent |
41| **Communication** | Report results back to the main agent only | Teammates message each other directly |
42| **Coordination** | Main agent manages all work | Shared task list with self-coordination |
43| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
44| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
38| | Subagents | Agent teams |
39| :---------------- | :----------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
40| **Context** | Own context window; results return to the caller | Own context window; fully independent |
41| **Communication** | Report results back to the main agent only | Teammates message each other directly |
42| **Coordination** | Main agent manages all work | Self-coordination through messages, plus a shared task list for [agents that have the Task tools](/docs/en/tools-reference#task-tool-availability) |
43| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
44| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
4545
4646Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.
4747
from line 175
175175
176176The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.
177177
178Agents [without the Task tools](/docs/en/tools-reference#task-tool-availability) coordinate through messages instead of the shared task list.
179
178180The lead can assign tasks explicitly, or teammates can self-claim:
179181
180182* **Lead assigns**: tell the lead which task to give to which teammate
from line 256
254256Spawn a teammate using the security-reviewer agent type to audit the auth module.
255257```
256258
257The teammate honors that definition's `tools` allowlist and `model`, and the definition's body is appended to the teammate's system prompt as additional instructions rather than replacing it. Team coordination tools such as `SendMessage` and the task management tools are always available to a teammate even when `tools` restricts other tools.
259The teammate honors that definition's `tools` allowlist and `model`, and the definition's body is appended to the teammate's system prompt as additional instructions rather than replacing it. For an in-process teammate, Claude Code adds `SendMessage` to that allowlist. In a [session that has the Task tools](/docs/en/tools-reference#task-tool-availability), Claude Code adds `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` to it too.
258260
259261<Note>
260262 The `skills` and `mcpServers` frontmatter fields in a subagent definition are not applied when that definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings, the same as a regular session.
env-vars Changed · +3 / -2 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 259
259259| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Set to `1` to populate the `/model` picker from your gateway's `/v1/models` endpoint when `ANTHROPIC_BASE_URL` points at an Anthropic-compatible gateway such as LiteLLM, Kong, or an internal proxy. Off by default because gateways backed by a shared API key would otherwise show every user every model the key can access. Discovered models are still filtered by an [`availableModels`](/docs/en/settings#available-settings) allowlist the session receives; deliver the list through [MDM or a managed settings file](/docs/en/settings#settings-files), since [server-managed delivery is not available on gateway configurations](/docs/en/server-managed-settings#platform-availability) |
260260| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | Removed in v2.1.142, when the [fast mode](/docs/en/fast-mode) default moved from Opus 4.6 to Opus 4.7 |
261261| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Set to `false` to disable prompt suggestions (the "Prompt suggestions" toggle in `/config`). These are the grayed-out predictions that appear in your prompt input. Takes precedence over the [`promptSuggestionEnabled`](/docs/en/settings#available-settings) setting. See [Prompt suggestions](/docs/en/interactive-mode#prompt-suggestions) |
262| `CLAUDE_CODE_ENABLE_TASKS` | Controls whether sessions use the structured Task tools (`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`) or the legacy `TodoWrite` tool. Task tools are the default in all modes. Set to `0` to use `TodoWrite`. See [Task list](/docs/en/interactive-mode#task-list) and [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) |
262| `CLAUDE_CODE_ENABLE_TASKS` | Selects which task-tracking tools Claude Code provides in [sessions that have them](/docs/en/tools-reference#task-tool-availability). By default, Claude Code provides the Task tools `TaskCreate`, `TaskUpdate`, `TaskGet`, and `TaskList`. Set to `0` to get the legacy `TodoWrite` tool instead. See [Task list](/docs/en/interactive-mode#task-list) and [Migrate to Task tools](/docs/en/agent-sdk/todo-tracking#migrate-to-task-tools) |
263263| `CLAUDE_CODE_ENABLE_TELEMETRY` | Set to `1` to enable OpenTelemetry data collection for metrics and logging. Required before configuring OTel exporters. See [Monitoring](/docs/en/monitoring-usage) |
264| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | Set to `1` to get the task-tracking tools on the models listed under [Task tool availability](/docs/en/tools-reference#task-tool-availability), where Claude Code otherwise leaves them out. `CLAUDE_CODE_ENABLE_TASKS` still selects the Task tools or `TodoWrite`. Requires Claude Code v2.1.233 or later |
264265| `CLAUDE_CODE_EXIT_AFTER_STOP_DELAY` | Time in milliseconds to wait after the query loop becomes idle before automatically exiting. Useful for automated workflows and scripts using SDK mode |
265266| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Set to `1` to enable [agent teams](/docs/en/agent-teams). Agent teams are experimental and disabled by default |
266267| `CLAUDE_CODE_EXTRA_BODY` | JSON object to merge into the top level of every API request body. Useful for passing provider-specific parameters that Claude Code doesn't expose directly. A value exported in your shell also applies to the [background sessions](/docs/en/agent-view) you dispatch with `claude agents` or `--bg`. Before v2.1.206, background sessions ignored a shell-exported value and used whatever copy the background supervisor process inherited |
from line 340
339340| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | Set to `1` to skip the client-side [fast mode](/docs/en/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) availability check, for proxies that intercept the check's request rather than refuse it. The API still rejects fast mode requests when your organization has fast mode disabled |
340341| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Skip Azure authentication for Microsoft Foundry, for a proxy or gateway that injects its own `Authorization` header. Claude Code sends requests without an Azure credential and preserves the `Authorization` header you supply, for example through `ANTHROPIC_CUSTOM_HEADERS`. Ignored when `ANTHROPIC_FOUNDRY_API_KEY` or `ANTHROPIC_FOUNDRY_AUTH_TOKEN` is set. Before v2.1.203, this variable left the Microsoft Foundry client unable to send requests unless an API key was also set |
341342| `CLAUDE_CODE_SKIP_MANTLE_AUTH` | Skip AWS authentication for Amazon Bedrock Mantle (for example, when using an LLM gateway) |
342| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Set to `1` to skip writing prompt history and session transcripts to disk. Sessions started with this variable set do not appear in `--resume`, `--continue`, or up-arrow history. Useful for ephemeral scripted sessions |
343| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Google authentication for Google Cloud's Agent Platform (for example, when using an LLM gateway)
343| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Set to `1` to skip writing prompt history and session transcripts to disk. Sessions started with this variable set do not appear in `--resume`, `--continue`, or up-arrow history. Useful for ephemeral scripted sessions
features-overview Changed · +8 / -8 lines
from line 19
1919* **[Code intelligence](/docs/en/tools-reference#lsp-tool-behavior)** connects Claude to a language server for symbol-level navigation and live type errors
2020* **[MCP](/docs/en/mcp)** connects Claude to external services and tools
2121* **[Subagents](/docs/en/sub-agents)** run their own loops in isolated context, returning summaries
22* **[Agent teams](/docs/en/agent-teams)** coordinate multiple independent sessions with shared tasks and peer-to-peer messaging
22* **[Agent teams](/docs/en/agent-teams)** coordinate multiple independent sessions with peer-to-peer messaging, plus a shared task list for [agents that have the Task tools](/docs/en/tools-reference#task-tool-availability)
2323* **[Hooks](/docs/en/hooks-guide)** run your script, HTTP request, prompt, or subagent when Claude Code reaches a lifecycle event
2424* **[Plugins](/docs/en/plugins)** and **[marketplaces](/docs/en/plugin-marketplaces)** package and distribute these features
2525
from line 123
123123 * **Subagents** run inside your session and report results back to your main context
124124 * **Agent teams** are independent Claude Code sessions that communicate with each other
125125
126 | Aspect | Subagent | Agent team |
127 | ----------------- | ------------------------------------------------ | --------------------------------------------------- |
128 | **Context** | Own context window; results return to the caller | Own context window; fully independent |
129 | **Communication** | Reports results back to the main agent only | Teammates message each other directly |
130 | **Coordination** | Main agent manages all work | Shared task list with self-coordination |
131 | **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
132 | **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
126 | Aspect | Subagent | Agent team |
127 | ----------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
128 | **Context** | Own context window; results return to the caller | Own context window; fully independent |
129 | **Communication** | Reports results back to the main agent only | Teammates message each other directly |
130 | **Coordination** | Main agent manages all work | Self-coordination through messages, plus a shared task list for [agents that have the Task tools](/docs/en/tools-reference#task-tool-availability) |
131 | **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
132 | **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
133133
134134 **Use a subagent** when you need a quick, focused worker: research a question, verify a claim, review a file. The subagent does the work and returns a summary. Your main conversation stays clean.
135135
tools-reference Changed · +20 / -5 lines
## Task tool availability
from line 45
4545| `SendUserFile` | Sends files from the session to you with an optional caption, so a generated report, diagram, screenshot, or built artifact reaches your device instead of only being mentioned in the transcript. As of v2.1.196, the optional `display` input controls presentation: `render` opens the file inline in the client, `attach` shows a download card only, and when unset the client decides by file type. Available when a [Remote Control](/docs/en/remote-control) client is connected or the session runs in a managed cloud environment such as [Claude Code on the web](/docs/en/claude-code-on-the-web). Delivery runs through Anthropic-hosted infrastructure, so the tool is not available on Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry | No |
4646| `ShareOnboardingGuide` | Uploads `ONBOARDING.md` and returns a share link teammates can open in Claude Code. Called from `/team-onboarding` after the guide is written. Available to claude.ai subscribers on Pro, Max, Team, and Enterprise plans | Yes |
4747| `Skill` | Executes a [skill](/docs/en/skills#control-who-invokes-a-skill) within the main conversation | Yes |
48| `TaskCreate` | Creates a new task in the task list | No |
49| `TaskGet` | Retrieves full details for a specific task | No |
50| `TaskList` | Lists all tasks with their current status | No |
48| `TaskCreate` | Creates a new task in the task list. Claude Code leaves it out on the models listed under [Task tool availability](#task-tool-availability) unless you opt in | No |
49| `TaskGet` | Retrieves full details for a specific task. Claude Code leaves it out on the models listed under [Task tool availability](#task-tool-availability) unless you opt in | No |
50| `TaskList` | Lists all tasks with their current status. Claude Code leaves it out on the models listed under [Task tool availability](#task-tool-availability) unless you opt in | No |
5151| `TaskOutput` | Retrieves output from a background task. Deprecated in favor of `Read` on the task's output file path. When no task matches the ID, the error lists the running background agents by ID and description. Before v2.1.203, the error named only the missing ID | No |
5252| `TaskStop` | Stops a running background task by ID. It also accepts an [agent-team teammate](/docs/en/agent-teams) or a named background agent by agent ID or name. Before v2.1.198, it accepted only a background task ID. When no task matches the ID, the error lists the running background agents by ID and description, including agents that another agent spawned. Before v2.1.203, the error listed running teammates and named agents but not background agents another agent spawned, so those couldn't be identified or stopped from the main conversation | No |
53| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks | No |
54| `TodoWrite` | Manages the session task checklist. Disabled by default in favor of `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`. Set `CLAUDE_CODE_ENABLE_TASKS=0` to re-enable | No |
53| `TaskUpdate` | Updates task status, dependencies, details, or deletes tasks. Claude Code leaves it out on the models listed under [Task tool availability](#task-tool-availability) unless you opt in | No |
54| `TodoWrite` | Manages the session task checklist. Disabled by default in favor of `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate`. Set `CLAUDE_CODE_ENABLE_TASKS=0` to re-enable it in [sessions that have the task-tracking tools](#task-tool-availability) | No |
5555| `ToolSearch` | Searches for and loads deferred tools when [tool search](/docs/en/mcp#scale-with-mcp-tool-search) is enabled | No |
5656| `WaitForMcpServers` | Waits for one or more [MCP servers](/docs/en/mcp) that are still connecting in the background, so a request can use their tools without restarting the session. Claude calls it when a needed server isn't connected yet. Only appears when [tool search](/docs/en/mcp#scale-with-mcp-tool-search) is disabled, since `ToolSearch` handles the wait when it's enabled | No |
5757| `WebFetch` | Fetches content from a specified URL. See [WebFetch tool behavior](#webfetch-tool-behavior) | Yes |
from line 410
410410* **Jupyter notebooks**: `.ipynb` files return all cells with their outputs, including code, markdown, and visualizations. Claude Code refuses to read a notebook file over 100 MB; the error tells Claude how to read a portion of the notebook instead, such as a slice of cells, with a shell command.
411411
412412Read only reads files, not directories. Claude lists directory contents with a shell command such as `ls`.
413
414## Task tool availability
415
416In Claude Code v2.1.233 and later, the following tools aren't available on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, or later versions of those families unless you opt in: `TodoWrite`, `TaskCreate`, `TaskGet`, `TaskUpdate`, and `TaskList`. Those models keep track of multi-step work without a written checklist, and the tools' definitions and reminders take up context, so Claude Code leaves them out. Without them, Claude adds nothing to the [task list](/docs/en/interactive-mode#task-list) while it works. On any other model, such as Opus 4.7, Claude Code provides the four Task tools by default and `TodoWrite` only when you set [`CLAUDE_CODE_ENABLE_TASKS=0`](/docs/en/env-vars).
417
418If you'd like to use these tools on one of the listed models anyway, do one of the following:
419
420* Export [`CLAUDE_CODE_ENABLE_TODO_TOOLS=1`](/docs/en/env-vars) before you start Claude Code, for example `CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude`. Claude Code then provides the same tools on every model and every provider
421* Name one of the tools in [`--allowedTools`](/docs/en/cli-reference#cli-flags), for example `claude --allowedTools TaskCreate`
422* List the tools in [`--tools`](/docs/en/cli-reference#cli-flags), which restricts the session's built-in tools to the ones it names. Include the tools you want alongside the other built-in tools you use
423* In the Agent SDK, the [`allowedTools` and `tools` options](/docs/en/agent-sdk/todo-tracking#model-availability) work the same way as the two flags
424
425In [background sessions](/docs/en/agent-view) and in [Claude Code on the web](/docs/en/claude-code-on-the-web), Claude Code provides the same tools on every model, listed or not.
426
427Claude Code gives a subagent the tools only when your session has them, even when the subagent runs a different model. An in-process [agent team](/docs/en/agent-teams) teammate follows your session the same way, while a teammate in its own [split pane](/docs/en/agent-teams#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides. Without the Task tools, an agent coordinates with its team through messages instead of the [shared task list](/docs/en/agent-teams#assign-and-claim-tasks).
413428
414429## WebFetch tool behavior
415430
agent-sdk/agent-loop Changed · +2 / -0 lines
from line 145
145145| **Discovery** | `ToolSearch` | Dynamically find and load tools on-demand instead of preloading all of them |
146146| **Orchestration** | `Agent`, `Skill`, `AskUserQuestion`, `TaskCreate`, `TaskUpdate` | Spawn subagents, invoke skills, ask the user, track tasks |
147147
148On the [models that don't get the task-tracking tools](/docs/en/agent-sdk/todo-tracking#model-availability), Claude Code provides `TaskCreate` and `TaskUpdate` only when you opt in.
149
148150Beyond built-in tools, you can:
149151
150152* **Connect external services** with [MCP servers](/docs/en/agent-sdk/mcp) (databases, browsers, APIs)
hooks Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 2251
22512251
22522252### TaskCreated
22532253
2254Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created.
2254Runs when a task is being created via the `TaskCreate` tool. Use this to enforce naming conventions, require task descriptions, or prevent certain tasks from being created. In a [session without the Task tools](/docs/en/tools-reference#task-tool-availability), this event doesn't fire.
22552255
22562256TaskCreated hooks don't support matchers and fire on every occurrence.
22572257
from line 3221
32213221| `model` | no | Model to use. Defaults to a fast model |
32223222| `timeout` | no | Timeout in seconds. Default: 60 |
32233223
3224The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on the same event; agent hooks have no `continueOnBlock` field, and don't support the prompt-hook `impossible` field.
3224The response schema is `{ "ok": true }` to allow or `{ "ok": false, "reason": "..." }` to block. On `ok: false`, Claude Code handles an agent hook the way it handles a [prompt hook with `continueOnBlock: true`](#response-schema) on t
interactive-mode Changed · +2 / -0 lines
from line 399
399399
400400The task list is Claude's to-do checklist: items Claude created to plan multi-step work, with indicators showing what's pending, in progress, or complete. It's separate from the background-task view. To see running shells and subagents, use [`/tasks`](/docs/en/commands) instead.
401401
402On [Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and later versions of those families](/docs/en/tools-reference#task-tool-availability), Claude keeps track of multi-step work without a written checklist, and Claude Code doesn't provide the tools that fill this list, so it stays empty. If you'd like the task list on those models anyway, opt in with `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` or one of the other ways under [Task tool availability](/docs/en/tools-reference#task-tool-availability). On earlier models such as Opus 4.7, and after you opt in, the task list works as follows:
403
402404* Press `Ctrl+T` to toggle the task list view. The display shows up to five tasks at a time. When Claude hasn't created any checklist items yet, the toggle has no visible effect because there's nothing to display
403405* To see all tasks or clear them, ask Claude directly: "show me all tasks" or "clear all tasks"
404406* Tasks persist across context compactions, helping Claude stay organized on larger projects
sub-agents Changed · +2 / -0 lines
from line 346
346346
347347Teammates in [agent teams](/docs/en/agent-teams) additionally keep the task tools and cron tools: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete`, and `CronList`.
348348
349In a [session without the Task tools](/docs/en/tools-reference#task-tool-availability), Claude Code doesn't provide the task tools to subagents either, even when the subagent runs a different model. An in-process teammate follows your session the same way, while a teammate in its own [split pane](/docs/en/agent-teams#choose-a-display-mode) runs as a separate Claude Code process, so its own model decides.
350
349351To restrict tools, use the `tools` field as an allowlist or the `disallowedTools` field as a denylist. This example uses `tools` to allow only Read, Grep, Glob, and Bash. The subagent can't edit files, write files, or use any MCP tools:
350352
351353```yaml theme={null}