@jeffober/thatch 0.1.38 → 0.1.39

package/README.md

@@ -92,8 +92,14 @@ Thatch gives your agent three layers of persistent context:
   only). The agent registers a watch on a GitHub PR or branch (main); thatch polls it in the
   background and prompts the session when comments, commits, CI results, or
   status changes arrive. Notifications carry pointer data only.
-
-Plus **26 skills** for memory workflows, structured multi-specialist code
+- **Notifications + user config** -- the agent can ping you out-of-band when
+  a long-running outcome lands: a desktop banner, a spoken voice
+  announcement, or both (macOS and Linux). Preferences live in a
+  hand-editable config file (`~/.config/thatch/config.json`) that the agent
+  manages through `config_get`/`config_set` -- ask it to change your voice
+  or quiet notifications entirely.
+
+Plus **skills** for memory workflows, structured multi-specialist code
 review, review response, change and feature walkthroughs, memory verification,
 knowledge export, and writing tasks
 (PR descriptions, tickets, PR splitting).

package/docs/dev/README.md

@@ -72,11 +72,13 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Per-session in-memory ring buffer (cap 20) that buffers non-thatch tool interactions and serializes them into the JSON payload the `get_extraction_payload` tool returns. The in-memory pipeline is opencode-only, but the payload builders (`buildExtractionPayload`, `deriveTitle`) are shared by both paths — `extract-queue.ts` imports `deriveTitle`, `mcp.ts` imports `buildExtractionPayload` for the extraction payload provider. `summarizeArgs` is used internally by `buildExtractionPayload`. |
 | `extract-queue.ts` | File-backed per-session JSONL queue (caps 20, oldest dropped). Shared by the Claude Code and Cursor hook paths, which fire one-shot per event with no cross-call state. This is the MCP-side equivalent of `extraction.ts`. |
+| `config.ts` | User config file (`~/.config/thatch/config.json`, beside the DB): Zod section schemas (strict — unknown keys fail validation), load with missing/invalid fallback to defaults, field-level merge, atomic save (temp + rename). Backs the `config_get`/`config_set` tools. |
+| `notify.ts` | Out-of-band notification dispatch: darwin (`osascript` banner + `/usr/bin/say` voice), linux (`notify-send` + `spd-say`/`espeak`), other platforms report unsupported. Injectable spawner (`CoreContext.spawner`) so tests never fire real commands. Backs the `notify_user` tool. |
 | `session-db.ts` | Read-only access to the opencode session database (opencode.db): session timeline (`session list`), full part/message retrieval (`session get`), OpenAI chat-completions transcript builder (`session transcript`), and decoded-content search (`session search`). Backs the `thatch session` CLI subcommands and the opencode-only `session_search`/`session_get` tools. Path resolution honors `OPENCODE_DB`, then the XDG default; the db opens read-only so a thatch bug cannot corrupt host history. |
 | `watchers.ts` | In-memory watcher registry and background poller for event-driven notifications (opencode-only). Watches GitHub PRs and branches via `gh api` (injected `GhRunner`), diffs against last-seen state, queues pointer-only events per session, and delivers them through a plugin-supplied callback when the session is idle. Process-lifetime state by design - no SQLite. |
 | `sideband.ts` | Unix domain socket server + client. The MCP server (long-lived, warm model) runs `SidebandServer` so one-shot hook processes can ask it to embed a prompt and search for matches without loading the model themselves. Handles three methods: `match` (recall nudge), `predictions` (prediction auto-fire), and `behaviors` (behavior auto-fire). Socket path is a hash of the DB path — both processes compute it independently. |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, prompt-aware recall nudge (`recallNudge` / `claudeRecallNudge`), prediction nudge (`predictionNudge`), behavior nudge (`behaviorNudge`), prediction verb selection (`predictionVerb`), Claude Code CLAUDE.md instructions, Cursor AGENTS.md instructions, Claude Code hook text. |
-| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (25 skills: fact-extractor, dedup-classifier, project-primer, 8 review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (fact-extractor, dedup-classifier, project-primer, the review specialists, review synthesizer, review context, code archaeology, review followup, review response, change walkthrough, code walkthrough, session reflection, coding-workflow, thatch-pr-description, thatch-ticket-description, thatch-split-overlarge-pr, memory-verify, knowledge-export — work on all three hosts) and `OPENCODE_ONLY_SKILLS` (code-review coordinator — requires sub-agent support, not installed for Claude Code or Cursor). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 | `scoring-engine.ts` | Generic four-table scoring engine with Bayesian confidence. Shared base for prediction and behavior engines — each wraps it with table-specific names. |
 | `prediction.ts` | Thin wrapper around `ScoringEngine` with prediction-specific table names. |
 | `behavior.ts` | Thin wrapper around `ScoringEngine` with behavior-specific table names. |

package/docs/dev/features/README.md

@@ -27,8 +27,9 @@ system, see [../skills.md](../skills.md). For non-obvious invariants, see
 | [compaction-recovery.md](compaction-recovery.md) | Compaction recovery (opencode compaction hooks) |
 | [session-lifecycle.md](session-lifecycle.md) | Session lifecycle management (opencode events, child tracking) |
 | [watchers.md](watchers.md) | Event-driven notifications (in-memory registry, background poller, PR watching) |
+| [notifications.md](notifications.md) | Out-of-band notification (banner + voice) and the user config file |
 | [setup.md](setup.md) | Setup system (markers, checkSetup, auto-refresh, binary resolution) |
 | [cli.md](cli.md) | CLI (subcommands, environment variables) |
-| [database.md](database.md) | Database (schema, migrations, WAL, 11 tables) |
-| [qa-system.md](qa-system.md) | QA system (93 use cases, automatable vs live, mise tasks) |
+| [database.md](database.md) | Database (schema, migrations, WAL) |
+| [qa-system.md](qa-system.md) | QA system (automatable vs live, mise tasks) |
 | [cicd.md](cicd.md) | CI/CD (CI pipeline, OIDC publishing, release helper) |

package/docs/dev/features/database.md

@@ -1,6 +1,6 @@
 # Database
 
-Thatch stores all data in a single SQLite file. The schema has 11 tables organized around three concerns: memory entries, the prediction engine, and the behavior engine.
+Thatch stores all data in a single SQLite file. The schema is organized around three concerns: memory entries, the prediction engine, and the behavior engine.
 
 ## Configuration
 
@@ -10,7 +10,7 @@ Thatch stores all data in a single SQLite file. The schema has 11 tables organiz
 
 ## Schema overview
 
-11 tables in three groups:
+The tables fall into three groups:
 
 | Group | Tables | Purpose |
 |-------|--------|---------|

package/docs/dev/features/multi-host.md

@@ -187,7 +187,7 @@ For the full parity matrix, see [../mcp-parity.md](../mcp-parity.md).
 
 ## Interactions with other features
 
-The 18 shared tools are available on all hosts via the single source of truth
+The shared tools are available on all hosts via the single source of truth
 in `src/tool-defs.ts`; opencode-only tools (e.g. `get_session_info`) are
 filtered out by the MCP server. Individual tool behavior is documented in
 [memory-store.md](memory-store.md), [extraction.md](extraction.md),
@@ -227,7 +227,7 @@ the opencode-only skills require sub-agent dispatch or in-process hooks.
 
 ## Key invariants
 
-- All hosts share the tool definitions from `src/tool-defs.ts` (18 shared + opencode-only tools marked `opencodeOnly: true`, which the MCP server filters out). Adding a tool requires updating `TOOL_DEFS` and all three prompt functions; opencode-only tools go in the opencode prompt only.
+- All hosts share the tool definitions from `src/tool-defs.ts` (shared tools plus opencode-only tools marked `opencodeOnly: true`, which the MCP server filters out). Adding a tool requires updating `TOOL_DEFS` and all three prompt functions; opencode-only tools go in the opencode prompt only.
 - The MCP server always exposes bare names. The `mcp__thatch__` prefix is applied by the MCP client, not thatch.
 - The three system prompt variants are independent string constants in `src/prompts.ts` with no shared template. Editing shared prose in one requires mirroring in the other two, or they drift.
 - The tool list line in all three prompts must match `TOOL_DEFS` in `src/tool-defs.ts` (opencode's list includes opencode-only tools; the MCP lists exclude them). The historical failure mode: a tool is added to `TOOL_DEFS` but only two of three prompts are updated.

package/docs/dev/features/notifications.md

@@ -0,0 +1,106 @@
+# Notifications and user config
+
+Out-of-band user notification (desktop banner + spoken voice) backed by a
+hand-editable user config file. Both are plain child processes and file I/O,
+so the feature works identically on every host -- opencode, Claude Code, and
+Cursor -- with no host-specific plumbing and no new npm dependencies.
+
+## Source files
+
+| File | Role |
+|------|------|
+| `src/config.ts` | Zod section schemas, config file load/save/merge, platform defaults. |
+| `src/notify.ts` | Per-platform dispatch for banner + voice, with an injectable spawner. |
+| `src/tool-defs.ts` | `config_get`, `config_set`, `notify_user` tool definitions (shared registry, non-opencodeOnly). |
+
+## Config design
+
+The config is one JSON file at `~/.config/thatch/config.json`, placed next to
+`thatch.db` by deriving the path from `THATCH_DB_PATH` (or the XDG default the
+same way `index.ts` and `mcp.ts` derive the DB path). Tests pass an explicit
+dbPath to keep writes inside a tempdir.
+
+Key decisions:
+
+- **Sections are `z.strictObject`.** Unknown keys fail validation instead of
+  being silently stripped, so a newer-version config round-tripping through an
+  older process cannot lose data. An unparseable file is *ignored* (empty
+  config + warning), never fatal -- a broken hand edit must not take the agent
+  down.
+- **Field-level merge in `config_set`.** `mergeNotificationPrefs` is a shallow
+  spread of current + patch (with `undefined` values stripped first). The
+  tool's description and the system prompt both state the merge semantics, and
+  the setter *echoes the resulting section* so the model can verify the write
+  in the same turn. This is the guardrail against the classic
+  read-modify-write failure where a model reconstructs a document and drops
+  sibling fields.
+- **Atomic writes.** `saveConfig` writes a temp file then renames, so a crash
+  mid-write cannot leave a truncated config and concurrent readers never see a
+  partial document.
+- **No env-var overrides for notification prefs.** The config file is the
+  single source of truth; `THATCH_*` env vars remain reserved for
+  infrastructure (DB path, model, thresholds). Preferences the LLM manages
+  belong in the file the LLM manages.
+
+`notificationDefaults()` supplies the platform fallbacks shown by `config_get`
+and applied by `notify_user`: darwin pins `Zarvox` + `Submarine` (the author's
+preference); other platforms defer to their tools' defaults.
+
+## Notification dispatch
+
+`sendNotification(request, spawner)` composes one or two command steps and
+returns a result string for the tool response:
+
+- **darwin**: banner via `/usr/bin/osascript -e 'display notification ...'`
+  (title defaults to `source`, then `thatch`; sound defaults to `Submarine`),
+  voice via `/usr/bin/say -v <voice>` (absolute path -- `~/bin/say` shadows
+  the system binary on the author's machine).
+- **linux**: banner via `notify-send`; voice via `spd-say -w`, falling back to
+  `espeak` when speech-dispatcher is absent. A voice override goes straight to
+  `espeak -v` because `spd-say` has no voice flag.
+- **other platforms** (win32 included): `[unsupported]` result, nothing runs.
+  Windows support is deliberately not a goal.
+
+Details that matter:
+
+- **The spawner is a `CoreContext` extension field** (`ctx.spawner`), the same
+  pattern as `watchers` and `extractionPayloadProvider`. Tests inject a mock;
+  production falls back to `defaultSpawner` (Bun.spawn). No test ever fires a
+  real banner or speaks.
+- **Failures never throw.** Every step's exit code and stderr are captured;
+  the result string is `[notified]` when anything succeeded, `[failed]` when
+  all requested channels failed, `[skipped]` when configured `mode` is
+  `none`, `[unsupported]` on other platforms.
+- **No delivery claims.** osascript exits 0 whether or not the banner
+  displayed (focus modes silently drop it), so result text reports command
+  success only.
+- **The spoken line prefixes the `source` label** ("PLAT-280: CI is green") so
+  a user with several concurrent agent sessions knows which one spoke. The
+  tool description enforces this on the model side.
+- Speech is awaited (the tool returns when the sentence finishes) so error
+  reporting stays honest. There is no debounce; polling agents notify once at
+  the end.
+
+## Prompt surface
+
+- `systemPrompt()` and `mcpInstructions()` list the three new tools and carry
+  a short "Notifications" section: when to notify, the source-label rule, and
+  the config_get-before-config_set instruction.
+- `notify_user` is not `opencodeOnly`: it needs no host capabilities, so MCP
+  hosts get it too. Nothing was added to `src/tools.ts` or `src/index.ts`.
+
+## Tests
+
+- `tests/config.test.ts` -- path derivation, missing/invalid/strict-schema
+  handling, round-trip, atomic save leaves no temp files, merge keeps
+  siblings, darwin defaults.
+- `tests/notify.test.ts` -- command construction per platform (mock spawner
+  records argv), AppleScript escaping, partial vs total failure, unsupported
+  platform, plus tool-level tests (merge-no-wipe, echo, `mode: none` no-op,
+  configured voice honored) with `THATCH_DB_PATH` pointed at a tempdir.
+- `tests/tool-defs.test.ts` -- registry count and name list (hardcoded literals that fail loudly when the surface changes).
+
+## QA coverage
+
+`tests/qa/auto/uc-059-tool-prefixing.ts` asserts the full bare-name list; the
+three new names are in its `expected` array.

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

@@ -1,14 +1,13 @@
 # QA System
 
-Thatch ships 95 QA use cases that verify end-to-end behavior. Each use case is
-a `bun:test` file that runs in an isolated environment — a temp-directory copy
-of the repo, not the working tree itself. Use cases are split into
-**automatable** (no LLM, fast) and **live** (spawns opencode, costs model
-tokens).
+Thatch ships a suite of QA use cases that verify end-to-end behavior. Each use
+case is a `bun:test` file that runs in an isolated environment — a
+temp-directory copy of the repo, not the working tree itself. Use cases are
+split into **automatable** (no LLM, fast) and **live** (spawns opencode, costs
+model tokens).
 
 ## What it does
 
-- 95 use cases: 75 automatable + 20 live
 - Automatable use cases run without an LLM — they test CLI behavior, hooks, DB
   operations, and tool execution directly via bun assertions
 - Live use cases spawn real opencode sessions — they test the full
@@ -39,7 +38,7 @@ registers all use cases in one suite, enabling `--concurrent
 --max-concurrency 5` to run 5 use cases at once (33s vs 88s sequential for the
 auto suite).
 
-### Automatable use cases (73)
+### Automatable use cases
 
 Run without an LLM. Test CLI behavior, hooks, DB operations, and tool
 execution directly via bun assertions. These are fast and run in parallel.
@@ -66,14 +65,15 @@ execution directly via bun assertions. These are fast and run in parallel.
 | UC-027 | behavior-confidence-model | ham/spam adjusts Bayesian confidence |
 | UC-028 | behavior-delete | semantic-match deletion with cascade |
 
-### Live use cases (20)
+### Live use cases
 
 Spawn real opencode sessions. Test the full pipeline with a real model. These
-cost model tokens and have a 20-minute per-use-case timeout. All 20 are marked
-`manualOnly: true` — the opencode binary is not available in CI, and three
-(UC-006, UC-010, UC-013) are manual-only for fundamental reasons (Cursor hook
-lifecycle, nested opencode session timeout, compaction trigger). Run them
-locally with `mise run qa-live`.
+cost model tokens and have a 20-minute per-use-case timeout. Live use cases
+check for `opencode` on PATH at runtime: if it is present they run; if not,
+they skip with `[MANUAL]`. Three (UC-006, UC-010, UC-013) are
+`manualOnly: true` for infrastructure reasons (Cursor hook lifecycle, nested
+opencode session timeout, compaction trigger). Run them locally with
+`mise run qa-live`.
 
 | UC | Name | What it tests |
 |----|------|---------------|
@@ -182,8 +182,8 @@ includes all of `tests/`), just not executed during `check`. See
 | `tests/qa/runner.ts` | `registerUseCase`, `UseCase` type, `ensureMaster`, `createFixture`, `runViaOpencode`, execution logic |
 | `tests/qa/auto/index.test.ts` | Automatable use case barrel — imports all auto use case modules |
 | `tests/qa/live/index.test.ts` | Live use case barrel — imports all live use case modules |
-| `tests/qa/auto/uc-NNN-*.ts` | 75 automatable use case files |
-| `tests/qa/live/uc-NNN-*.ts` | 20 live use case files |
+| `tests/qa/auto/uc-NNN-*.ts` | Automatable use case files, one per use case |
+| `tests/qa/live/uc-NNN-*.ts` | Live use case files, one per use case |
 
 No separate QA docs directory exists. QA use cases live in `tests/qa/` as executable tests, not docs.
 
@@ -191,8 +191,9 @@ No separate QA docs directory exists. QA use cases live in `tests/qa/` as execut
 
 1. **Automatable use cases never spawn an LLM.** They test CLI, hooks, DB, and
    tool execution directly.
-2. **Live use cases spawn real opencode sessions and cost model tokens.** All
-   20 are marked `manualOnly` — the opencode binary is not available in CI.
+2. **Live use cases spawn real opencode sessions and cost model tokens.** They
+   skip with `[MANUAL]` when `opencode` is not on PATH; three are
+   `manualOnly: true` for infrastructure reasons.
 3. **`QA_DRY_RUN=1` lists use cases without executing.** Use this for CI and
    coverage review.
 4. **Each use case follows the structured format**: preconditions, steps,

package/docs/dev/gotchas.md

@@ -146,3 +146,21 @@ here first. These are the things that have already cost time.
 - **`bun test` does not typecheck**, and `tsconfig.json` excludes `tests`. Test
   type errors are editor-only noise unless you run `tsc` on the test files
   directly. Keep test files type-clean anyway so the editor stays quiet.
+
+## Config and notifications
+
+- **Tests touching the config must set `THATCH_DB_PATH`.** The config tools
+  derive the config file path from the environment (`THATCH_DB_PATH`, then the
+  XDG default), not from the test's tempdir `ThatchDB`. A config test that
+  skips this reads and writes the developer's real
+  `~/.config/thatch/config.json`. See `tests/notify.test.ts` for the
+  save-and-restore pattern.
+- **osascript exits 0 even when macOS drops the banner.** Focus/Do Not Disturb
+  or missing notification permission silently swallow it. `notify_user` result
+  text therefore reports command success only; never interpret exit 0 as
+  delivery.
+- **New QA use cases must be imported into the directory's barrel file**
+  (`tests/qa/auto/index.test.ts` or the live one). The `.ts` files are not
+  discovered by bun on their own. UC-095 sat out of the suite for a release
+  cycle and rotted (asserted 3 watch tools when 4 existed) because nobody
+  noticed it never ran.

package/docs/dev/mcp-parity.md

@@ -18,7 +18,7 @@ This document maps the feature parity and documents the remaining gaps.
 
 | Feature | OpenCode plugin | Claude Code MCP + hooks | Cursor MCP + hooks | Parity |
 |---------|----------------|------------------------|---------------------|--------|
-| **Tools** (18 shared + 7 opencode-only, single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the 18 shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel |
+| **Tools** (single source of truth) | Plugin tool registration, `thatch_` prefix | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | MCP `tools/list` + `tools/call`, `mcp__thatch__` prefix (opencode-only tools filtered out) | **Full** for the shared tools; `get_session_info` (session identity) and `session_search`/`session_get` (conversation archaeology) are opencode-only — MCP hosts have no session concept. The `thatch session` CLI subcommands cover the same archaeology on any host with an opencode.db file. The `watch_*` tools (PR and branch watchers) are opencode-only — MCP hosts have no poller or proactive-prompt channel |
 | **System prompt** (store names, usage rules) | `experimental.chat.system.transform` — dynamic, repo baked in at runtime | CLAUDE.md static text appended by `thatch setup`; repo auto-detected by the MCP server at startup | AGENTS.md static text appended by `thatch setup`; repo auto-detected at startup | **Approximate** — static text persists through compaction, so the agent retains the usage instructions, but the dynamic per-turn refresh is lost |
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **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 |

package/docs/dev/skills.md

@@ -29,9 +29,9 @@ description: Extract durable project facts ... Use when ...
   Code, and Cursor all auto-discover skills and use the description for
   relevance).
 
-## The 26 skills
+## The skills
 
-**Shared (25)** — installed everywhere; no sub-agents required:
+**Shared** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -61,11 +61,11 @@ description: Extract durable project facts ... Use when ...
 | `thatch-memory-verify` | Fact-check a single memory against the current codebase and correct stale claims. Uses git archaeology to preserve historical context when changes were intentional. |
 | `thatch-knowledge-export` | Compile everything thatch knows about a topic into a curated markdown file for knowledge transfer. Searches across stores, curates out personal noise, fact-checks code-related memories via `thatch-memory-verify`. |
 
-**opencode-only (1)** — the coordinator needs sub-agent support:
+**opencode-only** — the coordinator needs sub-agent support:
 
 | Skill | Role |
 |-------|------|
-| `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 8 specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
+| `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 review specialists in parallel, synthesize with a workflow-change preface and prior-comment cross-reference. |
 
 ## REVIEW_COMMON
 
@@ -99,7 +99,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 26 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* all shared skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -138,7 +138,7 @@ and `--cursor` pass only the shared set.
 ## Memory review skills in practice
 
 - **Quick single lens**: load any specialist directly and point it at a branch.
-- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all 8 specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
+- **Full review on opencode**: load `thatch-code-review` — it gathers project context, researches affected workflows, dispatches all review specialists in parallel (with both the context brief and workflow guide injected into each briefing), then synthesizes a report that starts with the workflow changes before findings.
 - **Full review on Claude Code/Cursor**: run each specialist in sequence, then
   run `thatch-review-synthesizer` to verify and aggregate.
 - **Follow-up round (re-review)**: load `thatch-review-followup` when the author

package/docs/user/README.md

@@ -12,6 +12,7 @@ This README is the overview. Each feature has its own guide:
 - [memory.md](memory.md): persistent memory store
 - [extraction.md](extraction.md): automatic fact extraction from tool calls
 - [watchers.md](watchers.md): event-driven notifications (PR and branch watching)
+- [notifications.md](notifications.md): banner and voice notifications, user config
 - [prediction-engine.md](prediction-engine.md): user decision model
 - [behavior-engine.md](behavior-engine.md): agent self-discipline rules
 - [default-behaviors.md](default-behaviors.md): what ships automatically
@@ -143,6 +144,22 @@ Stores are created automatically. No setup required.
 | `thatch_behavior_list` | List all codified behaviors with matchers, confidence, and provenance. |
 | `thatch_behavior_delete` | Delete a behavior by semantic match. Edges and provenance are cascade-deleted. |
 
+### Config tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_config_get` | Read the user config (`~/.config/thatch/config.json`), with defaults annotated. The agent manages config through these tools; you can also edit the file by hand. |
+| `thatch_config_set` | Update config fields. Field-level merge: only fields you pass change. Returns the resulting section so the agent can verify. |
+
+### Notification tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_notify_user` | Notify the user out-of-band: desktop banner and/or spoken voice. Use for long-running outcomes worth interrupting for (CI results, deploys, watcher events). macOS and Linux. |
+
+See [notifications.md](notifications.md) for the full behavior and
+configuration.
+
 ### Session tools (opencode only)
 
 | Tool | What it does |
@@ -159,7 +176,8 @@ search` - JSONL output designed for piping to `jq` or `grep`.
 
 | Tool | What it does |
 |------|-------------|
-| `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
+| `thatch_watch_create` | Watch a GitHub PR for events (comments, review comments and replies, thread resolutions, commits, status changes, description edits, CI completions). The plugin polls in the background and prompts the session when a watched event happens. |
+| `thatch_watch_branch_create` | Watch a GitHub branch (typically main) for commit landings, CI check-run completions, and workflow runs, with an optional workflow-name filter. |
 | `thatch_watch_list` | List this session's active watchers. |
 | `thatch_watch_cancel` | Cancel one of this session's watchers by id. |
 
@@ -287,14 +305,14 @@ response, walkthrough, and workflow skills that support the review pipeline:
 
 | Skill | opencode | Claude Code | Cursor |
 |-------|----------|-------------|--------|
-| Memory skills (6) | Yes | Yes | Yes |
-| Review specialists (8) | Yes | Yes | Yes |
+| Memory skills | Yes | Yes | Yes |
+| Review specialists | Yes | Yes | Yes |
 | Review synthesizer | Yes | Yes | Yes |
 | Review context + code archaeology | Yes | Yes | Yes |
 | Review followup | Yes | Yes | Yes |
 | Review response (author-side) | Yes | Yes | Yes |
-| Walkthrough skills (2) | Yes | Yes | Yes |
-| Writing skills (3) | Yes | Yes | Yes |
+| Walkthrough skills | Yes | Yes | Yes |
+| Writing skills | Yes | Yes | Yes |
 | Code review coordinator | Yes | No (requires sub-agents) | No (requires sub-agents) |
 
 ### Using review skills
@@ -379,20 +397,24 @@ Store defaults to your current git repo.
 
 ## Configuration
 
-No configuration needed. The default behavior:
+Most configuration needs none. Two layers exist:
 
-- **Database**: `~/.config/thatch/thatch.db` (created automatically)
-- **Embedding model**: bge-small-en-v1.5 (downloaded once, cached locally)
-- **Store name**: auto-detected from `git remote get-url origin`
-- **Search scope**: always includes the project store and `global`
-
-### Environment variables
+- **Preferences the agent manages** live in
+  `~/.config/thatch/config.json` (beside the database): notification mode,
+  voice, and sound. Ask your agent ("set notifications to banner only") or
+  edit the file by hand. See [notifications.md](notifications.md).
+- **Environment variables** for infrastructure:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location |
+| `THATCH_DB_PATH` | `$XDG_CONFIG_HOME/thatch/thatch.db` | Override database location (the config file follows it) |
 | `THATCH_MODEL` | `Xenova/bge-small-en-v1.5` | Override embedding model |
 
+Unchanged defaults: the database is created automatically, the embedding
+model downloads once and is cached, the store name is auto-detected from
+`git remote get-url origin`, and search always includes the project store
+and `global`.
+
 `$XDG_CONFIG_HOME` defaults to `~/.config` when unset.
 
 **Changing `THATCH_MODEL` on an existing database:** memories embedded by a

package/docs/user/notifications.md

@@ -0,0 +1,84 @@
+# Notifications
+
+Thatch can notify you out-of-band when something happens worth leaving the
+terminal for: a CI run finishing, a merge or deploy completing, a watched PR
+receiving a comment. The notification is a desktop banner, a spoken voice
+announcement, or both, depending on your preferences.
+
+This works on every host (opencode, Claude Code, Cursor) because it is plain
+child processes, not host plumbing.
+
+## The tools
+
+| Tool | What it does |
+|------|-------------|
+| `thatch_notify_user` | Send a banner and/or spoken notification. |
+| `thatch_config_get` | Read the current config, with defaults annotated. |
+| `thatch_config_set` | Update config fields. Returns the resulting section. |
+
+### notify_user
+
+```text
+thatch_notify_user(message: "CI is green, clear for merge",
+                   source: "PLAT-280")
+```
+
+- **macOS**: banner via Notification Center (with an alert sound) and voice
+  via the built-in `say` command.
+- **Linux**: banner via `notify-send` (libnotify) and voice via
+  `spd-say`/`espeak` when installed. Missing tools are reported, never fatal.
+- **Windows**: not supported. The tool reports this instead of guessing.
+
+The agent includes a `source` label (a ticket number or feature name) so you
+know which of your concurrent sessions is speaking. Voice text spells out
+letter sequences ("C I green", not "CI green") so text-to-speech pronounces
+them.
+
+The tool result reports command success only. macOS focus modes can silently
+swallow banners; if you are not seeing them, check Focus settings and that
+your terminal app has notification permission.
+
+## Configuring notifications
+
+You have two options, and they edit the same file:
+
+1. **Ask your agent.** "Set notifications to banner only" -- the agent reads
+   current values with `config_get`, changes what you asked for with
+   `config_set`, and shows you the result.
+2. **Edit the file yourself.** The config lives at
+   `~/.config/thatch/config.json` (next to `thatch.db`, or under
+   `$XDG_CONFIG_HOME`).
+
+```json
+{
+  "notifications": {
+    "mode": "both",
+    "voice": "Zarvox",
+    "sound": "Submarine"
+  }
+}
+```
+
+| Field | Values | Default | Applies to |
+|-------|--------|---------|------------|
+| `mode` | `both`, `banner`, `voice`, `none` | `both` | Which channels `notify_user` uses. `none` disables notifications entirely; the agent is told it no-opped. |
+| `voice` | any installed voice name | `Zarvox` (macOS) | Spoken announcements. List macOS voices with `/usr/bin/say -v '?'`. |
+| `sound` | any system sound name | `Submarine` (macOS) | Banner alert sound. Sounds live in `/System/Library/Sounds`. |
+
+Fields you leave out fall back to the defaults. Unknown sections or fields
+are rejected when the file is read, and the config is ignored with a warning
+if it cannot be parsed -- a broken hand edit never crashes the agent, it just
+falls back to defaults.
+
+The agent can manage the whole file for you through `config_get` /
+`config_set`; edits merge at the field level, so the agent changing your
+voice cannot wipe your mode.
+
+## Limitations
+
+- Banners are best-effort by nature of the OS. The agent can only report
+  whether the command ran, not whether you saw the banner.
+- Speech is awaited: the tool returns after the sentence finishes. Notifications
+  are short by design.
+- There is no debounce. If an agent polls a status in a tight loop, it should
+  notify once at the end, not per poll.

package/docs/user/skills.md

@@ -20,7 +20,7 @@ becomes part of the agent's context.
 
 ## What ships
 
-26 skills total (25 shared, 1 opencode-only):
+Skills are split into shared (all hosts) and opencode-only:
 
 ### Memory skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "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/config.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+// Thatch user config: one JSON file beside thatch.db, hand-editable and
+// managed by the config_get / config_set tools. Sections are strict (unknown
+// keys fail validation instead of being silently dropped) so a hand edit or a
+// newer-version file can never lose data by round-tripping through an older
+// process. config_set merges at the field level: omitted fields keep their
+// values, so a partial section update never wipes sibling preferences.
+
+export const notificationPrefsSchema = z.strictObject({
+  mode: z.enum(["both", "banner", "voice", "none"]).optional(),
+  voice: z.string().optional(),
+  sound: z.string().optional(),
+});
+
+export const configSchema = z.strictObject({
+  notifications: notificationPrefsSchema.optional(),
+});
+
+export type NotificationPrefs = z.infer<typeof notificationPrefsSchema>;
+export type Config = z.infer<typeof configSchema>;
+
+/** Sections in presentation order. config_get / config_set iterate this. */
+export const CONFIG_SECTIONS = ["notifications"] as const;
+export type ConfigSection = (typeof CONFIG_SECTIONS)[number];
+
+/**
+ * Resolves the config file path. By convention it lives next to thatch.db,
+ * so a custom THATCH_DB_PATH moves the config with it. Tests pass an
+ * explicit dbPath to keep writes inside a tempdir.
+ */
+export function configFilePath(dbPath?: string): string {
+  if (dbPath) return join(dirname(dbPath), "config.json");
+  const dir = process.env.THATCH_DB_PATH
+    ? dirname(process.env.THATCH_DB_PATH)
+    : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "thatch");
+  return join(dir, "config.json");
+}
+
+export interface LoadedConfig {
+  config: Config;
+  /** Non-null when the file exists but is unparseable; the file is ignored. */
+  warning: string | null;
+  path: string;
+}
+
+/** Reads the config file. A missing file is the empty config, not an error. */
+export function loadConfig(dbPath?: string): LoadedConfig {
+  const path = configFilePath(dbPath);
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return { config: {}, warning: null, path };
+  }
+  try {
+    const parsed = configSchema.parse(JSON.parse(raw));
+    return { config: parsed, warning: null, path };
+  } catch (err) {
+    return {
+      config: {},
+      warning: `config file at ${path} is invalid and was ignored (${err instanceof Error ? err.message : String(err)})`,
+      path,
+    };
+  }
+}
+
+/**
+ * Writes the config atomically (temp file + rename) so a crash mid-write
+ * cannot leave a truncated file, and concurrent readers never see a partial
+ * document.
+ */
+export function saveConfig(config: Config, dbPath?: string): string {
+  const path = configFilePath(dbPath);
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
+  renameSync(tmp, path);
+  return path;
+}
+
+/** Field-level merge for one section: omitted fields keep their values. */
+export function mergeNotificationPrefs(
+  current: NotificationPrefs | undefined,
+  patch: NotificationPrefs,
+): NotificationPrefs {
+  return { ...current, ...patch };
+}
+
+/**
+ * Platform fallbacks shown by config_get and applied by notify_user when the
+ * user has not set a preference. Only darwin has opinionated defaults; other
+ * platforms use their tools' own voices and sounds.
+ */
+export function notificationDefaults(): { mode: "both" | "banner" | "voice" | "none"; voice?: string; sound?: string } {
+  if (process.platform === "darwin") {
+    return { mode: "both", voice: "Zarvox", sound: "Submarine" };
+  }
+  return { mode: "both" };
+}

