What is the AskUserQuestion tool?

The built-in tool Claude Code uses to stop mid-task and ask you a quick multiple-choice question instead of guessing. The closest thing the terminal has to a chief of staff who checks in before running the wrong way.

I told Claude Code to "clean up the old onboarding emails and rewrite them in our current voice." It didn't start rewriting. It stopped and put a small menu on the screen: Which emails count as "old"? (1) Everything before this year's rebrand. (2) Only the three in the deprecated sequence. (3) Let me list them and you pick. I picked option 3, scanned the list, told it which ones, and it went to work. It didn't burn twenty minutes rewriting the wrong nine emails, because it spent one question making sure.

That menu is the AskUserQuestion tool. It's how Claude Code asks you a question in the middle of a job instead of guessing and hoping it guessed right.

What it is

AskUserQuestion is a tool built into Claude Code. When you hand it an instruction that has more than one reasonable reading, it can pause, show you a short multiple-choice question, and wait for your answer before it touches anything. You answer with your keyboard, and it picks up exactly where it left off.

A few things worth knowing about the shape of it:

• It's small on purpose. Each pause is one to four questions, two to four options each. Every option comes with a one-line plain-English description of what choosing it means.
• One option is often marked "(Recommended)." That's Claude's own best guess, based on what it just read in your files. When you're not sure, that's the safe pick.
• There's always an "Other." If none of the options fit, you type your own answer. You're never trapped inside the menu.
• It waits for you. The job stays paused until you answer. No timer racing you into a bad choice.

You'll see it most in plan mode, where Claude investigates your request and asks what it needs to know before it writes a single plan. One limit worth noting: when Claude hands part of a job to a background helper to do heavy reading, that helper can't pop the question. Only the main session you're talking to can ask.

Why it matters

The default failure mode of every AI tool is confident wrongness. You give a slightly vague instruction, it fills the gap with an assumption, and it produces something polished and completely off. Then you spend longer fixing the wrong output than the task should have taken in the first place.

AskUserQuestion is the antidote to that, and it matters most for the person who can't read the code. A developer catches a wrong assumption by skimming the diff. You can't, and you shouldn't have to. The question is your reading glasses: Claude surfaces the fork in plain English, before any work happens, and lets you point it down the right path. A ten-second menu replaces a twenty-minute cleanup. That trade compounds across every task you hand it.

It also changes what delegation feels like. A great chief of staff asks a sharp clarifying question before charging off. A weak one guesses and apologizes later. AskUserQuestion is Claude doing the first thing, which is exactly the behavior you'd reward in a hire.

What a good answer looks like

You don't have to be technical to answer well. You just have to answer like an operator.

• When you don't know, pick Recommended and move. It's a default you can correct, not a contract. Freezing on the menu for two minutes is the only wrong play.
• Read the one-line descriptions, not just the labels. The label is the headline; the description is where the actual tradeoff lives. The whole point is that you recognize the right answer when you see it, even if you couldn't have named it cold.
• Use "Other" the second the menu misses. Your intent isn't limited to four options. Type the real answer in a sentence.
• Treat a flurry of questions as a signal about your brief. If Claude is asking five things, you under-briefed it. Bank the answers into your CLAUDE.md file so it stops asking the same ones next time.

Common mistakes

Dismissing the card as friction. The pause feels like an interruption, so the reflex is to swat it away. The pause is the feature working. It's catching the wrong turn while it's still cheap to fix.

Trying to silence it. Some people hunt for a setting to turn it off. You'd be turning off the one moment the tool admits it isn't sure, which is the moment you most want to be in the room.

Over-briefing to avoid it entirely. You don't need to anticipate every question up front. Let it ask, answer in plain English, and tighten your standing brief only for the questions that keep recurring.

Walking away mid-task. It waits for you, which is great until you've left for a meeting and the job is parked on a question. If you're stepping away, answer what's on screen first.

Do this next

Next time you hand Claude Code something with real consequences, turn on plan mode first (Shift+Tab cycles to it). Plan mode is where AskUserQuestion does its best work: Claude asks what it needs, you answer a few menus, and you approve a plan written in plain English before anything changes. Then read Claude Code tips for non-technical CEOs for the operating habits that turn the whole tool into leverage, and the pillar on why a CEO belongs in the terminal if you still want the bigger case.