Izin SDK

Claude Agent SDK menyediakan kontrol izin yang kuat yang memungkinkan Anda mengelola bagaimana Claude menggunakan alat dalam aplikasi Anda.

Panduan ini mencakup cara mengimplementasikan sistem izin menggunakan callback canUseTool, hooks, dan aturan izin settings.json. Untuk dokumentasi API lengkap, lihat referensi SDK TypeScript.

Ikhtisar

Claude Agent SDK menyediakan empat cara yang saling melengkapi untuk mengontrol penggunaan alat:

Mode Izin - Pengaturan perilaku izin global yang mempengaruhi semua alat
Callback canUseTool - Penanganan izin runtime untuk kasus yang tidak tercakup oleh aturan lain
Hooks - Kontrol terperinci atas setiap eksekusi alat dengan logika kustom
Aturan izin (settings.json) - Aturan allow/deny deklaratif dengan parsing perintah bash terintegrasi

Kasus penggunaan untuk setiap pendekatan:

Mode izin - Tetapkan perilaku izin keseluruhan (perencanaan, auto-accepting edits, bypassing checks)
canUseTool - Persetujuan dinamis untuk kasus yang tidak tercakup, meminta izin pengguna
Hooks - Kontrol programatik atas semua eksekusi alat
Aturan izin - Kebijakan statis dengan parsing perintah bash yang cerdas

Diagram Alur Izin

Urutan Pemrosesan: PreToolUse Hook → Deny Rules → Allow Rules → Ask Rules → Permission Mode Check → canUseTool Callback → PostToolUse Hook

Mode Izin

Mode izin memberikan kontrol global atas bagaimana Claude menggunakan alat. Anda dapat mengatur mode izin saat memanggil query() atau mengubahnya secara dinamis selama sesi streaming.

Mode yang Tersedia

SDK mendukung empat mode izin, masing-masing dengan perilaku yang berbeda:

Mode	Deskripsi	Perilaku Alat
`default`	Perilaku izin standar	Pemeriksaan izin normal berlaku
`plan`	Mode perencanaan - tidak ada eksekusi	Claude hanya dapat menggunakan alat read-only; menyajikan rencana sebelum eksekusi (Saat ini tidak didukung dalam SDK)
`acceptEdits`	Auto-accept file edits	Edit file dan operasi filesystem secara otomatis disetujui
`bypassPermissions`	Bypass semua pemeriksaan izin	Semua alat berjalan tanpa prompt izin (gunakan dengan hati-hati)

Mengatur Mode Izin

Anda dapat mengatur mode izin dengan dua cara:

1. Konfigurasi Awal

Atur mode saat membuat query:

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

const result = await query({
  prompt: "Help me refactor this code",
  options: {
    permissionMode: 'default'  // Standard permission mode
  }
});

2. Perubahan Mode Dinamis (Hanya Streaming)

Ubah mode selama sesi streaming:

Perilaku Spesifik Mode

Mode Accept Edits (`acceptEdits`)

Dalam mode accept edits:

Semua edit file secara otomatis disetujui
Operasi filesystem (mkdir, touch, rm, dll.) auto-approved
Alat lain masih memerlukan izin normal
Mempercepat pengembangan ketika Anda mempercayai edit Claude
Berguna untuk prototyping cepat dan iterasi

Operasi yang auto-approved:

Edit file (Edit, Write tools)
Perintah filesystem Bash (mkdir, touch, rm, mv, cp)
Pembuatan dan penghapusan file

Mode Bypass Permissions (`bypassPermissions`)

Dalam mode bypass permissions:

SEMUA penggunaan alat secara otomatis disetujui
Tidak ada prompt izin yang muncul
Hooks masih dieksekusi (masih dapat memblokir operasi)
Gunakan dengan sangat hati-hati - Claude memiliki akses sistem penuh
Direkomendasikan hanya untuk lingkungan terkontrol

Prioritas Mode dalam Alur Izin

Mode izin dievaluasi pada titik tertentu dalam alur izin:

Hooks dieksekusi terlebih dahulu - Dapat allow, deny, ask, atau continue
Aturan Deny diperiksa - Blokir alat terlepas dari mode
Aturan Allow diperiksa - Izinkan alat jika cocok
Aturan Ask diperiksa - Minta izin jika cocok
Mode izin dievaluasi:
- Mode bypassPermissions - Jika aktif, izinkan semua alat yang tersisa
- Mode lain - Tunda ke callback canUseTool
Callback canUseTool - Menangani kasus yang tersisa

Ini berarti:

Hooks dapat selalu mengontrol penggunaan alat, bahkan dalam mode bypassPermissions
Aturan deny eksplisit menggantikan semua mode izin
Aturan ask dievaluasi sebelum mode izin
Mode bypassPermissions menggantikan callback canUseTool untuk alat yang tidak cocok

Praktik Terbaik

