Agent Action Audit Trail

---
name: agent-action-audit-trail
description: "Append-only, hash-chained audit log for AI agents. Records agent actions, tool calls, decisions, and external writes with provenance, timestamps, and sha256 chain integrity. Designed for compliance with EU AI Act Article 12 automatic event recording requirements for high-risk AI…"
category: "AI & Agents"
author: community
version: "2.1.0"
icon: bot
---

# Agent Audit Trail

An append-only, hash-chained audit log for AI agents. Every significant action, decision, tool call, and external write is recorded with a sha256 chain linking entries together — making tampering detectable and providing an authoritative compliance record.

## Overview

This skill provides:
- **Append-only NDJSON log** at `audit/atlas-actions.ndjson`
- **Hash-chained entries** — each entry includes the sha256 of the previous entry
- **Monotonic ordering** — `ord` field ensures strict sequence
- **Structured fields** — consistent schema across all event types
- **EU AI Act Article 12** compliance implementation

## Log Location

```
audit/atlas-actions.ndjson
```

The file is append-only. Never truncate, overwrite, or reorder entries.

## Log Entry Schema

Each line is a valid JSON object:

```json
{
  "ts":         "2026-04-02T18:00:00.000+01:00",
  "kind":       "tool-call",
  "actor":      "atlas",
  "domain":     "agirails",
  "plane":      "action",
  "gate":       "external-write",
  "ord":        42,
  "provenance": "session:agent:main:discord:channel:1472016988741177520",
  "target":     "audit/atlas-actions.ndjson",
  "summary":    "Appended audit log entry",
  "prev_hash":  "sha256:abc123...",
  "hash":       "sha256:def456..."
}
```

### Field Reference

| Field | Type | Description |
|-------|------|-------------|
| `ts` | ISO-8601 | Timestamp with timezone offset (Europe/London) |
| `kind` | string | Event type (see below) |
| `actor` | string | Agent or component that triggered the event |
| `domain` | string | Domain partition (`agirails`, `client-lab`, `personal`) |
| `plane` | string | Four-plane label (`ingress`, `interpretation`, `decision`, `action`) |
| `gate` | string | Truth gate applied (see SOUL.md) |
| `ord` | integer | Monotonically increasing sequence number |
| `provenance` | string | Source session or external identity |
| `target` | string | File, URL, or resource affected |
| `summary` | string | Human-readable description of the event |
| `prev_hash` | string | sha256 of the previous log entry (hex, prefixed `sha256:`) |
| `hash` | string | sha256 of this entry excluding the `hash` field itself |

### Event Kinds

| Kind | Plane | Description |
|------|-------|-------------|
| `tool-call` | action | Any tool invocation |
| `external-write` | action | Write to external system (file, API, DB) |
| `credential-access` | action | Secret or key accessed |
| `install-extend` | action | Package install or skill activation |
| `decision` | decision | Agent decision with reasoning |
| `override` | decision | Safety override applied |
| `ingress` | ingress | External input received |
| `session-start` | ingress | Agent session initialised |
| `session-end` | ingress | Agent session terminated |
| `state-transition` | decision | Behaviour surface change |
| `payment` | action | ACTP/x402 payment event (amount, counterparty, txhash) |

## Setup

### 1. Create the audit directory

```bash
mkdir -p audit
touch audit/atlas-actions.ndjson
```

### 2. Wire into TOOLS.md

Add to your workspace `TOOLS.md`:

```markdown
## Audit Log
- Path: `audit/atlas-actions.ndjson`
- Format: append-only NDJSON, hash-chained (sha256), monotonic `ord`
- Timestamps: Europe/London ISO-8601 with offset
- Fields: ts, kind, actor, domain, plane, gate, ord, provenance, target, summary
```

### 3. Wire into SOUL.md

Add to your workspace `SOUL.md` invariants:

```
4. Append-only, hash-chained audit log with monotonic ordering
10. Behavior surface changes logged as state transitions
```

And to Truth Gates:

