> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit Trail

> Tracking and accountability for all agent actions

## Overview

Every agent action is tracked for accountability, debugging, and compliance. The audit trail answers: **Who did what, when, why, and what was the result?**

***

## What Gets Tracked

### Execution Records

Every agent run creates an execution record:

| Field          | Description                                     |
| -------------- | ----------------------------------------------- |
| `execution_id` | Unique identifier                               |
| `agent`        | Agent name (squad/agent)                        |
| `trigger`      | What initiated: manual, scheduled, event, smart |
| `started_at`   | Execution start time                            |
| `completed_at` | Execution end time                              |
| `status`       | success, failed, timeout, cancelled             |
| `tokens_in`    | Input tokens consumed                           |
| `tokens_out`   | Output tokens generated                         |
| `cost`         | USD cost                                        |
| `model`        | Model used (opus, sonnet, haiku)                |

### Action Records

Within each execution, individual actions are logged:

| Field         | Description                              |
| ------------- | ---------------------------------------- |
| `action_type` | issue.create, pr.merge, file.write, etc. |
| `target`      | What was acted upon                      |
| `result`      | success, failed, approved, rejected      |
| `approval_id` | Link to approval record if required      |
| `metadata`    | Additional context                       |

***

## Attribution Requirements

Policy `ORG-001` requires agent PRs include attribution trailers:

```
feat(auth): add OAuth2 support

Implements OAuth2 flow for GitHub and Google providers.

Closes #42

---
Agent: engineering/issue-solver
Squad: engineering
Trigger: event (issue.labeled)
Execution: exec-abc123
Model: claude-sonnet-4
```

### Required Trailers

| Trailer     | Description                   |
| ----------- | ----------------------------- |
| `Agent`     | Full agent path               |
| `Squad`     | Squad that owns the agent     |
| `Trigger`   | How the agent was triggered   |
| `Execution` | Execution ID for traceability |
| `Model`     | Which model was used          |

***

## Viewing Audit Data

### CLI Commands

```bash theme={null}
# Recent execution history
squads history

# Filter by squad
squads history --squad engineering

# With cost details
squads history --verbose

# Execution details
squads exec show exec-abc123

# Execution statistics
squads exec stats
```

### Example Output

```
Agent Execution History (7 days)

AGENT                    RUNS  SUCCESS  COST    LAST RUN
engineering/issue-solver 45    42 (93%) $156.40 2h ago
cli/cli-lead             12    12 (100%) $89.20 4h ago
intelligence/researcher  8     7 (87%)  $45.80  1d ago

Total: 65 runs │ $291.40 │ 94% success rate
```

***

## Database Schema

Execution records are stored in PostgreSQL:

```sql theme={null}
-- Execution records
CREATE TABLE trigger_executions (
  id UUID PRIMARY KEY,
  agent_name TEXT NOT NULL,
  squad TEXT NOT NULL,
  trigger_type TEXT NOT NULL,
  status TEXT NOT NULL,
  started_at TIMESTAMPTZ NOT NULL,
  completed_at TIMESTAMPTZ,
  tokens_in INTEGER,
  tokens_out INTEGER,
  cost DECIMAL(10,4),
  model TEXT,
  error_message TEXT,
  metadata JSONB
);

-- Action log
CREATE TABLE action_log (
  id UUID PRIMARY KEY,
  execution_id UUID REFERENCES trigger_executions(id),
  action_type TEXT NOT NULL,
  target TEXT,
  result TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  metadata JSONB
);
```

***

## Git History

All file changes by agents are tracked in git with:

1. **Commit messages** following Conventional Commits
2. **Attribution trailers** as described above
3. **PR links** to the creating execution

### Querying Git History

```bash theme={null}
# Find all agent commits
git log --all --grep="Agent:" --oneline

# Find commits by specific agent
git log --all --grep="Agent: engineering/issue-solver"

# Find commits from a specific execution
git log --all --grep="Execution: exec-abc123"
```

***

## Memory as Audit

Agent memory provides context for decisions:

```bash theme={null}
# View squad memory (includes decision rationale)
squads memory show engineering

# Search for specific decisions
squads memory query "why we chose PostgreSQL"
```

Memory entries include:

* What was decided
* Why (reasoning)
* When (timestamp)
* Who (agent or human)

***

## Session Tracking

Claude Code sessions are tracked for debugging:

```bash theme={null}
# Active sessions
squads sessions

# Session history
squads sessions history

# Session details
squads sessions summary
```

Session data includes:

* Start/end times
* Working directory
* Token usage
* Files accessed

***

## Compliance Reports

### Weekly Summary

```bash theme={null}
squads results --days 7
```

Shows:

* Goals achieved
* PRs merged
* Issues resolved
* Cost per outcome

### Monthly Export

```bash theme={null}
squads exec stats --period month --json > audit-$(date +%Y-%m).json
```

Export for external compliance systems.

***

## Incident Investigation

When something goes wrong, trace the issue:

### 1. Find the Execution

```bash theme={null}
# By time
squads history --days 1 | grep failed

# By agent
squads history --squad engineering --verbose
```

### 2. Get Details

```bash theme={null}
squads exec show exec-abc123
```

Output:

```
Execution: exec-abc123
Agent: engineering/issue-solver
Status: failed
Duration: 4m 32s
Tokens: 45,230 in / 12,450 out
Cost: $3.24

Error: Rate limit exceeded after 3 retries

Actions:
1. issue.read #42 → success
2. branch.create fix/issue-42 → success
3. file.write src/auth.ts → success
4. pr.create → failed (rate limit)
```

### 3. Check Logs

```bash theme={null}
# If agent ran locally
squads cron logs engineering/issue-solver

# If on VM
squads trigger logs exec-abc123
```

***

## Retention Policy

| Data Type         | Retention              |
| ----------------- | ---------------------- |
| Execution records | 90 days                |
| Action logs       | 90 days                |
| Git history       | Permanent              |
| Memory            | Permanent (summarized) |
| Session data      | 30 days                |

***

## Privacy Considerations

The audit trail does **not** capture:

* Actual file contents (only paths)
* API keys or secrets
* Personal user data
* Full conversation logs

For GDPR/CCPA compliance:

* Anonymize user-identifying data
* Provide data export on request
* Support deletion requests

***

## Best Practices

### 1. Review Weekly

```bash theme={null}
squads history --days 7
squads exec stats
```

Catch anomalies early.

### 2. Tag Important Executions

Use metadata for significant runs:

```bash theme={null}
squads run engineering/issue-solver --trigger manual
```

### 3. Document Exceptions

When overriding normal processes, document in:

* PR description
* Commit message
* Memory update

### 4. Archive Periodically

Export audit data before retention expiry:

```bash theme={null}
squads exec stats --period month --json >> audit-archive.jsonl
```