Claude Agent SDK Python｜TodoWrite 廃止と Task tools 移行

結論 ── Claude Agent SDK Python v0.2.82 で TodoWrite は廃止、Task tools への移行が必要

Claude Agent SDK Python のリリースノート によれば、2026-05-15 03:47 UTC に v0.2.82 がリリースされ、それまで Todo 系の進捗管理を一手に担っていた TodoWrite ツールが完全に削除されました。代わりに導入されたのが、TaskCreate(作成)・TaskUpdate(更新)・TaskGet(取得)・TaskList(一覧)の 4 つのツールで、CRUD の責務を明示的に分割した形になっています。これは Anthropic が Claude Agent SDK Python の公式ドキュメント と Todo Tracking ガイド でアナウンスしている通り、長期的な API 安定化と Managed Agents との整合を取るための一手です。

影響を受けるのは、TodoWrite を直接呼び出すツール定義を書いているコード、戻り値を独自にパースしている運用ロジック、そして Anthropic がリリースした SDK の最新版を自動的に取り込むタイプの内製ボットです。とくにヘッドレスセッションを動かしている運用チームでは、Python パッケージのバージョンを固定していないと、次回 pip install --upgrade の瞬間に TodoWrite が消えて ImportError で停止する事態が発生しえます。先に SDK のバージョンを ==0.2.81 で固定してから順序立てて移行するのが安全です。

影響範囲の早見表 ── あなたのコードに移行が必要か 30 秒で判定する

最初にやるべきは「自分のコードが Breaking Change の射程に入っているか」の見極めです。以下の表で、上から順に YES/NO を確認してください。1 つでも YES があれば移行作業が必要、すべて NO なら SDK アップグレードだけで動き続けます。

利用中の SDK バージョンを 1 コマンドで確認する

判定の前提として、いま自分の環境がどのバージョンを使っているかを確実に把握します。Python の仮想環境を起動した状態で次を実行してください。Version 行に 0.2.82 以降が表示されたら、すでに新 API へ切り替わっているはずなので破壊変更の射程内です。0.2.81 以前なら旧 API がまだ生きていますが、いつアップグレードが走るか分からないため移行準備を進めるべき状態と言えます。

pip show claude-agent-sdk
# Name: claude-agent-sdk
# Version: 0.2.82

戻り値の使い方別に影響度を仕分けする

TodoWrite の戻り値をどう扱っていたかで作業量は大きく変わります。戻り値を完全に無視していたコードは API 名を差し替えるだけで済みます。表示用に最新の Todo リストを引っ張っていた場合は TaskList の戻り値スキーマを読み替える必要があります。データベースなどに永続化していたコードは、フィールド名が todos から tasks に変わったこと、task_id が追加されたこと、status の取りうる値が pending / in_progress / completed / cancelled に整理されたことを反映しないと、保存ロジックが壊れます。

実装マッピング ── TodoWrite から TaskCreate / TaskUpdate / TaskGet / TaskList への置き換え手順

ここからは具体的なコード差分を見ていきます。まず旧 API と新 API の対応関係を一覧で押さえ、その後に段階置換のテンプレートを示します。Anthropic 公式の Todo Tracking ガイド(日本語) も同じ並びで解説しているので、本記事と照らし合わせて読むと迷いが減ります。

段階置換テンプレ ── import から戻り値解釈まで 5 ステップで進める

破壊変更を一度に当てると差分が肥大化してレビューが回らなくなります。次の順序で、コミットを分けながら進めるのが安全です。

1. import 修正: from claude_agent_sdk import TodoWrite を from claude_agent_sdk import TaskCreate, TaskUpdate, TaskGet, TaskList に置換し、まずビルドを通す。
2. ツールリスト更新: エージェントの tools= に渡している配列から TodoWrite を外し、新 4 ツールを追加。CLAUDE_CODE_ENABLE_TASKS=1 を環境変数に立ててから動作確認する。
3. 呼び出し置換: 既存の TodoWrite(todos=...) を TaskCreate の連続呼び出しに分解し、戻り値の task_id を辞書か dataclass に蓄積する。
4. 戻り値解釈の差分対応: 旧コードで todos[i].status を読んでいた箇所を、TaskList() または TaskGet(task_id) の戻り値スキーマに合わせて修正する。
5. テスト更新: スナップショットテストや VCR ベースのテストは旧 API のレスポンス JSON を保持しているため、固定値を新スキーマに書き換える。

このうち、もっとも事故りやすいのが Step 4 です。status の取りうる値が pending / in_progress / completed / cancelled に整理されたため、旧 API で in-progress(ハイフン)を保存していたデータは突合に失敗します。マイグレーションスクリプトを 1 本書いて、既存データの status 列を _ 区切りに正規化しておくと安全です。

落とし穴 ── stderr コールバック分離と CancelledError

claude-agent-sdk-python issue #309 で議論されている通り、v0.2.82 では stderr コールバックが Task 系ツールの完了コールバックから分離されました。旧コードで「Todo の完了タイミングで stderr のフラッシュも兼ねていた」場合、新 API では別経路で発火するので、ログが順序ズレして見えるケースがあります。さらに eager-flush モードの完了コールバック内で asyncio.CancelledError を握り潰していると、TaskUpdate が中途半端な状態で残って TaskList がゴーストタスクを返す挙動が確認されています。コールバック内では CancelledError を再送出するように修正してください。

CLAUDE_CODE_ENABLE_TASKS=1 フラグと段階移行の進め方

