Ask User


ID	`ask_user`
Category	Core
Features	None
Dependencies	None

Gives the agent one tool for collecting decisions it cannot make on its own. Instead of guessing, or ending the turn with a paragraph of questions and hoping the user answers all of them, it asks 1–4 structured questions and waits.

The user sees a card with the questions, their options, and a short description of each option’s trade-off. Answering resumes the turn.

Enabled by default on the Generic and Platform Chat harnesses. Not on Base, which has no interactive surface.

When to enable it

Enable it for agents that work with a person: anything where the agent’s first guess about intent, scope, or preference is likely to be wrong and expensive to undo.

Leave it off for agents that run unattended on a schedule or a trigger. It will not hang them — a client that cannot render a question gets the model’s declared defaults immediately, in the same turn — but an agent nobody is watching should be built to decide, not to ask.

This is the boundary worth being clear about before enabling both:

	`ask_user`	`request_approval`
For	Decisions and preferences	Permission to act
Example	”Which environment?"	"May I delete this bucket?”
No answer	Resolves to a default	Stays unresolved

ask_user auto-resolves. A question nobody answers falls back to the option the model marked as recommended. That is correct for a preference and wrong for permission, so a destructive, irreversible, or outward-facing action must go through request_approval (the soft_approval capability), whose wait does not auto-resolve.

Both are enabled together on the interactive harnesses for exactly this reason: the agent needs somewhere to put a preference so it stops putting permission questions there. The system prompt states the rule, but the capability pairing is what makes it followable.

Question kinds

Choice — 2 to 6 options, single- or multi-select, optionally with a free-text “Something else” path. Options are ordered most-applicable-first, because that is the order a fallback follows.

Secret — collects a credential. The value is stored encrypted in session storage and the agent receives a reference (session:MY_TOKEN), never the value itself, so it cannot reach the conversation history or the agent’s context. Tools resolve the reference by name. A secret question never auto-resolves: there is no such thing as a default credential, so an unanswered one is declined and proceeding without it becomes the agent’s explicit decision.

Use the secret kind rather than asking for a key in chat. A key typed into an ordinary message stays in the session history in plain text.

Tools

Tool	Description
`ask_user`	Ask 1–4 structured questions, or collect one credential, and wait for the answer.

Configuration

None. Limits are fixed by the contract:

Limit	Value
Questions per call	1–4 (a secret question must be alone)
Options per question	2–6
Timeout	300 seconds, which the agent may shorten but not extend

What the agent is told

The result says what was chosen and who chose it — a person, a timeout, or an unattended fallback. An agent that reads a fallback as a considered answer will act with more confidence than the answer deserves, so provenance travels with it.

A declined question is a finished decision. The agent must not ask it again.