@jeffober/thatch 0.1.13 → 0.1.15

package/README.md

@@ -32,6 +32,17 @@ No API keys, no cloud services; everything runs on your machine.
 On next start, OpenCode npm-installs thatch (putting the `thatch` CLI on your
 PATH as a side effect) and its tools are available immediately.
 
+Set this environment variable so the extraction nudge can run the fact-extractor
+as a **background** sub-agent instead of blocking your turn:
+
+```bash
+export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
+```
+
+Without it, opencode hides the task tool's `background` parameter and every
+extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
+`[env]`, or `.envrc`.
+
 **Self-hosting** (local development):
 
 ```jsonc

package/artifacts/skills/thatch-code-review.md

@@ -10,13 +10,21 @@ This entire review is a static analysis exercise. Do NOT run tests, linters, com
 
 ## Step 1: Resolve the review target
 
+First, run `git fetch origin` (NOT `git pull` — fetch updates remote-tracking refs without touching the working tree or current branch). This refreshes `origin/main` and other remote-tracking refs to their true remote state. Local branches (e.g. `main`) only advance on checkout/pull and may be stale on a long-lived feature checkout, so resolve the base against the remote tracking ref, not the local branch.
+
 Identify what to review:
-- If a branch was specified, identify the base branch (usually main or master), compute the merge-base, and review the range merge-base..HEAD.
-- If a PR number was specified, use gh pr view to resolve the head and base, fetch both refs, and review merge-base..head.
+- If a branch was specified, identify the base branch (usually main or master), compute the merge-base against the remote tracking ref (e.g. `git merge-base HEAD origin/main`), and review the range merge-base..HEAD.
+- If a PR number was specified, use `gh pr view` to resolve the head and base, fetch both refs, and review merge-base..head.
 - If a git range was specified (A..B form), use it directly.
-- If no target was specified, review the current branch against its base.
+- If no target was specified, review the current branch against its base, resolving the base from `origin/main` (or the appropriate remote tracking ref) after fetching.
+
+Also detect whether the current branch has a **connected PR/MR** even when none was specified — this is what enables follow-up-round detection in Step 2. Inspect `git remote -v` to recognize the VCS host (github.com → GitHub/`gh`; gitlab.* → GitLab/`glab`; bitbucket.org → Bitbucket Cloud; dev.azure.com → Azure DevOps). Then probe for an open PR/MR on the current branch using the matching CLI or REST API:
+- GitHub: `gh pr view --head <branch> --json number,headRefOid,baseRefOid`
+- GitLab: `glab mr list --source-branch <branch>`
+- Other providers: equivalent detection via their CLI or REST API.
+- If you cannot detect or cannot interact with the VCS (no CLI, no REST access), treat the change as a **local-branch review** and proceed with the existing procedure. A local-branch review is not a defect — it just means there is no prior-comments register to build.
 
-Fetch any refs not locally reachable so branches and PRs that were never checked out can be reviewed.
+Also fetch any refs not locally reachable so branches and PRs that were never checked out can be reviewed (e.g. `git fetch origin <branch>` for a PR head).
 
 Run git diff --stat on the resolved range and git log --oneline to understand the change.
 
@@ -30,8 +38,9 @@ Load the thatch-review-context skill and follow its methodology to build a conte
 - thatch_memory_recall for feature/project status, design decisions, ticket dependencies
 - Project docs, READMEs, design docs
 - Issue tracker (gh issue/view) if ticket IDs are found
+- **Prior review comments** — if Step 1 detected a connected PR/MR, fetch ALL prior review comments on it (see source #8 in the review-context skill) and build the prior-comments register with a preliminary addressed-check status per comment. This is what distinguishes a **follow-up round** (register non-empty) from the **first round** (register empty or PR has no prior reviews). If Step 1 found no connected PR/MR, the brief explicitly states `Local-branch review — no prior-comment fetch`.
 
-Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints).
+Produce the context brief in the format the skill prescribes (project context, this change's scope, deferred work, dependencies, relevant constraints, and the prior review comments section when present).
 
 If context is sparse (no PR description, no ticket references, no relevant memories), note that the change appears standalone. Even a sparse brief is valuable: it tells specialists you looked and found nothing, so they do not need to repeat the search.
 
@@ -99,13 +108,16 @@ After all sub-agents complete, load the thatch-review-synthesizer skill to verif
 
 Confirmed LOW findings are mandatory in the final report, including mechanical findings (pedantic, no-slop, breadcrumbs, docs, naming, style, comments). Do not omit them for being non-functional.
 
+**Follow-up round cross-reference** — if Step 2 built a prior-comments register, the synthesizer must cross-reference every confirmed and rejected finding against it (see the synthesizer skill's "Cross-reference against prior review comments" section). The final report includes a `### Previously identified findings` appendix listing each prior comment with its final status (`addressed`, `still active — reproduced by finding X`, `still active — not reproduced this round, re-verified above`, or `unclear`), the original author, date, and original location. New findings that match an addressed prior comment are still reported in the main findings (with attribution) and warrant a closer look — the prior round's resolution may be incomplete or the issue may have regressed.
+
 Alternatively, perform the synthesis yourself:
 1. Read each finding's cited location to verify evidence accuracy.
 2. Deduplicate findings flagged by multiple specialists.
 3. Group findings by root cause where multiple findings stem from the same issue.
 4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE. For behavioral findings, apply citation verification, reachability, and intent verification. For mechanical findings, verify the cited text exists, is branch-introduced or newly made relevant, and violates the stated guideline or specialist taxonomy.
