Why AI agents need auditable workspaces

You hand a task to Claude Code or Codex. Twenty minutes later there is a branch with a tidy diff. The diff looks fine. But the diff is the last thing that happened, the visible residue of a long operational session you never saw. What was the agent actually asked? Which files did it read and which did it ignore? What commands did it run, and what did they print? Could it have reached your secrets or the public internet? Which model produced this, steered by whose prompt? When a second agent picked up the work, what did the handoff say?

Git answers none of those questions, because Git was designed to version code, not to record the work that produced the code. For human authors that gap never mattered, the work lived in a person's head and their terminal, and we trusted the author. For autonomous agents the gap is the whole problem. The fix is not a better diff viewer. It is to make the workspace itself the unit of record.

The definition

Concretely, the workspace is the sum of everything that went into a change, not just the change:

Two cautions are built into that wording. "Workspace" is a crowded word, the defense is the adjective auditable and the location in your repo. And no single feature is the identity: token reduction, a prompt score, a messaging channel are all properties of the workspace, never the point. The point is that the place an agent worked becomes a record you can replay, review, and trust.

The problem: agents do operational work Git never records

A commit is a snapshot of files plus an author, a timestamp, and a message. That model is a perfect fit for "a person deliberately saved this state." It is a poor fit for "an autonomous process spent an hour reading, deciding, executing, and negotiating, and this diff fell out the end." All of the high-signal, high-risk material, the intent, the tool output, the reach, the reasoning, happens off-ledger.

That off-ledger work is exactly what a reviewer needs and exactly what an incident responder wishes they had. "The agent refactored billing" is reassuring until you learn it was prompted with "make it work", ran a destructive migration you can't see, and could reach the production database the whole time. None of that is in the diff. It was in the workspace, and the workspace evaporated.

Naming the missing data is a category question. AI-aware version control covers what record a diff structurally can't hold and how to store it on top of Git. This post is narrower and more operational: it is about the place the agent works and the concrete artifact that place leaves behind. The category says record the process, not just the artifact; the workspace is where that record actually accrues, command by command.

Three proof pillars

"Auditable" is not a vibe; it decomposes into three concrete properties of the workspace. Each one answers a question the diff can't, and each is backed by data that lives in your Git refs.

The middle pillar is the one teams underrate. "The agent physically could not exfiltrate" beats "we logged it" every time, a log tells you what happened, a boundary tells you what could never happen. h5i's sandboxed worktree (h5i env) enforces that boundary with tiered isolation and a network egress allowlist, then records the policy alongside the evidence so the confinement itself is auditable.

The workspace stack

Put the pillars together and a workspace has a stack, each layer a command you actually run, each layer recording a different slice of the work:

Agent Workspace
├─ Sandboxed worktree        h5i env
├─ Prompt-aware commits      h5i capture commit
├─ Compressed tool logs      h5i capture run
├─ Agent handoffs            h5i msg
├─ Risk/audit signals        h5i audit
└─ PR evidence brief         h5i share pr

The sandboxed worktree is the hero, not feature number seven. It is the canonical auditable workspace and the command humans actually type. Everything above it accrues onto that worktree as the agent works.

The golden path

The pieces compose into one user journey, the same ordering everywhere:

env create  →  agent works (env shell / capture run)  →  capture commit (provenance)
            →  msg review  →  share pr  →  apply

In narrative form: open a workspace, hand it to an agent, let evidence accrue (commands, logs, prompts, handoffs), have a reviewer read the provable record on the PR, and the human applies or merges. The agent never touches your branch directly, it works inside a confined worktree, and a person applies its work after reading the evidence.

The moat: it lives in your Git

