SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-21 23:02 UTC to 2026-10-22 22:58 UTC

This page contains 70 additions and 68 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

権限の設定

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

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

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

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

1. フック

最初に フック を実行します。フックは呼び出しを完全に拒否するか、それを通すことができます。allow を返すフックは、以下の deny および ask ルールをスキップしません。これらはフックの結果に関係なく評価されます。

allow を返す PreToolUse フックは、rm -rf ~ のように、Claude Code が対象を 重要なパス と認識する rm または rmdir コマンドを承認することもできません。plan モードでその allow がどのように動作するかについては、plan モードでのフックの承認 を参照してください。

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

5. Allow ルール

allow ルール（allowed_tools および settings.json から）をチェックします。ルールがマッチした場合、ツールは承認されます。ツール自体が承認する呼び出しもこのステップで解決されます。ルールは不要です。例えば、作業ディレクトリ内のファイル読み取りや 読み取り専用 Bash コマンド です。

認識された 重要なパスの削除 は、allow ルールによって承認されません。その後コールバックに到達するかどうかは権限モードに依存します。例えば、auto モードの Agent SDK セッションでは、Claude Code はデフォルトでコールバックを呼び出さずにそれらを拒否します。重要なパスのモード表 に、各モードがそれらをどう扱うかがリストされています。

allow ルールは、ネットワークパス からの読み取りを承認しません。

6. canUseTool コールバック

上記のいずれでも解決されない場合、決定のために canUseTool コールバック を呼び出します。dontAsk モードでは、このステップはスキップされ、ツールは拒否されます。ただし、インストールした mod は、そのような呼び出しの一部 を引き続き承認できます。

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 にルーティングします。

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 つのアンカー形式と、設定ファイルからのルール解決方法を参照してください。

[!WARNING]

自動承認ツールは canUseTool に到達しません。 acceptEdits または bypassPermissions によって、または許可ルールによって、任意の前のステップで承認されたツール呼び出しは、その canUseTool コールバックをスキップするため、そこに配置した権限チェックはそのツールに対して静かにバイパスされます。

許可ルールは、AskUserQuestion、MCP ツール（_meta["anthropic/requiresUserInteraction"]でマークされている）、コネクタツール（組織が ask に設定）、および認識された rm と rmdir の重要なパスの削除を自動承認することはありません。dontAsk モードでは、Claude Code はこれらの呼び出しをコールバックを呼び出さずに拒否します。他のモードでは、最初の 3 つはコールバックに到達します。重要なパスのモード表には、各モードが重要なパスの削除をどのように扱うかが記載されています。これらの削除を認識するチェックは、一部のコマンドを見逃す可能性があります。

カバレッジはエントリの形式に依存します：Read や mcp__github__get_issue のような裸の名前は、上記の例外とネットワークパスからの読み取りを除いて、そのツールへのすべての呼び出しを自動承認しますが、Bash(npm test *) のようなスコープ付きルールはマッチする呼び出しのみを自動承認し、承認が必要な他の Bash 呼び出しはコールバックにフォールスルーします。すべてのツール呼び出しで実行する必要があるチェックの場合は、PreToolUse フックを使用します：フックはすべての他のステップの前に実行され、フック拒否は bypassPermissions モードでも適用されます。

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

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

リストされたツールは承認されます。ただし、どのモードも自動承認しないアクションとネットワークパスからの読み取りを除きます。プロンプトを表示する他のすべての呼び出しは代わりに拒否されます。ただし、インストールした mod は、それらの呼び出しの一部を引き続き承認できます。

default モードで承認が不要な呼び出しは、リストするかどうかに関わらず実行されます。例えば、読み取り専用 Bash コマンド、Agent のような実行前に尋ねないツール、および作業ディレクトリ内のファイル読み取りなどです。ツールをリクエストから完全に削除するには、その裸の名前を disallowedTools に追加します。

[!WARNING]

