Skip to content

feat(plugin): optional branch name and single-route flow for /wt-switch-create - #3058

Merged
max-sixty merged 1 commit into
mainfrom
skill-branch-name
Jun 12, 2026
Merged

max-sixty merged 1 commit into
mainfrom
skill-branch-name

Conversation

@max-sixty

Copy link
Copy Markdown
Owner

The /wt-switch-create branch 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=json in Bash (rerunning without --create when the user named an existing branch), re-root the session with EnterWorktree({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 previous EnterWorktree({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 resetting cd that leaves the session's working directories.

Hook fix: both WorktreeCreate and WorktreeRemove pipelines are wrapped in bash -c 'set -o pipefail; ...'. Without it the trailing jq exits 0 on empty input, so a wt failure surfaced as a "successful" hook with an empty path. The wrapper is explicit bash because hooks spawn via /bin/sh -c, where dash rejects set -o pipefail fatally. 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 WorktreeCreate hook 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 wt itself (an idempotent --create cannot encode who chose the branch name, which determines the correct recovery).

This was written by Claude Code on behalf of max

…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 worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 xargs runs its command once even on empty input under GNU findutils (no -r), so a jq that emitted nothing would invoke wt remove --foreground with 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 xargs word-splits the path; -I{} passes the whole line as one argument.
  • pipefail surfaces a failed jq/wt instead of the trailing stage masking it.
  • No new force flags; wt remove still 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.

@max-sixty
max-sixty merged commit fd3ae5b into main Jun 12, 2026
36 checks passed
@max-sixty
max-sixty deleted the skill-branch-name branch June 12, 2026 06:01
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants