pal-e-docs

Bug: Dev agents pollute ~/claude-custom main checkout

bug-claude-custom-worktree-pollution Doc

bug resolved
Project
Severity: High — breaks agent spawning mid-session
Observed: 2026-03-07 (twice in same session, PR #58 and issue #59), 2026-03-16 (session startup warning: ~/claude-custom on branch 115-vector-powered-startup-briefing with uncommitted changes to plugins/installed_plugins.json)

Problem

Dev agents spawned with isolation: "worktree" targeting claude-custom repo check out feature branches in ~/claude-custom directly instead of using an isolated worktree. Because ~/.claude/hooks/ symlinks to ~/claude-custom/hooks/, every branch checkout makes the in-progress hook live immediately.

Impact

  • PR #58: New issue-gate hook was live before merge (harmless — desired behavior)
  • Issue #59: Schema-based hook went live referencing a schema file that doesn't exist on main. Broke QA agent spawning with "Agent spawn schema not found"
  • 2026-03-16: Session startup hook warns about uncommitted changes — branch 115 left dirty after vector-powered-startup work. Hooks on that branch are live instead of main.

Root Cause

isolation: "worktree" creates a worktree relative to the invoking repo (~/pal-e-platform), not the target repo (~/claude-custom). The dev agent then clones or checks out claude-custom in ~/claude-custom directly, switching the branch on the main checkout.

Workaround

After every agent that touches claude-custom, run: cd ~/claude-custom && git checkout main && git pull

Acceptance Criteria

  • Dev agents working on claude-custom never switch the branch on ~/claude-custom
  • ~/.claude/hooks/ always reflects main branch during a session
  • In-progress hook changes are never live before merge
  • Best: CLAUDE.md instruction — Add to claude-custom's CLAUDE.md: "Always clone to /tmp/claude-custom-{branch} for development. Never work in ~/claude-custom directly." Cheapest fix, aligns with agent-spawn-conventions.
  • Better: Post-agent reset hook — SessionStart hook that checks ~/claude-custom is on main and clean. Already partially exists (the startup warning is this hook). Extend it to auto-reset.
  • Best long-term: Break the symlink — Copy hooks on deploy/merge instead of symlinking. Requires a deploy step but eliminates the root cause entirely.
  • todo-worktree-tmp-migration — /tmp worktrees would partially solve this
  • phase-postgres-epilogue-cleanup — worktree migration is epilogue item 1
  • plan-pal-e-agency Phase 16 — Agent Model Completion (absorbs this bug)