メインコンテンツへスキップ
Claude Agent SDK は、Claude がツールをどのように使用するかを管理するためのパーミッション制御を提供します。パーミッションモードとルールを使用して、自動的に許可されるものを定義し、canUseTool コールバックを使用して、実行時にそれ以外のすべてを処理します。
このページはパーミッションモードとルールについて説明しています。ユーザーが実行時にツールリクエストを承認または拒否する対話的な承認フローを構築するには、承認とユーザー入力の処理を参照してください。

パーミッションの評価方法

Claude がツールをリクエストすると、SDK は次の順序でパーミッションをチェックします。
1

フック

最初にフックを実行します。フックはコールを直接拒否するか、それを渡すことができます。allow を返すフックは、以下の拒否および質問ルールをスキップしません。これらはフックの結果に関係なく評価されます。
2

拒否ルール

deny ルール(disallowed_tools およびsettings.jsonから)をチェックします。拒否ルールが一致する場合、bypassPermissions モードでもツールはブロックされます。Bash のような裸名の拒否ルールはこの評価が開始される前に Claude のコンテキストからツールを削除するため、このステップでチェックされるのは Bash(rm *) のようなスコープ付きルールのみです。
3

質問ルール

settings.jsonから ask ルールをチェックします。質問ルールが一致する場合、bypassPermissions モードでも、コールは確認のためにcanUseTool コールバックにフォールスルーします。ユーザーインタラクションが必要なツールは同じように動作します。AskUserQuestion および MCP ツール(サーバーが_meta["anthropic/requiresUserInteraction"]を設定)は、許可ルールが一致する場合でも常にコールバックにフォールスルーします。dontAsk モードでは、このモードはプロンプトを表示しないため、両方のケースが代わりに拒否されます。MCP アノテーションには Claude Code v2.1.199 以降が必要です。claude.ai コネクタツール(組織が ask に設定したもの)もこのステップでフローを離れます。すべてのコールはコールバックにフォールスルーします。bypassPermissions モードでも、許可ルールが一致する場合でもです。コールバックは理由 Your organization requires approval for this tool を受け取ります。dontAsk モードではコールが拒否される代わりに、このモードはプロンプトを表示しないためです。
4

権限モード

アクティブな権限モードを適用します。bypassPermissions はこのステップに到達したすべてを承認します。acceptEdits はファイル操作を承認します。plan はファイル編集およびシェル書き込みツールを許可ルールに関係なく canUseTool コールバックにルーティングするため、計画中は書き込み操作を自動承認することはできません。その他のモードはフォールスルーします。
5

許可ルール

allow ルール(allowed_tools および settings.json から)をチェックします。ルールが一致する場合、ツールは承認されます。
6

canUseTool コールバック

上記のいずれでも解決されない場合、決定のためにcanUseTool コールバックを呼び出します。dontAsk モードでは、このステップはスキップされ、ツールは拒否されます。
6 ステップのパーミッション評価フロー図。ツールリクエストはフック、拒否ルール、質問ルール、パーミッションモード、許可ルール、canUseTool を通過します。フック、拒否ルール、canUseTool はブロックにルーティングでき、パーミッションモードバイパス、許可ルール、canUseTool は実行にルーティングできます。質問ルールは canUseTool にルーティングします。 v2.1.198 以降、このパーミッション評価順序が到達できない canUseTool コールバックを渡す場合、TypeScript SDK はクエリが構築されるときに Node.js プロセス警告を 1 回発行します。警告のコードは CLAUDE_SDK_CAN_USE_TOOL_SHADOWED です。2 つの設定がこれをトリガーします。
  • permissionMode: 'bypassPermissions'。これはパーミッションモードステップに到達するすべてのコールを自動承認します。
  • "Read" などの各裸の allowedTools エントリ。これはコールバックが相談される前にそのツール全体を自動承認します。
