Inside Agentwhy, Part 1: A Step-by-Step Audit Trail for AI Coding Agents
One part of agentwhy each week. This one shows every step your AI and its helpers took, and where a rule stopped them.
On November 16th, the author published an article about preventing AI coding agents from accessing sensitive information. A reader asked whether the blocked attempts could be logged on the conversation timeline with the task and secret omitted. Agentwhy, the agent in question, already performs this action. This article serves as the first in a series that examines each part of Agentwhy in detail.
The first part focuses on the step-by-step audit trail of a single conversation between a user and the AI agent. The screenshots used in this article are from a hypothetical demo project.
The conversation begins with the user asking Claude Code to find out why the AI chat stopped responding. Claude completed this task in six minutes. The first screen of the report details the files that were read, attempted to be opened, and successfully accessed, as well as the helpers involved in the process. Only one file, business-plan.md, was allowed to be read and marked as "tracked."
Two other private files, customers.csv and .env, were attempted to be opened but were blocked by rules. One helper was engaged, and it did not read any private files.
The relationship between the user, AI, and helper is illustrated through a diagram, with read attempts represented by orange dots, stopped attempts by dashed green lines, and tasks assigned to helpers by grey lines. A particular focus is placed on the helper's task, as it is crucial to understanding what went wrong in this scenario.
In the author's own incident in September, the rule in AGENTS.md did not reach the helper, as the helper only had its assigned task, which requested the secret. This visual representation highlights the importance of understanding both the request and the helper's task in identifying issues.
The "Step by Step" tab presents the conversation as a list, providing a chronological order of events. Each step lists what the AI wrote, what files were read, what was executed, and what was changed. The model used by Claude Code is shown above the list as claude-opus-5-5. Every step is then broken down into individual rows, showing the actions taken by the AI and the helper. The MCP step provides additional insights that may not be apparent from the conversation alone.
Two specific rows warrant closer examination. The first row details the MCP tool's utilization of the Sentry MCP server, which operates outside the conversation's scope, meaning Agentwhy cannot see which files were accessed. The second row highlights an attempt to open the customers.csv file, which was blocked by a rule in the user's settings.
The author notes that in setups where a deny rule triggers no hook, no records will be available in the hooks or logs, but the conversation and Agentwhy can still access the information logged within.
A helper's task is initiated through a separate file named subagents/agent-.jsonl, which is stored in a folder corresponding to the conversation. This file contains a small meta.json file that includes crucial information such as the agent type, tool use ID, and spawn depth. The tool use ID is generated from the original Agent call and is used to link the helper's actions back to the initial request. In cases where a helper is started via a skill, the toolUseId may not be present, as shown in the provided code snippet.
Rewritten by urgent.news; may contain errors — check the original.