> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wardin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic governance

> Extend policy enforcement and signed receipts from model calls to agent tool calls.

Wardin's enforcement point normally sits on **model calls**: a request is authenticated, policy-checked, metered, and signed into the receipt chain before it reaches a provider. Agentic governance extends that same lifecycle to **agent tool calls** — so when an agent asks to invoke a tool (file a PR, hit a database, send a message), the **governance decision on that action** gets the same tamper-evident, audit-grade record as a token spend.

<Note>
  The live MCP proxy — Wardin forwarding tool calls to upstream MCP servers — is **in development**. What ships today is the governance + evidence core: a gateway decision endpoint that authenticates the caller, resolves agent identity, enforces a tool allowlist, and writes a **signed tool-call receipt** into the same evidence chain as model calls. Scope is gateway-routed tool calls only.
</Note>

## The three pieces

### 1. Agent identity registry

An **agent** is a durable, named actor bound to one virtual key (a key can front many agents — e.g. a CI key running `pr-bot` and `deploy-bot`). Register agents in **Console → MCP / Agents**. Identity is deliberately *not* taken from an agent runner's ephemeral per-spawn headers — it comes from the registry, bound to the authenticating key, so "which agent, on whose behalf" is answerable from the signed record and cannot be forged by presenting another key's agent id.

A tool call presents its agent via the `X-Wardin-Agent-Id` header. The gateway accepts it only if it resolves to a registered agent **bound to the same key** the request authenticated with; a cross-key or cross-tenant agent id is rejected with a `403` and recorded as an `AGENT_IDENTITY: FAIL` check in the chain.

### 2. Tool allowlist policy

`tool_allowlist` is a [policy type](/concepts/policies) — which tools an agent may invoke. Patterns are globs, authored in **Console → Policies**:

```yaml theme={null}
allowed_tools:
  - github__*
  - read_file
```

Like `model_allowlist`, the gateway fail-opens on an empty list (so an empty allowlist is blocked at save time). An off-list tool is denied with a structured `403` and a signed `TOOL_ALLOWLIST: FAIL` check.

### 3. Enforcement mode

Governance follows an **observe → enforce** ramp, set per tenant in **Console → Organization → Agentic Governance**:

| Mode              | `/mcp/tool-call`         | Tool calls                                                         | Agent identity                                                             |
| ----------------- | ------------------------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| **off** (default) | disabled — returns `404` | —                                                                  | —                                                                          |
| **permissive**    | live                     | allowed, metered, signed; only an explicit `tool_allowlist` denies | a presented agent id must resolve, but is optional (falls back to the key) |
| **enforced**      | live                     | must pass a covering `tool_allowlist` (fail-closed)                | a registered `X-Wardin-Agent-Id` is **required**                           |

Mode changes are picked up by the gateway on its refresh cycle — no redeploy.

## The governance endpoint

Point a tool call at the gateway's `/mcp/tool-call` endpoint with your virtual key and (optionally) an agent id:

```bash theme={null}
curl https://gw.wardin.ai/mcp/tool-call \
  -H "Authorization: Bearer wardin_sk_..." \
  -H "X-Wardin-Agent-Id: <agent-id>" \
  -H "Content-Type: application/json" \
  -d '{"server": "github-mcp", "tool": "create_pull_request"}'
```

An allowed call returns `200 {"decision":"allow", ...}`; a denied call returns a structured `403` (`TOOL_NOT_ALLOWED`, `AGENT_REQUIRED`, or `AGENT_INVALID`). Either way a signed receipt is written.

## Signed tool-call receipts

Every governed tool call — allowed, tool-denied, or identity-denied — is chained into the **same per-tenant [receipt chain](/concepts/receipts)** as model calls, so an auditor verifies one continuous, tamper-evident chain of model *and* agent activity. Tool receipts reuse the canonical receipt fields (`provider` = the MCP server, `model` = the tool name, tokens/cost = 0) and carry the enforcement decision as signed `AGENT_IDENTITY` / `TOOL_ALLOWLIST` checks. A `kind` marker distinguishes `tool_call` from `model_call` receipts for querying, without changing the signed content — so the [offline verifier](/concepts/offline-verification) needs no special handling.

## Honest scope

Agentic governance covers **gateway-routed tool calls only** — tools an agent invokes outside the gateway are not seen. The mappings and controls here are runtime records, not a certification. The live MCP proxy (forwarding to upstream MCP servers, credential vault, and session→tools→outcome lineage) is on the roadmap; the identity, allowlist, and signed-receipt core described above is what enforces today.