-5. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
-6. Produce a final report grouped by severity, with coverage gaps noted. Include every confirmed LOW finding.
+5. Cross-reference against the prior-comments register if one was built in Step 2: tag matching findings `Provenance: previously identified by @author, PR #N, DATE` and produce the `### Previously identified findings` appendix per the synthesizer skill.
+6. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
+7. Produce a final report grouped by severity, with coverage gaps noted. Include every confirmed LOW finding.
 
 ## Specialist briefing template
 
@@ -116,6 +128,7 @@ When dispatching each sub-agent, include in the prompt:
 - The diff stat for this unit's files
 - **The project context brief** from Step 2, filtered to what is relevant to this unit's scope. Explicitly list any deferred work that falls within this unit's files, and call out TODO ($ticket) markers the specialists should recognize as intentional.
 - **The workflow guide** from Step 3, filtered to the workflows relevant to this unit's scope. Use it to understand the purpose and evolution of the code before flagging issues. It provides the code-level context (flows, contracts, history, constraints) that prevents false positives about intentional behavior and long-standing design decisions.
+- **The prior review comments register** from Step 2 when present — the list of issues other reviewers already raised, with each comment's current-HEAD location and preliminary status. This is a **hint list, not a finding list**: it saves specialists the work of treating an already-identified issue as newly discovered. Specialists still produce their own findings normally. For any finding that matches a prior comment, set `Provenance` to `previously identified by @author, PR #N, DATE` in addition to the branch-introduced / pre-existing classification — the synthesizer does the final cross-reference and dedup.
 - Any design context or specific concerns
 - Explicit scope boundaries ("your scope is X; do NOT review Y")
 - Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance

package/artifacts/skills/thatch-review-context.md

@@ -56,6 +56,62 @@ If ticket IDs were found:
 - Look for milestone assignments, dependencies, and blocking relationships
 - Check for epic or parent issues that describe the overall feature
 
