--- name: Agent Audit Trail version: 2.1.0 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 systems. author: name: Justin Roosch url: https://github.com/roosch269 license: MIT-0 tags: - audit - compliance - logging - eu-ai-act - article-12 - governance - provenance - security keywords: - audit trail - agent logging - hash chain - event log - compliance logging ---

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:

{
  "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

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

2. Wire into TOOLS.md

Add to your workspace TOOLS.md:

## 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)

# 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:

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

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

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

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:

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:

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).