THE AUDIT SYSTEM

When an AI agent operates a Swamp repo, it runs dozens of commands in minutes. Some are swamp commands. Some are direct CLI calls to tools like aws, terraform, or kubectl. The human who returns to the repo needs a single answer: what happened while I was away? The audit system exists to provide that answer — a chronological timeline of every command, regardless of origin.

Two sources of truth

Swamp commands are recorded automatically. Every swamp model method run, swamp workflow run, or swamp data query invocation writes an audit entry with a timestamp, session ID, and the full command string. No configuration required.

Direct CLI commands are a harder problem. A Swamp workflow might run swamp model method run deploy, but the model's method internally calls aws ec2 run-instances. Without capturing that second command, the audit timeline has a gap. Audit hooks close the gap by recording CLI commands executed within the repo directory. The result is a unified timeline where both layers are visible: the Swamp command that initiated the work and the underlying tool invocations it produced.

Why hooks are tool-specific

Each AI coding tool intercepts shell commands through a different mechanism. Claude Code uses hooks defined in its settings file. Cursor uses shell integration. Other tools have their own extension points. A single generic approach would miss commands or double-count them depending on the tool's execution model.

swamp repo init --tool <tool> configures the correct hook for the active tool. swamp doctor audit verifies the hook is installed and functioning. The tradeoff is explicit: rather than attempting a fragile universal solution, Swamp maintains per-tool integrations that each work reliably.

Sessions isolate concurrent actors

Each terminal session or agent run receives a session ID. The audit timeline can be filtered by session, which matters when multiple agents or humans work in the same repo at the same time. Without session filtering, interleaved commands from different actors would produce an unreadable timeline. With it, you can isolate exactly what one agent did during one run.

What audit deliberately omits

The audit system records commands, not outcomes. It does not capture exit codes, stdout, stderr, or which resources a command created or destroyed. This is a deliberate design boundary. Recording outcomes would require parsing tool-specific output formats, handling streaming output, and storing potentially large payloads — all of which would make the system expensive and fragile.

For execution outcomes, Swamp has purpose-built tools: swamp model method history shows what a method produced, and swamp workflow history shows the result of each workflow step. For what is running right now, swamp run history tracks in-flight executions with heartbeat-based liveness detection. The audit timeline complements all three by answering a different question: not "what was the result?" or "what is happening now?" but "what was attempted?"

This separation keeps audit lightweight and always-on. Every command is recorded with minimal overhead, so the timeline is never incomplete. The more expensive work of tracking outcomes stays in the systems that already do it well.

Vault read-access audit

The command-level audit system records what was attempted — commands that ran, regardless of what they touched. It deliberately does not track which resources a command accessed, because doing so would require parsing tool-specific output.

Vault read-access audit fills a different gap. It records what was accessed — specifically, which secrets were read from which vaults, and what triggered the read. The question it answers is not "what commands ran?" but "who looked at my secrets?"

The two systems are separate by design. They use different storage — the command timeline writes to .swamp/audit/commands-YYYY-MM-DD.jsonl, while vault read audit writes to .swamp/audit/vault-reads-YYYY-MM-DD.jsonl. They operate at different granularity: a single swamp model method run command might resolve three vault expressions, producing one command audit entry and three vault read entries. And they serve different compliance concerns — command audit is about agent activity; vault read audit is about secret access.

This separation keeps each system focused. Vault read audit can record the exact secret key and caller context without complicating the command timeline, and the command timeline stays lightweight without needing to understand vault internals. For how to enable and query vault read audits, see Enable and Query Vault Read Audits. For the entry format and field reference, see Read-Access Audit Trail.

For a broader view of how these primitives compose, see How Swamp Works.