@jeffober/thatch 0.1.48 → 0.2.0

package/docs/dev/features/opencode-plugin.md

@@ -0,0 +1,133 @@
+# Feature: OpenCode plugin dual-adapter (v1 + v2)
+
+The opencode plugin supports both opencode lines from one npm package: the
+1.18.x plugin API and the 2.x plugin API. The user's setup (shim file, config
+key, DB, skills) is identical under either host.
+
+## Architecture
+
+```text
+src/index.ts          dual entry -- merged default export { id, setup, server }
+  │                     opencode v1 reads default.server; v2 reads
+  │                     default.setup and strips excess keys. Both loaders
+  │                     verified against tagged upstream source.
+  ├── (lazy) → src/opencode/v1.ts   v1 adapter (@opencode-ai/plugin)
+  └── (lazy) → src/opencode/v2.ts   v2 adapter (@opencode/plugin)
+                     both delegate to:
+                src/runtime.ts      shared runtime (nudges, system prompt,
+                                    session events, extraction, bookkeeping)
+                     ↑ consumes
+                src/capabilities.ts HostCapabilities seam
+```
+
+### The isolation rule
+
+`src/index.ts`'s static import graph must stay SDK-free. Each adapter
+imports its host's SDK (`@opencode-ai/plugin` vs `@opencode/plugin`), and the
+SDKs resolve only under their own host's install, so the entry reaches both
+adapters exclusively through dynamic `import()`. A top-level await would make
+either host's load block on (or fail from) the other host's adapter. The pure
+helpers (`osProcessArgs`, `startupSessionId`, ...) live in `src/os-args.ts`,
+which is safe to re-export statically.
+
+### The export shape
+
+Upstream loaders decide everything:
+
+- **v1** (`packages/opencode/src/plugin/shared.ts`, `readV1Plugin`, identical
+  across 1.18.0-1.18.32): reads only `mod.default`; uses `default.server` if
+  present and never reaches the named-export ("legacy") fallback. Excess keys
+  (like `setup`) are invisible to it. A default export with `id` but no
+  `server` throws and the host SILENTLY SKIPS the plugin (error-publish is
+  commented out in the upstream caller).
+- **v2** (`packages/core/src/plugin/module.ts` @ v2.0.9): decodes `default`
+  as `{ id, effect }` or `{ id, setup }` with Effect Schema; excess keys
+  (like `server`) are tolerated and stripped (verified empirically at
+  effect@4.0.0-rc.112, the version v2 pins).
+
+So the merged object `{ id, setup, server }` satisfies both. A module with a
+named `server` export plus a v2-shaped default does NOT work on v1 -- that
+shape throws in `readV1Plugin`.
+
+## The capability seam
+
+`HostCapabilities` (src/capabilities.ts) is the interface of host operations
+the shared runtime needs. It is the lifecycle-level sibling of `CoreContext`
+(src/tool-defs.ts, the per-tool-call seam); they stay separate on purpose.
+
+| Capability | v1 source | v2 source | v2 strategy |
+|---|---|---|---|
+| bus events | `event` hook | `event.subscribe` (raw SSE) | client-side location filter; location-less events resolve via `session.get` (`{sessionID}` input) and drop unresolvable (mirrors v1's server-side filter); events for plugin-created extraction children pass by ID (they live in the project directory, which differs from the instance directory on below-root launches) |
+| incoming message | `chat.message` hook | `session.hook("prompt")` | the hook awaits the runtime; nudge injections append to the OUTBOUND request's last user message in the generate hook (v2 wire `Message` carries parts in `content`, not `parts`) |
+| system prompt | `experimental.chat.system.transform` | `session.hook("context")` | mutates the request's system array; the runtime's plain strings convert to `{type: "text", text}` SystemPart objects at the boundary |
+| compaction | `experimental.session.compacting` + `.autocontinue` + `session.compacted` | `session.hook("compaction")` | flag lands; context-injection surface unverified |
+| wrap-up commands | `command.execute.before` + command files | `command.transform` + `CommandEditor.add` | registered in code: `execute` arms the greenlight check (`onCommandExecuteBefore`) and delivers the same prompt body the v1 file carries, substituting the invocation's prompt text for `$ARGUMENTS` (v2's `session.prompt` does no template expansion); the runtime installs only ACTION command files on v2 and REMOVES stale wrap-up files from earlier v1 runs (a file and a registered command with the same name would collide) |
+| tools | `hooks.tool` map via `tool()` | `tool.transform` + `ToolEditor.add` | zod shapes pre-converted to JSON Schema with our own zod (v2's `instanceof $ZodType` detection fails for ours and drops the schema); results wrap as `{ content }` |
+| tool buffering | `tool.execute.after` hook | `tool.hook("execute.after")` | wired: feeds the same extraction buffer; `Tool.Result.content` is flattened (string passes through, content-part arrays contribute their text parts); the title is derived from the tool name and args (`deriveTitle`), since v2's `Tool.Result.output` is a typed output value, not a title |
+| noReply deliveries | `promptAsync` with `noReply` | none | gated off via `HostCapabilities.noReplyDelivery` -- chat echoes and the session-start reminder are skipped on v2 (delivering them would start real model turns: a feedback loop) |
+| synthetic wake deliveries | `promptAsync` with `synthetic` parts | `session.synthetic` endpoint | watcher + chat wake nudges route to v2's synthetic endpoint (TUI-hidden), matching v1 |
+| child sessions | `client.session.create/promptAsync/prompt/delete` | `session.create/prompt` | create+prompt supported (a missing id throws into the extraction fallback); delete degrades (extraction children are not cleaned up on v2 -- the session picker accumulates one `thatch-extraction` entry per extraction, and `-c` "continue last session" logic that picks the newest top-level session will land in an extraction child after any session that triggered extraction) |
+| session status | `client.session.status` | none | returns `{}`; the wake gate treats unknown as idle and the event-fed status map does the gating |
+| session messages | `client.session.messages` | `session.context` | mapped into the v1 `{info: {role}, parts}` shape, so the wrap-up greenlight check works (the promise domain has no `message` accessor) |
+| session list | `client.session.list` | none | degrade (`-c` resume listing loses its data source) |
+| compaction trigger | `client.tui.executeCommand("session_compact")` | none | degrade (no `session.compact` on the promise domain's Pick, and the built-in `/compact` is a TUI palette action calling the server endpoint directly - the server command registry only knows config/plugin-registered names; the wrap-up checklist and flush still run, the automatic compaction is skipped) |
+| toasts | `client.tui.showToast` | none reachable | degrade (the `tui.toast.show` event has no producer surface from the promise context; a `tui` companion plugin entrypoint is the known lift candidate) |
+| TUI app exit | `client.tui.publish` | none | degrade (the wrap-up exit's checklist and flush run; the exit does not - upstream [anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984). On v2 the right target closes THIS session's tab (tab-scoped), not `app.exit`: the daemon hosts every tab; the `tui` companion entrypoint's `ui.tabs.close` is the known lift candidate) |
+| tab close | n/a | no session.deleted on v2 tab close | known gap: a closed tab's watchers keep polling until their TTL (deliveries fail their idle gate and stay pending); restart dormancy covers the daemon-restart case, not tab close |
+| wake gate after reload | `session.status` event map | map rehydrates empty | known gap: v2's fetchStatuses stub is structural (the promise context has no session.status), so in the reload window - until the session's next status event - the proactive-prompt gate is fully open |
+| dispose | `dispose` hook | cleanup returned from `setup` | must be idempotent: v2 auto-reloads plugins on file change, and a non-idempotent cleanup doubles pollers/pumps/nudges. Volatile runtime state (extraction buffer + accepted entries, child bookkeeping, wrap-up arms, watcher definitions) is journaled to the `runtime_state` table - instance-scoped by the writing location's directory - and rehydrated on the next `setup()`: rows from the same process AND directory (a reload) all restore; rows from a dead process are pruned unless the session is the `-c`/`-s` startup resume, which inherits recovery-safe state only (buffer requeued, no live child bookkeeping - the child died with the old process). Exception: a dead process's watcher definitions are kept as DORMANT rows (no polling, no delivery) instead of pruned - resuming the session re-arms them on its first message (a `chat.message` scan: own rows re-arm, same-directory rows of still-dead sessions earn the live session a one-line death notice gated on the owning pid being dead, rows past the watcher TTL plus a 24h grace age out). Restored sessions on v1 get a synthetic noReply re-attach notice (v2 has no turn-free delivery and skips it). The chat poller re-hosts the instance's journaled hosted set on reload, so pending chat mail wakes sessions the reload left asleep and heartbeats keep the reaper from reaping live registrations. The embedding model is refcounted per db path, so N location instances share one resident model |
+
+## Live verification and remaining unknowns
+
+The v2 adapter was written against tagged source (v2.0.9) before a live
+binary was available, then verified against a real v2.0.15 binary on
+2026-09-23: merged-default loading, tool schemas (via pre-converted JSON
+Schema - see the gotcha), event shapes, the execution-lifecycle idle signal,
+synthetic wake delivery, and command registration all work; the full QA
+suite runs green against a v2 serve.
+
+Still unverified against the live binary (static analysis only):
+
+- Whether `session.hook("prompt")` fires for `session.synthetic` inbox
+  items. If it does not, `pendingInjections` from the prior real turn gets
+  appended to the synthetic turn's outbound request.
+- Whether `SessionGenerate.messages` are fresh objects per model call within
+  a turn. If not, the generate hook pushes duplicate nudges on every tool
+  round trip.
+- An npm-installed copy (not the dev checkout, which has devDependencies
+  present) loading under v2 - the isolation rule's real-world proof.
+
+The app-exit gap (no server-side publish surface for `tui.command.execute`)
+is upstream:
+[anomalyco/opencode#50984](https://github.com/anomalyco/opencode/issues/50984).
+Install opencode-v2 (brew formula `anomalyco/tap/opencode-v2`; conflicts
+with the v1 formula's binary name, so it cannot coexist) and re-run the QA
+live suite against it.
+
+## User setup compatibility
+
+No config file moves or changes format. The DB, model cache, version-check
+files, and skills dirs are host-agnostic and shared. opencode's own config
+key (`plugin` vs `plugins`) is auto-migrated by v2. The only user-owned file
+with a content change is the dev-session shim, and its new dual-shape content
+loads under both hosts.
+
+## Source files
+
+- `src/index.ts` -- dual entry, merged default export, lazy wrappers
+- `src/opencode/v1.ts` -- v1 hooks adapter
+- `src/opencode/v2.ts` -- v2 promise-context adapter + capability impl
+- `src/capabilities.ts` -- `HostCapabilities`, `capabilitiesFromClient`
+- `src/runtime.ts` -- the shared runtime (all behavioral logic)
+- `src/os-args.ts` -- pure argv helpers
+- `tests/opencode-v2.test.ts` -- v2 adapter contract tests (mocked context)
+- `tests/plugin.test.ts` -- v1 adapter contract tests (mocked client)
+
+## Interactions with other features
+
+Everything downstream of the hooks is unchanged by the dual adapter:
+[extraction.md](extraction.md), [nudge-pipeline.md](nudge-pipeline.md),
+[session-lifecycle.md](session-lifecycle.md),
+[cross-session-chat.md](cross-session-chat.md),
+[watchers.md](watchers.md), [notifications.md](notifications.md). The MCP
+path ([mcp-parity.md](../mcp-parity.md)) does not touch any of this.

package/docs/dev/features/qa-system.md

@@ -96,6 +96,49 @@ opencode session timeout, compaction trigger). Run them locally with
 | `qa-auto` | `bin/qa-run auto` | Run automatable only (fast, no LLM). Pass UC names as args to select a subset. |
 | `qa-live` | `bin/qa-run live` | Run live only (spawns opencode, costs tokens). Pass UC names as args to select a subset. |
 
+### The opencode version matrix (default behavior)
+
+Every task that runs opencode-driven use cases runs one leg per
+DISCOVERED opencode install, with test names suffixed
+(`UC-001-memory-roundtrip [v1]`, `UC-001-memory-roundtrip [v2]`) when
+there are several. There is no separate matrix command - the ordinary
+tasks just do the matrix based on what is available.
+
+Discovery (tests/qa/binaries.ts) asks the package manager where its
+formulas are installed (`brew --prefix opencode`, `brew --prefix
+opencode-v2`), falls back to the PATH-resolved binary, validates each
+candidate by running `--version`, tags it by major (`v1`, `v2` - the
+version output decides, not the formula name), and dedups candidates
+that resolve to the same binary. A machine with one install runs
+single-leg with unsuffixed names, so single-binary setups behave
+exactly as they did before the matrix existed.
+
+A use case opts into or restricts the matrix with `hosts: ["v1"]` /
+`["v2"]` / `["v1", "v2"]` on the `UseCase`:
+
+- Live use cases (no custom `run`) are matrixed by default - the default
+  `runViaOpencode` path spawns opencode by definition.
+- Automatable use cases keep a single leg unless they declare `hosts` -
+  the fast suite is not doubled for cases that never touch opencode.
+  Declare `hosts` when a custom `run` spawns opencode itself (UC-098) or
+  drives a serve (UC-100).
+
+`QA_HOSTS=v1` (comma-separated) narrows the legs when iterating against
+one major; a value matching no discovered install registers nothing
+with an explanatory line.
+
+Legs get separate fixtures (the fixture directory is keyed by test name
+suffix) because hosts cannot share one: a v2 session db in a shared
+fixture fails the v1 leg's serve with "Database is not empty and has no
+session table".
+
+The v1 and v2 `run` CLIs disagree on flags (v1 has `--dir`, which v2
+dropped; v2 needs `--standalone` to skip the background daemon, which a
+fixture sandbox must not boot). `opencodeRunArgs(ctx, prompt)` in the
+runner builds the right invocation per leg by version-detecting the
+binary the leg's PATH selects; `runViaOpencode` and UC-098's custom runs
+go through it.
+
 The `qa` task runs auto first via `&&`. Auto failures stop before live runs.
 The `qa-live` task does not use `--concurrent` — live sessions are
 resource-heavy and benefit from sequential execution.

package/docs/dev/features/repo-identity.md

@@ -104,7 +104,7 @@ are per-worktree -- so git reads are equivalent from either. Consumers:
 
 - `src/git.ts` -- resolution chain, cache validation, spawn-cwd fallback
 - `src/db.ts` -- `repo_paths` table, accessors, `repoPathCache` adapter
-- `src/index.ts` -- plugin init order (DB before detection), identity from
+- `src/runtime.ts` -- plugin init order (DB before detection), identity from
   the session directory, watcher runner wrapper
 - `src/mcp.ts` -- MCP server init order
 - `bin/thatch` -- CLI `defaultStore()` and hook-line identity resolution

package/docs/dev/features/session-lifecycle.md

@@ -1,5 +1,7 @@
 # Session Lifecycle Management (opencode)
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 opencode emits bus events for session lifecycle changes. Thatch subscribes to these events to manage the extraction pipeline, send session-start reminders, handle child session cleanup, and resolve wrap-up commands.
 
 ## What it does
@@ -15,7 +17,7 @@ opencode emits bus events for session lifecycle changes. Thatch subscribes to th
 
 ## How it works
 
-### Event handler (`src/index.ts`, event hook)
+### Event handler (`src/runtime.ts`, shared by both adapters)
 
 Subscribes to all session bus events. Dispatches based on `event.type`.
 
@@ -122,7 +124,8 @@ first-ever install is invisible until the next server start.
 
 ## Source files
 
-- `src/index.ts` -- event handler (all session events), `triggerExtraction`, `cleanupChild`, internal state maps
+- `src/runtime.ts` -- event handler (all session events), `triggerExtraction`, `cleanupChild`, internal state maps
+- `src/opencode/v1.ts`, `src/opencode/v2.ts` -- host adapters wiring the runtime into each opencode plugin API
 
 ## Key invariants
 

package/docs/dev/features/watchers.md

@@ -1,5 +1,7 @@
 # Watchers
 
+Unless noted, `client.*` names below are the opencode v1 mapping; the v2 equivalents and degrades are in [opencode-plugin.md](opencode-plugin.md).
+
 Watchers are the general mechanism for event-driven notifications from
 external sources: the model registers a watch on something outside the
 session, thatch polls it in the background, and the plugin prompts the
@@ -42,10 +44,15 @@ The registry lives in plugin memory, never in SQLite. Three reasons:
    in-memory; the file-backed queue exists only for the MCP path's
    separate short-lived hook processes.
 
-The cost: a restart loses watches. Accepted because the session that
-created them loses its conversational context too - a notification
-into a session that no longer knows why it is being watched is worse
-than a lost watch.
+The cost used to be "a restart loses watches", accepted because the
+session that created them loses its conversational context too - a
+notification into a session that no longer knows why it is being
+watched is worse than a lost watch. The dormant-recovery layer keeps
+the best of both: the definition survives the restart (journaled),
+nothing polls or delivers while its session is away, and resuming the
+session re-arms the watches into a session that again knows why it is
+being watched. See the `runtime_state` row in
+`docs/dev/features/opencode-plugin.md` for the journal mechanics.
 
 `session.deleted` also cancels the session's watchers and pending
 events, and `dispose` stops the poller. These are cheap insurance;
@@ -221,7 +228,7 @@ src/watchers.ts, test-enforced); command watchers register the single
 - `src/watchers.ts` - registry, poller, gh CLI runner, command runner,
   diff functions
 - `src/tool-defs.ts` - the watch tool definitions (see `TOOL_DEFS`)
-- `src/index.ts` - registry construction, delivery closure,
+- `src/runtime.ts` - registry construction, delivery closure,
   session.status tracking, session.deleted cleanup, dispose
 - `src/prompts.ts` - `watcherNotificationNudge()`, system prompt
   Watchers section

package/docs/dev/gotchas.md

@@ -70,7 +70,7 @@ here first. These are the things that have already cost time.
 - **`chat.message` has two priority tiers**: extraction nudge first (returns
   early), then the prompt-aware recall nudge. Don't run both in one turn.
 - **The extraction nudge peeks, never flushes.** The buffer is NOT drained
-  on nudge delivery (`index.ts:366` — `peek()` call). It persists until the
+  on nudge delivery (`extraction.peek()` in `triggerExtraction`, src/runtime.ts). It persists until the
   agent writes a memory or calls `thatch_extraction_done`. Ignored nudges
   accumulate; the `missedNudges` counter escalates the tone (polite at 0-1
   misses, insistent at 2, ALL-CAPS at 3+). The counter resets when the
@@ -80,8 +80,8 @@ here first. These are the things that have already cost time.
   is active. The peek-not-drain semantics still hold for the fallback nudge
   path (MCP hosts and any `triggerExtraction` failure).
 - **A child sub-agent's `thatch_memory_remember` drains the parent's buffer**
-  via the `childToParent` Map (`index.ts:79` declaration, `index.ts:272`
-  lookup). Two paths reach this machinery: (a) the **plugin-initiated child
+  via the `childToParent` Map in src/runtime.ts (declaration plus `.get()`
+  lookups in the idle and remember handlers). Two paths reach this machinery: (a) the **plugin-initiated child
   session** — `triggerExtraction` calls `client.session.create` with a
   `parentID`, the primary opencode path; (b) the **agent-initiated background
   task** — the model dispatches the fact-extractor via the `task` tool after
@@ -196,3 +196,36 @@ prose end marker stopped matching, and setup could never update the block
 again while `checkSetup` reported `markers-broken` on every session. Rule:
 never use file content as its own delimiter; agents will reword it. The
 legacy-prose detection constants exist only to migrate old installs.
+
+## The dual-shape plugin entry: named `server` + v2 default export silently breaks v1
+
+opencode v1's plugin loader (`readV1Plugin`, identical across 1.18.x) reads
+ONLY `mod.default`. A module that exports a named `server` plus a v2-shaped
+default `{ id, setup }` (no `server` inside the default) makes v1 throw on
+load - and the host swallows the error and SKIPS the plugin with no visible
+message. The failure looks like "thatch tools disappeared", not like a load
+error. This is why the dual entry exports a MERGED default object
+(`{ id, setup, server }`) and why every shim (the user's
+`~/.config/opencode/plugins/thatch.ts` and the QA runner's generated one)
+must re-export the default as well as the name. A named-only shim loads on
+v1 and silently disables thatch on v2 - same invisible failure, opposite
+host.
+
+## The extraction buffer matches on tool NAME, so Code Mode execute calls re-queue pipeline traffic
+
+The non-bufferable filter in `onToolExecuteAfter` (`src/runtime.ts`) matches
+`input.tool`, but a Code Mode `execute` call that wraps
+`tools.thatch_extraction_done` / `tools.thatch_memory_remember` inside its
+code string arrives as tool name `execute`. Unfixed, every execute-wrapped
+ack landed back in the buffer as an extractable interaction: each
+extraction run's payload contained only the previous run's dispatch and ack,
+the nudge always found pending interactions, and a session could loop
+forever on dispatch → ack → nudge (observed live in an oink session,
+September 2026 - the looped agent answered every turn with "Extractor
+dispatched and acknowledged. Stopping per the nudge" and never resumed the
+user's work; only a human message broke the cycle). The fix unwraps execute
+calls (`unwrapExecuteThatchCalls` in `src/extraction.ts`) and runs the
+wrapped tool's hook semantics instead of buffering. Lesson for sibling
+hooks: when a filter reasons about tool identity, an aggregator tool
+(arbitrary code execution over other tools) defeats name-based matching -
+unwrap the aggregation before classifying.

package/docs/dev/mcp-parity.md

@@ -24,8 +24,9 @@ This document maps the feature parity and documents the remaining gaps.
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
 | **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
-| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-thatch, non-skill, non-task tool calls in-process; **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
+| **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
+| **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |
 | **Prompt-aware recall nudge** | `chat.message` hook embeds the prompt with the in-process warm model, searches `db.search()`, pushes a nudge part if matches ≥ threshold | `UserPromptSubmit` hook → `thatch flush-tools` connects to the MCP server's sideband socket; the warm server embeds + searches; hook prints the nudge or falls back to the write nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — sideband socket gives cold hook processes access to the warm MCP server's model |
 | **Prediction auto-fire** (user decision model) | `chat.message` hook scores the prompt embedding against prediction matchers; injects a `[thatch] User decision model` nudge alongside the recall nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires prediction query via the sideband socket's `predictions` method in parallel with the recall nudge | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scorePredictionNudge` entry point in both paths |
 | **Behavior auto-fire** (self-discipline rules) | `chat.message` hook scores the prompt embedding against behavior matchers; injects a `[thatch] Situational behaviors` nudge (separate synthetic part, same embedding call) | `UserPromptSubmit` hook → `thatch flush-tools` fires behavior query via the sideband socket's `behaviors` method in parallel with recall and predictions | `beforeSubmitPrompt` hook → `thatch flush-tools --json` (same sideband path) | **Full** — same `scoreBehaviorNudge` entry point in both paths |
@@ -72,8 +73,8 @@ and the nudge (fallback):
 
 **Direct extraction (primary path):**
 
-1. `tool.execute.after` buffers every non-thatch, non-skill, non-task tool
-   call into a per-session in-memory array (max 20 interactions).
+1. `tool.execute.after` buffers every non-meta tool
+   call (`isMetaToolName` in `src/extraction.ts`) into a per-session in-memory array (max 20 interactions).
 2. When the parent session goes idle (`session.status` idle event) with pending
    buffer entries, the plugin calls `triggerExtraction`: creates a child session
    via `client.session.create` (with `parentID`), then prompts it via

package/docs/dev/setup-and-hooks.md

@@ -12,7 +12,12 @@ No `setup` command — opencode loads the plugin from `opencode.json`:
 { "plugin": ["@jeffober/thatch"] }
 ```
 
-The plugin entry (`src/index.ts`) registers these hooks in code:
+The plugin supports both opencode lines: v1 (1.18.x) via the `experimental.*`
+hook surface below, and v2 (2.x) via the promise-context domains
+(`session.hook("prompt"/"context"/"compaction")`, `tool.transform`). Both
+adapters delegate to the shared runtime (`src/runtime.ts`); the hooks below
+describe the v1 shape the v2 mappings mirror. The v1 hooks, registered in
+code (`src/opencode/v1.ts`):
 
 | Hook | Input | Output | Behavior |
 |------|-------|--------|----------|