Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix(wt-switch-create): leave the current worktree session before entering by path (#4714)
Worktrunk Bot9bd2b6387118
diff --git a/plugins/worktrunk/skills/wt-switch-create/SKILL.md b/plugins/worktrunk/skills/wt-switch-create/SKILL.mdindex 95dc6bcfb..947fd17fc 100644--- a/plugins/worktrunk/skills/wt-switch-create/SKILL.md+++ b/plugins/worktrunk/skills/wt-switch-create/SKILL.md@@ -58,8 +58,11 @@ design choices behind this — read it before re-adding guards or routes. -->with no task text, confirm it's ready and wait).Mid-session, carry uncommitted work across: `git stash push -u` before the- `EnterWorktree` call, then `git stash pop` after — the call re-roots the- session into the new worktree, and the stash is shared across worktrees.+ `EnterWorktree` call, then `git stash pop` once the session is in the new+ worktree, which is after step 3 if this call fails. Entering re-roots the+ session into the new worktree, and the stash is shared across worktrees. If+ step 3 hands back without the session in the new worktree, restore the work+ where it came from first (`git -C <that worktree> stash pop`).3. **Otherwise create it with `wt` and enter by path.** Two cases reach here: arepo argument, which step 2 can't target, and a failed step 2, whose error@@ -76,12 +79,26 @@ design choices behind this — read it before re-adding guards or routes. -->worktree if missing); if step 1 picked the name, pick another and rerun. Anyother failure (not a git repo, invalid name): report it and stop.- With a repo argument, `cd <repo>` next, in its own `Bash` call.+ Next, call `ExitWorktree({action: "keep"})`. This invocation is the user+ asking to move the session, which includes leaving the worktree it is in,+ so make the call even when you're unsure the session is in one. A session+ in a worktree can enter only one under its repository's+ `.claude/worktrees/`; leaving lifts that limit, keeps the old worktree and+ its branch on disk, and returns the session to the directory it was in+ before it entered. Where there is nothing to leave (no worktree session, or+ an agent pinned to its own worktree), the call returns an error and changes+ nothing; carry on. If the session did leave a worktree+ and the entry below doesn't happen, say so when you hand back: name the+ worktree it left, still on disk, and where the session is now.++ With a repo argument, `cd <repo>` next, in its own `Bash` call:`EnterWorktree` re-roots only within the repository the cwd is in, andworktrunk's `PermissionRequest` hook answers the confirmation that call- asks for only for a `wt` worktree of that same repository. If the `cd`+ asks for only for a `wt` worktree of that same repository. If that `cd`reports `Shell cwd was reset`, the repo is unreachable: skip the entry and- hand back as in **Unreachable** below.+ hand back as in **Unreachable** below. With no repo argument, don't `cd`:+ leaving put the session back in this repository, and a `cd` into the+ worktree it left can reset.Then call `EnterWorktree({path: "<path from the JSON>"})`.@@ -96,12 +113,11 @@ design choices behind this — read it before re-adding guards or routes. -->with no task text, confirm it's ready and wait).- **Tool error** — the tool ran and returned an error (`Cannot enterworktree: …`) → graceful; nothing moved, and one recovery covers them- all. The common cause is a session already rooted in a worktree (or a- pinned agent), which limits entry to the current repo's- `.claude/worktrees/` and excludes even a same-repo `wt` sibling. The- recovery test is whether you can `cd` into the worktree, which works- when it's inside an allowed directory. So `cd <path>` and read the- result:+ all. One cause is an agent pinned to its own worktree, which can+ enter only under its repo's `.claude/worktrees/`, excluding even a+ same-repo `wt` sibling. The recovery test is whether you can `cd` into+ the worktree, which works when it's inside an allowed directory. So+ `cd <path>` and read the result:- no `Shell cwd was reset` notice → it stuck; the worktree is reachable.Work there, but a bare `cd` is not a tracked re-root, so the cwd canrevert to the session's launch worktree across turns (and in spawned@@ -131,7 +147,8 @@ remove it unprompted.A worktree from step 2 that the session never touched — no changed files, nocommits — is cleaned up when the session ends, branch included; anything-written into it keeps it. A worktree from step 3 always stays. If the user asks+written into it keeps it. A worktree from step 3 always stays, as does a+worktree the session left in step 3. If the user asksto leave mid-session, `ExitWorktree({action: "keep"})` returns the session toits original directory;`ExitWorktree` cannot remove a worktree entered by `path`, so removing one ofdiff --git a/plugins/worktrunk/skills/wt-switch-create/rationale.md b/plugins/worktrunk/skills/wt-switch-create/rationale.mdindex fe518af5e..5ef758ae2 100644--- a/plugins/worktrunk/skills/wt-switch-create/rationale.md+++ b/plugins/worktrunk/skills/wt-switch-create/rationale.md@@ -13,6 +13,8 @@ leaves behind at exit — was re-run live on 2026-07-28 against Claude Code2.1.220 and wt v0.69.2. The confirmation hook and `cd`-before-entry for anotherrepo were verified live on 2026-09-16 against Claude Code 2.1.273 (#4149).Hook-based exit cleanup was checked live on Claude Code 2.1.308 on 2026-10-22.+Leaving a worktree session with `ExitWorktree` before path entry was verified+live on 2026-11-05 against Claude Code 2.1.316 and wt v0.81.0.Re-verify against current versions before relying on a specific behavior; the*shape* of the argument should outlive the details.Binary symbol names are deliberately omitted — they re-minify every build.@@ -28,7 +30,8 @@ no rationale.from firing. It fails from a session that already entered a worktree, andit has no repo targeting.3. Otherwise `wt -C <repo> switch --create <branch> --no-cd --format=json` in- Bash, then, for another repo, `cd <repo>`, then `EnterWorktree({path})`.+ Bash, then `ExitWorktree({action: "keep"})`, then, for another repo,+ `cd <repo>`, then `EnterWorktree({path})`.`wt` solves repo targeting (`-C` works from anywhere), existing-branchhandling (rerun without `--create`), and machine-readable output (`.path`on stdout, status on stderr). Creating in another repo is fine; only@@ -38,6 +41,17 @@ no rationale.worktrees ("The confirmation hook"). The `cd` satisfies both. Entry that someone declinedends there, with the worktree left unentered (M2).+ Leaving first lifts the stricter gate a session already in a worktree is+ held to (M2, "Why leave before entering"), and does nothing for a session+ in none. Leaving also moves the cwd and the session's base cwd (M1) back+ to where they stood when the current worktree session began (a switch+ within a session keeps that point; leaving and entering again resets it).+ That is normally in the same repository as the worktree just left, so+ with no repo argument step 3 enters from there. A `cd` back into the+ worktree just left would reset under the default sibling layout unless an+ `additionalDirectories` entry covers it, and after a `cd` into the new+ worktree `EnterWorktree` would refuse it as the current directory.+On a tool error (or a denial with no user behind it), the session can stillwork there iff the path sitsinside a directory it's allowed in (an `additionalDirectories` entry). A@@ -118,6 +132,13 @@ cwd.one registered to a repo nested inside it.- **Already in a worktree-session, or a pinned agent** → only under thatrepo's `.claude/worktrees/`; rejects even same-repo siblings.+ `ExitWorktree({action: "keep"})` ends a worktree session, keeps its+ worktree, and moves the cwd and the base cwd (M1) back to where they+ stood when that worktree session began, after which the first bullet+ applies again. In a subagent with a cwd override (`isolation: "worktree"`+ or an explicit `cwd`) it refuses instead (`ExitWorktree cannot be called+ from a subagent with a cwd override …`; read from the 2.1.316 binary, not+ run live), so a pinned agent stays under this gate.- **cwd outside any git repo** → refuses entirely.- **Confirmation:** the safety check runs on the two facts the call carries —a `path` argument, and a target outside the project's `.claude/worktrees/` —@@ -149,14 +170,22 @@ cwd.`permissions.deny` entry for `EnterWorktree`, with or without an argumentpattern, drops the tool from the session instead, so there is no call todeny.-- Rejections are graceful and side-effect-free (nothing is created). The three- the skill's own flow produces, verbatim (others exist — a worktree locked by- another running session, the main working tree, a prunable registration):+- Rejections are graceful and side-effect-free (nothing is created). The ones+ the skill's own flow can produce, verbatim (others exist — a worktree locked+ by another running session, a prunable registration):- registered-check: `Cannot enter worktree: <path> is not a registeredworktree of <repo>. Run 'git -C <repo> worktree list' …`- managed-location: `Cannot enter worktree: <path> is not under<repo>/.claude/worktrees. Switching from this session is limited to- worktrees managed by Claude Code …`+ worktrees managed by Claude Code …`, or, in a repo with no+ `.claude/worktrees/` at all, `Cannot enter worktree:+ <repo>/.claude/worktrees does not exist, so <path> cannot be a worktree+ managed by Claude Code.`+ - current directory: `Cannot enter worktree: <path> is the current working+ directory.`+ - main working tree: `Cannot enter worktree: <path> is the main working+ tree, not a linked worktree.`, when the user names the branch checked out+ there and the rerun without `--create` returns its path.- no repo: `Cannot enter an existing worktree: the current directory is not ina git repository.`@@ -309,14 +338,39 @@ fires only on an actual reset. Cheap to attempt, and the handback is actionableand durable (a `~/workspace` entry, set once, covers every future cross-repotask).+### Why leave before entering++Step 3 used to enter without leaving. A session already in a worktree, which is+the usual way to reach step 3 since step 2 fails exactly there, then always took+the managed-location rejection and the `cd` recovery: in one user's recorded+sessions over 45 days, 14 of 16 invocations from inside a worktree went that+way. The `cd` leaves the session's tracked worktree on the old one. Claude+Code's Bash guard for worktree sessions keeps judging commands against it and+names it when it refuses one ("run them from <old worktree>"), and session+exit and `ExitWorktree` both act on it. Leaving costs one call, keeps the old worktree on+disk, and makes the next entry a first entry. Verified live: from a session in+one `wt` worktree, entering a sibling by path failed with the managed-location+rejection, and after `ExitWorktree` the same call succeeded; entering another+repo's worktree likewise succeeded after leaving and `cd` into that repo, and a+session launched with `--worktree` left and entered the same way. With no repo+argument and no `additionalDirectories` entry, entering from where+`ExitWorktree` left the session succeeded, while a `cd` back into the old+worktree reset.++Leaving would also let step 2's name route work again, but its+`WorktreeCreate` hook creates in `$CLAUDE_PROJECT_DIR`, the launch repo+("Re-rooting keeps the launch repo's instructions"), so after an entry into+another repo's worktree a retry would create the worktree in the wrong repo.+`wt switch` creates it in the repo the session is working in.+## Known limits (deliberate)- Another repo is reachable only through `additionalDirectories` ("How theycompose", above); outside it the skill escalates for the one-line config addrather than degrading to absolute-paths mode.-- A pinned or already-in-worktree session can't even re-enter a *same-repo*- sibling worktree (the stricter `.claude/worktrees/` check); it lands in the- same reachability test and the same escalation.+- A pinned agent can't even re-enter a *same-repo* sibling worktree (the+ stricter `.claude/worktrees/` check), and `ExitWorktree` refuses to run in+ it; it lands in the same reachability test and the same escalation.- Where the plugin's hooks don't run, or the worktree is off the`worktree-path` template (an existing branch whose worktree lives elsewhere,a detached worktree), step 3's entry asks the user to confirm, once per call,diff --git a/skills/wt-switch-create/SKILL.md b/skills/wt-switch-create/SKILL.mdindex 95dc6bcfb..947fd17fc 100644--- a/skills/wt-switch-create/SKILL.md+++ b/skills/wt-switch-create/SKILL.md@@ -58,8 +58,11 @@ design choices behind this — read it before re-adding guards or routes. -->with no task text, confirm it's ready and wait).Mid-session, carry uncommitted work across: `git stash push -u` before the- `EnterWorktree` call, then `git stash pop` after — the call re-roots the- session into the new worktree, and the stash is shared across worktrees.+ `EnterWorktree` call, then `git stash pop` once the session is in the new+ worktree, which is after step 3 if this call fails. Entering re-roots the+ session into the new worktree, and the stash is shared across worktrees. If+ step 3 hands back without the session in the new worktree, restore the work+ where it came from first (`git -C <that worktree> stash pop`).3. **Otherwise create it with `wt` and enter by path.** Two cases reach here: arepo argument, which step 2 can't target, and a failed step 2, whose error@@ -76,12 +79,26 @@ design choices behind this — read it before re-adding guards or routes. -->worktree if missing); if step 1 picked the name, pick another and rerun. Anyother failure (not a git repo, invalid name): report it and stop.- With a repo argument, `cd <repo>` next, in its own `Bash` call.+ Next, call `ExitWorktree({action: "keep"})`. This invocation is the user+ asking to move the session, which includes leaving the worktree it is in,+ so make the call even when you're unsure the session is in one. A session+ in a worktree can enter only one under its repository's+ `.claude/worktrees/`; leaving lifts that limit, keeps the old worktree and+ its branch on disk, and returns the session to the directory it was in+ before it entered. Where there is nothing to leave (no worktree session, or+ an agent pinned to its own worktree), the call returns an error and changes+ nothing; carry on. If the session did leave a worktree+ and the entry below doesn't happen, say so when you hand back: name the+ worktree it left, still on disk, and where the session is now.++ With a repo argument, `cd <repo>` next, in its own `Bash` call:`EnterWorktree` re-roots only within the repository the cwd is in, andworktrunk's `PermissionRequest` hook answers the confirmation that call- asks for only for a `wt` worktree of that same repository. If the `cd`+ asks for only for a `wt` worktree of that same repository. If that `cd`reports `Shell cwd was reset`, the repo is unreachable: skip the entry and- hand back as in **Unreachable** below.+ hand back as in **Unreachable** below. With no repo argument, don't `cd`:+ leaving put the session back in this repository, and a `cd` into the+ worktree it left can reset.Then call `EnterWorktree({path: "<path from the JSON>"})`.@@ -96,12 +113,11 @@ design choices behind this — read it before re-adding guards or routes. -->with no task text, confirm it's ready and wait).- **Tool error** — the tool ran and returned an error (`Cannot enterworktree: …`) → graceful; nothing moved, and one recovery covers them- all. The common cause is a session already rooted in a worktree (or a- pinned agent), which limits entry to the current repo's- `.claude/worktrees/` and excludes even a same-repo `wt` sibling. The- recovery test is whether you can `cd` into the worktree, which works- when it's inside an allowed directory. So `cd <path>` and read the- result:+ all. One cause is an agent pinned to its own worktree, which can+ enter only under its repo's `.claude/worktrees/`, excluding even a+ same-repo `wt` sibling. The recovery test is whether you can `cd` into+ the worktree, which works when it's inside an allowed directory. So+ `cd <path>` and read the result:- no `Shell cwd was reset` notice → it stuck; the worktree is reachable.Work there, but a bare `cd` is not a tracked re-root, so the cwd canrevert to the session's launch worktree across turns (and in spawned@@ -131,7 +147,8 @@ remove it unprompted.A worktree from step 2 that the session never touched — no changed files, nocommits — is cleaned up when the session ends, branch included; anything-written into it keeps it. A worktree from step 3 always stays. If the user asks+written into it keeps it. A worktree from step 3 always stays, as does a+worktree the session left in step 3. If the user asksto leave mid-session, `ExitWorktree({action: "keep"})` returns the session toits original directory;`ExitWorktree` cannot remove a worktree entered by `path`, so removing one ofdiff --git a/skills/wt-switch-create/rationale.md b/skills/wt-switch-create/rationale.mdindex fe518af5e..5ef758ae2 100644--- a/skills/wt-switch-create/rationale.md+++ b/skills/wt-switch-create/rationale.md@@ -13,6 +13,8 @@ leaves behind at exit — was re-run live on 2026-07-28 against Claude Code2.1.220 and wt v0.69.2. The confirmation hook and `cd`-before-entry for anotherrepo were verified live on 2026-09-16 against Claude Code 2.1.273 (#4149).Hook-based exit cleanup was checked live on Claude Code 2.1.308 on 2026-10-22.+Leaving a worktree session with `ExitWorktree` before path entry was verified+live on 2026-11-05 against Claude Code 2.1.316 and wt v0.81.0.Re-verify against current versions before relying on a specific behavior; the*shape* of the argument should outlive the details.Binary symbol names are deliberately omitted — they re-minify every build.@@ -28,7 +30,8 @@ no rationale.from firing. It fails from a session that already entered a worktree, andit has no repo targeting.3. Otherwise `wt -C <repo> switch --create <branch> --no-cd --format=json` in- Bash, then, for another repo, `cd <repo>`, then `EnterWorktree({path})`.+ Bash, then `ExitWorktree({action: "keep"})`, then, for another repo,+ `cd <repo>`, then `EnterWorktree({path})`.`wt` solves repo targeting (`-C` works from anywhere), existing-branchhandling (rerun without `--create`), and machine-readable output (`.path`on stdout, status on stderr). Creating in another repo is fine; only@@ -38,6 +41,17 @@ no rationale.worktrees ("The confirmation hook"). The `cd` satisfies both. Entry that someone declinedends there, with the worktree left unentered (M2).+ Leaving first lifts the stricter gate a session already in a worktree is+ held to (M2, "Why leave before entering"), and does nothing for a session+ in none. Leaving also moves the cwd and the session's base cwd (M1) back+ to where they stood when the current worktree session began (a switch+ within a session keeps that point; leaving and entering again resets it).+ That is normally in the same repository as the worktree just left, so+ with no repo argument step 3 enters from there. A `cd` back into the+ worktree just left would reset under the default sibling layout unless an+ `additionalDirectories` entry covers it, and after a `cd` into the new+ worktree `EnterWorktree` would refuse it as the current directory.+On a tool error (or a denial with no user behind it), the session can stillwork there iff the path sitsinside a directory it's allowed in (an `additionalDirectories` entry). A@@ -118,6 +132,13 @@ cwd.one registered to a repo nested inside it.- **Already in a worktree-session, or a pinned agent** → only under thatrepo's `.claude/worktrees/`; rejects even same-repo siblings.+ `ExitWorktree({action: "keep"})` ends a worktree session, keeps its+ worktree, and moves the cwd and the base cwd (M1) back to where they+ stood when that worktree session began, after which the first bullet+ applies again. In a subagent with a cwd override (`isolation: "worktree"`+ or an explicit `cwd`) it refuses instead (`ExitWorktree cannot be called+ from a subagent with a cwd override …`; read from the 2.1.316 binary, not+ run live), so a pinned agent stays under this gate.- **cwd outside any git repo** → refuses entirely.- **Confirmation:** the safety check runs on the two facts the call carries —a `path` argument, and a target outside the project's `.claude/worktrees/` —@@ -149,14 +170,22 @@ cwd.`permissions.deny` entry for `EnterWorktree`, with or without an argumentpattern, drops the tool from the session instead, so there is no call todeny.-- Rejections are graceful and side-effect-free (nothing is created). The three- the skill's own flow produces, verbatim (others exist — a worktree locked by- another running session, the main working tree, a prunable registration):+- Rejections are graceful and side-effect-free (nothing is created). The ones+ the skill's own flow can produce, verbatim (others exist — a worktree locked+ by another running session, a prunable registration):- registered-check: `Cannot enter worktree: <path> is not a registeredworktree of <repo>. Run 'git -C <repo> worktree list' …`- managed-location: `Cannot enter worktree: <path> is not under<repo>/.claude/worktrees. Switching from this session is limited to- worktrees managed by Claude Code …`+ worktrees managed by Claude Code …`, or, in a repo with no+ `.claude/worktrees/` at all, `Cannot enter worktree:+ <repo>/.claude/worktrees does not exist, so <path> cannot be a worktree+ managed by Claude Code.`+ - current directory: `Cannot enter worktree: <path> is the current working+ directory.`+ - main working tree: `Cannot enter worktree: <path> is the main working+ tree, not a linked worktree.`, when the user names the branch checked out+ there and the rerun without `--create` returns its path.- no repo: `Cannot enter an existing worktree: the current directory is not ina git repository.`@@ -309,14 +338,39 @@ fires only on an actual reset. Cheap to attempt, and the handback is actionableand durable (a `~/workspace` entry, set once, covers every future cross-repotask).+### Why leave before entering++Step 3 used to enter without leaving. A session already in a worktree, which is+the usual way to reach step 3 since step 2 fails exactly there, then always took+the managed-location rejection and the `cd` recovery: in one user's recorded+sessions over 45 days, 14 of 16 invocations from inside a worktree went that+way. The `cd` leaves the session's tracked worktree on the old one. Claude+Code's Bash guard for worktree sessions keeps judging commands against it and+names it when it refuses one ("run them from <old worktree>"), and session+exit and `ExitWorktree` both act on it. Leaving costs one call, keeps the old worktree on+disk, and makes the next entry a first entry. Verified live: from a session in+one `wt` worktree, entering a sibling by path failed with the managed-location+rejection, and after `ExitWorktree` the same call succeeded; entering another+repo's worktree likewise succeeded after leaving and `cd` into that repo, and a+session launched with `--worktree` left and entered the same way. With no repo+argument and no `additionalDirectories` entry, entering from where+`ExitWorktree` left the session succeeded, while a `cd` back into the old+worktree reset.++Leaving would also let step 2's name route work again, but its+`WorktreeCreate` hook creates in `$CLAUDE_PROJECT_DIR`, the launch repo+("Re-rooting keeps the launch repo's instructions"), so after an entry into+another repo's worktree a retry would create the worktree in the wrong repo.+`wt switch` creates it in the repo the session is working in.+## Known limits (deliberate)- Another repo is reachable only through `additionalDirectories` ("How theycompose", above); outside it the skill escalates for the one-line config addrather than degrading to absolute-paths mode.-- A pinned or already-in-worktree session can't even re-enter a *same-repo*- sibling worktree (the stricter `.claude/worktrees/` check); it lands in the- same reachability test and the same escalation.+- A pinned agent can't even re-enter a *same-repo* sibling worktree (the+ stricter `.claude/worktrees/` check), and `ExitWorktree` refuses to run in+ it; it lands in the same reachability test and the same escalation.- Where the plugin's hooks don't run, or the worktree is off the`worktree-path` template (an existing branch whose worktree lives elsewhere,a detached worktree), step 3's entry asks the user to confirm, once per call,