Audit Trails & Compliance

Enterprise deployments of AI agents require audit trails that answer four questions: who initiated the task, what did the agent do, when did each action occur, and why was each decision made. Regulatory frameworks (SOC 2, GDPR, HIPAA) require demonstrable control over automated systems that process data or make decisions. An audit trail transforms agents from opaque automation into auditable, governable infrastructure.

The audit trail for a Codex agent pipeline captures events at three levels. Pipeline level: who submitted the task, what priority was assigned, which SLA policy applied, and the final outcome (success/partial/failure). Agent level: which model was used, what files were read, what files were modified, how many tokens were consumed, and the agent's output. Decision level: why the supervisor chose a particular decomposition, why a retry was triggered, why an escalation occurred, and why the pipeline was aborted or completed.

from dataclasses import dataclass, field
from datetime import datetime
import json

@dataclass
class AuditEvent:
    timestamp: datetime
    trace_id: str
    level: str        # "pipeline", "agent", "decision"
    actor: str        # User or agent name
    action: str       # "submit", "execute", "modify", "escalate"
    target: str       # File path, task ID, agent name
    detail: dict = field(default_factory=dict)
    # Immutable once written — append-only log

class AuditLog:
    def __init__(self, log_path: str):
        self.log_path = log_path

    def record(self, event: AuditEvent):
        """Append event to immutable audit log."""
        with open(self.log_path, "a") as f:
            entry = {
                "timestamp": event.timestamp.isoformat(),
                "trace_id": event.trace_id,
                "level": event.level,
                "actor": event.actor,
                "action": event.action,
                "target": event.target,
                "detail": event.detail,
            }
            f.write(json.dumps(entry) + "\n")

# Usage:
# audit.record(AuditEvent(
#     timestamp=datetime.now(),
#     trace_id="pipeline-001",
#     level="agent",
#     actor="implementer-0",
#     action="modify",
#     target="src/middleware/rateLimit.ts",
#     detail={"lines_added": 45, "lines_removed": 12},
# ))