feat: Claude Code's own worktrees are workers too (decision 0015)

[mauricios]

What changed and why

Accepts and implements 0015, which amends 0008.

Teams that work in the desktop app start tasks in a new session with its worktree option, which already gives the task its own worktree, branch, and session. Two projects running the parallel-agents module had such worktrees in use: the module's origin project, and the marketing site upgraded this week, with four each. Meanwhile the framework gave those sessions no role and sent the developers to a second tool. Claude Code now covers most of what the scripts were added for. .worktreeinclude copies the env file, project-scope plugins and the local settings reach worktrees, and the app archives its worktrees.

With the module, every linked worktree is a worker. A task gets its worktree one of two ways:

• Claude Code's worktree, by default: a new desktop session with the worktree option, or claude --worktree. The worker renames the generated branch to <type>/<slug> after triage.
• The scripts (/dispatch): when the worktree needs a port, setup or start commands, or a base branch other than the default branch.

Changes

• skeleton/.claude/hooks/session-context.sh (core):
  • In the main checkout, it says which route this project's tasks take, read from worktree.conf.
  • In a worktree the scripts didn't set up, it adds a line for each gap: a generated branch name or a detached HEAD, a missing env file, the scripts' setup, or the wrong base branch.
  • Where the worktree sits no longer matters, so the desktop app's "Worktree location" setting can't change the role.
• worktree-new.sh writes a marker in the worktree's own git directory, which git status doesn't show. Worktrees from before the marker are recognized by their folder name.
• _worktree-lib.sh: scripts_worktree and generated_branch replace builtin_worktree.
• worktree-ls.sh lists Claude Code's worktrees as workers, marked "not from the scripts". It flags the ones on a generated branch or a detached HEAD, instead of asking to move task work out of them.
• .worktreeinclude (new, module) lists the env file.
• /dispatch opens with § Which route. Started from the desktop app, it opens the scripts' worktree as the session's folder rather than using the worktree option.
• Docs:
  • PARALLEL-AGENTS.md gets § Two routes, a comparison table, and § Claude Code's worktrees.
  • MODULE.md adds a customize step for .worktreeinclude.
  • The scenario, onboarding, the README table, and the skills catalog describe both routes.
  • protect-hub.sh's message names both routes.
• Records: 0015 accepted; 0008 marked "amended by 0015"; the index updated.

Upgrade impact

In CHANGELOG.md § Unreleased:

• Overwrite:
  • Core: session-context.sh, protect-hub.sh, the hooks README.
  • With the module: the three scripts and /dispatch.
• Merge (with the module): docs/PARALLEL-AGENTS.md.
• Additive: .worktreeinclude, kept in step with ENV_FILE.
• No migration: existing script worktrees are recognized by folder name.

How to verify

1. Run ./evals/run-evals.sh.
   • The hook tests cover the dispatcher's route in three configurations: no setup, a server project, and a non-default base. They cover a script worktree (no gaps), Claude Code's worktree (generated branch, missing env file), a detached HEAD, a marked worktree outside the usual place, a renamed branch, and the wrong base.
   • The module tests cover the marker (invisible to git status) and worktree-ls.sh's flags.
2. In a repository with the module, start a desktop session with the worktree option. Its context should say WORKER and ask to rename the branch after triage.

Verified / not verified

• Verified: static suites 131, 71, 43 → 45, and 9 pass. I also checked the session-start output by hand, for the main checkout and for a claude/bold-oak worktree.
• Not verified: a live desktop session with the worktree option, and .worktreeinclude copying the env file. Both are Claude Code behavior, from its docs. The pilot project can confirm them once it takes this change.

Merge danger

Reversible: yes. Reverting restores the "no role" message and the old flag. The marker files left in worktrees' git directories are harmless.
Blast radius: sessions in projects with the parallel-agents module, once they take this upgrade. Sessions in Claude Code's worktrees get work instructions instead of "ask for a dispatch". Nothing changes without the module.

🤖 Generated with Claude Code