Skip to main content
Claude Code 默认仅在模型可用性下列出的模型上提供任务跟踪工具。较新的模型无需书面待办事项列表即可跟踪多步骤工作,因此在这些模型上,您不需要本页面上的任何内容即可让 Claude 完成多步骤任务。 在具有任务跟踪工具的会话中,Claude 保持书面待办事项列表,在工作时更新每个项目的状态。您在消息流中看到每个更改作为结构化工具调用。仅当您的应用程序读取这些工具调用时才选择加入会话,无论是记录任务活动还是呈现自己的进度显示。

模型可用性

The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn’t recognize, they aren’t available unless you opt in:
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
Wherever the tools are available, Claude Code provides the four Task tools, or TodoWrite instead when you set CLAUDE_CODE_ENABLE_TASKS=0.This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.
在默认情况下没有这些工具的模型上,除非您选择加入会话,否则您在消息流中看不到这些工具的 tool_use 块。Agent SDK 通过它捆绑的 Claude Code 二进制文件应用这些默认值。如果您将 pathToClaudeCodeExecutable(TypeScript)或 cli_path(Python)指向您自己的 Claude Code 安装,您将获得该安装提供的任何工具,在其自己的默认值下。要查看运行中会话中的确切集合,请检查哪些工具可用。要选择加入会话,请执行以下操作之一:
  • allowedTools(TypeScript)或 allowed_tools(Python)选项中命名其中一个工具
  • tools 选项中列出工具,该选项将会话的内置工具限制为它命名的工具。将您想要的工具与您使用的其他内置工具一起包括
  • env 选项中设置 CLAUDE_CODE_ENABLE_TODO_TOOLS=1,如本页面上的示例所做的那样。在 TypeScript 中,env 替换子进程环境,因此展开 ...process.env 以保持继承的变量。在 Python 中,env 合并在继承的环境之上

待办事项生命周期

Claude 将每个待办事项移动通过可预测的生命周期:
  1. 创建:当 Claude 识别任务时,将待办事项添加为 pending
  2. 激活:当 Claude 开始工作时,将待办事项设置为 in_progress
  3. 完成:当任务成功完成时,Claude 将其标记为已完成
  4. 移除:Claude 通过在 TaskUpdate 调用中设置 status: "deleted" 来删除不再需要的待办事项

何时 Claude 创建待办事项

具有任务跟踪工具的会话中,Claude 为大多数多步骤工作创建待办事项,例如:
  • 复杂的多步骤任务需要三个或更多不同的操作
  • 用户提供的任务列表当提到多个项目时
  • 较长的操作受益于进度跟踪
  • 明确的请求当用户要求待办事项组织时
Claude 可能会跳过非常短或单步骤请求的待办事项。

示例

在运行这些示例之前,请按照快速入门安装 Claude Agent SDK。本页面上的每个示例都共享相同的权限设置和退出行为:
  • 权限模式:示例提示要求 Claude 对项目进行真实工作,因此每个示例都设置 permissionMode: "acceptEdits"(TypeScript)或 permission_mode="acceptEdits"(Python)以自动批准工作产生的文件编辑。有关替代方案,请参阅权限模式
  • 轮次限制:每个示例运行直到代理完成并产生其最终结果消息。如果会话首先达到其轮次限制,该结果消息具有 error_max_turns 子类型。检查 subtype 以检测该结束。
  • 错误处理:这些示例使用单次 query() 调用。在产生 error_max_turns 结果后,query() 会抛出一个包含 Reached maximum number of turns 的错误。每个示例都将其循环包装在 try 块中,以便在发生这种情况时干净地退出。有关结果子类型,请参阅处理结果
任务系统消息,SDKTaskNotificationMessage(TypeScript)或 TaskNotificationMessage(Python)等,报告后台任务,例如后台命令和子代理。在消息流中,您看到待办事项活动作为助手消息中的 tool_use 块。

监控待办事项变化

以下示例监视助手流中的 TaskCreateTaskUpdate tool_use 块,并为每个新任务的主题打印一条 + 行,为每个状态更改的任务 ID 和新状态打印一条更新行。当您想要任务活动的日志而不是呈现的显示时,请使用此形状。+ 行不包括分配的 ID,因此此日志无法将更新与其创建相匹配。要保持该关联,请按照实时显示进度所做的那样捕获 ID。 流式传输的 tool_use 输入是模型发出的原始形状。Claude Code 在执行前修复一些接近但不正确的键名,将 idtask_id 映射到 taskId,将 active_form 映射到 activeForm,但该修复不会反映在流中。防御性地读取 TaskUpdate 输入字段,如本页面上的两个示例所做的那样,而不是假设规范名称始终存在。

实时显示进度

以下示例监视助手流中的 TaskCreateTaskUpdate tool_use 块,并在 TaskTracker 类中保持由任务 ID 键入的任务映射,在每次更改时重新呈现进度摘要。摘要计算已完成和进行中的任务,并显示每个活跃项目的 activeForm 标签代替其 subject。当您的应用程序维护进度显示而不是记录每个事件时,请使用此形状。 分配的任务 ID 不在 TaskCreate 输入中。Claude Code 在携带其 tool_result 块的用户消息上传递每个工具的结构化输出,在 tool_use_result 字段中。对于 TaskCreate,该对象在 TypeScript 中记录为工具输出类型下的 TaskCreateOutput,在 Python 中该字段是相同形状的普通字典。跟踪器通过 tool_use_id 将每个 tool_result 块与其 tool_use 调用配对,并从配对消息的 tool_use_result 中读取 task.id。Claude 可以使用 TaskList 读取列表,使用 TaskGet 读取一个任务的完整详细信息。