Claude Code Ask User Question Tool: How to Use It Well

If you searched for the Claude Code Ask User Question tool, you probably want Claude to pause and ask what you mean before it starts building. The built-in tool is called AskUserQuestion, and it presents structured questions with selectable answers. You can also provide your own response when the suggested choices miss what you need.

The useful part is deciding where a question belongs. Asking about an important product rule can prevent the wrong implementation, while asking about every minor detail can make a simple task drag. This guide explains how to request the tool, build a focused interview, and troubleshoot situations where the question interface does not behave as expected.

Quick Answer

What Does the Claude Code Ask User Question Tool Do?

The documented question interface lets you select an option or enter custom text through the Other row or notes field. Its purpose is to clarify a decision, such as how a feature should behave. Choosing an answer does not automatically validate the resulting code.

Imagine you ask Claude to add a booking feature. “Booking” could mean an immediately confirmed appointment, a request awaiting staff approval, or a reservation that expires unless payment arrives. Those differences affect the interface, stored data, notifications, and tests.

Use questions to settle that behavior before discussing implementation details. A technically polished booking page can still be wrong if it confirms appointments your staff expected to review.

A Useful Question Explains the Consequences

A weak question asks, “Which booking system do you want?” A stronger question names the behavior and explains what each choice means.

For a hypothetical appointment project, a question might offer:

These are illustrative product choices, not a guaranteed question generated by Claude. If your business uses a different rule, describe it instead of selecting the closest-looking option.

How to Use AskUserQuestion Before Coding

A good interview starts with context, not a long list of questions. Give Claude enough information to identify the choices that remain open, and tell it which decisions are already settled.

1. Describe the Result You Need

Start with the user’s task and the current problem. Include constraints that would make an otherwise reasonable solution unacceptable.

For example:

Add appointment rescheduling to our existing booking application. Customers should be able to move an appointment without calling staff. Keep the existing calendar integration and do not introduce a new paid service.

This leaves useful questions open while closing unnecessary ones. Claude should investigate the existing integration rather than asking you to pick a replacement calendar provider.

2. Use Plan Mode When You Want to Review the Approach First

The plan-before-editing workflow lets Claude investigate and propose an approach before changing your source files. In the terminal, you can start a session with:

claude --permission-mode plan

You can also cycle modes with Shift+Tab until the status bar shows plan mode. Check that indicator before submitting a task when you intend to review the proposed changes first.

3. Ask for Questions That Affect the Implementation

Be explicit about what deserves a question. Prioritize behavior, compatibility, data handling, and the boundaries of the task.

Use this prompt:

Inspect the relevant code and project instructions first. Use AskUserQuestion for unresolved decisions about rescheduling deadlines, staff approval, and notifications. Do not ask about choices the existing project already settles. After my answers, propose the smallest implementation that meets the requirements.

This creates a useful stopping rule for the interview. Claude has a reason to ask about an appointment deadline, but little reason to ask you to choose a formatting convention already used throughout the repository.

4. Correct Incomplete Options

An option can sound reasonable while hiding a requirement you care about. Before selecting it, check whether its description covers exceptions and existing commitments.

For instance, “allow rescheduling until the appointment” may be too broad. Your actual rule might allow changes until the previous business day, with staff handling later requests.

Write that rule in your custom answer. Then ask Claude to explain how it will interpret “business day,” including the relevant time zone and holidays.

5. Turn the Answers Into Acceptance Criteria

Before implementation, ask for a short summary of what the finished feature must do. This is where you can catch a misunderstood answer without reading a patch.

For the rescheduling example, useful criteria might include:

• Customers cannot select an unavailable slot.
• Moving an appointment releases the original slot.
• Requests after the cutoff follow the agreed staff process.
• Notifications contain the updated appointment time.
• A failed update leaves the original booking intact.

The recommended interview-and-specification workflow also suggests creating a self-contained specification before implementation. For a larger feature, that document should include scope, relevant interfaces, exclusions, and a way to verify the result.

Reusable Prompts for Common Tasks

You do not need an elaborate prompt to get useful questions. The important ingredients are the task, the unresolved decisions, and a clear point at which the interview should end.

For a New Feature

I want customers to download their order history. Inspect the existing account and order code, then use AskUserQuestion to clarify export contents, file format, and access rules. Ask one question at a time. Finish by summarizing the agreed behavior and verification steps.

This prompt focuses the interview on decisions that change the export. It also gives Claude a reason to examine existing access controls before proposing new ones.

