2.9 KiB
name, description
| name | description |
|---|---|
| parallel-worktree-path-hazard | Use when several agents edit the same repo in different git worktrees at once, or when an edit lands in the wrong checkout: relative tool paths resolve to the session cwd, not the shell cwd. |
Use when several agents (or you across two checkouts) edit the same repo in different git worktrees at once, or when an edit/query lands in the wrong checkout.
The silent failure: relative tool paths resolve to the SESSION cwd
read / edit / write / grep resolve a relative path against the session working directory — never against the cd inside a neighboring bash call, and not against a ../other-worktree/... prefix either (that gets normalized back into the session tree). So after cd ../wt-B && grep … you can read path="docs/page.md" and get wt-A's copy.
Why it survives "I just read it to check": the returned path is printed workspace-relative and the file name is identical in every checkout, so the output looks like a correct read of the tree you meant. Only content that differs between the checkouts betrays it.
Rules:
- Absolute paths for every tool call that targets a worktree other than the session's. No exceptions for quick reads.
- Confirm the checkout from content you know differs (a heading, a status line), not from the echoed path.
- A
readerror like "Did you mean .AGENTTRASH/" is a signal the relative path resolved into the session tree — re-issue absolute. - Same trap for
bash: it starts each call in the session cwd, socdtwice per call or use absolute paths there too.
Landing a change when the session worktree is stale
git diff --name-only HEAD origin/main first. If main moved a file you are editing, your edit's base is wrong even though the file "looks fine" — do not commit on the stale base.
git worktree add ../wt-clean -b <type>/<slug> origin/main; copy the new files in.- Re-apply the edit against the clean tree's version with absolute paths, then read it back absolutely to prove which tree changed.
- Run the suite inside the clean worktree; commit there.
- Remove your own duplicate edit from the session worktree by editing it away (
CUT/PUT).git checkout -- <path>and branch switches are policy-blocked in shared workspaces and should stay blocked — they discard edits other agents rely on. - Never carry the same uncommitted edit in two worktrees at once; if you must keep both trees, keep a task that reconciles them.
Multi-agent hazards in one shared worktree
- Another agent can stage, commit, or check out files under you; re-read a file immediately before editing it if any tool result hinted at intervening change.
- Untracked scratch you drop in a shared tree (reports, notes,
.AGENTTRASH/entries) is visible to everyone and can be committed by them. Put throwaway artifacts outside the checkout. - Never
git clean -f,rm -rf, or branch switching to "get a clean state" in a tree another agent is using.