+### 8. Prior review comments (follow-up round detection)
+
+If the change under review has a connected PR/MR on the upstream remote, fetch all prior review comments so this review does not duplicate already-identified issues. Any prior review activity on the PR/MR means **this is a follow-up round**, not the first review. If no PR/MR is connected, this is a **local-branch review** — skip this source entirely; the existing review procedure applies.
+
+#### Detect the VCS provider
+
+`git remote -v` lists remotes and URLs. Parse the upstream URL:
+- `github.com` → GitHub (`gh`)
+- `gitlab.*` → GitLab (`glab`)
+- `bitbucket.org` → Bitbucket Cloud
+- `dev.azure.com` → Azure DevOps
+- Unknown host or no upstream → local-branch review, skip this source.
+
+If the matching CLI tool (`gh`, `glab`, etc.) is not on PATH and you cannot call the provider's REST API via available HTTP tools, skip this source — the missing integration is not a finding.
+
+#### Detect the connected PR/MR
+
+Use the current branch name (without remote or merge-base prefix) to look up an open PR/MR:
+- **GitHub**: `gh pr view --head <branch> --json number,title,state,headRefName,baseRefName,headRefOid,baseRefOid`. Fallback: `gh api repos/{owner}/{repo}/pulls --jq ".[] | select(.head.ref==\"<branch>\")"`.
+- **GitLab**: `glab mr list --source-branch <branch>`.
+- **Bitbucket Cloud**: REST `https://api.bitbucket.org/2.0/repositories/<owner>/<slug>/pullrequests?q=source.branch.name="<branch>"` (no widely-adopted CLI; call via available HTTP tool).
+- **Azure DevOps**: `az repos pr list --source-branch <branch> --org <org-url> -r <project>`.
+
+If a PR/MR is found and has zero prior review comments/reviews by other users, treat this as the first round on this PR/MR — skip the addressed-check, but still record the PR/MR identity in the brief for reference.
+
+#### Fetch ALL prior review comments
+
+Pull review threads and summaries regardless of resolved state — the goal is to see everything that has been raised, not just unresolved threads.
+- **GitHub**: `gh api repos/{owner}/{repo}/pulls/{N}/reviews` (review summaries: body, user, state, submitted_at) AND `gh api repos/{owner}/{repo}/pulls/{N}/comments` (inline file:line comments with `path`, `line`, `original_line`, `commit_id`, `body`, `user`).
+- **GitLab**: `glab api projects/:id/merge_requests/:iid/discussions` returns discussion threads with anchored positions; threads expose `resolved` and `resolved_by` (use as a supplementary addressed signal).
+- **Bitbucket Cloud**: REST `activities` endpoint for the PR.
+- **Azure DevOps**: REST `threads` endpoint for the PR.
+
+#### Build the prior-comments register
+
+For each prior comment, record:
+- Author, submitted date
+- Original commit SHA, file, line range (or `summary` for non-inline review)
+- Comment body (quoted)
+- The semantic claim raised (what the reviewer said was wrong — paraphrase the core issue, one sentence)
+- VCS resolve state if available (GitLab `resolved`/`resolved_by`; GitHub `isResolved` via GraphQL if accessible)
+
+#### Addressed-check methodology
+
+For each comment, attempt to determine whether it has been addressed in the **current HEAD** under review:
+1. **Locate the original code location.** If the file was deleted, mark `unclear`. If the file was renamed, follow it with `git log --diff-filter=R -- <path>`.
+2. **Anchor to current HEAD.** Read the cited line plus 3-5 lines of context at the original commit (`git show <comment-SHA>:<file>`). Find the equivalent region in the current HEAD file by matching the surrounding text (search for unique tokens from that region). Determine the new line range.
+3. **Judge the issue.** Read the code at the new location. Does the issue the comment described still exist, or has it been fixed, refactored away, or otherwise made moot by changes in this change's commit range?
+4. **Tag preliminary status:**
+   - `addressed` — the code at the equivalent location no longer exhibits the issue, or the referenced structure was refactored away in a way that resolves the comment.
+   - `still active` — the issue persists at the equivalent location.
+   - `unclear` — file gone, line unlocatable, or the substantive change makes comparison impossible.
+5. **VCS resolve signal as a supplement, not a substitute.** If the VCS exposes a resolved flag (GitLab `resolved: true`, GitHub `isResolved` via GraphQL), record it as supporting evidence. When the resolved flag disagrees with the code-state verdict, trust the code state — a thread can be marked resolved in the UI while the bug persists, and an unresolved thread may already have been fixed by a later commit. Note both signals in the register so the synthesizer can weigh them.
+
+The register produced here is a **preliminary** classification. The synthesizer produces the final cross-reference, including any prelim-status overrides when new findings from the specialist round reproduce or refute a prior comment.
+
 ## Context brief format
 
 Produce a structured brief:
