Configure permissions（Agent SDK パーミッション）

概要

Agent SDK でツール使用の許可・拒否を制御する仕組み。パーミッションモード、allow/deny ルール、canUseTool コールバックを組み合わせて、エージェントがどのツールを使えるかを決定する。

仕様

パーミッション評価フロー

Claude がツールを要求したとき、SDK は以下の順序で評価する。

Hooks — PreToolUse フックを最初に実行。フックは呼び出しを拒否するか、次に渡す。フックが allow を返しても deny/ask ルールの評価はスキップされない。フックの allow は critical path を対象とする rm/rmdir の承認にはならない
Deny ルール — disallowed_tools および settings.json のルールを評価。一致したらブロック（bypassPermissions モードでも）。ベアネーム deny（例: Bash）はツール定義自体を除去するため、ここではスコープ付きルール（例: Bash(rm *)）のみ評価
Ask ルール — settings.json の ask ルールを評価。一致したら canUseTool コールバックへ（bypassPermissions モードでも）。AskUserQuestion、_meta["anthropic/requiresUserInteraction"] を設定した MCP ツール（v2.1.199 以降）、組織が ask に設定した claude.ai connector ツールも同様にコールバックへ。このときコールバックは理由として Your organization requires approval for this tool を受け取る。dontAsk モードでは deny
Permission mode — アクティブなパーミッションモードを適用。bypassPermissions は critical path の rm/rmdir 以外を承認。acceptEdits はファイル操作を承認。plan はファイル編集・シェル書き込みを canUseTool へ
Allow ルール — allowed_tools および settings.json のルールを評価。一致したら承認。critical path の rm/rmdir は allow ルールで承認されない。プロンプトが出るモードではコールバックへ、auto モードでは classifier へ回り（Claude Code v2.1.218 以降）、dontAsk モードでは拒否される
canUseTool コールバック — 上記で解決しなかった場合に呼び出される。dontAsk モードではスキップされ deny

Allow / Deny ルール

オプション	効果
`allowed_tools=["Read", "Grep"]`	`Read` と `Grep` を自動承認。他のツールはパーミッションモードと `canUseTool` へフォールスルー
`disallowed_tools=["Bash"]`	`Bash` のツール定義を除去。Claude からは見えない
`disallowed_tools=["Bash(rm *)"]`	`Bash` は利用可能だが `rm *` にマッチする呼び出しは全モードで拒否
`disallowed_tools=["*"]`	全ツール定義を除去。`"mcp__*"` で全 MCP ツールにマッチ

allowed_tools に task-tracking ツールのいずれかを指定すると、Claude Code はそのセッションを task tracking に opt-in する
Allow ルールのグロブは mcp__<server>__ プレフィックス後のみ対応（例: mcp__puppeteer__*、mcp__github__get_*）。サーバーセグメントにグロブは使えない
allowed_tools=["*"] や allowed_tools=["mcp__*"] は無視され起動時に警告が出る
Read と Edit のスコープ付きルールはパスパターンを取る。Edit(path) ルールは Write や NotebookEdit を含む全ファイル書き込みツールに適用。Write(path) ルールは単独ではマッチしない
Edit(//path) で絶対ファイルシステムパス、Edit(/path) でルールソースからの相対パス

パーミッションモード

モード	説明	ツールの挙動
`default`	標準	自動承認なし。未解決のツールは `canUseTool` コールバックへ
`dontAsk`	プロンプトの代わりに拒否	`allowed_tools` やルールで事前承認されたもの以外は拒否。組織が ask に設定した connector ツール・ユーザー操作を要求するツール・critical path を対象とする `rm`/`rmdir` は事前承認済みでも拒否。`canUseTool` は呼ばれない
`acceptEdits`	ファイル編集を自動承認	ファイル編集とファイルシステム操作（`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp`、`sed`）を自動承認。作業ディレクトリまたは `additionalDirectories` 内のパスのみ。スコープ内であっても protected paths への書き込みと critical path を対象とする `rm`/`rmdir` は依然プロンプトが出る
`bypassPermissions`	パーミッションチェックをバイパス	プロンプトなしでツール実行。critical path の `rm`/`rmdir` 等は例外
`plan`	計画モード	ファイル編集は自動承認されず `canUseTool` コールバックへ。v2.1.212 以降ではシェルのファイル変更コマンドも同様
`auto`	モデル分類器による承認	モデル分類器が承認・拒否を判定

サブエージェントの継承

サブエージェントは親セッションのパーミッションモードを継承する
AgentDefinition の permissionMode でオーバーライド可能。ただし bypassPermissions、acceptEdits、auto は全サブエージェントに適用され、オーバーライド不可
permissions.disableBypassPermissionsMode が設定されている場合、サブエージェントの permissionMode: "bypassPermissions" は無視され、親セッションのモードで動く
サブエージェントは親と異なるシステムプロンプトを持ち、制約の緩い挙動をしうる。 bypassPermissions を継承させると、完全な自律的システムアクセスを与えることになる（「どのモードでも自動承認されないアクション」は引き続き適用される）

CLAUDE_SDK_CAN_USE_TOOL_SHADOWED 警告

TypeScript SDK で、評価順上 canUseTool コールバックが実質的にスキップされる構成の場合に Node.js プロセス警告が発生する。以下の構成でトリガー:

permissionMode: 'bypassPermissions'
ベアネームの allowedTools エントリ（例: "Read"）

スコープ付きエントリ（例: Bash(ls *)）や acceptEdits モードではトリガーされない。設定ファイル由来の allow ルールはこの検査から見えない。

process.on('warning', ...) で受け取り、code で照合して記録・抑制できる。モードやルールに関わらず全ツール呼び出しを検査したいなら PreToolUse hook を使う。

設定

// ロックダウンされたエージェント: 許可ツール + dontAsk
const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

# Python での設定
options = ClaudeAgentOptions(
    permission_mode="default",
)

# ストリーミング中のモード変更
await client.set_permission_mode("acceptEdits")

制約・注意点

自動承認されたツールは canUseTool コールバックに到達しない。ただし AskUserQuestion、_meta["anthropic/requiresUserInteraction"] 付き MCP ツール、組織が ask に設定した connector ツール、critical path の rm/rmdir は例外
allowed_tools は bypassPermissions を制限しない。allowed_tools=["Read"] と permission_mode="bypassPermissions" を併用しても全ツールが承認される。特定ツールをブロックするには disallowed_tools を使う
dontAsk モードでは canUseTool は一切呼ばれない。PreToolUse hook の allow も、critical path を対象とする削除は解除しない
settings.json の allow / deny / ask ルールは、project の setting source が有効なときに読まれる。query() の既定オプションでは有効になっている。 setting_sources（TypeScript: settingSources）を明示指定する場合のみ、"project" を含める必要がある