権限の設定

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

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

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

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

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

• permissionMode: 'bypassPermissions'。これは permission モードステップに到達するすべての呼び出しを自動承認します。ただし、どのモードも自動承認しないアクション は除きます。
• "Read" などの各裸の allowedTools エントリ。これはコールバックが相談される前にそのツール全体を自動承認します。ただし、どのモードも自動承認しないアクション は除きます。

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 でも利用可能であり、承認が必要なそのツールへの呼び出しは権限モードにフォールスルーします。拒否ルールは、ツール名を指定するか、ツール内のパターンをスコープするかによって動作が異なります。

許可ルールは、リテラル 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 は以下の権限モードをサポートしています。

権限モードを設定する

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

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();

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

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

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

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

計画モード（`plan`）

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

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

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

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

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

関連リソース

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

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