Skip to content

fix(plugin): fail worktree hooks before side effects; document path args - #3060

Merged
max-sixty merged 4 commits into
mainfrom
wt-switch-create-pinned-cwd
Jun 12, 2026
Merged

max-sixty merged 4 commits into
mainfrom
wt-switch-create-pinned-cwd

Conversation

@max-sixty

@max-sixty max-sixty commented Jun 12, 2026 •

Copy link
Copy Markdown
Owner

Hardens the plugin's worktree-lifecycle hooks against malformed payloads, and documents two things they rely on.

Hooks (plugins/worktrunk/hooks/hooks.json): in the pipeline form, jq -r .name | xargs … wt switch --create {} … runs wt with whatever jq printed — so a payload missing .name minted a real branch named null, and set -o pipefail could only report the failure after the side effect (verified under /bin/sh). Both hooks now validate the field in a command substitution before wt runs (name=$(jq -er .name) || exit 1; …), which fails with nothing created and stays whitespace-safe via quoted variables. The bash -c wrapper remains — hook commands must parse under fish/zsh/bash and fish rejects name=$(…) — but set -o pipefail is gone: the only remaining pipe ends in jq -er .path, whose exit is the pipeline's. Exercised under sh -c against the shipped JSON: missing field → exit 1, no branch; fresh create → path on stdout, exit 0; existing branch → wt's real error, nonzero; remove by path → removed.

Docs: wt remove's positional also accepts worktree paths (resolve_worktree_arg tries branches first, then paths) and the WorktreeRemove hook passes a path — the help line now reads "Branch name or worktree path". The plugin README lists jq as a hook dependency, and the skill's branch-naming step asks for names consistent with the repo's existing worktrees.

This was written by Claude Code on behalf of max

max-sixty and others added 3 commits June 11, 2026 23:16
…potence

Ground the wt-switch-create skill in verified harness behavior and fix
the defects the verification campaign surfaced:

- WorktreeCreate hook: fall back to plain `wt switch` when --create
  fails (wt errors deliberately on an existing branch, so re-entry via
  EnterWorktree was broken), use `jq -er` so a missing .name fails the
  hook instead of minting a branch literally named "null", and let
  failures propagate instead of being masked by the trailing jq
- WorktreeRemove hook: extract the path without xargs (whitespace-safe)
  and with `jq -er`
- Skill grammar: branch and repo are now optional — the branch name is
  derived from the task when omitted, and the repo defaults to the
  session's unless the task's work plainly lives elsewhere
- Delete the cd-then-EnterWorktree cross-repo mechanism: the harness
  keeps the shell inside the session's working directories in every
  session type, so it never worked; cross-repo targets now use
  `wt -C <repo> switch --create --no-cd` without re-rooting
- Rewrite Cleanup to observed ExitWorktree semantics (refuses without
  discard_changes: true; wt remove keeps dirty worktrees and unmerged
  branches)
- Document `wt remove`'s path acceptance, which the hook depends on
- README: jq dependency, `--` in the example to match the grammar

Every behavioral claim in the skill is now probe-verified or backed by
a checkable contract.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
#3058 landed a parallel, better-evidenced rewrite of the same skill
(EnterWorktree({path}) accepts sibling-layout worktrees on first entry;
the {name}/hook route auto-removes clean worktrees at session exit).
Resolution: #3058's skill, docs, and plugin CLAUDE.md win wholesale;
this branch contributes the pieces #3058 lacks:

- hooks: replace the pipefail pipelines with sequenced command
  substitutions (`name=$(jq -er '.name') || exit 1; …`). In the
  pipeline form, jq -er prints "null" before exiting nonzero and the
  downstream xargs has already run wt by then — a missing .name minted
  a real branch named "null" even though the hook reported failure
  (verified under /bin/sh). The sequenced form fails before any side
  effect, needs no pipefail (so no bash -c wrapper), and keeps #3058's
  no-fallback design for --create.
- `wt remove` help: document path acceptance ("Branch name or worktree
  path"), which the WorktreeRemove hook depends on.
- README: jq listed as a hook dependency.
- skill step 1: branch names also stay consistent with existing
  worktree names.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…hook

The trailing `jq -er '.path'` already fails on empty input when wt
errors, so the intermediate out=$() capture added nothing. The
load-bearing sequencing — validating .name before wt runs — is
unchanged.

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.

Reviewed the substance and it holds up — submitting as a comment rather than an approval because the diff edits plugins/worktrunk/hooks/hooks.json, which carries wt remove --foreground (the data-loss surface this repo holds for human review). Since you authored it, that review is already in human hands; flagging per policy, no auto-approve.

What I verified:

  • wt remove help line — resolve_worktree_arg is branch-first then falls back to worktree_at_path, so "Branch name or worktree path" is accurate, and all four mirrors are in sync (src/cli/mod.rs, both remove.md docs, both snapshots).
  • Dropping set -o pipefail — the only remaining pipe ends in jq -er '.path', so a failed wt switch (no JSON on stdout) makes jq exit nonzero and the failure surfaces as the pipeline's exit. The one masked case — wt printing the path JSON then exiting nonzero — can't happen, since --format=json only emits on success. path is always serialized (no skip_serializing_if), so jq -er '.path' is reliable.
  • Same pattern elsewhere — the repo-root Gemini hooks/hooks.json only ships activity-tracking hooks, no WorktreeCreate/WorktreeRemove, so there's no second site carrying the old jq -r .name | xargs shape.

No actionable findings.

test_claude_hook_commands_parse_in_all_shells syntax-checks every hook
command under fish/bash/zsh, and fish rejects `name=$(...)`. Keep the
sequenced validate-before-wt logic inside a bash -c wrapper; pipefail
stays gone (the only remaining pipe ends in jq -er, whose exit is the
pipeline's).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@max-sixty
max-sixty merged commit 11129d3 into main Jun 12, 2026
34 checks passed
@max-sixty
max-sixty deleted the wt-switch-create-pinned-cwd branch June 12, 2026 07:34
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