greprag 0.9.1 → 0.11.0

package/skill/{SKILL.md → greprag/SKILL.md}

@@ -12,7 +12,7 @@ description: |
   "what's been happening in this project", "session context".
 metadata:
   author: travsteward
-  version: "3.5.0"
+  version: "3.7.0"
   repository: https://github.com/travsteward/greprag
 license: MIT
 ---
@@ -21,6 +21,12 @@ license: MIT
 
 The agent drives all setup and runs the briefing. Single source of truth: `greprag status --json`.
 
+### OpenCode vs Claude Code
+
+- **Claude Code**: hooks in `~/.claude/settings.json` + advisor skill — follow steps 1-6 below.
+- **OpenCode**: plugin at `~/.config/opencode/plugins/greprag-memory.ts` runs silently (injects recap via system prompt, stores turns automatically). The `/greprag` skill works on-demand in both. Run `greprag init --opencode` once to install.
+- Both share the same anchor (`.claude/project.json` or `.opencode/project.json`) and the same API key.
+
 ## Step 1 — Get the status
 
 ```bash
@@ -30,9 +36,23 @@ greprag status --json
 Parse the JSON. The keys to check, in this order:
 
 1. `auth.api_key_present`
-2. `hooks.session_start_recap`, `hooks.stop_store`, `hooks.user_prompt_submit_notify`
-3. `project.anchor_found`
-4. `project.memory_capture`, `project.session_start_recap`, `project.inbox_notify`
+2. `project.anchor_found`
+3. `project.memory_capture`, `project.session_start_recap`, `project.inbox_notify`
+
+For Claude Code, also check `hooks.session_start_recap`, `hooks.stop_store`, `hooks.user_prompt_submit_notify`.
+
+Also check the chip-coordination convention is installed in global CLAUDE.md (Step 3b):
+```bash
+if grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo CONV_V3
+elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo CONV_V2_NEEDS_UPGRADE
+elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo CONV_V1_NEEDS_UPGRADE
+else echo CONV_MISSING; fi
+```
+
+Also check the permission allowlist (Step 3c):
+```bash
+node -e "const s=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/settings.json','utf8'));const a=(s.permissions&&s.permissions.allow)||[];console.log(a.includes('Monitor')?'MON_OK':'MON_MISSING')"
+```
 
 For each gap, walk the user through the fix. When everything is configured, skip to Step 6 (briefing).
 
@@ -83,6 +103,122 @@ Edit `~/.claude/settings.json` to add the missing hook(s):
 
 Append the missing entries to the existing arrays (create the arrays if absent). Don't overwrite existing hooks from other tools.
 
+## Step 3b — Convention install (only if marker missing or out-of-date)
+
+The chip-spawning + agent-coordination convention is a one-time install into the user's global CLAUDE.md. Every project session reads it; without it, chips spawn without worktree isolation, inbox report-back, or reply-listening. Detect first:
+
+```bash
+if grep -q "greprag-conventions:start v3" ~/.claude/CLAUDE.md; then echo V3
+elif grep -q "greprag-conventions:start v2" ~/.claude/CLAUDE.md; then echo V2_UPGRADE
+elif grep -q "greprag-conventions:start v1" ~/.claude/CLAUDE.md; then echo V1_UPGRADE
+else echo MISSING; fi
+test -f ~/.claude/docs/agent-coordination.md && echo DOC_OK || echo DOC_MISSING
+```
+
+**If `MISSING`**, insert the v3 block into `~/.claude/CLAUDE.md` immediately after the `## Inbox` section (use the Edit tool, marker comments verbatim):
+
+```markdown
+<!-- greprag-conventions:start v3 -->
+## Chip Spawning & Agent Coordination
+
+Delegating work — `spawn_task` chip vs `Agent` tool, two chip modes, the worktree-first + inbox-report + reply-listening convention. Full spec: `~/.claude/docs/agent-coordination.md`.
+
+**Two chip modes** — pick deliberately:
+- **Mode A (default) — ship chip.** Lands in a worktree, ships code, user-in-loop optional. The workhorse. A chip that dispatches its own `Agent` sub-tasks mid-work is still Mode A — that's a behavior, not a peer mode.
+- **Mode B — discussion chip.** Lands as a context-rich conversation partner. Reads code, proposes, iterates. Ships nothing without explicit go-ahead. Output is a decision or a scoped follow-up chip. Reach for B the moment you notice you're proposing architecture from partial grep reads.
+
+**Spawn primitives** (not modes — pick by what fits the work):
+- `spawn_task` — Mode A or B chip. Worktree, chip UI, persistence, optional cross-project via `cwd:`.
+- `Agent` — one-shot delegation, returns once to caller. No chip lifecycle. Pass `subagent_type` (Explore / Plan / general-purpose / code-reviewer) when a specialized shape fits.
+
+**Non-negotiables for every `spawn_task` chip prompt:** (0.5) project facts pulled from `greprag fact`, (1) worktree-first setup, (2) `greprag send` report-back, (3) `Monitor` on own inbox for follow-ups. Without them the chip pollutes the main checkout, has no return channel, or dies after one report. Copy the boilerplate verbatim from the deep doc.
+
+**Reply listening (any session, not just chips).** Any time you `greprag send` a message that could draw a directive in response, arm a `Monitor` watcher on your own inbox in the same turn. Use the bash-wrapper form so the watcher auto-restarts if the inner SSE process dies (network blip, supervisor bug, Cygwin fork failure):
+
+```bash
+while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+Run under `Monitor` with `persistent: true`. Fall back to `--project <own-project>` instead of `--session` when no session identity is available. The Stop hook only fires between user prompts; without Monitor, mid-task replies are invisible until the next stop boundary.
+
+For real-time chip reports, the parent arms the same wrapped watcher (`--session <parent-session-id>` preferred, `--project <parent-project>` for multi-chip campaigns) under `Monitor` BEFORE spawning. Each stdout line = one notification. Do NOT use `Bash(run_in_background)` — it only fires on process completion, not per line; a watcher never exits, so the parent gets zero events. Do NOT use the bare `greprag inbox watch` without the `while true` wrapper — if the inner watcher dies you go silently deaf with no restart.
+<!-- greprag-conventions:end v3 -->
+```
+
+**If `V2_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v2 -->` … `<!-- greprag-conventions:end v2 -->` block (inclusive of markers) with the v3 block above. Tell the user "Upgrading greprag-conventions v2 → v3 (collapses Mode B mission-commander into Mode A behavior; renames Mode C to Mode B = discussion chip)." Don't preserve any v2 content — v3 supersedes.
+
+**If `V1_UPGRADE`**, replace the entire `<!-- greprag-conventions:start v1 -->` … `<!-- greprag-conventions:end v1 -->` block (inclusive of markers) with the v3 block above. Tell the user "Upgrading greprag-conventions v1 → v3 (adds Block 3 reply-listening; reframes modes as ship chip + discussion chip)." Don't preserve any v1 content — v3 supersedes.
+
+**If `DOC_MISSING`**, copy the canonical content from the template shipped with this skill:
+```bash
+mkdir -p ~/.claude/docs && cp ~/.claude/skills/greprag/templates/agent-coordination.md ~/.claude/docs/agent-coordination.md
+```
+
+If `DOC_OK` but you just upgraded from v1 or v2, overwrite the doc too (the v3 template carries the new mode framing + operating guidelines + detection signals):
+```bash
+cp ~/.claude/skills/greprag/templates/agent-coordination.md ~/.claude/docs/agent-coordination.md
+```
+
+The deep doc covers Block 0.5 (project-facts pull), Block 1 (worktree-first), Block 2 (inbox report-back), Block 3 (reply-listening), parent-side watcher, Mode A operating guidelines + sub-Agent dispatch (3-layer chain when needed), Mode B detection signals + operating guidelines, and anti-patterns.
+
+Re-run the grep to confirm install. Markers must stay verbatim — they're how subsequent `/greprag` runs detect "already installed" and skip this step.
+
+## Step 3c — Permission allowlist (only if `MON_MISSING` from Step 1)
+
+Without `Monitor` in the allowlist, every inbox-watcher firing prompts the user to approve. That breaks the reply-listening convention — chip and parent sessions both arm watchers as background tasks, and a permission dialog mid-task drops the agent out of flow.
+
+Read `~/.claude/settings.json` and confirm `permissions.allow` contains `"Monitor"`. If not, add it. Recommended baseline for greprag users:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Monitor",
+      "Read", "Edit", "Write", "Grep", "Glob",
+      "WebFetch", "WebSearch", "Skill", "Agent", "Task"
+    ]
+  }
+}
+```
+
+`Bash(*)` already covers `greprag inbox`, `greprag send`, `greprag retract`, `greprag watch` etc. — no per-command allow entries needed once Bash is broadly trusted. `Monitor` is the missing piece, because it's its own tool (not Bash) and prompts independently.
+
+If the user has a tighter Bash policy (no `Bash(*)`), the per-command minimum for greprag is:
+- `Bash(greprag *)` — covers send, inbox, retract, watch, status, discover
+- `Bash(greprag-hook *)` — covers the hook commands installed in Step 3
+- `Monitor` — inbox watchers
+
+Tell the user the change you're proposing before editing settings.json. Don't silently broaden their permission posture.
+
+## Step 3d — Channel plugins (if user has Discord / Telegram / iMessage plugins enabled)
+
+Adjacent gotcha worth surfacing during setup. Check whether any channel plugin is enabled in either global or any project `settings.json`:
+
+```bash
+grep -lE '"(discord|telegram|imessage|fakechat)@claude-plugins-official":\s*true' \
+  ~/.claude/settings.json \
+  $(find . -maxdepth 3 -path '*/.claude/settings.json' 2>/dev/null) 2>/dev/null
+```
+
+If any match: tell the user that channel push delivery requires the `--channels` flag at session launch — being in `settings.json` and `.mcp.json` is not enough. Specifically:
+
+- **Setting enables the MCP server to load** → its tools (e.g. `reply`, `fetch_messages`) become available.
+- **`--channels plugin:<name>@<marketplace>` at launch enables push** → inbound `notifications/claude/channel` events surface as `<channel>` blocks in the session context.
+
+Without `--channels`, the bot can be DM'd and the bun server receives the event, but Claude Code's harness filters it out. Users observe "typing indicator fires, then bot times out without replying."
+
+The flag is hidden from `claude --help` on 2.1.149 (research preview) but accepted on 2.1.80+. **FleetView / Claude Desktop's CCD launcher does not pass `--channels`** — push delivery only works from terminal-launched sessions. Recommend the user launch one terminal-rooted Claude session in the project where the plugin is enabled:
+
+```bash
+cd <project-with-plugin>
+claude --channels plugin:discord@claude-plugins-official
+```
+
+FleetView sessions can still call the plugin's REST tools as a polling workaround, but the realtime path is terminal-only until the launcher catches up.
+
+Also recommend: scope the plugin to a single project's `.claude/settings.json`, not global. Discord allows exactly one gateway connection per bot token; if multiple sessions all have the plugin enabled, the bun servers race for the token and Discord drops all but one.
+
 ## Step 4 — Project anchor (only if `project.anchor_found === false`)
 
 The current folder has no `.claude/project.json`. Ask the user:
