Toolchain Parity Between Agent VMs and Developer Machines
Matching agent VMs to developer toolchains stops failures before CI.

Toolchain parity between agent VMs and developer machines is a prerequisite for trustworthy pull requests. Agents need the same checks, dependencies, services, and diagnostic coverage that make developer changes reviewable. Without that baseline, even better reasoning leaves environment failures to reach CI and take up reviewers’ time.
Why environment gaps — not model quality — cause agent pull requests to fail review
A reviewer opens a diff and finds that the change failed because a required check never ran. The review becomes an investigation into the agent’s working conditions. Before judging the logic, the reviewer must find out whether the agent could test it properly. That uncertainty costs more than a pipeline run.
Coding agents have moved from autocomplete to orchestration, planning work, executing it in cloud environments, and returning finished changes for review. That shift makes the environment part of the delivery process. When the VM lacks the hooks, dependencies, or services that CI expects, its apparent success is misleading. Toolchain mismatch is therefore the primary cause of preventable agent PR failures. A red push wastes a cycle, while repeated hook violations or missing dependencies weaken confidence in subsequent agent work.
What "parity" actually means across the four layers that break agent PRs
Parity has four layers, each a distinct place to diagnose a failure. The first is pre-commit hooks. A formatter, linter, or policy check that runs on developer commits but not agent commits creates an enforcement gap. The second is dependency snapshots, where packages installed during a task can produce a dependency graph different from the one pinned in the repository. A passing result inside that VM does not establish that CI will pass.
The third layer is service availability. An agent that needs a database, message broker, or internal API to test a change must find those services in its environment. The fourth is observability, which reveals what executed and how long each phase took. These layers make parity a testable property of the working environment by providing evidence that lets teams reliably distinguish a missing service from a dependency or hook failure.

Why pre-commit hooks are the highest-leverage parity investment
Pre-commit hooks enforce checks at the point closest to the commit. Consider a linting hook present on developer machines but absent from the agent VM. The agent commits a violation, CI rejects it, and the reviewer receives a broken PR. On a developer machine, the same hook would have blocked the commit before it reached the remote. The missing hook moves an inexpensive local failure into a full pipeline run and a review interruption.
Hooks must run inside the agent VM. A requirement described in instructions is not the same as a command that blocks an invalid commit. Claude Code’s hook system shows how shell commands can run before or after agent actions to enforce the team’s checks. Skills, subagents, and plugins can package repeatable workflows, allowing the mechanisms used to distribute developer hooks to reach agent environments too. Hooks take time to run, but a slower valid commit costs less than a broken PR that needs another run and more of a reviewer’s time.
How agent VMs actually start, and why mid-session installs break the snapshot guarantee
Agent VMs start through setup scripts, filesystem snapshots, or rebuild triggers. Those mechanisms determine what is available when work begins. If a tool is absent from the snapshot, installing it later fixes only the current session, leaving the baseline for subsequent runs unchanged.
The failure repeats in a predictable sequence. An agent starts, discovers a missing hook tool, installs it, and commits successfully. Because the snapshot was never updated, the next agent starts without that tool again. The dependency graph at commit time has also departed from the graph against which the snapshot was tested, leaving CI and the agent with different working conditions.
The timing of installation is therefore a design decision. Background installation from session start can combine CI parity with a fast first action, but it remains distinct from placing dependencies in a tested snapshot. A frontier model in an under-provisioned VM cannot compensate for that missing baseline.
Measuring bootstrap time as an engineering discipline, not a feeling

