feat(source-control): unify native-hook + /worktree-skill worktree creation via one shared helper

[kyle-sexton]

Summary

Unify Claude Code worktree creation so that both entry paths — the native WorktreeCreate hook (fires for claude --worktree and subagent isolation:"worktree") and the /worktree skill (EnterWorktree) — place worktrees in the same location via one shared helper. Today they diverge: the hook can relocate; the skill's EnterWorktree-in-a-git-repo lands in .claude/worktrees/ and the hook does not fire for it.

Component

plugins/source-control/skills/worktree/** + a shared helper script; consumed by the setup skill.

Background (verified this session)

• The WorktreeCreate hook prints the worktree dir to stdout and replaces git's default placement — but per the EnterWorktree tool contract, inside a git repo EnterWorktree creates under .claude/worktrees/ and does NOT consult the hook (it only delegates to the hook outside a git repo). So a hook alone cannot standardize the interactive /worktree create path.
• The hook must create the worktree itself (not merely echo a path) and re-implement .worktreeinclude copying (bypassed under a hook). Real stdin field is .name (docs say worktree_name — anthropics/claude-code #77566).

Design

A single shared helper (in the plugin) that: computes <root>/<owner>-<repo>-<slug> (root from the setup skill), runs git worktree add with the correct base, sanitizes the branch slug, handles detached HEAD, and copies .worktreeinclude-matched local files. Invoked by:

1. The WorktreeCreate hook (native --worktree / subagent isolation).
2. The /worktree skill — patched to call the shared helper (git worktree add to the external root) instead of relying on EnterWorktree's in-repo default.

Result: identical placement regardless of entry path.

Empirical gates (must pass before shipping the hook)

• Gate 1: Confirm whether EnterWorktree inside a D:\repos git repo fires the hook or goes to .claude/worktrees/; simultaneously dump raw hook stdin (jq .) to capture the real field set (.name, base ref, cwd) for the tested CC version. Pin the contract to that version.
• Gate 2: Confirm whether a hook-relocated subagent-isolation worktree (outside .claude/worktrees/) prompts/blocks under normal (non-bypassPermissions) permissions (docs: out-of-.claude/worktrees paths need approval; anthropics/claude-code #78212). If it blocks, autonomous isolation is incompatible without bypassPermissions — decide accordingly.

Acceptance criteria

• One shared helper owns path computation + creation + local-file copy.
• WorktreeCreate hook and /worktree skill both route through it → identical placement.
• Built against stdin .name; base-ref logic (fresh/head) reimplemented in the helper.
• Both empirical gates run and documented; ship gated on their outcome.
• Failure-safe: helper errors surface clearly; a hook failure that would brick all CC worktree creation is guarded/tested.

Part of

Worktree-convention epic: #398

[kyle-sexton]

Decision brief (2-minute read)

Problem. Claude Code worktrees can be created two ways — the native path (claude --worktree, subagent isolation:"worktree"), which a WorktreeCreate hook can relocate, and the /worktree skill, whose EnterWorktree call inside a git repo always lands in .claude/worktrees/ and never consults the hook. The moment #398's setup installs a relocating hook, the two paths produce worktrees in different places; the decision is how (and in what order) to route both through one shared helper.

Today. Verified against the current checkout: the plugin ships no WorktreeCreate hook and no shared helper — plugins/source-control/ contains only babysit scripts under bin/ and scripts/, and no hooks/ directory exists. plugins/source-control/skills/worktree/context/create.md implements create by validating a name and calling EnterWorktree as the final action, which in-repo lands in .claude/worktrees/<name>; its base-ref section says a project's WorktreeCreate hook "wins," which is true only for the native path, not for EnterWorktree in a repo. So today both paths coincidentally land in .claude/worktrees/ — both hitting the confirmed double-load bug (#400) — and divergence is one installed hook away. skills/setup/SKILL.md exists but currently configures only commit conventions and babysit; it has no worktree-root surface yet.

Options.

1. RECOMMENDED — Phased shared helper: skill first, hook behind the gates. Build the shared helper (path computation <root>/<owner>-<repo>-<slug>, git worktree add with base-ref logic, slug sanitization, .worktreeinclude copy) with the root read from a config seam (userConfig / tracked config that feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398's setup will later write — no hardcoded paths, per this repo's design rules). Phase A: patch /worktree create to call the helper instead of relying on EnterWorktree's in-repo default — this closes high-priority fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 immediately and depends on nothing undocumented. Phase B: ship the WorktreeCreate hook through the same helper only after both empirical gates pass (Gate 1: real stdin field set — docs say worktree_name, reality is reportedly .name, upstream [DOCS] WorktreeCreate hook stdin field is name, not the documented worktree_path anthropics/claude-code#77566; Gate 2: whether hook-relocated subagent worktrees prompt/block under normal permissions, #78212). Each phase is independently shippable and reversible; a gate failure kills only Phase B, not the fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 fix. One flagged uncertainty to verify in Phase A: replacing EnterWorktree changes how the session transitions into the worktree (cwd/session state) — confirm whether EnterWorktree can target the externally created worktree or whether the skill must instruct a cd/new session.
2. All-at-once (the issue's design as one gated change). Helper + hook + skill patch in a single PR, shipped only after both gates pass. Cleaner review, guaranteed-identical placement on day one — but the fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 token-waste fix waits on gate outcomes, and a Gate 2 failure (permission block on out-of-tree paths without bypassPermissions) could invalidate half the build after full investment. A buggy hook also risks bricking every native worktree creation in one release.
3. Skill-only; defer the hook indefinitely. Smallest blast radius: fix the interactive path, never touch the native one. But subagent isolation:"worktree" keeps landing in .claude/worktrees/ with the double-load, and the unification goal is abandoned rather than decided. Acceptable only if Gate 2 proves autonomous isolation incompatible.
4. Hook-only (non-viable — listed to preempt it). Configure the hook and leave the skill on EnterWorktree. Structurally cannot work: in-repo EnterWorktree bypasses the hook, so the interactive path never unifies.

Interaction with #398. #398 owns detect→decide→install (including computing the external root and installing the hook); #399's helper must consume that root through a config seam, never compute policy itself. Deciding #399 as recommended fixes the helper's interface first, letting #398 slot in as the root's producer without rework — and Phase A needs an interim root answer (explicit userConfig, or refuse-until-configured) until #398 ships; recommend refuse-with-guidance over inventing a default.

Related.

• feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398 — epic; produces the root + installs the hook; this decision defines the helper interface it consumes.
• fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 — the concrete high-priority double-load bug; closed by Phase A of the recommendation.
• chore(source-control): retire stale ghq-layout-sibling-pr-worktrees doc; plugin owns worktree convention #401 — retiring the stale dotfiles worktree doc follows once the plugin owns the convention.
• source-control: babysit worktree pruner hard-depends on ghq (undeclared, author-personal repo-layout tool) #438 — babysit worktree pruner's ghq coupling; same convention family, explicitly exempt per feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398's per-tool map.

[kyle-sexton]

Blocked-by #398 — held this pass (tower overnight decision resolver, Opus).

The RECOMMENDED phased shared-helper design (Phase A: route /worktree create through one shared helper with an interim refuse-with-guidance root until configured; Phase B: ship the WorktreeCreate hook only after the upstream stdin-field #77566 + out-of-tree-permission #78212 gates pass) is sound engineering and non-convention on its own.

But Phase A's "refuse until configured" depends on the worktree_root config key that #398 defines, and #398 is held for an operator convention ruling (central-external-root vs the documented sibling default). Finalizing #399 now would pre-empt that ruling.

Held pending #398. Once the operator rules #398, this is a reversible engineering decision the next decide/tower pass can settle.

This was generated by AI (tower overnight decision resolver, Opus).

[kyle-sexton]

Unblocked by operator ruling on #398 (central-external-root + worktree_root userConfig key ratified in-session 2026-07-21, recorded there). Phase A (shared helper, skill-first, interim refuse-with-guidance until configured) is now implementable; Phase B stays gated on the two empirical gates (upstream stdin-field + out-of-tree permission checks). Flipping to status: ready.

This was generated by AI (control tower, session 6).