SpyBara
Go Premium

agent-sdk/permissions.md 2026-09-13 21:00 UTC to 2026-09-14 22:58 UTC

This page contains 105 additions and 84 deletions.

2026
Mon 14 22:58 Fri 18 23:58 Fri 25 23:58

権限の設定

権限モード、hooks、および宣言的な許可/拒否ルールを使用して、エージェントがツールをどのように使用するかを制御します。

Claude Agent SDK は、Claude がツールをどのように使用するかを管理するための権限制御を提供します。権限モードとルールを使用して、自動的に許可されるものを定義し、canUseTool コールバックを使用して、実行時にそれ以外のすべてを処理します。

権限がどのように評価されるか

Claude がツールをリクエストすると、SDK は以下の順序で権限をチェックします。

1

Hooks

最初に hooks を実行します。Hook は呼び出しを完全に拒否するか、それを通すことができます。allow を返す Hook は、以下の deny および ask ルールをスキップしません。これらは Hook の結果に関係なく評価されます。PreToolUse Hook の allow は、重要なパス をターゲットとする rm または rmdir の削除を承認することもできません。

2

Deny ルール

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

3

Ask ルール

settings.json から ask ルールをチェックします。Ask ルールがマッチした場合、呼び出しは確認のために canUseTool コールバック にフォールスルーします。bypassPermissions モードでも同様です。

ユーザーインタラクションが必要なツールは同じように動作します。AskUserQuestion および _meta["anthropic/requiresUserInteraction"] を設定する MCP ツールサーバーは、allow ルールがマッチした場合でも常にコールバックにフォールスルーします。dontAsk モードでは、このモードは決してプロンプトを表示しないため、両方のケースが拒否されます。MCP アノテーションには Claude Code v2.1.199 以降が必要です。

組織が ask に設定した claude.ai コネクタ ツールもこのステップでフローを離れます。bypassPermissions モードでも allow ルールがマッチした場合でも、すべての呼び出しはコールバックにフォールスルーします。コールバックは理由 Your organization requires approval for this tool を受け取ります。dontAsk モードでは、このモードは決してプロンプトを表示しないため、呼び出しは拒否されます。

4

Permission モード

アクティブな permission モード を適用します。

  • bypassPermissions モードでは、Claude Code はこのステップに到達したすべてのものを承認します。ただし、重要なパス をターゲットとする rm および rmdir の削除は除きます。これらはフォールスルーします。
  • acceptEdits モードでは、Claude Code は Accept edits モード の下にリストされたファイル操作を承認します。
  • plan モードでは、Claude Code は allow ルールに関係なく、ファイル編集およびシェル書き込みツールを canUseTool コールバックに送信します。これにより、計画中に書き込み操作を自動承認することはできません。
  • その他のモードでは、リクエストはフォールスルーします。
5

Allow ルール

allow ルール（allowed_tools および settings.json から）をチェックします。ルールがマッチした場合、ツールは承認されます。ツール自体が承認する呼び出しもこのステップで解決されます。ルールは不要です。例えば、作業ディレクトリ内のファイル読み取りまたは 読み取り専用 Bash コマンド。rm および rmdir の削除で 重要なパス をターゲットとするものは、allow ルールによって決して承認されません。プロンプトを表示するモードではコールバックに到達し、Claude Code v2.1.218 以降の auto モードでは 分類器 に移動し、dontAsk モードでは拒否されます。

6

canUseTool コールバック

上記のいずれでも解決されない場合、決定のために canUseTool コールバック を呼び出します。dontAsk モードでは、このステップはスキップされ、ツールは拒否されます。

TypeScript SDK では、permissionPrompts: 'none' を設定した場合、このステップではコールバックは呼び出されません。PermissionRequest hook はまだ決定する機会があり、そうしない場合、Claude Code は呼び出しを拒否します。このオプションには Claude Code v2.1.259 以降が必要です。

