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.

Cara izin dievaluasi

Saat Claude meminta sebuah tool, SDK memeriksa izin dengan urutan berikut:

1. Hooks

Jalankan hook terlebih dahulu. Sebuah hook dapat langsung menolak panggilan tersebut atau meneruskannya. Hook yang mengembalikan allow tidak melewati aturan deny dan ask di bawah; aturan-aturan tersebut tetap dievaluasi apa pun hasil hook-nya. Hook PreToolUse yang mengembalikan allow juga tidak dapat menyetujui penghapusan rm atau rmdir yang menargetkan jalur kritis. Untuk apa yang dilakukan allow tersebut dalam plan mode, lihat Persetujuan hook dalam plan mode.

2. Deny rules

Periksa aturan deny (dari disallowed_tools dan settings.json). Jika aturan deny cocok, tool tersebut diblokir, bahkan dalam mode bypassPermissions. Aturan deny dengan nama saja seperti Bash menghapus tool tersebut dari konteks Claude sebelum evaluasi ini dimulai, sehingga hanya aturan bercakupan seperti Bash(rm *) yang diperiksa pada langkah ini.

3. Ask rules

Periksa aturan ask dari settings.json. Jika aturan ask cocok, panggilan tersebut diteruskan ke callback canUseTool Anda untuk konfirmasi, bahkan dalam mode bypassPermissions.

Tool yang memerlukan interaksi pengguna berperilaku sama: AskUserQuestion dan tool MCP yang server-nya menetapkan _meta["anthropic/requiresUserInteraction"] selalu diteruskan ke callback, bahkan ketika aturan allow cocok. Dalam mode dontAsk, kedua kasus tersebut justru ditolak, karena mode tersebut tidak pernah menampilkan permintaan izin. Anotasi MCP memerlukan Claude Code v2.1.199 atau yang lebih baru.

Tool konektor claude.ai yang telah ditetapkan organisasi Anda ke ask juga keluar dari alur pada langkah ini. Setiap panggilan diteruskan ke 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 tersebut justru ditolak, karena mode tersebut tidak pernah menampilkan permintaan izin.

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 justru diteruskan ke langkah berikutnya.
• Dalam mode acceptEdits, Claude Code menyetujui operasi file yang tercantum di bawah Mode accept edits.
• Dalam mode plan, Claude Code mengirimkan tool pengeditan file dan tool penulisan shell ke callback canUseTool Anda terlepas dari aturan allow, sehingga operasi tulis tidak dapat disetujui secara otomatis selama perencanaan.
• Dalam mode lain, permintaan diteruskan ke langkah berikutnya.

5. Allow rules

Periksa aturan allow (dari allowed_tools dan settings.json). Jika aturan cocok, tool tersebut disetujui. Panggilan yang disetujui oleh tool itu sendiri juga diselesaikan pada langkah ini, tanpa memerlukan aturan: 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. Apakah penghapusan tersebut kemudian mencapai callback Anda bergantung pada mode izin: dalam sesi Agent SDK dalam mode auto, misalnya, Claude Code menolaknya secara default tanpa memanggil callback. Tabel mode Jalur kritis mencantumkan apa yang dilakukan setiap mode terhadapnya.

Aturan allow tidak menyetujui pembacaan dari jalur jaringan.

6. canUseTool callback

Jika tidak diselesaikan oleh langkah-langkah di atas, panggil callback canUseTool Anda untuk mendapatkan keputusan. Dalam mode dontAsk, langkah ini dilewati dan tool ditolak, meskipun mod yang Anda instal masih dapat menyetujui beberapa panggilan semacam itu.

Di TypeScript SDK, jika Anda menetapkan permissionPrompts: 'none', callback Anda tidak dipanggil pada langkah ini. Hook PermissionRequest masih mendapat kesempatan untuk memutuskan, dan jika hook tersebut tidak memutuskan, Claude Code menolak panggilan tersebut. Opsi ini memerlukan Claude Code v2.1.259 atau yang lebih baru.

Jika Anda meneruskan callback canUseTool dalam konfigurasi di mana TypeScript SDK memperkirakan urutan evaluasi akan menyetujui panggilan secara otomatis sebelum callback dikonsultasikan, SDK mengeluarkan peringatan proses Node.js satu kali saat query dibuat. Kode peringatan tersebut adalah CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Dua konfigurasi memicunya:

