How to Keep an Audit Log of Every Command and Tool Call a Coding Agent Runs

When a coding agent edits a repository, runs a shell command, or calls an external tool, a useful audit log needs to show what the agent requested and what actually ran. An audit log is a time-ordered record used to review actions later. A practical audit log combines events from the agent with records from the computer or container that runs it. Send both to a destination where the agent cannot quietly change the only copy.

A tool call is an agent’s request to use a capability such as a terminal, file editor, web search, or external service. The agent’s record of a shell command does not necessarily show every child process that command starts. For that reason, “every action” needs a defined boundary: tool requests, executions, child processes, file changes, or some combination. The steps below show how to choose that boundary, capture the relevant events, and make collection gaps visible.

Capture what the agent requested

Start with the agent’s own event stream or hooks. These records capture activity as the agent chooses and uses a tool. They can include details that shell history usually misses, such as approvals, external tool parameters, and results.

For example, Cursor’s hooks expose events for shell execution and file edits. They also expose MCP calls, failures, and subagents. MCP, or Model Context Protocol, is a way for an agent to connect to tools provided by external services. Cursor documents shell events that can include the command and output, along with the duration and sandbox status. MCP events can include the tool name and parameters, as well as the server, result, and duration. These hooks record the events they cover, but they do not show that they capture every phase of every agent session. Cursor documents that hooks do not run during some early, read-only exploratory turns in cloud-agent sessions.

For runs started by scripts or without an interactive interface, Codex CLI’s JSON output provides events in a format that software can read. JSONL, or JSON Lines, stores one JSON record per line, which makes it easier to process events as they arrive. Codex’s documented event types include command executions and file changes. They also include MCP calls and web searches. The stream records events Codex emits. It does not check on its own whether each event changed anything on the host.

When the agent provides these events, record each call from request through completion. A useful record includes the request, approval or denial, start and completion, and result or error. Record cancelled and failed calls too. A log of successful calls alone leaves out decisions and attempts that did not succeed, which may matter during review. OpenAI’s Codex telemetry documentation describes tool approval decisions and execution results. It also describes MCP server use and network-proxy allow or deny events. Availability depends on the product and customer plan; OpenAI documents Compliance Platform activity logs for Enterprise and Edu customers.

Record enough context to connect events

Give each event a unique ID, and keep the IDs that connect related events. A tool-call ID connects a request to its result; a session or thread ID connects tool calls to one agent session. A parent event or trace ID helps connect a subagent’s activity to the work that started it.

For each event, record the agent and runtime versions, the user or service identity, the repository or workspace, the host or container, the working directory, the tool name, and its target. Include the arguments, approval decision, timestamps, outcome, and exit code when available. Store the result or output too. If it is too sensitive for the main log, store a protected reference to it instead. These are recommended fields, not a promise that each agent product emits them all.

OpenAI’s tracing documentation describes tool spans that can include a tool name, arguments, result, status, and errors. A span is a record of one operation within a larger trace. Check the event format before treating an empty result field as proof that a tool did nothing. The documentation says an MCP response can appear in the call record instead of a separate result panel.

OpenTelemetry is a common framework for collecting and sharing telemetry, or records about activity. Its terms offer a starting point for connecting model and tool events. Its GenAI conventions include fields for conversation IDs and tool-call IDs. They also define fields for tool names, arguments, and results. The conventions warn that these fields can contain sensitive material, and their attributes can change. Check the current definitions before depending on a particular field name.

Add host records when you need execution evidence

Agent logs answer what the agent asked to do. Host or container records help answer what ran. One shell request can start a script, and that script can start additional processes. A single agent event therefore does not necessarily enumerate every process or indirect effect.

If your audit requirement includes child processes or file activity, compare agent events with operating-system or container records of those events. Test the exact runtime and environment you use; the reviewed agent documentation does not establish complete host-level coverage. Match records by time and execution context, such as the host, container, workspace, and agent session. If your host records cannot be linked reliably to an agent call, report that limitation instead of presenting the two records as a complete trace.

Protect records and surface collection failures

Send records to a centrally controlled destination so the agent process cannot quietly alter the only copy. Keep a local buffer when needed to handle interruptions, then forward its events. Set rules for how long to keep records and who can access them. Use integrity checks to help detect changes. NIST’s log-management guidance covers generating, transmitting, storing, analyzing, and disposing of logs, including centralized collection and integrity checking.

Make failures visible. Track whether hooks or exporters are running, whether records reached storage, and whether events were dropped. Decide what the agent should do when logging fails: alert an operator, stop work, or continue with an explicit gap. Storage exhaustion needs a defined response too. Without one, a full destination can turn a required audit trail into an unreported blind spot.

Protect the contents as carefully as the collection path. Commands, prompts, arguments, and results can expose credentials, personal information, proprietary code, or infrastructure details. Decide which fields to hide, replace with hashes, shorten, or store in a restricted location. Redaction reduces exposure but also removes details that might help reconstruct an event. OpenTelemetry’s GenAI guidance calls out this sensitivity for inputs and outputs. It also covers tool arguments and results.

Test the boundary you claim to cover

Test sessions with successful, denied, failed, and cancelled calls. Cover shell commands and file operations. Also test external tools and subagent activity. Compare agent records with host evidence where available. Restart the agent, interrupt the exporter, and test what happens when storage fills. Confirm that each failure produces an alert or a visible gap, rather than an apparently quiet period.

Check product-specific exceptions as well. For Cursor cloud agents, test the early read-only phase because its documentation says hooks do not run during some of those turns. Repeat the checks whenever you change the agent, runtime, or product plan. Those details affect which events the product records. Product documentation describes available event surfaces; it does not supply a universal completeness guarantee or a tested capture percentage.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com