dispatch prompt: EnterWorktree-first isolation; manual git worktree add stalls Claude bg agents on approval - #107
Merged
Conversation
The branch blocks told every dispatched agent to isolate with `git worktree add <path> -b <branch>`. For a Claude Code background agent that is a trap: the harness rejects file edits until its own EnterWorktree tool has run, and pointing that tool at a pre-made worktree raises an approval prompt a headless session can never answer. Three of four dispatches on 2026-07-31 followed the instruction literally and froze two minutes in, sitting `running` for eleven hours on dead sessions; the one agent that used name-based EnterWorktree instead finished. Both templates now name the harness mechanism first and keep `git worktree add` as the fallback for agents without one. Because such a tool names the branch itself, the block also spells out the `git switch -c <branch>` that puts the work on the branch Voro tracks. The isolation wording moves into a shared const beside the register and rebase sentences so the two templates cannot drift. The repo's `.claude/settings.json` allows EnterWorktree outright, so even a path-entry call cannot hang a headless job here. Verified with `cargo test --workspace` and `cargo clippy --all-targets -D warnings`; both rendered preambles were printed and read end to end.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the dispatch preamble's two branch blocks so the agent isolates with
its harness's own worktree mechanism first, and adds a repo-level permission
allow so a Claude dispatch cannot stall on the approval prompt either way.
Why
The blocks told every agent to isolate with
git worktree add <path> -b <branch>. For a Claude Code background agent that is a trap: the harnessrejects file edits until its own
EnterWorktreetool has run, and pointingthat tool at a pre-made worktree raises an interactive approval prompt a
headless session can never answer. On 2026-07-31 three of four dispatches
(#312, #313, #294) followed the instruction literally and froze about two
minutes in, sitting
runningfor eleven hours on dead sessions; the one agentthat used name-based EnterWorktree instead (#314) finished.
What changed
crates/voro/src/dispatch.rs: newBRANCH_ISOLATE_SENTENCE, shared byASSIGNED_BRANCH_TEMPLATEandUNASSIGNED_BRANCH_TEMPLATEbeside theexisting register and rebase sentences so the three cannot drift. It names
the harness mechanism first (
EnterWorktree, "creates and enters a worktreeunder
.claude/worktrees/unprompted"), demotesgit worktree add <path> -b <name>to the fallback for agents without one, and — since such a tool namesthe branch itself — spells out the
git switch -c <name>that puts the workon the branch Voro tracks. The unassigned template now uses
<name>throughout instead of mixing
<name>and<branch>.registration via
voro set --branch, and the stale-base rebase sentence areall unchanged and still shared.
.claude/settings.json(new): allowsEnterWorktree, so even a path-entrycall cannot hang a headless job in this checkout.
docs/DESIGN.md§11 worktree lifecycle: records that how the agent makes itsworktree is its own business, why the harness mechanism is preferred, and
that a nested worktree is immaterial downstream because
openand cleanupboth find it through
git worktree list.Verification
cargo test --workspace(542 tests) andcargo clippy --workspace --all-targets -- -D warningsboth clean. New testpreamble_puts_the_harness_worktree_tool_ahead_of_git_worktree_addasserts,for both the assigned and unassigned cases, that the prompt names
EnterWorktree, carriesgit switch -c <branch>, and mentions the harnessmechanism before the manual fallback. Both rendered preambles were printed in
full and read end to end. This task itself was done through the new flow —
EnterWorktree, then
git switch -c task-320-enterworktree-dispatch— with noapproval prompt.
Branch
task-320-enterworktree-dispatchis committed locally and not pushed.Follow-up filed as #324 (nested worktrees show untracked in projects that do
not ignore
.claude/worktrees/).