Ask User

Use the ask_user tool to collect structured input from the user.

When to use ask_user

• Architectural trade-offs with high impact
• Requirements are ambiguous or conflicting
• Assumptions would materially change implementation
• User preferences needed (style, approach, priority)
• Confirming before destructive operations

Decision Handshake Flow

1. Gather evidence and summarize context
2. Ask ONE focused question via ask_user
3. Wait for explicit user choice
4. Confirm the decision, then proceed

Parameters

Parameter	Type	Default	Description
question	string	required	The question to ask
context	string?	—	Additional context shown before question
options	array?	[]	Multiple-choice options with labels, descriptions, values
allowMultiple	boolean?	false	Enable multi-select
allowFreeform	boolean?	true	Add "Custom response" checkable option
timeout	number?	—	Auto-dismiss after N ms

Option Properties

Property	Type	Default	Description
label	string	required	Display label
description	string?	—	Description shown below label
value	string?	label	Value returned when selected
allowCustom	boolean?	false	Allow user to add custom text for this option (shorthand for action: "input")
action	string?	"select"	Special action: "select", "input", "end_turn", "new_session"
prefill	string?	—	Prefill message for "new_session" action

Action Types

Action	Behavior
"select"	Normal selection (default). Returns immediately.
"input"	Enters text input mode. Returns combined response with selection + text.
"end_turn"	Signals end of agent turn. Returns end_turn response kind.
"new_session"	Starts a handoff. Returns new_session response kind with optional prefill. Shows a launcher overlay offering Compact & run (compact first, then queue/submit the prefill) or Run directly (queue/submit immediately). The current LLM follow-up is aborted after a successful queue or editor fallback.

Examples

Single choice:

ask_user({
  question: "Which database should we use?",
  options: [
    { label: "PostgreSQL", description: "Reliable, feature-rich" },
    { label: "SQLite", description: "Simple, serverless" }
  ]
})

Multi-select:

ask_user({
  question: "Which features to implement?",
  options: [
    { label: "Auth", value: "auth" },
    { label: "Cache", value: "cache" },
    { label: "Logging", value: "logging" }
  ],
  allowMultiple: true
})

With context:

ask_user({
  question: "Which approach?",
  context: "Current bottleneck: network I/O. Goal: reduce latency.",
  options: [
    { label: "Cache-first" },
    { label: "DB-first" }
  ]
})

Freeform only:

ask_user({
  question: "What should we name this module?",
  options: [],
  allowFreeform: true
})

Combined (multi-select + freeform):

ask_user({
  question: "Which features and what custom feature?",
  options: [
    { label: "Auth", value: "auth" },
    { label: "Cache", value: "cache" }
  ],
  allowMultiple: true,
  allowFreeform: true
})

User can check "Auth", "Cache", and "Custom response" to type additional features.

With per-option custom text:

ask_user({
  question: "Does this look right?",
  options: [
    { label: "Yes", value: "yes" },
    { label: "Partially", value: "partial", allowCustom: true },
    { label: "No", value: "no", allowCustom: true }
  ],
  allowFreeform: false
})

Selecting "Partially" or "No" enters text input so the user can explain what needs to change.

With end_turn and new_session actions:

ask_user({
  question: "How would you like to proceed?",
  options: [
    { label: "Looks good, proceed", value: "proceed" },
    { label: "I want changes", value: "changes", action: "input" },
    { label: "Done for now", value: "done", action: "end_turn" },
    { label: "Start fresh", value: "new", action: "new_session", prefill: "Let's redesign the..." }
  ],
  allowFreeform: false
})

• "Looks good" returns immediately with selection
• "I want changes" enters text input mode for the user to explain
• "Done for now" signals the agent to end its turn
• "Start fresh" opens the launcher; Compact & run or Run directly queues the prefill message automatically

Session Launcher

When a user selects a new_session option, a secondary launcher overlay appears with three choices:

Choice	Behavior
🧹 Compact & run	Starts ctx.compact() without waiting in the tool spinner, then queues/submits the prefill as a follow-up message after compaction or a short fallback timer
▶ Run directly	Queues/submits the prefill immediately as a follow-up message, without compaction
✕ Cancel	Cancels the session launch; no prefill is queued

The prefill can be a slash command (for example /unipi:work specs:...) or any non-empty message. If automatic delivery fails, ask_user places the prefill in the editor and warns the user to press Enter. This two-step flow lets the user manage context window usage before starting a new task while avoiding unnecessary LLM follow-up in the old session.