Bash(ls *) などの指定子を持つエントリと acceptEdits モードはこれをトリガーしません。また、設定ファイルから来る許可ルールはチェックに表示されません。 process.on('warning', ...) でリッスンしてコードをマッチングしてログに記録するか、それを抑制します。モードとルールに関係なくすべてのツールコールをゲートするには、代わりにPreToolUse フックを使用します。 このページは許可および拒否ルールパーミッションモードに焦点を当てています。その他のステップについては、以下を参照してください。
  • フック: カスタムコードを実行して、ツールリクエストを許可、拒否、または変更します。フックで実行を制御を参照してください。
  • canUseTool コールバック: 実行時にユーザーに承認を促します。承認とユーザー入力の処理を参照してください。

許可および拒否ルール

allowed_tools および disallowed_tools(TypeScript:allowedTools / disallowedTools)は、上記の評価フロー内の許可および拒否ルールリストにエントリを追加します。許可ルールは承認のみに影響します。allowed_tools にリストされていないツールは引き続き Claude に利用可能であり、パーミッションモードにフォールスルーします。拒否ルールは、ツール全体に名前を付けるか、ツール内のパターンをスコープするかによって異なる動作をします。 許可ルールは、リテラル mcp__<server>__ プレフィックスの後にのみツール名グロブを受け入れます。サーバーセグメントはグロブフリーである必要があり、設定したサーバーに名前を付けます。mcp__puppeteer__*puppeteer サーバーからのすべてのツールに一致し、mcp__github__get_* はその get_ ツールに一致します。allowed_tools=["*"] または allowed_tools=["mcp__*"] のようなアンカーされていないエントリは、スタートアップ警告で無視され、何も自動承認しません。 Read および Edit のスコープ付きルールはパスパターンを取ります。Edit(path) ルールは、Write および NotebookEdit を含む、ファイルを書き込むすべての組み込みツールを管理します。Write(path) ルールはファイル権限チェックと一致することはありません。 絶対ファイルシステムパスには //path を使用します。Edit(//secrets/**) の拒否ルールは、ディスク上の /secrets の下のどこでも書き込みをブロックします。単一の先頭スラッシュを使用する場合、Edit(/secrets/**) はルールのソースでアンカーされます。allowed_tools または disallowed_tools を通じて渡されるルールの場合、これはセッションの作業ディレクトリを意味するため、ルールはディスク上の /secrets をブロックしません。4 つのアンカー形式と設定ファイルからのルール解決方法については、Read および Edit ルールを参照してください。
自動承認されたツールは canUseTool に到達しません。 任意の前のステップで承認されたツール呼び出し(acceptEdits または bypassPermissions による、または許可ルールによる)は、canUseTool コールバックをスキップするため、そこに配置した権限チェックはそのツールに対して静かにバイパスされます。AskUserQuestion、MCP ツール(_meta["anthropic/requiresUserInteraction"] でマークされたもの)、およびコネクタツール(組織が ask に設定したもの)は、許可ルールが一致する場合でもコールバックに到達します。カバレッジはエントリの形式に依存します。Read または mcp__github__get_issue のような単純な名前は、そのツールへのすべての呼び出しを自動承認しますが、Bash(ls *) のようなスコープ付きルールは一致する呼び出しのみを自動承認し、その他の Bash 呼び出しはコールバックにフォールスルーします。すべてのツール呼び出しで実行する必要があるチェックについては、PreToolUse フックを使用してください。フックはすべての他のステップの前に実行され、フック拒否は bypassPermissions モードでも適用されます。
ロックダウンされたエージェントの場合、allowedToolspermissionMode: "dontAsk" と組み合わせます。リストされたツールは承認されます。上記の警告の常にプロンプトが表示されるツールを除き、その他のものはプロンプトの代わりに直接拒否されます。
allowed_toolsbypassPermissions を制限しません。 allowed_tools はリストしたツールのみを事前承認します。リストされていないツールは許可ルールと一致せず、パーミッションモードにフォールスルーします。ここで bypassPermissions はそれらを承認します。allowed_tools=["Read"]permission_mode="bypassPermissions" と一緒に設定すると、BashWriteEdit を含むすべてのツールが承認されます。bypassPermissions が必要だが特定のツールをブロックしたい場合は、disallowed_tools を使用してください。
.claude/settings.json で許可、拒否、および質問ルールを宣言的に設定することもできます。これらのルールは、project 設定ソースが有効な場合に読み込まれます。デフォルトの query() オプションではこれが有効です。setting_sources(TypeScript:settingSources)を明示的に設定する場合は、それらを適用するために "project" を含めてください。ルール構文については、パーミッション設定を参照してください。

