パーミッションの設定

パーミッションモード、フック、宣言的な許可/拒否ルールを使用して、エージェントがツールをどのように使用するかを制御します。

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

パーミッションの評価方法

Claude がツールをリクエストすると、SDK は次の順序でパーミッションをチェックします。

このページは許可および拒否ルールとパーミッションモードに焦点を当てています。その他のステップについては、以下を参照してください。

• フック： カスタムコードを実行して、ツールリクエストを許可、拒否、または変更します。フックで実行を制御を参照してください。
• canUseTool コールバック： 実行時にユーザーに承認を促します。承認とユーザー入力の処理を参照してください。

許可および拒否ルール

allowed_tools および disallowed_tools（TypeScript：allowedTools / disallowedTools）は、上記の評価フロー内の許可および拒否ルールリストにエントリを追加します。許可ルールは承認のみに影響します。allowed_tools にリストされていないツールは引き続き Claude に利用可能であり、パーミッションモードにフォールスルーします。拒否ルールは、ツール全体に名前を付けるか、ツール内のパターンをスコープするかによって異なる動作をします。

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

ロックダウンされたエージェントの場合、allowedTools を permissionMode: "dontAsk" と組み合わせます。リストされたツールは承認されます。その他のものはプロンプトの代わりに直接拒否されます。

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

.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",  # ここでモードを設定
),
):
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" // ここでモードを設定
}
})) {
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",  # デフォルトモードで開始
)
) as client:
await client.query("Help me refactor this code")

# セッション中盤でモードを動的に変更
await client.set_permission_mode("acceptEdits")

# 新しいパーミッションモードでメッセージを処理
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" // デフォルトモードで開始
}
});

// セッション中盤でモードを動的に変更
await q.setPermissionMode("acceptEdits");

// 新しいパーミッションモードでメッセージを処理
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 内のパスにのみ適用されます。そのスコープ外のパスおよび保護されたパスへの書き込みはプロンプトが表示されます。

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

質問しないモード（`dontAsk`）

パーミッションプロンプトを拒否に変換します。allowed_tools、settings.json 許可ルール、またはフックで事前承認されたツールは通常どおり実行されます。その他のすべては canUseTool を呼び出さずに拒否されます。

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

パーミッションバイパスモード（`bypassPermissions`）

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

計画モード（`plan`）

Claude はコードベースを探索および計画を作成し、ソースファイルを編集しません。読み取り専用ツールはデフォルトモードと同じように実行されます。ファイル編集は計画モードで自動承認されることはなく、許可ルールが一致する場合でも、代わりに canUseTool コールバックを通じてプロンプトが表示されます。Claude は計画を最終化する前に要件を明確にするために AskUserQuestion を使用する場合があります。これらのプロンプトの処理については、承認とユーザー入力の処理を参照してください。

使用時期： Claude に変更を提案させたいが実行させたくない場合、たとえばコードレビュー中または変更を実行する前に承認が必要な場合。

関連リソース

パーミッション評価フロー内の他のステップについては、以下を参照してください。

• 承認とユーザー入力の処理：対話的な承認プロンプトと明確化の質問
• フックガイド：エージェントライフサイクルの主要なポイントでカスタムコードを実行
• パーミッションルール：settings.json の宣言的な許可/拒否ルール