SDK でツール使用を絞る

段	達成したと言える状態
1. 触る	`allowed_tools` と `disallowed_tools` を渡して実行し、拒否されたツールの挙動を確認した
2. 入れる	用途に合うパーミッションモードを選び、未解決のツールを `canUseTool` コールバックで処理している
3. 効かせる	hooks → deny → ask → mode → allow → `canUseTool` の評価順に沿って、意図した箇所で止まる構成にできる

何のためのものか

Agent SDK でツール使用の許可・拒否を制御する仕組み。パーミッションモード、allow/deny ルール、canUseTool コールバックの 3 つを組み合わせて決める。

まず 2 つのオプションを渡してみる。

オプション	効果
`allowed_tools=["Read", "Grep"]`	自動承認。他のツールはモードと `canUseTool` へフォールスルー
`disallowed_tools=["Bash"]`	ツール定義自体を除去する。 Claude からは見えない
`disallowed_tools=["Bash(rm *)"]`	`Bash` は使えるが、一致する呼び出しは全モードで拒否

ベアネームの deny は定義ごと消し、スコープ付きの deny は呼び出しだけを止める。 この違いが分かると設計が変わる。

モードを選び、残りを canUseTool で処理する。

モード	ツールの挙動
`default`	自動承認なし。未解決のツールは `canUseTool` へ
`dontAsk`	事前承認されたもの以外は拒否。`canUseTool` は呼ばれない
`acceptEdits`	作業ディレクトリ内のファイル編集とファイルシステム操作を自動承認
`plan`	ファイル編集は自動承認されず `canUseTool` へ
`bypassPermissions`	プロンプトなしで実行（critical path の `rm` / `rmdir` 等は例外）
`auto`	モデル分類器が承認・拒否を判定

ロックダウンしたいなら allowed_tools に read 系だけを並べて permissionMode: "dontAsk" にする。

評価順を覚える。 ここを外すと「書いたルールが効かない」になる。

subagent は親のパーミッションモードを継承する。 AgentDefinition の permissionMode で上書きできるが、bypassPermissions / acceptEdits / auto は上書き不可
パスのスコープは Edit(path) が全ファイル書き込みツールに適用される。Write(path) ルールは単独ではマッチしない

critical path を対象とする rm / rmdir は、allow ルールでも hook の allow でも承認されない
allowed_tools=["*"] や ["mcp__*"] は無視され、起動時に警告が出る。 allow のグロブは mcp__<server>__ の後ろにしか置けない
canUseTool が実質スキップされる構成では警告が出る（TypeScript SDK の CLAUDE_SDK_CAN_USE_TOOL_SHADOWED）。permissionMode: 'bypassPermissions' とベアネームの allowedTools エントリの組み合わせで起きる
dontAsk では、事前承認済みでも拒否されるものがある（ユーザー操作を要求するツール、組織が ask に設定した connector ツール）