@@ -83,6 +139,19 @@ List each deferred piece:
 - Design decisions or architectural constraints from memories or docs
 - Conventions that reviewers should be aware of
 
+### Prior review comments (only when the change has a connected PR/MR with prior reviews)
+
+List the prior-comments register (one entry per prior comment):
+- Author and submitted date
+- Original location (`file:line @ commit-SHA`, or `summary review`) and current HEAD location (`file:line`) if locatable
+- The semantic claim raised (one-sentence paraphrase)
+- Preliminary status: `addressed` / `still active` / `unclear` — with the code-state evidence (a short quote from the current HEAD that supports the verdict)
+- VCS resolve flag if applicable (and any disagreement with the code-state verdict)
+
+If context gathering found a connected PR/MR but no prior reviews by other users, state `First round on PR #N — no prior comments to register`.
+
+If context gathering found no connected PR/MR (local-branch review), state `Local-branch review — no prior-comment fetch`. This is not a gap; the existing review procedure applies.
+
 ## If context is sparse
 
 Not every PR will have rich context. If you find minimal context:

package/artifacts/skills/thatch-review-synthesizer.md

@@ -54,6 +54,26 @@ The same issue may be flagged by multiple specialists when it spans category bou
 
 Multiple findings may stem from the same underlying issue (e.g., a contract mismatch causes errors in 3 call sites). Group these under the root cause.
 
