モデル利用可能性
以下のツールは、デフォルトでは Claude Opus 4.7、Claude Sonnet 4.6、Claude Haiku 4.5、およびそれ以前のモデルでのみ利用可能です。その他のすべてのモデル(Claude Code が認識しないモデル ID を含む)では、オプトインしない限り利用できません。
TodoWriteTaskCreateTaskGetTaskUpdateTaskList
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 を予測可能なライフサイクルを通じて移動させます:- 作成:Claude がタスクを識別したときに
pendingとして todo を追加します - アクティベート:Claude が作業を開始したときに todo を
in_progressに設定します - 完了:Claude がタスクが正常に完了したときにそれを完了としてマークします
- 削除:Claude が
TaskUpdate呼び出しでstatus: "deleted"を設定することで、不要になった todo を削除します
Claude が todo を作成するとき
タスク追跡ツールを持つセッションでは、Claude は以下のような複数ステップの作業のほとんどに対して todo を作成します:- 複雑な複数ステップのタスク - 3 つ以上の異なるアクションが必要な場合
- ユーザー提供のタスクリスト - 複数のアイテムが言及されている場合
- より長い操作 - 進捗追跡の恩恵を受ける場合
- 明示的なリクエスト - ユーザーが 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 つのタスクの完全な詳細を読み取ることができます。
関連ドキュメント
- Agent SDK リファレンス - TypeScript:TypeScript SDK のオプション、タイプ、およびツールスキーマ。Task ツール入力および出力タイプを含みます
- Agent SDK リファレンス - Python:Python SDK のオプション、タイプ、およびツールドキュメント
- ストリーミング入力:2 つの入力モード、およびこれらの例が使用する単一ショット呼び出しの代わりにストリーミング入力を使用する場合
- Claude にカスタムツールを提供する:SDK のインプロセス MCP サーバーで独自のツールを定義します