| name | compose:ask |
| description | Use whenever you need a decision, clarification, or approval from the user — covers how to ask with the question tool, and how to resolve the decision yourself when no user is available (question tool absent, or a [Never-Ask] response) |
Asking the User
The Rule
Every time you need the user to decide, clarify, or approve something, route it through the question tool. Never stop the loop with a natural-language question ("Does this look right?", "Should I proceed?", "Which would you prefer?"). A natural-language question ends your turn without finishing the task; a question tool call does not.
This means: the loop only ends when the task is actually complete — never because you paused to ask in prose.
How to Ask
- Structured options — when the decision has known choices, list them as
options (each with a short label and a description).
- Open-ended — when you can't enumerate good options, pass empty
options. An empty options list renders as a free-text prompt: the user types whatever they want. So anything you'd normally ask in prose can be asked through question instead.
- One question per concern — don't bundle unrelated decisions; ask them as separate questions (or separate calls).
- Don't repeat the question in prose — the tool already renders it. Just call the tool.
question({
questions: [{
question: "Which auth strategy should I use?",
header: "Auth",
options: [
{ label: "Session cookies", description: "Server-side sessions, simplest" },
{ label: "JWT", description: "Stateless, good for multiple services" },
],
}],
})
When No User Is Available
