feat(core): add bm hook producer front door for harness capture

CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## Unreleased
+
+### Features
+
+- **#997**: Added the `bm hook` harness front door (SPEC-55). Lifecycle verbs
+  (`session-start`, `pre-compact`) move the plugin hook logic into the package
+  behind per-harness stdin adapters, with the session brief fenced as reference
+  data. Opt-in envelope capture (`captureEvents: true`, fail-closed) records
+  redacted lifecycle events into a local inbox WAL, projected deterministically
+  by `bm hook flush`; `bm hook status` shows the surface. `bm hook install` /
+  `bm hook remove` wire the hooks into user-level harness config for standalone
+  users with ownership-tagged, surgical merging. The Claude Code and Codex
+  plugin hooks are now zero-logic shims that exec `basic-memory hook`; their
+  `uvx` fallback floor is bumped by release tooling.
+
 ## v0.22.1 (2026-06-12)
 
 Follow-up patch to v0.22.0. Fixes project and default-project resolution on

plugins/claude-code/CHANGELOG.md

@@ -62,6 +62,14 @@ Memory's durable graph**, rather than a memory layer of its own. See
 
 ### Changed
 
+- **Hooks are now zero-logic shims** (SPEC-55, #997). `session-start.sh` and
+  `pre-compact.sh` resolve the Basic Memory CLI (`BM_BIN` → `basic-memory`/`bm`
+  on PATH → `uvx "basic-memory>=<floor>"`, floor bumped by release tooling) and
+  exec `basic-memory hook <event> --harness claude` with the hook JSON on
+  stdin. The brief/checkpoint logic lives in the released package; opt-in
+  `captureEvents: true` additionally records redacted event envelopes to a
+  local inbox. uv is the documented prerequisite; the uvx fallback fetches from
+  PyPI on first run.
 - **SessionStart hook now nudges toward `/basic-memory:bm-setup` on first run** — when
   no `basicMemory` config block is present in either settings file. The nudge
   survives a failed/empty task query (so a brand-new user with no project yet still

plugins/claude-code/README.md

@@ -45,13 +45,36 @@ Plugin skills are namespaced under the plugin name:
 
 ## Requirements
 
-- [Basic Memory](https://github.com/basicmachines-co/basic-memory) `>= 0.19.0`
-  connected as an MCP server. `uv tool install basic-memory` is recommended (it puts
-  a `basic-memory` binary on PATH, which the hooks call directly). A `uvx
-  basic-memory mcp`-only setup also works — the hooks fall back to `uvx`/`uv` when no
-  binary is on PATH.
+- **[uv](https://docs.astral.sh/uv/)** — the documented prerequisite for the hooks'
+  fallback path. Install per platform:
+  - macOS: `brew install uv` (or the curl installer below)
+  - Linux/macOS: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+  - Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+- [Basic Memory](https://github.com/basicmachines-co/basic-memory) connected as an
+  MCP server. `uv tool install basic-memory` is recommended — it puts a
+  `basic-memory` binary on PATH, which the hooks call directly and which keeps the
+  hook version consistent with your MCP server.
 - Claude Code.
 
+### What the hooks execute
+
+The hook scripts are zero-logic shims: they resolve the Basic Memory CLI
+(`BM_BIN` override → `basic-memory` / `bm` on PATH → `uvx "basic-memory>=<floor>"`)
+and exec `basic-memory hook <event>` with the hook JSON on stdin. All behavior
+lives in the released Python package — versioned, typed, and tested. Two
+disclosures:
+
+- **Network fetch on first run.** When no binary is on PATH, the `uvx` fallback
+  downloads `basic-memory` from PyPI at a pinned minimum version (bumped by
+  release tooling); later runs use uv's cache.
+- **Event capture is opt-in and off by default.** Setting `captureEvents: true`
+  (the JSON boolean — strings never enable it) records redacted lifecycle-event
+  envelopes to a local inbox under your Basic Memory home. Inspect with
+  `basic-memory hook status`, project with `basic-memory hook flush`.
+
+If nothing is resolvable the shims exit silently — the plugin stays invisible
+when Basic Memory isn't installed.
+
 ## Installation
 
 ```bash
@@ -101,6 +124,7 @@ settings (or select it via `/config`).
 | `recallTimeframe` | `3d` | Recency window for the session brief |
 | `recallPrompt` | _(built-in)_ | The instruction appended to the brief |
 | `preCompactCapture` | `extractive` | How checkpoints are produced |
+| `captureEvents` | `false` | Opt-in: record redacted lifecycle-event envelopes to the local inbox (see `basic-memory hook status` / `flush`). Only the JSON boolean `true` enables it. |
 
 See [DESIGN.md](./DESIGN.md) for the complete configuration schema, the
 Claude-Code-project ↔ Basic-Memory-project mapping, and team-workspace behavior.