Approvals
How an action that a policy holds reaches you, how you decide it, what the agent does while it waits, and how you approve a held payment from a chat app. What approvals are and what they cost is on Controls.
Two kinds of approval
- A held action: your policy says a person must decide before one action of an agent runs. This guide is mostly about these.
- An approval of a change: you, or a tool acting for you, asked for something that widens what agents may do. It is covered at the end.
Hold an action for a person
A policy holds an action in one of three ways:
{
"name": "Assistant",
"actions": { "kinds": { "card.checkout": "review" } },
"review": { "over_cents": 200 }
}
- actions.kinds set to review holds every action of that kind.
- review.over_cents holds any action that costs more than the amount.
- A rule for one connected service can hold calls to it.
- Setting these is in Policies.
What the agent sees
The held call answers 403 CONTROL_DENIED with the reason review_required and a reference:
{
"error": {
"code": "CONTROL_DENIED",
"details": {
"reason_code": "review_required",
"retry": { "ref": "crv_abc123", "after_seconds": 30 }
}
}
}
- Nothing ran and the action is not counted.
- The agent sends the very same call again later, with the reference: control_ref in a tool call, controlRef in the SDK, --control-ref in the terminal. Over the API it is the header X-Control-Ref.
- While you have not decided, the answer is review_pending. If you declined, it is review_rejected.
- Once you approve, the same call goes through. The agent has one hour to send it.
- The approval covers that exact call, once. A different call is held again.
- The agent is also woken when you decide, so it does not have to keep asking.
Decide
What is waiting for my approval?
The client calls stack_list_control_reviews and shows each held action with a link to its approval page. You decide on that page, signed in. From the terminal:
npx @getstackrun/cli reviews list
npx @getstackrun/cli reviews get crv_abc123
- Only the owner or an admin can decide.
- No tool, SDK method or command can decide for you. That is on purpose: a person decides, in a browser or in a chat app as below.
- A held action nobody decides expires after 24 hours.
- From code: stack.controlReviews.list({ status: "pending" }).
Approve a payment from Telegram, a text or Slack
A held card or wallet payment can be approved from a chat app you have linked, within limits you set. Nothing else can be approved this way.
First set both limits in the policy. Turning this on counts as loosening:
{
"name": "Assistant",
"review": {
"over_cents": 100,
"chat": { "max_per_payment_cents": 2000, "max_per_day_cents": 5000 }
}
}
Then link your chat identity:
npx @getstackrun/cli chat link telegram
npx @getstackrun/cli chat link slack
npx @getstackrun/cli chat link sms --phone +14155550123
- Telegram: open the link the command prints and press Start. Slack: send the command it prints. A text: type the six-digit code you receive into the Console.
- Then confirm the identity in the Console, signed in. Until you do, it approves nothing.
- A prompt reaches only the owner's or an admin's linked identity. It works once and for ten minutes.
- A payment over either limit is not offered in the chat. Use the approval page.
- chat list shows your linked identities. chat remove ends one.
Whoever controls that phone number or chat account can approve payments up to your limits. Keep the limits small.
Approving a change
When a call would widen what agents may do, it answers 403 GOVERNANCE_APPROVAL_REQUIRED with a link. You approve, and the same call is sent again with the approval.
- In an AI client, most of these are asked right in the chat, with every part of the change listed. You answer there.
- Some are never asked in a chat and need the approval page in a signed-in browser: loosening a policy or controls, a held action, changing your own decision server, billing, deleting the account, changing its email, single sign-on, adding an install key, and approving an intent that can move money.
- From the terminal, the command prints the link, waits for you, and carries on.
- An approval works once and lasts 24 hours.
- stack_list_approvals and stack_get_approval read them. From the terminal: approval list and approval show <id>.
When it is refused
- 403 CONTROL_DENIED, reason review_required, review_pending or review_rejected - see above.
- 403 GOVERNANCE_APPROVAL_PENDING, _REJECTED or _EXPIRED - the approval sent with the call is not usable.
- 403 on a chat link step - typing the code and confirming an identity are done in the Console, signed in.
- 409 CONTROLS_NOT_ENABLED - controls are off, so no policy can hold anything.
Reference
Writing the rules is in Policies. Whether purchases and orders wait for you at all is The trust switch.