```
- external-write: provenance + intent + approval + tool-log + ordering
- credential-access: domain scope + justification + audit + human approval
- install-extend: integrity proof + scope + rollback ref + human approval
```

### 4. Helper script (optional)

```python
# scripts/audit_append.py
import json, hashlib, time, sys
from datetime import datetime, timezone, timedelta
from pathlib import Path

LOG = Path("audit/atlas-actions.ndjson")
TZ  = timezone(timedelta(hours=1))  # Europe/London BST; adjust for GMT

def last_hash():
    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []
    if not lines:
        return "sha256:0" * 1  # genesis
    last = json.loads(lines[-1])
    return last.get("hash", "sha256:genesis")

def last_ord():
    lines = LOG.read_text().strip().splitlines() if LOG.exists() else []
    if not lines:
        return 0
    return json.loads(lines[-1]).get("ord", 0)

def append(kind, actor, domain, plane, gate, provenance, target, summary):
    entry = {
        "ts":         datetime.now(TZ).isoformat(),
        "kind":       kind,
        "actor":      actor,
        "domain":     domain,
        "plane":      plane,
        "gate":       gate,
        "ord":        last_ord() + 1,
        "provenance": provenance,
        "target":     target,
        "summary":    summary,
        "prev_hash":  last_hash(),
    }
    raw    = json.dumps({k: v for k, v in entry.items()}, separators=(",", ":"))
    digest = "sha256:" + hashlib.sha256(raw.encode()).hexdigest()
    entry["hash"] = digest
    with LOG.open("a") as f:
        f.write(json.dumps(entry) + "\n")
    return entry

if __name__ == "__main__":
    # Example: python3 scripts/audit_append.py
    append("session-start", "atlas", "personal", "ingress", "none",
           "manual", "audit/atlas-actions.ndjson", "Session initialised")
```

## Verification

To check chain integrity:

```bash
python3 - <<'EOF'
import json, hashlib
from pathlib import Path

LOG = Path("audit/atlas-actions.ndjson")
lines = LOG.read_text().strip().splitlines()
prev = "sha256:genesis"

for i, line in enumerate(lines):
    entry = json.loads(line)
    stored_hash = entry.pop("hash")
    raw = json.dumps(entry, separators=(",", ":"))
    computed = "sha256:" + hashlib.sha256(raw.encode()).hexdigest()
    if stored_hash != computed:
        print(f"CHAIN BROKEN at entry {i} (ord={entry.get('ord')})")
        break
    if entry.get("prev_hash") != prev:
        print(f"PREV_HASH MISMATCH at entry {i}")
        break
    prev = stored_hash

else:
    print(f"Chain OK — {len(lines)} entries verified")
EOF
```

## Usage Patterns

### Log every external write

```python
append(
    kind="external-write",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="external-write",
    provenance="session:agent:main:discord:...",
    target="https://api.agirails.xyz/v1/escrow",
    summary="Created ACTP escrow 0xabc... for 10 USDC"
)
```

### Log credential access

```python
append(
    kind="credential-access",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="credential-access",
    provenance="session:agent:main",
    target=".env:ACTP_KEY_PASSWORD",
    summary="Accessed ACTP wallet key for testnet payment"
)
```

### Log payment events

```python
append(
    kind="payment",
    actor="atlas",
    domain="agirails",
    plane="action",
    gate="external-write",
    provenance="session:agent:main",
    target="base-sepolia:0xabc...def",
    summary="x402 payment: 5 USDC → counterparty 0x123, txhash 0xdef..."
)
```

---

## EU AI Act Compliance

### Article 12 — Automatic Event Recording

EU AI Act **Article 12** mandates that providers of **high-risk AI systems** must ensure their systems can automatically record events ("logging") throughout their operational lifetime. Requirements include:

- Automatic recording of the period of each use (date, time)
- Reference database(s) searched or verified against
- Input data that led to the system output
- Identity of the natural/legal persons involved in verification

**August 2026 deadline** — High-risk AI systems must be compliant by the enforcement date under the EU AI Act transition schedule.

