A pull request changes three lines in a prompt. The source diff is tiny. The resulting agent run adds a tool call, skips a planning step, changes its recovery path, and takes twice as long. Which diff describes the risk more accurately? Both do—but they describe different things. I maintain AgentInspect, an open-source TypeScript toolkit for inspecting agent runs locally. I designed its run-diff workflow around a simple idea: code review tells us what the developer changed; execution evidence tells us what the agent did differently. The examples below use synthetic fixtures verified against agent-inspect@6.17.4. Source changes and behavior are no longer tightly coupled In ordinary deterministic code, a source diff is often a strong predictor of runtime change. Agent systems add several moving parts: prompts and system instructions; model versions and sampling behavior; tool descriptions and schemas; retrieval content; external services; memory and conversation state; orchestration and fallback policies. A large refactor can preserve the same trajectory. A one-word prompt change can alter tool selection. Identical code can behave differently when a model or external result changes. That does not make code review obsolete. It means the review unit needs another layer: source diff behavior diff ----------- ------------- what was edited? what path changed? what code owns the change? where did runs diverge? is the implementation sound? which steps/errors/outputs differ? Capture two comparable runs A useful behavioral comparison needs a deliberate baseline and candidate: baseline same synthetic input pinned or recorded configuration known-good trace candidate same synthetic input intended code/prompt/model change newly captured trace Control what you can. Record what you cannot. If the input, retrieval corpus, model, and tool fixtures all change at once, the diff may be accurate but difficult to interpret. With two local run IDs, compare them from the CLI: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect The synthetic fixture output begins with the summary and first divergence: Run diff Left: minimal-success Right: minimal-error Summary: Differences: 4 Errors: 0 Warnings: 3 Info: 1 First divergence: run-status at (run) left: success right: error That “first divergence” is often more actionable than a long list of event differences. It gives the reviewer a starting point for the causal investigation. Read added and removed steps as structural evidence The same fixture reports: Differences: [warning] run-status Run completion status differs left: success right: error [info] duration Run duration differs left: 120 right: 70 [warning] step-removed plan Step only in left run: plan left: step_root right: (undefined) [warning] step-added failing-step Step only in right run: failing-step left: (undefined) right: step_fail The evidence says that plan appears only in the left run and failing-step only in the right. It does not automatically say why. Possible explanations include: the candidate genuinely skipped planning; a step was renamed; instrumentation boundaries changed; the agent chose a different path; the run ended before reaching the step. This is why a behavioral diff is an input to review, not an automatic verdict. Pair it with the source diff and inspect the execution tree around the divergence. Focus the diff on the question you are asking The CLI can limit the comparison to a specific check dimension. To inspect only structure: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect \ --check structure That removes status and duration noise and leaves the added/removed steps. For a performance-oriented review: npx agent-inspect diff minimal-success minimal-error \ --dir .agent-inspect \ --check timing \ --duration-threshold 20ms The command also supports JSON output for automation, --ignore-duration, focus modes, and verbose output. A practical rule is to begin with the broad human-readable diff, then narrow the view when you know which hypothesis you are testing. Timing differences require controlled interpretation The fixture reports 120 versus 70 milliseconds. It would be a mistake to generalize that single synthetic delta into a performance claim. Agent latency can vary with network conditions, cache state, provider load, token volume, and concurrency. A timing diff is most useful when: the tool and model calls are stubbed in a deterministic test; the difference is large relative to expected noise; multiple representative runs show the same pattern; the structural diff explains the extra work. Use --duration-threshold to suppress insignificant changes, but derive the threshold from your environment. Do not choose a number merely because it makes a current test pass. A run diff does not rerun the agent AgentInspect’s diff is a read-only comparison of persisted traces. It does not replay either agent, invoke a model, or prove that the difference will recur. That property is useful for review: the comparison is deterministic for the two stored artifacts. It is also a limitation: representative capture remains your responsibility. I think of the workflow as three separate actions: execute -> capture evidence compare -> describe observed differences judge -> decide whether the change is acceptable Only the middle action is the run-diff engine. Add a behavior-evidence section to pull requests For changes that can materially affect an agent path, a compact pull-request section can make review faster: ## Agent behavior evidence - Fixture: `refund-eligible-order` - Baseline run: `refund-before` - Candidate run: `refund-after` - Expected change: prefer cached policy when current - First divergence: `retrieve-policy` replaced by `load-policy-cache` - Contract result: pass - Evidence artifact: attached CI bundle - Reviewer note: no production or customer data used This is intentionally concise. The full trace should remain an artifact, not be pasted into the pull-request description. The most important field is “expected change.” It tells reviewers whether an observed divergence is intentional. Without that statement, the diff is merely a list of facts. Combine diffing with contracts A diff answers “What changed?” A contract answers “Did a declared invariant still hold?” Use both. Suppose a candidate run replaces remote retrieval with a cache hit. The structural diff should show the path change. A contract might still require: successful completion; no forbidden write tool; validation before the final response; a bounded tool-call count. The candidate can therefore differ from the baseline and still pass the invariant gate. This is healthier than either extreme: rejecting every structural change; or accepting every change that ends with plausible prose. What to compare in practice Choose fixtures around decisions, not around random traffic. High-value comparisons include: Prompt or instruction changes Did tool selection, ordering, retry behavior, or token usage change? Model upgrades Does the new model reach the same goal with a different trajectory? Does it invoke a fallback more often in controlled cases? Tool-schema changes Did a renamed or re-described tool disappear, get replaced, or start failing? Orchestrator refactors Did parent-child structure, concurrency, or error propagation change even if final answers stayed stable? Retrieval changes Did the run add or skip retrieval, or generate before the required evidence step? For each case, pair the behavioral observation with a domain-specific quality check. A shorter path is not necessarily a better answer. Review what executed, not only what was edited Code diffs remain the foundation of software review. Agent systems need an additional artifact because runtime behavior depends on more than source text. A disciplined workflow is straightforward: capture a known-good baseline for a synthetic, representative fixture; capture the candidate with controlled inputs; inspect the first divergence and focused structural changes; run stable deterministic contracts; preserve the evidence with the pull request; apply human and semantic judgment to the result. This does not eliminate nondeterminism. It gives reviewers something more precise than “I tried the prompt and it looked better.” The tagged release and fixtures used for this article are available on GitHub. If you adopt behavior diffs in code review, begin with one high-risk fixture and learn which differences your team actually finds actionable.