# Useful but Little-Known Features of Claude Agent SDK 🌍 Losing track of complex multi-step tasks? Structured task tracking makes progress visible! Claude Agent SDK includes built-in task management for organized progress tracking during agent execution. 📌 Title: Structured Task (Todo) Tracking 🔗 URL: 🧩 Overview Four tools — `TaskCreate`, `TaskUpdate`, `TaskGet`, and `TaskList` — enable structured task management during agent execution. These task-tracking 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 (the default set in Claude Code v2.1.268 and later, bundled by the TypeScript SDK from v0.3.268); on every other model you must opt the session in. The agent automatically registers multi-step work as tasks and manages their lifecycle: `pending` → `in_progress` → `completed`. Unlike the legacy `TodoWrite` which overwrote the entire list on every call, Task tools operate on individual items, enabling fine-grained progress tracking. 🛠 How to Use ```python # Python - Monitor TaskCreate/TaskUpdate in the stream from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock async for message in query( prompt="Optimize my React app performance", # Keeps the Task tools on models where Claude Code otherwise doesn't provide them options=ClaudeAgentOptions(env={"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"}), ): if not isinstance(message, AssistantMessage): continue for block in message.content: if not isinstance(block, ToolUseBlock): continue if == "TaskCreate": print(f"+ {block.input['subject']}") elif == "TaskUpdate" and block.input.get("status"): # The streamed input is the raw shape the model emitted (may be id / task_id) task_id = ( block.input.get("taskId") or block.input.get("id") or block.input.get("task_id") ) print(f" {task_id} -> {block.input['status']}") ``` ```typescript // TypeScript - Display task creation and updates in real time import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Optimize my React app performance", // Keeps the Task tools on models where Claude Code otherwise doesn't provide them options: { env: { ...process.env, CLAUDE_CODE_ENABLE_TODO_TOOLS: "1" } }, })) { if (message.type !== "assistant") continue; for (const block of message.message.content) { if (block.type !== "tool_use") continue; if ( === "TaskCreate") { console.log(`+ ${block.input.subject}`); } else if ( === "TaskUpdate") { // The streamed input is the raw shape the model emitted (may be id / task_id) const taskId = block.input.taskId ?? ?? block.input.task_id; if (taskId && block.input.status) console.log(` ${taskId} -> ${block.input.status}`); } } } ``` 🏗 Integration into Production Systems - Reflect task progress in UI progress bars or checklists to give users visibility into agent work - Capture `taskId` from `TaskCreate` tool results and maintain a map for a complete task overview - Monitor `TaskList` tool results for snapshots to display on dashboards - Tasks are automatically created for 3+ step workflows, making them ideal for monitoring long-running operations 💡 Use Cases 📋 Share large-scale refactoring progress with the team in real time 🔄 Track completion status of each agent step in CI/CD pipelines 📊 Display which analyses are complete on a dashboard during multi-step code review ⚠️ Caveats - `TaskCreate` input does not contain `taskId`; retrieve it from the corresponding `tool_result` block as `{ task: { id, subject } }` - On models that don't have the tools by default, opt the session in by naming a tool in `allowed_tools`, listing the tools in the `tools` option, or setting `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` in `env` — without opting in, no `tool_use` blocks for them appear in the stream. Conversely, `CLAUDE_CODE_ENABLE_TASKS=0` makes Claude Code provide the legacy `TodoWrite` instead of the four Task tools - Setting `status` to `"deleted"` removes a task ✨ Waiting for multi-step work without knowing what's happening is stressful. Use task tracking to make your agent's work fully transparent! #ClaudeAgentSDK# #AIAgent#