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 モードでは、このステップはスキップされ、ツールは拒否されます。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 ルールを参照してください。
ロックダウンされたエージェントの場合、allowedTools を permissionMode: "dontAsk" と組み合わせます。リストされたツールは承認されます。上記の警告の常にプロンプトが表示されるツールを除き、その他のものはプロンプトの代わりに直接拒否されます。
.claude/settings.json で許可、拒否、および質問ルールを宣言的に設定することもできます。これらのルールは、project 設定ソースが有効な場合に読み込まれます。デフォルトの query() オプションではこれが有効です。setting_sources(TypeScript:settingSources)を明示的に設定する場合は、それらを適用するために "project" を含めてください。ルール構文については、パーミッション設定を参照してください。
パーミッションモード
パーミッションモードは、Claude がツールをどのように使用するかについてのグローバル制御を提供します。query() を呼び出すときにパーミッションモードを設定するか、ストリーミングセッション中に動的に変更できます。
利用可能なモード
SDK は以下のパーミッションモードをサポートしています。パーミッションモードの設定
クエリを開始するときにパーミッションモードを一度設定するか、セッションがアクティブな間に動的に変更できます。- クエリ時
- ストリーミング中
クエリを作成するときに
permission_mode(Python)または permissionMode(TypeScript)を渡します。このモードは、動的に変更されない限り、セッション全体に適用されます。モードの詳細
ファイル編集モード(acceptEdits)
ファイル操作を自動承認し、Claude がプロンプトなしでコードを編集できるようにします。その他のツール(ファイルシステム操作ではない Bash コマンドなど)は引き続き通常のパーミッションが必要です。
自動承認される操作:
- ファイル編集(Edit、Write ツール)
- ファイルシステムコマンド:
mkdir、touch、rm、rmdir、mv、cp、sed
additionalDirectories 内のパスにのみ適用されます。そのスコープ外のパスおよび保護されたパスへの書き込みはプロンプトが表示されます。
使用時期: Claude の編集を信頼し、プロトタイピング中など、より高速な反復を望む場合、または分離されたディレクトリで作業する場合。
質問しないモード(dontAsk)
パーミッションプロンプトを拒否に変換します。allowed_tools、settings.json 許可ルール、またはフックで事前承認されたツールは通常どおり実行されます。コネクタツール組織が ask に設定したもの、およびユーザーインタラクションが必要なツールは、許可ルールが一致する場合でも拒否されます。その他のすべては canUseTool を呼び出さずに拒否されます。
使用時期: ヘッドレスエージェント用に固定された明示的なツール表面が必要で、canUseTool が存在しないことへの暗黙的な依存よりもハード拒否を優先する場合。
パーミッションバイパスモード(bypassPermissions)
プロンプトなしですべてのツール使用を自動承認します。フックは引き続き実行され、必要に応じて操作をブロックできます。
計画モード(plan)
Claude はコードベースを探索および計画を作成し、ソースファイルを編集しません。読み取り専用ツールはデフォルトモードと同じように実行されます。ファイル編集は計画モードで自動承認されることはなく、許可ルールが一致する場合でも、代わりに canUseTool コールバックを通じてプロンプトが表示されます。Claude は計画を最終化する前に要件を明確にするために AskUserQuestion を使用する場合があります。これらのプロンプトの処理については、承認とユーザー入力の処理を参照してください。
使用時期: Claude に変更を提案させたいが実行させたくない場合、たとえばコードレビュー中または変更を実行する前に承認が必要な場合。
関連リソース
パーミッション評価フロー内の他のステップについては、以下を参照してください。- 承認とユーザー入力の処理:対話的な承認プロンプトと明確化の質問
- フックガイド:エージェントライフサイクルの主要なポイントでカスタムコードを実行
- パーミッションルール:
settings.jsonの宣言的な許可/拒否ルール