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:
Hooks
Jalankan hooks terlebih dahulu. Hook dapat menolak panggilan sepenuhnya atau meneruskannya. Hook yang mengembalikan allow tidak melewati aturan deny dan ask di bawah; aturan tersebut dievaluasi terlepas dari hasil hook.
Deny rules
Periksa aturan deny (dari disallowed_tools dan settings.json). Jika aturan deny cocok, alat diblokir, bahkan dalam mode bypassPermissions.
Permission mode
Terapkan mode izin yang aktif. bypassPermissions menyetujui semua yang mencapai langkah ini. acceptEdits menyetujui operasi file. Mode lain jatuh melalui.
Allow rules
Periksa aturan allow (dari allowed_tools dan settings.json). Jika aturan cocok, alat disetujui.
canUseTool callback
Jika tidak diselesaikan oleh salah satu di atas, panggil callback canUseTool Anda untuk keputusan. Dalam mode dontAsk, langkah ini dilewati dan alat ditolak.
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. 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. Mereka mengontrol apakah panggilan alat disetujui, bukan apakah alat tersedia untuk Claude.
| Opsi | Efek |
|---|---|
allowed_tools=["Read", "Grep"] |
Read dan Grep disetujui secara otomatis. Alat yang tidak tercantum di sini masih ada dan jatuh melalui mode izin dan canUseTool. |
disallowed_tools=["Bash"] |
Bash selalu ditolak. Aturan deny diperiksa terlebih dahulu dan berlaku di setiap mode izin, termasuk bypassPermissions. |
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:
| Mode | Deskripsi | Perilaku alat |
|---|---|---|
default |
Perilaku izin standar | Tidak ada persetujuan otomatis; alat yang tidak cocok memicu callback canUseTool Anda |
dontAsk |
Tolak daripada meminta | Apa pun yang tidak pra-disetujui oleh allowed_tools atau aturan ditolak; canUseTool tidak pernah dipanggil |
acceptEdits |
Terima otomatis edit file | Edit file dan operasi sistem file (mkdir, rm, mv, dll.) disetujui secara otomatis |
bypassPermissions |
Lewati semua pemeriksaan izin | Semua alat berjalan tanpa prompt izin (gunakan dengan hati-hati) |
plan |
Mode perencanaan | Alat baca saja berjalan; Claude menganalisis dan merencanakan tanpa mengedit file sumber Anda |
auto (TypeScript saja) |
Persetujuan yang diklasifikasikan model | Pengklasifikasi model menyetujui atau menolak setiap panggilan alat. Lihat Mode Auto untuk ketersediaan |
Tetapkan mode izin
Anda dapat menetapkan mode izin sekali saat memulai kueri, atau mengubahnya secara dinamis saat sesi aktif.
Teruskan permission_mode (Python) atau permissionMode (TypeScript) saat membuat kueri. Mode ini berlaku untuk seluruh sesi kecuali diubah secara dinamis.
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();
Panggil set_permission_mode() (Python) atau setPermissionMode() (TypeScript) untuk mengubah mode di tengah sesi. Mode baru berlaku segera untuk semua permintaan alat berikutnya. Ini memungkinkan Anda memulai dengan pembatasan dan melonggarkan izin seiring kepercayaan berkembang, misalnya beralih ke acceptEdits setelah meninjau pendekatan awal Claude.
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)
Membatasi Claude ke alat baca saja. Claude dapat membaca file dan menjalankan perintah shell baca saja untuk menjelajahi basis kode tetapi tidak mengedit file sumber Anda. 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