Konfigurasi izin

Kontrol bagaimana agen Anda menggunakan alat dengan mode izin, hooks, dan aturan allow/deny deklaratif.

Claude Agent SDK menyediakan kontrol izin untuk mengelola bagaimana Claude menggunakan alat. Gunakan mode izin dan aturan untuk menentukan apa yang diizinkan secara otomatis, dan callback canUseTool untuk menangani segalanya di runtime.

Bagaimana izin dievaluasi

Ketika Claude meminta alat, SDK memeriksa izin dalam urutan ini:

Halaman ini berfokus pada aturan allow dan deny serta mode izin. Untuk langkah lainnya:

• Hooks: jalankan kode khusus untuk mengizinkan, menolak, atau memodifikasi permintaan alat. Lihat Kontrol eksekusi dengan hooks.
• canUseTool callback: minta persetujuan pengguna di runtime, ketika tidak ada langkah sebelumnya yang menyelesaikan panggilan. Lihat Tangani persetujuan dan input pengguna.

Aturan allow dan deny

allowed_tools dan disallowed_tools (TypeScript: allowedTools / disallowedTools) menambahkan entri ke daftar aturan allow dan deny dalam alur evaluasi di atas. Aturan allow hanya mempengaruhi persetujuan: alat yang tidak tercantum dalam allowed_tools masih tersedia untuk Claude dan jatuh melalui mode izin. Aturan deny berperilaku berbeda tergantung pada apakah mereka menamai alat atau membatasi pola dalam satu alat.

Aturan allow menerima glob nama-alat hanya setelah awalan literal mcp__<server>__. Segmen server harus bebas glob sehingga aturan menamai server spesifik yang Anda konfigurasi: mcp__puppeteer__* cocok dengan setiap alat dari server puppeteer, dan mcp__github__get_* cocok dengan alat get_ miliknya. Entri yang tidak berlabuh seperti allowed_tools=["*"] atau allowed_tools=["mcp__*"] diabaikan dengan peringatan startup dan tidak menyetujui apa pun secara otomatis.

Untuk agen yang terkunci, pasangkan allowedTools dengan permissionMode: "dontAsk". Alat yang tercantum disetujui; apa pun yang lain ditolak sepenuhnya daripada meminta:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

Anda juga dapat mengonfigurasi aturan allow, deny, dan ask secara deklaratif di .claude/settings.json. Aturan ini dibaca ketika sumber pengaturan project diaktifkan, yang merupakan default untuk opsi query(). Jika Anda menetapkan setting_sources (TypeScript: settingSources) secara eksplisit, sertakan "project" agar aturan diterapkan. Lihat Pengaturan izin untuk sintaks aturan.

Mode izin

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

Mode yang tersedia

SDK mendukung mode izin ini:

Tetapkan mode izin

Anda dapat menetapkan mode izin sekali saat memulai kueri, atau mengubahnya secara dinamis saat sesi aktif.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default",  # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

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

async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Set the mode here
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}

main();

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default",  # Start in default mode
)
) as client:
await client.query("Help me refactor this code")

# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")

# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

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

async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Start in default mode
}
});

// Change mode dynamically mid-session
await q.setPermissionMode("acceptEdits");

// Process messages with the new permission mode
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}

main();

Detail mode

Mode terima edit (`acceptEdits`)

Menyetujui operasi file secara otomatis sehingga Claude dapat mengedit kode tanpa meminta. Alat lain (seperti perintah Bash yang bukan operasi sistem file) masih memerlukan izin normal.

Operasi yang disetujui secara otomatis:

• Edit file (alat Edit, Write)
• Perintah sistem file: mkdir, touch, rm, rmdir, mv, cp, sed

Keduanya hanya berlaku untuk jalur di dalam direktori kerja atau additionalDirectories. Jalur di luar cakupan itu dan penulisan ke jalur yang dilindungi masih meminta.

Gunakan ketika: Anda mempercayai edit Claude dan menginginkan iterasi yang lebih cepat, seperti selama prototyping atau saat bekerja di direktori terisolasi.

Mode jangan tanya (`dontAsk`)

Mengonversi prompt izin apa pun menjadi penolakan. Alat yang pra-disetujui oleh allowed_tools, aturan allow settings.json, atau hook berjalan normal. Segalanya ditolak tanpa memanggil canUseTool.

Gunakan ketika: Anda menginginkan permukaan alat yang tetap dan eksplisit untuk agen headless dan lebih suka penolakan keras daripada ketergantungan diam pada canUseTool yang tidak ada.

Mode lewati izin (`bypassPermissions`)

Menyetujui semua penggunaan alat secara otomatis tanpa prompt. Hooks masih dijalankan dan dapat memblokir operasi jika diperlukan.

Mode rencana (`plan`)

Claude menjelajahi basis kode dan menghasilkan rencana tanpa mengedit file sumber Anda. Alat baca saja berjalan seperti dalam mode default. Edit file tidak pernah disetujui secara otomatis dalam mode rencana, bahkan ketika aturan allow cocok. Mereka diminta melalui callback canUseTool Anda sebagai gantinya. Claude dapat menggunakan AskUserQuestion untuk mengklarifikasi persyaratan sebelum menyelesaikan rencana. Lihat Tangani persetujuan dan input pengguna untuk menangani prompt ini.

Gunakan ketika: Anda ingin Claude mengusulkan perubahan tanpa menjalankannya, seperti selama tinjauan kode atau ketika Anda perlu menyetujui perubahan sebelum dibuat.

Sumber daya terkait

Untuk langkah lain dalam alur evaluasi izin:

• Tangani persetujuan dan input pengguna: prompt persetujuan interaktif dan pertanyaan klarifikasi
• Panduan hooks: jalankan kode khusus di titik kunci dalam siklus hidup agen
• Aturan izin: aturan allow/deny deklaratif di settings.json