+## Cross-reference against prior review comments
+
+If your input includes a **prior-comments register** (built by the coordinator via `thatch-review-context` source #8 — prior review comments retrieved from the PR/MR's review history), cross-reference every confirmed and rejected finding against it so the final report does not present already-identified issues as fresh discoveries.
+
+For each new finding:
+1. **Search for a matching prior comment** by location and semantic claim. Match if both hold:
+   - The finding's cited file:line falls within (or has moved to) the prior comment's referenced location in current HEAD, AND
+   - The finding's core claim restates the prior comment's semantic claim (the same code-level issue, even if worded differently or covering a slightly wider scope).
+2. **If a match is found**, tag the finding's `Provenance` field as `previously identified by @author, PR #N, DATE` in addition to its branch-introduced / pre-existing classification. Do not drop the finding. Keep it in the main findings (with attribution) so the user sees what still needs attention this round.
+
+For each entry in the prior-comments register, finalize its status using both the register's preliminary verdict and this round's findings:
+- **`addressed`** — the register's preliminary status was `addressed` AND no new finding reproduces the comment. Re-read the cited current-HEAD location to confirm the issue is gone; if you find the issue persists, override to `still active — not reproduced this round, re-verified above`.
+- **`still active — reproduced by finding X`** — a new finding this round matches the prior comment. Cite the finding's severity and source specialist.
+- **`still active — not reproduced this round, re-verified above`** — no new finding matches, but you re-read the code and the issue described in the prior comment still persists. Include a one-line quote from current HEAD as evidence.
+- **`unclear`** — the original line is unlocatable in current HEAD, the file is gone, or substantive change makes the comparison impossible. State which.
+
+New findings that match a prior comment tagged `addressed` (preliminary) are still reported — they may indicate the resolution was incomplete or that the issue regressed. Note this in the finding's `Provenance` field so the user investigates.
+
+When the VCS resolve flag (GitLab `resolved`, GitHub `isResolved`) disagrees with the code-state verdict (e.g., thread marked resolved in the UI but the bug persists), trust the code state and call out the disagreement in the appendix entry.
+
 ## Severity calibration
 
 Assign final severity based on YOUR verification:
@@ -82,7 +102,7 @@ For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each fin
 4. **Finding**: what the problem is
 5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
 6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified
-7. **Provenance**: branch-introduced or pre-existing
+7. **Provenance**: branch-introduced or pre-existing. If the finding matches a prior review comment, append `; previously identified by @author, PR #N, DATE` to this field. For findings matching an `addressed` prior comment, also add a one-line note on why the finding persists so the user can investigate whether the prior resolution is incomplete or the issue has regressed.
 
 ### Rejected findings (appendix, brief)
 Findings you rejected and a one-line reason why. Include the specialist and location for each.
@@ -90,5 +110,19 @@ Findings you rejected and a one-line reason why. Include the specialist and loca
 ### Pre-existing bugs (appendix, brief)
 Findings you verified as real but pre-existing, with a one-line note on the issue and its potential impact.
 
+### Previously identified findings (appendix — only when a prior-comments register was provided)
+List every entry from the prior-comments register here. For each entry, produce a one-block record:
+1. **Author and date** of the original comment
+2. **Original location** (`file:line @ commit-SHA`, or `summary review`) and **current HEAD location** (`file:line`) if locatable
+3. **Claim**: one-sentence paraphrase of what the prior reviewer raised
+4. **Final status**: one of
+   - `addressed` — issue confirmed gone in current HEAD
+   - `still active — reproduced by finding X` — with the cross-referenced finding's severity and source specialist
+   - `still active — not reproduced this round, re-verified above` — with a one-line quote from current HEAD as evidence
+   - `unclear` — with the reason (file gone, line unlocatable, etc.)
+5. **VCS resolve flag** if applicable, and any disagreement with the code-state verdict (e.g., thread marked resolved in the UI but the bug persists) — trust the code state and surface the disagreement.
+
+If no prior-comments register was provided (local-branch review or first round on the PR/MR), state `None — no prior review comments to cross-reference` and move on.
+
 ### Coverage gaps
 Note which files or areas were NOT covered by any specialist.

package/docs/dev/skills.md

@@ -36,8 +36,8 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth-wall breaks, em dashes, filler. |
 | `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of behavior? |
 | `thatch-review-mark-and-sweep` | Mechanical change completeness: whole-repo sweep for stragglers after renames, flag removals, API substitutions. |
-| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. |
-| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. |
+| `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Cross-references findings against prior review comments when a follow-up round register is provided; produces a Previously identified appendix. |
+| `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
 | `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 
@@ -45,7 +45,7 @@ description: Extract durable project facts ... Use when ...
 
 | Skill | Role |
 |-------|------|
-| `thatch-code-review` | Resolve review target, gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize. |
+| `thatch-code-review` | Resolve review target (incl. VCS detection and connected PR/MR lookup for follow-up round detection), gather project context, research affected workflows, estimate complexity, partition, dispatch the 6 specialists in parallel, synthesize (incl. cross-referencing findings against prior review comments). |
 
 ## REVIEW_COMMON
 

package/docs/user/README.md

@@ -20,6 +20,17 @@ Publish to npm and add thatch to your opencode config:
 
 OpenCode installs the plugin and its dependencies automatically on next start.
 
+Set this environment variable so the extraction nudge can dispatch the
+fact-extractor as a **background** sub-agent instead of blocking your turn:
+
+```bash
+export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
+```
+
+Without it, opencode hides the task tool's `background` parameter and the
+extraction nudge runs synchronously. Put it in your shell rc, `mise.toml`
+`[env]`, or `.envrc`.
+
 For local development before publishing, use a file path:
 
 ```jsonc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin), Claude Code (as an MCP server), and Cursor (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/extract-queue.ts

@@ -56,7 +56,7 @@ export function appendBatch(sessionID: string, toolCalls: BatchToolCall[]): void
   const additions: ToolInteraction[] = [];
   for (const tc of toolCalls) {
     const lower = tc.tool_name.toLowerCase();
-    if (lower === "mcp__thatch__memory_remember") {
+    if (lower === "mcp__thatch__memory_remember" || lower === "mcp__thatch__extraction_done") {
       resetMissedCount(sessionID);
       consumeQueue(sessionID);
       existing.length = 0;

package/src/index.ts

@@ -56,6 +56,14 @@ export const server: Plugin = async ({ client, worktree }) => {
   // all-caps shouting. Reset to 0 whenever the agent writes a memory.
   const missedNudges = new Map<string, number>();
 
+  // Parent-child session mapping for cross-session buffer drain. opencode
+  // creates real child sessions with their own IDs for sub-agents; without
+  // this map, a memory_remember call in a child (e.g. a background
+  // fact-extractor task) drains the child's empty buffer but leaves the
+  // parent's buffer untouched, causing the nudge to replay indefinitely.
+  // Populated from session.created events that carry a parentID.
+  const childToParent = new Map<string, string>();
+
   // Skills always install to the global opencode config — installing into the
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
@@ -103,8 +111,34 @@ export const server: Plugin = async ({ client, worktree }) => {
     //    The buffer is NOT drained on nudge delivery — it persists until the
     //    agent writes a memory, so ignored nudges accumulate and the payload
     //    grows with each missed cycle.
+    //
+    //    Fix A: a memory_remember call in a child session (sub-agent) also
+    //    drains the parent's buffer. Without this, dispatching the
+    //    fact-extractor as a background task writes memories in the child
+    //    but never clears the parent's queue — the nudge replays every turn.
+    //
+    //    Fix C: thatch_extraction_done is an explicit acknowledgment tool the
+    //    model calls in the parent session after dispatching. Belt-and-
+    //    suspenders for fix A: covers the case where the sub-agent errors out
+    //    or the host doesn't expose parent-child session relationships.
     "tool.execute.after": async (input, output) => {
       if (input.tool === "thatch_memory_remember") {
+        extraction.consume(input.sessionID);
+        missedNudges.delete(input.sessionID);
+        // Fix A: if this is a child session, also drain the parent so the
+        // parent's extraction nudge stops replaying after a sub-agent writes
+        // memories on its behalf.
+        const parentID = childToParent.get(input.sessionID);
+        if (parentID) {
+          extraction.consume(parentID);
+          missedNudges.delete(parentID);
+        }
+        return;
+      }
+      // Fix C: explicit acknowledgment tool drains the buffer without
+      // requiring a memory write. The model calls this after dispatching
+      // the fact-extractor to a sub-agent.
+      if (input.tool === "thatch_extraction_done") {
         extraction.consume(input.sessionID);
         missedNudges.delete(input.sessionID);
         return;
@@ -183,7 +217,22 @@ export const server: Plugin = async ({ client, worktree }) => {
 
     // 5. Session-start reminder, carrying the hygiene heartbeat. Hygiene is
     // best-effort: a failure there must not cost the reminder itself.
+    //
+    // Also tracks parent-child session relationships for fix A (cross-session
+    // buffer drain). session.created with a parentID records the mapping;
+    // session.deleted cleans it up to avoid unbounded growth.
     event: async ({ event }) => {
+      if (event.type === "session.created") {
+        const info = event.properties.info;
+        if (info.parentID) {
+          childToParent.set(info.id, info.parentID);
+        }
+      }
+      if (event.type === "session.deleted") {
+        childToParent.delete(event.properties.info.id);
+        return;
+      }
+
       if (event.type !== "session.created") return;
       const id = event.properties.info.id;
 

package/src/prompts.ts

@@ -136,7 +136,7 @@ Tools are prefixed in Claude Code: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_recall\`, \`mcp__thatch__memory_list\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
-\`mcp__thatch__dedup_mark_checked\`.
+\`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`.
 Bare names used below for readability.
 
 ## Stores
@@ -268,21 +268,38 @@ export function extractionNudge(
   payload: string,
 ): string {
   const plural = count === 1 ? "" : "s";
+  // opencode's task tool has a `background` parameter (requires
+  // OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true) that launches the sub-agent
+  // asynchronously — the call returns immediately and the session is notified
+  // on completion. Naming the parameter gives the model a direct hit on the tool
+  // schema it sees. MCP hosts (Claude Code, Cursor) keep generic sub-agent
+  // wording because their background mechanisms differ and are not exposed as a
+  // per-call parameter in the same way.
+  const isOpencode = toolName.startsWith("thatch_");
+  const dispatch = isOpencode
+    ? "Dispatch a task with background: true"
+    : "Spawn a background sub-agent";
+  const drainTool = isOpencode ? "thatch_extraction_done" : "mcp__thatch__extraction_done";
+  const acknowledge = `After dispatching, call ${drainTool} to acknowledge.`;
+
   if (missedCount >= 3) {
     return `[thatch] YOU ARE IGNORING EXTRACTION INSTRUCTIONS. ` +
       `${count} TOOL INTERACTION${plural.toUpperCase()} ARE QUEUED AND YOU HAVE NOT PROCESSED ANY OF THEM. ` +
       `THE USER INSTALLED THIS PLUGIN FOR A REASON. ` +
-      `SPAWN A SUB-AGENT NOW TO RUN THE thatch-fact-extractor SKILL ` +
-      `AND USE ${toolName.toUpperCase()} TO SAVE DURABLE FACTS FROM THIS PAYLOAD:\n${payload}`;
+      `${dispatch.toUpperCase()} NOW TO RUN THE thatch-fact-extractor SKILL. ` +
+      `${acknowledge.toUpperCase()} ` +
+      `USE ${toolName.toUpperCase()} TO SAVE DURABLE FACTS FROM THIS PAYLOAD:\n${payload}`;
   }
   if (missedCount >= 2) {
     return `[thatch] YOU HAVE NOT PROCESSED YOUR PREVIOUS EXTRACTION PAYLOAD${plural.toUpperCase()}. ` +
       `${count} more tool interaction${plural} are now queued. ` +
-      `Spawn a background sub-agent to run the thatch-fact-extractor skill on this payload. ` +
+      `${dispatch} to run the thatch-fact-extractor skill on this payload. ` +
+      `${acknowledge} ` +
       `Use ${toolName} to save durable facts from this payload:\n${payload}`;
   }
-  return `[thatch] Spawn a background sub-agent to run the thatch-fact-extractor skill ` +
+  return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
+    `${acknowledge} ` +
     `Then answer the user. ` +
     `Use ${toolName} to save durable facts from this payload:\n${payload}`;
 }
@@ -312,7 +329,7 @@ Tools are prefixed in Cursor: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_recall\`, \`mcp__thatch__memory_list\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
-\`mcp__thatch__dedup_mark_checked\`.
+\`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`.
 Bare names used below for readability.
 
 ## Stores

package/src/tool-defs.ts

@@ -340,6 +340,33 @@ const markCheckedDef: ToolDef = {
   },
 };
 
