Agent SDKのパーミッション制御 — モードとallow/denyルール

Agent SDKの権限判定は何が優先されるか

Claudeがツールを呼び出そうとするたびに、Agent SDKは6つのステップを順番にチェックします。上から順に見て、どこかで許可か拒否が決まればそこで終わりです。

TypeScript SDKでpermissionPrompts: 'none'を指定すると、最後のステップでもコールバックは呼ばれません。PermissionRequestフックが判断し、決めなければ拒否です。このオプションはClaude Code v2.1.259以降が前提です。拒否をUIに出すイベントの出方はAgent SDKのpermission_deniedイベントで拒否をUIに出す方法にあります。

6つの権限モードは何を自動承認するか

acceptEditsが自動承認するのは作業ディレクトリまたはadditionalDirectories配下に限られ、それ以外のパスや保護対象パスへの書き込みは確認を求められます。bypassPermissionsはallowed_toolsの内容にかかわらず全ツールを承認します。ただし、どのモードでも自動承認されない操作が残ります。askルールに一致したツール、ユーザー操作が必要なツール、rm・rmdirによるクリティカルパス(ファイルシステムのルート、トップレベルディレクトリ、ホームディレクトリ、作業ディレクトリとその親など)の削除などです。

クリティカルパスの削除は、allowルールにもPreToolUseフックのallowにも承認されません。その先の扱いはモード次第です。Agent SDKのセッションでautoモードなら、コールバックを呼ばずに既定で拒否されます。確認を求めるdefault・acceptEdits・bypassPermissionsと違い、確認も分類器も通りません(dontAskも拒否します)。

autoモードの分類器は、ルール側で承認・拒否が確定しなかった呼び出しを別の分類器モデルに判定させる仕組みです。リスクの高い操作はブロックされ、低リスクと判断された呼び出しは確認なしで進みます。

permissionModeを省略すると何が起きるか

permissionModeを渡さなかったとき、開始モードは固定のdefaultではありません。設定ファイルのpermissions.defaultModeがあればそれに従い、無ければ組み込みの既定になります。この既定は、機能フラグを取得するセッションではdefault、それ以外ではClaude Code v2.1.285以降でautoです。.claude/settings.jsonや.claude/settings.local.jsonにdefaultMode: "auto"を書いても効きません。

TypeScript Agent SDK v0.3.286より前は、省略はdefaultを渡すのと同じでした。それ以降は、autoで始まったセッションがBashのような広いallowルールを捨てます。defaultや広いallowを前提にしたアプリケーションは、permissionMode: "default"を明示するほうが挙動が固定されます。

CLIの側では、defaultは「Manual」という表示名で出てきます。claude --helpの--permission-modeの選択肢にはdefaultが無く、manualが並びます(v2.1.287)。

claude --help | grep -A3 -e "--permission-mode" -e "--permission-prompts"

v2.1.287での出力(抜粋)です。

  --permission-mode <mode>              Permission mode to use for the session
                                        (choices: "acceptEdits", "auto",
                                        "bypassPermissions", "manual",
                                        "dontAsk", "plan")
  --permission-prompts <target>         Who answers permission prompts with
                                        --print: "host" (the SDK host or
                                        --permission-prompt-tool) or "none"
                                        (nobody: anything that would prompt is
                                        denied automatically; the permission
                                        mode still decides everything else)

manualはdefaultの別名です。SDKやフックの設定値としてはdefaultのままで、manualの表示と別名はClaude Code v2.1.200以降のものです。--permission-prompts noneはSDKのpermissionPrompts: 'none'に当たるCLI側の指定で、-p実行では「確認が必要な呼び出しは自動的に拒否」になります。

allow/denyルールの書き方で挙動はどう変わるか

allowed_toolsとdisallowed_tools(TypeScriptではallowedTools/disallowedTools)は、この評価フローのallow・denyルール一覧に項目を追加する役割です。書き方によって粒度が変わります。

Bash(rm *)が防ぐのは、その書き方のコマンドだけです。パスを変えた/bin/rmは別の呼び出しとして扱われるため、rmを確実に止めたいならBashの取り除きやフックを併用します。

allowルールでツール名ワイルドカードが効くのは、mcp__<サーバー名>__というリテラルなプレフィックスの後だけです。mcp__puppeteer__*はpuppeteerサーバーの全ツールに一致します。サーバー名部分にワイルドカードを含むallowed_tools=["*"]やallowed_tools=["mcp__*"]は起動時警告とともに無視され、何も自動承認しません。

