[passitalong]

The "Parallel sub-Agents" example runs wt switch --create <branch> --no-cd --no-hooks. On a machine with a pre-start hook in user config — mine symlinks the primary worktree's Python venv, which is gitignored and so never arrives with the checkout — that flag skips the provisioning, and the sub-Agent gets a worktree with no interpreter. Every command it runs fails, and nothing in the worktree says why.

The prose is already conditional, but the example is what an agent copies: it reads the command block, not the paragraph three blocks down. So the example now omits --no-hooks, and the sentence states when to add it — only when no user or project hooks provision the worktree and each sub-Agent does its own setup.

Docs only; the flag's behaviour is unchanged.

🤖 Generated with Claude Code

[worktrunk-bot]

The rewrite is right about what it fixes, and the regenerated digest in docs/public/.well-known/agent-skills/index.json matches the new SKILL.md byte-for-byte, so the sync check is satisfied.

One gap the new example opens. With --no-hooks gone, the block is a command an agent runs from a non-TTY tool call, and wt switch --create gates project-config hooks before it creates anything: approve_switch_hooks calls HookPlanBuilder::finish().approve(...) and propagates its error, and the prompt helper behind it (prompt_for_batch_approval_with_header in src/commands/command_approval.rs) returns GitError::NotInteractive as soon as it sees !io::stdin().is_terminal(). So in a repo whose .config/wt.toml declares pre-start/post-start/post-switch commands that aren't yet in approvals.toml — worktrunk's own repo among them — the recipe now fails with Cannot prompt for approval in non-interactive environment and creates no worktree, where the old command with --no-hooks never reached the gate.

Failing loudly there is the right behaviour, and this file already documents it under Hook approvals in non-interactive sessions. The problem is distance: that section is several blocks up, and the paragraph an agent reads next to the example gives it no reason to connect the error to it. One clause pointing there closes the loop. User-config hooks — the case that motivated this PR — are never approvable, so they're unaffected either way.

The inline suggestion also restores "build/test step" for the cargo run -- hook pre-merge --yes example. The rewrite relabels it as the sub-Agent's own "setup", and hook pre-merge is the gate that runs after provisioning, not provisioning itself.

Apply it on skills/worktrunk/SKILL.md only — cargo test --test integration test_docs_are_in_sync rewrites plugins/worktrunk/skills/worktrunk/SKILL.md and the index digest from the authored copy.

[passitalong]

Apologies for not opening an Issue first. We are loving worktrunk. Happy to move this to an issue and restart. Or address any concerns.

[worktrunk-bot]

No need to restart — there's no issue-first requirement here, and for a docs change this size the diff is the clearest statement of the proposal. Reopening it as an issue would only lose the review thread.

Nothing outstanding from my side either: the approvals clause landed in 6af2ff5, and test_docs_are_in_sync regenerated the plugin mirror and the .well-known digest from it. test (linux), check-docs, lint, and codecov/patch are green; test (macos) and test (windows) are still running. Merging is @max-sixty's call — I only review.

And thanks for the report behind it: a pre-start hook that links a gitignored venv is exactly the case the old example broke on, and it wasn't obvious from the prose.

[max-sixty]

thanks @passitalong ! this is much better