# Useful but Little-Known Features of Claude Agent SDK 🌍 Tired of agents making decisions without asking? Guide them interactively with multiple-choice questions! The `AskUserQuestion` tool in Claude Agent SDK lets agents ask clarifying questions with predefined choices. 📌 Title: Multiple-Choice Clarifying Questions via AskUserQuestion 🔗 URL: 🧩 Overview When multiple valid approaches exist, the agent calls the `AskUserQuestion` tool to ask users for direction. Each question includes 2-4 options (with `label` + `description`), supporting both single and multi-select. Questions are handled via the `canUseTool` callback, processed in-loop without ending the query call. This is especially common in `plan` mode, where Claude explores the codebase and asks questions before proposing a plan. 🛠 How to Use ```python # Python - Handle clarifying questions in the callback from claude_agent_sdk import ClaudeAgentOptions, query from claude_agent_sdk.types import PermissionResultAllow, HookMatcher async def can_use_tool(tool_name, input_data, context): if tool_name == "AskUserQuestion": answers = {} for q in input_data.get("questions", []): print(f"\n{q['header']}: {q['question']}") for i, opt in enumerate(q["options"]): print(f" {i+1}. {opt['label']} - {opt['description']}") choice = input("Your choice: ").strip() # Answer by number or free text try: idx = int(choice) - 1 answers[q["question"]] = q["options"][idx]["label"] except (ValueError, IndexError): answers[q["question"]] = choice return PermissionResultAllow( updated_input={"questions": input_data["questions"], "answers": answers} ) return PermissionResultAllow(updated_input=input_data) ``` ```typescript // TypeScript - Handle AskUserQuestion import { query } from "@anthropic-ai/claude-agent-sdk"; for await (const message of query({ prompt: "Help me decide on a tech stack", options: { tools: ["Read", "Grep", "AskUserQuestion"], canUseTool: async (toolName, input) => { if (toolName === "AskUserQuestion") { const answers: Record = {}; for (const q of input.questions) { // Display options in UI and collect user selection answers[q.question] = selectedLabel; } return { behavior: "allow", updatedInput: { questions: input.questions, answers } }; } return { behavior: "allow", updatedInput: input }; } } })) { /* ... */ } ``` 🏗 Integration into Production Systems - In web UIs, display questions and options as modal dialogs and return user answers to the callback - When specifying a `tools` array, include `"AskUserQuestion"` or the clarifying question feature will be disabled - For `multiSelect: true` questions, return multiple answers as a comma-separated string or array - Free-text answers (beyond predefined options) can be returned directly as the value 💡 Use Cases 🎯 Let agents ask about framework and database preferences during tech stack decisions 📐 Confirm output format or architecture patterns before code generation 🔀 When multiple refactoring approaches exist, let users choose the one matching their intent ⚠️ Caveats - Each `AskUserQuestion` call supports 1-4 questions with 2-4 options each - `AskUserQuestion` is not currently available in subagents spawned via the Agent tool - The callback waits indefinitely until an answer is returned; use the `defer` hook decision if timeouts are needed ✨ The best AI assistant doesn't just guess — it asks the right questions at the right moments! #ClaudeAgentSDK# #AIAgent#