ldraney/claude-custom
1
0
Fork 0
Code Issues 32 Pull requests Projects Releases Packages Wiki Activity Actions

Feature: Cross-repo worktree isolation hook and dev agent profile update #205

New issue
Closed
opened 2026-03-28 11:38:01 +00:00 by forgejo_admin · 0 comments
forgejo_admin commented 2026-03-28 11:38:01 +00:00
Contributor
Copy link

Type

Feature

Lineage

Child of forgejo_admin/pal-e-platform#188 (Cross-repo worktree isolation for parallel agents)

Repo

forgejo_admin/claude-custom

User Story

As a platform operator spawning parallel Dev agents
I want a PreToolUse hook that warns when agents attempt unsafe cross-repo checkouts, plus updated dev agent instructions
So that parallel agents working on repos other than the spawning repo get isolated working directories and cannot clobber each other

Context

On 2026-03-26, three parallel Dev agents were spawned to work on westside-playground. All three ran cd ~/westside-playground && git checkout ... against the same shared checkout, clobbering each other's branches and working tree state. Work was lost.

The root cause: the worktree-workflow SOP and agent-spawn-conventions only cover isolation for the spawning repo. When agents work on a different repo, there is no isolation mechanism. This child ticket implements the enforcement side: a PreToolUse hook to detect the unsafe pattern, dev agent profile updates with cross-repo isolation instructions, and /tmp/ clone cleanup.

File Targets

Files to create or modify in claude-custom:

  1. NEW: hooks/cross-repo-isolation.sh — PreToolUse hook that:
    • Detects when an agent runs cd ~/other-repo && git checkout on a shared checkout
    • Warns/blocks and suggests the isolated alternative: git clone ~/repo /tmp/{repo}-{branch}
    • Must be lightweight (< 50ms) — pattern match on command string, not filesystem checks
    • Should NOT fire for the spawning repo (which already has worktree isolation)
  2. agents/dev.md — add cross-repo isolation instructions:
    • When working on a repo other than the spawning repo, clone to /tmp/{repo}-{branch}
    • Never cd ~/shared-checkout && git checkout on a non-spawning repo
    • Clean up /tmp/ clones when done
  3. cleanup-worktrees.sh (or equivalent) — add /tmp/ clone cleanup logic for cross-repo clones

Acceptance Criteria

  • hooks/cross-repo-isolation.sh exists and detects the unsafe cd ~/repo && git checkout pattern on shared checkouts
  • The hook suggests /tmp/{repo}-{branch} clone as the safe alternative
  • The hook does NOT fire for the spawning repo (which uses isolation: worktree)
  • agents/dev.md includes cross-repo isolation instructions
  • /tmp/ clone cleanup mechanism exists (in cleanup-worktrees.sh or equivalent)
  • When a Dev agent works on a non-spawning repo, it clones to /tmp/{repo}-{branch}
  • When parallel agents target the same non-spawning repo, each gets its own isolated directory

Test Expectations

  • Manual test: run bash hooks/cross-repo-isolation.sh with mock inputs simulating cd ~/westside-playground && git checkout feature-branch — hook fires warning
  • Manual test: run with mock inputs simulating work in the spawning repo — hook does NOT fire
  • Manual test: spawn two parallel agents targeting the same non-spawning repo — confirm separate /tmp/ directories
  • agents/dev.md contains cross-repo isolation section

Constraints

  • Hook must be lightweight (< 50ms) — pattern match on command string, not filesystem checks
  • Follow the existing hook structure in claude-custom/hooks/
  • Cross-repo isolation is Dev-agent-only — QA agents are read-only and don't need this
  • The /tmp/ clone pattern aligns with the existing CLAUDE.md Worktree Isolation section in pal-e-platform
  • claude-custom#184 covers adjacent worktree gaps (freshness, cleanup) but NOT the cross-repo isolation hook — no overlap

Checklist

  • hooks/cross-repo-isolation.sh created and tested
  • agents/dev.md updated with cross-repo isolation instructions
  • /tmp/ clone cleanup added to cleanup script
  • Hook registered in settings.json (or equivalent hook config)
  • No overlap with claude-custom#184 scope

Related

  • Parent: forgejo_admin/pal-e-platform#188
  • Sibling (Dottie): SOP updates to worktree-workflow and agent-spawn-conventions — tracked as Dottie task on parent issue
  • claude-custom#184 — adjacent worktree gaps (freshness, cleanup), no overlap
  • worktree-workflow (pal-e-docs SOP) — the existing isolation SOP
  • agent-spawn-conventions (pal-e-docs convention) — pre-spawn checklist
