How to Audit What Your Coding Agent Actually Runs (2026)
Real recording. Since it was made, a force-push is held for your approval rather than blocked. It ends on the answer this post is about: grep '"event":"pre"' ~/.acp/audit.jsonl shows every call the agent made, the decision (deny, ask or allow), and why, one line each, on your machine. That is the hook audit log (option 4 below), not something rebuilt from a transcript.
After an incident, the same thing happens every time. Something got deleted or force-pushed, and the team tries to work out what the agent actually did. The answer is buried in a transcript, if it was kept at all. You don’t have to trust an agent blindly. You do need to be able to look. Here are four ways to do that, and what each one misses.
1. Harness transcripts
Claude Code writes session transcripts as JSONL under ~/.claude/projects/. Other harnesses keep their own session records, in their own formats. This is real data, already on disk, and free. It has three gaps:
- One format per tool. Three agents means three formats in three places.
- Shaped like a conversation. Finding twelve commands inside ten thousand lines of model turns is work.
- No decisions. A transcript says what the agent said it ran. It doesn’t say what was allowed, denied, or why.
2. Shell history
Skip it. Agents run commands through their own exec tools, not your interactive shell, so ~/.zsh_history misses nearly everything.
3. OS-level logging
script, auditd, and EndpointSecurity on macOS capture everything. That is the right call in regulated environments. The costs are real, though. Setup is heavy, the output is a firehose where agent calls look the same as yours, and there is still no record of why something was allowed. Use it for forensics, not for a quick “what did it just do.”
4. A hook audit log
Most coding agents run a hook before and after each tool call. Log at that point and you get what the other three can’t give you: one line per call, across the agents you run, with the decision attached.
This is the layer we build. One command, on your machine, no account:
curl -sf https://agenticcontrolplane.com/install.sh | bash -s -- --local
tail -f ~/.acp/audit.jsonl
Each line has a timestamp, the client, the tool, the classified action (Bash.git.push, Bash.curl.api.stripe.com), the decision, where the decision came from, and the reason. It’s the same file whether the call came from Claude Code or Codex. The hook that writes the line is the same hook that holds the force-push for approval, so the log and the control come from one place.
Limits:
- It only sees what the hooks see. A harness without hook coverage isn’t in the file, and neither is a command you run yourself in a bare terminal. The coverage matrix lists what ACP sees on each harness.
- Locally it’s a record, not proof. See the FAQ.
- Teams that need a copy the agent can’t touch keep the same log in a workspace. It’s the same hook, and the copy is stored off your machine.
What we’d do
If you work alone on repos you trust, run the hook log locally and keep transcripts as backup detail. If untrusted input is involved, or more than one person uses the agents, send the hook log to a workspace. Add OS-level capture if an auditor will ever ask.
Either way, the test is the same. Can you answer “what did the agent run today” from one file, with one grep, with reasons? Or are you re-reading transcripts and hoping? The 60-second recording ends on that grep.
Doesn't Claude Code already log everything?
It keeps session transcripts, and they are useful. But they are per-tool, in a tool-specific format, and they record the conversation, not a decision. There is no line saying a call was allowed because of rule X. Pulling just the commands out of a long transcript is slow work.
Why not just read shell history?
Agents mostly run commands through the harness’s own exec tool, not your interactive shell, so history files miss most of what an agent does. They also say nothing about file edits or web fetches.
What does a hook audit line contain?
In local mode: a timestamp, the client (which agent), the tool, the classified action (like Bash.git.push), the decision (allow, ask or deny), where the decision came from, and the reason. One JSON line per call, append-only, easy to grep.
Is a local audit log tamper-proof?
No. A local file can be written by anything running as you, including the agent. For one developer that is fine, because the question is what happened, not proving it to an auditor. If you need a trail the agent can’t touch, use a workspace, which keeps a copy on a separate system.
Running Codex? One command adds a hook for shell, apply_patch and MCP calls. Each call is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex
What the installer writes · Codex guide · free up to 5 agents