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