権限の設定

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

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

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

[!NOTE]

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

Claude がツールの使用を求めると、Claude Code は以下のステップで呼び出しをチェックします。各ステップは、呼び出しを決定するか、canUseTool コールバックに送るか、次のステップに渡すことができます。

1. フック

フックを実行します。フックは呼び出しを即座に拒否することも、次に渡すこともできます。allow を返すフックであっても、拒否ルールと確認ルールのステップはスキップされません。これらのステップはフックの結果に関係なく評価されます。

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

2. Deny ルール

disallowed_tools または SDK が読み込む設定ファイル の deny ルールがマッチした場合、呼び出しは拒否され、canUseTool は呼び出されません。bypassPermissions モードであっても、またフックが allow を返した場合であっても、呼び出しはこのように拒否されます。

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 はこのステップに到達した各呼び出しを承認します。ただし、どのモードでも自動承認されないアクション のいずれかである場合は除きます。それらのアクションのうちどれが canUseTool コールバックに送られるかについては、Bypass permissions モード を参照してください。
• acceptEdits モードでは、Claude Code は Accept edits モード の下にリストされたファイル操作を承認します。
• plan モードでは、一部の呼び出しはコールバックに到達し、auto モードが利用可能な場合、その他の呼び出しは代わりに auto モードの分類器に送られます。詳細については、Plan モード を参照してください。
• default および dontAsk モードでは、呼び出しは allow ルールに進みます。
• auto モードについては、Auto モード を参照してください。

5. Allow ルール

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

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

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

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 コールバック： 前のステップで呼び出しが解決されない場合、実行時にユーザーの承認をプロンプトします。承認とユーザー入力を処理する を参照してください。

許可ルールと拒否ルール

allowedTools と disallowedTools（TypeScript）または allowed_tools と disallowed_tools（Python）を設定すると、Claude Code はそれらのエントリを権限評価フロー内の許可ルールリストと拒否ルールリストに追加します。allowed_tools にリストされていない他のツールは、Claude でも利用可能であり、承認が必要なそのツールへの呼び出しは権限モードにフォールスルーします。

許可ルールは、リテラル mcp__<server>__ プレフィックスの後にのみツール名グロブを受け入れます。サーバーセグメントはグロブフリーである必要があり、設定したサーバーを指定します：mcp__puppeteer__* は puppeteer サーバーからのすべてのツールにマッチし、mcp__github__get_* はその get_ ツールにマッチします。allowed_tools=["*"] や allowed_tools=["mcp__*"] のようなアンカーなしエントリは無視され、何も自動承認しません。

[!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 呼び出しは権限モードにフォールスルーします。

許可ルール、acceptEdits、または bypassPermissions が承認する呼び出しをチェックするには、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 モードでは、Claude Code はリストされていないツールへの呼び出しも、どのモードも自動承認しないアクションのいずれかでない限り承認します。

allowed_tools=["Read"] を permission_mode="bypassPermissions" と一緒に設定しても、Claude Code は Bash、Write、Edit などのツールへの呼び出しを承認します。bypassPermissions が必要だが、特定のツールをブロックしたい場合は、disallowed_tools を使用します。このモードでも canUseTool コールバックに到達する呼び出しについては、権限バイパスモードを参照してください。

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

プロジェクトの .claude/settings.json 内の許可ルールがいつ適用されるかについては、プロジェクトの許可ルールとワークスペースの信頼を参照してください。

ルール内のパスパターン

Read と Edit のスコープ付きルールはパスパターンを取ります。Edit(path) ルールは、Write と NotebookEdit を含む、ファイルを書き込むすべての組み込みツールを管理するため、これらのいずれに対するパスルールも Edit(path) として記述してください。パスルールを Write(path) または NotebookEdit(path) として記述すると、どの呼び出しにもマッチせず、効果はありません。

allowed_tools と disallowed_tools では、絶対パスの場合はパスパターンを // で始め、セッションの作業ディレクトリ内のパスの場合は単一の / で始めます：

• //path：Edit(//secrets/**) の拒否ルールがある場合、Claude Code は Claude のファイルツールおよびtee や > file リダイレクトなどの Bash コマンドによる、ディスク上の /secrets 以下への書き込みをブロックします。Claude が実行し、自らファイルを開くスクリプトは、引き続き /secrets 以下に書き込むことができます。オペレーティングシステムによる強制については、サンドボックス化された Bash ツールを設定するを参照してください。
• /path：Edit(/secrets/**) は作業ディレクトリ内の secrets ディレクトリにマッチします。

パスパターンを開始するその他の方法については、Read と Edit ルールを参照してください。

権限モード

権限モードは、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 を継承すると、完全かつ自律的なシステムアクセスが付与されます。どのモードでも自動承認されないアクションは引き続き適用されます。

権限モードを設定する

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

[tab] クエリ時

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

[tab] ストリーミング中

セッションの途中でモードを変更するには、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、NotebookEdit ツールによるファイル編集
• ファイルシステムコマンド：mkdir、touch、rm、rmdir、mv、cp、sed

いずれも、作業ディレクトリまたは追加したディレクトリ内のパスに適用されます。ディレクトリを追加するには、Python では add_dirs、TypeScript では 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 を返した場合でも、その呼び出しは拒否されます。これらの削除を認識するチェックは一部のコマンドを見逃す可能性があります。

使用する場面： ヘッドレスエージェントを実行しており、本来であればプロンプトが表示される各呼び出しを確実に拒否したいとき。

Bypass permissions モード（bypassPermissions）

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

[!WARNING]

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

allowed_tools はこのモードを制限せず、リストに含めていないツールの呼び出しも承認されます。次の制御は引き続き適用されます：

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

Plan モード（plan）

Claude はコードベースを探索し、計画を作成します。計画中は、保護されたパス外で Claude のファイルツールを使って行われる編集は、許可ルールに一致した場合や PreToolUse フックが allow を返した場合でも、canUseTool コールバックに渡されます。AskUserQuestion の呼び出しも、許可ルールでそのツールが指定されている場合でもコールバックに渡されます。

auto モードが利用可能な場合、どの許可ルールでも承認されない次の呼び出しについて、Claude Code は計画中にコールバックではなく auto モードの分類器に送って審査させます。

• シェルコマンド
• Web フェッチ
• Web 検索
• サーバーが読み取り専用としてマークしている MCP ツールの呼び出し

この審査はデフォルトでオンになっています。オフにするには、query() に渡す settings オプション、またはユーザー設定で useAutoModeDuringPlan を false に設定します。審査がオフの間は、Web 検索と読み取り専用としてマークされた MCP ツールの呼び出しはコールバックに渡されます。

シェルコマンドと Web フェッチについて、各呼び出しがコールバックに渡されるかどうかを次の表に示します。

分類器が連続して複数の呼び出しを拒否した後の動作については、繰り返しブロックのしきい値を参照してください。

[!NOTE]

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

使用する場面： コードレビュー中や大きな変更の前など、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 の宣言的な許可/拒否ルール