Skip to documentation
Anywe

Request an approved action

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

  1. Invoke

    tools/invoke

  2. Evaluate

    policy engine

  3. Decide

    3 outcomes

  4. Resolve

    a human

  5. tool.result

    delivery

  6. 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

  1. 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 and permissions reference define the security boundary; this guide sequences the call, it does not replace them.

  2. 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 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 block instead.

Wait for the result

  1. 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.

  2. 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

Next steps