​

Izin SDK

​

Gambaran Umum

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

• Mode izin - Mengatur perilaku izin keseluruhan (perencanaan, auto-accepting edits, melewati pemeriksaan)
• 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

​

Mode Izin

​

Mode yang Tersedia

​

Mengatur Mode Izin

​

1. Konfigurasi Awal

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)

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)

• 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

• Edit file (alat Edit, MultiEdit, Write)
• Perintah filesystem bash (mkdir, touch, rm, mv, cp)
• Pembuatan dan penghapusan file

​

Mode Bypass Permissions (bypassPermissions)

• 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

1. Hooks dieksekusi terlebih dahulu - Dapat menimpa mode apa pun
2. Aturan deny diperiksa - Blokir alat terlepas dari mode
3. Mode bypassPermissions - Jika aktif, mengizinkan semua alat yang tersisa
4. Aturan allow diperiksa
5. Mode lain mempengaruhi perilaku alat tertentu
6. Callback canUseTool - Menangani kasus yang tersisa

• Hooks selalu dapat memblokir penggunaan alat, bahkan dalam mode bypassPermissions
• Aturan deny eksplisit menimpa semua mode izin
• Mode bypassPermissions menimpa aturan allow dan canUseTool

​

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. Kombinasikan mode dengan hooks untuk kontrol yang detail
5. Beralih mode secara dinamis berdasarkan kemajuan tugas dan kepercayaan

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

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

​

canUseTool

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

​

Menggunakan Hooks untuk Kontrol Alat

​

Implementasi Hook

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

const result = await query({
  prompt: "Bantu saya refactor kode ini",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Permintaan alat: ${input.tool_name}`);
          
          // Parse dan validasi input alat sendiri
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Perintah berbahaya diblokir"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Alat selesai: ${input.tool_name}`);
          // Log atau audit hasil alat
          return { continue: true };
        }]
      }]
    }
  }
});

​

Perbedaan Utama dari canUseTool

• Cakupan: Hooks dipanggil untuk semua penggunaan alat; canUseTool menangani kasus yang tidak dicakup oleh aturan izin
• Kontrol: Hooks memerlukan parsing dan validasi input sendiri
• Events: Hooks mendukung beberapa event (PreToolUse, PostToolUse, dll.) untuk tahap yang berbeda

​

Menggunakan Aturan Izin (settings.json)

​

Struktur Konfigurasi

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​

Sintaks Aturan

• Aturan bash: Menggunakan pencocokan prefix (bukan regex). Contoh: Bash(npm:*) cocok dengan perintah apa pun yang dimulai dengan “npm”
• Aturan file: Mendukung pola glob. Contoh: Read(./src/**/*.ts) cocok dengan file TypeScript di src
• Aturan tool-only: Hilangkan tanda kurung untuk mengontrol seluruh alat. Contoh: WebFetch memblokir semua web fetch

​

Menggunakan dengan SDK

​

Urutan Evaluasi Izin

1. Aturan deny diperiksa terlebih dahulu - jika cocok, penggunaan alat diblokir
2. Aturan allow diperiksa selanjutnya - jika cocok, penggunaan alat diizinkan
3. Aturan ask diperiksa - jika cocok, pengguna diminta
4. Callback canUseTool dipanggil untuk kasus yang tersisa

​

Parsing Perintah Bash

• Menangani pipes, redirects, dan substitusi perintah
• Mengenali pola berbahaya seperti rm -rf atau curl | sh
• Mendukung wildcard dan pencocokan prefix

• Bash(git:*) - Cocok dengan perintah git apa pun
• Bash(npm run test) - Cocok dengan perintah yang tepat
• Bash(npm run test:*) - Cocok dengan perintah Bash yang dimulai dengan npm run test seperti npm run test anyFile.test.ts

​

Praktik Terbaik

1. Mulai dengan mode default untuk pemeriksaan izin standar
2. Gunakan aturan izin untuk kebijakan statis, terutama perintah bash (lihat pengaturan izin)
3. Gunakan hooks untuk log, audit, atau transformasi semua penggunaan alat (lihat tipe hook)
4. Gunakan canUseTool untuk keputusan dinamis pada kasus yang tidak tercakup (lihat tipe CanUseTool)
5. Lapisan pertahanan dengan menggabungkan mode, aturan, hooks, dan callback untuk aplikasi kritis