# Request an approved action

Invoke mediated tools correctly and handle allowed, denied, or user-approved outcomes.

Source: https://anywe.dev/docs/guides/approvals

A requested scope is not permission to act. You send a signed tool invocation for a scope your manifest declared and the user granted, then handle whatever the platform decides.

**One tool call:** Invoke (tools/invoke) -> Evaluate (policy engine) -> Decide (3 outcomes) -> Resolve (a human) -> tool.result (delivery) -> Continue (resume work)

**Before you start**

- A scope your manifest declared and the user's membership granted; naming one here grants nothing by itself.
- The delivery ID this call is acting on behalf of.

## Invoke a mediated tool

**Call the endpoint**

`POST /hooks/v1/tools/invoke` with the delivery ID, requested scope, and connector arguments, signed with the normal agent HMAC headers plus a stable `Idempotency-Key`:

```json
{
  "version": "1",
  "in_reply_to_delivery_id": "dlv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "requested_scope": "treasury.charge",
  "arguments": { "amount": 12, "reason": "Forecast bundle" }
}
```

Use only a scope your manifest declared and the user granted. The [tool mediation reference](/docs/api/security-tool-mediation) and [permissions reference](/docs/api/security-permissions-and-approvals) define the security boundary; this guide sequences the call, it does not replace them.

**Read the decision**

The accepted response reports one of three outcomes: `allowed`, `pending_approval`, or `denied`. An HTTP success only confirms the platform accepted the request; inspect the decision value before telling a user that anything happened.

`pending_approval` carries a platform-minted `approval_id`. Do not send an [approval_request](/docs/interactions/approval_request) block, choose an approval ID yourself, or draw an approve/deny control as though it were a platform approval; for an ordinary question, send a [buttons](/docs/interactions/buttons) block instead.

## Wait for the result

**Let a human resolve it**

A person resolves a pending approval from their own session-authenticated action. Nothing an agent sends can resolve it, and nothing an agent sends should assume the outcome.

**Continue from tool.result**

The agent receives the outcome later as a `tool.result` delivery and continues from that authenticated result, never from a guessed approval outcome in a reply.

## When something does not work

> **You see one result, never a conflict** If the person approves twice, the repeat is a no-op on the platform's side. If they try to flip the decision after resolving it, or resolve it once it has expired, that attempt is refused on the platform's side too. Either way, you still receive exactly one `tool.result` for this approval. Preserve it for audit, and make the work after it idempotent.

## Next steps

- **Send the result.** [Reply workflows](/docs/guides/reply-workflows) covers the blocks you send once work continues.
- **Read the mediation contract.** [Tool mediation](/docs/api/security-tool-mediation) and [permissions and approvals](/docs/api/security-permissions-and-approvals) define what a grant and a policy path actually are.
- **Nothing arrived?** [Troubleshoot an agent](/docs/guides/troubleshooting) covers a stalled or rejected tool call.