約 3 分で読めます

Agent SDKの権限評価順序とcanUseToolの死角

社内基盤にエージェントを載せるとき、プラットフォームチームは canUseTool コールバックに承認ロジックと監査ログを集約しがちです。ところが、このコールバックは全ツール呼び出しの関門ではありません。allowedTools に載せた時点で、承認ログに一件も残らないツールが生まれます。

本記事は Claude Agent SDK の権限評価の順序を公式ドキュメントで確認し、統制をどの層に置けば迂回されないかを設計の観点で整理します。権限設定の入門は Claude Codeの権限設計 を参照してください。

権限はどの順序で評価されるのか

SDK はツール要求を、フック、deny、ask、権限モード、allow、canUseTool の6段階で評価します。上位で決着した呼び出しは下位に届きません。

公式ドキュメントが示す評価順序は次のとおりです。

  1. フック: 呼び出しを拒否できる。allow を返しても、後続の deny と ask は評価される
  2. deny ルール: 一致すれば bypassPermissions でもブロックされる
  3. ask ルール: 一致すれば canUseTool に回る。bypassPermissions でも同様
  4. 権限モード: bypassPermissions はここで残りをすべて承認する
  5. allow ルール: allowedTools や settings.json の allow に一致すれば承認
  6. canUseTool: 上記で決まらなかった呼び出しだけが届く

重要なのは、canUseTool が最下層にあることです。ここに置いた検査は、上位で承認された呼び出しに対して一度も実行されません。

なぜcanUseToolだけでは統制が抜けるのか

allowedTools の裸のツール名は、そのツールの全呼び出しを自動承認します。bypassPermissions を併用すると、列挙外のツールも承認されます。

公式の警告は2点です。第一に、"Read" のような裸の名前は、そのツールの全呼び出しを canUseTool の手前で承認します。第二に、allowedTools は bypassPermissions を制限しません。allowed_tools=["Read"] と bypassPermissions を併用しても、Bash や Write を含む全ツールが承認されます。

TypeScript SDK は、この構成を検知すると Node.js のプロセス警告 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED を一度出します。起動時にこの警告を process.on('warning', ...) で拾い、CI で失敗させる運用が有効です。スコープ付きの Bash(ls *) や acceptEdits では警告は出ません。

全呼び出しを統制するにはどこに置くのか

全呼び出しに必ず効く層は PreToolUse フックと deny ルールです。承認ロジックと監査ログはここに置きます。

公式は「全ツール呼び出しに対して検査を走らせたいなら PreToolUse フックを使う」としています。フックは他のどの段階よりも先に走り、フックの deny は bypassPermissions でも有効です。

エンタープライズ向けの配置指針を次に示します。

目的置き場所理由
絶対禁止の操作deny ルール(Bash(rm *) など)どのモードでも有効
全呼び出しの監査・DLPPreToolUse フック最上位で必ず実行
人の承認が要る操作ask ルール + canUseTool承認 UI を一箇所に集約
ヘッドレス実行allowedTools + dontAsk列挙外は拒否される

dontAsk モードは、承認が必要な呼び出しを canUseTool を呼ばずに拒否します。ツール面を固定したいバッチ系エージェントに向きます。裸の Bash を deny に入れるとツール定義そのものが除去され、モデルは試行すらできません。

サブエージェントに権限モードはどう継承されるのか

サブエージェントは plan、acceptEdits、auto、bypassPermissions を親から継承します。ただし bypassPermissions の値は定義側から適用されません。

親が plan モードなら、サブエージェント定義に acceptEdits を書いても plan のままです。親が default または dontAsk なら、定義した値で動きます。ただし公式は、bypassPermissions を継承したサブエージェントは完全な自律権限を持つと警告しています。

規模の統制には、環境変数も使います。ネストの深さは CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH(既定3)、同時実行数は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(既定20)、支出は maxBudgetUsd で上限を設けます。複数チームが共有する基盤では、これらを基盤側の既定値として固定します。

大規模組織での統制設計は、大企業向け AI変革プログラム RDE で支援しています。

参考

まとめ

canUseTool は最下層の承認窓口であり、全呼び出しの関門ではありません。統制は deny ルールと PreToolUse フックに置きます。

承認ログを canUseTool だけに頼る設計は、allowedTools と bypassPermissions で静かに崩れます。評価順序を前提に、禁止は deny、監査はフック、人の承認は ask と canUseTool に分担させてください。エージェント基盤の権限設計は Kuu株式会社のRDE にご相談ください。

関連記事

エージェント委譲のID設計:JWT-SVIDとactクレームDPoPでエージェントの盗用トークン再利用を防ぐExcessive Agencyを機能・権限・自律性の3軸で点検Lethal Trifectaを設計で崩す3つの切り口