Hook failure always suggests --no-hooks, including for pre-merge gates

[ee-prog]

wt v0.77.0, macOS arm64 (Homebrew).

Every hook failure ends with the same remediation:

✗ pre-merge command failed: gate: exit status: 1
↳ To skip pre-merge hooks, re-run with --no-hooks

✗ pre-start command failed: deps: exit status: 1
↳ To skip pre-start hooks, re-run with --no-hooks

For post-* hooks and most pre-start setup that reads fine. For pre-merge it is offering the one action the hook exists to prevent. In our repo the pre-merge pipeline (lint, tests, build) is the only gate between a branch and a production deploy, because every push to the default branch deploys and there is no CI. The line an agent or a person reads at the exact moment they are blocked and impatient is "re-run with --no-hooks".

We have had to write "never --no-hooks, whatever Worktrunk's own error text suggests" into our contributor docs, which is a poor place for that instruction to live.

Suggestions, any of which would help:

• Omit the hint for pre-merge specifically, or
• word it as a statement rather than a next step ("--no-hooks skips them" rather than "To skip ... re-run with"), or
• make it configurable, e.g. a project-config key that suppresses the hint for named hook types.

Happy to send a PR if you have a preference on which.

[worktrunk-bot]

No code change yet — this is a wording/product call, and you asked for a preference, so here is what the code says about the three options plus where I'd land.

The hint is not per-hook-type. It is attached at exactly two places — execute_hook and execute_planned_hook — and every caller of those two passes a pre-* type with FailureStrategy::FailFast: pre-merge, pre-commit, pre-remove, pre-switch, pre-start. post-* hooks never reach it; they run in the background through the announcer, and manual wt hook <type> deliberately bypasses the hint because you asked for the hooks. So the line you're seeing after pre-start is the same code path, and every single time this hint renders, a pre-* hook has just blocked an operation. There is no "mostly post-hooks, occasionally a gate" mix for a carve-out to separate.

That changes the shape of your first suggestion. Special-casing pre-merge is a carve-out inside a set that is already uniformly gate failures; the honest version of it is "drop the hint from every pre-* failure", which costs discoverability exactly where --no-hooks is the right next step — a pre-start setup script that's broken, where the alternative is no worktree at all.

My preference is your second option, and I don't think it's only the cheapest. The project's own hint convention already allows it: writing-user-outputs defines a hint as suggesting user action or providing additional non-essential context, and lists statement-form hints ("Branch can be deleted") next to imperative ones. So ↳ --no-hooks skips pre-merge hooks isn't a deviation — it reclassifies the line from a next step into a fact, uniformly, with no per-type branching and no new surface. The flag stays discoverable for the pre-start case; it just stops being phrased as the thing to do next.

On the config key — worktrunk treats a config key as a product decision that has to earn its documentation surface (CLAUDE.md, Project Status), and a key whose whole job is suppressing one hint line is a thin case for that. It would work for you — project config is committed by the maintainer, so the impatient reader can't undo it — but it's the most expensive of the three for a problem the wording change addresses for everyone.

Landing the reword is one string in HookErrorWithHint::render. It's pinned by 13 snapshot files plus two inline assert_snapshot! cases in that same file; cargo insta test --accept --test integration regenerates them, and cargo run -- hook pre-merge --yes runs the whole gate.

Worth saying that having to write "never --no-hooks, whatever Worktrunk's own error text suggests" into contributor docs is the part that reads as the actual bug here — the tool's text is being contradicted downstream. A maintainer should pick among the three, but that detail is the argument for doing something rather than nothing.

[max-sixty]

• "--no-hooks skips them"

is this that different??

all hints are written with the same sentence construction; namely that the command comes last. The other ones add too much complexity and overfitting on that project (how about pre-commit?? maybe pre-start is also important?)

open to a different phrasing if there's a better one, but otherwise I'll plan to leave as-is, hope that's reasonable

[worktrunk-bot]

You're right, and I checked rather than just conceding: every hint in the tree that carries a command uses one construction — goal first, command last.

• To drop a duplicate, run {cmd}
• To force-delete, run {cmd}
• To apply: wt config update
• To rebase onto main, run wt merge
• To skip {} hooks, re-run with --no-hooks

Statement-form hints exist, but they're all hints that name no command (Nushell support is experimental, Approval will be requested again next time). So --no-hooks skips pre-merge hooks would be the only command-bearing hint that inverts the order — that's a real consistency cost I understated, and it changes my recommendation.

The force-delete one is the closest precedent and it cuts against the original report: CannotRemoveDefaultBranch refuses to delete your default branch and then, in the same breath, hands you wt remove -D. That's a more destructive override than --no-hooks, offered at the same moment — refusal, then the flag that undoes the refusal. The form is already the project's idiom for escape hatches, so pre-merge isn't a special case of it, and a reader who learns the idiom on wt remove reads the hook line the same way.

Since you asked for a phrasing: the only lever that doesn't touch the construction is the verb — To bypass pre-merge hooks, re-run with --no-hooks. Same shape, same length, and bypass names circumventing a gate where skip suggests an optional step. But it's one word against 13 snapshot files, and it does nothing the idiom doesn't already do. Leaving as-is seems reasonable to me.