Skip to main content
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:
1

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. Hook PreToolUse allow juga tidak dapat menyetujui penghapusan rm atau rmdir yang menargetkan jalur kritis.
2

Deny rules

Periksa aturan deny (dari disallowed_tools dan settings.json). Jika aturan deny cocok, alat diblokir, bahkan dalam mode bypassPermissions. Aturan deny dengan nama bare seperti Bash menghapus alat dari konteks Claude sebelum evaluasi ini dimulai, jadi hanya aturan yang dibatasi seperti Bash(rm *) yang diperiksa pada langkah ini.
3

Ask rules

Periksa aturan ask dari settings.json. Jika aturan ask cocok, panggilan jatuh melalui callback canUseTool Anda untuk konfirmasi, bahkan dalam mode bypassPermissions.Alat yang memerlukan interaksi pengguna berperilaku dengan cara yang sama: AskUserQuestion dan alat MCP yang servernya menetapkan _meta["anthropic/requiresUserInteraction"] selalu jatuh melalui callback, bahkan ketika aturan allow cocok. Dalam mode dontAsk kedua kasus ditolak sebagai gantinya, karena mode itu tidak pernah meminta. Anotasi MCP memerlukan Claude Code v2.1.199 atau lebih baru.Alat konektor claude.ai yang organisasi Anda atur ke ask juga meninggalkan alur pada langkah ini. Setiap panggilan jatuh melalui callback, bahkan dalam mode bypassPermissions dan bahkan ketika aturan allow cocok. Callback menerima alasan Your organization requires approval for this tool. Dalam mode dontAsk panggilan ditolak sebagai gantinya, karena mode itu tidak pernah meminta.
4

Permission mode

Terapkan mode izin yang aktif:
  • Dalam mode bypassPermissions, Claude Code menyetujui semua yang mencapai langkah ini kecuali penghapusan rm dan rmdir yang menargetkan jalur kritis, yang jatuh melalui sebagai gantinya.
  • Dalam mode acceptEdits, Claude Code menyetujui operasi file yang tercantum di bawah Accept edits mode.
  • Dalam mode plan, Claude Code mengirim alat file-edit dan shell-write ke callback canUseTool Anda terlepas dari aturan allow, sehingga operasi write tidak dapat disetujui secara otomatis saat merencanakan.
  • Dalam mode lain, permintaan jatuh melalui.
5

Allow rules

Periksa aturan allow (dari allowed_tools dan settings.json). Jika aturan cocok, alat disetujui. Panggilan yang alat setujui sendiri juga diselesaikan pada langkah ini, tanpa aturan yang diperlukan: misalnya pembacaan file di dalam direktori kerja Anda atau perintah Bash read-only. Penghapusan rm dan rmdir yang menargetkan jalur kritis tidak pernah disetujui oleh aturan allow: mereka mencapai callback Anda dalam mode yang meminta, pergi ke classifier dalam mode auto pada Claude Code v2.1.218 atau lebih baru, dan ditolak dalam mode dontAsk.
6

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.Dalam SDK TypeScript, jika Anda menetapkan permissionPrompts: 'none', callback Anda tidak dipanggil pada langkah ini. Hook PermissionRequest masih mendapat kesempatan untuk memutuskan, dan jika tidak, Claude Code menolak panggilan. Opsi memerlukan Claude Code v2.1.259 atau lebih baru.
Diagram dari alur evaluasi izin enam langkah yang cocok dengan langkah-langkah di atas: permintaan alat melewati hooks, deny rules, ask rules, permission mode, allow rules, dan canUseTool. Hooks, deny rules, dan canUseTool dapat merutekan ke Blocked; permission mode bypass, allow rules, dan canUseTool dapat merutekan ke Execute; ask rules merutekan ke canUseTool. Diagram dari alur evaluasi izin enam langkah yang cocok dengan langkah-langkah di atas: permintaan alat melewati hooks, deny rules, ask rules, permission mode, allow rules, dan canUseTool. Hooks, deny rules, dan canUseTool dapat merutekan ke Blocked; permission mode bypass, allow rules, dan canUseTool dapat merutekan ke Execute; ask rules merutekan ke canUseTool. Jika Anda meneruskan callback canUseTool dalam konfigurasi di mana SDK TypeScript mengharapkan urutan evaluasi untuk menyetujui panggilan secara otomatis sebelum callback dikonsultasikan, SDK memancarkan peringatan proses Node.js sekali ketika kueri dibangun. Kode peringatan adalah CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Dua konfigurasi memicunya: Entri dengan spesifier seperti Bash(ls *) dan mode acceptEdits tidak memicunya, dan aturan allow yang berasal dari file pengaturan tidak terlihat oleh pemeriksaan. Dengarkan dengan process.on('warning', ...) dan cocokkan kode untuk mencatat atau menekannya. Untuk membatasi setiap panggilan alat terlepas dari mode dan aturan, gunakan hook PreToolUse sebagai gantinya. Halaman ini berfokus pada aturan allow dan deny serta mode izin. Untuk langkah-langkah lainnya:
  • Hooks: jalankan kode khusus untuk mengizinkan, menolak, atau memodifikasi permintaan alat. Lihat Control execution with hooks.
  • canUseTool callback: minta persetujuan pengguna saat runtime, ketika tidak ada langkah sebelumnya yang menyelesaikan panggilan. Lihat Handle approvals and user input.