• permissionMode: 'bypassPermissions', yang secara otomatis menyetujui setiap panggilan yang mencapai langkah mode izin, kecuali tindakan yang tidak disetujui otomatis oleh mode mana pun
• Setiap entri allowedTools dengan nama saja seperti "Read", yang secara otomatis menyetujui seluruh tool tersebut sebelum callback dikonsultasikan, kecuali tindakan yang tidak disetujui otomatis oleh mode mana pun dan pembacaan dari jalur jaringan

Entri dengan penentu seperti Bash(ls *) dan mode acceptEdits tidak memicunya, dan aturan allow yang berasal dari file pengaturan tidak terlihat oleh pemeriksaan ini.

Dengarkan dengan process.on('warning', ...) dan cocokkan kodenya untuk menulisnya ke log atau menekannya. Untuk membatasi setiap panggilan tool 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:

• Hook: jalankan kode kustom untuk mengizinkan, menolak, atau memodifikasi permintaan tool. Lihat Mengontrol eksekusi dengan hook.
• Callback canUseTool: minta persetujuan pengguna saat runtime, ketika tidak ada langkah sebelumnya yang menyelesaikan panggilan tersebut. Lihat Menangani persetujuan dan input pengguna.

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 mengikutsertakan sesi tersebut. 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 tool hanya setelah awalan mcp__<server>__ literal. Segmen server harus bebas glob sehingga aturan menyebutkan server spesifik yang Anda konfigurasi: mcp__puppeteer__* cocok dengan setiap tool dari server puppeteer, dan mcp__github__get_* cocok dengan tool get_ miliknya. Entri yang tidak berlabuh seperti allowed_tools=["*"] atau allowed_tools=["mcp__*"] diabaikan 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.

[!WARNING]

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.

Aturan izin tidak pernah menyetujui secara otomatis AskUserQuestion, alat MCP yang ditandai _meta["anthropic/requiresUserInteraction"], alat konektor organisasi Anda atur ke ask, atau penghapusan rm dan rmdir yang menargetkan jalur kritis. Dalam mode dontAsk Claude Code menolak panggilan ini tanpa memanggil callback. Dalam mode lain tiga yang pertama mencapai callback. Tergantung pada mode izin, penghapusan jalur kritis mencapai callback juga atau Claude Code menolaknya tanpa memanggilnya, seperti yang dilakukannya secara default untuk sesi Agent SDK dalam mode auto.

Cakupan tergantung pada bentuk entri: nama polos seperti Read atau mcp__github__get_issue menyetujui secara otomatis setiap panggilan ke tool tersebut kecuali pengecualian di atas dan pembacaan dari jalur jaringan, sementara aturan bercakupan seperti Bash(npm test *) hanya menyetujui secara otomatis panggilan yang cocok, dan panggilan Bash lainnya yang memerlukan persetujuan tetap diteruskan ke callback. Untuk pemeriksaan yang harus berjalan pada setiap panggilan tool, gunakan hook PreToolUse: hook berjalan sebelum setiap langkah lainnya, dan penolakan hook tetap berlaku bahkan dalam mode bypassPermissions.

Untuk agen yang terkunci, pasangkan allowedTools dengan permissionMode: "dontAsk":

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

Tool yang tercantum disetujui, kecuali tindakan yang tidak disetujui otomatis oleh mode mana pun dan pembacaan dari jalur jaringan. Setiap panggilan lain yang akan memunculkan permintaan izin justru ditolak, meskipun mod yang Anda instal masih dapat menyetujui sebagian dari panggilan tersebut.

Panggilan yang tidak memerlukan persetujuan dalam mode default tetap berjalan baik Anda mencantumkannya atau tidak. Panggilan tersebut mencakup perintah Bash read-only, tool seperti Agent yang tidak meminta persetujuan sebelum berjalan, dan pembacaan file di dalam direktori kerja Anda. Untuk menghapus tool sepenuhnya dari permintaan, tambahkan nama polosnya ke disallowedTools.

[!WARNING]

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.

