What Is AI-Aware Version Control? The Record a Diff Can't Hold

Why this question matters now

For thirty years, a Git commit carried a safe assumption: the person in the author field typed the lines, understood them, and could explain them in review. That assumption is quietly breaking. When Claude Code, Codex, or another coding agent writes a patch, the commit author is still a human email — but that human may have typed one sentence of intent and approved a multi-file change they did not read line by line. The committer no longer reliably identifies the real author, and review can no longer assume the committer understood the change.

This is not a forecast; it is the daily texture of agentic development. A single agent session can read a dozen files, edit several, run a test suite, and open a pull request — all from a one-line prompt. The diff that lands is real and reviewable. But the diff is the smallest part of the reviewable artifact. The prompt that started the task, the files the agent actually inspected, the assumptions it made, the tests it ran, the uncertainty it flagged, the handoffs it exchanged with another agent — that is what review, audit, and rollback depend on, and it is exactly what a diff structurally cannot hold.

AI-aware version control is the response: version control that records who and what produced a change, not just what changed. The unit of authorship has shifted from a human typing lines to an agent acting on a prompt with observed context. The version-control record has to follow that shift. This post defines the missing record precisely, separates what you already know about Git from what you may not have considered, shows how the record can be implemented on top of Git today, and compares the approach fairly to the adjacent tools you may already use.

What Git records, and what it never has

Git is an exceptional content-addressed history. It records snapshots, the parent graph, an author, a committer, a timestamp, and a message. None of that is wrong, and AI-aware version control does not replace any of it. The point is narrower and more specific: Git records the artifact, not the process that produced it.

Git does not know a change was generated from a prompt. It does not know whether the agent read the migration file before editing the model, or the interface before editing a caller. It does not know the agent chose a smaller refactor because the larger one looked risky. The commit message can describe some of this, but a message is a hand-written summary, not evidence — and when an agent writes the message, it is the same model summarizing its own work.

That gap is invisible until something forces the question why did this change happen? A human reviewer needs to know where to focus. A compliance reviewer needs to know whether AI participated and under what controls. A maintainer bisecting a regression needs to know which intent introduced the behavior. A second agent resuming the work needs the previous agent's working memory, not only the final patch. In every case the answer existed at the moment the change was made and was discarded because the diff had nowhere to put it.

The missing record: six fields

The record a diff cannot hold reduces to six fields. Each one answers a question review and audit actually ask, and each one is useless reconstructed after the fact — it has to be captured when the change is made.

• Agent identity. Which agent acted — Claude Code, Codex, a CI bot, a human. Without it, git author conflates the person who approved the change with the system that produced it. Rollback and incident response need to know whether a class of changes came from one agent configuration.
• Model. Which model and version produced the patch. Model behavior changes across releases; "all of agent X's changes during the week of a known-bad model revision" is a query you want to be able to run, and it is impossible if the model was never recorded.
• Prompt / intent. The request the change was meant to fulfill. This is the difference between reviewing code and reviewing whether the code does what was asked. A diff can be internally correct and still answer the wrong question; only the prompt reveals the mismatch.
• Context observed. What the agent actually read before editing — did it open the interface, the tests, the caller, the migration? This is the field most reviewers do not think to ask for and the one that most often explains a bad change. An edit to a function whose callers the agent never opened is a different risk than the same edit made after reading every call site.
• Action / tool trace. The sequence of tool calls and commands the agent ran. It distinguishes a focused edit from a thrash of attempts, and it is the record that lets you reproduce or distrust a result.
• Test evidence. Which tests ran, their result, and the output — tied to this change and the prompt behind it, not floating in a CI dashboard. The question is not "is the build green" but "did the change that claimed to fix X actually exercise X".
• Review / risk signals. Flags worth a reviewer's attention first: blind edits to unobserved files, large churn, scope creep beyond the prompt, recorded uncertainty, prompt-injection indicators in observed content. These turn a flat diff into a triaged one.

Six fields, one rule: capture at the moment of authorship, store next to the commit, make it queryable. That is the whole idea.

What you already know vs what you may not have considered

You already know Git tracks content, author, and a message, and that pull requests and CI sit on top. You may have assumed that between commit metadata, the PR description, and a green pipeline, the provenance question is basically covered.

It is not, and the gaps are specific. The commit author records who ran Git, not which model wrote the lines. The commit message is a summary an agent can write about itself, not evidence of what it observed. The PR description lives out of band from the per-commit history and is rarely queryable. And a green CI run — the part teams lean on most — proves the tests passed at a moment in time, but it is bound to a pipeline run, not to the prompt and intent that motivated the change. None of your existing records connect "the agent was asked to fix X" to "these tests, exercising X, passed." That join is the thing AI-aware version control adds, and it is the thing nothing in the default stack provides.

How AI-aware version control works on top of Git

