ask

Ask the user a question; resume when they answer. Or leave a to-do.

When to use

Call ask when the agent needs the user to decide something, approve an action, or simply remember to do something. Use kind='bool' for yes/no, kind='choose' for multiple-choice, kind='text' for free-form input, and kind='todo' for a non-blocking reminder the agent can leave and move on from.

Example user prompts

• Ask me whether to deploy after the migration finishes.
• Ask me to choose between the two API designs.
• Leave me a to-do to smoke-test checkout before 3 PM.

MCP tool signature

ask_user(
    question: str,
    kind: Literal['bool', 'choose', 'text', 'form', 'todo'],
    project: str | None = None,
    options: list[Option] | None = None,   # for 'choose'
    schema: JsonSchema | None = None,       # for 'form'
    context_md: str | None = None,
    context_image_b64: str | None = None,
    attachments: list[ShareRef] | None = None,
    ttl_minutes: int = 60,
    allow_remark: bool = True,
    notify: Literal['push', 'email', 'none'] = 'push',
) -> AskHandle   # {decision_id, web_url, expires_at}

# Block until the user answers (optional)
await_decision(decision_id, timeout_s=600) -> Decision

# Poll without blocking
get_decision(decision_id) -> Decision

Example call

# Overnight agent asking for deploy approval
handle = ask_user(
    question='The migration finished cleanly. Deploy to production?',
    kind='bool',
    context_md='Migration ran in 4m 12s. 0 errors. Staging looks good.',
    notify='push',
)
# Agent can block here or hang up and poll later
decision = await_decision(handle['decision_id'], timeout_s=3600)

Return value

Returns an AskHandle with decision_id, web_url (the page the user opens to answer), and expires_at. After the user responds, get_decision returns a Decision with outcome, remark, and answered_at.

Credit cost

2 actions per create call.

Notes

kind='todo' returns immediately — no await_decision needed. The to-do appears in the user's feed until they mark it done, skip it, or let it expire.

Recipes

See all recipes for copy-paste patterns that use ask and other tools together.