### How This Skill Implements Article 12

| Article 12 Requirement | This Skill's Implementation |
|------------------------|----------------------------|
| Automatic event recording | `audit_append.py` — every tool call, decision, ingress |
| Period of use (timestamps) | `ts` field — ISO-8601 with timezone offset |
| Input data traceability | `provenance` + `ingress` kind entries |
| Decision traceability | `decision` kind entries with reasoning summary |
| Identity of actors | `actor` + `provenance` fields |
| Tamper detection | sha256 hash chain — `prev_hash` + `hash` fields |
| Ordering guarantees | Monotonic `ord` field |

### Classification Guidance

Assess whether your agent deployment qualifies as high-risk under Annex III of the EU AI Act. If operating in:
- Critical infrastructure
- Employment/HR decisions
- Access to essential services
- Law enforcement adjacent systems
- Migration/asylum decisions

…then Article 12 logging is **mandatory**, not optional. Run the **Agent Compliance & Security Assessment** skill first to determine your risk classification.

---

## Companion Skills

### `agent-self-assessment` (v2.2.1)
> Run the assessment first, then set up logging for ongoing compliance.

The self-assessment skill provides a 14-check compliance and security framework with RED/AMBER/GREEN ratings. Use it to determine your EU AI Act risk classification before configuring this audit trail.

**Install:**
```bash
clawhub install agent-self-assessment
```

Or if already available in your workspace:
```
Read ~/.openclaw/workspace/skills/agent-self-assessment/SKILL.md
```

**Workflow:**
1. Run `agent-self-assessment` → identify gaps + risk tier
2. Install `agent-audit-trail` → implement logging for ongoing compliance
3. Schedule periodic re-assessments (monthly/quarterly)

---

### `agirails` (v3.0.0)
> Enable payment tracking in your audit trail.

AGIRAILS provides ACTP escrow and x402 instant payment primitives for AI agents. All payments should be logged using the `payment` kind in this audit trail.

**Install:**
```bash
clawhub install agirails
```

Or if already available in your workspace:
```
Read ~/.openclaw/workspace/skills/agirails/SKILL.md
```

**Payment logging integration:**
- Every ACTP escrow creation → `external-write` entry
- Every x402 settlement → `payment` entry with txhash
- Every wallet balance change → `state-transition` entry
- Wallet address and amount included in `summary`

See `TOOLS.md` → **Audit Log** and `SOUL.md` invariant #4 for the full integration.

---

## Roadmap (v2.1+)

The following features are planned for upcoming releases:

### `export` command
Generate a structured compliance report from the NDJSON log:
- Filter by date range, domain, kind, actor
- Output: Markdown, PDF, or JSON summary
- EU AI Act Article 12 report template included
- Example: `python3 scripts/audit_export.py --from 2026-01-01 --to 2026-04-01 --domain agirails`

### `stats` command
Event counts, domain breakdown, and time-range queries:
- Total events per kind
- Events per domain over configurable time window
- Busiest hours / session lengths
- Example: `python3 scripts/audit_stats.py --range 7d --by domain`

### JSON Schema for log validation
A formal JSON Schema (`audit/log-schema.json`) to validate entries:
- Validate all required fields are present and correctly typed
- CI-friendly: run on every log append or as a pre-push hook
- Schema versioned alongside SKILL.md

### Optional remote log shipping (append-only S3/GCS)
Ship log entries to an append-only remote bucket for disaster recovery:
- AWS S3 (object lock / WORM policy)
- Google Cloud Storage (object retention policy)
- Configurable flush interval (real-time or batched)
- No reads from remote — write-only pipeline

### Compliance report template (EU AI Act Article 12)
A structured report template covering:
- System description and risk classification
- Logging configuration and retention policy
- Chain integrity verification results
- Event summary by category
- Named actors and provenance registry
- Attestation block for human signatory

---

*This skill is part of the Atlas workspace compliance stack. See also: `SOUL.md` (invariants), `TOOLS.md` (audit log config), `agent-self-assessment` (risk classification).*