Claude Code TodoツールがOpus 4.8以降で既定オフ — 影響と復活方法
Claude Code v2.1.233以降、Opus 4.8やSonnet 5などの新世代モデルではTodo/Taskツールが既定で使えなくなりました。何に影響し、どう復活させるかをまとめます。
新世代モデルではタスク一覧ツールが既定で消えた
Claude Code v2.1.233から、Opus 4.8・Sonnet 5・Fable 5・Mythos 5、およびそれ以降の各ファミリーのモデルでは、TodoWriteとTaskCreate TaskGet TaskUpdate TaskListのどちらの系統もデフォルトで提供されなくなりました。旧世代のOpus 4.7などでは今まで通りTask系4ツールが既定で使え、これは新世代モデルだけに起きる変更です。
タスクを書き出すツール自体が渡されないため、Claudeは何段階かの作業をしていても、チェックリストへの追加を一切しません。タスクを管理していないわけではなく、書き出す先が無い状態になります。
なぜ既定で外されたのか
新世代モデルは、書き出したチェックリストが無くても複数ステップの作業を追跡できるようになったというのが公式の説明です。あわせて、ツール定義とツール利用を促すリマインダーがコンテキストを消費するため、Claude Codeは新世代モデルではこれらのツールを渡さない判断をしています。性能上の欠落ではなく、コンテキスト予算の最適化という位置づけです。
実際に何が変わって見えるか
ツールが渡されなくなると、いくつかの機能が連鎖して中身の無い状態になります。エラーは出ないため、気づかないまま運用を続けてしまいがちです。
| 影響箇所 | 新世代モデル(既定) | 旧世代モデル / opt-in後 |
|---|---|---|
セッション内タスク一覧(Ctrl+T) | 新世代モデル(既定)何も表示されない(トグル自体は反応するが空) | 旧世代モデル / opt-in後進行中・完了・保留のチェックリストが見える |
CLAUDE_CODE_TASK_LIST_IDによるタスク共有 | 新世代モデル(既定)共有する中身が無いため実質無効 | 旧世代モデル / opt-in後セッションをまたいで同じタスク一覧を共有できる |
| コンテキスト圧縮後のタスク保持 | 新世代モデル(既定)保持するタスクがそもそも無い | 旧世代モデル / opt-in後タスクは圧縮をまたいで保持される |
TaskCreated Hook | 新世代モデル(既定)発火しない(タスクが作られないため) | 旧世代モデル / opt-in後タスク作成のたびに発火し、拒否や介入ができる |
| Agent teamsの共有タスク一覧 | 新世代モデル(既定)使えず、チームメイトはメッセージで調整 | 旧世代モデル / opt-in後タスクの割り当て・claimで進捗を共有 |
とくにTaskCreated Hookを使って「大きすぎるタスク分割を止める」「特定のタスク名を禁止する」といった制御を組んでいたチームは、対象モデルへ切り替えた瞬間にそのHookが動かなくなります。Hookの発火自体を疑う前に、モデルとバージョンの組み合わせを先に確認する価値があります。イベントの種類や設定方法はClaude Code Hooks完全ガイドにまとめています。
そもそもどんな作業でTodoが作られていたか
既定オフの影響範囲を判断するには、ツールがあった頃にどんな場面でTodoが作られていたかを思い出すと早いです。公式ドキュメントは、Task系ツールがあるセッションでClaudeがTodoを作る典型例として次を挙げています。
- 3ステップ以上の複数アクションが必要な複雑なタスク
- 利用者が複数の項目を一度に伝えたとき(タスクリストをそのまま渡された場合)
- 進捗の追跡が助けになる、些細ではない作業
- Todoで管理してほしいと明示的に頼まれたとき
逆に、ごく短い作業や単発の依頼ではTodoを作らないこともあります。つまり既定オフの影響が最も大きいのは、複数ファイルにまたがる実装や長時間の自走タスクのように、もともとTodoが作られやすかった場面です。単発の質問や小さな修正が中心の使い方なら、既定オフになったこと自体にほとんど気づきません。
CLAUDE_CODE_ENABLE_TODO_TOOLS=1で元に戻す
以前と同じ挙動が欲しい場合は、環境変数CLAUDE_CODE_ENABLE_TODO_TOOLSを1に設定します。これを立てると、モデルやプロバイダーを問わず同じツールセットが提供されます。
export CLAUDE_CODE_ENABLE_TODO_TOOLS=1
claude環境変数の全体像で見ると分かるとおり、似た名前のCLAUDE_CODE_ENABLE_TASKSとは役割が異なる点に注意してください。CLAUDE_CODE_ENABLE_TASKSは「Task系4ツールにするか、レガシーなTodoWrite1本にするか」を選ぶ変数で、対象モデルでツールそのものを渡すかどうかとは無関係です。CLAUDE_CODE_ENABLE_TODO_TOOLS=1だけを立てればCLAUDE_CODE_ENABLE_TASKSは未設定のままでよく、その場合は既定のTask系4ツールが復活します。両方を組み合わせて「対象モデルでもTodoWriteだけを復活させる」という指定も可能です。
環境変数を使わずに、その場のセッション限定で戻す方法もあります。--allowedToolsに対象ツール名を1つ挙げるだけで、Claude Codeはそのセッションをタスクツールありのモードへ切り替えます。
claude --allowedTools TaskCreate--toolsでセッションの組み込みツールを絞り込む場合も、必要なタスクツールを他のツールと一緒に列挙すれば同様に復活します。Agent SDKで開発している場合は、allowedTools / toolsオプションが同じ役割を果たします。
Task系ツールとTodoWriteの違い
タスク管理ツールという括りの中には、実は新旧2つの実装があります。名前が近い環境変数もあり混同しやすいため、対応関係を表にしておきます。
| Task系(既定) | TodoWrite(レガシー) | |
|---|---|---|
| ツール数 | Task系(既定)TaskCreate TaskGet TaskUpdate TaskListの4つ | TodoWrite(レガシー)1つ |
| 更新の単位 | Task系(既定)TaskUpdateがtaskId単位で1件ずつ差分更新 | TodoWrite(レガシー)呼び出すたびにリスト全体を丸ごと書き換え |
| 切り替え方 | Task系(既定)CLAUDE_CODE_ENABLE_TASKSを未設定(既定) | TodoWrite(レガシー)CLAUDE_CODE_ENABLE_TASKS=0 |
| 対象モデルでの既定 | Task系(既定)提供されない(要CLAUDE_CODE_ENABLE_TODO_TOOLS=1) | TodoWrite(レガシー)同左 |
CLIのCtrl+Tによるタスク一覧表示は、どちらの系統を使っていても同じUIに描画されるため、利用者から見た体験差は小さめです。差が出るのはHookやAgent SDKでツール呼び出しを直接監視している場合で、TaskUpdateは1件ずつの差分、TodoWriteは全件書き換えという構造の違いがそのまま監視コードに影響します。
HookやカスタムスクリプトでTaskCreateの呼び出しを監視している場合、割り当てられたタスクIDはTaskCreateの入力そのものには含まれていません。対応するtool_resultに{ task: { id, subject } }という形で返ってくるため、IDを追う実装は結果ブロック側を見る必要があります。この構造を知らずに入力ブロックだけを見ていると、IDが常に空に見えるという分かりにくいハマり方をします。
再有効化するかどうかの判断軸
すべてのチームが復活させる必要はありません。判断材料は3つです。
| 状況 | 対応の目安 |
|---|---|
TaskCreated Hookやタスク一覧を前提にした自動化を組んでいる | 対応の目安CLAUDE_CODE_ENABLE_TODO_TOOLS=1を既定にする |
CLAUDE_CODE_TASK_LIST_IDで複数セッション間のタスクを共有している | 対応の目安同上。共有の中身が空になるため復活させないと運用が壊れる |
とくに監視や自動化はせず、進捗をたまにCtrl+Tで覗く程度 | 対応の目安復活は任意。無くても実害は小さい |
| コンテキスト消費を切り詰めたい、長時間セッションが多い | 対応の目安既定のまま(オフ)にしておくとツール定義分のコンテキストが浮く |
Hookやタスク共有に依存していないなら、既定のオフのままにしておくとツール定義とリマインダーの分だけコンテキストに余裕ができます。逆に自動化を組んでいる場合は、モデルを新世代へ切り替える前にCLAUDE_CODE_ENABLE_TODO_TOOLS=1を設定へ足しておくと、気づかないうちに機能が消える事態を避けられます。
まとめ
v2.1.233以降、Opus 4.8・Sonnet 5・Fable 5・Mythos 5以降のモデルでは、対話セッションに限りTodo/Taskツールが既定で渡されなくなりました。タスク一覧・HookのTaskCreated・複数セッション間のタスク共有・Agent teamsの共有タスク一覧が連鎖して使えなくなるため、これらに依存した運用をしているならCLAUDE_CODE_ENABLE_TODO_TOOLS=1で明示的に復活させる必要があります。依存していないなら、コンテキストを浮かせられる既定のままで問題ありません。バックグラウンドセッションとClaude Code on the webは対象外で、これまで通りツールが提供され続けます。
よくある質問
CLAUDE_CODE_ENABLE_TASKSとCLAUDE_CODE_ENABLE_TODO_TOOLSはどちらを設定すればいいですか
対象モデルでツールそのものを復活させたいならCLAUDE_CODE_ENABLE_TODO_TOOLS=1です。CLAUDE_CODE_ENABLE_TASKSは、ツールがある前提で「Task系4つにするかTodoWrite1つにするか」を選ぶ変数で、単独では対象モデルの既定オフを覆せません。
新世代モデルでもClaudeは本当にタスクを追跡していますか
公式の説明では、対象モデルは書き出したチェックリストが無くても多段階の作業を追跡できるとされています。ただし利用者側から見える形(Ctrl+Tのタスク一覧やHookイベント)には出てこないため、進捗の可視化を運用に組み込んでいる場合は影響を受けます。
サブエージェントやAgent teamsのメンバーにも既定オフは適用されますか
サブエージェントは、そのセッションがツールを持っているときだけツールを渡されます。別モデルで動くサブエージェントでも、親セッション側の設定に従います。設計の考え方はClaude Code Sub-agents完全ガイドで扱っています。Agent teamsでは、Task系ツールが無いとチームメイトは共有タスク一覧の代わりにメッセージで調整するようになります。
この変更はAgent SDKでも同じですか
はい。TypeScript Agent SDK 0.3.233以降、Python Agent SDK 0.2.139以降で同じ既定オフが適用されます。SDK側ではallowedToolsやtoolsオプション、envにCLAUDE_CODE_ENABLE_TODO_TOOLSを設定する方法で復活させます。TypeScriptではenvがサブプロセスの環境変数を丸ごと置き換える仕様のため、既存の環境変数を残したいなら...process.envを展開したうえでCLAUDE_CODE_ENABLE_TODO_TOOLSを追加します。Pythonのenvは継承した環境の上にマージされる挙動なので、この配慮は不要です。
--allowedToolsと--toolsはどちらでタスクツールを復活させるべきですか
用途が違います。--allowedToolsは確認なしで実行してよいツールを追加指定するオプションで、既存の組み込みツールセットはそのまま保たれます。--toolsはセッションで使える組み込みツールの一覧そのものを絞り込むオプションで、タスクツールを使いたい場合は他に必要なツール名と一緒に列挙する必要があります。恒常的に使うなら環境変数のほうが設定漏れが起きにくく安全です。