@@ -157,10 +293,17 @@ To send a plain message:
 greprag send "<markdown body>" --to <address>
 ```
 
+`send` prints two lines on success — the delivered-to confirmation **and a retract code**:
+```
+Sent to alice@greprag.com/abc12345  (a7f3c5e2)
+Retract: greprag retract K9M2X4P7QV
+```
+The retract code lets the sender pull the message back without layering follow-up "SUPERSEDES" notes on top. See Step 5d.
+
 To send a **rich message** with back-pointers — preferred whenever the message refers to a memory row, a shipped artifact, or specific code lines:
 ```bash
 greprag send "Quick heads up — the auth bug I described yesterday repros here." \
-  --to alice@example.com/paybot \
+  --to alice@greprag.com/abc12345 \
   --memory 04f3e0d4-aa12-44ef-9a01-bb3df2c7e911 \
   --file src/auth/handler.ts:42 \
   --file src/middleware/check.ts:10-15 \
@@ -173,8 +316,9 @@ Flags (all repeatable, all optional):
 - `--artifact <type:id>` — point to a shipped thing. Types: `commit`, `pr`, `deploy`, `release`, `push`, `merge`
 - `--file <path[:lines]>` — point to a code location. Lines are `42` or `10-15`
 - `--ref-json '<json>'` — escape hatch for a fully-formed references object (mutually exclusive with the above)