Dengan Claude Code v2.1.302 atau lebih baru, aplikasi Anda dimulai dalam mode default kecuali Anda mengatur mode izin atau aplikasi mendapatkannya dari permissions.defaultMode dalam file pengaturannya. Dalam mode default, Claude Code menolak setiap panggilan tool yang memerlukan persetujuan kecuali Anda menyetujuinya melalui aturan allow, hook, callback canUseTool, atau tool prompt izin. Jika panggilan tool ditolak, lihat Panggilan tool ditolak dalam run claude -p dan Agent SDK.

Mode yang tersedia

SDK mendukung mode izin berikut:

[!WARNING]

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", dan menerapkan nilai "auto" hanya ketika auto mode tersedia untuk subagent tersebut. 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.

Pada waktu query

Lewatkan permission_mode (Python) atau permissionMode (TypeScript) saat membuat query.

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

Selama streaming

Panggil set_permission_mode() (Python) atau setPermissionMode() (TypeScript) untuk mengubah mode di tengah sesi. Mode baru berlaku segera untuk semua permintaan tool berikutnya. Ini memungkinkan Anda untuk 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 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, meskipun mod yang Anda instal masih dapat menyetujui sebagian panggilan tersebut. Tools yang disetujui sebelumnya oleh allowed_tools, aturan allow settings.json, atau hook berjalan seperti biasa. Panggilan yang tidak memerlukan persetujuan dalam mode default juga berjalan, seperti pembacaan file di dalam direktori kerja Anda dan panggilan ke Agent.

Connector tools yang diatur organisasi Anda ke ask, tools yang memerlukan interaksi pengguna, pembacaan dari jalur jaringan, serta penghapusan rm dan rmdir yang menargetkan jalur kritis ditolak bahkan ketika aturan allow cocok. Hook allow PreToolUse juga tidak meloloskan penghapusan jalur kritis maupun pembacaan dari jalur jaringan.

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. Pada Linux dan macOS, Claude Code menolak untuk memulai dalam mode ini sebagai root atau di bawah sudo di luar sandbox yang diakui, dan query gagal sebelum giliran pertama.

[!WARNING]

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 plan mode, bahkan ketika aturan allow cocok atau hook PreToolUse mengembalikan allow. Pengeditan tersebut 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.

Dalam SDK TypeScript, jika Anda mengatur allowDangerouslySkipPermissions: true bersama dengan permissionMode: 'plan', pengeditan file dan perintah shell yang memodifikasi file masih mencapai callback canUseTool Anda. Opsi ini memungkinkan Anda untuk beralih ke bypassPermissions nanti dengan setPermissionMode().

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.

Auto mode (auto)

Model pengklasifikasi meninjau tindakan seperti perintah shell dan permintaan jaringan sebelum dijalankan, serta mengizinkan atau memblokir masing-masing yang ditinjaunya. Untuk model dan penyedia yang diperlukan auto mode serta urutan evaluasi tindakannya, lihat Hilangkan prompt izin dengan auto mode.

Jika Anda mengalihkan sesi yang berada dalam auto mode ke model yang tidak didukung auto mode, menggunakan set_model(), setModel(), atau applyFlagSettings(), sesi berubah ke mode default:

• Yang Anda lihat: pesan system dengan subtype status dan permissionMode diatur ke "default", yang diberi tipe oleh SDK TypeScript sebagai SDKStatusMessage. Sejak saat itu, panggilan yang memerlukan persetujuan dan tidak cocok dengan aturan allow mencapai callback canUseTool Anda.
• Untuk kembali ke auto mode: beralih ke model yang didukung, lalu panggil set_permission_mode("auto") atau setPermissionMode("auto"). Jika Anda mengembalikan model tanpa melakukan panggilan tersebut, sesi tetap dalam mode default. Selama model yang tidak didukung aktif, panggilan tersebut gagal dengan Cannot set permission mode to auto: auto mode unavailable for this model.

Perubahan ke mode default setelah panggilan set_model(), setModel(), atau applyFlagSettings() memerlukan Claude Code v2.1.299 atau lebih baru.

Sumber daya terkait

Untuk langkah-langkah lain dalam alur evaluasi izin:

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