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.
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
# 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:
- Commit messages following Conventional Commits
- Attribution trailers as described above
- 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"
- 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
- Start/end times
- Working directory
- Token usage
- Files accessed
Compliance Reports
Weekly Summary
Shows:
- Goals achieved
- PRs merged
- Issues resolved
- Cost per outcome
Monthly Export
squads exec stats --period month --json > audit-$(date +%Y-%m).json
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
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 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
squads history --days 7
squads exec stats
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