パーミッションモード

パーミッションモードは、Claude がツールをどのように使用するかについてのグローバル制御を提供します。query() を呼び出すときにパーミッションモードを設定するか、ストリーミングセッション中に動的に変更できます。

利用可能なモード

SDK は以下のパーミッションモードをサポートしています。
サブエージェント継承: 親が bypassPermissionsacceptEdits、または auto を使用する場合、すべてのサブエージェントはそのモードを継承し、サブエージェントごとにオーバーライドすることはできません。サブエージェントはシステムプロンプトが異なり、メインエージェントよりも制約が少ない動作をする可能性があるため、bypassPermissions を継承すると、完全な自律的なシステムアクセスが付与されます。明示的な ask ルール、コネクタツール組織が ask に設定したもの、およびユーザーインタラクションが必要なツールは引き続きプロンプトを強制します。

パーミッションモードの設定

クエリを開始するときにパーミッションモードを一度設定するか、セッションがアクティブな間に動的に変更できます。
クエリを作成するときに permission_mode(Python)または permissionMode(TypeScript)を渡します。このモードは、動的に変更されない限り、セッション全体に適用されます。

モードの詳細

ファイル編集モード(acceptEdits

ファイル操作を自動承認し、Claude がプロンプトなしでコードを編集できるようにします。その他のツール(ファイルシステム操作ではない Bash コマンドなど)は引き続き通常のパーミッションが必要です。 自動承認される操作:
  • ファイル編集(Edit、Write ツール)
  • ファイルシステムコマンド:mkdirtouchrmrmdirmvcpsed
どちらも、作業ディレクトリまたは additionalDirectories 内のパスにのみ適用されます。そのスコープ外のパスおよび保護されたパスへの書き込みはプロンプトが表示されます。 使用時期: Claude の編集を信頼し、プロトタイピング中など、より高速な反復を望む場合、または分離されたディレクトリで作業する場合。

質問しないモード(dontAsk

パーミッションプロンプトを拒否に変換します。allowed_toolssettings.json 許可ルール、またはフックで事前承認されたツールは通常どおり実行されます。コネクタツール組織が ask に設定したもの、およびユーザーインタラクションが必要なツールは、許可ルールが一致する場合でも拒否されます。その他のすべては canUseTool を呼び出さずに拒否されます。 使用時期: ヘッドレスエージェント用に固定された明示的なツール表面が必要で、canUseTool が存在しないことへの暗黙的な依存よりもハード拒否を優先する場合。

パーミッションバイパスモード(bypassPermissions

プロンプトなしですべてのツール使用を自動承認します。フックは引き続き実行され、必要に応じて操作をブロックできます。
極度の注意を持って使用してください。Claude はこのモードでフルシステムアクセスを持ちます。すべての可能な操作を信頼できる制御された環境でのみ使用してください。allowed_tools はこのモードを制限しません。リストしたツールだけでなく、すべてのツールが承認されます。拒否ルール(disallowed_tools)、明示的な ask ルール、およびフックはモードチェック前に評価され、ツールをブロックできます。コネクタツール組織が ask に設定したもの、およびユーザーインタラクションが必要なツールは引き続き canUseTool コールバックにフォールスルーします。

計画モード(plan

Claude はコードベースを探索および計画を作成し、ソースファイルを編集しません。読み取り専用ツールはデフォルトモードと同じように実行されます。ファイル編集は計画モードで自動承認されることはなく、許可ルールが一致する場合でも、代わりに canUseTool コールバックを通じてプロンプトが表示されます。Claude は計画を最終化する前に要件を明確にするために AskUserQuestion を使用する場合があります。これらのプロンプトの処理については、承認とユーザー入力の処理を参照してください。 使用時期: Claude に変更を提案させたいが実行させたくない場合、たとえばコードレビュー中または変更を実行する前に承認が必要な場合。 パーミッション評価フロー内の他のステップについては、以下を参照してください。