Repository navigation
feat(plugin): optional branch name and single-route flow for /wt-switch-create - #3058
Conversation
…ch-create
The branch argument is now optional; a name is picked from the task when
omitted. The workflow is rebuilt around one evidence-tested route: create
the worktree with `wt switch --create --format=json` in Bash, re-root the
session with EnterWorktree({path}), and fall back to absolute paths when
re-rooting is rejected (cross-repo, pinned cwd, nested session). The
previous guard-heavy flow encoded untested hypotheses about Claude Code;
every claim behind the new design is verified against primary sources and
documented in the new skills/wt-switch-create/rationale.md.
Also:
- hooks.json: wrap the WorktreeCreate and WorktreeRemove pipelines in
`bash -c 'set -o pipefail; ...'` so a wt failure propagates instead of
being swallowed by the trailing jq (Claude Code previously saw a
"successful" hook with an empty path); xargs -I{} also fixes paths
containing spaces
- docs, README, and plugin CLAUDE.md aligned with the new mechanism: the
skill no longer rides the WorktreeCreate hook, and the worktree persists
after the session like any other worktrunk worktree
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
worktrunk-bot
left a comment
There was a problem hiding this comment.
This touches the worktree-removal surface — plugins/worktrunk/hooks/hooks.json, the WorktreeRemove pipeline that runs wt remove --foreground. Per this repo's data-safety review policy I'm flagging it for a human merge decision rather than approving, even though my read is that the change is a net safety improvement.
Independent analysis of the WorktreeRemove change (xargs … remove → xargs -I{} … remove {}, wrapped in bash -c 'set -o pipefail; …'):
- Empty/missing path no longer triggers a removal. The old bare
xargsruns its command once even on empty input under GNU findutils (no-r), so ajqthat emitted nothing would invokewt remove --foregroundwith no path argument.xargs -I{}runs zero times on empty input on both GNU and BSD — verified locally (printf '' | xargs -I{} …→ no invocation, exit 0). That closes a real footgun on the removal path. - Paths with spaces survive. Bare
xargsword-splits the path;-I{}passes the whole line as one argument. pipefailsurfaces a failedjq/wtinstead of the trailing stage masking it.- No new force flags;
wt removestill refuses dirty worktrees (exit 1, hints--force), so the safe variant is preserved.
The mirror edits to docs/content/claude-code.md and skills/worktrunk/reference/claude-code.md are consistent prose (no Zola syntax in the changed paragraph), so test_docs_are_in_sync should regenerate to the same content. The rest is skill/doc prose plus the new rationale.md; the EnterWorktree/Claude-Code-internals claims rest on the author's live testing, which I can't independently reproduce from CI.
No blocking issues found — holding the verdict to a human only because the removal hook is in scope.
worktrunk 0.58.0 Created-by: HarmonybrewBot Commit-by: HarmonybrewBot Merged-by: HarmonybrewBot Description: Created by `brew bump` --- Created with `brew bump-formula-pr`.<details> <summary>release notes</summary> <pre>## Release Notes ### Improved - **Table-form `pre-*` hooks run concurrently**: A multi-entry table hook (`[pre-merge]` with several keys) now runs its commands concurrently, completing the cut-over announced in v0.37.0: every hook type has one execution semantic, where table form is concurrent and pipeline form (`[[pre-merge]]` blocks) is serial. Configs that need ordering should use pipeline form; affected configs have warned on every invocation since v0.37.0, with `wt config update` offering a serial-preserving migration. Two adjacent inconsistencies are also gone: `wt hook <post-type>` foreground runs of multi-entry table hooks now run concurrently like their background counterpart, and single-entry table aliases write to stdout like the other alias spellings, so `wt <alias> | …` works for that spelling too. (Breaking: multi-entry table-form `pre-*` hooks no longer run serially) ([#3052](max-sixty/worktrunk#3052)) - **CI column shows the PR/MR number and review state**: The CI column in `wt list --full` and the statusline shows the branch's open PR/MR reference (`#3041` on GitHub/Gitea/Azure DevOps, `!3041` on GitLab) instead of a plain dot: colored by CI status, hyperlinked to the PR, dimmed when stale or draft. Review state folds into the color, with magenta for changes requested and cyan for awaiting review. `wt list --format=json` gains `ci.number` and `ci.review_state`. ([#3041](max-sixty/worktrunk#3041), [#3044](max-sixty/worktrunk#3044)) - **Hook and alias templates render when each step runs**: Templates are syntax-checked before the first step runs and rendered as each step executes, so `{{ vars.* }}` always reads fresh values and hooks and aliases share one expansion model. Two consequences: a pipeline step with an undefined variable fails when that step is reached (earlier steps run first), and a template error in a background hook surfaces in the hook log rather than failing the foreground command. The background runner also labels template errors the way the foreground does. ([#3042](max-sixty/worktrunk#3042), [#3047](max-sixty/worktrunk#3047)) - **`wt config state cache`**: The regenerable caches (CI status, branch summaries, git-command caches, hints, the `wt switch -` target) are consolidated under `wt config state cache`; `cache clear` drops them all without prompting, since everything regenerates. `wt config state clear`, which also wipes hand-authored markers and vars, now asks for confirmation; `--yes` skips, and non-interactive runs without `--yes` cancel. The `ci-status`, `hints`, and `previous-branch` subcommands are deprecated but still work. ([#3027](max-sixty/worktrunk#3027)) - **Statusline rate-limit segment**: Above 90% of the binding window the segment shows the used percentage (`95%(8:30am–1:30pm)`) instead of the pace ratio; near the cap, what's left matters more than the rate. The pace form drops the word "pace" (`2.9×(Tue–Tue 5pm)`), and `-vv` logs each window's inputs and selection to `.git/wt/logs/trace.log` so the binding-window choice can be reconstructed. ([#3057](max-sixty/worktrunk#3057), [#3053](max-sixty/worktrunk#3053), [#3029](max-sixty/worktrunk#3029)) - **`/wt-switch-create` branch name is optional**: The Claude Code plugin command picks a branch name from the task when none is given, and the skill's workflow is one route (create, then enter) with an error-driven fallback instead of three guarded paths. Worktrees created mid-session persist after the session ends. ([#3058](max-sixty/worktrunk#3058)) ### Fixed - **Plugin worktree hooks fail before side effects**: The Claude Code plugin's `WorktreeCreate`/`WorktreeRemove` hooks validate the payload before running `wt`; a malformed payload previously created a branch named `null` or could remove the wrong worktree. `wt remove`'s help now documents that the positional argument accepts a worktree path as well as a branch name. ([#3058](max-sixty/worktrunk#3058), [#3060](max-sixty/worktrunk#3060)) - **Waiting-for-input marker covers questions, permission prompts, and turn end**: The Claude Code plugin sets the 💬 marker on `AskUserQuestion`, permission requests, and turn end. Previously only the `Notification` event set it, which never fires for the built-in question picker (and on some platforms not for permission prompts), so the marker stayed 🤖 while Claude waited. Part of [#2916](max-sixty/worktrunk#2916). ([#3023](max-sixty/worktrunk#3023), thanks @Ismael for reporting) - **`wt list --help` no longer panics when piped**: With no detectable terminal width (output piped, `COLUMNS` unset), `wt list --help` panicked with a capacity overflow, and the post-commit diffstat truncated filenames to ~10 characters. Both now handle unknown width. ([#3040](max-sixty/worktrunk#3040)) - **Deprecation warnings match `wt config update`**: A config deprecation warning now fires exactly when `wt config update` would change the file. The old detection and migration logic had drifted in several places: `ff` and `no-ff` together silently dropped `no-ff`, a scalar `forge` key was overwritten by the `[ci]` migration, an empty `[ci] platform` migrated without warning, and an empty `approved-commands = []` could be removed by an unrelated update. ([#3055](max-sixty/worktrunk#3055)) - **Migrated `[forge]` keeps `[ci]`'s spot**: The `[ci]` → `[forge]` migration rendered the new section at the end of the file and could drop comments above `[ci]`; it now takes over `[ci]`'s position, comments included, so `wt config show` and `wt config update` diffs stay minimal. ([#3051](max-sixty/worktrunk#3051)) - **`wt config state get` is read-only**: The aggregate dump resolved (and re-cached) the default branch, so running it right after `clear` silently repopulated the cache, and on a cold clone it could hit the network. It now reports the cached value or `(none)`. `wt config state default-branch get` still resolves and caches. ([#3024](max-sixty/worktrunk#3024)) ### Documentation - **Reading vs resolving cached state**: `wt config state default-branch get` resolves and caches; the aggregate `wt config state get` only reports the cache. The help text and module docs now state the split. ([#3028](max-sixty/worktrunk#3028)) ### Internal - `wt switch`/`wt remove` orchestration moved from `main.rs` to their command modules, and the hook execution call chain lost two delegation layers. ([#3049](max-sixty/worktrunk#3049), [#3036](max-sixty/worktrunk#3036)) - Config deprecations are driven by a single rule table; each rule is one function that migrates and reports what it changed. ([#3045](max-sixty/worktrunk#3045), [#3055](max-sixty/worktrunk#3055)) - `terminal_width()` returns `Option<usize>` instead of a `usize::MAX` sentinel, making the no-width case a compile-time concern. ([#3043](max-sixty/worktrunk#3043)) - Snapshot tests regenerate identically across machines: host-specific paths are guarded, host-dependent env-block markers are normalized, and help snapshots share one settings builder. ([#3009](max-sixty/worktrunk#3009), [#3026](max-sixty/worktrunk#3026), [#3037](max-sixty/worktrunk#3037), [#3061](max-sixty/worktrunk#3061)) - Nightly CI runs lib tests across the full feature powerset. ([#3059](max-sixty/worktrunk#3059)) - MSRV bumped from 1.94 to 1.95. ([#2948](max-sixty/worktrunk#2948)) ## Install worktrunk 0.58.0 ### Install prebuilt binaries via shell script ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-installer.sh | sh && wt config shell install ``` ### Install prebuilt binaries via powershell script ```sh powershell -ExecutionPolicy Bypass -c "irm https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-installer.ps1 | iex"; git-wt config shell install ``` ### Install prebuilt binaries via Homebrew ```sh brew install worktrunk && wt config shell install ``` ## Download worktrunk 0.58.0 | File | Platform | Checksum | |--------|----------|----------| | [worktrunk-aarch64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-aarch64-apple-darwin.tar.xz.sha256) | | [worktrunk-x86_64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-x86_64-apple-darwin.tar.xz.sha256) | | [worktrunk-x86_64-pc-windows-msvc.zip](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-x86_64-pc-windows-msvc.zip) | x64 Windows | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-x86_64-pc-windows-msvc.zip.sha256) | | [worktrunk-aarch64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-aarch64-unknown-linux-musl.tar.xz) | ARM64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.58.0/worktrunk-aarch64-unknown-linux-musl.tar.xz.sha256) | See merge request: Harmonybrew/homebrew-core!11501
The
/wt-switch-createbranch argument becomes optional (a name is picked from the task when omitted), and the skill's workflow is rebuilt from a guard-heavy three-route flow into one route plus one error-driven fallback.The new flow: pick a branch name if none was given, create the worktree with
wt -C <repo> switch --create <branch> --no-cd --format=jsonin Bash (rerunning without--createwhen the user named an existing branch), re-root the session withEnterWorktree({path}), and on a graceful rejection (different repo, pinned cwd, nested session) work in the worktree via absolute paths instead.Why the rewrite: the old flow's guards encoded hypotheses about Claude Code that turned out wrong or untested. The load-bearing discoveries, each verified by binary inspection, official docs, or live tests and documented in the new
skills/wt-switch-create/rationale.md:EnterWorktree({path})accepts worktrunk's sibling layout on first entry; every rejection it can raise is side-effect-free, so try-then-fallback replaces prediction; the previousEnterWorktree({name})/hook route silently auto-removes a clean worktree at session exit, which is wrong for durable worktrunk worktrees (path-entered worktrees persist); and the "pinned cwd" the old guards defended against was a misdiagnosis of the harness resettingcdthat leaves the session's working directories.Hook fix: both
WorktreeCreateandWorktreeRemovepipelines are wrapped inbash -c 'set -o pipefail; ...'. Without it the trailingjqexits 0 on empty input, so awtfailure surfaced as a "successful" hook with an empty path. The wrapper is explicitbashbecause hooks spawn via/bin/sh -c, where dash rejectsset -o pipefailfatally.xargs -I{}also fixes worktree paths containing spaces. Tested end-to-end in both directions (success exits 0 with the path; failure exits 1 with empty stdout).Docs, README, and plugin CLAUDE.md are aligned with the new mechanism. The agent-isolation use of the
WorktreeCreatehook is unchanged.Review trail: the design survived an evidence audit (every rationale claim independently re-verified), a code review (bare directory-named tokens no longer parse as the repo; mid-session moves now stash uncommitted work across), and a level check that considered and rejected fixing this in
wtitself (an idempotent--createcannot encode who chose the branch name, which determines the correct recovery).