---
name: asking-for-approval
description: Use before any action that sends, spends, deletes or changes something on a person's behalf (sending email or messages, payments, deleting files or data, changing settings, deploying) when the VariantGate tools `request_approval` and `check_approval` are available. Asks a person first, acts only on an explicit yes, and reports what it did.
---

# Asking for approval

A person has put VariantGate between you and risky actions. Before one, you ask; they answer in their inbox; you act only if the answer is yes.

## The rule

**Act only when `allowed` is `true`.** `pending`, `denied`, `expired` and `withdrawn` all mean do not act. Never treat silence, a timeout or an error as a yes.

## When to ask

Ask before anything that is hard to undo or that reaches outside the conversation:

- sending an email, message or post
- spending money or creating a charge
- deleting or overwriting files, records or branches
- changing settings, permissions or infrastructure

Reading, searching and drafting do not need approval. If you are unsure whether an action is risky, ask.

## How

1. **Ask.** Call `request_approval` with:
   - `agent`: your name, the same every time, so the person recognises you
   - `action`: a short machine-friendly name, such as `email.send` or `files.delete`
   - `summary`: one plain sentence saying exactly what will happen, written for the person deciding. Include the amount, the recipient or the number of things affected.
   - `details` (optional): an object with the supporting facts, such as the full email text or the list of files. See "Writing details" below.
   - `amount` and `currency` (when money moves): the exact amount as a number, such as `129.00`, and its three-letter code, such as `EUR`. The workspace may have rules with a limit; they go by these fields, not by the summary. Then spend no more than `approved_amount`.
   - `ttl_seconds` (optional): how long the request stays open, 10 seconds to 7 days. The default is 15 minutes.

   Keep the returned `id`. A standing rule may answer at once; then skip to step 3.

2. **Wait.** Call `check_approval` with that `id`. It waits up to 30 seconds for the person and answers as soon as they decide. Call it again while `status` is still `pending`. Every answer starts with a line saying what you may do now; follow it.

   If the plan changes while you wait, or the user no longer wants it, call `withdraw_request` with the `id`. The action must then not happen.

3. **Follow the answer.**
   - `allowed: true`: do exactly what was approved, nothing more: `approved_summary`, for at most `approved_amount`.
   - `changed: true`: the person approved a narrower version than you asked: new wording, a lower amount, or both. Do only that version. Never fall back to your original `summary` or `amount`. If the approved version cannot be done, do not act; report `failed` with the reason.
   - `denied`: do not act. Read `decision_note` if there is one, tell the user what was denied, and stop or change the plan.
   - `paused: true`: a person has paused you or every agent in the workspace. Do not act, even on an earlier approval. Tell the user and wait.
   - `expired`: nobody answered in time. Do not act. Tell the user and ask whether to request again.

4. **Report.** After acting on an approval, call `report_outcome` with the `id`, `outcome` (`succeeded` or `failed`) and a short `note` such as the message id or the error. The person sees it on the record. Report a failure too: an approval that was not carried out is worth knowing about.

## What a good request looks like

| Weak | Strong |
|---|---|
| "Send email" | "Send the March invoice (€1,240.00) to billing@acme.example" |
| "Clean up files" | "Delete 214 files in /exports/2024, 1.8 GB in total" |
| "Make a payment" | "Pay €129.00 to Hetzner for the server renewal" |

One request covers one action. If the plan changes after approval — a different recipient, a larger amount, more files — ask again. An approval with changes is the person's answer, not an invitation to ask for the original again.

## Writing details

The person sees `details` exactly as you send them, so send the real thing, not a description of it:

- **Message text** goes whole in a field such as `body`. Line breaks are kept.
- **A code change** goes in `diff` as a unified diff (`git diff` output); it is shown with added and removed lines marked.
- **SQL** goes in `sql`, and **a shell command** in `command`. Fields named like code (`sql`, `query`, `command`, `script`, `json`, `yaml`, `raw_sql`, …) are shown in a fixed-width font.
- **Items**, such as order lines or files, go in a list of objects with the same keys, such as `[{"item": "Desk lamp", "qty": 1, "price": "109.00"}]`. With up to five keys and short values, they are shown as a table.
- **Links** are shown as the full address, never as words you choose, and only `http` and `https` addresses are linked.

Everything is shown as plain text: HTML and markdown are not interpreted. The whole request is limited to 64 KB; for something larger, send the first part and say how much is left out.

## What you cannot do

You cannot approve your own request, read the inbox or change a decision. A decision is final. Do not look for another way to do something that was denied.

## If the tools fail

If a VariantGate tool returns an error or cannot be reached, you have no approval. Do not act; tell the user what failed. An `action_out_of_scope` error means your key may not ask for this action at all: do not ask again or try another way, and tell the user which action was refused.
