greprag 5.82.1 → 5.83.0

package/skill/templates/chip-spawn.md

@@ -2,9 +2,9 @@
 
 **Grok Build?** Stop. Run `greprag load grok-chip-spawn`. This entry is Claude `spawn_task`.
 
-The `pre-spawn-check` PreToolUse hook **validates** chip prompts at the spawn boundary, but **cannot inject content** — `modifiedInput` is silently dropped by the CCD harness for MCP `spawn_task` calls (see `adr/spawn-task-hook-mode.md` 2026-05-27 entry). The agent writes Block 1 into the prompt itself. Validator rejects with `permissionDecision: deny` and a remediation reason if the `Chip: ` title prefix or the Block 1 worktree marker is missing.
+The `pre-spawn-check` PreToolUse hook **validates** chip prompts at the spawn boundary, but **cannot inject content** — `modifiedInput` is silently dropped by the CCD harness for MCP `spawn_task` calls (see `adr/spawn-task-hook-mode.md` 2026-05-27 entry). The agent writes Block 1 into the prompt itself. Validator rejects with `permissionDecision: deny` and a remediation reason if the `Chip: ` title prefix or the current Block 1 (its `git branch -m` reuse step and its `git worktree add` local-start step) is missing.
 
-**Chips talk over native `SendMessage`, not greprag.** Claude Code addresses live sessions by name on this machine — `ListAgents` to discover, `SendMessage to: "<name>"` to send, delivered at the recipient's next tool boundary. The parent gets native start and completion notifications for every chip it spawns. So there is no IN-FLIGHT ping, no `greprag send` report-back, and **no watcher to arm**. greprag's role in the chip loop is now content only (the `fix list` pre-pull below, and `fix spawn` as mission generator).
+**Chips talk over native `SendMessage`, not greprag.** Claude Code addresses live sessions by name on this machine — `ListAgents` to discover, `SendMessage to: "<name>"` to send, delivered at the recipient's next tool boundary — unless the recipient runs in a different permission mode, which holds the message for the operator's approval and may let it expire. The parent gets native start and completion notifications for every chip it spawns. So there is no IN-FLIGHT ping, no `greprag send` report-back, and **no watcher to arm**. greprag's role in the chip loop is now content only (the `fix list` pre-pull below, and `fix spawn` as mission generator).
 
 > **Part of a multi-chip mission?** If this chip is one of ≥2 aimed at a single objective, you should already be inside a chip-leader plan — your **base branch** and **merge target** (the integration branch, *never* master) come from it. If you're not, stop and run `greprag load chip-leader` first. A lone chip targeting its own objective proceeds here directly.
 
@@ -18,6 +18,9 @@ Add `mode: interactive` as the first line of the task body to pause the chip for
 
 ## Block 1 — Setup (verbatim, substitute `<slug>`)
 
+<!-- adr: adr/prespawn-augmentation.md -->
+The desktop app starts each spawned chip in a fresh worktree of its own. Block 1 keeps that worktree and renames its branch to `chip/<slug>`; it makes `.claude/worktrees/<slug>` only on a local start.
+
 `<slug>` = title slugified (e.g. `Chip: Fix synthesis loop` → `fix-synthesis-loop`). `<parent-name>` = YOUR native session name, the one `ListAgents` prints as "This session is `<name>`" — that is the chip's reply address, not a greprag 8-hex.
 
 ````
@@ -25,20 +28,32 @@ Add `mode: interactive` as the first line of the task body to pause the chip for
 
 ```bash
 main_root=$(git rev-parse --git-common-dir | xargs dirname)
-cd "$main_root"
-
-if [ -d ".claude/worktrees/<slug>" ]; then
-    cd ".claude/worktrees/<slug>"
-    current_branch=$(git branch --show-current)
-    if [ "$current_branch" = "chip/<slug>" ]; then
-        echo "Worktree already exists on correct branch — reusing"
+branch=$(git branch --show-current)
+
+if [ "$branch" = "chip/<slug>" ]; then
+    echo "Already on chip/<slug> — reusing this worktree"
+elif [ "$(git rev-parse --path-format=absolute --git-dir)" != "$(git rev-parse --path-format=absolute --git-common-dir)" ] \
+    && [ -n "$branch" ] && [ -z "$(git status --porcelain)" ] \
+    && [ -z "$(git for-each-ref --format='%(upstream)' "refs/heads/$branch")" ] \
+    && git merge-base --is-ancestor HEAD "$(git -C "$main_root" rev-parse HEAD)"; then
+    # The app already gave this chip a fresh worktree (clean, local branch, no commits of its own): use it.
+    git branch -m "chip/<slug>" || exit 1
+else
+    # Started locally, so there is no fresh worktree here: make the chip's own.
+    cd "$main_root"
+    if [ -d ".claude/worktrees/<slug>" ]; then
+        cd ".claude/worktrees/<slug>"
+        current_branch=$(git branch --show-current)
+        if [ "$current_branch" = "chip/<slug>" ]; then
+            echo "Worktree already exists on correct branch — reusing"
+        else
+            echo "ERROR: Worktree dir exists but is on branch '$current_branch', not 'chip/<slug>'. Remove it and retry." >&2
+            exit 1
+        fi
     else
-        echo "ERROR: Worktree dir exists but is on branch '$current_branch', not 'chip/<slug>'. Remove it and retry." >&2
-        exit 1
+        git worktree add ".claude/worktrees/<slug>" -b chip/<slug>
+        cd ".claude/worktrees/<slug>"
     fi
-else
-    git worktree add ".claude/worktrees/<slug>" -b chip/<slug>
-    cd ".claude/worktrees/<slug>"
 fi
 
 # Pristine worktrees check out source only — if the repo ships a worktree
@@ -57,7 +72,7 @@ Your parent session is named `<parent-name>`. When you finish, report to it with
 
 **Worktree launch failed? START THE CHIP LOCALLY instead.** The harness creates the worktree before your Block 1 ever runs, and when that fails the spawning session sees nothing — no error, no exit code, only the operator reporting it is stuck. A local start is safe and self-correcting: Block 1 creates the worktree itself as its first action, so nothing is lost and nothing is done twice. If the same slug fails again, change the slug — you cannot see harness-side worktree errors, so elimination is the only tool you have.
 
-**Multi-chip mission (`greprag load chip-leader`)?** The spawn title alone does NOT reach FleetView's watcher registry — that title is auto-generated by gpt-5.4-nano from your opening turn. So the leader will have you **stamp your registry title in Block 1**, right after the `cd` into the worktree:
+**Multi-chip mission (`greprag load chip-leader`)?** The spawn title alone does NOT reach FleetView's watcher registry — that title is auto-generated by gpt-5.4-nano from your opening turn. So the leader will have you **stamp your registry title in Block 1**, right after the worktree setup:
 
 ```bash
 greprag session retitle <your-own-8hex> "Chip <Label> — <workstream>"
