権限の設定

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

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

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

[!NOTE]

mod を含むプラグインを読み込む場合は、ルールとフックの中で mod の決定がどこに位置するか を参照してください。

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

1. フック

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

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

2. Deny ルール

disallowed_tools または settings.json の deny ルールがマッチした場合、bypassPermissions モードであっても、またフックが allow を返した場合であっても、呼び出しは拒否され、canUseTool は呼び出されません。

TypeScript SDK では、カスタムツール の permission_policy を always_deny に設定した場合、そのツールの呼び出しはこのステップで拒否されます。

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 モードでは、このモードは決してプロンプトを表示しないため、呼び出しは拒否されます。

TypeScript SDK では、カスタムツールの permission_policy を always_ask に設定した場合、どの allow ルールもその呼び出しを承認しません。allowedTools のエントリであっても同様です。dontAsk モードでは Claude Code はそれらの呼び出しを拒否し、auto、plan、または bypassPermissions モードではコールバックが実行される前に それらを承認できます。

4. 権限モード

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

• bypassPermissions モードでは、Claude Code はこのステップに到達したすべてのものを承認します。ただし、認識された 重要なパスの削除 と、Dangerous rm operation not ruled out のフラグが付いた Bash コマンドは除き、これらは代わりにフォールスルーします。
  • これらの削除をプロンプトなしで実行するには、重要なパスの削除プロンプトをオフにする を参照してください。
• acceptEdits モードでは、Claude Code は Accept edits モード の下にリストされたファイル操作を承認します。
• plan モードでは、Claude Code は allow ルールに関係なく、ファイル編集ツールを canUseTool コールバックに送信します。
• その他のモードでは、リクエストはフォールスルーします。

5. Allow ルール

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

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

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

6. canUseTool コールバック

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

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

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

• permissionMode: 'bypassPermissions'：警告テキストは canUseTool will not be invoked: permissionMode 'bypassPermissions' で始まります。ツール呼び出しは canUseTool に問い合わせる前に承認されるため、コールバックは Bypass permissions モード に記載されている呼び出しなど、ごく一部の呼び出しに対してのみ実行されます。承認された呼び出しもチェックするには、コールバックのチェックを PreToolUse フック に入れます
• "Read" のようにツール名のみの allowedTools エントリ：警告は canUseTool will not be invoked for: の後にそのような各エントリを列挙します。列挙されたツールへの呼び出しは、allow ルールが決して承認しない呼び出し を除き、canUseTool に問い合わせる前に承認されます。承認が必要な、列挙されたツールの呼び出しに対してコールバックを実行させるには、そのツールのエントリを allowedTools から削除します

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

この警告は呼び出しをブロックしたり、オプションを変更したりすることはありません。確認したいすべての呼び出しをコールバックがすでに受け取っている場合は、設定をそのままにしておいてください。警告をログに記録するには、process.on('warning', ...) でリッスンし、CLAUDE_SDK_CAN_USE_TOOL_SHADOWED コードをマッチさせます。

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

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

許可ルールと拒否ルール

allowed_tools と disallowed_tools（TypeScript：allowedTools / disallowedTools）は、上記の評価フロー内の許可ルールと拒否ルールリストにエントリを追加します。allowed_tools にタスク追跡ツールの 1 つを名前で指定すると、Claude Code はそのセッションでタスク追跡ツールも有効にします。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 をブロックしません。Read と Edit ルールで 4 つのアンカー形式と、設定ファイルからのルール解決方法を参照してください。

[!WARNING]

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

allowed_tools 内のツールへの呼び出しが引き続き canUseTool コールバックに到達する場合、または dontAsk モードで拒否される場合は、それらがネットワークパスからの読み取りであるか、次のいずれかの呼び出しに該当するかを確認してください。これらの呼び出しを承認する許可ルールはありません。プロンプトを一切表示しない dontAsk モードでは、Claude Code は canUseTool を呼び出さずにこれらを拒否します。その他の権限モードでは、各項目の説明に従って処理します：

• AskUserQuestion、_meta["anthropic/requiresUserInteraction"] でマークされた MCP ツール、および組織が ask に設定したコネクタツール：コールバックで応答します。明確化のための質問を処理するでは AskUserQuestion への応答方法を示しています。コネクタの呼び出しは理由 Your organization requires approval for this tool とともに届きます

• アプリケーションが always_ask とマークしたカスタムツール：コールバックで呼び出しを判断します。これらの呼び出しが届かないようにするには、セッション中にポリシーを変更します。auto、plan、bypassPermissions モードでは、always_ask 呼び出しを承認できる権限モードに記載されているケースで、代わりにコールバックの前に呼び出しが承認される場合があります

• 認識された rm および rmdir の重要なパスの削除：default、acceptEdits、bypassPermissions モードでは、コールバックで削除を許可または拒否します。このとき decisionReason は Dangerous rm で始まります。auto および plan モードについては、各権限モードにおける重要なパスの削除を参照してください。これらの削除を認識するチェックは、一部のコマンドを見逃す可能性があります

