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

> Claude Agent SDKは6段階で権限を評価し、allowedToolsやbypassPermissionsで承認されたツールはcanUseToolに届きません。統制を外さない配置を整理します。

- Canonical: https://kuucorp.com/blog/claude-agent-sdk-permission-evaluation-order-canusetool-design/
- Date: 2026-10-25
- Last modified: 2026-10-25
- Publisher: Kuu株式会社 (https://kuucorp.com)

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

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

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

> 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 *)` など） | どのモードでも有効 |
| 全呼び出しの監査・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](https://kuucorp.com/services/rde/) で支援しています。

## 参考

- [Configure permissions（Claude Agent SDK）](https://code.claude.com/docs/en/agent-sdk/permissions)
- [Subagents in the SDK](https://code.claude.com/docs/en/agent-sdk/subagents)

## まとめ

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

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