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

```bash
# 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.

```bash
agents audit show 42
```

### `agents audit prune`

Delete entries older than the retention period.

```bash
# 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.

```bash
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

```sql
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:

```python
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},
)
```