Everything above lives under refs/h5i/*, so it travels with the repository like any other Git data. No SaaS, no lock-in, works offline. Clone the repo and you have the workspaces; there is no separate service holding your audit trail hostage and no account to log into to find out what an agent did. The evidence is as durable and portable as the commits it explains.

That is also why the token-reduction claim ladders up to "auditable" rather than standing on its own: the workspace keeps raw logs out of the agent's context window, recoverable, not discarded, which is how it gets to ~95% lower token waste while still being able to show you the full output later.

How the record is captured: refs and hooks

"Recorded in your repo" is precise, not a metaphor. Each dimension of the workspace maps to a Git ref, and most of the writing happens automatically through editor hooks, not through commands you remember to run:

The hooks matter as much as the refs. An audit trail an agent has to opt into is one it will forget under deadline; capture has to be the default path, not a discipline. h5i wires that with h5i hook setup: in Claude Code, SessionStart, UserPromptSubmit, PostToolUse (on every Read/Edit/Write), and Stop hooks record the prompt, the reads as OBSERVE, the edits as ACT, and mined THINK/NOTE reasoning, without the agent issuing a single logging command. Codex reconstructs the same record from its session JSONL. The verbatim human prompt wins over any agent-supplied --intent, so the record reflects what a person actually asked, not what the agent later claims it was asked.

Surfacing the record: a worked example

An audit trail is only worth keeping if you can read it back cheaply. The same workspace that captured the work exposes it through query commands, with no console and no export. Suppose a reviewer is staring at a one-line change in src/api/client.py and wants to know who and what produced it:

$ h5i recall blame src/api/client.py --show-prompt  # line → author + model + prompt + test result
$ h5i recall log --limit 20                       # provenance per commit, most recent first
$ h5i notes uncertainty                            # where the agent flagged it was unsure
$ h5i audit review --limit 50                      # triage funnel: integrity Warnings/Violations
$ h5i audit compliance --since 2026-01-01 \
      --until 2026-03-31 --format html --output audit.html  # a dated, shareable report
$ h5i share pr post                                # the same evidence as a sticky PR comment

The shape of the answer is the point: recall blame turns "who wrote this line" into "which model, steered by which human prompt, with which test result," and audit review is a deterministic triage funnel, with no model in the loop grading the work, surfacing the commits whose stored IntegrityReport came back Warning or Violation. A reviewer reads the record, not the agent's self-report.

How it compares

Teams already reach for several tools to answer "what did the agent do?" Each captures a real slice; none captures the workspace. The honest comparison:

None of these is wrong, and an auditable workspace does not replace CI or your PR template. It complements them by giving the per-commit, in-repo substrate the others assume but don't provide. The differentiator is the last column's first entry: the record is yours, durable, and portable, because it is Git.

Failure modes: where this breaks

A pillar should be honest about its edges. An auditable workspace fails in three predictable ways, and each has a mitigation rather than a denial:

• Unshared refs. refs/h5i/* are deliberately not moved by a plain git push, so a reviewer on another clone sees the code but not the record. The record is there, just local. The fix is operational, not technical: run h5i share push (and h5i share pull), ideally from CI on the branch, so the evidence travels with the PR by default.
• Gaming the record. Provenance the agent writes about itself, an --intent string or a tidy commit message, can flatter. h5i blunts this by preferring captured signal over self-report: the verbatim human prompt overrides agent-supplied intent, tool output is captured by the wrap-bash hook rather than narrated, the IntegrityReport verdict is computed, and confinement is a boundary, not a claim: an egress allowlist makes "it couldn't exfiltrate" provable instead of asserted. What an agent narrates is weaker evidence than what the workspace observed.
• Discipline drift. If commits skip h5i capture commit, runs skip capture run, or hooks aren't installed, coverage is patchy and the trail has holes. The mitigation is to make capture the default path. h5i hook setup wires it into the editor so the agent can't opt out, and a missing record on a PR should be a review blocker, the same way an untested change is.

What it is not

It does not replace Git; it rides alongside it. It is not a cloud sandbox like a hosted dev environment, the confinement runs on your machine and the record lives in your repo. And it is not merely a sandbox: a sandbox confines, but an auditable workspace confines and records and makes the whole thing reviewable on the PR. Confinement is one of the three pillars, not the product.

Why this is the right unit

Code review evolved for a world where a trusted human authored every line and could answer for it in a hallway conversation. Agents broke that assumption: the author is a process, it can't be cross-examined later, and it operated with real capability over your machine and network. The honest response is not to trust harder or log more, it is to make the agent's entire workspace a first-class, Git-backed, provable artifact. Grade the work by the record it leaves, confine what it can reach, and let a human apply it after reading the evidence.

Frequently asked questions