allowed_tools は bypassPermissions を制約しません。 allowed_tools はリストしたツールを事前承認します。リストされていない他のツールは、許可ルールによってマッチされず、権限モードにフォールスルーします。ここで bypassPermissions はそれらを承認します。allowed_tools=["Read"] を permission_mode="bypassPermissions" と一緒に設定すると、Bash、Write、Edit を含むすべてのツールが承認されます。bypassPermissions が必要だが、特定のツールをブロックしたい場合は、disallowed_tools を使用します。

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

権限モード

権限モードは、Claude がツールを使用する方法をグローバルに制御します。権限モードは query() の呼び出し時に設定することも、ストリーミングセッション中に動的に変更することもできます。

Claude Code v2.1.302 以降では、権限モードを設定しない限り、または設定ファイル内の permissions.defaultMode から権限モードが取得されない限り、アプリは default モードで起動します。default モードでは、許可ルール、フック、canUseTool コールバック、または権限プロンプトツールによって承認しない限り、Claude Code は承認が必要なツール呼び出しをすべて拒否します。ツール呼び出しが拒否される場合は、claude -p および Agent SDK の実行でツール呼び出しが拒否されるを参照してください。

利用可能なモード

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

モード 説明 ツールの動作
default 標準の権限動作 モードに基づく自動承認はありません。承認が必要で、どの許可ルールにも一致しない呼び出しは canUseTool コールバックをトリガーします
dontAsk プロンプトを表示せずに拒否 本来であればプロンプトが表示される呼び出しは、canUseTool を呼び出さずに拒否されます。ただし、インストールした mod がそれらの呼び出しの一部を引き続き承認できます。allowed_tools または settings.json の許可ルールで承認された呼び出しは実行され、default モードで承認を必要としない呼び出しも実行されます。ネットワークパスからの読み取りなど一部の呼び出しは、allowed_tools や許可ルールに一致していても拒否されます。一覧については、Don't ask モードを参照してください
acceptEdits ファイル編集を自動承認 ファイル編集とファイルシステム操作（mkdir、rm、mv など）が自動的に承認されます
bypassPermissions 権限チェックをバイパス どのモードでも自動承認されないアクションを除き、ツールは権限プロンプトなしで実行されます。注意して使用してください
plan 計画モード Claude はソースファイルを編集せずに探索と計画を行います。ファイル編集は自動承認されることはなく、canUseTool コールバックを通じてプロンプトが表示されます
auto モデルによる分類に基づく承認 モデル分類器がシェルコマンドやネットワークリクエストなどのアクションを審査し、審査した各アクションを許可またはブロックします。利用条件と判定順序については、auto モードを参照してください

[!WARNING]

サブエージェントの継承： サブエージェントは、その AgentDefinition で permissionMode を設定し、かつ親セッションが default、dontAsk、または plan モードである場合を除き、親セッションの権限モードで実行されます。その場合でも、Claude Code は "bypassPermissions" の値を適用することはなく、"auto" の値はそのサブエージェントで auto モードが利用可能な場合にのみ適用します。サブエージェントが bypassPermissions モードで実行されるのは、親セッション自体がそのモードである場合のみです。bypassPermissions に関するこの例外には Claude Code v2.1.267 以降が必要です。

サブエージェントは、メインエージェントとは異なるシステムプロンプトを持ち、制約の少ない動作をする場合があるため、bypassPermissions を継承すると、完全かつ自律的なシステムアクセスが付与されます。どのモードでも自動承認されないアクションは引き続き適用されます。

権限モードを設定する

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

クエリ時

クエリを作成する際に、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())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

ストリーミング中

セッションの途中でモードを変更するには、set_permission_mode()（Python）または setPermissionMode()（TypeScript）を呼び出します。新しいモードは、以降のすべてのツールリクエストに即座に適用されます。これにより、最初は制限的に開始し、信頼が構築されるにつれて権限を緩めることができます。たとえば、Claude の最初のアプローチを確認した後に acceptEdits に切り替えることができます。

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

モードの詳細

Accept edits モード（acceptEdits）

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

自動承認される操作：

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

