SDK権限

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

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

概要

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

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

各アプローチの使用例：

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

権限フロー図

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([ツールリクエスト]) --> PreHook(PreToolUse Hook)

    PreHook -->|  許可  | Execute(ツール実行)
    PreHook -->|  拒否  | Denied(拒否)
    PreHook -->|  確認  | Callback(canUseTool Callback)
    PreHook -->|  継続  | Deny(拒否ルールチェック)

    Deny -->|  マッチ  | Denied
    Deny -->|  マッチなし  | Allow(許可ルールチェック)

    Allow -->|  マッチ  | Execute
    Allow -->|  マッチなし  | Ask(確認ルールチェック)

    Ask -->|  マッチ  | Callback
    Ask -->|  マッチなし  | Mode{権限モード?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  その他のモード  | Callback

    Callback -->|  許可  | Execute
    Callback -->|  拒否  | Denied

    Denied --> DeniedResponse([エージェントへのフィードバック])

    Execute --> PostHook(PostToolUse Hook)
    PostHook --> Done([ツールレスポンス])

    style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

    style Denied fill:#BF4D43,color:#fff
    style DeniedResponse fill:#BF4D43,color:#fff
    style Execute fill:#DAAF91,color:#191919
    style Done fill:#DAAF91,color:#191919

    classDef hookClass fill:#CC785C,color:#fff
    class PreHook,PostHook hookClass

    classDef ruleClass fill:#EBDBBC,color:#191919
    class Deny,Allow,Ask ruleClass

    classDef modeClass fill:#A8DAEF,color:#191919
    class Mode modeClass

    classDef callbackClass fill:#D4A27F,color:#191919
    class Callback callbackClass

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

権限モード

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

利用可能なモード

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

権限モードの設定

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

1. 初期設定

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

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

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

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

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

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

モード固有の動作

編集承認モード（acceptEdits）

編集承認モードでは：

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

自動承認される操作：

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

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

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

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

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

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

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

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

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

ベストプラクティス

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

モード進行の例：

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

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

canUseTool

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

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

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

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

関連リソース

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