TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降、セッションは
TodoWrite の代わりに構造化された Task ツール TaskCreate、TaskUpdate、TaskGet、および TaskList を使用します。Python SDK は Python パッケージバージョンではなく、起動する Claude Code CLI からこの変更を取得します。スイッチは、その CLI(pip パッケージ内にバンドルされているコピー、または cli_path で指定するコピー)が v2.1.142 以降の場合に適用されます。監視コードの変更方法については、Task ツールへの移行を参照してください。このページの例では、まだ移行していないセッションの TodoWrite を引き続き表示するために CLAUDE_CODE_ENABLE_TASKS=0 を設定しています。Todo ライフサイクル
Todo は予測可能なライフサイクルに従います:- 作成 - タスクが識別されたときに
pendingとして作成される - アクティベート - 作業が開始されたときに
in_progressに変更される - 完了 - タスクが正常に完了したときに完了する
- 削除 - グループ内のすべてのタスクが完了したときに削除される
Todo が使用される場合
SDK は以下の場合に自動的に todo を作成します:- 複雑なマルチステップタスク - 3 つ以上の異なるアクションが必要な場合
- ユーザー提供のタスクリスト - 複数のアイテムが言及されている場合
- 非自明な操作 - 進捗追跡の恩恵を受ける場合
- 明示的なリクエスト - ユーザーが todo 整理を要求した場合
例
これらの例を実行する前に、クイックスタートに従って Claude Agent SDK をインストールしてください。 各例はエージェントが完了して最終結果メッセージを生成するまで実行されます。セッションがターン制限に最初に達した場合、その結果メッセージはerror_max_turns サブタイプを持ちます。終了を検出するために subtype を確認してください。
これらの例は単一ショットの query() 呼び出しを使用します。error_max_turns 結果を生成した後、query() は Reached maximum number of turns を含むエラーを発生させます。各例はそれが発生したときにクリーンに終了するために、ループを try ブロックでラップします。
結果サブタイプについては、結果を処理するを参照してください。
Todo 変更の監視
リアルタイム進捗表示
Task ツールへの移行
Task ツールは、単一のTodoWrite 呼び出しを、各新規アイテムの TaskCreate と各ステータス変更の TaskUpdate に分割し、TaskList と TaskGet はモデルが現在のリストを読み戻すために利用可能です。監視コードは引き続きアシスタントストリーム内の tool_use ブロックを検査しますが、すべての呼び出しでリスト全体を置き換える代わりに、タスク ID でキー付けされたマップを保持します。Task ツールは TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降のデフォルトであるため、options.env の変更は不要です。
割り当てられたタスク ID は
TaskCreate 入力にはありません。マッチング tool_result で { task: { id, subject } } として返されるため、マップをキー付けするために結果ブロックからそれをキャプチャします。次の例は、Todo 変更の監視ループへの最小限の変更を示しています。ストリーム内の TaskList ツール結果を監視するか、TaskCreate 結果と TaskUpdate 入力をマップに蓄積することで、完全なリストをレンダリングできます。
ストリーミングされた tool_use 入力は、モデルが発行した生の形状です。Claude Code は実行前にいくつかの近いが正確でないキー名を修復し、id または task_id を taskId にマッピングし、active_form を activeForm にマッピングしますが、その修復はストリームに反映されません。以下のサンプルのように、常に正規名が存在すると仮定するのではなく、TaskUpdate 入力フィールドを防御的に読み取ります。