ガイド

権限の処理

Claude Agent SDKでツールの使用と権限を制御する

SDK権限

Claude Agent SDKは、アプリケーションでClaudeがツールを使用する方法を管理できる強力な権限制御を提供します。

このガイドでは、canUseToolコールバック、フック、およびsettings.json権限ルールを使用して権限システムを実装する方法について説明します。完全なAPIドキュメントについては、TypeScript SDKリファレンスを参照してください。

概要

Claude Agent SDKは、ツールの使用を制御するための4つの補完的な方法を提供します：

権限モード - すべてのツールに影響するグローバル権限動作設定
canUseTool コールバック - 他のルールでカバーされていないケースのランタイム権限ハンドラー
フック - カスタムロジックによるすべてのツール実行の細かい制御
権限ルール (settings.json) - 統合されたbashコマンド解析による宣言的な許可/拒否ルール

各アプローチの使用例：

権限モード - 全体的な権限動作の設定（計画、編集の自動承認、チェックのバイパス）
canUseTool - カバーされていないケースの動的承認、ユーザーに権限を求める
フック - すべてのツール実行のプログラム的制御
権限ルール - インテリジェントなbashコマンド解析による静的ポリシー

権限フロー図

処理順序： PreToolUse Hook → 拒否ルール → 許可ルール → 確認ルール → 権限モードチェック → canUseTool Callback → PostToolUse Hook

権限モード

権限モードは、Claudeがツールを使用する方法のグローバル制御を提供します。query()を呼び出すときに権限モードを設定したり、ストリーミングセッション中に動的に変更したりできます。

利用可能なモード

SDKは4つの権限モードをサポートしており、それぞれ異なる動作をします：

モード	説明	ツールの動作
`default`	標準権限動作	通常の権限チェックが適用される
`plan`	計画モード - 実行なし	Claudeは読み取り専用ツールのみ使用可能；実行前に計画を提示（現在SDKではサポートされていません）
`acceptEdits`	ファイル編集の自動承認	ファイル編集とファイルシステム操作が自動的に承認される
`bypassPermissions`	すべての権限チェックをバイパス	すべてのツールが権限プロンプトなしで実行される（注意して使用）

権限モードの設定

権限モードは2つの方法で設定できます：

1. 初期設定

クエリを作成するときにモードを設定：

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: "このコードのリファクタリングを手伝って",
  options: {
    permissionMode: 'default'  // 標準権限モード
  }
});

2. 動的モード変更（ストリーミングのみ）

ストリーミングセッション中にモードを変更：

モード固有の動作

編集承認モード（`acceptEdits`）

編集承認モードでは：

すべてのファイル編集が自動的に承認される
ファイルシステム操作（mkdir、touch、rm等）が自動承認される
他のツールは通常の権限が必要
Claudeの編集を信頼する場合の開発速度向上
迅速なプロトタイピングと反復に有用

自動承認される操作：

ファイル編集（Edit、Writeツール）
Bashファイルシステムコマンド（mkdir、touch、rm、mv、cp）
ファイルの作成と削除

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

権限バイパスモードでは：

すべてのツール使用が自動的に承認される
権限プロンプトが表示されない
フックは依然として実行される（操作をブロック可能）
極度の注意が必要 - Claudeがシステムへの完全なアクセス権を持つ
制御された環境でのみ推奨

権限フローにおけるモードの優先度

権限モードは権限フローの特定のポイントで評価されます：

フックが最初に実行 - 許可、拒否、確認、または継続が可能
拒否ルールがチェックされる - モードに関係なくツールをブロック
許可ルールがチェックされる - マッチした場合ツールを許可
確認ルールがチェックされる - マッチした場合権限を求める
権限モードが評価される：
- bypassPermissionsモード - アクティブな場合、残りのすべてのツールを許可
- その他のモード - canUseToolコールバックに委譲
canUseToolコールバック - 残りのケースを処理

これは以下を意味します：

フックはbypassPermissionsモードでもツール使用を常に制御できる
明示的な拒否ルールはすべての権限モードを上書きする
確認ルールは権限モードより前に評価される
bypassPermissionsモードはマッチしないツールに対してcanUseToolコールバックを上書きする

ベストプラクティス

通常の権限チェックによる制御された実行にはdefaultモードを使用
分離されたファイルやディレクトリで作業する場合はacceptEditsモードを使用
本番環境や機密データのあるシステムではbypassPermissionsを避ける
細かい制御のためにモードとフックを組み合わせる
タスクの進行と信頼度に基づいてモードを動的に切り替える

モード進行の例：

// 制御された実行のためにdefaultモードで開始
permissionMode: 'default'

// 迅速な反復のためにacceptEditsに切り替え
await q.setPermissionMode('acceptEdits')

canUseTool

canUseToolコールバックはquery関数を呼び出すときにオプションとして渡されます。ツール名と入力パラメータを受け取り、許可または拒否の決定を返す必要があります。

canUseToolは、Claude Codeがユーザーに権限プロンプトを表示する場合に発動します。例えば、フックと権限ルールがそれをカバーしておらず、acceptEditsモードでない場合です。

インタラクティブなツール承認の実装方法を示す完全な例は以下の通りです：

関連リソース

フックガイド - ツール実行の細かい制御のためのフック実装方法を学ぶ
設定: 権限ルール - bashコマンド解析による宣言的な許可/拒否ルールを設定する

import { query } from "@anthropic-ai/claude-agent-sdk";

// ストリーミング入力用の非同期ジェネレーターを作成
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "デフォルト権限で始めましょう" 
    }
  };
  
  // 会話の後で...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "今度は開発を速めましょう"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // デフォルトモードで開始
  }
});

// モードを動的に変更
await q.setPermissionMode('acceptEdits');

// メッセージを処理
for await (const message of q) {
  console.log(message);
}

import { query } from "@anthropic-ai/claude-agent-sdk";

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 ツールリクエスト:");
  console.log(`   ツール: ${toolName}`);
  
  // ツールパラメータを表示
  if (input && Object.keys(input).length > 0) {
    console.log("   パラメータ:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // ユーザー承認を取得（UIロジックに置き換えてください）
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ 承認\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ 拒否\n");
    return {
      behavior: "deny",
      message: "ユーザーがこのツールの権限を拒否しました"
    };
  }
}

// 権限コールバックを使用
const result = await query({
  prompt: "このコードベースの分析を手伝って",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

SDK権限

概要

権限フロー図

権限モード

利用可能なモード

権限モードの設定

1. 初期設定

2. 動的モード変更（ストリーミングのみ）

モード固有の動作

編集承認モード（acceptEdits）

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

権限フローにおけるモードの優先度

ベストプラクティス

canUseTool

関連リソース

SDK権限

概要

権限フロー図

権限モード

利用可能なモード

権限モードの設定

1. 初期設定

2. 動的モード変更（ストリーミングのみ）

モード固有の動作

編集承認モード（acceptEdits）

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

権限フローにおけるモードの優先度

ベストプラクティス

canUseTool

関連リソース

編集承認モード（`acceptEdits`）

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

編集承認モード（`acceptEdits`）

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