main-bash-cwd-persists-nested-worktree

name	main-bash-cwd-persists-nested-worktree
description	Prevent and diagnose nested git worktrees created at the wrong filesystem path when orchestrating parallel work from the main Claude Code agent. Use when (1) you ran `git worktree add .claude/worktrees/<name> ...` from the main agent's Bash tool, (2) `git worktree list` shows the new worktree at an unexpected nested path like `.claude/worktrees/<previous-worktree>/.claude/worktrees/<name>` instead of the intended top-level location, (3) a subagent dispatched to the intended path reports "worktree path mismatch" or operates from a longer nested path. Root cause: the main agent's Bash tool **persists cwd between calls** (per its docstring: "The working directory persists between commands"). An earlier `cd /abs/path && cmd` changes the main shell's cwd; a later `git worktree add <relative-path> ...` resolves against that persisted cwd rather than the project root, silently creating nested layouts. This is the **inverse** of the subagent variant (subagent-bash-cd-wrong-worktree) — subagent shells reset per call, main shell doesn't. **Also covers the sibling case (v1.1): from the project ROOT, a `git worktree add ../<name> ...` escapes UP to the repo's PARENT dir (e.g. `/Users/x/Documents/<name>`), OUTSIDE the `.claude/worktrees/` convention — and a later Read/Edit/Write using the assumed `.claude/worktrees/<name>` absolute path fails with a MISLEADING "file does not exist" (the file exists, the worktree is just elsewhere).** **Also covers (v1.2): a drifted cwd makes `git diff A B -- <repo-relative-path>` return EMPTY while `git diff A B --stat` (no pathspec) shows the same file as changed — because pathspecs resolve relative to cwd but `--stat` reports against the repo root. Tell: a pathspec-filtered git command comes back empty yet `--stat` / `git show <rev>:<path>` disagree → suspect cwd drift, not the commit/branch/range.**
author	Claude Code
version	1.2.0
date	"2026-07-02T00:00:00.000Z"
disable-model-invocation	true

Main-agent Bash cwd persistence → nested worktrees at wrong path

Problem

You're orchestrating multiple parallel-dispatch subagents, each in its own git worktree. From the main agent's Bash tool you do:

git worktree add .claude/worktrees/track-A origin/main -b feat/track-A
# ... dispatch Track A subagent ...
# ... investigate codebase ...
cd /path/to/repo/.claude/worktrees/track-A && grep -rn "foo" src/   # persists cwd!
# ... time passes, you dispatch Track B ...
git worktree add .claude/worktrees/track-B origin/main -b feat/track-B

You expect track-B at <repo>/.claude/worktrees/track-B. Instead git worktree list reports it at <repo>/.claude/worktrees/track-A/.claude/worktrees/track-B — nested inside the Track A worktree.

Branches, commits, and pushes still work (git resolves them via .git/worktrees/<name> metadata regardless of disk location), but:

• Dispatched subagents pointed at the intended path will report "worktree path mismatch."
• Cleanup (git worktree remove .claude/worktrees/track-B) from the project root won't find it.
• Per-worktree caches, venvs, and uploads end up under the wrong parent directory.

Context / Trigger conditions

• Main agent runs more than one git worktree add in the same session.
• Between worktree-add calls, the main agent ran a Bash command that included a cd to a path other than the project root.
• The later git worktree add uses a relative path (e.g., .claude/worktrees/<name>).
• Symptom: git worktree list shows nested paths, OR a subagent given the intended path can't find its worktree, OR pwd inside a subagent reports a longer-than-expected path.

The Bash tool's own description says it: "The working directory persists between commands, but shell state does not." This is the opposite of subagent Bash, which resets cwd per call (see subagent-bash-cd-wrong-worktree).

Solution

Three reliable mitigations, in order of preference:

1. Always pass an absolute path to git worktree add from the main agent.

   git worktree add /Users/<user>/Documents/the-handover-repo/.claude/worktrees/track-B origin/main -b feat/track-B
   

   This is the cleanest fix and is robust against any cwd drift.

2. Reset cwd to project root in the same chained call before any git worktree add with a relative path:

   cd /Users/<user>/Documents/the-handover-repo && git worktree add .claude/worktrees/track-B origin/main -b feat/track-B
   

3. Create ALL worktrees up-front in a single batch at the start of the session, before any other Bash commands that might cd.

When dispatching parallel subagent prompts, also bake an absolute-path verification step into each prompt:

First action: verify worktree path matches expectation.
cd /Users/<user>/Documents/the-handover-repo/.claude/worktrees/<name>
pwd  # MUST end in <name>; STOP and report if it doesn't
git rev-parse --abbrev-ref HEAD  # MUST be feat/<name>

Verification

After creating a worktree, immediately:

git worktree list | grep <name>

The reported path must NOT be nested under another worktree. If it is, before any subagent dispatch:

# Move it to the correct location (requires admin; or just remove + re-add)
git worktree remove <wrong-nested-path>
git worktree add /abs/path/to/.claude/worktrees/<name> origin/main -b feat/<name>

Example

What went wrong (Session 15, the-handover-repo):

# Main agent at /Users/<user>/Documents/the-handover-repo (project root)
git worktree add .claude/worktrees/s15-lows-bundle origin/main -b feat/s15-lows-bundle
# → created at .../the-handover-repo/.claude/worktrees/s15-lows-bundle ✅

