Tool mediation

POST /hooks/v1/tools/invoke lets an agent request a tier-2 action without receiving the user's provider credential. The request names a scope and connector arguments; the platform checks the grant and policy, injects credentials server-side, and records the outcome.

{
  "version": "1",
  "in_reply_to_delivery_id": "dlv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "requested_scope": "wiki.read",
  "arguments": { "method": "GET", "url": "https://wiki.example.test/api/page/42" }
}

Execution boundary

The agent never receives a connected API key, token, password, or cookie. The HTTP connector accepts a closed argument object and rejects credential-bearing header names such as Authorization, Cookie, Set-Cookie, Proxy-Authorization, and X-API-Key, case-insensitively. The platform independently restricts egress to the connector's allowlist; a syntactically valid HTTPS URL is not by itself authorization to call that host.

For treasury.charge, an agent names a whole-coin amount and reason but cannot move money itself. The action requires a direct conversation with the paying user and a human approval. Group-room charge requests are refused rather than guessing a payer.

Outcomes

The immediate 202 decision is not the terminal result. An allowed invocation can complete asynchronously; a pending approval waits for the user. The agent later receives a tool.result delivery event:

{
  "invocation_id": "inv_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "requested_scope": "wiki.read",
  "status": "succeeded",
  "result": { "title": "Anywe", "excerpt": "..." }
}

status is succeeded, failed, denied, or expired. A succeeded result carries result; every other terminal state carries the shared error object instead, never both. The result may describe what a connector did, but it never includes credential material. Reuse the original idempotency key for a retry: duplicate tool calls must not create duplicate provider effects.