ReadとEditのスコープ付きルールはパスパターンを取ります。Edit(path)はWriteやNotebookEditを含む書き込み系の組み込みツール全般に適用されます。逆にWrite(path)というルールは、ファイル権限チェックでは一致しません。

パスの指定には、先頭スラッシュの数で意味が変わる落とし穴があります。Edit(//secrets/**)は実ファイルシステムの/secrets以下を止めます。Edit(/secrets/**)はルールの取得元が起点で、allowed_tools/disallowed_tools経由ならセッションの作業ディレクトリ基準になり、ディスク上の/secretsは止まりません。

.claude/settings.jsonに書いたallow・deny・askのルールも使えます。読み込まれるのはprojectの設定ソースが有効なときで、query()の既定オプションでは有効です。settingSourcesを明示する場合は"project"を含めないと、これらのルールは効きません。

ツールの範囲を固定したい無人稼働のエージェントには、allowedToolsとpermissionMode: "dontAsk"を組み合わせる構成が向きます。

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk",
};

リストにあるツールは承認され、確認が必要になる呼び出しは確認を挟まず拒否されます。読み取り専用のBashコマンドや作業ディレクトリ内のファイル読み取りのように、defaultでも確認が要らない呼び出しは、リストに無くても動く点に注意が要ります。ツールをClaudeの手の届かない所へ置くなら、素の名前をdisallowedToolsに入れます。

同じallowed_tools=["Read"]でも、組み合わせるモードで意味が正反対になります。

サブエージェントは親の権限モードをどう引き継ぐか

サブエージェントは既定で、親セッションの権限モードで動きます。AgentDefinitionのpermissionModeで個別に上書きできるのは、親セッションがdefault・dontAsk・planのいずれかのときに限られます。親がbypassPermissions・acceptEdits・autoで動いている場合、そのモードがセッション内の全サブエージェントに及び、サブエージェント側の指定は効きません。

さらに、サブエージェント側に"bypassPermissions"を書いても、Claude Codeは適用しません。サブエージェントがbypassPermissionsで動くのは、親セッション自身がそのモードのときだけです。この例外はClaude Code v2.1.267以降のものです。サブエージェントの定義自体の設計はAgent SDKのサブエージェント定義にまとめています。

この継承には実務上の注意点があります。サブエージェントは親と異なるシステムプロンプトを持ち、制約の少ない振る舞いをすることがあります。親がbypassPermissionsなら、確認なしでシステム全体に触れる権限が、そのままサブエージェントへ渡ります。管理設定のpermissions.disableBypassPermissionsModeを"disable"にすれば、組織としてこのモード自体を塞げます。

もう一つ見落としやすいのが、canUseToolコールバックが呼ばれない自動承認のケースです。permissionMode: "bypassPermissions"と、"Read"のようにツール名だけを書いたallowedToolsの項目は、コールバックの手前で承認してしまいます。TypeScript SDKはこの構成を検知すると、CLAUDE_SDK_CAN_USE_TOOL_SHADOWEDというコードのNode.jsプロセス警告を1回だけ発行します。

Bash(ls *)のようなスコープ付きの項目やacceptEditsは対象外です。設定ファイルから来るallowルールも、この検査には見えません。警告が出ないからコールバックが必ず呼ばれる、とは言えない点に注意が必要です。

hooksとcanUseToolコールバックはどう役割分担するか

Claude Codeの権限判定では、hooksとコールバックが評価フローの両端を受け持ちます。

実行時にユーザーへ都度確認を取りたいだけならcanUseToolで足ります。モードやルールの選び間違いに備えるなら、全呼び出しの手前で動くPreToolUseフックを併用すると、選び間違いに強い構成です。止めたいツールが決まっているならdenyルールで足り、フックが担うのは呼び出しの中身を見て止める判断です。

まとめ — モードとルールは別レイヤーとして設計する

モードはセッション全体の既定を決め、ルールは個々のツールの例外を作ります。自動化の範囲はモードとallowで決め、「何があっても止める」条件はdenyルールとhooksに置くと、設定の選び間違いが事故になりにくくなります。

Claude Code CLIでの権限モデルの変遷はClaude Code権限モデルの変遷、settings.jsonでのルール記法はClaude Code settings.json完全ガイドにあります。