# Later, investigation:
cd /Users/<user>/Documents/the-handover-repo/.claude/worktrees/s15-lows-bundle && grep "_JINJA_ENV" src/
# → main shell cwd is now inside s15-lows-bundle worktree

# Even later, second worktree:
git worktree add .claude/worktrees/s15-csv-upload origin/main -b feat/s15-csv-upload
# → created at .../s15-lows-bundle/.claude/worktrees/s15-csv-upload ❌

Fix applied in that session: none mid-session (PRs all pushed correctly via branch refs). The lesson is to use absolute paths next time.

Variant (v1.1): ../<name> escapes UP to the repo parent, then a file-tool call "file does not exist"

A second, even-easier-to-hit shape — cwd was correct (the project root), the relative path itself was wrong:

cd /Users/x/Documents/myrepo                       # at project root — cwd is fine
git worktree add -b docs/foo ../foo origin/main    # ../ escapes to /Users/x/Documents/foo ❌
#   intended .claude/worktrees/foo, but ../foo = the repo's PARENT dir
tail ../foo/docs/file.md                            # works HERE — same bash, cwd still repo root
# ... later, an Edit/Write/Read with the ASSUMED path:
# Edit /Users/x/Documents/myrepo/.claude/worktrees/foo/docs/file.md
#   → "File does not exist"  ← MISLEADING: the file exists at /Users/x/Documents/foo/...

The ../<name> reads like "a worktree beside the others" but .claude/worktrees/ is two levels down, so ../ goes the wrong direction entirely. The trap is the downstream symptom: the worktree was created fine and even tail in the same bash worked (cwd-relative), but the next file-tool call uses a hard-coded absolute path under .claude/worktrees/ and reports the file missing — pointing you at the file, not at the worktree's real location.

Guards (in addition to the absolute-path rule above):

1. To match the convention, pass the full intended path, not ../: git worktree add .claude/worktrees/<name> <ref> (from the project root) or the absolute equivalent.
2. Resolve the worktree's REAL path before constructing absolute paths for Read/Edit/Write:

   git worktree list | grep <name>   # the path column is the source of truth
   

   Use that exact path — never an assumed .claude/worktrees/<name> — when the next tool call needs an absolute path.
3. If you see a file-tool "file does not exist" right after a git worktree add, suspect the worktree location before suspecting your file path.

Variant (v1.2): drifted cwd makes git diff -- <repo-relative-path> return EMPTY while --stat shows the change

Same root cause (main-shell cwd persisted into a subdir after an earlier cd), different — and very disorienting — symptom: git pathspecs are resolved relative to cwd, but --stat/--name-only without a pathspec report against the repo root. So the two disagree, and the file looks both changed and unchanged at once:

# earlier in the session, cwd drifted into a subdir:
cd /repo/<analytics_pkg>/cloudrun/<dashboard_app> && python -m pytest ...   # persists cwd

# later, trying to inspect a commit that DID touch bq_queries.py:
git show --stat HEAD | grep bq_queries          # → "bq_queries.py | 62 ++++--"  (file IS in the commit)
git diff HEAD~1 HEAD -- <analytics_pkg>/cloudrun/<dashboard_app>/bq_queries.py
# → EMPTY  ❌  (pathspec resolved from cwd = .../<dashboard_app>/<analytics_pkg>/... which doesn't exist)
git show HEAD:<analytics_pkg>/.../bq_queries.py | grep <symbol>   # → matches (object-name form is cwd-INDEPENDENT)

The tell is the contradiction: git show --stat / git diff A B --stat (no pathspec) lists the file as changed, but git diff A B -- <repo-relative-path> returns nothing, and git show HEAD:<path> (a <rev>:<path> object name, which is always repo-root-relative) shows the content fine. When a pathspec-filtered git command comes back empty but the unfiltered --stat disagrees, suspect cwd drift before suspecting the commit, the branch, a .gitattributes -diff driver, or a bad range.

Guards:

1. pwd when a pathspec-filtered git result surprises you — the harness's own "Shell cwd was reset to …" tool-result lines are reporting the drift, not just noise.
2. Prefer a leading cd /abs/repo/root && git diff … -- <path> for any pathspec-filtered inspection, OR use the cwd-independent git show <rev>:<path> / --stat (no pathspec) forms.
3. A cd inside a compound Bash command (cd X && cmd) still mutates the persistent cwd for every later call — it is not scoped to that one command.

Notes

• Branch and push behavior are NOT affected because git tracks worktrees by .git/worktrees/<name> metadata, not by filesystem path. So this bug is silent — you only notice when a subagent reports a path mismatch or when you try to git worktree remove from the project root.
• Variant v1.2's pathspec trap is not worktree-specific — it bites in any repo the moment cwd drifts into a subdir — but the fix is identical (absolute paths / repo-root cd / cwd-independent git forms), so it lives here with the other cwd-drift symptoms.
• This is a property of the Claude Code Bash tool specifically. Other tools (e.g., Edit, Write, Read) don't have a persistent cwd — they take absolute paths or resolve against the project root.
• The subagent variant (subagent-bash-cd-wrong-worktree) describes the opposite failure mode: subagent shells reset cwd per call, so a cd followed by git commit in a separate Bash call commits to the parent repo's HEAD. Both are real, and the fix is the same: use absolute paths and verify with pwd before any state-changing command.

References

• Claude Code Bash tool docstring: "The working directory persists between commands, but shell state does not."
• Related skill: subagent-bash-cd-wrong-worktree — the inverse failure mode in subagent shells.
• Related skill: using-git-worktrees — general worktree workflow.