いずれも、作業ディレクトリまたは additionalDirectories 内のパスにのみ適用されます。acceptEdits モードでは、Claude が次のことを行う場合、Claude Code はリクエストを自動承認しません。

  • そのスコープ外のパスを操作する
  • 保護されたパスに書き込む
  • Claude Code がクリティカルパスとして認識するパスを rm または rmdir で削除する

使用する場面： Claude の編集を信頼しており、プロトタイピング中や隔離されたディレクトリで作業する場合など、より速く反復したいとき。

Don't ask モード（dontAsk）

すべての権限プロンプトを、canUseTool を呼び出さずに拒否に変換します。ただし、インストールした mod がそれらの呼び出しの一部を引き続き承認できます。allowed_tools、settings.json の許可ルール、またはフックによって事前承認されたツールは通常どおり実行されます。作業ディレクトリ内でのファイル読み取りや Agent の呼び出しなど、default モードで承認を必要としない呼び出しも実行されます。

組織が ask に設定したコネクタツール、ユーザーの操作を必要とするツール、ネットワークパスからの読み取り、および認識されたクリティカルパスの削除は、許可ルールに一致していても拒否されます。PreToolUse フックによる許可も、認識されたクリティカルパスの削除やネットワークパスからの読み取りを通過させることはありません。これらの削除を認識するチェックは一部のコマンドを見逃す可能性があります。

使用する場面： ヘッドレスエージェントに対して固定された明示的なツールのサーフェスを用意したく、canUseTool が存在しないことに暗黙的に頼るよりも確実な拒否を望むとき。

Bypass permissions モード（bypassPermissions）

以下の警告に記載されたケースを除き、ツールの使用をプロンプトなしで自動承認します。フックは引き続き実行され、必要に応じて操作をブロックできます。Linux および macOS では、認識されたサンドボックスの外で root として、または sudo の下でこのモードで起動しようとすると、Claude Code は起動を拒否し、クエリは最初のターンの前に失敗します。

[!WARNING]

細心の注意を払って使用してください。このモードでは、Claude はシステムへの完全なアクセス権を持ちます。発生しうるすべての操作を信頼できる、管理された環境でのみ使用してください。

allowed_tools はこのモードを制約しません。リストに含めたツールだけでなく、すべてのツールが承認されます。次の制御は引き続き適用されます。

Plan モード（plan）

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

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

TypeScript SDK では、permissionMode: 'plan' と併せて allowDangerouslySkipPermissions: true を設定した場合でも、ファイル編集およびファイルを変更するシェルコマンドは引き続き canUseTool コールバックに渡されます。このオプションにより、後で setPermissionMode() を使って bypassPermissions に切り替えることができます。

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

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

Auto モード（auto）

分類器モデルが、シェルコマンドやネットワークリクエストなどのアクションを実行前に審査し、審査した各アクションを許可またはブロックします。auto モードに必要なモデルとプロバイダー、およびアクションを評価する順序については、auto モードで権限プロンプトをなくすを参照してください。

auto モードのセッションを、set_model()、setModel()、または applyFlagSettings() を使用して auto モードがサポートしていないモデルに切り替えると、セッションは default モードに変わります。

  • 表示される内容：サブタイプが status で、permissionMode が "default" に設定された system メッセージです。TypeScript SDK ではこれを SDKStatusMessage として型付けしています。以降、承認が必要でどの許可ルールにも一致しない呼び出しは、canUseTool コールバックに渡されます。
  • auto モードに戻すには：サポートされているモデルに切り替えてから、set_permission_mode("auto") または setPermissionMode("auto") を呼び出します。この呼び出しを行わずにモデルを元に戻した場合、セッションは default モードのままです。サポートされていないモデルがアクティブな間は、この呼び出しは Cannot set permission mode to auto: auto mode unavailable for this model で失敗します。

set_model()、setModel()、または applyFlagSettings() の呼び出し後に default モードへ変わる動作には、Claude Code v2.1.299 以降が必要です。

関連リソース

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