• 裸の名前：Read や mcp__github__get_issue のようなエントリは、どのモードも自動承認しないアクションとネットワークパスからの読み取りを除いて、そのツールへのすべての呼び出しを自動承認します。

• スコープ付きルール：Bash(npm test *) のようなエントリはマッチする呼び出しのみを自動承認し、承認が必要な他の Bash 呼び出しは引き続きコールバックにフォールスルーします。

すべてのツール呼び出しで実行する必要があるチェックの場合は、PreToolUse フックを使用します：フックはすべての他のステップの前に実行され、フック拒否は bypassPermissions モードでも適用されます。

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

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

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

default モードで承認が不要な呼び出しは、リストするかどうかに関わらず実行されます。例えば、読み取り専用 Bash コマンド、Agent のような実行前に尋ねないツール、および作業ディレクトリ内のファイル読み取りなどです。組み込みツールの呼び出しを拒否するのではなく、Claude からそのツールを完全に隠すには、その裸の名前を 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 は次の権限モードをサポートしています。

[!WARNING]

サブエージェントの継承： メインセッションが plan モードの場合、AgentDefinition で permissionMode: "acceptEdits" を設定したサブエージェントも plan モードで実行されます。そのサブエージェントによるソースファイルへの Edit および Write の呼び出しは、引き続き canUseTool コールバックに渡されます。plan モードは定義したサブエージェントにも適用されるため、サブエージェントに作業を任せても、先に計画を確認する手順を回避することはできません。

サブエージェントは、メインセッションから plan、acceptEdits、auto、または bypassPermissions を継承し、メインセッションが default または dontAsk モードの場合は、設定したモードで実行されます。その場合でも、Claude Code は "bypassPermissions" の値を適用することはなく、"auto" の値はそのサブエージェントで auto モードが利用可能な場合にのみ適用します。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 で削除する
• たとえばオプションや glob を付けて、または timeout 5 や LANG=C のプレフィックスを付けて touch を実行する

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

Don't ask モード（dontAsk）

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

次の呼び出しは、許可ルールに一致していても拒否されます。

• 組織が ask に設定したコネクタツール
• AskUserQuestion や、サーバーが _meta["anthropic/requiresUserInteraction"] を設定している MCP ツールなど、ユーザーの操作を必要とするツール
• アプリケーションが permission_policy を always_ask に設定しているカスタムツール
• ネットワークパスからの読み取り
• 認識されたクリティカルパスの削除

PreToolUse フックが、認識されたクリティカルパスの削除、ネットワークパスからの読み取り、または always_ask が設定されたツールの呼び出しに対して allow を返した場合でも、その呼び出しは拒否されます。これらの削除を認識するチェックは一部のコマンドを見逃す可能性があります。

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

Bypass permissions モード（bypassPermissions）

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

[!WARNING]

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

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

• 拒否ルール、明示的な ask ルール、およびフックはモードのチェックより前に評価され、引き続きツールをブロックできます。
• 組織が ask に設定したコネクタツール、ユーザーの操作を必要とするツール、および認識されたクリティカルパスの削除は、引き続き canUseTool コールバックに渡されます。これらの削除を認識するチェックは一部のコマンドを見逃す可能性があります。また、クリティカルパスの削除プロンプトをオフにすることもできます。クラウドセッション外では、アプリケーションが always_ask に設定したカスタムツールの呼び出しもコールバックに渡されます。
• セッション間メッセージングの安全策は引き続き適用されます。

Plan モード（plan）

Claude はソースファイルを編集せずにコードベースを探索し、計画を作成します。plan モードでは、許可ルールに一致した場合や PreToolUse フックが allow を返した場合でも、ファイル編集が自動承認されることはありません。代わりに、canUseTool コールバックを通じてプロンプトが表示されます。

セッションで auto モードが利用可能な間は、計画中に Claude が実行するコマンドはデフォルトではコールバックに渡されません。auto モードが使用する分類器モデルが代わりにそれらを審査するためです。この審査が有効な場合、分類器は、許可ルールのない WebFetch の呼び出しなど、本来であればコールバックに渡される読み取り専用の呼び出しを承認することもできます。

[!NOTE]

TypeScript SDK では、permissionMode: 'plan' と併せて allowDangerouslySkipPermissions: true を設定した場合でも、ファイル編集は引き続き canUseTool コールバックに渡されます。plan モードで開始したセッションを後で setPermissionMode() を使って bypassPermissions に切り替えるには、最初から allowDangerouslySkipPermissions を設定しておく必要があります。

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 以降が必要です。

関連リソース

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

• 承認とユーザー入力の処理：インタラクティブな承認プロンプトと確認質問
• Hooks ガイド：エージェントライフサイクルの重要なポイントでカスタムコードを実行
• 権限ルール：settings.json の宣言的な許可/拒否ルール