Audit trails for agent actions

An agent session that leaves no trace is a session nobody can review later — not the engineer who approved it, not the one debugging a regression three weeks on, not an auditor asking why a config file changed. Audit trails turn "the agent did something" into a sequence of facts you can point to, each one written down at the moment it happened rather than reconstructed from memory.

What counts as an audit trail here

Not the full chat transcript — that's too dense to be useful and often gets deleted or truncated. What you want are the load-bearing events: which tools ran, on which files, what the diff was, what a verification step returned, who approved the result, and what commit it landed as. In the figure, each of those events on the timeline drops one retained artifact below it. None of the artifacts depend on the others still existing — you can throw away the raw transcript and still know exactly what changed and why.

Logging tool calls as they happen

The right place to capture this is at the tool-call boundary, not after the fact. Claude Code's PostToolUse hooks fire once per tool call and receive the tool name and its input as JSON, which is enough to append a structured log line without touching the agent's own output:

#!/bin/bash
# PostToolUse hook: one JSON line per tool call
jq -c '{ts: now, tool: .tool_name, input: .tool_input}' >> .agent-audit.log

Pair this with your normal git history — a diff is already an audit artifact — and you get a log that says which tool touched which file, in order, correlated with the commits that resulted.

What to keep, and what not to bother with

Keep: diffs, test/lint output at the point a change was accepted, the reviewer's findings if you used a subagent reviewer, and a record of who clicked approve and when. Skip: full raw transcripts by default — they're large, they may contain content you don't want retained long-term, and the five artifacts above answer almost every question you'll actually ask later ("why did this file change," "did tests pass before merge," "who signed off").

Making it queryable after the fact

An audit trail nobody reads is just disk usage. Tag commits with a session or task identifier in the commit message, and store the test log and reviewer findings alongside the PR rather than in a separate system — the moment someone has to go looking in two places, they stop looking in either.

Try it today

1. Add a PostToolUse hook that appends tool name and file path to a log file for every session this week.
2. Include the test output as a PR comment or artifact at merge time, not just in CI's ephemeral logs.
3. Put a session or task ID in every commit message an agent produces.
4. Pick one past incident and check whether your current logs would have let you answer "what did the agent touch" in under a minute. If not, that's the gap to close first.

Where this breaks

Logging every tool call generates a lot of low-value noise — a hundred Read calls during exploration tell you little. Filter for state-changing tools (Edit, Write, Bash) if volume becomes a problem. An audit trail also only records what happened through instrumented paths — an agent with raw shell access can do things your hook never sees. And retention has a cost of its own: decide upfront how long diffs, logs, and transcripts are kept before they become a compliance liability rather than a debugging aid.

Next: multi-agent patterns that converge — once you can see what one agent did, the harder problem is knowing when several of them are actually finished.