Bahasa Indonesia

Menangani persetujuan dan input pengguna

Tampilkan permintaan persetujuan Claude dan pertanyaan klarifikasi kepada pengguna, kemudian kembalikan keputusan mereka ke SDK.

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, 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 callback canUseTool dalam opsi kueri Anda. Callback dipicu setiap kali Claude membutuhkan input pengguna, menerima nama alat dan input sebagai argumen:

async def handle_tool_request(tool_name, input_data, context):
# Minta pengguna dan kembalikan izin atau tolak
...


options = ClaudeAgentOptions(can_use_tool=handle_tool_request)

async function handleToolRequest(toolName, input, options) {
// options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }
// Minta pengguna dan kembalikan izin atau tolak
}

const options = { canUseTool: handleToolRequest };

Callback dipicu dalam dua kasus:

Alat membutuhkan persetujuan: Claude ingin menggunakan alat yang tidak disetujui secara otomatis oleh aturan izin atau mode. Periksa tool_name untuk alat (misalnya, "Bash", "Write").
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.

Menangani permintaan persetujuan alat

Setelah Anda melewatkan callback canUseTool dalam opsi kueri Anda, callback dipicu ketika Claude ingin menggunakan alat yang tidak disetujui secara otomatis. Callback Anda menerima tiga argumen:

Argumen	Deskripsi
`toolName`	Nama alat yang ingin digunakan Claude (misalnya, `"Bash"`, `"Write"`, `"Edit"`)
`input`	Parameter yang diteruskan Claude ke alat. Isi bervariasi menurut alat.
`options` (TS) / `context` (Python)	Konteks tambahan termasuk `suggestions` opsional (entri `PermissionUpdate` yang diusulkan untuk menghindari permintaan ulang) dan sinyal pembatalan. Di TypeScript, `signal` adalah `AbortSignal`; di Python, bidang sinyal dicadangkan untuk penggunaan di masa depan. Lihat `ToolPermissionContext` untuk Python.

Objek input berisi parameter khusus alat. Contoh umum:

