# 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#