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

# Audit

> A tamper-evident record of every decision, and how to read it after an incident.

The database logs the query. Warden logs the **intent**: which agent, on what task, at which step of what plan, for what stated reason, which rules fired, what was decided, who reviewed it, and what happened.

## Reading it

```bash theme={null}
warden audit tail                           # follow as decisions happen
curl -H "Authorization: Bearer $OK" \
  "http://127.0.0.1:9470/api/v1/audit?agent=agent:support&limit=50"
```

Filters: `agent`, `task`, `type`, `effect`, `outcome`, `limit`, and `after` for paging by sequence.

## What an event holds

| Field | Meaning |
| - | - |
| `type` | `decision`, `execution`, `pause`, `resolve`, `lease`, `breaker`, `idempotency` |
| `agent_id`, `task_id`, `step_index`, `plan_hash` | Who, and where in its plan |
| `reason` | The agent's own explanation. Untrusted text: displayed, never interpreted |
| `class`, `verb`, `statement`, `resources` | What it asked for, with parameters still bound rather than interpolated |
| `bounded` | Whether it was provably bounded |
| `effect`, `code`, `outcome` | What policy decided and what actually happened |
| `trace` | The policy rules that fired |
| `reviewer` | Who approved or rejected it |
| `records_affected`, `duration_ms` | The result |

> [!NOTE]
>
> Statements are recorded with their parameters unbound, so the log holds the *shape* of every operation without accumulating a copy of the customer data it touched.

## Tamper evidence

Each event carries a hash of the one before it. Altering or removing an event breaks the chain from that point on, and the break is detectable:

```bash theme={null}
warden audit verify
curl -H "Authorization: Bearer $OK" http://127.0.0.1:9470/api/v1/audit/verify
```

```json theme={null}
{ "intact": true, "events": 1284, "summary": "audit chain intact: 1284 events verified" }
```

A broken chain returns HTTP 409 and names the event where verification stopped.

> [!WARNING]
>
> **A broken chain refuses startup.** The gateway will not append new history on top of a chain it cannot verify, because doing so would bury whatever broke it. Investigate, keep the file as evidence, and start from a known-good copy.

This is tamper-*evident*, not tamper-proof: someone with write access to the file and the will to rewrite every subsequent hash can forge a consistent chain. Shipping events to append-only storage elsewhere is what makes that impractical, and is on the roadmap.

## What to do after an incident

1. **`warden audit verify`** — establish that what you are about to read has not been altered.
2. **Filter by agent and task** — reconstruct the sequence, including refusals. What an agent *tried* is often more informative than what it did.
3. **Look at `reason` and `trace`** — what the agent said it was doing, and which rule let it or stopped it.
4. **Check `breaker` events** — when the agent began misbehaving, and on what evidence. An automatic freeze is recorded with its trigger, and a reinstatement with the human judgement that justified it.
5. **Check `lease` events** — what access existed at the time, and when it ended.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.