Alat	Bidang input
`Bash`	`command`, `description`, `timeout`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Read`	`file_path`, `offset`, `limit`

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.

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import (
HookMatcher,
PermissionResultAllow,
PermissionResultDeny,
ToolPermissionContext,
)


async def can_use_tool(
tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:
# Tampilkan permintaan alat
print(f"\nTool: {tool_name}")
if tool_name == "Bash":
print(f"Command: {input_data.get('command')}")
if input_data.get("description"):
print(f"Description: {input_data.get('description')}")
else:
print(f"Input: {input_data}")

# Dapatkan persetujuan pengguna
response = input("Allow this action? (y/n): ")

# Kembalikan izin atau tolak berdasarkan respons pengguna
if response.lower() == "y":
# Izinkan: alat dijalankan dengan input asli (atau dimodifikasi)
return PermissionResultAllow(updated_input=input_data)
else:
# Tolak: alat tidak dijalankan, Claude melihat pesan
return PermissionResultDeny(message="User denied this action")


# Solusi yang diperlukan: hook dummy menjaga aliran tetap terbuka untuk can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
return {"continue_": True}


async def prompt_stream():
yield {
"type": "user",
"message": {
"role": "user",
"content": "Create a test file in /tmp and then delete it",
},
}


async def main():
async for message in query(
prompt=prompt_stream(),
options=ClaudeAgentOptions(
can_use_tool=can_use_tool,
hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline";

// Helper untuk meminta input pengguna di terminal
function prompt(question: string): Promise<string> {
const rl = readline.createInterface({
input: process.stdin,
output: process.stdout
});
return new Promise((resolve) =>
rl.question(question, (answer) => {
rl.close();
resolve(answer);
})
);
}

for await (const message of query({
prompt: "Create a test file in /tmp and then delete it",
options: {
canUseTool: async (toolName, input) => {
// Tampilkan permintaan alat
console.log(`\nTool: ${toolName}`);
if (toolName === "Bash") {
console.log(`Command: ${input.command}`);
if (input.description) console.log(`Description: ${input.description}`);
} else {
console.log(`Input: ${JSON.stringify(input, null, 2)}`);
}

// Dapatkan persetujuan pengguna
const response = await prompt("Allow this action? (y/n): ");

// Kembalikan izin atau tolak berdasarkan respons pengguna
if (response.toLowerCase() === "y") {
// Izinkan: alat dijalankan dengan input asli (atau dimodifikasi)
return { behavior: "allow", updatedInput: input };
} else {
// Tolak: alat tidak dijalankan, Claude melihat pesan
return { behavior: "deny", message: "User denied this action" };
}
}
}
})) {
if ("result" in message) console.log(message.result);
}

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:

Respons	Python	TypeScript
Izinkan	`PermissionResultAllow(updated_input=...)`	`{ behavior: "allow", updatedInput }`
Tolak	`PermissionResultDeny(message=...)`	`{ behavior: "deny", message }`

Saat mengizinkan, berikan input alat (asli atau dimodifikasi). Saat menolak, berikan pesan yang menjelaskan alasannya. Claude melihat pesan ini dan mungkin menyesuaikan pendekatannya.

from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

# Izinkan alat untuk dijalankan
return PermissionResultAllow(updated_input=input_data)

# Blokir alat
return PermissionResultDeny(message="User rejected this action")

// Izinkan alat untuk dijalankan
return { behavior: "allow", updatedInput: input };

// Blokir alat
return { behavior: "deny", message: "User rejected this action" };

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

Pengguna menyetujui tindakan apa adanya. Teruskan input dari callback Anda tanpa perubahan dan alat dijalankan persis seperti yang diminta Claude.

async def can_use_tool(tool_name, input_data, context):
print(f"Claude wants to use {tool_name}")
approved = await ask_user("Allow this action?")

if approved:
return PermissionResultAllow(updated_input=input_data)
return PermissionResultDeny(message="User declined")

canUseTool: async (toolName, input) => {
console.log(`Claude wants to use ${toolName}`);
const approved = await askUser("Allow this action?");

if (approved) {
return { behavior: "allow", updatedInput: input };
}
return { behavior: "deny", message: "User declined" };
};

Pengguna menyetujui tetapi ingin memodifikasi permintaan terlebih dahulu. Anda dapat mengubah input sebelum alat dijalankan. Claude melihat hasilnya tetapi tidak diberitahu Anda mengubah apa pun. Berguna untuk sanitasi parameter, menambahkan batasan, atau membatasi akses.

async def can_use_tool(tool_name, input_data, context):
if tool_name == "Bash":
# Pengguna menyetujui, tetapi batasi semua perintah ke sandbox
sandboxed_input = {**input_data}
sandboxed_input["command"] = input_data["command"].replace(
"/tmp", "/tmp/sandbox"
)
return PermissionResultAllow(updated_input=sandboxed_input)
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
if (toolName === "Bash") {
// Pengguna menyetujui, tetapi batasi semua perintah ke sandbox
const sandboxedInput = {
...input,
command: input.command.replace("/tmp", "/tmp/sandbox")
};
return { behavior: "allow", updatedInput: sandboxedInput };
}
return { behavior: "allow", updatedInput: input };
};

Pengguna menyetujui dan tidak ingin ditanya lagi untuk jenis panggilan ini. Argumen callback ketiga membawa suggestions, sebuah array entri PermissionUpdate yang sudah jadi. Kembalikan satu di updatedPermissions untuk menerapkannya. Saran dengan tujuan localSettings menulis aturan ke .claude/settings.local.json sehingga sesi mendatang melewati prompt untuk panggilan yang cocok.

Contoh Python memerlukan claude-agent-sdk 0.1.80 atau lebih baru.

async def can_use_tool(tool_name, input_data, context):
choice = await ask_user(f"Allow {tool_name}?", ["once", "always", "no"])

if choice == "always":
persist = [
s for s in context.suggestions if s.destination == "localSettings"
]
return PermissionResultAllow(
updated_input=input_data, updated_permissions=persist
)
if choice == "once":
return PermissionResultAllow(updated_input=input_data)
return PermissionResultDeny(message="User declined")

canUseTool: async (toolName, input, { suggestions = [] }) => {
const choice = await askUser(`Allow ${toolName}?`, ["once", "always", "no"]);

if (choice === "always") {
const persist = suggestions.filter(
(s) => s.destination === "localSettings"
);
return {
behavior: "allow",
updatedInput: input,
updatedPermissions: persist
};
}
if (choice === "once") {
return { behavior: "allow", updatedInput: input };
}
return { behavior: "deny", message: "User declined" };
};

Pengguna tidak menginginkan tindakan ini terjadi. Blokir alat dan berikan pesan yang menjelaskan alasannya. Claude melihat pesan ini dan mungkin mencoba pendekatan yang berbeda.

async def can_use_tool(tool_name, input_data, context):
approved = await ask_user(f"Allow {tool_name}?")

if not approved:
return PermissionResultDeny(message="User rejected this action")
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
const approved = await askUser(`Allow ${toolName}?`);

if (!approved) {
return {
behavior: "deny",
message: "User rejected this action"
};
}
return { behavior: "allow", updatedInput: input };
};

Pengguna tidak menginginkan tindakan spesifik ini, tetapi memiliki ide yang berbeda. Blokir alat dan sertakan panduan dalam pesan Anda. Claude akan membaca ini dan memutuskan cara melanjutkan berdasarkan umpan balik Anda.

async def can_use_tool(tool_name, input_data, context):
if tool_name == "Bash" and "rm" in input_data.get("command", ""):
# Pengguna tidak ingin menghapus, sarankan pengarsipan sebagai gantinya
return PermissionResultDeny(
message="User doesn't want to delete files. They asked if you could compress them into an archive instead."
)
return PermissionResultAllow(updated_input=input_data)

canUseTool: async (toolName, input) => {
if (toolName === "Bash" && input.command.includes("rm")) {
// Pengguna tidak ingin menghapus, sarankan pengarsipan sebagai gantinya
return {
behavior: "deny",
message:
"User doesn't want to delete files. They asked if you could compress them into an archive instead."
};
}
return { behavior: "allow", updatedInput: input };
};

Menangani pertanyaan klarifikasi

Ketika Claude membutuhkan lebih banyak arahan tentang tugas dengan beberapa pendekatan yang valid, Claude memanggil alat AskUserQuestion. 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:

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:

async for message in query(
prompt="Analyze this codebase",
options=ClaudeAgentOptions(
# Sertakan AskUserQuestion dalam daftar alat Anda
tools=["Read", "Glob", "Grep", "AskUserQuestion"],
can_use_tool=can_use_tool,
),
):
print(message)

for await (const message of query({
prompt: "Analyze this codebase",
options: {
// Sertakan AskUserQuestion dalam daftar alat Anda
tools: ["Read", "Glob", "Grep", "AskUserQuestion"],
canUseTool: async (toolName, input) => {
// Tangani pertanyaan klarifikasi di sini
}
}
})) {
console.log(message);
}

Deteksi AskUserQuestion

Dalam callback Anda, periksa apakah toolName sama dengan AskUserQuestion untuk menanganinya secara berbeda dari alat lain:

async def can_use_tool(tool_name: str, input_data: dict, context):
if tool_name == "AskUserQuestion":
# Implementasi Anda untuk mengumpulkan jawaban dari pengguna
return await handle_clarifying_questions(input_data)
# Tangani alat lain secara normal
return await prompt_for_approval(tool_name, input_data)

canUseTool: async (toolName, input) => {
if (toolName === "AskUserQuestion") {
// Implementasi Anda untuk mengumpulkan jawaban dari pengguna
return handleClarifyingQuestions(input);
}
// Tangani alat lain secara normal
return promptForApproval(toolName, input);
};

Analisis input pertanyaan

Input berisi pertanyaan Claude dalam array questions. Setiap pertanyaan memiliki question (teks untuk ditampilkan), options (pilihan), dan multiSelect (apakah beberapa pilihan diizinkan):

{
"questions": [
{
"question": "How should I format the output?",
"header": "Format",
"options": [
{ "label": "Summary", "description": "Brief overview" },
{ "label": "Detailed", "description": "Full explanation" }
],
"multiSelect": false
},
{
"question": "Which sections should I include?",
"header": "Sections",
"options": [
{ "label": "Introduction", "description": "Opening context" },
{ "label": "Conclusion", "description": "Final summary" }
],
"multiSelect": true
}
]
}

Lihat Format pertanyaan untuk deskripsi bidang lengkap.

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.

Kembalikan jawaban ke Claude

Bangun objek answers sebagai catatan di mana setiap kunci adalah teks question dan setiap nilai adalah label opsi yang dipilih:

Dari objek pertanyaan	Gunakan sebagai
Bidang `question` (misalnya, `"How should I format the output?"`)	Kunci
Bidang `label` opsi yang dipilih (misalnya, `"Summary"`)	Nilai

Untuk pertanyaan multi-pilih, berikan array label atau gabungkan dengan ", ". Jika Anda mendukung input teks bebas, gunakan teks kustom pengguna sebagai nilai.

return PermissionResultAllow(
updated_input={
"questions": input_data.get("questions", []),
"answers": {
"How should I format the output?": "Summary",
"Which sections should I include?": ["Introduction", "Conclusion"],
},
}
)

return {
behavior: "allow",
updatedInput: {
questions: input.questions,
answers: {
"How should I format the output?": "Summary",
"Which sections should I include?": "Introduction, Conclusion"
}
}
};

Format pertanyaan

Input berisi pertanyaan yang dihasilkan Claude dalam array questions. Setiap pertanyaan memiliki bidang-bidang ini:

Bidang	Deskripsi
`question`	Teks pertanyaan lengkap untuk ditampilkan
`header`	Label pendek untuk pertanyaan (maks 12 karakter)
`options`	Array 2-4 pilihan, masing-masing dengan `label` dan `description`. TypeScript: secara opsional `preview` (lihat di bawah)
`multiSelect`	Jika `true`, pengguna dapat memilih beberapa opsi

Struktur yang diterima callback Anda:

{
  "questions": [
    {
      "question": "How should I format the output?",
      "header": "Format",
      "options": [
        { "label": "Summary", "description": "Brief overview of key points" },
        { "label": "Detailed", "description": "Full explanation with examples" }
      ],
      "multiSelect": false
    }
  ]
}

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.

`previewFormat`	`preview` berisi
tidak diatur (default)	Bidang tidak ada. Claude tidak menghasilkan pratinjau.
`"markdown"`	ASCII art dan blok kode yang dibatasi
`"html"`	Fragmen `<div>` bergaya (SDK menolak `<script>`, `<style>`, dan `<!DOCTYPE>` sebelum callback Anda berjalan)

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.

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me choose a card layout",
  options: {
    toolConfig: {
      askUserQuestion: { previewFormat: "html" }
    },
    canUseTool: async (toolName, input) => {
      // input.questions[].options[].preview adalah string HTML atau undefined
      return { behavior: "allow", updatedInput: input };
    }
  }
})) {
  // ...
}

Opsi dengan pratinjau HTML:

{
  "label": "Compact",
  "description": "Title and metric value only",
  "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"
}

Format respons

Kembalikan objek answers yang memetakan bidang question setiap pertanyaan ke label opsi yang dipilih:

Bidang	Deskripsi
`questions`	Teruskan array pertanyaan asli (diperlukan untuk pemrosesan alat)
`answers`	Objek di mana kunci adalah teks pertanyaan dan nilai adalah label yang dipilih
`response`	Respons freeform opsional yang diketik pengguna alih-alih menjawab pertanyaan terstruktur

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.

{
  "questions": [
    // ...
  ],
  "answers": {
    "How should I format the output?": "Summary",
    "Which sections should I include?": ["Introduction", "Conclusion"]
  }
}

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

Lihat contoh lengkap di bawah untuk implementasi lengkap.

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 canUseTool memeriksa apakah nama alat adalah "AskUserQuestion" dan mengarahkan ke handler khusus
Tampilkan pertanyaan: Handler melakukan loop melalui array questions dan 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 questions asli dan pemetaan answers

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
from claude_agent_sdk.types import HookMatcher, PermissionResultAllow


def parse_response(response: str, options: list) -> str:
"""Analisis input pengguna sebagai nomor opsi atau teks bebas."""
try:
indices = [int(s.strip()) - 1 for s in response.split(",")]
labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]
return ", ".join(labels) if labels else response
except ValueError:
return response


async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:
"""Tampilkan pertanyaan Claude dan kumpulkan jawaban pengguna."""
answers = {}

for q in input_data.get("questions", []):
print(f"\n{q['header']}: {q['question']}")

options = q["options"]
for i, opt in enumerate(options):
print(f"  {i + 1}. {opt['label']} - {opt['description']}")
if q.get("multiSelect"):
print("  (Enter numbers separated by commas, or type your own answer)")
else:
print("  (Enter a number, or type your own answer)")

response = input("Your choice: ").strip()
answers[q["question"]] = parse_response(response, options)

return PermissionResultAllow(
updated_input={
"questions": input_data.get("questions", []),
"answers": answers,
}
)


async def can_use_tool(
tool_name: str, input_data: dict, context
) -> PermissionResultAllow:
# Arahkan AskUserQuestion ke handler pertanyaan kami
if tool_name == "AskUserQuestion":
return await handle_ask_user_question(input_data)
# Setujui secara otomatis alat lain untuk contoh ini
return PermissionResultAllow(updated_input=input_data)


async def prompt_stream():
yield {
"type": "user",
"message": {
"role": "user",
"content": "Help me decide on the tech stack for a new mobile app",
},
}


# Solusi yang diperlukan: hook dummy menjaga aliran tetap terbuka untuk can_use_tool
async def dummy_hook(input_data, tool_use_id, context):
return {"continue_": True}


async def main():
async for message in query(
prompt=prompt_stream(),
options=ClaudeAgentOptions(
can_use_tool=can_use_tool,
hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
),
):
if isinstance(message, ResultMessage) and message.subtype == "success":
print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as readline from "readline/promises";

// Helper untuk meminta input pengguna di terminal
async function prompt(question: string): Promise<string> {
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const answer = await rl.question(question);
rl.close();
return answer;
}

// Analisis input pengguna sebagai nomor opsi atau teks bebas
function parseResponse(response: string, options: any[]): string {
const indices = response.split(",").map((s) => parseInt(s.trim()) - 1);
const labels = indices
.filter((i) => !isNaN(i) && i >= 0 && i < options.length)
.map((i) => options[i].label);
return labels.length > 0 ? labels.join(", ") : response;
}

// Tampilkan pertanyaan Claude dan kumpulkan jawaban pengguna
async function handleAskUserQuestion(input: any) {
const answers: Record<string, string> = {};

for (const q of input.questions) {
console.log(`\n${q.header}: ${q.question}`);

const options = q.options;
options.forEach((opt: any, i: number) => {
console.log(`  ${i + 1}. ${opt.label} - ${opt.description}`);
});
if (q.multiSelect) {
console.log("  (Enter numbers separated by commas, or type your own answer)");
} else {
console.log("  (Enter a number, or type your own answer)");
}

const response = (await prompt("Your choice: ")).trim();
answers[q.question] = parseResponse(response, options);
}

// Kembalikan jawaban ke Claude (harus menyertakan pertanyaan asli)
return {
behavior: "allow",
updatedInput: { questions: input.questions, answers }
};
}

async function main() {
for await (const message of query({
prompt: "Help me decide on the tech stack for a new mobile app",
options: {
canUseTool: async (toolName, input) => {
// Arahkan AskUserQuestion ke handler pertanyaan kami
if (toolName === "AskUserQuestion") {
return handleAskUserQuestion(input);
}
// Setujui secara otomatis alat lain untuk contoh ini
return { behavior: "allow", updatedInput: input };
}
}
})) {
if ("result" in message) console.log(message.result);
}
}

main();

Keterbatasan

Subagents: AskUserQuestion saat ini tidak tersedia di subagents yang dihasilkan melalui alat Agent
Batas pertanyaan: setiap panggilan AskUserQuestion mendukung 1-4 pertanyaan dengan 2-4 opsi masing-masing

Cara lain untuk mendapatkan input pengguna

Callback canUseTool 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

Input streaming ideal untuk UI percakapan di mana pengguna berinteraksi dengan agen sepanjang eksekusi, bukan hanya di titik persetujuan.

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

Alat kustom memberi Anda kontrol penuh atas interaksi, tetapi memerlukan lebih banyak pekerjaan implementasi daripada menggunakan callback canUseTool bawaan.

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

agent-sdk/user-input.md +44 −16

16 16

17Panduan ini menunjukkan cara mendeteksi setiap jenis permintaan dan merespons dengan tepat.17Panduan ini menunjukkan cara mendeteksi setiap jenis permintaan dan merespons dengan tepat.

18 18

~~19## Deteksi ketika Claude membutuhkan input~~19<h2 id="detect-when-claude-needs-input">

20 Deteksi ketika Claude membutuhkan input

21</h2>

20 22

21Berikan callback `canUseTool` dalam opsi kueri Anda. Callback dipicu setiap kali Claude membutuhkan input pengguna, menerima nama alat dan input sebagai argumen:23Berikan callback `canUseTool` dalam opsi kueri Anda. Callback dipicu setiap kali Claude membutuhkan input pengguna, menerima nama alat dan input sebagai argumen:

22 24

49 Untuk secara otomatis mengizinkan atau menolak alat tanpa meminta pengguna, gunakan [hooks](/id/agent-sdk/hooks) sebagai gantinya. Hooks dijalankan sebelum `canUseTool` dan dapat mengizinkan, menolak, atau memodifikasi permintaan berdasarkan logika Anda sendiri. Anda juga dapat menggunakan [hook `PermissionRequest`](/id/agent-sdk/hooks#available-hooks) untuk mengirim notifikasi eksternal (Slack, email, push) ketika Claude menunggu persetujuan.51 Untuk secara otomatis mengizinkan atau menolak alat tanpa meminta pengguna, gunakan [hooks](/id/agent-sdk/hooks) sebagai gantinya. Hooks dijalankan sebelum `canUseTool` dan dapat mengizinkan, menolak, atau memodifikasi permintaan berdasarkan logika Anda sendiri. Anda juga dapat menggunakan [hook `PermissionRequest`](/id/agent-sdk/hooks#available-hooks) untuk mengirim notifikasi eksternal (Slack, email, push) ketika Claude menunggu persetujuan.

50</Note>52</Note>

51 53

~~52## Menangani permintaan persetujuan alat~~54<h2 id="handle-tool-approval-requests">

55 Menangani permintaan persetujuan alat

56</h2>

53 57

54Setelah Anda melewatkan callback `canUseTool` dalam opsi kueri Anda, callback dipicu ketika Claude ingin menggunakan alat yang tidak disetujui secara otomatis. Callback Anda menerima tiga argumen:58Setelah Anda melewatkan callback `canUseTool` dalam opsi kueri Anda, callback dipicu ketika Claude ingin menggunakan alat yang tidak disetujui secara otomatis. Callback Anda menerima tiga argumen:

55 59

197 201

198Contoh 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](#respond-to-tool-requests) untuk semua cara Anda dapat merespons.202Contoh 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](#respond-to-tool-requests) untuk semua cara Anda dapat merespons.

199 203

200### Merespons permintaan alat204<h3 id="respond-to-tool-requests">

205 Merespons permintaan alat

206</h3>

201 207

202Callback Anda mengembalikan salah satu dari dua jenis respons:208Callback Anda mengembalikan salah satu dari dua jenis respons:

203 209

407 </Tab>413 </Tab>

408</Tabs>414</Tabs>

409 415

410## Menangani pertanyaan klarifikasi416<h2 id="handle-clarifying-questions">

417 Menangani pertanyaan klarifikasi

418</h2>

411 419

412Ketika Claude membutuhkan lebih banyak arahan tentang tugas dengan beberapa pendekatan yang valid, Claude memanggil alat `AskUserQuestion`. 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.420Ketika Claude membutuhkan lebih banyak arahan tentang tugas dengan beberapa pendekatan yang valid, Claude memanggil alat `AskUserQuestion`. 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.

413 421

551 </Step>559 </Step>

552</Steps>560</Steps>

553 561

554### Format pertanyaan562<h3 id="question-format">

563 Format pertanyaan

564</h3>

555 565

556Input berisi pertanyaan yang dihasilkan Claude dalam array `questions`. Setiap pertanyaan memiliki bidang-bidang ini:566Input berisi pertanyaan yang dihasilkan Claude dalam array `questions`. Setiap pertanyaan memiliki bidang-bidang ini:

557 567

558| Bidang | Deskripsi |568| Bidang | Deskripsi |

559| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |569| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |

562| `options` | Array 2-4 pilihan, masing-masing dengan `label` dan `description`. TypeScript: secara opsional `preview` (lihat [di bawah](#option-previews-type-script)) |572| `options` | Array 2-4 pilihan, masing-masing dengan `label` dan `description`. TypeScript: secara opsional `preview` (lihat [di bawah](#option-previews-typescript)) |

564 574

565Struktur yang diterima callback Anda:575Struktur yang diterima callback Anda:

580}590}

581```591```

582 592

583#### Pratinjau opsi (TypeScript)593<h4 id="option-previews-typescript">

594 Pratinjau opsi (TypeScript)

595</h4>

584 596

585`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.597`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.

586 598

621}633}

622```634```

623 635

624### Format respons636<h3 id="response-format">

637 Format respons

638</h3>

625 639

626Kembalikan objek `answers` yang memetakan bidang `question` setiap pertanyaan ke `label` opsi yang dipilih:640Kembalikan objek `answers` yang memetakan bidang `question` setiap pertanyaan ke `label` opsi yang dipilih:

627 641

645}659}

646```660```

647 661

648#### Dukung input teks bebas662<h4 id="support-free-text-input">

663 Dukung input teks bebas

664</h4>

649 665

650Opsi yang telah ditentukan Claude tidak akan selalu mencakup apa yang diinginkan pengguna. Untuk memungkinkan pengguna mengetik jawaban mereka sendiri:666Opsi yang telah ditentukan Claude tidak akan selalu mencakup apa yang diinginkan pengguna. Untuk memungkinkan pengguna mengetik jawaban mereka sendiri:

651 667

654 670

655Lihat [contoh lengkap](#complete-example) di bawah untuk implementasi lengkap.671Lihat [contoh lengkap](#complete-example) di bawah untuk implementasi lengkap.

656 672

657### Contoh lengkap673<h3 id="complete-example">

674 Contoh lengkap

675</h3>

658 676

659Claude 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.677Claude 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.

660 678

821 ```839 ```

822</CodeGroup>840</CodeGroup>

823 841

824## Keterbatasan842<h2 id="limitations">

843 Keterbatasan

844</h2>

825 845

826* **Subagents**: `AskUserQuestion` saat ini tidak tersedia di subagents yang dihasilkan melalui alat Agent846* **Subagents**: `AskUserQuestion` saat ini tidak tersedia di subagents yang dihasilkan melalui alat Agent

827* **Batas pertanyaan**: setiap panggilan `AskUserQuestion` mendukung 1-4 pertanyaan dengan 2-4 opsi masing-masing847* **Batas pertanyaan**: setiap panggilan `AskUserQuestion` mendukung 1-4 pertanyaan dengan 2-4 opsi masing-masing

828 848

829## Cara lain untuk mendapatkan input pengguna849<h2 id="other-ways-to-get-user-input">

850 Cara lain untuk mendapatkan input pengguna

851</h2>

830 852

831Callback `canUseTool` dan alat `AskUserQuestion` mencakup sebagian besar skenario persetujuan dan klarifikasi, tetapi SDK menawarkan cara lain untuk mendapatkan input dari pengguna:853Callback `canUseTool` dan alat `AskUserQuestion` mencakup sebagian besar skenario persetujuan dan klarifikasi, tetapi SDK menawarkan cara lain untuk mendapatkan input dari pengguna:

832 854

833### Input streaming855<h3 id="streaming-input">

856 Input streaming

857</h3>

834 858

835Gunakan [input streaming](/id/agent-sdk/streaming-vs-single-mode) ketika Anda perlu:859Gunakan [input streaming](/id/agent-sdk/streaming-vs-single-mode) ketika Anda perlu:

836 860

840 864

841Input streaming ideal untuk UI percakapan di mana pengguna berinteraksi dengan agen sepanjang eksekusi, bukan hanya di titik persetujuan.865Input streaming ideal untuk UI percakapan di mana pengguna berinteraksi dengan agen sepanjang eksekusi, bukan hanya di titik persetujuan.

842 866

843### Alat kustom867<h3 id="custom-tools">

868 Alat kustom

869</h3>

844 870

845Gunakan [alat kustom](/id/agent-sdk/custom-tools) ketika Anda perlu:871Gunakan [alat kustom](/id/agent-sdk/custom-tools) ketika Anda perlu:

846 872

850 876

851Alat kustom memberi Anda kontrol penuh atas interaksi, tetapi memerlukan lebih banyak pekerjaan implementasi daripada menggunakan callback `canUseTool` bawaan.877Alat kustom memberi Anda kontrol penuh atas interaksi, tetapi memerlukan lebih banyak pekerjaan implementasi daripada menggunakan callback `canUseTool` bawaan.

852 878

853## Sumber daya terkait879<h2 id="related-resources">

880 Sumber daya terkait

881</h2>

854 882

855* [Konfigurasi izin](/id/agent-sdk/permissions): atur mode dan aturan izin883* [Konfigurasi izin](/id/agent-sdk/permissions): atur mode dan aturan izin

856* [Kontrol eksekusi dengan hooks](/id/agent-sdk/hooks): jalankan kode kustom di titik-titik kunci dalam siklus hidup agen884* [Kontrol eksekusi dengan hooks](/id/agent-sdk/hooks): jalankan kode kustom di titik-titik kunci dalam siklus hidup agen

agent-sdk/user-input.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

Menangani persetujuan dan input pengguna

Deteksi ketika Claude membutuhkan input

Menangani permintaan persetujuan alat

Merespons permintaan alat

Menangani pertanyaan klarifikasi

Berikan callback canUseTool

Deteksi AskUserQuestion

Analisis input pertanyaan

Kumpulkan jawaban dari pengguna

Kembalikan jawaban ke Claude

Format pertanyaan

Pratinjau opsi (TypeScript)

Format respons

Dukung input teks bebas

Contoh lengkap

Keterbatasan

Cara lain untuk mendapatkan input pengguna

Input streaming

Alat kustom

Sumber daya terkait