AskUserQuestion 工具)時。兩者都會觸發您的 canUseTool 回呼,該回呼會暫停執行,直到您返回回應。這與普通對話輪次不同,在普通對話輪次中 Claude 完成後會等待您的下一條訊息。
對於澄清問題,Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中;如果您需要自己詢問使用者某些事項,請在應用程式邏輯中單獨進行。
回呼可以無限期地保持待處理狀態。執行保持暫停狀態,直到您的回呼返回,SDK 只在查詢本身被取消時才取消等待。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應,請返回 defer hook 決定,它允許流程退出並稍後從持久化會話恢復。
本指南向您展示如何檢測每種類型的請求並做出適當的回應。
檢測 Claude 何時需要輸入
在您的查詢選項中傳遞canUseTool 回呼。每當 Claude 需要使用者輸入時,回呼就會觸發,接收工具名稱和輸入作為參數:
- 工具需要批准:Claude 想要使用未被權限規則或模式自動批准的工具。檢查
tool_name以查看工具(例如"Bash"、"Write")。 - Claude 提出問題:Claude 呼叫
AskUserQuestion工具。檢查tool_name == "AskUserQuestion"以不同方式處理它。如果您指定tools陣列,請包含AskUserQuestion以使其正常工作。有關詳細資訊,請參閱處理澄清問題。
要自動允許或拒絕工具而不提示使用者,請改用 hooks。Hooks 在
canUseTool 之前執行,可以根據您自己的邏輯允許、拒絕或修改請求。您也可以使用 PermissionRequest hook 在 Claude 等待批准時發送外部通知(Slack、電子郵件、推送)。處理工具批准請求
一旦您在查詢選項中傳遞了canUseTool 回呼,當 Claude 想要使用未自動批准的工具時,它就會觸發。您的回呼接收三個參數:
| 參數 | 描述 |
|---|---|
toolName | Claude 想要使用的工具名稱(例如 "Bash"、"Write"、"Edit") |
input | Claude 傳遞給工具的參數。內容因工具而異。 |
options (TS) / context (Python) | 其他上下文,包括可選的 suggestions(建議的 PermissionUpdate 條目以避免重新提示)和取消信號。在 TypeScript 中,signal 是 AbortSignal;在 Python 中,信號欄位保留供將來使用。有關 Python,請參閱 ToolPermissionContext。 |
input 物件包含工具特定的參數。常見範例:
| 工具 | 輸入欄位 |
|---|---|
Bash | command、description、timeout |
Write | file_path、content |
Edit | file_path、old_string、new_string |
Read | file_path、offset、limit |
在 Python 中,
can_use_tool 需要串流模式和返回 {"continue_": True} 的 PreToolUse hook 以保持流開放。沒有此 hook,流會在權限回呼可以被調用之前關閉。y 以外的任何輸入都被視為拒絕。在實踐中,您可能會構建一個更豐富的 UI,讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式,請參閱回應工具請求。
回應工具請求
您的回呼返回以下兩種回應類型之一:| 回應 | Python | TypeScript |
|---|---|---|
| 允許 | PermissionResultAllow(updated_input=...) | { behavior: "allow", updatedInput } |
| 拒絕 | PermissionResultDeny(message=...) | { behavior: "deny", message } |
- 批准:讓工具按 Claude 要求執行
- 批准並進行更改:在執行前修改輸入(例如清理路徑、添加約束)
- 批准並記住:回應建議的權限規則,以便匹配的呼叫在下次跳過提示
- 拒絕:阻止工具並告訴 Claude 原因
- 建議替代方案:阻止但引導 Claude 朝著使用者想要的方向發展
- 完全重定向:使用串流輸入向 Claude 發送全新指令
- 批准
- 批准並進行更改
- 批准並記住
- 拒絕
- 建議替代方案
- 完全重定向
使用者按原樣批准該操作。傳遞回呼中的
input 不變,工具完全按 Claude 要求執行。處理澄清問題
當 Claude 需要在具有多個有效方法的任務上獲得更多方向時,它會呼叫AskUserQuestion 工具。這會使用 toolName 設定為 AskUserQuestion 的方式觸發您的 canUseTool 回呼。輸入包含 Claude 的問題作為多選選項,您將其顯示給使用者並返回他們的選擇。
以下步驟顯示如何處理澄清問題:
傳遞 canUseTool 回呼
在您的查詢選項中傳遞
canUseTool 回呼。預設情況下,AskUserQuestion 可用。如果您指定 tools 陣列來限制 Claude 的功能(例如,只有 Read、Glob 和 Grep 的唯讀代理),請在該陣列中包含 AskUserQuestion。否則,Claude 將無法提出澄清問題:解析問題輸入
輸入在 有關完整欄位描述,請參閱問題格式。
questions 陣列中包含 Claude 的問題。每個問題都有 question(要顯示的文字)、options(選擇)和 multiSelect(是否允許多個選擇):將答案返回給 Claude
將
對於多選問題,傳遞標籤陣列或使用
answers 物件構建為記錄,其中每個鍵是 question 文字,每個值是所選選項的 label:| 來自問題物件 | 用作 |
|---|---|
question 欄位(例如 "How should I format the output?") | 鍵 |
所選選項的 label 欄位(例如 "Summary") | 值 |
", " 連接它們。如果您支援自由文字輸入,請使用使用者的自訂文字作為值。問題格式
輸入在questions 陣列中包含 Claude 生成的問題。每個問題都有這些欄位:
| 欄位 | 描述 |
|---|---|
question | 要顯示的完整問題文字 |
header | 問題的簡短標籤(最多 12 個字元) |
options | 2-4 個選擇的陣列,每個都有 label 和 description。TypeScript:可選 preview(請參閱下方) |
multiSelect | 如果為 true,使用者可以選擇多個選項 |
選項預覽 (TypeScript)
toolConfig.askUserQuestion.previewFormat 為每個選項添加 preview 欄位,以便您的應用程式可以在標籤旁邊顯示視覺模型。沒有此設定,Claude 不會生成預覽,該欄位不存在。
previewFormat | preview 包含 |
|---|---|
| 未設定(預設) | 欄位不存在。Claude 不會生成預覽。 |
"markdown" | ASCII 藝術和圍欄程式碼區塊 |
"html" | 樣式的 <div> 片段(SDK 在您的回呼執行前拒絕 <script>、<style> 和 <!DOCTYPE>) |
preview(佈局選擇、配色方案),並在不會的地方省略它(是/否確認、純文字選擇)。在呈現前檢查 undefined。
回應格式
返回answers 物件,將每個問題的 question 欄位對應到所選選項的 label:
| 欄位 | 描述 |
|---|---|
questions | 傳遞原始問題陣列(工具處理所需) |
answers | 物件,其中鍵是問題文字,值是所選標籤 |
response | 可選的自由形式回覆,使用者輸入的內容,而不是回答結構化問題 |
", " 連接它們。對於每個問題的自由文字,例如「其他」選項,將使用者的文字放在 answers[question] 中,如支援自由文字輸入中所示。僅當您的 UI 讓使用者關閉問題卡並輸入不是任何特定問題答案的一般回覆時,才設定 response。當設定 response 時,Claude 會收到「使用者回應:…」而不是每個問題的答案清單。
支援自由文字輸入
Claude 的預定義選項不會總是涵蓋使用者想要的內容。要讓使用者輸入自己的答案:- 在 Claude 的選項後顯示額外的「其他」選擇,接受文字輸入
- 使用使用者的自訂文字作為答案值(不是「其他」一詞)
完整範例
當 Claude 需要使用者輸入以繼續時,它會提出澄清問題。例如,當被要求幫助決定行動應用程式的技術堆棧時,Claude 可能會詢問跨平台與原生、後端偏好或目標平台。這些問題幫助 Claude 做出與使用者偏好相符的決定,而不是猜測。 此範例在終端機應用程式中處理這些問題。以下是每個步驟發生的情況:- 路由請求:
canUseTool回呼檢查工具名稱是否為"AskUserQuestion"並路由到專用處理程式 - 顯示問題:處理程式循環遍歷
questions陣列並列印每個問題及編號選項 - 收集輸入:使用者可以輸入數字以選擇選項,或直接輸入自由文字(例如「jquery」、「i don’t know」)
- 對應答案:程式碼檢查輸入是否為數字(使用選項的標籤)或自由文字(直接使用文字)
- 返回給 Claude:回應包括原始
questions陣列和answers對應
限制
- 子代理:
AskUserQuestion目前在透過 Agent 工具生成的子代理中不可用 - 問題限制:每個
AskUserQuestion呼叫支援 1-4 個問題,每個 2-4 個選項
獲取使用者輸入的其他方式
canUseTool 回呼和 AskUserQuestion 工具涵蓋大多數批准和澄清情況,但 SDK 提供其他方式來從使用者獲取輸入:
串流輸入
當您需要以下情況時,使用串流輸入:- 在任務中途中斷代理:在 Claude 工作時發送取消信號或改變方向
- 提供額外上下文:添加 Claude 需要的資訊,無需等待它詢問
- 構建聊天介面:讓使用者在長時間運行的操作期間發送後續訊息
自訂工具
當您需要以下情況時,使用自訂工具:- 收集結構化輸入:構建超越
AskUserQuestion多選格式的表單、精靈或多步驟工作流程 - 整合外部批准系統:連接到現有的票務、工作流程或批准平台
- 實現特定領域的互動:創建針對您應用程式需求的工具,例如程式碼審查介面或部署檢查清單
canUseTool 回呼更多的實現工作。
相關資源
- 配置權限:設定權限模式和規則
- 使用 hooks 控制執行:在代理生命週期的關鍵點執行自訂程式碼
- TypeScript SDK 參考:完整 canUseTool API 文件