Agent ツールの effort にはどんな値を渡せるのか？
公式の changelog は effort パラメータが追加されたとだけ書き、値は挙げていない。コミュニティの提案は low、medium、high、xhigh、max を挙げているが、それは提案の内容であり、確認された出荷後の挙動ではない。
公式の sub-agents ドキュメントを確認するか、テスト用のプロジェクトで値ごとに1回ずつ呼び出し、どれが受け付けられどれがエラーになるかを見るとよい。
呼び出しごとの effort は、エージェント定義の effort を上書きするのか？
提案は呼び出しごとがエージェント定義より、さらにセッションのレベルより優先されることを望んでおり、呼び出し側がデフォルトを上書きするという一般的な感覚とも合う。ただし公式は明言しておらず、メンテナーによる確認も見つけられなかった。
試す方法は簡単で、effort が low のエージェントを定義し、呼び出しごとに high を渡して、実際の挙動とトークン使用量を確認する。
effort を下げれば必ず安くなるのか？
方向としては通常そうなる。思考トークンが減るからだが、各レベルでどれだけ節約できるかの公式な数値はなく、同時に品質が落ちることもある。
だからまずベースラインを測り、繰り返しが多く間違えてもコストが小さいタスクにだけ effort を下げ、請求額と結果の品質の両方で確認する。
すでに reviewer-low や reviewer-high のように段階分けしたエージェントがある場合、すぐ統合すべきか？
急ぐ必要はない。まず呼び出しごとの値と優先順位が期待どおりに動くことを確認し、それから段階分けしたエージェントを1つへ少しずつまとめる。
統合前は古い構成をしばらく残し、2つの方法を1回並行して動かし、挙動が一致してから古いものを外す。
Claude Code v2.1.292（2026年10月6日）の changelog には、追加項目として Agent ツールに effort パラメータが加わったとの1行がある。公式の記載はこれだけで、値の一覧も優先順位の説明もないため、この記事では確認できたことと推測を分けて書く。
それまでも Agent ツールは呼び出しごとに model を指定できたが、サブエージェントの effort は2か所からしか決まらなかった。エージェント定義の effort（frontmatter または --agents の JSON）か、メインセッションのレベルだ。コミュニティの GitHub には関連する提案がいくつかあり、その1つは必要性を具体的に述べている。メインセッションは medium、機械的なバッチ作業には low、難しいレビューには xhigh を、同じエージェントで使いたいというものだ。呼び出しごとのパラメータがなければ、reviewer-low や reviewer-high のようにレベルごとにエージェント型を作るしかなく、エージェント一覧が散らかる。
確認できたのは changelog の1行、つまり Agent ツールに effort パラメータが加わり、同じバージョンで claude Plugin install --marketplace なども追加されたことだ。細部は確認できていない。上記の提案は low、medium、high、xhigh、max という値と、「呼び出しごとの effort が、エージェント定義の effort より、セッションのレベルより優先」という順位を挙げているが、それは提案の内容であり、私が見つけた資料にはメンテナーによる出荷後の挙動の確認も、対応モデルの説明もない。別のプロジェクトの導入メモは frontmatter をデフォルト、呼び出しごとを上書きと扱っているが、これも利用者側の解釈だ。受け付ける値と優先順位は、公式の sub-agents ドキュメントか自分の小さなテストで確認してほしい。
effort は思考トークンの使用量に直接影響し、思考トークンは出力単価で課金される。リスクの低い繰り返し作業（ファイルのスキャン、書式チェック、項目の抽出）では effort を下げ、判断が要る少数のレビューでは上げるのは、予算を効くところに使う方法だ。Haiku 5.5 のような小型モデルをサブエージェントに当てる考え方と同じで、サブタスクごとに見合うコストは違う。各レベルでどれだけ節約できるかの公式な数値はまだないため、効果は自分で測るしかない。
サブエージェントを多く動かすチームは、まず1週間のベースラインを測る。エージェントごとの平均トークン数とコストだ。次に最も繰り返しの多いエージェントを選び、同じバッチを呼び出しごとの低い effort で実行して、品質と請求額を比べる。品質が落ちず、コストが実際に下がった場合にだけデフォルトを変える。公式のレベル別データが出るまでは、どれだけ節約できるかは仮説として扱い、自分の請求書で検証すること。