Todo 追踪

SDK 内置 TodoWrite 工具，当任务涉及 3 个或以上步骤时，Claude 会自动创建 Todo 列表追踪进度。通过监听消息流中的 TodoWrite 工具调用，可以实时展示任务进度。

核心机制

Todo 生命周期：pending（已识别）→ in_progress（进行中）→ completed（已完成）→ 移除（全部完成后）。

自动触发条件：

• 复杂多步骤任务（3 个或以上步骤）
• 用户提供的任务列表
• 非简单操作（需要进度追踪的任务）
• 用户明确要求 Todo 组织

监听方式：检查 AssistantMessage 中 tool_use 类型且 name == "TodoWrite" 的内容块，block.input.todos 包含完整 Todo 列表。

新版 Task 工具（预览）：通过 CLAUDE_CODE_ENABLE_TASKS=1 启用，将 TodoWrite 拆分为 TaskCreate（新建）和 TaskUpdate（更新状态），提供更细粒度的任务管理。

关键细节

监听 Todo 变更：

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
 
async for message in query(
    prompt="Optimize my React app performance and track progress with todos",
    options=ClaudeAgentOptions(max_turns=15),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
                todos = block.input["todos"]
                for todo in todos:
                    status = "✅" if todo["status"] == "completed" else "🔧" if todo["status"] == "in_progress" else "⏳"
                    print(f"{status} {todo['content']}")

Todo 对象字段：

• content：任务描述
• status："pending" / "in_progress" / "completed"
• activeForm：进行中时的动态描述（如 “Analyzing performance bottlenecks…“）

迁移到 Task 工具：

# 启用新版 Task 工具
options = ClaudeAgentOptions(env={"CLAUDE_CODE_ENABLE_TASKS": "1"})
 
# 监听方式变化
if block.name == "TaskCreate":
    print(f"+ {block.input['subject']}")
elif block.name == "TaskUpdate" and block.input.get("status"):
    print(f"  {block.input['taskId']} -> {block.input['status']}")

与其他概念的关联

• agent-loop - TodoWrite 是 AssistantMessage 中的工具调用
• streaming-output - 实时显示 Todo 状态变化

实践要点

• TodoWrite 每次调用会重写完整 todos 数组，不是增量更新
• 新版 Task 工具中，TaskCreate 的 task ID 在对应的 tool_result 中返回，不在 input 中
• 可以在 prompt 中明确要求 Claude 使用 Todo 追踪进度
• Todo 追踪主要用于展示给用户，不影响 Agent 的实际执行逻辑