@@ -72,21 +87,22 @@ Close the task body with this (substitute `<slug>` + `<parent-name>`):
 ````
 ---
 
-**Report back:** when the work is committed, send your result to the parent with native `SendMessage`:
+**Report back:** when the work is committed, send your result to the parent with native `SendMessage`, then end your turn:
 
 - `to`: `"<parent-name>"`
 - `message`: status, commit hash, branch `chip/<slug>`, and a one-line summary.
+- `notify_when_idle`: `true`
 
-The parent is a live session on this machine — no greprag address, no watcher. If `SendMessage` errors because the parent has ended, stop and leave the commit on the branch; the parent picks it up at merge.
+The parent is a live session on this machine — no greprag address, no watcher. A successful send only means queued: a parent in a different permission mode holds the report for the operator's approval and may let it expire, and the `[Cross-session delivery notice]` saying so reaches you only after your turn ends.
 
-**Then close yourself:** once the report has landed, run `/close`. It takes the chip path automatically (it recognises a `chip/` branch), so it sends no question and touches nothing outside this worktree — it commits any stragglers, confirms the report, and archives the session, which removes this worktree. Your branch survives for the parent to merge. If the report failed because the parent is gone, do NOT close — leave the worktree standing.
+**Then close yourself:** run `/close` only when the parent's `[Cross-session idle notice]` says it is idle and no delivery notice said the report was held, refused or not approved before expiry. `/close` takes the chip path automatically (it recognises a `chip/` branch), so it sends no question and touches nothing outside this worktree — it commits any stragglers and archives the session, which removes this worktree. Your branch survives for the parent to merge. Anything else — a held, refused or expired report, or `SendMessage` erroring because the parent has ended — means the report did not land: do NOT close, leave the commit on the branch and the worktree standing, and tell the operator where the report is (a held one waits for their approval in `<parent-name>`).
 
 **Cleanup discipline (HARD RULE):** chip prompts forbid `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <other>`, raw `rm -rf` outside the worktree's tracked files.
 ````
 
 ## After spawning — do nothing
 
-No watcher. No arming. The harness tells you when the operator starts the chip and again when it ends, and the chip's own `SendMessage` lands at your next tool boundary. Never arm a `Monitor` on greprag's inbox for chip traffic — the inbox watcher exists for Discord, inbound email, and cold opens, not for chips.
+No watcher. No arming. The harness tells you when the operator starts the chip and again when it ends. Never arm a `Monitor` on greprag's inbox for chip traffic — the inbox watcher exists for Discord, inbound email, and cold opens, not for chips.
 
 ## Before composing
 
@@ -100,6 +116,6 @@ Chips never `npm run deploy` (or Wrangler / another provider deploy) from the wo
 
 ## Parent merge discipline — prune at the merge (HARD RULE)
 
-When you (the parent) merge a chip branch — through the canonical commit path or a profile-declared merge — prune in the same breath: junction guard (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove .claude/worktrees/<slug>`, and `git branch -d chip/<slug>` once merged. A chip that closed itself has already removed its own worktree, so that path will be gone — delete the branch and move on, don't go hunting for it. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the integration-branch merge; the branch lives until the configured default-branch merge (chip-leader Phase 4).
+When you (the parent) merge a chip branch — through the canonical commit path or a profile-declared merge — prune in the same breath: find the worktree holding `chip/<slug>` in `git worktree list` (the app's own worktree when the chip reused it, `.claude/worktrees/<slug>` on a local start), junction guard it (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove <worktree>`, and `git branch -d chip/<slug>` once merged. A chip that closed itself has already removed its own worktree, so no worktree holds the branch — delete the branch and move on, don't go hunting for it. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the integration-branch merge; the branch lives until the configured default-branch merge (chip-leader Phase 4).
 
 **FIX chips report to the mission owner.** A `greprag fix spawn` mission is the source of truth for FIX behavior. `fix spawn` detects usable Git history and emits `workspaceMode`: Git uses an isolated worktree; non-Git, unavailable Git, or no commit uses the project-local task with serialized writes. Dispatch honors that mode without trying a worktree first. The FIX chip identifies the exact friction, makes the smallest durable root-cause fix, verifies and commits useful work, then reports the commit/result and cleanup parameters to the parent mission owner. It creates no human landing gate. If no live parent exists and the chip carries the full-goal mission, it follows the repo profile as mission owner.