The encouraging part of the third takeaway is that you do not need a new system of record to get this. Git already has the storage primitives. Git notes attach arbitrary data to an existing commit without rewriting it, and refs outside refs/heads/* can carry structured history that travels with the repo. AI-aware version control is what you get when you put the six fields there. h5i is one open-source implementation of exactly this; the mechanics are worth seeing concretely.

• Per-commit provenance in git notes. h5i capture commit writes an H5iCommitRecord — model, agent, prompt, token count, test metrics, and an integrity report (Valid / Warning / Violation) — as JSON in a git note attached to the commit. The commit object is untouched; git log and git diff are unchanged.
• Reasoning and context in refs/h5i/context. A context DAG records OBSERVE / THINK / ACT / NOTE / MERGE entries, a goal, and milestones, pinned to commit SHAs. This is the "context observed" and "action trace" record — recoverable per commit, not lost when the session ends.
• Coordination in refs/h5i/msg. When multiple agents collaborate, handoffs, review requests, risk flags, and acknowledgements live in a shareable ref rather than in chat scrollback.
• Captured automatically by hooks. This is what keeps it from being manual bookkeeping. In Claude Code, h5i hook setup --write wires SessionStart, PostToolUse, Stop, and UserPromptSubmit hooks; the verbatim human prompt is captured by the UserPromptSubmit hook (and wins over any agent-supplied --intent), while Reads become OBSERVE traces and Edits become ACT traces. Codex integrates through its own SessionStart and Stop hooks and mines its session log. The record accrues as a byproduct of work.
• Shareable like any Git data — but only on purpose. Because the data lives in refs/h5i/*, a plain git push does not move it. You publish it explicitly with h5i share push and fetch it with h5i share pull. (That property is also the first failure mode below.)

How it compares to adjacent approaches

Several existing practices touch parts of this problem. Each does something genuinely well; none closes the per-commit, agent-authorship gap on its own.

• Commit-message conventions and trailers (Conventional Commits, Co-authored-by:, Assisted-by: trailers). Good: zero new infrastructure, lives in the commit, human-readable. Gap: human-authored, unstructured, and gameable — a trailer is a claim, not evidence, and it cannot record what the agent observed or which tests tied to the intent.
• PR templates and descriptions. Good: a natural place for intent and a reviewer checklist, and people already read them. Gap: out of band from the per-commit history, written once per PR rather than per change, and effectively unqueryable across a repo's history.
• MLOps / experiment lineage (MLflow, DVC, Weights & Biases). Good: rigorous lineage for model and data — runs, parameters, datasets, metrics — and the mature answer for training reproducibility. Gap: it tracks the lifecycle of a model being built, not the per-commit provenance of a coding agent changing your application source.
• CI artifacts and test reports. Good: trustworthy, machine-generated evidence that tests ran and what they produced. Gap: the evidence is bound to a pipeline run and a ref, not to the prompt or intent — it answers "did the build pass" but not "did the change that claimed to fix X exercise X."
• Vendor session transcripts. Good: the richest raw record of what the agent did, straight from the tool. Gap: per-vendor, often ephemeral, and not in your repository — you cannot git log it, review it next to the diff, or guarantee it survives the session. The useful abstraction is not one vendor's transcript format; it is a stable record of the six fields, stored where your code is.

The honest summary: AI-aware version control is not a new category competing with these. It is the per-commit, repo-resident join the others leave out — connecting agent and prompt to the context observed and the tests that verified it, in a form normal Git tooling can carry.

Failure modes and tradeoffs

A page that only listed benefits would be the kind of marketing this approach is supposed to make obsolete. The real limits:

• Provenance rot if refs are not shared. Because refs/h5i/* is not moved by a plain git push, a team that never runs h5i share push ends up with provenance trapped on one laptop. The sidecar design that keeps the record out of your branches is the same design that lets you forget to publish it.
• Gaming. Captured prompts and intents are not proof of good faith. A model can write a tidy prompt and a clean message around a careless change. The deterministic fields — was the file observed before it was edited, did the diff exceed the prompt's scope, did the tests actually run — resist gaming better than free text, but no record makes review optional.
• Rebase and squash lose per-commit notes. Git notes attach to a specific commit SHA. Squash-merging or rewriting history orphans the notes on the original commits, so a squash-heavy workflow has to decide what provenance survives the collapse. This is a real interaction cost, not a footnote.
• Discipline and tooling cost. The capture is automatic only after the hooks are wired and only for the agents that are integrated; manual commits and unintegrated tools fall back to a fallback --intent flag or nothing. There is a setup step, and there is a habit to maintain.

These are tradeoffs, not disqualifiers. They argue for treating the provenance refs as first-class shared state — pushed, reviewed, and backed up like any other branch — rather than as a local convenience.

A worked example

Concretely, the workflow is a one-time human setup followed by automatic capture. After the two setup commands, no one types the record by hand; it accrues as the agent works, and the six fields surface on demand.

# --- one-time human setup ---
$ h5i init                      # attach the sidecar: .git/.h5i/ + refs/h5i/*
$ h5i hook setup --write        # wire Claude Code hooks (idempotent)
                                #   Codex: h5i hook setup --target codex

# --- then, during a normal Claude Code or Codex session, capture is automatic ---
#   agent identity + model + prompt  ← UserPromptSubmit hook (verbatim prompt)
#   context observed                 ← OBSERVE traces from each Read
#   action / tool trace              ← ACT traces from each Edit / Write
#   the agent records the commit with provenance and test metrics:
$ h5i capture commit -m "fix: validate token expiry" \
      --model claude-sonnet-4-6 --agent claude-code --tests --audit

# --- surfacing the six-field record ---
$ h5i recall log --limit 5      # AI history: agent + model + prompt + test result
$ h5i recall blame src/auth/token.py --show-prompt
                                # per-line authorship with the prompt behind each commit
$ h5i audit review              # triage funnel: uncertainty, churn, scope, risk flags
$ h5i share push                # publish refs/h5i/* (plain git push does NOT)
$ h5i share pr post             # sticky GitHub PR comment: context + tests + review

The output of those recall and audit commands is the point. Instead of asking a reviewer to infer intent from a patch, AI-aware version control hands them the patch, the prompt it was meant to satisfy, the context the agent observed, the tests tied to that intent, and the risk signals that say which parts deserve attention first. It is not a replacement for review; it is a better review packet — and a queryable audit trail when someone later asks why a change happened.

When you need it

The threshold is simple. One-off autocomplete survives on ordinary Git hygiene. You need AI-aware version control when AI-generated change becomes routine — when an agent edits multiple files, runs tools, hands off work, and makes architectural choices across a long session, often enough that "why did the agent do this?" is a question your team will actually ask after a bad merge. If it is, capture the answer before the merge, not after.

FAQ

What is AI-aware version control?

AI-aware version control is version control that records not only what changed but who and what produced the change when an AI agent is the author: the agent identity, the model, the prompt, the context the agent observed, the actions it took, the tests that verified it, and the review or risk signals. Plain Git records content, author, and message; a diff structurally cannot hold the rest. AI-aware version control captures it as Git-native data — git notes plus sidecar refs — not a separate SaaS.

How is AI-aware version control different from plain Git?

It is a layer on top of Git, not a replacement. Commits, branches, git log, git diff, pull requests, and CI keep working unchanged. The difference is that AI-specific provenance — model, prompt, observed context, test evidence, review signals — is stored in durable, queryable records (git notes and sidecar refs) tied to each commit, so the answer to "why did the agent do this?" travels with the repo.

What are the six fields AI-aware version control records?

Agent identity, model, prompt or intent, the context the agent actually observed, the action or tool trace, test evidence, and review or risk signals. The commit author and message no longer identify the real author or explain the change once an agent acts on a prompt, so the record has to follow the new unit of authorship.

Isn't a green CI run enough provenance for AI-generated code?

No. A green CI run proves the tests passed at a point in time, but it is tied to a run, not to the prompt and intent that motivated the change. It cannot tell a reviewer which files the agent inspected, what it assumed, or where it flagged uncertainty. AI-aware version control ties test evidence to the prompt and context, not just to a pipeline run.

Can I get AI-aware version control without adopting a new system of record?

Yes. You can get it today on top of Git using git notes for per-commit provenance and sidecar refs (refs/h5i/*) for reasoning and coordination. h5i is one open-source implementation: it captures the record automatically via hooks and shares it with h5i share push and h5i share pull, since refs/h5i/* are not moved by a plain git push.

Does AI-aware version control work with both Claude Code and Codex?

Yes. The useful abstraction is not one vendor's transcript format; it is a stable record of agent, prompt, context, action, test, and review. h5i integrates with Claude Code via hooks and MCP, and with Codex via its SessionStart and Stop hooks plus the prelude, sync, and finish commands.

Conclusion

The diff was never the whole story; it was just the part Git could store. For decades that was enough, because the author in the commit was also the author in fact. Coding agents broke that equivalence — the unit of authorship is now an agent acting on a prompt with observed context — and the version-control record has to follow it. The missing record is concrete and small: six fields, captured at the moment of authorship, stored next to the commit, queryable later. You do not need a new system of record to hold them; Git notes and sidecar refs already can. The work that remains is not inventing a category but adopting the discipline of capturing what review and audit will eventually need — and, just as importantly, sharing it so it does not rot on one machine.

Sources and verification

This article avoids vendor-specific claims that were not checked against primary docs or local h5i CLI behavior.

• Git notes documentation
• Git hooks documentation
• Claude Code hooks reference