cleveragents-core/docs/reference/audit_logging.md

Audit Logging

CleverAgents records security-relevant operations in an audit_log table for compliance, post-hoc analysis, and diagnostics.

Event Types

Event Type	Trigger	Details Captured
plan_applied	agents plan apply	Plan ID, project, files changed, validation results
plan_cancelled	agents plan cancel	Plan ID, reason, resources released
resource_modified	Tool write during Execute	Resource ID, modification type, tool name
correction_applied	agents plan correct	Correction ID, original decision, mode, guidance
config_changed	agents config set	Key, old/new values (masked if secret)
entity_deleted	agents <entity> delete	Entity type, entity name, cascade effects
session_created	agents session create	Session ID, actor name

CLI Commands

agents audit list

List audit entries with optional filters.

# List recent entries
agents audit list

# Filter by plan
agents audit list --plan 01HXYZ123

# Filter by project and time range
agents audit list --project myproject --since 2026-02-01T00:00:00

# Filter by event type with limit
agents audit list --type plan_applied --limit 10

agents audit show <id>

Display a single entry with full metadata and JSON details.

agents audit show 42

agents audit prune

Delete entries older than the retention period.

# Use configured retention (default: keep indefinitely)
agents audit prune --yes

# Override retention to 90 days
agents audit prune --days 90 --yes

agents audit count

Display the total number of audit log entries.

agents audit count

Configuration

Setting	Environment Variable	Default	Description
audit_retention_days	CLEVERAGENTS_AUDIT_RETENTION_DAYS	0	Days to retain entries. 0 = keep indefinitely.

Database Schema

CREATE TABLE audit_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_type TEXT NOT NULL,
    plan_id TEXT,
    project_name TEXT,
    actor_name TEXT,
    user_identity TEXT,
    details TEXT NOT NULL,  -- JSON
    created_at TEXT NOT NULL
);

CREATE INDEX idx_audit_event ON audit_log(event_type);
CREATE INDEX idx_audit_plan ON audit_log(plan_id) WHERE plan_id IS NOT NULL;
CREATE INDEX idx_audit_created ON audit_log(created_at);

Retention Policy

By default, audit logs are retained indefinitely (audit_retention_days=0) for compliance purposes. Use agents audit prune to manually remove old entries, or set a non-zero retention to enable periodic pruning.

Recording Events

The AuditService.record() method writes events:

from cleveragents.application.services.audit_service import AuditService
from cleveragents.config.settings import get_settings

service = AuditService(settings=get_settings())
service.record(
    event_type="plan_applied",
    plan_id="01HXYZ123",
    project_name="my-project",
    actor_name="openai/gpt-4o",
    details={"files_changed": 3, "validation_passed": True},
)