Audit Traces

Every action evaluated by SidClaw produces an audit trace — a chronological chain of events that records exactly what happened, from the moment the action was submitted through policy evaluation, approval (if needed), and final outcome. Traces are tamper-proof, exportable, and designed for compliance.

Trace Structure

A trace is the top-level record. It captures:

The Event Chain

Each trace contains a sequence of audit events. Events are ordered chronologically and linked by a SHA-256 hash chain. A typical trace looks like this:

trace_initiated
  └─ identity_resolved
       └─ policy_evaluated
            └─ approval_required (if policy says so)
                 └─ approval_granted / approval_denied / approval_expired
                      └─ operation_executed / operation_blocked
                           └─ trace_closed

For actions that are allowed immediately (no approval needed):

trace_initiated → identity_resolved → policy_evaluated → operation_executed → trace_closed

For actions that are denied by policy:

trace_initiated → identity_resolved → policy_evaluated → operation_blocked → trace_closed

Event Types

SidClaw records the following event types:

Each event also records:

• actor_type — Who caused the event: agent, policy_engine, approval_service, human_reviewer, or system
• actor_name — The name of the actor (e.g., the reviewer's name, the agent's name)
• description — Human-readable description of what happened
• status — The status at this point (e.g., success, denied, pending)
• policy_version — Which version of the policy was in effect (for policy events)
• metadata — Additional structured data (error messages, context, etc.)
• integrity_hash — SHA-256 hash linking this event to the previous one

Trace Outcomes

The final_outcome field on the trace records the overall result:

Integrity Hashes

Every audit event in a trace is linked to its predecessor by a SHA-256 hash chain. This makes the audit trail tamper-proof — if any event is modified, deleted, or inserted after the fact, the hash chain breaks and verification fails.

The hash is computed over:

• The event's ID, trace ID, event type, actor, description, status, and timestamp
• The previous event's hash (or GENESIS for the first event in a trace)

Event 1: hash = SHA-256(event_data + "GENESIS")
Event 2: hash = SHA-256(event_data + Event1.hash)
Event 3: hash = SHA-256(event_data + Event2.hash)

Verifying Integrity

You can verify a trace's integrity via the API:

GET /api/v1/traces/{traceId}/verify

The response tells you whether the chain is intact:

{
  "verified": true,
  "total_events": 5,
  "verified_events": 5,
  "broken_at": null
}

If tampering is detected:

{
  "verified": false,
  "total_events": 5,
  "verified_events": 2,
  "broken_at": {
    "event_id": "evt_...",
    "event_type": "policy_evaluated",
    "expected_hash": "a1b2c3...",
    "actual_hash": "d4e5f6..."
  }
}

Parent Traces and Delegation Chains

When an agent acts with delegated authority, the resulting trace can reference a parent_trace_id. This creates a chain of traces that shows the full delegation path — from the original request through each delegating agent to the final action.

This is particularly useful for auditing multi-agent systems where one agent delegates work to another.

Export Formats

Traces can be exported in two formats:

JSON (Single Trace)

Export a single trace with all its events as a JSON document. This is the full-fidelity format suitable for programmatic analysis, compliance archives, or importing into other systems.

CSV (Bulk Export)

Export multiple traces as CSV for spreadsheet analysis. The CSV format flattens the trace and event data into rows suitable for filtering, sorting, and reporting in tools like Excel or Google Sheets. Supports date range filtering to scope the export.