git-worktrees

Make sure the work happens somewhere isolated, without fighting whatever isolation the environment already provides. The order matters: detect what you're already in, prefer native tooling, and only reach for raw git worktree as a last resort. Creating a worktree on top of an environment that already gave you one produces phantom state the harness can't see or clean up.

Step 0: Detect existing isolation first

Before creating anything, check whether you're already isolated.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

If GIT_DIR != GIT_COMMON, you're likely already in a linked worktree — but the same is true inside a git submodule, so rule that out first:

git rev-parse --show-superproject-working-tree 2>/dev/null

If that prints a path, you're in a submodule: treat it as a normal repo. Otherwise, GIT_DIR != GIT_COMMON means you're already in a worktree — skip creation and go straight to setup (Step 3). Report it: "Already in an isolated workspace at <path> on branch <name>" (or note a detached HEAD, which will need a branch created at finish time).

If GIT_DIR == GIT_COMMON (or you're in a submodule), you're in a normal checkout. Unless the user has already stated a worktree preference, ask before creating one:

"Want me to set up an isolated worktree? It keeps your current branch untouched while I work."

Honor an existing stated preference without re-asking. If the user declines, work in place and skip to Step 3.

Step 1: Create the isolated workspace

Two mechanisms, tried in this order.

1a. Native worktree tooling (preferred)

Do you already have a native way to create a worktree — a tool named something like EnterWorktree or WorktreeCreate, a /worktree command, a --worktree flag? If so, use it and skip to Step 3. Native tools handle placement, branch creation, and cleanup themselves; using raw git worktree add alongside them creates state the harness can't track. Only fall through to 1b if no native tool exists.