SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 100 additions and 130 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. Hooks

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

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 ルールによって決して承認されません。その後、コールバックに到達するかどうかは permission モードに依存します。例えば、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 つはコールバックに到達します。権限モードに応じて、重要なパス削除はコールバックに到達するか、Claude Code はそれを呼び出さずに拒否します。デフォルトでは Agent SDK セッションの auto モードでそうするように、です。

カバレッジはエントリの形式に依存します：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 プロンプトの代わりに拒否 それ以外の場合はプロンプトが表示されるコールは拒否されます。ただし、インストールした mod は引き続き それらのコールの一部 を承認できます。allowed_tools またはルールで承認されたコール、および default モードで承認が不要なコールは実行されます。コネクタツール（組織が ask に設定）、ユーザーインタラクションが必要なツール、ネットワークパスからの読み取り、ならびに 重要なパス をターゲットとする rm および rmdir の削除は、事前に承認していても拒否されます。canUseTool は呼び出されません
acceptEdits ファイル編集を自動承認 ファイル編集および ファイルシステム操作（mkdir、rm、mv など）は自動的に承認されます
bypassPermissions 権限チェックをバイパス モードが自動承認しないアクション を除き、ツールは権限プロンプトなしで実行されます。注意して使用してください
plan 計画モード Claude はソースファイルを編集せずに探索と計画を行います。ファイル編集は自動承認されず、canUseTool コールバックを通じてプロンプトが表示されます
auto モデル分類承認 モデル分類器がシェルコマンドやネットワークリクエストなどのアクションをレビューし、レビューする各アクションを許可またはブロックします。利用可能性と決定順序については 自動モード を参照してください

[!WARNING]

サブエージェント継承： サブエージェントは、その AgentDefinition で permissionMode を設定し、親セッションが default、dontAsk、または plan モードにある場合を除き、親セッションの権限モードで実行されます。その場合でも、Claude Code は "bypassPermissions" 値を適用せず、"auto" 値はそのサブエージェントで auto モードが利用可能 な場合にのみ適用します。サブエージェントは、親セッション自体が bypassPermissions モードにある場合にのみ、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();

モードの詳細

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

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

自動承認される操作：

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

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

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

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

質問しないモード（dontAsk）

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

コネクタツール（組織が ask に設定）、ユーザーインタラクションが必要なツール、ネットワークパスからの読み取り、および 重要なパス をターゲットとする rm および rmdir の削除は、許可ルールが一致する場合でも拒否されます。PreToolUse フックによる許可も、重要なパスの削除やネットワークパスからの読み取りをクリアしません。

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

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

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

[!WARNING]

極度の注意を持って使用してください。このモードでは Claude はシステムへの完全なアクセスを持ちます。信頼できるすべての操作が可能な制御された環境でのみ使用してください。

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

  • 拒否ルール、明示的な ask ルール、およびフックはモードチェック前に評価され、ツールをブロックできます。
  • コネクタツール（組織が ask に設定）、ユーザーインタラクションが必要なツール、および 重要なパス をターゲットとする rm および rmdir の削除は、引き続き canUseTool コールバックにフォールスルーします。
  • クロスセッションメッセージングセーフガード は引き続き適用されます。

計画モード（plan）

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

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

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

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

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

auto モード（auto）

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

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

  • 表示される内容：subtype が 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 以降が必要です。

関連リソース

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