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, dan SDK hanya membatalkan tunggu ketika kueri itu sendiri dibatalkan. Jika pengguna mungkin membutuhkan waktu lebih lama untuk merespons daripada yang dapat ditahan proses Anda, kembalikan keputusan defer hook, yang memungkinkan proses 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 callbackcanUseTool dalam opsi kueri Anda. Callback dipicu setiap kali Claude membutuhkan input pengguna, menerima nama alat dan input sebagai argumen:
- Alat membutuhkan persetujuan: Claude ingin menggunakan alat yang tidak disetujui secara otomatis oleh aturan izin atau mode izin. Periksa
tool_nameuntuk alat (misalnya,"Bash","Write"). - Claude mengajukan pertanyaan: Claude memanggil alat
AskUserQuestion. Periksa apakahtool_name == "AskUserQuestion"untuk menanganinya secara berbeda. Jika Anda menentukan arraytools, sertakanAskUserQuestionagar ini berfungsi. Lihat Menangani pertanyaan klarifikasi untuk detail.
PermissionRequest untuk mengirim notifikasi eksternal (Slack, email, push) ketika Claude menunggu persetujuan.
Menangani permintaan persetujuan alat
Setelah Anda melewatkan callbackcanUseTool dalam opsi kueri Anda, callback dipicu ketika Claude ingin menggunakan alat yang tidak disetujui secara otomatis. 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.
Di Python,
can_use_tool memerlukan mode streaming. Ketika Anda melewatkan aliran pesan terbatas melalui query(prompt=generator) atau ClaudeSDKClient.connect(prompt=async_iterable), SDK menutup aliran input setelah pesan terakhir, sebelum callback izin dapat dipanggil, kecuali hook terdaftar atau server MCP dalam proses menjaganya tetap terbuka. Contoh di atas menjaganya tetap terbuka dengan hook PreToolUse yang mengembalikan {"continue_": True}. Menghubungkan tanpa prompt dan mengirim pesan melalui ClaudeSDKClient.query() menjaga aliran tetap terbuka dengan sendirinya dan tidak memerlukan hook.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.
- 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
- Setujui
- Setujui dengan perubahan
- Setujui dan ingat
- Tolak
- Sarankan alternatif
- Alihkan sepenuhnya
Pengguna menyetujui tindakan apa adanya. Teruskan
input dari callback Anda tanpa perubahan dan alat dijalankan persis seperti yang diminta Claude.Menangani pertanyaan klarifikasi
Ketika Claude membutuhkan lebih banyak arahan tentang tugas dengan beberapa pendekatan yang valid, Claude memanggil alatAskUserQuestion. Ini memicu callback canUseTool Anda dengan toolName diatur ke AskUserQuestion. Input berisi pertanyaan Claude sebagai opsi pilihan ganda, yang Anda tampilkan kepada pengguna dan kembalikan pilihan mereka.
Langkah-langkah berikut menunjukkan cara menangani pertanyaan klarifikasi:
1
Berikan callback canUseTool
Berikan callback
canUseTool dalam opsi kueri Anda. Secara default, AskUserQuestion tersedia. Jika Anda menentukan array tools untuk membatasi kemampuan Claude (misalnya, agen read-only dengan hanya Read, Glob, dan Grep), sertakan AskUserQuestion dalam array itu. Jika tidak, Claude tidak akan dapat mengajukan pertanyaan klarifikasi:2
Deteksi AskUserQuestion
Dalam callback Anda, periksa apakah
toolName sama dengan AskUserQuestion untuk menanganinya secara berbeda dari alat lain:3
Analisis input pertanyaan
Input berisi pertanyaan Claude dalam array Lihat Format pertanyaan untuk deskripsi bidang lengkap.
questions. Setiap pertanyaan memiliki question (teks untuk ditampilkan), options (pilihan), dan multiSelect (apakah beberapa pilihan diizinkan):4
Kumpulkan jawaban dari pengguna
Presentasikan pertanyaan kepada pengguna dan kumpulkan pilihan mereka. Cara Anda melakukan ini tergantung pada aplikasi Anda: prompt terminal, formulir web, dialog seluler, dll.
5
Kembalikan jawaban ke Claude
Bangun objek
answers sebagai catatan di mana setiap kunci adalah teks question dan setiap nilai adalah label opsi yang dipilih:Untuk pertanyaan multi-pilih, berikan array label atau gabungkan dengan
", ". Jika Anda mendukung input teks bebas, gunakan teks kustom pengguna sebagai nilai.Format pertanyaan
Input berisi pertanyaan yang dihasilkan Claude dalam arrayquestions. Setiap pertanyaan memiliki bidang-bidang ini:
Struktur yang diterima callback Anda:
Pratinjau opsi (TypeScript)
toolConfig.askUserQuestion.previewFormat menambahkan bidang preview ke setiap opsi sehingga aplikasi Anda dapat menampilkan mockup visual di samping label. Tanpa pengaturan ini, Claude tidak menghasilkan pratinjau dan bidang tidak ada.
Format berlaku untuk semua pertanyaan dalam sesi. Claude menyertakan
preview pada opsi di mana perbandingan visual membantu (pilihan tata letak, skema warna) dan menghilangkannya di mana tidak akan membantu (konfirmasi ya/tidak, pilihan hanya teks). Periksa undefined sebelum merender.
Format respons
Kembalikan objekanswers yang memetakan bidang question setiap pertanyaan ke label opsi yang dipilih:
Untuk pertanyaan multi-pilih, berikan array label atau gabungkan dengan
", ". Untuk input teks bebas per-pertanyaan seperti opsi “Other”, masukkan teks pengguna dalam answers[question] seperti yang ditunjukkan dalam Dukung input teks bebas. Atur response hanya ketika UI Anda memungkinkan pengguna untuk menutup kartu pertanyaan dan mengetik respons umum yang bukan jawaban untuk pertanyaan spesifik apa pun. Ketika response diatur, Claude menerima “The user responded: …” alih-alih daftar jawaban per-pertanyaan.
Dukung input teks bebas
Opsi yang telah ditentukan Claude tidak akan selalu mencakup apa yang diinginkan pengguna. Untuk memungkinkan pengguna mengetik jawaban mereka sendiri:- Tampilkan pilihan “Other” tambahan setelah opsi Claude yang menerima input teks
- Gunakan teks kustom pengguna sebagai nilai jawaban (bukan kata “Other”)
Contoh lengkap
Claude mengajukan pertanyaan klarifikasi ketika membutuhkan input pengguna untuk melanjutkan. Misalnya, ketika diminta membantu memutuskan tech stack untuk aplikasi seluler, Claude mungkin menanyakan tentang cross-platform vs native, preferensi backend, atau platform target. Pertanyaan-pertanyaan ini membantu Claude membuat keputusan yang sesuai dengan preferensi pengguna daripada menebak. Contoh ini menangani pertanyaan-pertanyaan tersebut dalam aplikasi terminal. Berikut yang terjadi di setiap langkah:- Arahkan permintaan: Callback
canUseToolmemeriksa apakah nama alat adalah"AskUserQuestion"dan mengarahkan ke handler khusus - Tampilkan pertanyaan: Handler melakukan loop melalui array
questionsdan mencetak setiap pertanyaan dengan opsi bernomor - Kumpulkan input: Pengguna dapat memasukkan angka untuk memilih opsi, atau mengetik teks bebas langsung (misalnya, “jquery”, “i don’t know”)
- Peta jawaban: Kode memeriksa apakah input adalah numerik (menggunakan label opsi) atau teks bebas (menggunakan teks langsung)
- Kembalikan ke Claude: Respons mencakup array
questionsasli dan pemetaananswers
ask.ts dan jalankan dengan npx tsx ask.ts, atau simpan versi Python sebagai ask.py dan jalankan dengan python ask.py.
Keterbatasan
- Subagents:
AskUserQuestionsaat ini tidak tersedia di subagents yang dihasilkan melalui alat Agent - Batas pertanyaan: setiap panggilan
AskUserQuestionmendukung 1-4 pertanyaan dengan 2-4 opsi masing-masing
Cara lain untuk mendapatkan input pengguna
CallbackcanUseTool dan alat AskUserQuestion mencakup sebagian besar skenario persetujuan dan klarifikasi, tetapi SDK menawarkan cara lain untuk mendapatkan input dari pengguna:
Input streaming
Gunakan input streaming ketika Anda perlu:- Mengganggu agen di tengah-tugas: kirim sinyal pembatalan atau ubah arah saat Claude sedang bekerja
- Memberikan konteks tambahan: tambahkan informasi yang dibutuhkan Claude tanpa menunggu untuk ditanya
- Membangun antarmuka obrolan: biarkan pengguna mengirim pesan lanjutan selama operasi yang berjalan lama
Alat kustom
Gunakan alat kustom ketika Anda perlu:- Mengumpulkan input terstruktur: bangun formulir, wizard, atau alur kerja multi-langkah yang melampaui format pilihan ganda
AskUserQuestion - Mengintegrasikan sistem persetujuan eksternal: terhubung ke platform tiket, alur kerja, atau persetujuan yang ada
- Menerapkan interaksi khusus domain: buat alat yang disesuaikan dengan kebutuhan aplikasi Anda, seperti antarmuka tinjauan kode atau daftar periksa penyebaran
canUseTool bawaan.
Sumber daya terkait
- Konfigurasi izin: atur mode dan aturan izin
- Kontrol eksekusi dengan hooks: jalankan kode kustom di titik-titik kunci dalam siklus hidup agen
- Referensi TypeScript SDK: dokumentasi API canUseTool lengkap