Konfigurasi izin - Claude Code Docs

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.

Halaman ini mencakup mode izin dan aturan. Untuk membangun alur persetujuan interaktif di mana pengguna menyetujui atau menolak permintaan alat di runtime, lihat Tangani persetujuan dan input pengguna.

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. Aturan deny dengan nama bare seperti Bash menghapus alat dari konteks Claude sebelum evaluasi ini dimulai, jadi hanya aturan berscopе seperti Bash(rm *) yang diperiksa pada langkah ini.

Ask rules

Periksa aturan ask dari settings.json. Jika aturan ask cocok, panggilan jatuh melalui callback canUseTool Anda untuk konfirmasi, bahkan dalam mode bypassPermissions. Dalam mode dontAsk aturan ask yang cocok ditolak sebagai gantinya, karena mode itu tidak pernah meminta.

Permission mode

Terapkan mode izin yang aktif. bypassPermissions menyetujui semua yang mencapai langkah ini. acceptEdits menyetujui operasi file. plan merutekan alat file-edit dan shell-write ke callback canUseTool Anda terlepas dari aturan allow, jadi operasi write tidak dapat disetujui secara otomatis saat merencanakan. 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.

Diagram alur evaluasi izin lima langkah yang sesuai dengan langkah-langkah di atas: permintaan alat melewati hooks, aturan deny, mode izin, aturan allow, dan canUseTool. Hooks, aturan deny, dan canUseTool dapat merutekan ke Blocked; bypass mode izin, aturan allow, dan canUseTool dapat merutekan ke Execute.

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. 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.

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"]`	Definisi alat `Bash` dihapus dari permintaan. Claude tidak melihat alat dan tidak dapat mencobanya.
`disallowed_tools=["Bash(rm *)"]`	`Bash` tetap tersedia. Panggilan yang cocok dengan `rm *` ditolak di setiap mode izin, termasuk `bypassPermissions`. Panggilan `Bash` lainnya jatuh melalui mode izin.
`disallowed_tools=["*"]`	Setiap definisi alat dihapus dari permintaan. Glob nama-alat didukung dalam aturan deny: `""` cocok dengan setiap alat dan `"mcp__"` cocok dengan setiap alat MCP di semua server.

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

allowed_tools tidak membatasi bypassPermissions. allowed_tools hanya pra-menyetujui alat yang Anda cantumkan. Alat yang tidak tercantum tidak cocok dengan aturan allow apa pun dan jatuh melalui mode izin, di mana bypassPermissions menyetujuinya. Menetapkan allowed_tools=["Read"] bersama dengan permission_mode="bypassPermissions" masih menyetujui setiap alat, termasuk Bash, Write, dan Edit. Jika Anda memerlukan bypassPermissions tetapi ingin alat tertentu diblokir, gunakan disallowed_tools.

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 pemeriksaan izin	Alat berjalan tanpa prompt izin, kecuali aturan `ask` eksplisit cocok (gunakan dengan hati-hati)
`plan`	Mode perencanaan	Claude menjelajahi dan merencanakan tanpa mengedit file sumber Anda; edit file tidak pernah disetujui secara otomatis dan diminta melalui callback `canUseTool` Anda
`auto` (TypeScript saja)	Persetujuan yang diklasifikasikan model	Pengklasifikasi model menyetujui atau menolak setiap panggilan alat. Lihat Mode Auto untuk ketersediaan

Warisan subagen: Ketika induk menggunakan bypassPermissions, acceptEdits, atau auto, semua subagen mewarisi mode tersebut dan tidak dapat ditimpa per subagen. Subagen mungkin memiliki prompt sistem yang berbeda dan perilaku yang kurang terbatas daripada agen utama Anda, jadi mewarisi bypassPermissions memberikan mereka akses sistem penuh dan otonom. Aturan ask eksplisit masih memaksa prompt.

Tetapkan mode izin

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

Pada waktu kueri
Selama streaming

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())

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())

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.

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 alat disetujui, bukan hanya yang Anda cantumkan. Aturan deny (disallowed_tools), aturan ask eksplisit, dan hooks dievaluasi sebelum pemeriksaan mode dan masih dapat memblokir alat.

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. 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

​Bagaimana izin dievaluasi

​Aturan allow dan deny

​Mode izin

​Mode yang tersedia

​Tetapkan mode izin

​Detail mode

​Mode terima edit (acceptEdits)

​Mode jangan tanya (dontAsk)

​Mode lewati izin (bypassPermissions)

​Mode rencana (plan)

​Sumber daya terkait

Bagaimana izin dievaluasi

Aturan allow dan deny

Mode izin

Mode yang tersedia

Tetapkan mode izin

Detail mode

Mode terima edit (`acceptEdits`)

Mode jangan tanya (`dontAsk`)

Mode lewati izin (`bypassPermissions`)

Mode rencana (`plan`)

Sumber daya terkait