新 Task tools は、いきなり強制適用ではなく オプトインフラグ として導入されています。検証環境で安全に新 API を試してから本番投入できる設計です。フラグは環境変数 CLAUDE_CODE_ENABLE_TASKS=1 で有効化します。

# 1. シェルから一時的に有効化(検証用)
export CLAUDE_CODE_ENABLE_TASKS=1
python my_agent.py

# 2. .env ファイル経由で永続化
echo "CLAUDE_CODE_ENABLE_TASKS=1" >> .env

# 3. ヘッドレスセッション起動時に明示的に渡す
CLAUDE_CODE_ENABLE_TASKS=1 python -m claude_agent_sdk.session start

部分有効化で A/B 動作を比較する

フラグをセッション単位で切り替えられるため、同じ入力を新旧両方の経路で走らせて差分を観察する A/B が組めます。本番投入前にこのステップを 1 回挟んでおくと、戻り値スキーマの食い違いや status 列の正規化漏れを実環境のログから検出できます。とくに Anthropic 公式が提供している Agent SDK Python のドキュメント に書かれている EffortLevel 型の公開を活かすと、A/B 比較ログに型情報をそのまま流し込めるので、レビュー時の見通しが上がります。

チームへのロールアウト推奨フェーズ

ロールアウトは次の順序で 1 週間かけて進めるのが現実的です。一気に本番へ当てると、戻り値スキーマの食い違いで運用ボットが沈黙する事故が起きえます。

1. 検証環境(Day 1-2): 開発者の手元と CI で CLAUDE_CODE_ENABLE_TASKS=1 を立て、テストとサンプル運用ログを通す。
2. ステージング(Day 3-4): 本番相当のデータでヘッドレスセッションを 24 時間動かし、TaskList のスナップショット差分を朝夕で比較する。
3. 本番カナリア(Day 5): 全体の 10〜20% のセッションでフラグを ON にし、エラーレート・遅延・トークン使用量を旧経路と比較する。
4. 本番フルロールアウト(Day 6-7): 全セッションでフラグ ON、SDK バージョン固定を ==0.2.82 に切り替え。
5. 旧 API 削除(Day 8 以降): コードベースから TodoWrite の import と関連テストを完全削除する。

ロールバック手順 ── 二段構えで素早く戻す

フルロールアウト後に問題が発覚した場合は、二段でロールバックします。第一段が「フラグだけ解除」、第二段が「SDK バージョン自体を ==0.2.81 にダウングレード」です。フラグ解除だけで戻せるなら SDK のリリースサイクルに依存せず短時間で復旧でき、ライブラリ側に致命的な不具合が見つかった場合のみ第二段に進みます。本番のロールバックは Anthropic Console のセッションログで TaskCreate 呼び出しを止めてから行うと、孤児タスクの発生を防げます。

移行後のベストプラクティスと運用 Tips ── ヘッドレスセッションでの安定運用

新 API への切り替えが終わったら、運用面で押さえておきたい 4 点があります。短期的に「動く」だけでなく、半年後にチームメンバーが入れ替わっても安定して動かし続けるための知見です。

EffortLevel 型公開を活かして型安全に書く

v0.2.82 では EffortLevel 型が公開され、low / medium / high の 3 段階を Literal 型として import できるようになりました。これにより、エージェントに渡すパラメータの型注釈が厳密になり、mypy や pyright で EffortLevel = "med" のようなタイプミスを CI が拾えます。TaskCreate や TaskUpdate の引数として渡すだけでなく、自前のラッパー関数のシグネチャにも組み込んでおくと、ヘッドレス運用時の事故が減ります。

MCP サーバー背景接続との併用注意点

Claude Agent SDK Python は MCP(Model Context Protocol)サーバーをバックグラウンド接続する仕組みを併せ持っており、新 Task tools と組み合わせる際に挙動の癖があります。MCP 接続が status: "pending" のまま、TaskCreate が先に発火するケースが報告されており、Task が作成された直後に MCP リソースを参照しようとすると ResourceNotReady 例外が出ます。対策は、TaskCreate の前に MCP の status が ready になるまでポーリングする小さなヘルパーを挟むことです。

同梱 Claude CLI v2.1.142 への自動アップデートで起きる差分

Claude Agent SDK Python v0.2.82 をインストールすると、同梱の Claude CLI も v2.1.142 にアップデートされます。CLI 側の Help テキストやエラーメッセージのフォーマットがわずかに変わっており、subprocess 経由で出力をパースしている運用スクリプトは正規表現が外れる可能性があります。リリース直後は claude --version と claude --help の出力を CI で固定化し、想定外の差分を早期に検出できる体制を作っておくと安全です。

Claude Code v2.1.143 のプラグイン依存関係強制 / worktree.bgIsolation: "none" 新設

合わせて発表された Claude Code v2.1.143 では、プラグインの依存関係解決が強制化され、package.json に書かれていない依存を require した瞬間に起動エラーが出るようになりました。さらに worktree.bgIsolation: "none" という設定が新設され、複数 worktree を並列で動かす場合に背景プロセスを共有させる選択肢が増えています。Claude Agent SDK Python と Claude Code を組み合わせて運用しているチームは、SDK のアップデートと同じタイミングで Claude Code 側の package.json と設定も棚卸ししておくのがおすすめです。

出典

• Claude Agent SDK Python リリースノート(GitHub)
• Claude Agent SDK Python ドキュメント(英語版)
• Todo Tracking ガイド(日本語版)
• claude-agent-sdk-python issue #309
• Claude Code リリースノート(GitHub)