Gunakan mode default untuk eksekusi terkontrol dengan pemeriksaan izin normal
Gunakan mode acceptEdits saat bekerja pada file atau direktori terisolasi
Hindari bypassPermissions dalam produksi atau pada sistem dengan data sensitif
Gabungkan mode dengan hooks untuk kontrol terperinci
Ubah mode secara dinamis berdasarkan kemajuan tugas dan kepercayaan diri

Contoh perkembangan mode:

// Start in default mode for controlled execution
permissionMode: 'default'

// Switch to acceptEdits for rapid iteration
await q.setPermissionMode('acceptEdits')

canUseTool

Callback canUseTool dilewatkan sebagai opsi saat memanggil fungsi query. Ini menerima nama alat dan parameter input, dan harus mengembalikan keputusan - allow atau deny.

canUseTool fires kapan pun Claude Code akan menampilkan prompt izin kepada pengguna, misalnya hooks dan aturan izin tidak mencakupnya dan tidak dalam mode acceptEdits.

Berikut adalah contoh lengkap yang menunjukkan cara mengimplementasikan persetujuan alat interaktif:

Menangani Alat AskUserQuestion

Alat AskUserQuestion memungkinkan Claude untuk mengajukan pertanyaan klarifikasi kepada pengguna selama percakapan. Ketika alat ini dipanggil, callback canUseTool Anda menerima pertanyaan dan harus mengembalikan jawaban pengguna.

Struktur Input

Ketika canUseTool dipanggil dengan toolName: "AskUserQuestion", input berisi:

{
  questions: [
    {
      question: "Which database should we use?",
      header: "Database",
      options: [
        { label: "PostgreSQL", description: "Relational, ACID compliant" },
        { label: "MongoDB", description: "Document-based, flexible schema" }
      ],
      multiSelect: false
    },
    {
      question: "Which features should we enable?",
      header: "Features",
      options: [
        { label: "Authentication", description: "User login and sessions" },
        { label: "Logging", description: "Request and error logging" },
        { label: "Caching", description: "Redis-based response caching" }
      ],
      multiSelect: true
    }
  ]
}

Mengembalikan Jawaban

Kembalikan jawaban dalam updatedInput.answers sebagai record yang memetakan teks pertanyaan ke label opsi yang dipilih:

return {
  behavior: "allow",
  updatedInput: {
    questions: input.questions,  // Pass through original questions
    answers: {
      "Which database should we use?": "PostgreSQL",
      "Which features should we enable?": "Authentication, Caching"
    }
  }
}

Jawaban multi-select adalah string yang dipisahkan koma (misalnya, "Authentication, Caching").

Sumber Daya Terkait

Panduan Hooks - Pelajari cara mengimplementasikan hooks untuk kontrol terperinci atas eksekusi alat
Pengaturan: Aturan Izin - Konfigurasi aturan allow/deny deklaratif dengan parsing perintah bash

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

// Create an async generator for streaming input
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Let's start with default permissions" 
    }
  };
  
  // Later in the conversation...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Now let's speed up development"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Start in default mode
  }
});

// Change mode dynamically
await q.setPermissionMode('acceptEdits');

// Process messages
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🔧 Tool Request:");
  console.log(`   Tool: ${toolName}`);
  
  // Display tool parameters
  if (input && Object.keys(input).length > 0) {
    console.log("   Parameters:");
    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}`);
    }
  }
  
  // Get user approval (replace with your UI logic)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Approved\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Denied\n");
    return {
      behavior: "deny",
      message: "User denied permission for this tool"
    };
  }
}

// Use the permission callback
const result = await query({
  prompt: "Help me analyze this codebase",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Menangani Izin

Menangani Izin

Izin SDK

Ikhtisar

Diagram Alur Izin

Mode Izin

Mode yang Tersedia

Mengatur Mode Izin

1. Konfigurasi Awal

2. Perubahan Mode Dinamis (Hanya Streaming)

Perilaku Spesifik Mode

Mode Accept Edits (`acceptEdits`)

Mode Bypass Permissions (`bypassPermissions`)

Prioritas Mode dalam Alur Izin

Praktik Terbaik

canUseTool

Menangani Alat AskUserQuestion

Struktur Input

Mengembalikan Jawaban

Sumber Daya Terkait

Izin SDK

Ikhtisar

Diagram Alur Izin

Mode Izin

Mode yang Tersedia

Mengatur Mode Izin

1. Konfigurasi Awal

2. Perubahan Mode Dinamis (Hanya Streaming)

Perilaku Spesifik Mode

Mode Accept Edits (acceptEdits)

Mode Bypass Permissions (bypassPermissions)

Prioritas Mode dalam Alur Izin

Praktik Terbaik

canUseTool

Menangani Alat AskUserQuestion

Struktur Input

Mengembalikan Jawaban

Sumber Daya Terkait

Mode Accept Edits (`acceptEdits`)

Mode Bypass Permissions (`bypassPermissions`)