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 TypeScript SDK.

Gambaran Umum

Claude Agent SDK menyediakan empat cara komplementer untuk mengontrol penggunaan alat:

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

Kasus penggunaan untuk setiap pendekatan:

• Mode izin - Mengatur perilaku izin keseluruhan (perencanaan, otomatis menerima edit, melewati pemeriksaan)
• canUseTool - Persetujuan dinamis untuk kasus yang tidak tercakup, meminta izin pengguna
• Hooks - Kontrol programatis atas semua eksekusi alat
• Aturan izin - Kebijakan statis dengan parsing perintah bash yang cerdas

Diagram Alur Izin

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([Permintaan alat]) --> PreHook(PreToolUse Hook)

    PreHook -->|  Izinkan  | Execute(Eksekusi Alat)
    PreHook -->|  Tolak  | Denied(Ditolak)
    PreHook -->|  Tanya  | Callback(canUseTool Callback)
    PreHook -->|  Lanjutkan  | Deny(Periksa Aturan Tolak)

    Deny -->|  Cocok  | Denied
    Deny -->|  Tidak Cocok  | Allow(Periksa Aturan Izinkan)

    Allow -->|  Cocok  | Execute
    Allow -->|  Tidak Cocok  | Ask(Periksa Aturan Tanya)

    Ask -->|  Cocok  | Callback
    Ask -->|  Tidak Cocok  | Mode{Mode Izin?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  Mode lain  | Callback

    Callback -->|  Izinkan  | Execute
    Callback -->|  Tolak  | Denied

    Denied --> DeniedResponse([Umpan balik ke agen])

    Execute --> PostHook(PostToolUse Hook)
    PostHook --> Done([Respons Alat])

    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

Urutan Pemrosesan: PreToolUse Hook → Aturan Tolak → Aturan Izinkan → Aturan Tanya → Pemeriksaan Mode Izin → canUseTool Callback → PostToolUse Hook

Mode Izin

Mode izin menyediakan 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:

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: "Bantu saya refactor kode ini",
  options: {
    permissionMode: 'default'  // Mode izin standar
  }
});

2. Perubahan Mode Dinamis (Hanya Streaming)

Ubah mode selama sesi streaming:

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

// Buat async generator untuk input streaming
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Mari mulai dengan izin default" 
    }
  };
  
  // Nanti dalam percakapan...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Sekarang mari percepat pengembangan"
    }
  };
}

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

// Ubah mode secara dinamis
await q.setPermissionMode('acceptEdits');

// Proses pesan
for await (const message of q) {
  console.log(message);
}

Perilaku Spesifik Mode

Mode Accept Edits (acceptEdits)

Dalam mode accept edits:

• Semua edit file secara otomatis disetujui
• Operasi filesystem (mkdir, touch, rm, dll.) secara otomatis disetujui
• 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 (alat Edit, Write)
• 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:

1. Hooks dieksekusi terlebih dahulu - Dapat mengizinkan, menolak, bertanya, atau melanjutkan
2. Aturan tolak diperiksa - Memblokir alat terlepas dari mode
3. Aturan izinkan diperiksa - Mengizinkan alat jika cocok
4. Aturan tanya diperiksa - Meminta izin jika cocok
5. Mode izin dievaluasi:
   • Mode bypassPermissions - Jika aktif, mengizinkan semua alat yang tersisa
   • Mode lain - Menunda ke callback canUseTool
6. Callback canUseTool - Menangani kasus yang tersisa

Ini berarti:

• Hooks selalu dapat mengontrol penggunaan alat, bahkan dalam mode bypassPermissions
• Aturan tolak eksplisit menimpa semua mode izin
• Aturan tanya dievaluasi sebelum mode izin
• Mode bypassPermissions menimpa callback canUseTool untuk alat yang tidak cocok

Praktik Terbaik

1. Gunakan mode default untuk eksekusi terkontrol dengan pemeriksaan izin normal
2. Gunakan mode acceptEdits saat bekerja pada file atau direktori yang terisolasi
3. Hindari bypassPermissions dalam produksi atau pada sistem dengan data sensitif
4. Gabungkan mode dengan hooks untuk kontrol yang detail
5. Beralih mode secara dinamis berdasarkan kemajuan tugas dan kepercayaan

Contoh progres mode:

// Mulai dalam mode default untuk eksekusi terkontrol
permissionMode: 'default'

// Beralih ke acceptEdits untuk iterasi cepat
await q.setPermissionMode('acceptEdits')

canUseTool

Callback canUseTool diteruskan sebagai opsi saat memanggil fungsi query. Ini menerima nama alat dan parameter input, dan harus mengembalikan keputusan - baik izinkan atau tolak.

canUseTool dipicu setiap kali 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:

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

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Permintaan Alat:");
  console.log(`   Alat: ${toolName}`);
  
  // Tampilkan parameter alat
  if (input && Object.keys(input).length > 0) {
    console.log("   Parameter:");
    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}`);
    }
  }
  
  // Dapatkan persetujuan pengguna (ganti dengan logika UI Anda)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Disetujui\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Ditolak\n");
    return {
      behavior: "deny",
      message: "Pengguna menolak izin untuk alat ini"
    };
  }
}

// Gunakan callback izin
const result = await query({
  prompt: "Bantu saya analisis codebase ini",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Sumber Daya Terkait

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