Worktrees never check out a shared branch — enforced at the tool boundary¶
- Date: 2026-08-31
- Status: Accepted
- Tags:
tooling
Context¶
git worktree add <path> main checks main out into the new worktree. Git permits a branch
to be checked out in exactly one tree at a time, so from that moment the primary repo can no
longer switch to main — the checkout errors, and the usual recovery leaves the primary repo
on a detached HEAD.
Git reports nothing wrong at any point. The damage is entirely downstream, and on an infrastructure repo it is expensive:
- Terraform plans and applies run from a tree with no branch, so the config being applied cannot be named and does not necessarily match what the operator believes is checked out.
- Branch-aware tooling — pre-commit branch-name checks, worktree-scoped helpers, anything
reading
symbolic-ref— misreads the tree or fails outright. - Applying from a
mainworktree is separately hazardous: main's config has no knowledge of another session's applied-but-unmerged resources, so a plan from there proposes deleting them. That failure mode already has its own history in this setup.
This was not hypothetical. On 2026-08-31 an agent created a worktree on main in a work
infrastructure repo to reconcile live cloud state back to the mainline. The primary repo was
forced detached, and the operator's terraform init/plan/apply runs stopped behaving
correctly. The symptom presented as "terraform is broken in this repo", several steps removed
from the cause, and cost real debugging time before the worktree was identified.
The correct move in that situation was always available and no harder: branch from the shared branch and give the worktree the new branch. Content is identical and the shared branch stays free. It simply was not the thing that came to mind under time pressure.
Documentation and memory notes are the obvious response, and they are insufficient here — the mistake is a one-line convenience that reads as correct at the moment of typing, and the feedback arrives minutes later in an unrelated tool.
Decision¶
I will enforce the rule at the tool boundary with a PreToolUse hook on Bash,
hooks/git-worktree-guard.py, wired in settings.json.
A worktree always gets its own branch.
| Command | Verdict |
|---|---|
git worktree add <path> main (or master, develop, trunk, production, prod) |
denied |
git worktree add --detach <path> <ref> |
denied |
git worktree add -b <topic> <path> [start-point] |
allowed |
git worktree add <path> <topic-branch> |
allowed |
git worktree add <path> (git derives a branch from the basename) |
allowed |
The denial message states the cause and hands over the corrected command, so the recovery is a paste rather than a re-derivation.
The guard fails open: a command it cannot tokenize is allowed through. This is deliberate and is the opposite posture from the terraform scope guard (0036), which fails closed. That distinction is the point and is documented in the file so it is not "fixed" later: the scope guard is a boundary with an adversarial reading, where an unresolvable command must be denied. This one is a footgun guard against a slip by a cooperating author, where blocking legitimate work over a quoting edge case costs more than the occasional miss. Guards should fail in the direction of their threat model, not uniformly.
This sync also records the removal of hooks/chain-aware-allow.py, superseded by the single
Bash grant authority decided in 0035. No new decision
is being made there; the mirror is catching up.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| Documentation and a memory note only | This is the status quo that failed. The mistake is a plausible-looking one-liner and the consequence surfaces later in a different tool, so recall at the moment of typing is exactly what cannot be relied on. |
| Fold the rule into the terraform scope guard | Conflates two threat models in one file. That guard fails closed by design; adding a fail-open concern to it invites someone to unify the posture and quietly weaken the boundary. |
A git hook in the repo instead of a harness hook |
No git hook fires on worktree add, and a per-repo hook would need installing in every repo. The mistake is agent behaviour, so the agent's tool boundary is the right place. |
| Detect the detached HEAD afterwards and warn | Recovery is cheap only if nothing has been applied yet. A warning after a terraform apply from a detached tree is too late to be worth much. |
Ban git worktree add entirely |
Worktrees are genuinely useful for parallel sessions and are used heavily. The problem is one argument, not the command. |
Consequences¶
Positive:
- The failure cannot recur through the agent path; the message converts a confusing multi-step debug into a one-line correction.
- Shared branches stay free for the primary repo, which is what makes parallel sessions across several worktrees workable at all.
- Removes one contributing path to applying from
mainand deleting another session's applied-but-unmerged resources.
Negative / Trade-offs:
- Fails open, so an obfuscated or unparseable command still gets through. Accepted: this guards a slip, not an adversary.
- The protected-branch list is hardcoded. A repo whose mainline is named something else is unguarded until the list is extended.
- One more
PreToolUseBash hook on every Bash call. Negligible individually, but the count is growing and the aggregate is worth watching.
Ongoing obligations:
- Keep the protected-branch set current if a new mainline convention appears.
- Preserve the fail-open/fail-closed distinction against well-meaning unification, in this record and in the file header.
python3 hooks/git-worktree-guard.py --selftestcovers 14 cases; extend it when the matching logic changes rather than testing by hand.
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.