上記のステップに対応する 6 ステップの権限評価フロー図。ツールリクエストは hooks、deny ルール、ask ルール、permission モード、allow ルール、canUseTool を通過します。Hooks、deny ルール、canUseTool は Blocked にルーティングでき、permission モード bypass、allow ルール、canUseTool は Execute にルーティングでき、ask ルールは canUseTool にルーティングします。 上記のステップに対応する 6 ステップの権限評価フロー図。ツールリクエストは hooks、deny ルール、ask ルール、permission モード、allow ルール、canUseTool を通過します。Hooks、deny ルール、canUseTool は Blocked にルーティングでき、permission モード bypass、allow ルール、canUseTool は Execute にルーティングでき、ask ルール は canUseTool にルーティングします。

TypeScript SDK がコールバックが相談される前に呼び出しを自動承認することを期待する設定で canUseTool コールバックを渡す場合、SDK はクエリが構築されるときに Node.js プロセス警告を 1 回発行します。警告のコードは CLAUDE_SDK_CAN_USE_TOOL_SHADOWED です。2 つの設定がそれをトリガーします。

Bash(ls *) などの指定子を持つエントリおよび acceptEdits モードはそれをトリガーしません。また、設定ファイルから来る allow ルールはチェックに表示されません。

process.on('warning', ...) でリッスンし、コードをマッチさせてログまたは抑制します。モードとルールに関係なくすべてのツール呼び出しをゲートするには、代わりに PreToolUse hook を使用します。

このページは allow および deny ルール および permission モード に焦点を当てています。その他のステップについては、以下を参照してください。

  • Hooks： ツールリクエストを許可、拒否、または変更するカスタムコードを実行します。実行を Hook で制御する を参照してください。
  • canUseTool コールバック： 前のステップで呼び出しが解決されない場合、実行時にユーザーの承認をプロンプトします。承認とユーザー入力を処理する を参照してください。

許可ルールと拒否ルール

allowed_tools と disallowed_tools（TypeScript：allowedTools / disallowedTools）は、上記の評価フロー内の許可ルールと拒否ルールリストにエントリを追加します。allowed_tools にタスク追跡ツールの 1 つを名前で指定すると、Claude Code もセッションをオプトインします。allowed_tools にリストされていない他のツールは、Claude でも利用可能であり、承認が必要なそのツールへの呼び出しは権限モードにフォールスルーします。拒否ルールは、ツール名を指定するか、ツール内のパターンをスコープするかによって動作が異なります。

オプション 効果
allowed_tools=["Read", "Grep"] Read と Grep は自動承認されます。ここにリストされていない他のツールは依然として存在し、承認が必要なそれらへの呼び出しは権限モードと canUseTool にフォールスルーします。
disallowed_tools=["Bash"] Bash ツール定義はリクエストから削除されます。Claude はツールを認識せず、実行を試みることはできません。
disallowed_tools=["Bash(rm *)"] Bash は利用可能なままです。rm *に記載されているとおりにマッチする呼び出しは、bypassPermissions を含むすべての権限モードで拒否されます。/bin/rm を含む他の Bash 呼び出しは、権限モードにフォールスルーします。
disallowed_tools=["*"] すべてのツール定義がリクエストから削除されます。拒否ルールではツール名グロブがサポートされています："*" はすべてのツールにマッチし、"mcp__*" はすべてのサーバー全体のすべての MCP ツールにマッチします。

許可ルールは、リテラル 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 をブロックしません。Read と Edit ルールで 4 つのアンカー形式と、設定ファイルからのルール解決方法を参照してください。

ロックダウンされたエージェントの場合、allowedTools を permissionMode: "dontAsk" と組み合わせます：

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

リストされたツールは承認されます。ただし、モードが自動承認しないアクションを除きます。プロンプトを表示する他のすべての呼び出しは代わりに拒否されます。default モードで承認が不要な呼び出しは、リストするかどうかに関わらず実行されます。例えば、読み取り専用 Bash コマンド、Agent のような実行前に尋ねないツール、および作業ディレクトリ内のファイル読み取りなどです。ツールを Claude の到達範囲から完全に外すには、その裸の名前を disallowedTools に追加します。

.claude/settings.json で許可、拒否、および質問ルールを宣言的に設定することもできます。これらのルールは、project 設定ソースが有効な場合に読み込まれます。デフォルト query() オプションではこれが有効です。setting_sources（TypeScript：settingSources）を明示的に設定する場合は、それらを適用するために "project" を含めます。権限設定でルール構文を参照してください。

権限モード

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

利用可能なモード

SDK は以下の権限モードをサポートしています。

