社内基盤にエージェントを載せるとき、プラットフォームチームは canUseTool コールバックに承認ロジックと監査ログを集約しがちです。ところが、このコールバックは全ツール呼び出しの関門ではありません。allowedTools に載せた時点で、承認ログに一件も残らないツールが生まれます。
本記事は Claude Agent SDK の権限評価の順序を公式ドキュメントで確認し、統制をどの層に置けば迂回されないかを設計の観点で整理します。権限設定の入門は Claude Codeの権限設計 を参照してください。
権限はどの順序で評価されるのか
SDK はツール要求を、フック、deny、ask、権限モード、allow、canUseTool の6段階で評価します。上位で決着した呼び出しは下位に届きません。
公式ドキュメントが示す評価順序は次のとおりです。
- フック: 呼び出しを拒否できる。
allowを返しても、後続の deny と ask は評価される - deny ルール: 一致すれば
bypassPermissionsでもブロックされる - ask ルール: 一致すれば
canUseToolに回る。bypassPermissionsでも同様 - 権限モード:
bypassPermissionsはここで残りをすべて承認する - allow ルール:
allowedToolsや settings.json の allow に一致すれば承認 - 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 *) など) | どのモードでも有効 |
| 全呼び出しの監査・DLP | PreToolUse フック | 最上位で必ず実行 |
| 人の承認が要る操作 | 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 にご相談ください。
