# Asks and answers

> An ask waits for a person. The kinds of ask, what a decision means, who may answer, and what happens when nobody does.

An ask is a [message](/docs/concepts/messages) with an `ask` field: the agent stops and waits for a person's decision.
`ask.type` says how the question is shown; the answer's `resolution.decision` says what it means.

## Kinds of ask

| `ask.type` | You see | The answer |
|---|---|---|
| `confirm` | Approve and Reject, or up to 4 buttons of your own, each meaning approve or reject | `decision`: `approve` or `reject` |
| `choice` | 2 to 12 options; `multiple: true` lets you pick several, `allow_other` lets you type your own | `decision: respond`, with `option` or `options` |
| `multi` | 2 to 12 options to tick, between `min` and `max` of them | `decision: respond`, with `options` |
| `text` | A text field, with optional `suggestions` | `decision: respond`, with `text` |
| `form` | Up to 10 fields: text, numbers, yes or no, one or several of a list, a date | `decision: respond`, with `values` |

A two-button confirm is answered right from the notification, on the Lock Screen; anything richer opens Kabu. Any ask
can let you decline instead (`decision: reject`), and `allow_comment` adds a note to the answer.

```json
{
  "title": "Run the production migration?",
  "body": "Adds `orders.archived_at`. About a 3 s lock.",
  "action": { "name": "db.migrate", "args": { "version": 42, "env": "prod" } },
  "ask": { "type": "confirm", "irreversible": true }
}
```

`action` says what will run if you approve, and Kabu shows it with the question. With `allow_edit`, you may change
its arguments: the decision is then `edit`, with the arguments you approved in `edited_args`.

## Decisions

Branch on `resolution.decision`, never on the button's label:

| `decision` | Means |
|---|---|
| `approve` | Do exactly what was asked |
| `reject` | Do not, or the person declined to answer; `comment` may say why |
| `edit` | Do it, with `edited_args` instead of the proposed arguments |
| `respond` | The answer is the value: `option`, `options`, `text` or `values` |
| `ignore` | Skip this step: only when an option offered it |

A decision you do not recognise is never approval. The resolution also records who answered (`responded_by`), where
(`via`: the Lock Screen, the app, the web) and how sure Kabu is it was them (`assurance`), and carries
a signed [receipt](/docs/concepts/receipts).

## Waiting, and expiry

An ask waits until it is answered, cancelled or expires (`expires_in`, an hour unless you say; from a minute to 30
days). Wait for it with `?wait=` on `POST /v2/messages` and `GET /v2/messages/{message_id}`, or with `kabu ask`,
which waits as long as it takes.

Expiry never approves anything. Unanswered, an ask ends `expired` with no decision, unless it set
`ask.on_expire` to a safe default (`reject`, `respond` with a value, or `ignore`), which Kabu then applies and marks as
the system's. An agent cannot schedule its own approval.

## Irreversible asks

`irreversible: true` is for the steps you cannot take back: approving needs your phone unlocked, and the ask is
never settled by its expiry (`on_expire` is refused). Use it for production deploys, migrations and deletions.

## Who may answer

The people it was sent to (`to`), from the Kabu app and its notifications, or the link Kabu sends
them. With several recipients, the first answer settles the ask and the others' notifications are withdrawn. A
service of yours can answer on a person's behalf with a key holding `answers:delegate`.

The key that asked never can: any key that may send messages is refused with `403`
[`self_response_forbidden`](/docs/errors/self_response_forbidden), so an agent cannot approve its own request. An
answer to a settled ask is `409` [`already_settled`](/docs/errors/already_settled); one after the deadline, `410`
[`ask_expired`](/docs/errors/ask_expired).