-- `--session <id>` — target a specific session under the project. Only the session's `inbox watch --session <id>` sees it; broadcasts (no `--session`) still reach every session-scoped watcher. Equivalent to suffixing the address with `/<id>`.
-- `--from-session <id>` — sender's own session UUID. Denormalized onto the message so the recipient learns your session and can address replies back via `--session <your-id>` without re-discovery. Use whenever you expect a reply.
+- `--from-session <id>` — sender's own session UUID. Denormalized onto the message so the recipient learns your session and can address replies back without re-discovery. Use whenever you expect a reply.
+
+The target lives in the `--to` address itself (see "Address formats" below). The legacy `--session` and `--project` flags were removed in v0.11 — passing them now errors out with a migration hint.
 
 **When to populate references vs. when to leave them off:**
 - Short chat messages ("pinging you", "deploy is up", "ack") — no references, just body.
@@ -182,20 +326,103 @@ Flags (all repeatable, all optional):
 - Cross-referencing prior memory — pull memory IDs from a `greprag inbox` listing or from the recap and pass via `--memory`. The recipient agent can fetch the row directly.
 - Don't hallucinate references. If you can't name a real file path or artifact ID, leave the flag off.
 
-Address formats (all valid):
-- `1834729@greprag.com` — canonical numeric handle. Every account has one; opaque, leaks nothing. Get yours from `greprag status --json | jq -r .identity.handle` or `greprag whoami`.
-- `1834729@greprag.com/paybot` — recipient's paybot project inbox.
-- `1834729@greprag.com/paybot/<session-id>` — only the named session sees it (plus broadcasts). Trailing UUID is case-sensitive.
+Address formats (v0.11+):
+
+| Form | Use | Behavior |
+|---|---|---|
+| `<handle>@greprag.com` | What you SHARE | Identity-only / receive form. Errors on send — the bare handle has no target. |
+| `<handle>@greprag.com/<session-uuid>` | What you SEND with (normal) | Targets one specific session. UUID or 8-hex short form. Only that session's watcher receives. |
+| `<handle>@greprag.com/<project-name>` | What you SEND with (rare) | Project-wide broadcast — every watcher in that project receives. Reserve for genuine "everyone in this project should know" messages. |
+| `me` / `self` | Shortcut for your own tenant | Receive form only. |
+
+Disambiguation rule: a single segment after `/` is a session if it matches `[0-9a-f]{8}` (8-hex short form) or full UUID, otherwise a project name. Project names that look like UUIDs are rejected at registration time so this is always unambiguous.
+
+`<handle>` is one of:
+- `1834729@greprag.com` — canonical numeric handle. Opaque, leaks nothing. Get yours from `greprag status --json | jq -r .identity.handle` or `greprag whoami`.
 - `alice@greprag.com` — opt-in vanity alias (claim with `greprag identity claim alice`).
-- `me` / `self` — shortcut for your own tenant inbox (server resolves).
 
 **Real emails are NEVER routing addresses.** `users.email` is auth credential only. If you don't know the recipient's numeric handle, ask the user — don't guess from their email. adr: adr/numeric-handles.md
 
-Project-level addressing is the fallback whenever no specific session is in mind. Session-level is for precise routing — chip ↔ parent reply isolation, or any case where multiple sessions on the same project would otherwise share an inbox.
+Session targeting is the default and expected form. Project broadcasts are intentional opt-ins for the rare case where everyone in a project should hear something. adr: adr/address-grammar.md
 
 Auto-read semantics: any message returned by `greprag inbox` (without `--all`) is marked read in the same call. Once read, it stops appearing in notifications. TTL deletes read messages after 14 days. Use `keep` to extend before expiry.
 