Aturan izin dan penolakan

allowed_tools dan disallowed_tools (TypeScript: allowedTools / disallowedTools) menambahkan entri ke daftar aturan izin dan penolakan dalam alur evaluasi di atas. Jika Anda menyebutkan salah satu dari alat pelacakan tugas dalam allowed_tools, Claude Code juga memilih sesi masuk. Alat lain apa pun yang tidak tercantum dalam allowed_tools masih tersedia untuk Claude, dan panggilan ke alat tersebut yang memerlukan persetujuan jatuh melalui mode izin. Aturan penolakan berperilaku berbeda tergantung pada apakah mereka menyebutkan alat atau membatasi pola dalam satu. Aturan izin menerima glob nama alat hanya setelah awalan mcp__<server>__ literal. Segmen server harus bebas glob sehingga aturan menyebutkan 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. Aturan berskop untuk Read dan Edit mengambil pola jalur. Aturan Edit(path) mengatur semua alat bawaan yang menulis file, termasuk Write dan NotebookEdit; aturan Write(path) tidak pernah cocok dengan pemeriksaan izin file. Gunakan //path untuk jalur sistem file absolut: aturan penolakan Edit(//secrets/**) memblokir penulisan di mana pun di bawah /secrets di disk. Dengan garis miring tunggal di depan, Edit(/secrets/**) berlabuh di sumber aturan sebagai gantinya. Untuk aturan yang dilewatkan melalui allowed_tools atau disallowed_tools, itu berarti direktori kerja sesi, sehingga aturan tidak memblokir /secrets di disk. Lihat Aturan Read dan Edit untuk empat bentuk jangkar dan bagaimana aturan dari file pengaturan diselesaikan.
Alat yang disetujui secara otomatis tidak pernah mencapai canUseTool. Panggilan alat yang disetujui pada langkah sebelumnya apa pun, oleh acceptEdits atau bypassPermissions, atau oleh aturan izin, melewati callback canUseTool Anda, sehingga pemeriksaan izin yang Anda letakkan di sana diam-diam dilewati untuk alat tersebut. AskUserQuestion, alat MCP yang ditandai _meta["anthropic/requiresUserInteraction"], alat konektor organisasi Anda atur ke ask, dan penghapusan rm dan rmdir yang menargetkan jalur kritis masih mencapai callback, bahkan ketika aturan izin cocok. Dalam mode auto, penghapusan jalur kritis pergi ke pengklasifikasi alih-alih callback, sementara panggilan lain yang tercantum di sini masih mencapainya; perutean pengklasifikasi memerlukan Claude Code v2.1.218 atau lebih baru. Dalam mode dontAsk panggilan ini ditolak sebagai gantinya, tanpa memanggil callback.Cakupan tergantung pada bentuk entri: nama telanjang seperti Read atau mcp__github__get_issue menyetujui setiap panggilan ke alat tersebut terlepas dari pengecualian di atas, sementara aturan berskop seperti Bash(npm test *) hanya menyetujui panggilan yang cocok, dan panggilan Bash lainnya yang memerlukan persetujuan masih jatuh melalui callback. Untuk pemeriksaan yang harus berjalan pada setiap panggilan alat, gunakan hook PreToolUse: hook berjalan sebelum setiap langkah lainnya, dan penolakan hook bahkan berlaku dalam mode bypassPermissions.
Untuk agen yang terkunci, pasangkan allowedTools dengan permissionMode: "dontAsk":
Alat yang tercantum disetujui, terlepas dari tindakan yang tidak ada mode auto-approve, dan setiap panggilan lain yang akan meminta ditolak sebagai gantinya. Panggilan yang tidak memerlukan persetujuan dalam mode default berjalan apakah atau tidak Anda mencantumnya, seperti perintah Bash hanya-baca, alat seperti Agent yang tidak bertanya sebelum menjalankan, dan pembacaan file di dalam direktori kerja Anda. Untuk menempatkan alat di luar jangkauan Claude sepenuhnya, tambahkan nama telanjangnya ke disallowedTools.
allowed_tools tidak membatasi bypassPermissions. allowed_tools pra-menyetujui alat yang Anda cantumkan. Alat unlisted lainnya tidak cocok dengan aturan izin apa pun dan jatuh melalui mode izin, di mana bypassPermissions menyetujuinya. Mengatur allowed_tools=["Read"] bersama dengan permission_mode="bypassPermissions" masih menyetujui setiap alat, termasuk Bash, Write, dan Edit. Jika Anda memerlukan bypassPermissions tetapi menginginkan alat spesifik diblokir, gunakan disallowed_tools.
Anda juga dapat mengonfigurasi aturan izin, penolakan, dan tanya secara deklaratif dalam .claude/settings.json. Aturan ini dibaca ketika sumber pengaturan project diaktifkan, yang mana untuk opsi query() default. Jika Anda mengatur 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 cara Claude menggunakan tools. Anda dapat mengatur mode izin saat memanggil query() atau mengubahnya secara dinamis selama sesi streaming.

