​

Izin SDK

​

Gambaran Umum

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

• Mode izin - Mengatur perilaku izin secara keseluruhan (perencanaan, menerima edit otomatis, 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-code";

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-code";

// 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 disetujui secara otomatis
• Operasi filesystem (mkdir, touch, rm, dll.) disetujui otomatis
• 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 disetujui secara otomatis
• Tidak ada prompt izin yang muncul
• Hooks masih dieksekusi (masih bisa 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 pertama - Dapat menimpa mode apa pun
2. Aturan deny diperiksa - Memblokir 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. Gabungkan 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-code";

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-code";

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 khusus alat: Hilangkan tanda kurung untuk mengontrol seluruh alat. Contoh: WebFetch memblokir semua web fetch

​

Menggunakan dengan SDK

​

Urutan Evaluasi Izin

1. Aturan deny diperiksa pertama - 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 pipe, redirect, 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 npm run test:unit, test:integration, dll.

​

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