ask-user

Ask User — Choice Gate Pattern

How to Ask

Call the AskUserQuestion tool. It blocks until the user responds and returns the answer as a structured tool result. Do not attempt to simulate a question by writing prose — use the tool.

Tool parameters

Field	Type	Required	Notes
kind	string	✓	"single", "multi", "text", or "confirm"
prompt	string	✓	The question to show the user
choices	[]string	see below	Required for single/confirm/multi; optional for text
allow_text	bool	–	Add a free-text field to a multi question
default	string	–	Pre-selected value hint (display only)
timeout_seconds	int	–	Bound the wait. By default there is no timeout — the question waits until the user answers (or the turn is aborted). Set a positive value to auto-cancel after N seconds

Kind semantics

Kind	Widget	Choices	Result fields used
single	Radio buttons	2-4 required	selected[0]
confirm	Radio buttons	Exactly 2 required (Yes/No)	selected[0]
multi	Checkboxes (+ optional text)	≥1 required	selected[], text
text	Text area	Optional hint choices ignored	text

Cancelled result

If the user clicks Skip/Cancel (or an explicit timeout_seconds you set elapses), cancelled: true is set in the result. Fall back to the safest default and note what was assumed. With no timeout_seconds the question simply waits for the user — it is not auto-cancelled on a timer.

---

Editorial policy

Infer before asking

Before calling AskUserQuestion, run these checks:

1. Scan conversation history — did the user already answer this implicitly?
2. Check stated preferences — does a loaded skill supply a default?
3. Estimate cost of a wrong default — if low, pick the safest default and note it.

Only gate when the three checks leave the answer genuinely ambiguous.

Constraints

Check	Requirement
Option count	2–4 choices max. More than 4 creates decision paralysis.
Labels	Self-explanatory labels. Action verb + brief qualifier, not "Option 1".
Escape hatch	Always include an escape hatch (e.g. "Skip" or "Cancel") as the last choice.
Question scope	One AskUserQuestion call per turn. Never stack multiple calls sequentially before reading results.
Safety ordering	Safest/reversible option first for destructive ops.
Blocking order	Ask the most blocking question first when multiple unknowns exist.

How to gate (CRITICAL)

After calling AskUserQuestion, the tool blocks — the LLM turn does not end until the user answers. Do not speculatively continue planning inside the same turn while waiting. Read the tool result, acknowledge briefly, then branch.

If the result has cancelled: true, fall back to the safest default and continue with a note about the assumption.

Non-blocking exception

If the gate blocks only one branch of a parallelizable plan and unrelated independent work exists, you MAY call other tools for that unrelated work before calling AskUserQuestion for the blocked branch, and state what you are doing in parallel.

---

Example calls

Single choice

AskUserQuestion({
  "kind": "single",
  "prompt": "Which branch should I target?",
  "choices": ["main", "develop", "feature/my-branch", "Skip — I'll tell you later"]
})

Confirmation

AskUserQuestion({
  "kind": "confirm",
  "prompt": "This will delete 47 files. Proceed?",
  "choices": ["No, cancel", "Yes, delete them"]
})

Multi-select

AskUserQuestion({
  "kind": "multi",
  "prompt": "Which test suites should I run?",
  "choices": ["unit", "integration", "e2e", "lint"],
  "allow_text": false
})

Free text

AskUserQuestion({
  "kind": "text",
  "prompt": "What should I name the new branch?"
})