Bootstrap time becomes manageable when it is attributed to individual tools. An average for the whole session collapses two different experiences into one number. A developer watching a new environment start is waiting differently from an agent blocked on output mid-task. Teams should measure the time spent watching startup separately from the time spent waiting mid-task.
The reduction from a 422-second bootstrap to 75 seconds illustrates the method. Timing each tool inside the pre-commit hook established where startup time went, and targeted optimizations followed across subsequent changes. Attribution preceded optimization. Predictions stated before each change and a manifest recording the result afterward make improvements accountable to measurement.
That discipline becomes more valuable as the toolchain grows. Without per-tool timing, a team cannot tell whether bootstrap is getting slower or which check is to blame. Maintaining parity requires both a complete toolchain and evidence about the cost of running it.
Why Bash-level telemetry misses what git hooks execute, and how PATH shims close the gap
A wrapper around the agent’s shell session does not expose every tool involved in a commit. Git invokes the pre-commit hook directly, and the tools called by that hook sit outside the shell-level wrapper’s view. The telemetry may show that an operation took a long time without showing which tool caused the delay.
PATH shims wrap tool commands, emit telemetry, and then pass execution through to the real binaries. They preserve the existing checking policy. They let teams connect a slow or failing commit to the hook tool that actually ran. The same instrumentation supports bootstrap attribution, so startup measurement and execution diagnostics share infrastructure.
Complete coverage also requires three distinct views. Agent telemetry records what the agent decided, execution telemetry records which commands ran, and lifecycle telemetry records when sessions started and ended. None substitutes for the others. Together, they provide the evidence needed to judge whether parity is holding.
How platform behaviour changes underneath a fixed environment — and what to do about it
GitHub access illustrates how a fixed toolchain can encounter changing platform behaviour. A single engineering estate that ran Claude Code cloud sessions over 2026 recorded blocked gh GraphQL access and times when REST requests were either rejected with 403 responses or allowed. Its skills documentation had to be corrected again and again as access changed. A gather script also passed a 403 response through as exit=0 data without detecting the failure.
Other changes affected the environment more directly. Around 2026-10-03, the VM image began preinstalling gcloud, bypassing a wrapper built to install its own binary. Brokered calls failed until the wrapper was changed to wrap the preinstalled binary instead. Separately, the platform preset CLOUDSDK_AUTH_ACCESS_TOKEN in a way the team could not reliably suppress, requiring per-invocation unsetting or wrapper logic that the proxy could bypass. Even installation ownership was a changing assumption.
Instructions were another source of drift. ADR-0019 relied on a measured observation that Claude Code did not load repository-level AGENTS.md, but later platform behaviour invalidated that premise. Rerun environment conformance tests on a schedule, because documentation describes intended behaviour and may differ from current behaviour. ADR-0021’s design response was to keep environments few and generic, with variation in versioned scripts. A platform change could then be handled in one script rather than through repairs to many hand-configured VMs.
Choosing an agent harness that exposes enough surface area to build parity in
Harness selection determines which parity controls a team can implement. Claude Code exposes 33 hook events and Dynamic Workflows, giving it the deepest programmable surface among these options for pre-commit and lifecycle instrumentation. Its default model choice is limited to Anthropic’s Claude models, although unsupported third-party gateways allow non-Anthropic models. That is a product constraint as well as an infrastructure consideration.
Cursor’s Builds, shipped 13 August, takes a different approach through pre-configured cloud-agent environments. Cursor’s own environment measurements show a time to first token roughly three times faster than with cold-start setup for each session. Requiring successful builds before activation places environment readiness before the agent session, making Builds a snapshot-first approach at the product level.
OpenCode supports more than 75 providers, making it a practical option when model flexibility is the constraint. The team must assemble the environment primitives itself. Yet no individual harness resolves governance across all the others. Cursor hooks control what happens in Cursor sessions, while Claude Code audit logs cover Claude Code sessions. Teams that use more than one harness thus need a platform-level layer to apply the same controls across them.
Running harness-agnostic agent VMs with consistent governance across the team
A shared platform layer lets teams configure environments outside each harness. Every run can start in its own isolated VM, pre-loaded with the team’s dependencies and tools, whether Claude Code, Codex, Cursor, or OpenCode performs the work. The baseline stays consistent across harness choices. Agents can install packages, run services, drive a browser, and verify changes in an environment functionally equivalent to a developer machine.
The same layer can provide common attribution. Analytics that track runtime by source, harness, model, and credential let teams see how the way they configure environments and choose agents connects to PR outcomes. Runs triggered from Slack, Linear, GitHub, or GitLab can also return work to the existing review queue without changing where engineers initiate it.
Harness-agnostic governance provides a common place to absorb updates to platform behaviour. When a harness changes, the platform layer can handle it without teams having to reconfigure every environment or repeat the same governance work for each harness.
A practical sequence for teams building toolchain parity from scratch
List every pre-commit hook that runs on developer machines and establish which also runs in the agent VM. The difference is the most immediate parity debt affecting reviewer trust. Next, move the installations required by those hooks into the snapshot, and test that snapshot against CI before agents use it. This establishes the baseline before optimizing or expanding it.
Once the baseline is sound, instrument bootstrap time for each tool and emit the timings to a manifest. Add PATH shims for hook-invoked tools so their execution appears in the observability record. Teams should then run environment conformance tests on a schedule to check that the platform still behaves as the baseline needs it to.
Keep the number of environments small and keep them generic as this work grows. Keep variation in versioned scripts so that a change to a shared script can fix environments when platform behaviour changes. Once hooks, snapshots, and observability are in place, multi-harness governance can bring those controls to the whole team. Teams must maintain this operating discipline as tools, dependencies, and platforms change for agent PRs to stay trustworthy.


