# Agents - Worktree Workflows and Pre-PR Review Agent work in a linked git worktree diverges from the main checkout in three ways: the guard hook, the language server, and the review tool each need the worktree's own state. Treat the worktree's build and tests as ground truth, run commands with `git -C` and `make -C`, and run the human pre-PR review from the worktree before anything is pushed. ## Key points - A worktree-guard `PreToolUse` hook blocks file-edit tools on the default branch. Create a named worktree first. The `Bash` tool is not matched by the guard, so heredoc writes bypass it. Do not use that bypass. - A kill-switch environment variable in the repository settings env block exempts one repository from the worktree guard without disabling it everywhere else. - A language server rooted at a stale module reports diagnostics that contradict a linked-worktree checkout. The build and race-enabled tests in that worktree are the ground truth. - A concurrent agent that commits to the default branch during your work creates a diverged base. Run `git merge main` into your branch first, resolve there, verify, then fast-forward main. Keep the default branch clean. - The pre-PR review tool `crit` is worktree-aware by design. Its merge-base computation falls back for worktrees created from a bare repository. Untracked files enter the review scope. Only its own state directory is ignored. Verify such tool claims in source and empirically before you build process text on them. - The review session API exposes the diff scope on the `/api/focus` endpoint. The file-listing endpoint is a repository browser. It does not show the review scope. - A review launched from the feature worktree includes uncommitted changes. The pre-PR review can therefore run before any commit exists, including when the guard blocks a commit on the current branch. - Parallel lane worktrees let file-disjoint tasks run concurrently without merge conflicts. The precondition is a non-overlapping set of source files per lane. - Linked worktrees share one object store, but each worktree has an independent index. Staged changes cannot bleed between worktrees. Byte-identical tree hashes prove where a change actually lives. The commit graph can be healthy while only the working tree is wrong. - A linked worktree's `.git` file is a pointer with a host-absolute `gitdir` path. Git inside a VM guest therefore fatals. Mount the main repository's `.git` at the identical absolute guest path and add `safe.directory`. A commit made in the guest worktree then lands on the host branch. - In fresh shells, use `git -C <worktree>` and `make -C <worktree>`. A `cd` between tool calls is lost, and stray runs in the main repository measure the wrong change. - After delegated work returns, re-check that the edits landed under the actual working directory. Dual writes to main-checkout absolute paths hide the work until it is re-applied. - Verify a staged index as a real commit without committing to the branch: `sha=$(git commit-tree $(git write-tree) -p HEAD -m verify-candidate)` and then `git worktree add --detach`. ## How to apply 1. Create a named worktree before any edit. 2. Run every command against the worktree path: `git -C <worktree> ...` and `make -C <worktree> <target>`. Do not rely on `cd`. 3. When the language server disagrees with the worktree, run `go build` and `go test -race` there. Trust those results. 4. Before landing, run `git merge main` into the branch, resolve, verify, then fast-forward main. 5. Before opening a pull request, run the review tool from the feature worktree. The review covers committed, pending, and untracked files. Read the scope from `/api/focus`, not from the file browser. 6. To verify staged work in isolation, build a throwaway commit with `git commit-tree $(git write-tree) -p HEAD -m verify-candidate` and check it out with `git worktree add --detach`. 7. After a delegated task, confirm each edited file lives under the worktree path, not under the main checkout. ## Observations - [tooling] A guard hook that matches only file-edit tools leaves shell writes as a bypass. The correct path is a new worktree, not a heredoc. #worktrees (source: agent sessions, 2026-05) - [verification] Diagnostics from a stale language server root disagree with the worktree checkout. The worktree's build and race tests are the ground truth. #verification (source: agent sessions, 2026-07) - [git] Each linked worktree holds an independent index over a shared object store. Staged changes cannot bleed across, and tree hashes prove where a change lives. #git (source: agent sessions, 2026-08) - [git] A worktree `.git` pointer holds a host-absolute gitdir path, so guest git fatals until the guest mounts `.git` at the identical path. #virtualization (source: agent sessions, 2026-10) - [process] A `cd` between tool calls is lost. `git -C` and `make -C` keep every run inside the worktree. #shell (source: agent sessions, 2026-10) - [delegation] Delegated edits can land on main-checkout absolute paths. Re-check the working directory before you verify. #delegation (source: agent sessions, 2026-06) ## Relations - relates_to [[resources/documentation/Agents/Agents - One Workstream per Task]] (one worktree per workstream is the unit of isolation) - relates_to [[resources/documentation/Agents/Agents - Guards, Hooks, and Security Boundaries]] (the worktree guard is a hook-enforced boundary) - relates_to [[resources/documentation/Git - Coexisting with a Background Auto-Committer]] (merging main into the branch first when a concurrent agent commits) - relates_to [[resources/documentation/Agents/Agents - Parallel Orchestration and Delegation]] (delegated edits must land in the assigned worktree) ## Sources - Personal agent-session notes, April 2026 to October 2026.