### Type Feature ### Lineage Child of `forgejo_admin/pal-e-platform#188` (Cross-repo worktree isolation for parallel agents) ### Repo `forgejo_admin/claude-custom` ### User Story As a platform operator spawning parallel Dev agents I want a PreToolUse hook that warns when agents attempt unsafe cross-repo checkouts, plus updated dev agent instructions So that parallel agents working on repos other than the spawning repo get isolated working directories and cannot clobber each other ### Context On 2026-03-26, three parallel Dev agents were spawned to work on `westside-playground`. All three ran `cd ~/westside-playground && git checkout ...` against the same shared checkout, clobbering each other's branches and working tree state. Work was lost. The root cause: the `worktree-workflow` SOP and `agent-spawn-conventions` only cover isolation for the spawning repo. When agents work on a different repo, there is no isolation mechanism. This child ticket implements the enforcement side: a PreToolUse hook to detect the unsafe pattern, dev agent profile updates with cross-repo isolation instructions, and `/tmp/` clone cleanup. ### File Targets Files to create or modify in `claude-custom`: 1. **NEW: `hooks/cross-repo-isolation.sh`** — PreToolUse hook that: - Detects when an agent runs `cd ~/other-repo && git checkout` on a shared checkout - Warns/blocks and suggests the isolated alternative: `git clone ~/repo /tmp/{repo}-{branch}` - Must be lightweight (< 50ms) — pattern match on command string, not filesystem checks - Should NOT fire for the spawning repo (which already has worktree isolation) 2. **`agents/dev.md`** — add cross-repo isolation instructions: - When working on a repo other than the spawning repo, clone to `/tmp/{repo}-{branch}` - Never `cd ~/shared-checkout && git checkout` on a non-spawning repo - Clean up `/tmp/` clones when done 3. **`cleanup-worktrees.sh`** (or equivalent) — add `/tmp/` clone cleanup logic for cross-repo clones ### Acceptance Criteria - [ ] `hooks/cross-repo-isolation.sh` exists and detects the unsafe `cd ~/repo && git checkout` pattern on shared checkouts - [ ] The hook suggests `/tmp/{repo}-{branch}` clone as the safe alternative - [ ] The hook does NOT fire for the spawning repo (which uses `isolation: worktree`) - [ ] `agents/dev.md` includes cross-repo isolation instructions - [ ] `/tmp/` clone cleanup mechanism exists (in `cleanup-worktrees.sh` or equivalent) - [ ] When a Dev agent works on a non-spawning repo, it clones to `/tmp/{repo}-{branch}` - [ ] When parallel agents target the same non-spawning repo, each gets its own isolated directory ### Test Expectations - [ ] Manual test: run `bash hooks/cross-repo-isolation.sh` with mock inputs simulating `cd ~/westside-playground && git checkout feature-branch` — hook fires warning - [ ] Manual test: run with mock inputs simulating work in the spawning repo — hook does NOT fire - [ ] Manual test: spawn two parallel agents targeting the same non-spawning repo — confirm separate `/tmp/` directories - [ ] `agents/dev.md` contains cross-repo isolation section ### Constraints - Hook must be lightweight (< 50ms) — pattern match on command string, not filesystem checks - Follow the existing hook structure in `claude-custom/hooks/` - Cross-repo isolation is Dev-agent-only — QA agents are read-only and don't need this - The `/tmp/` clone pattern aligns with the existing `CLAUDE.md` Worktree Isolation section in `pal-e-platform` - `claude-custom#184` covers adjacent worktree gaps (freshness, cleanup) but NOT the cross-repo isolation hook — no overlap ### Checklist - [ ] `hooks/cross-repo-isolation.sh` created and tested - [ ] `agents/dev.md` updated with cross-repo isolation instructions - [ ] `/tmp/` clone cleanup added to cleanup script - [ ] Hook registered in `settings.json` (or equivalent hook config) - [ ] No overlap with `claude-custom#184` scope ### Related - Parent: `forgejo_admin/pal-e-platform#188` - Sibling (Dottie): SOP updates to `worktree-workflow` and `agent-spawn-conventions` — tracked as Dottie task on parent issue - `claude-custom#184` — adjacent worktree gaps (freshness, cleanup), no overlap - `worktree-workflow` (pal-e-docs SOP) — the existing isolation SOP - `agent-spawn-conventions` (pal-e-docs convention) — pre-spawn checklist
forgejo_admin 2026-03-28 18:47:55 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
217-enhance-skill-review-ticket-verify-arch
86-epilogue-nits-hook-updates-dottie-config
76-add-sessionstart-hook-to-detect-missing
69-fix-block-docs-writes-sh-security-gap-ad
51-phase-3-agent-label-behavior-posttooluse
No results found.
Labels
Clear labels   
domain:backend

   
domain:devops

   
domain:frontend

   
status:approved

QA passed, awaiting merge approval

  
status:in-progress

Dev agent is actively working

  
status:needs-fix

QA found issues, back to dev

  
status:qa

PR submitted, awaiting QA review

  
type:bug

Bug fix

  
type:devops

Infrastructure/CI/config work

  
type:feature

New functionality

No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/claude-custom#205
No description provided.