package/src/embeddings.ts

@@ -16,6 +16,7 @@ export interface EmbeddingModel {
   load(): Promise<void>;
   queryEmbed(text: string): Promise<Float32Array>;
   passageEmbed(text: string): Promise<Float32Array>;
+  dispose(): Promise<void>;
 }
 
 /**
@@ -81,4 +82,35 @@ export class BgeEmbeddingModel implements EmbeddingModel {
     });
     return output.data as Float32Array;
   }
+
+  /**
+   * Releases the pipeline's native ONNX sessions. The host calls this during
+   * graceful shutdown so onnxruntime's NAPI wrap finalizers are freed while
+   * the runtime is still alive. If instead they survive to Bun's worker
+   * teardown, Bun panics creating their errors (oven-sh/bun#34664).
+   *
+   * Best-effort by design: dispose never throws, and a failed release is
+   * indistinguishable from never loading. An embed call after dispose just
+   * lazily re-loads the model.
+   */
+  async dispose(): Promise<void> {
+    // An in-flight load memoizes a rejecting promise on failure. Await it
+    // defensively so its error neither escapes dispose nor kills the teardown.
+    if (this.#loading) {
+      try {
+        await this.#loading;
+      } catch {
+        // Load failed - nothing was loaded, so nothing to release.
+      }
+    }
+    const pipe = this.#pipe;
+    this.#pipe = null;
+    this.#loading = null;
+    if (!pipe) return;
+    try {
+      await pipe.dispose();
+    } catch {
+      // Best-effort - see doc comment above.
+    }
+  }
 }