+/**
+ * Acknowledge that the extraction nudge has been handled. Drains the
+ * extraction buffer so the nudge does not replay on the next turn.
+ *
+ * The actual draining happens in the host's post-tool hook
+ * (tool.execute.after for opencode, PostToolBatch/appendBatch for MCP) —
+ * this tool's execute function is a no-op confirmation. The tool exists so
+ * the model can call it in the parent session after dispatching the
+ * fact-extractor to a sub-agent, giving the hook a recognizable tool name
+ * to key on. Without it, the buffer only drains when a memory_remember
+ * call lands in the same session (or a tracked child session), which fails
+ * if the sub-agent errors out or the host doesn't expose parent-child
+ * session relationships.
+ */
+const extractionDoneDef: ToolDef = {
+  name: "extraction_done",
+  description:
+    "Acknowledge that the extraction nudge has been dispatched to a sub-agent. " +
+    "Drains the extraction buffer so the nudge does not replay. " +
+    "Call this in the parent session after dispatching a background task " +
+    "to run the thatch-fact-extractor skill.",
+  args: {},
+  async execute() {
+    return "[acknowledged] extraction buffer drained";
+  },
+};
+
 /**
  * All tool definitions, in the order they should be presented to the agent.
  * The opencode plugin wraps each in `tool()`; the MCP server exposes them
@@ -354,4 +381,5 @@ export const TOOL_DEFS: ToolDef[] = [
   listStoresDef,
   findDuplicatesDef,
   markCheckedDef,
+  extractionDoneDef,
 ];