@jeffober/thatch 0.1.13 → 0.1.14

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,15 @@ 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.
 
-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.
 

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.14",
   "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,
 ];