For an Unclear Bug Report

Investigate why some customers cannot complete checkout. Read the relevant code and available error information first. Use AskUserQuestion only for missing reproduction details or expected behavior you cannot establish from the project. Separate confirmed findings from hypotheses.

For debugging, avoid choosing a proposed cause simply because it appears in a question. Describe what you observed, then require evidence before accepting a diagnosis.

For an Internal Knowledge Assistant

Help plan an employee knowledge assistant using our approved documentation. Use AskUserQuestion to clarify document ownership, access boundaries, conflicting sources, and what happens when no reliable answer exists. Summarize those decisions before recommending the architecture.

If this is your project, the guide to planning an internal knowledge assistant provides a useful starting point for source ownership and access requirements. Bring those requirements into the interview so a polished interface does not distract from the information employees may retrieve.

Where It Fits in the Claude Code Tools List

Claude Code tools support different parts of a task, from reading project files to running verification commands. Understanding those roles helps you recognize whether Claude is gathering evidence, requesting a decision, or changing something.

Here is a focused Claude Code tools list relevant to this workflow:

Your available set can vary by platform, provider, and configuration. Ask Claude what tools are loaded in the current session rather than assuming every published tool is available.

Requirements, Approval, and Permissions Are Different Decisions

A requirements question asks what you want the product to do. Plan approval asks whether the proposed approach is acceptable, while a permission prompt concerns an action Claude wants to perform.

The permission configuration documentation explains the controls for tool execution. Keep those controls separate from your product answers: choosing an export format is not a substitute for reviewing a command that deletes files.

Keep interview questions about concrete requirements. Review execution actions according to their actual effect, especially when they touch remote systems or existing data.

Using AskUserQuestion in the Agent SDK

Building your own application around Claude requires handling the questions in your interface. A terminal dialogue does not automatically become a working web form just because the underlying tool exists.

The SDK user-input documentation describes the integration:

1. Provide a canUseTool callback.
2. Detect calls whose tool name is AskUserQuestion.
3. Display the supplied questions and options.
4. Collect the user’s selections or custom response.
5. Return the original questions and an answers mapping through updatedInput.

In that mapping, question text is the key and the selected label is the answer. If you restrict the SDK’s tools array, include AskUserQuestion explicitly.

The documented format supports one to four questions per call, with two to four options per question and a multiSelect field. The SDK currently documents that this tool is unavailable in subagents spawned through Agent.

Test your interface with an ordinary selection, multiple selections, custom text, and cancellation. Decide how the application should respond when a user disconnects or supplies no answer, rather than treating an empty response as agreement.

Troubleshooting Missing or Unexpected Questions

When the question interface fails, first identify where the failure happens. Claude may never request the tool, the tool may be unavailable, or your application may fail to display or return the question.

The CLI tool-selection flags distinguish availability from permission handling. In particular, --tools restricts built-in tools, while --allowedTools controls which tools execute without permission prompts.

Changing an allowlist does not prove that your interface can collect an answer. Check the actual returned answer before letting later steps depend on it.

Check Whether a Timeout Is Configured

Questions wait for an answer by default. The askUserQuestionTimeout setting can enable automatic continuation after 60s, 5m, or 10m; this timeout does not automatically resolve permission prompts or plan approval.

For a decision you must make yourself, review that setting before leaving the session unattended. Also state that unresolved requirements should remain open rather than being recorded as confirmed choices.

Use a Small Diagnostic Prompt

A minimal question separates interface problems from a complicated project interview. Try asking Claude to use AskUserQuestion to let you choose between a brief explanation and a detailed explanation.

If that still fails, record your version, interface, launch flags, and whether you use a wrapper or SDK application. Those details make a problem report much more useful than saying the tool “does not work.”

Common Mistakes That Reduce Its Value

The biggest mistake is asking for an exhaustive interview without a stopping point. A project can always generate another question, so define the decisions that must be settled before the next stage.

Another mistake is accepting a recommended option without checking its assumptions. Ask what the recommendation depends on and whether an existing project constraint changes it.

Finally, do not confuse agreement with verification. After implementation, check that the feature follows the answers you gave, including failure cases and exclusions.

Does Asking Questions Add Cost or Time?

An interview adds conversation turns and your time answering them. Whether it reduces the overall effort depends on whether those answers prevent meaningful rework.

The usage and cost guidance explains that consumption depends on factors such as model choice, context, and workflow. Use a short interview for a narrow change and a deeper one for decisions that are expensive to reverse.

Frequently Asked Questions