package/src/index.ts

@@ -816,6 +816,10 @@ export const server: Plugin = async ({ client, worktree }) => {
     dispose: async () => {
       stopVersionChecker();
       watchers.dispose();
+      // Release native ONNX sessions while the worker is still healthy. Left
+      // to Bun's teardown, their NAPI finalizers panic the process (see
+      // BgeEmbeddingModel.dispose).
+      await model.dispose();
       db.close();
     },
   };

package/src/notify.ts

@@ -0,0 +1,123 @@
+// Out-of-band user notification: desktop banner plus spoken voice. Both are
+// plain child processes - no vendored binaries, no npm notifier dependency -
+// because the per-platform commands are one-liners and the alternatives
+// (node-notifier's bundled terminal-notifier) trip Gatekeeper on modern macOS.
+// Dispatch is darwin and linux only by design: win32 support is not a goal,
+// and the tool reports the gap honestly rather than half-working.
+
+export type NotifyChannel = "both" | "banner" | "voice";
+
+export interface NotifyRequest {
+  message: string;
+  title?: string;
+  source?: string;
+  channel: NotifyChannel;
+  /** Voice name override; falls back to the platform default. */
+  voice?: string;
+  /** Banner alert sound (macOS); falls back to Submarine. */
+  sound?: string;
+  platform?: string;
+}
+
+export interface SpawnResult {
+  exitCode: number | null;
+  stderr: string;
+}
+
+export type Spawner = (cmd: string[]) => Promise<SpawnResult>;
+
+/** The real runner. Tests inject a mock so nothing actually speaks. */
+export const defaultSpawner: Spawner = async (cmd) => {
+  const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+  const stderr = await new Response(proc.stderr).text();
+  await proc.exited;
+  return { exitCode: proc.exitCode, stderr };
+};
+
+/**
+ * The spoken line. The source label (ticket number, feature name) goes first
+ * so the listener immediately knows which session is talking.
+ */
+export function spokenText(request: Pick<NotifyRequest, "message" | "source">): string {
+  return request.source ? `${request.source}: ${request.message}` : request.message;
+}
+
+/** AppleScript string literal - backslash and double-quote are the escapes. */
+function appleScriptString(s: string): string {
+  return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+interface StepOutcome {
+  label: string;
+  ok: boolean;
+  detail: string;
+}
+
+async function runStep(label: string, cmd: string[], spawner: Spawner): Promise<StepOutcome> {
+  try {
+    const result = await spawner(cmd);
+    if (result.exitCode === 0) {
+      return { label, ok: true, detail: label };
+    }
+    return { label, ok: false, detail: `${label} failed: exited ${result.exitCode}${result.stderr.trim() ? `: ${result.stderr.trim()}` : ""}` };
+  } catch (err) {
+    // Missing binary surfaces here (ENOENT) rather than as an exit code.
+    return { label, ok: false, detail: `${label} failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/**
+ * Sends the notification and returns a result line for the tool response.
+ * A zero exit proves only that the command ran - macOS focus modes can still
+ * suppress the banner silently - so the result never claims the user saw it.
+ * Never throws: every failure becomes text the calling model can read.
+ */
+export async function sendNotification(
+  request: NotifyRequest,
+  spawner: Spawner = defaultSpawner,
+): Promise<string> {
+  const platform = request.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux") {
+    return `[unsupported] notifications are not implemented on ${platform} (macOS and Linux only); nothing was sent.`;
+  }
+
+  const outcomes: StepOutcome[] = [];
+
+  if (request.channel !== "voice") {
+    const title = request.title ?? request.source ?? "thatch";
+    if (platform === "darwin") {
+      const sound = request.sound ?? "Submarine";
+      const script =
+        `display notification ${appleScriptString(request.message)} ` +
+        `with title ${appleScriptString(title)} sound name ${appleScriptString(sound)}`;
+      outcomes.push(await runStep("banner (osascript)", ["/usr/bin/osascript", "-e", script], spawner));
+    } else {
+      outcomes.push(await runStep("banner (notify-send)", ["notify-send", title, request.message], spawner));
+    }
+  }
+
+  if (request.channel !== "banner") {
+    const spoken = spokenText(request);
+    if (platform === "darwin") {
+      const voice = request.voice ?? "Zarvox";
+      outcomes.push(await runStep(`voice (${voice})`, ["/usr/bin/say", "-v", voice, spoken], spawner));
+    } else {
+      // spd-say has no voice flag, so a voice override goes straight to
+      // espeak (-v). Without an override, speech-dispatcher is the friendlier
+      // default; raw espeak is the fallback when it is absent.
+      if (request.voice) {
+        outcomes.push(await runStep(`voice (espeak -v ${request.voice})`, ["espeak", "-v", request.voice, spoken], spawner));
+      } else {
+        const spd = await runStep("voice (spd-say)", ["spd-say", "-w", spoken], spawner);
+        outcomes.push(spd.ok ? spd : await runStep("voice (espeak)", ["espeak", spoken], spawner));
+      }
+    }
+  }
+
+  const failed = outcomes.filter((o) => !o.ok);
+  if (outcomes.every((o) => !o.ok)) {
+    return `[failed] ${failed.map((o) => o.detail).join("; ")}`;
+  }
+  const parts = outcomes.map((o) => (o.ok ? `${o.detail} ok` : o.detail));
+  return `[notified] ${parts.join("; ")}`;
+}

package/src/prompts.ts

@@ -23,7 +23,8 @@ Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
         thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
         thatch_prediction_delete,
         thatch_behavior_codify, thatch_behavior_feedback, thatch_behavior_list,
-        thatch_behavior_delete, thatch_get_session_info,
+        thatch_behavior_delete, thatch_config_get, thatch_config_set,
+        thatch_notify_user, thatch_get_session_info,
         thatch_session_search, thatch_session_get,
         thatch_watch_create, thatch_watch_branch_create,
         thatch_watch_list, thatch_watch_cancel
@@ -178,6 +179,17 @@ way that is about your own operational discipline (not a user preference):
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
+## Notifications
+
+Use thatch_notify_user for terminal-event outcomes the user should hear about
+even when looking away: CI results, merge or deploy completion, watcher
+events. Always include a source label (ticket number or feature name) so the
+user knows which session spoke. Manage notification preferences with
+thatch_config_get and thatch_config_set - call config_get first; config_set
+merges fields and echoes the result. The config file
+(~/.config/thatch/config.json) is also hand-editable; do not store thatch
+config in memory.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment
@@ -288,7 +300,9 @@ Tools are prefixed in ${host}: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`,
 \`mcp__thatch__behavior_codify\`, \`mcp__thatch__behavior_feedback\`,
-\`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`. Bare names used below for readability.
+\`mcp__thatch__behavior_list\`, \`mcp__thatch__behavior_delete\`,
+\`mcp__thatch__config_get\`, \`mcp__thatch__config_set\`,
+\`mcp__thatch__notify_user\`. Bare names used below for readability.
 get_session_info, session_search, session_get, watch_create,
 watch_branch_create, watch_list,
 and watch_cancel are intentionally absent: they are opencode-only (MCP
@@ -412,6 +426,16 @@ way that is about your own operational discipline (not a user preference):
 Do not codify rules that make you lazier or less thorough. Rules should encode
 discipline, not shortcuts.
 
+## Notifications
+
+Use notify_user for terminal-event outcomes the user should hear about even
+when looking away: CI results, merge or deploy completion, watcher events.
+Always include a source label (ticket number or feature name) so the user
+knows which session spoke. Manage notification preferences with config_get
+and config_set - call config_get first; config_set merges fields and echoes
+the result. The config file (~/.config/thatch/config.json) is also
+hand-editable; do not store thatch config in memory.
+
 ## What to Store
 
 - **Global store**: user observations, agent personality, system environment

package/src/tool-defs.ts

@@ -1,6 +1,18 @@
 import { z } from "zod";
 import type { ThatchDB, DedupCandidate, MemoryRow } from "./db";
 import type { EmbeddingModel } from "./embeddings";
+import {
+  CONFIG_SECTIONS,
+  loadConfig,
+  mergeNotificationPrefs,
+  notificationDefaults,
+  notificationPrefsSchema,
+  saveConfig,
+  type Config,
+  type ConfigSection,
+  type NotificationPrefs,
+} from "./config";
+import { sendNotification, defaultSpawner, type NotifyChannel, type Spawner } from "./notify";
 import { predictionVerb } from "./prompts";
 import { resolveOpencodeDbPath, SessionDB, partToTimelineEntry, partToFullJson, messageToFullJson } from "./session-db";
 import { PR_EVENT_TYPES, BRANCH_EVENT_TYPES, type WatcherRegistry, type PrWatcherEventType, type BranchWatcherEventType } from "./watchers";
@@ -42,6 +54,9 @@ export interface CoreContext {
    *  path - MCP hosts have no poller, no event bus, and no way to deliver a
    *  proactive prompt, so watch tools are opencode-only. */
   watchers?: WatcherRegistry;
+  /** Injectable command runner for notify_user. Defaults to Bun.spawn.
+   *  Tests inject a mock so notifications never actually fire or speak. */
+  spawner?: Spawner;
 }
 
 /**
@@ -818,6 +833,161 @@ const behaviorDeleteDef: ToolDef = {
   },
 };
 
+// ---------------------------------------------------------------------------
+// Config and notification tools. The config is a single JSON file beside
+// thatch.db, hand-editable and also managed through these tools. notify_user
+// shells out to the platform's banner and TTS commands - see src/notify.ts.
+// ---------------------------------------------------------------------------
+
+/** Notification preference fields, in presentation order. */
+const NOTIFICATION_FIELDS = ["mode", "voice", "sound"] as const;
+
+/** Renders one section with per-field default annotations for echo output. */
+function renderNotificationSection(prefs: NotificationPrefs | undefined): string {
+  const defaults = notificationDefaults();
+  const lines = ["notifications:"];
+  for (const field of NOTIFICATION_FIELDS) {
+    const current = prefs?.[field];
+    const fallback = defaults[field];
+    lines.push(`  ${field}: ${current ?? "<unset>"}${fallback ? ` (default: ${fallback})` : ""}`);
+  }
+  return lines.join("\n");
+}
+
+/** Drops keys explicitly set to undefined so a merge never overwrites. */
+function stripUndefined(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+
+const configGetDef: ToolDef = {
+  name: "config_get",
+  description:
+    "Read thatch's user config, optionally restricted to one section. " +
+    "Values are annotated with their defaults; unset fields show <unset>. " +
+    "The config file (~/.config/thatch/config.json, beside thatch.db) is " +
+    "also hand-editable. Call this before config_set.",
+  args: {
+    section: z.enum(["notifications"]).optional().describe(
+      "Restrict output to one section. Omit to read all sections.",
+    ),
+  },
+  async execute(args) {
+    const loaded = loadConfig();
+    const lines: string[] = [];
+    if (loaded.warning) lines.push(`[warning] ${loaded.warning}`, "");
+    const sections: ConfigSection[] = args.section
+      ? [args.section as ConfigSection]
+      : [...CONFIG_SECTIONS];
+    for (const name of sections) {
+      if (name === "notifications") {
+        lines.push(renderNotificationSection(loaded.config.notifications));
+      }
+    }
+    lines.push("", `file: ${loaded.path}`);
+    return lines.join("\n");
+  },
+};
+
+const configSetDef: ToolDef = {
+  name: "config_set",
+  description:
+    "Update thatch's user config. Field-level merge: only fields you pass " +
+    "change; omitted fields and omitted sections keep their current values. " +
+    "Returns the resulting section so you can verify the write. Call " +
+    "config_get first to see current values and defaults.",
+  args: {
+    notifications: z.strictObject({
+      mode: z.enum(["both", "banner", "voice", "none"]).optional().describe(
+        "Default channels for notify_user: both, banner only, voice only, " +
+        "or none (disable notifications entirely).",
+      ),
+      voice: z.string().optional().describe(
+        "Spoken voice name (macOS default: Zarvox). Omit to use the " +
+        "platform default.",
+      ),
+      sound: z.string().optional().describe(
+        "Banner alert sound (macOS, from /System/Library/Sounds; default: " +
+        "Submarine). Omit to use the platform default.",
+      ),
+    }).optional().describe(
+      "Notification preferences to update. Fields you omit keep their " +
+      "current values.",
+    ),
+  },
+  async execute(args) {
+    const loaded = loadConfig();
+    const config: Config = { ...loaded.config };
+    const patch = args.notifications as Record<string, unknown> | undefined;
+    if (!patch || Object.keys(stripUndefined(patch)).length === 0) {
+      return (
+        "Nothing to update: pass a section with fields to change.\n" +
+        renderNotificationSection(config.notifications)
+      );
+    }
+    config.notifications = notificationPrefsSchema.parse(
+      mergeNotificationPrefs(config.notifications, stripUndefined(patch)),
+    );
+    const path = saveConfig(config);
+    return (
+      `[saved] ${path}\n` +
+      renderNotificationSection(config.notifications)
+    );
+  },
+};
+
+const notifyUserDef: ToolDef = {
+  name: "notify_user",
+  description:
+    "Notify the user out-of-band: desktop banner and/or spoken voice " +
+    "(macOS: Notification Center + say; Linux: notify-send + spd-say/espeak). " +
+    "Use for long-running terminal-event outcomes worth interrupting for: " +
+    "CI results, merge or deploy completion, watcher events. ALWAYS include " +
+    "source: a word or two identifying the session or work item (ticket " +
+    "number or feature name) so the user knows which session spoke. Honors " +
+    "the user's configured preferences; pass channel to override for this " +
+    "call only. If the configured mode is none, the tool no-ops and says " +
+    "so. The result reports command success only - OS focus modes can " +
+    "silently suppress banners.",
+  args: {
+    message: z.string().describe(
+      "The notification text. Spell out letter sequences so " +
+      "text-to-speech pronounces them (\"C I green\", not \"CI green\").",
+    ),
+    title: z.string().optional().describe(
+      "Banner title. Defaults to source, then \"thatch\".",
+    ),
+    source: z.string().optional().describe(
+      "Short label identifying the session or work item (ticket number or " +
+      "feature name), e.g. \"PLAT-280\". Prepended to the spoken message.",
+    ),
+    channel: z.enum(["both", "banner", "voice"]).optional().describe(
+      "Override the configured mode for this call only.",
+    ),
+    voice: z.string().optional().describe(
+      "Override the configured voice for this call.",
+    ),
+  },
+  async execute(args, ctx) {
+    const loaded = loadConfig();
+    const prefs = loaded.config.notifications ?? {};
+    const mode = prefs.mode ?? "both";
+    if (mode === "none") {
+      return "[skipped] notifications are disabled (notifications.mode: none). " +
+        "Use thatch config_set to re-enable if the user asks.";
+    }
+    const channel = (args.channel as NotifyChannel | undefined) ?? (mode as NotifyChannel);
+    return sendNotification({
+      message: args.message as string,
+      title: args.title as string | undefined,
+      source: args.source as string | undefined,
+      channel,
+      voice: (args.voice as string | undefined) ?? prefs.voice,
+      sound: prefs.sound,
+    }, ctx.spawner ?? defaultSpawner);
+  },
+};
+
+
 /**
  * Reports the calling session's identity. opencode does not surface its
  * session ID to the model, so the model cannot learn it any other way -
@@ -1148,6 +1318,9 @@ export const TOOL_DEFS: ToolDef[] = [
   behaviorFeedbackDef,
   behaviorListDef,
   behaviorDeleteDef,
+  configGetDef,
+  configSetDef,
+  notifyUserDef,
   getSessionInfoDef,
   sessionSearchDef,
   sessionGetDef,