モード 説明 ツール動作
default 標準的な権限動作 モードベースの自動承認なし。承認が必要で許可ルールに一致しないコールは、canUseTool コールバックをトリガーします
dontAsk プロンプトの代わりに拒否 それ以外の場合はプロンプトが表示されるコールは拒否されます。allowed_tools またはルールで承認されたコール、および default モードで承認が不要なコールは実行されます。コネクタツール（組織が ask に設定）およびユーザーインタラクションが必要なツール、ならびに 重要なパス をターゲットとする rm および rmdir の削除は、事前に承認していても拒否されます。canUseTool は呼び出されません
acceptEdits ファイル編集を自動承認 ファイル編集および ファイルシステム操作（mkdir、rm、mv など）は自動的に承認されます
bypassPermissions 権限チェックをバイパス モードが自動承認しないアクション を除き、ツールは権限プロンプトなしで実行されます。注意して使用してください
plan 計画モード Claude はソースファイルを編集せずに探索と計画を行います。ファイル編集は自動承認されず、canUseTool コールバックを通じてプロンプトが表示されます
auto モデル分類承認 モデル分類器が権限プロンプトを承認または拒否します。利用可能性については 自動モード を参照してください

権限モードを設定する

クエリを開始するときに権限モードを一度設定するか、セッションがアクティブな間に動的に変更できます。

クエリを作成するときに permission_mode（Python）または permissionMode（TypeScript）を渡します。このモードは、動的に変更されない限り、セッション全体に適用されます。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default",  # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

モードの詳細

編集受け入れモード（`acceptEdits`）

ファイル操作を自動承認して、Claude がプロンプトなしでコードを編集できるようにします。その他のツール（ファイルシステム操作ではない Bash コマンドなど）は通常の権限が必要です。

自動承認される操作：

  • ファイル編集（Edit、Write ツール）
  • ファイルシステムコマンド：mkdir、touch、rm、rmdir、mv、cp、sed

どちらも、作業ディレクトリまたは additionalDirectories 内のパスにのみ適用されます。acceptEdits モードでは、Claude が以下の場合、Claude Code は要求を自動承認しません。

  • そのスコープ外のパスで作業する
  • 保護されたパスに書き込む
  • rm または rmdir で 重要なパス を削除する

使用時期： Claude の編集を信頼し、より高速な反復を望む場合。プロトタイピング中や分離されたディレクトリで作業する場合など。

質問しないモード（`dontAsk`）

canUseTool を呼び出さずに、権限プロンプトを拒否に変換します。allowed_tools、settings.json 許可ルール、またはフックで事前承認されたツール、および default モードで承認が不要なコール（作業ディレクトリ内のファイル読み取りや Agent への呼び出しなど）は通常どおり実行されます。コネクタツール（組織が ask に設定）、ユーザーインタラクションが必要なツール、および 重要なパス をターゲットとする rm および rmdir の削除は、許可ルールが一致する場合でも拒否されます。PreToolUse フック許可は、重要なパス削除をクリアしません。

使用時期： ヘッドレスエージェント用に固定された明示的なツールサーフェスを望み、canUseTool が存在しないことへの暗黙的な依存よりもハード拒否を優先する場合。

権限バイパスモード（`bypassPermissions`）

以下に示す場合を除き、プロンプトなしでツール使用を自動承認します。フックは引き続き実行され、必要に応じて操作をブロックできます。

計画モード（`plan`）

Claude はソースファイルを編集せずにコードベースを探索し、計画を作成します。読み取り専用ツールは default 権限モードと同じように実行されます。

ファイル編集は計画モードで自動承認されません。許可ルールが一致する場合でも、代わりに canUseTool コールバックを通じてプロンプトが表示されます。Claude Code v2.1.212 以降では、touch や rm などのファイルを変更するシェルコマンドは同じ方法で canUseTool コールバックに到達します。

Claude は計画を最終化する前に、AskUserQuestion を使用して要件を明確にする場合があります。これらのプロンプトの処理については、承認とユーザー入力の処理 を参照してください。

使用時期： Claude に変更を実行せずに提案させたい場合。コードレビュー中や、変更が行われる前に承認する必要がある場合など。

権限評価フローの他のステップについては、以下をご覧ください。