# Security: Tool mediation

How mediated tools preserve credential boundaries and report asynchronous outcomes.

Source: https://anywe.dev/docs/api/security-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.

```json
{
  "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:

```json
{
  "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.

> **Mediation is not an arbitrary proxy** Do not treat the tool endpoint as a way to relay unbounded URLs, headers, or secrets. The request schema and execution policy intentionally refuse those capabilities.