Skip to main content
Claude Code は、モデル利用可能性に記載されているモデルでのみデフォルトでタスク追跡ツールを提供します。新しいモデルは書かれた todo リストなしで複数ステップの作業を追跡するため、これらのモデルでは Claude が複数ステップのタスクを処理するためにこのページの内容は必要ありません。 タスク追跡ツールを持つセッションでは、Claude は書かれた todo リストを保持し、作業を進めるにつれて各アイテムのステータスを更新します。メッセージストリーム内で各変更が構造化されたツール呼び出しとして表示されます。アプリケーションがこれらのツール呼び出しを読み取る場合にのみセッションをオプトインしてください。タスク活動をログするか、独自の進捗表示をレンダリングするかどうかに関わらず。

モデル利用可能性

以下のツールは、デフォルトでは Claude Opus 4.7、Claude Sonnet 4.6、Claude Haiku 4.5、およびそれ以前のモデルでのみ利用可能です。その他のすべてのモデル(Claude Code が認識しないモデル ID を含む)では、オプトインしない限り利用できません。
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
ツールが利用可能な場所では、Claude Code は 4 つの Task ツールを提供します。CLAUDE_CODE_ENABLE_TASKS=0 を設定した場合は、代わりに TodoWrite を提供します。このデフォルトセットは Claude Code v2.1.268 以降に適用されます。これは TypeScript Agent SDK が v0.3.268 からバンドルしています。
デフォルトではツールを持たないモデルでは、セッションをオプトインしない限り、メッセージストリーム内でこれらのツールの tool_use ブロックは表示されません。Agent SDK は、バンドルされている Claude Code バイナリを通じてこれらのデフォルトを適用します。pathToClaudeCodeExecutable(TypeScript)または cli_path(Python)を独自の Claude Code インストールに指定する場合、そのインストールが提供するツールが、独自のデフォルトの下で取得されます。実行中のセッションで正確なセットを確認するには、利用可能なツールを確認してください。セッションをオプトインするには、以下のいずれかを実行してください:
  • allowedTools(TypeScript)または allowed_tools(Python)オプションでツールの 1 つに名前を付ける
  • tools オプションにツールをリストします。これはセッションの組み込みツールを、それが名前を付けるものに制限します。使用する他の組み込みツールと一緒に必要なツールを含めます
  • このページの例のように、env オプションで CLAUDE_CODE_ENABLE_TODO_TOOLS=1 を設定します。TypeScript では、env はサブプロセス環境を置き換えるため、継承された変数を保持するために ...process.env を展開します。Python では、env は継承された環境の上にマージされます

Todo ライフサイクル

Claude は各 todo を予測可能なライフサイクルを通じて移動させます:
  1. 作成:Claude がタスクを識別したときに pending として todo を追加します
  2. アクティベート:Claude が作業を開始したときに todo を in_progress に設定します
  3. 完了:Claude がタスクが正常に完了したときにそれを完了としてマークします
  4. 削除:Claude が TaskUpdate 呼び出しで status: "deleted" を設定することで、不要になった todo を削除します

Claude が todo を作成するとき

タスク追跡ツールを持つセッションでは、Claude は以下のような複数ステップの作業のほとんどに対して todo を作成します:
  • 複雑な複数ステップのタスク - 3 つ以上の異なるアクションが必要な場合
  • ユーザー提供のタスクリスト - 複数のアイテムが言及されている場合
  • より長い操作 - 進捗追跡の恩恵を受ける場合
  • 明示的なリクエスト - ユーザーが todo 整理を要求する場合
Claude は非常に短いまたは単一ステップのリクエストに対しては todo をスキップする場合があります。

例

これらの例を実行する前に、クイックスタートに従って 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)を含むものは、バックグラウンドコマンドやサブエージェントなどのバックグラウンドタスクを報告します。メッセージストリーム内では、todo アクティビティがアシスタントメッセージ内の tool_use ブロックとして表示されます。

Todo 変更を監視する

次の例はアシスタントストリームで TaskCreate と TaskUpdate の tool_use ブロックを監視し、各新しいタスクの件名を含む + 行と各ステータス変更のタスク ID と新しいステータスを含む更新行を出力します。タスク活動のログが必要で、レンダリングされた表示ではない場合、この形状を使用してください。+ 行は割り当てられた ID を含まないため、このログは更新を作成に一致させることはできません。その相関を保つには、リアルタイムで進捗を表示するのように ID をキャプチャしてください。 ストリーミングされた tool_use 入力は、モデルが発行した生の形状です。Claude Code は実行前にいくつかの近いが正確でないキー名を修復し、id または task_id を taskId にマッピングし、active_form を activeForm にマッピングしますが、その修復はストリームに反映されません。以下の両方の例のように、常に正規名が存在すると仮定するのではなく、TaskUpdate 入力フィールドを防御的に読み取ります。

リアルタイムで進捗を表示する

次の例はアシスタントストリームで TaskCreate と TaskUpdate の 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 で 1 つのタスクの完全な詳細を読み取ることができます。