M167.4 — Manual Worktree Pattern for Parallel Agents

Path B workaround empirically validated

Codifies the manual pre-create worktree pattern in /ork:implement as a workaround for the broken Agent(isolation="worktree") behavior in CC Opus 4.7 (Nov 2026 — Apr 2026). Closes Yonatan-HQ/platform#3224 Path B.

The bug

Spawn pattern
Agent(subagent_type="x", isolation="worktree", run_in_background=true)
Agent(subagent_type="y", isolation="worktree", run_in_background=true)
Agent(subagent_type="z", isolation="worktree", run_in_background=true)
Agent(subagent_type="w", isolation="worktree", run_in_background=true)
Expected behavior
primary ──── HEAD \ ├── worktree-x ── feat/x branch (agent X works here) ├── worktree-y ── feat/y branch (agent Y works here) ├── worktree-z ── feat/z branch (agent Z works here) └── worktree-w ── feat/w branch (agent W works here)
Actual behavior (git reflog of primary)
checkout: moving from feat/x to feat/y
checkout: moving from feat/y to feat/z
checkout: moving from feat/z to feat/w
...
primary ──── HEAD ── feat/x ── feat/y ── feat/z ── feat/w ↑ ↑ ↑ ↑ agent X agent Y agent Z agent W (untracked files stashed at each switch)

Result: 3 of 4 agents hit the ~60-tool-use cliff because pre-push hooks fail on thrashed node_modules.

Empirical evidence (M164 overnight, 2026-05-11→12)

PatternTool-uses / agentCutoffs
Wave 1 — isolation="worktree" 60 – 86 3 of 4
Wave 2/3 — manual pre-create 4 – 22 0 of 8

The fix — manual pre-create + cd-first

Step 1 — Lead pre-creates worktrees
backend_wt = setup_agent_worktree(
    REPO, SLUG, "feat/x-backend"
)
frontend_wt = setup_agent_worktree(
    REPO, SLUG, "feat/x-frontend"
)
tests_wt = setup_agent_worktree(
    REPO, SLUG, "feat/x-tests"
)
Step 2 — Spawn with explicit cd in prompt
Agent(
  subagent_type="backend-system-architect",
  prompt=(
    f"FIRST: cd {backend_wt}. "
    f"THEN implement: ... "
    f"Commit + push + open PR "
    f"from {backend_wt}."
  ),
  run_in_background=true)

Helper function

import subprocess

def setup_agent_worktree(repo_root: str, slug: str, branch: str) -> str:
    """Pre-create a worktree off origin/main and return its absolute path."""
    path = f"{repo_root}/../{slug}-{branch.split('/')[-1]}"
    subprocess.run(
        ["git", "-C", repo_root, "worktree", "add",
         "-b", branch, path, "origin/main"],
        check=True,
    )
    return path

Why this works

The isolation param is accepted by CC but the worktree may not be created (or cd'd into) before the agent's first Bash call fires. By the time the agent runs, its CWD is the primary tree.

Manual pre-creation moves the git worktree add into the deterministic lead context BEFORE the agent starts. The agent's prompt then explicitly cd's into the prepared worktree as the first instruction.

Prompt constraints (load-bearing)

  1. cd must be the FIRST Bash call. Wrap in FIRST: cd <path>. THEN: ... so the agent can't skip.
  2. Forbid touching the primary tree. Add: "Do not cd out. All commits, pushes, PRs originate from {worktree-path}."
  3. Push early. Add: "As soon as you have a minimal working file + 1 reference doc, commit + push + open PR. Iterate via follow-up commits."
  4. Explicit branch. Always pass -b feat/<slug>-<role> — never let the agent choose its own.

What this doesn't fix

References