Skip to main content

​
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:
FieldDescription
execution_idUnique identifier
agentAgent name (squad/agent)
triggerWhat initiated: manual, scheduled, event, smart
started_atExecution start time
completed_atExecution end time
statussuccess, failed, timeout, cancelled
tokens_inInput tokens consumed
tokens_outOutput tokens generated
costUSD cost
modelModel used (opus, sonnet, haiku)

​
Action Records

Within each execution, individual actions are logged:
FieldDescription
action_typeissue.create, pr.merge, file.write, etc.
targetWhat was acted upon
resultsuccess, failed, approved, rejected
approval_idLink to approval record if required
metadataAdditional 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

TrailerDescription
AgentFull agent path
SquadSquad that owns the agent
TriggerHow the agent was triggered
ExecutionExecution ID for traceability
ModelWhich model was used

​
Viewing Audit Data

​
CLI Commands

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

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

squads results --days 7
Shows:
  • Goals achieved
  • PRs merged
  • Issues resolved
  • Cost per outcome

​
Monthly Export

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

# By time
squads history --days 1 | grep failed

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

​
2. Get Details

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

# If agent ran locally
squads cron logs engineering/issue-solver

# If on VM
squads trigger logs exec-abc123

​
Retention Policy

Data TypeRetention
Execution records90 days
Action logs90 days
Git historyPermanent
MemoryPermanent (summarized)
Session data30 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

squads history --days 7
squads exec stats
Catch anomalies early.

​
2. Tag Important Executions

Use metadata for significant runs: 
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: 
squads exec stats --period month --json >> audit-archive.jsonl