Mode yang tersedia

SDK mendukung mode izin berikut:
Pewarisan subagent: Subagent berjalan dalam mode izin sesi induk kecuali Anda mengatur permissionMode pada AgentDefinition dan sesi induk berada dalam mode default, dontAsk, atau plan. Bahkan kemudian, Claude Code tidak pernah menerapkan nilai "bypassPermissions". Subagent berjalan dalam mode bypassPermissions hanya ketika sesi induk itu sendiri melakukannya. Pengecualian bypassPermissions memerlukan Claude Code v2.1.267 atau lebih baru.Subagent mungkin memiliki prompt sistem yang berbeda dan perilaku yang kurang terbatas daripada agen utama Anda, jadi mewarisi bypassPermissions memberi mereka akses sistem penuh dan otonom. Tindakan yang tidak ada mode auto-approve masih berlaku.

Atur mode izin

Anda dapat mengatur mode izin sekali saat memulai query, atau mengubahnya secara dinamis saat sesi aktif.
Lewatkan permission_mode (Python) atau permissionMode (TypeScript) saat membuat query. Mode ini berlaku untuk seluruh sesi kecuali diubah secara dinamis.

Detail mode

Mode terima pengeditan (acceptEdits)

Auto-approve operasi file sehingga Claude dapat mengedit kode tanpa meminta. Tools lain (seperti perintah Bash yang bukan operasi sistem file) masih memerlukan izin normal. Operasi yang auto-approved:
  • Pengeditan file (tools Edit, Write)
  • Perintah sistem file: mkdir, touch, rm, rmdir, mv, cp, sed
Keduanya hanya berlaku untuk jalur di dalam direktori kerja atau additionalDirectories. Dalam mode acceptEdits, Claude Code tidak auto-approve permintaan ketika Claude:
  • Bekerja pada jalur di luar cakupan itu
  • Menulis ke jalur yang dilindungi
  • Menghapus jalur kritis dengan rm atau rmdir
Gunakan ketika: Anda mempercayai pengeditan 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, tanpa memanggil canUseTool. Tools yang disetujui sebelumnya oleh allowed_tools, aturan izin settings.json, atau hook berjalan seperti biasa, begitu juga panggilan yang tidak memerlukan persetujuan dalam mode default, seperti pembacaan file di dalam direktori kerja Anda dan panggilan ke Agent. Connector tools organisasi Anda atur ke ask, tools yang memerlukan interaksi pengguna, dan penghapusan rm dan rmdir yang menargetkan jalur kritis ditolak bahkan ketika aturan izin cocok. Hook allow PreToolUse juga tidak menghapus penghapusan jalur kritis. Gunakan ketika: Anda menginginkan permukaan tool yang tetap dan eksplisit untuk agen headless dan lebih suka penolakan keras daripada ketergantungan diam pada canUseTool yang tidak ada.

Mode lewati izin (bypassPermissions)

Auto-approve penggunaan tool tanpa meminta, kecuali kasus yang tercantum dalam peringatan di bawah. Hook masih dijalankan dan dapat memblokir operasi jika diperlukan.
Gunakan dengan sangat hati-hati. Claude memiliki akses sistem penuh dalam mode ini. Hanya gunakan di lingkungan terkontrol di mana Anda mempercayai semua operasi yang mungkin.allowed_tools tidak membatasi mode ini. Setiap tool disetujui, bukan hanya yang Anda daftarkan. Kontrol ini masih berlaku:
  • Aturan penolakan, aturan ask eksplisit, dan hook dievaluasi sebelum pemeriksaan mode dan masih dapat memblokir tool.
  • Connector tools organisasi Anda atur ke ask, tools yang memerlukan interaksi pengguna, dan penghapusan rm dan rmdir yang menargetkan jalur kritis masih jatuh ke callback canUseTool Anda.
  • Perlindungan pesan lintas sesi masih berlaku.

Mode rencana (plan)

Claude menjelajahi basis kode dan menghasilkan rencana tanpa mengedit file sumber Anda. Tools read-only berjalan seperti dalam mode izin default. Pengeditan file tidak pernah auto-approved dalam mode rencana, bahkan ketika aturan izin cocok. Mereka meminta melalui callback canUseTool Anda sebagai gantinya. Pada Claude Code v2.1.212 atau lebih baru, perintah shell yang memodifikasi file, seperti touch dan rm, mencapai callback canUseTool Anda dengan cara yang sama. 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. Untuk langkah-langkah lain dalam alur evaluasi izin: