Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(skill): frame hook approvals as user consent, stop advocating --yes (#3146)
Worktrunk Bot9147c0e46d58
diff --git a/.gitignore b/.gitignoreindex bf6d9744f..7ab874faf 100644--- a/.gitignore+++ b/.gitignore@@ -2,6 +2,9 @@docs/static/assets/docs/demos/out/+# Claude Code per-developer local settings (never share these)+.claude/settings.local.json+# Lychee link checker cache.lycheecachetest-concurrent.shdiff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.jsonindex 59f4f0ac0..b879b4362 100644--- a/docs/static/.well-known/agent-skills/index.json+++ b/docs/static/.well-known/agent-skills/index.json@@ -6,7 +6,7 @@"type": "skill-md","description": "Guidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.","url": "./worktrunk/SKILL.md",- "digest": "sha256:8989343881b190da544109b7d813a3f823aa17b74e0f4b4becec6bb6b5bb5ec9"+ "digest": "sha256:2a41c53d60232fd8d8a4973474f63dde4b5339738f2a728eac309a0162947f35"}]}diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.mdindex 8fe4efaee..ab68bcf99 100644--- a/skills/worktrunk/SKILL.md+++ b/skills/worktrunk/SKILL.md@@ -267,7 +267,9 @@ grep -A 20 "## Warning Messages" reference/shell-integration.md## Hook Approvals in Non-Interactive Sessions-Project hooks and project aliases prompt for approval on first run, so an untrusted `.config/wt.toml` can't silently execute arbitrary commands. Agents running `wt merge`, `wt switch`, or other commands that trigger hooks will hit an error like:+Worktrunk never runs a project's hooks or aliases until the user has explicitly approved them. The commands in `.config/wt.toml` are arbitrary shell code shipped in a repository the user may have just cloned, so on first run Worktrunk shows each command and waits for the user to approve it — an untrusted `.config/wt.toml` cannot silently execute anything. Approvals are stored per-project in `~/.config/worktrunk/approvals.toml` and re-prompted whenever a command template changes, so a hook can't be swapped for a different command after it was approved.++Agents running `wt merge`, `wt switch`, or other commands that trigger hooks will hit an error like:```▲ cargo-difftest needs approval to execute 1 command:@@ -277,12 +279,11 @@ Project hooks and project aliases prompt for approval on first run, so an untrus↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt config approvals add```-Two resolutions exist — pick based on who the agent is running for:+The resolution is for the user to make the trust decision themselves:-- **`wt config approvals add`** — interactive prompt that stores approvals to `~/.config/worktrunk/approvals.toml`. Run once per project; persists across invocations until the command template changes or the project moves. This is the right choice when the human owns the trust decision.-- **`--yes`** / `-y` — bypasses approval for a single invocation. Appropriate for CI/CD where hook contents are controlled by the pipeline itself.+- **`wt config approvals add`** — interactive prompt where the user reviews each command before it is stored to `~/.config/worktrunk/approvals.toml`. Run once per project; the approval persists across invocations until the command template changes or the project moves. This is the path to recommend — the user reviews and consents to exactly the commands that will run.-**When invoked as an agent, stop and escalate to the user** — pre-approval is a security decision about whether this project's hooks should be trusted to run arbitrary commands on their machine. Tell the user to run `wt config approvals add` (or review and re-run with `--yes` if they accept the CI-style one-shot bypass). Don't reach for `--yes` on the user's behalf just to unblock the command.+**When invoked as an agent, stop and escalate to the user.** Approving a project's hooks is a security decision about whether this repository should be trusted to run arbitrary commands on the user's machine — that decision belongs to the user, not the agent. Tell the user to run `wt config approvals add` and let them review the commands. Do not run `--yes` on the user's behalf: it skips the approval gate for that invocation, so reaching for it to unblock a command defeats the protection. `--yes` exists for CI/CD pipelines that already control their own hook contents; it is not a shortcut for an interactive agent to silence an approval prompt.## Advanced: Agent Handoffs