-## Step 5c — Health & repair (when memory looks wrong)
+## Step 5c — Watching the inbox (push delivery)
+
+When you've spawned chips that will report back via `greprag send`, or you're waiting on any message that needs to land in real time, run a live SSE watcher instead of polling `greprag inbox` on a heartbeat:
+
+```bash
+greprag inbox watch                       # tenant-wide stream
+greprag inbox watch --project <name>      # only messages addressed to this project
+greprag inbox watch --session <id>        # only messages targeting this session (plus broadcasts)
+greprag inbox watch --since <id-or-iso>   # resume from a known cursor
+greprag inbox watch --json                # emit one JSON object per line (preferred under Monitor)
+```
+
+`--project` and `--session` compose — pass both when a session lives inside a specific project's inbox space. `--session` is the strictest filter: only messages with matching `to_session_id` (or `to_session_id IS NULL` for broadcasts) get through. This is what eliminates cross-session noise when several Claude sessions watch the same project's inbox at once.
+
+Each message arrives within ~500ms of the sender's `greprag send` (210ms verified end-to-end). The connection is held open and auto-reconnects with exponential backoff if the server drops; the watcher tracks the last seen message id and uses it as `since=` on reconnect, so nothing is dropped and nothing is duplicated.
+
+**Liveness model (post v0.8.5):** the server emits an SSE `: ping` comment every 15s. The client tracks time since the last byte and treats 60s of total silence (4 missed pings) as a dead stream — aborts the fetch, reconnects with the preserved cursor, and the server's per-tenant InboxDO replays any rows that landed in the gap from its tail buffer (or backfills from the DB for older gaps). After replay, the server emits an `event: replay-complete` SSE event with the row count so the watcher logs `replayed N missed row(s), resuming live tail` to stderr. Disconnects and reconnect attempts also log to stderr with the cursor — debugging silent gaps no longer requires inspecting the running process. Pre-`fix`, a silently half-open TCP socket would hang the watcher indefinitely with no log; that failure mode is gone, but watcher delivery is still opportunistic — the `UserPromptSubmit` hook remains the correctness guarantee, surfacing any unread messages at the next user turn.
+
+**Two canonical patterns:**
+
+### Parent-side: watch for chip reports BEFORE spawning
+
+```bash
+# Parent arms a Monitor scoped to its own session, then spawns the chip
+# (chip prompt's Block 2 sends with --session <parent-session-id>).
+# Each chip's "done" report becomes one Monitor notification, with no cross-talk
+# from other chips or sessions sharing the parent's project inbox.
+# The while-loop wrapper auto-restarts the SSE process if it dies — a bare
+# `greprag inbox watch` would silently end the Monitor task on any inner crash.
+while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+If the parent has no session identity (rare — older sessions before session-scope shipped), fall back to `--project <parent-project>`. The chip then sends without `--session` and the message reaches every watcher under the project.
+
+### Post-send: listen for replies after `greprag send`
+
+Any session that sends a message that could draw a directive in response arms the same watcher on its own inbox in the same turn. Without this, the Stop hook is the only path for the reply to surface — and Stop only fires between user prompts. Mid-task replies are invisible until the next stop boundary.
+
+```bash
+# After: greprag send "..." --to <someone>/<their-project>/<their-session> \
+#                          --from-session <own-session-id>
+# Arm under Monitor (persistent: true):
+while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+The `--from-session` flag on the outgoing message tells the recipient where to address replies; the `--session` filter on the watcher narrows incoming traffic to messages aimed at this exact session (plus general broadcasts). No more sibling-chip cross-talk and no self-echo from tenant-wide sends.
+
+This is also the Block 3 pattern for chips — see `~/.claude/docs/agent-coordination.md`. The same rule applies to main sessions, advisor sessions, and any other context that pings someone and expects a response.
+
+**Run it under the `Monitor` agent tool, `persistent: true`.** Monitor emits one notification per stdout line — the agent reacts the moment a message lands. **Do NOT use `Bash(run_in_background: true)`** — Bash background notifies only on process completion, and a watcher runs forever, so the agent gets zero events until it manually reads the output file. Confirmed bug, learned the hard way. Stop with `TaskStop` on the Monitor task when the watch is truly no longer needed.
+
+The watcher is the right default whenever you'd otherwise loop `greprag inbox` every N seconds — lower latency, cheaper, doesn't burn quota on empty polls.
+
+## Step 5d — Retracting a message you just sent
+
+`send` returns a retract code (printed after `Retract:` on the second line of the success output). Use it when you realize a message was wrong-framed and want to pull it back instead of stacking a follow-up "SUPERSEDES" note on top:
+
+```bash
+greprag retract <code>
+```
+
+Behavior is decided by the server based on whether the recipient has already read the message:
+
+- **Unread** → the row is hard-deleted. Recipient never sees it. Output: `Retracted (status: deleted — recipient had not read it).`
+- **Read** → message body is replaced with `[RETRACTED BY SENDER at <ts>]`. Recipient still sees the row in `inbox --all`, but the original body is gone. Output: `Marked retracted (status: retracted_after_read — recipient had already read; they'll see the retraction notice in place of the original body).`
+- **Already retracted** → no-op, idempotent. Output: `Already retracted (status: already_retracted — no change).`
+- **Unknown code** → no error, just confirms nothing happened. Output: `Not found (status: not_found — code does not match any message you sent, or the message has already expired).`
+
+**When to retract vs. when to send a SUPERSEDES follow-up:**
+- Just sent it, recipient hasn't read yet, and the framing was wrong? → `greprag retract`. Clean inbox state, zero noise.
+- Recipient has already read it? → `greprag retract` still beats a stacked follow-up — they get a placeholder instead of a confusing stale message — and then send a fresh `greprag send "<corrected message>"` with the right framing.
+- Recipient acted on the message already (committed code, made a decision)? → send a follow-up `SUPERSEDES <old-id>: <correction>` so they have full context on what changed and why. Retract still works alongside this to clean the original.
+
+Retract codes are sender-scoped — your code cannot retract a message someone else sent. Codes stay valid until the message expires (14 days unread, longer if `keep`'d).
+
+## Step 5e — Health & repair (when memory looks wrong)
 
 Triggers: user says "memory looks empty", "I'm missing my history", "fix greprag here", "are there orphans", "consolidate my project IDs"; or `greprag status` reports identity drift; or the session-start recap printed a "[GrepRAG memory: identity drift detected ...]" line.
 
@@ -218,7 +445,7 @@ Flags:
 
 Repair is fully tenant-scoped via the API — `greprag doctor` only ever touches rows under the caller's tenant, and the merge runs in a transaction so a partial failure rolls back cleanly.
 
-## Step 5d — Corpus (upload + search arbitrary text)
+## Step 5f — Corpus (upload + search arbitrary text)
 
 Episodic memory captures the agent's own work. **Corpus** is the other direction: upload a book, a codebase, a reference doc, a writing-sample library — any text — and search it with lexical grep enriched by write-side vocabulary bridging. Same substrate, same retrieval modes; just a different `kind` on the store.
 

package/skill/templates/agent-coordination.md

@@ -0,0 +1,253 @@
+# Agent Coordination
+
+How sessions delegate work — chips, agents, and the multi-tier orchestrator pattern. Companion to `/greprag` (inbox transport) and `~/.claude/CLAUDE.md` (the lean reference).
+
+## Two tools, two purposes
+
+| Tool | What it spawns | Lands in | Parameters | When to use |
+|---|---|---|---|---|
+| `mcp__ccd_session__spawn_task` | Full Claude Code session ("chip") | Any cwd via `cwd:` param | title, prompt, tldr, cwd | Cross-project work; long-running coordination; user-visible chip UI |
+| `Agent` tool | Subagent instance | Current session's cwd | subagent_type, model, isolation, prompt, run_in_background | One-shot work inside this project; needs specific model/agent type |
+
+Picking between them:
+
+- **Cross-project? → `spawn_task`** (only it has `cwd`).
+- **In this project, one-shot, specific model? → `Agent`** with `isolation: "worktree"`.
+- **In this project, long campaign? → either** — chip if you want a persistent UI surface; Agent if it's a single delegation.
+
+## Chip convention (every `spawn_task` call)
+
+A chip prompt = **Block 0.5 (project facts, optional)** + **Block 1 (worktree-first)** + the actual task + **Block 2 (report back via inbox)** + **Block 3 (stay listening for follow-up)**. Non-negotiable: 1/2/3. Without them the chip pollutes the main checkout (no isolation), the parent has no return channel, or the chip dies after one report and can't be redirected on follow-up. Block 0.5 is recommended but skip when the project has no seeded facts yet.
+
+### Block 0.5 — Project facts (prepend; pull pattern)
+
+Before composing the chip prompt, the spawning agent pulls the target project's `chip-startup` facts and inlines them at the top of the prompt:
+
+```bash
+greprag fact query --scope chip-startup --project <chip-project> --limit 10 --format markdown
+```
+
+If the output is non-empty, wrap it in a `**Project Facts (do not re-discover)**` block at the very top of the prompt:
+
+```
+**Project Facts (do not re-discover):**
+
+1. <fact 1 verbatim>
+2. <fact 2 verbatim>
+...
+
+---
+```
+
+If the output is empty, skip the block entirely — don't inject placeholder text.
+
+**Why this exists.** Chips routinely burn 10–20 startup turns rediscovering project layout (where migrations live, which file owns the CLI dispatch, what the inbox storage shape is). Seeding those answers once and pulling them at spawn makes every future chip skip the search. Contribution side of the protocol — when to seed, scope naming, deliberate review — is in the `/greprag` skill § "Seeding learnings" (`~/.claude/skills/greprag/SKILL.md` or the package copy at `packages/cli/skill/SKILL.md`).
+
+### Block 1 — Worktree-first (prepend to prompt)
+
+```
+**Setup — do this FIRST, before anything else:**
+
+```bash
+cd <chip-cwd>
+git worktree add .claude/worktrees/<slug> -b chip/<slug>
+cd .claude/worktrees/<slug>
+```
+
+All edits, tests, and commits happen in the worktree. The main checkout stays untouched. Pick a slug that matches the chip's title (kebab-case, short — e.g. `discover-cli`, `doctor-merge-fix`).
+
+**Your parent's session id is `<parent-session-id>`** — record it; you'll need it in Block 2 to address the report-back so only the parent sees it, not every sibling chip watching the same project inbox.
+```
+
+Fill `<parent-session-id>` from your own (parent) session UUID when composing the spawn_task prompt. If you don't know your session UUID, fall back to project-level addressing throughout Block 2/3 — the chip then sends to `--to <handle>@greprag.com/<parent-project>` (project broadcast, intentional) and the parent watches `--project <parent-project>` (no `--session`). Less precise, still correct — both sides have to be project-scoped for the loop to close.
+
+Path convention: `<project>/.claude/worktrees/<slug>/` — same parent directory Claude Code Desktop uses for IDE-checkbox worktrees. One place to look for any active Claude worktree. Branch prefix `chip/` distinguishes agent-spawned from IDE-spawned (`claude/<auto-name>`), so `git branch` output shows provenance at a glance. `/clean-worktrees` skill cleans both.
+
+`spawn_task` does NOT auto-create worktrees — only the `Agent` tool does (via `isolation: "worktree"`). Chips run wherever you point them, so the worktree setup must be explicit in the prompt itself.
+
+**Chip cleanup discipline (HARD RULE — every chip prompt must enforce this).** Chips **commit and exit**. They do NOT run `git clean -fd`, `git reset --hard`, `git worktree remove` (any target), `git checkout <other-branch>`, raw `rm -rf` of directories, or any destructive shell command outside their own worktree's tracked files. If a chip needs to delete a file it created, use `git rm` and commit the deletion — never raw `rm`. The parent session owns post-merge worktree cleanup; chips never reach for it themselves. This rule exists because parallel worktrees share `.git`, a poorly-scoped cleanup command can wipe another worktree's working tree, and the main checkout has been observed to lose `packages/*/src/` files in this exact pattern. Spawning agents: include "Chip cleanup discipline" verbatim in Block 1 of every chip prompt.
+
+**`npm link` discipline.** If a chip needs to smoke-test a CLI build globally, run `npm link` from the main checkout's package dir (`cd <main>/packages/<pkg> && npm link`), NOT from the worktree. Linking from the worktree registers a global symlink that points INTO the worktree; after `git worktree remove` runs in /commit's Phase 4, the symlink dangles and the CLI breaks system-wide until reinstalled. The /commit skill's `guard-npm-links.sh` auto-recovers (re-points at main or unlinks), but the cleanest path is to never create the worktree-pointed symlink in the first place.
+
+### Block 2 — Report back via greprag inbox (append to prompt)
+
+```
+**When done (or stuck), report back via greprag inbox:**
+
+```bash
+greprag send "<status>: <commit hash> on chip/<slug> — <one-line>" \
+  --to <your-tenant-handle>@greprag.com/<parent-session-id> \
+  --from-session <own-session-id> \
+  --artifact commit:<hash> \
+  --file <key-file-path>
+```
+
+- `<status>`: `done` | `blocked` | `partial`
+- `<your-tenant-handle>`: parent's `@greprag.com` handle (e.g. `1834729` or a claimed alias like `travis`).
+- `<parent-session-id>`: filled in by the spawning session in Block 1 of this prompt. The full UUID or 8-hex short form both work. This trailing segment IS the target — only the parent's session-scoped watcher receives the message.
+- `<own-session-id>`: this chip's own session UUID. Denormalized onto the message so the parent can address replies back without re-discovering the chip's identity.
+- Body ≤280 chars where possible. If blocked, name the blocker explicitly.
+- Use `--artifact` and `--file` flags to back-reference the actual work (see `/greprag` skill).
+
+If `<parent-session-id>` is unknown (parent didn't pass one), send to the parent's project instead: `--to <handle>@greprag.com/<parent-project>` (no session suffix). That's an intentional project broadcast — every watcher in `<parent-project>` receives it, including the parent. Use sparingly; session-targeting is the default. adr: adr/address-grammar.md
+
+Send the report BEFORE exiting. The parent agent reads `greprag inbox` on its next turn and picks it up — no polling, no manual chasing.
+```
+
+### Block 3 — Stay listening for follow-up (append to prompt, runs after Block 2)
+
+```
+**After sending the done report, stay reachable for follow-ups:**
+
+Arm a `Monitor` on your own inbox so any directive from main lands as an in-session event. Use the bash-wrapper form — the `while` loop auto-restarts the watcher if the inner SSE process dies (network blip, crash, fork failure). Run this under the **`Monitor`** tool with `persistent: true`:
+
+```bash
+while true; do greprag inbox watch --session <own-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+- `<own-session-id>` is the chip's own session UUID — same one passed as `--from-session` in Block 2. The filter narrows the stream to messages aimed at this exact session plus broadcasts; sibling chips watching the same project no longer pollute this feed.
+- If you don't have a session id (older sessions), substitute `--project <own-project>` instead of `--session <id>` — wider net but still correct.
+- The chip then idles between events — no token burn, no polling. Each new inbox line = one notification.
+- Restart events go to stderr as `[wrapper] watcher exited…` — visible in the Monitor output file but not as a Monitor notification.
+- When the work is truly done and no follow-up is expected, call `TaskStop` on the Monitor task. Otherwise leave it armed until the session closes.
+- Do NOT drop the `while … done` wrapper. A bare `greprag inbox watch …` will silently end the Monitor task on any inner crash, and any directive sent in the gap is lost until the next user prompt.
+```
+
+**Why not the Stop hook?** The greprag Stop hook ingests inbox messages between user prompts. A Mode B chip running autonomously may never hit a stop boundary; a Mode A chip waiting on a reply mid-task gets the reply only on the next manual interaction. Monitor delivers the reply as an in-session event the moment it lands — no hook lag, no missed directive.
+
+## Reply listening (any session, not just chips)
+
+The chip Block 3 pattern generalizes. Any session that sends a message expecting a directive in response should arm a Monitor on its own inbox in the same turn — before the send if you can, so a fast reply doesn't slip past. Use the same bash-wrapper form shown in Block 3 (substitute `--project <own-project>` when no session identity is available), `persistent: true`. Same reasoning: the Stop hook is best-effort for session-end ingestion; Monitor is the only path that catches mid-task replies.
+
+**Session scoping is the default in v0.11.** The send-side address grammar — `<handle>@greprag.com/<session-uuid>` — makes the session the only segment, so messages land in exactly one inbox. Project-name addresses (`<handle>@greprag.com/<project>`) are intentional broadcasts, used only when the sender genuinely means "everyone in this project should hear this." A `--session` watcher still passes broadcasts through (by design, so tenant-wide announcements aren't lost), but with session-targeting as the dominant pattern those broadcasts are now rare and recognizable.
+
+## Parent-side: watch for the report
+
+If you want the chip's report the instant it lands (not on next turn), start an SSE watcher in the background BEFORE spawning the chip:
+
+```bash
+# preferred — single chip (bash wrapper auto-restarts on inner death)
+while true; do greprag inbox watch --session <parent-session-id> --json; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+
+# fallback / multi-chip campaigns
+while true; do greprag inbox watch --project <parent-project>; echo "[wrapper] watcher exited, restarting in 1s" >&2; sleep 1; done
+```
+
+`--session` is the right default when the chip's Block 2 sends with `--session <parent-session-id>` — exactly one report lands in this watcher per chip. Use `--project` when you've spawned several chips at once and want all their reports on one stream (each chip still tags `--from-session <own-id>`, so the parent reads provenance per message).
+
+**Run it under the `Monitor` agent tool.** Monitor emits one notification per stdout line — the parent agent reacts the moment a message lands. **Do NOT use `Bash(run_in_background: true)` for this** — Bash background only notifies on process completion, and a watcher runs forever, so the parent agent gets no events at all until it manually checks the output file. Burned this lesson once already.
+
+Sub-1s delivery (verified 210ms in live test), auto-reconnects with cursor-based resume, no polling. Default to this whenever you're waiting on one or more chips. Full pattern: `~/.claude/skills/greprag/SKILL.md` § 5c.
+
+## Parent-project name
+
+When spawning, include `<parent-project>` (your current project_name) in the report-back template so the chip knows where to send the report. Get it via `greprag status --json | jq -r '.project.project_name'` or `greprag project-id`.
+
+## Two chip modes
+
+Both modes use the same Block 0.5 / 1 / 2 / 3 wrapper — the difference is what the chip does inside.
+
+### Mode A — Ship chip (default)
+
+The chip lands in its worktree, does the work, commits checkpoints as progress, reports back via inbox, stays listening for follow-ups. Whether you watch the chip UI mid-flight or it runs end-to-end and inboxes a `done` is a function of how tight the spec is, not a separate mode. A chip that dispatches its own `Agent` sub-tasks mid-work (the "mission commander" pattern) is still Mode A — the Agent dispatch is a behavior the chip's prompt unlocks, not a peer mode.
+
+**Use when:** the work is "build X" or "fix Y" or "refactor Z" and the spec is clear enough to ship from. This is the workhorse — reach for it by default.
+
+**Operating guidelines:**
+
+1. **All edits, tests, builds, commits happen in the worktree.** Never reach into the parent checkout.
+2. **Checkpoint commits.** Each logical unit of work gets its own commit (matches the global "checkpoint after every fix/feature" rule). Don't batch a whole feature into one final commit.
+3. **Verify before reporting done.** Build passes, tests pass, hand-verify the change does what the spec asked. `done` means demonstrably working, not "I wrote code."
+4. **Never push.** Parent owns the push boundary.
+5. **No destructive commands.** `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <foreign-branch>`, raw `rm -rf` — all forbidden. Use `git rm` for tracked deletions only.
+6. **Mid-flight ambiguity → surface it, don't guess.** Either the user types into the chip UI to redirect, OR the chip `greprag send`s a question to main and Monitors its own inbox for the reply.
+7. **Done-report carries proof.** Pass commit hashes via `--artifact commit:<hash>` and key file paths via `--file <path>`. Not just prose.
+
+**Sub-Agent dispatch (still Mode A).** When a discrete sub-task fits a specialized agent (`Explore` for read-only search, `Plan` for design work, `general-purpose` for execution, `code-reviewer` for second opinion), the chip can call `Agent` directly. Pass `model: "haiku" | "sonnet" | "opus"` to scale cost to task. The chip evaluates the Agent's return value and either continues, dispatches another Agent, or inboxes back to main.
+
+This gives you a three-layer chain when sub-tasks span model tiers or operator chatter would pollute main's context:
+
+```
+Main session (Opus)         ← strategic orchestrator
+    ↓ spawn_task(cwd: <target-project>, prompt: "...")
+Mode A chip (Opus)          ← tactical commander in target project
+    ↓ Agent(subagent_type, model, isolation: "worktree")
+Subagent (any model/type)   ← field operator
+    ↑ Agent returns to chip
+Chip evaluates, may spawn more Agents, may inbox up
+    ↑ greprag send → <your-tenant-email>/<main-project>
+Main session reads inbox, gives next directive via greprag send
+    ↓ <your-tenant-email>/<chip-project>
+Chip continues
+```
+
+**What each layer owns:**
+
+- **Main** — strategy. Decides what gets delegated. Stays Opus; never burns context on routine sub-tasks.
+- **Chip** — tactical coordination inside a target project. Persists across multiple Agent rounds. Receives directives from main via inbox, dispatches operators, evaluates results, asks for clarification if needed. Picks model per sub-task.
+- **Agent / subagent** — execution. Specific subagent_type and model fit to the task. Returns once when done.
+
+**Communication channels:**
+
+- Main ↔ chip: greprag inbox (`<handle>@greprag.com/<parent-session-id>` ↔ `<handle>@greprag.com/<chip-session-id>`, falling back to `/<project>` only when a session id is unknown).
+- Chip ↔ subagent: direct return value from the `Agent` tool (no inbox needed — same session).
+
+Skip the layering when one Agent call would do — direct dispatch from main is simpler.
+
+### Mode B — Discussion chip
+
+The chip lands NOT to ship code, but to be a context-rich conversation partner for design / architecture / debugging questions the orchestrator can't reason about well from grep snippets. The chip reads code as needed, proposes, receives push-back, iterates. Ships nothing without explicit go-ahead — often ships nothing at all and just produces a decision or a scoped follow-up chip prompt.
+
+**Detection signals — switch to Mode B when ANY of these fire:**
+
+1. **You catch yourself extrapolating from partial reads.** "Based on these grep hits I think X" — the moment "I think" or "based on snippets" enters your reasoning about architecture, that's the signal. A chip with the repo loaded ground-truths this. Single biggest signal.
+2. **The user's question is "how should this be shaped?" not "build X."** Design / architecture / "is this the right approach?" / "why is this code like this?" — Mode B. Implementation tasks — Mode A.
+3. **The user wants to think out loud.** "Bounce something off you" / "thoughts?" / "talk me through this." They want a conversation, not a deliverable.
+4. **The work will touch multiple subsystems and second-order effects are unknown.** Mode B chip explores the coupling, surfaces what main missed; then either main implements (light coupling) or a follow-up Mode A chip gets a tightened spec (heavy coupling).
+
+**Operating guidelines:**
+
+- Read code; don't commit.
+- The worktree is scratch space for proposed edits, not a place to ship from.
+- Propose in the chip UI; receive pushback; iterate.
+- Output is a decision: shipped (after explicit go-ahead → transitions into a Mode A finish), parked, or a scoped follow-up Mode A chip prompt.
+- Report-back captures the outcome, not a deliverable.
+
+**Chip prompts for Mode B look different from Mode A:**
+
+- Frame the open question, not a deliverable.
+- List the sub-questions the user has raised — give the chip the discussion thread, not a spec.
+- Explicitly say "This is a discussion chip, not a task chip. Read code. Propose. Don't ship without go-ahead."
+- Open with a "where do you want to start?" rather than a task list.
+
+**Why this beats arguing in main:** orchestrator runs on what it can grep + read in-context. Anything beyond that is plausible-sounding extrapolation. A chip with the repo loaded catches "this coupling exists" / "this billing dependency is non-obvious" / "you missed a callsite" — corrections the orchestrator can't surface itself.
+
+### Picking the slug, model, and subagent_type
+
+- **Slug** — kebab-case, short, matches the chip's title. Becomes the worktree branch name (`chip/<slug>`) and the worktree directory (`<project>/.claude/worktrees/<slug>/`).
+- **Model at the chip layer** — defaults to whatever the FleetView/CCD runtime assigns (currently Opus). `spawn_task` has no model param.
+- **Model at the subagent layer** — pass `model: "sonnet"`/`"haiku"`/`"opus"` to the `Agent` tool. Default to the cheapest that fits the task.
+- **subagent_type** — `Explore` for read-only search, `Plan` for design work, `general-purpose` for execution, `code-reviewer` (if installed) for second opinion. Full list in the `Agent` tool description.
+
+### Anti-patterns
+
+- **Chip running cleanup commands** — `git clean`, `git reset --hard`, `git worktree remove`, `git checkout` of foreign branches, raw `rm -rf`. Parallel worktrees share `.git`; a chip cleaning "itself" can hit main's working tree. Chips commit and exit; parent owns cleanup.
+- **Chip without Block 1** — pollutes parent checkout. Always include the worktree-setup block.
+- **Chip without Block 2** — parent has no way to know it landed. Always include the report-back block.
+- **Chip without Block 3** — chip dies after one report; parent can't redirect. Always include the reply-listening block.
+- **Sending an expected-reply message without arming Monitor** — Stop hook fires only between user prompts, so a mid-task reply is invisible. Arm `Monitor` on own inbox in the same turn as the `greprag send`.
+- **Spawn_task when Agent would do** — extra session, extra context, slower turnaround. Only reach for spawn_task when you need cross-project or persistence.
+- **Agent when spawn_task would do** — Agent can't change cwd, so cross-project delegation must go through spawn_task.
+- **Polling `greprag inbox` in a loop** — use `greprag inbox watch` under Monitor instead. SSE push, sub-1s latency, free.
+
+## Future blocks (planned, not yet defined)
+
+- **Block 0 — Pre-spawn checklist.** Auto-fill parent-project name, generate slug from title, dry-run the worktree path for collisions. Reduces the boilerplate the spawning agent has to compose by hand.
+
+**Shipped:** session-scoped routing via the single-segment address grammar `<handle>@greprag.com/<target>` where `<target>` is a session UUID (normal) or a project name (intentional broadcast). v0.11 dropped the legacy `--session`/`--project` send flags and the 3-segment `email/project/session` address — the address itself now carries the target, so missing-target sends error loudly instead of silently broadcasting. adr: adr/address-grammar.md
+
+## See also
+
+- `~/.claude/skills/greprag/SKILL.md` — inbox transport, watcher, retract, discover
+- `~/.claude/CLAUDE.md` § Chip Spawning — the lean reference (5 lines) pointing here
+- `~/.claude/CLAUDE.md` § Worktree env — sourcing `.env` from main repo when running in a worktree