Skip to main content
Saat mengerjakan tugas, Claude kadang-kadang perlu berkonsultasi dengan pengguna. Mungkin perlu izin sebelum menghapus file, atau perlu menanyakan database mana yang akan digunakan untuk proyek baru. Aplikasi Anda perlu menampilkan permintaan ini kepada pengguna sehingga Claude dapat melanjutkan dengan input mereka. Claude meminta input pengguna dalam dua situasi: ketika membutuhkan izin untuk menggunakan alat (seperti menghapus file atau menjalankan perintah), dan ketika memiliki pertanyaan klarifikasi (melalui alat AskUserQuestion). Keduanya memicu callback canUseTool Anda, yang menghentikan eksekusi sampai Anda mengembalikan respons. Ini berbeda dari putaran percakapan normal di mana Claude selesai dan menunggu pesan berikutnya Anda. Untuk pertanyaan klarifikasi, Claude menghasilkan pertanyaan dan opsi. Peran Anda adalah menyajikannya kepada pengguna dan mengembalikan pilihan mereka. Anda tidak dapat menambahkan pertanyaan Anda sendiri ke alur ini; jika Anda perlu menanyakan sesuatu kepada pengguna, lakukan itu secara terpisah dalam logika aplikasi Anda. Callback dapat tetap tertunda tanpa batas waktu. Eksekusi tetap dijeda sampai callback Anda kembali. Jika pengguna mungkin membutuhkan waktu lebih lama untuk merespons daripada yang dapat ditahan proses Anda, daftarkan hook PreToolUse yang mengembalikan keputusan defer alih-alih menunggu dalam callback, sehingga proses dapat keluar dan dilanjutkan nanti dari sesi yang disimpan. Panduan ini menunjukkan cara mendeteksi setiap jenis permintaan dan merespons dengan tepat.

Deteksi ketika Claude membutuhkan input

Berikan callback canUseTool dalam opsi kueri Anda. Callback dipicu setiap kali Claude membutuhkan input pengguna, menerima nama alat dan input sebagai argumen:
Callback dipicu dalam dua kasus:
  1. Alat membutuhkan persetujuan: Claude ingin menggunakan alat yang tidak disetujui secara otomatis oleh aturan izin atau mode izin. Periksa tool_name untuk alat (misalnya, "Bash", "Write").
  2. Claude mengajukan pertanyaan: Claude memanggil alat AskUserQuestion. Periksa apakah tool_name == "AskUserQuestion" untuk menanganinya secara berbeda. Jika Anda menentukan array tools, sertakan AskUserQuestion agar ini berfungsi. Lihat Menangani pertanyaan klarifikasi untuk detail.
Callback tidak pernah dipicu untuk alat yang disetujui secara otomatis. Setiap persetujuan sebelumnya dalam alur evaluasi izin, aturan izin atau mode seperti acceptEdits atau bypassPermissions, menyelesaikan panggilan sebelum canUseTool dikonsultasikan. Jika Anda mencantumkan alat secara langsung dalam allowed_tools, pemeriksaan canUseTool untuk alat tersebut berjalan hanya ketika alur evaluasi mengarahkan panggilan kembali ke prompt, seperti aturan ask atau mode plan. Untuk logika yang harus diterapkan ke setiap panggilan alat, gunakan hook PreToolUse, yang dijalankan sebelum sisa alur dan dapat mengizinkan, menolak, atau memodifikasi permintaan.Aturan izin tidak pra-menyetujui tindakan yang tidak ada mode yang menyetujui secara otomatis; lihat Cara izin dievaluasi untuk mengetahui mana dari mereka yang mencapai callback dan apa yang terjadi dalam mode dontAsk dan auto.
Anda juga dapat menggunakan hook PermissionRequest untuk mengirim notifikasi eksternal (Slack, email, push) ketika Claude menunggu persetujuan.

Menangani permintaan persetujuan alat

Setelah Anda melewatkan callback canUseTool dalam opsi kueri Anda, callback dipicu ketika Claude ingin menggunakan alat yang tidak disetujui oleh apa pun sebelumnya dalam alur izin. Dalam beberapa konfigurasi, seperti mode dontAsk, Claude Code tidak memanggilnya; langkah terakhir dari Bagaimana izin dievaluasi mencantumkannya dan mengatakan apa yang terjadi pada panggilan sebagai gantinya. Callback Anda menerima tiga argumen: Objek input berisi parameter khusus alat. Contoh umum: Lihat referensi SDK untuk skema input lengkap: Python | TypeScript. Anda dapat menampilkan informasi ini kepada pengguna sehingga mereka dapat memutuskan apakah akan mengizinkan atau menolak tindakan, kemudian kembalikan respons yang sesuai. Contoh berikut meminta Claude untuk membuat dan menghapus file uji. Ketika Claude mencoba setiap operasi, callback mencetak permintaan alat ke terminal dan meminta persetujuan y/n.
Contoh ini menggunakan alur y/n di mana input apa pun selain y diperlakukan sebagai penolakan. Dalam praktik, Anda mungkin membangun UI yang lebih kaya yang memungkinkan pengguna memodifikasi permintaan, memberikan umpan balik, atau mengarahkan Claude sepenuhnya. Lihat Merespons permintaan alat untuk semua cara Anda dapat merespons.

Merespons permintaan alat

Callback Anda mengembalikan salah satu dari dua jenis respons: Saat mengizinkan, alat berjalan dengan input yang diminta Claude kecuali Anda mengembalikan input yang dimodifikasi, updatedInput di TypeScript atau updated_input di Python. Sebelum v2.1.207, Claude Code menolak hasil izin yang menghilangkan updatedInput dan menolak panggilan alat dengan kesalahan validasi. Saat menolak, berikan pesan yang menjelaskan alasannya. Claude melihat pesan ini dan mungkin menyesuaikan pendekatannya. Selain mengizinkan atau menolak, Anda dapat memodifikasi input alat atau memberikan konteks yang membantu Claude menyesuaikan pendekatannya:
  • Setujui: biarkan alat dijalankan seperti yang diminta Claude
  • Setujui dengan perubahan: modifikasi input sebelum eksekusi (misalnya, sanitasi jalur, tambahkan batasan)
  • Setujui dan ingat: kembalikan aturan izin yang disarankan sehingga panggilan yang cocok melewati prompt berikutnya
  • Tolak: blokir alat dan beri tahu Claude mengapa
  • Sarankan alternatif: blokir tetapi arahkan Claude ke arah yang diinginkan pengguna
  • Alihkan sepenuhnya: gunakan input streaming untuk mengirim Claude instruksi yang sepenuhnya baru
Pembantu ask_user dan askUser dalam cuplikan berikut berdiri untuk UI prompt aplikasi Anda sendiri.
Pengguna menyetujui tindakan apa adanya. Teruskan input dari callback Anda tanpa perubahan dan alat dijalankan persis seperti yang diminta Claude.