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

.gitattributes

@@ -0,0 +1,6 @@
+# Shell scripts must reach every checkout with LF endings. Marketplace plugin
+# installs are git clones, and Git for Windows defaults to core.autocrlf=true;
+# a CRLF-converted hook shim makes bash exit 2 with syntax errors on every
+# session start — breaking the hooks' fail-open contract exactly where the
+# uvx fallback is meant to protect users without a local install.
+*.sh text eol=lf

CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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 PEP 723 uv scripts (`uv run --script`) that
+  invoke `basic-memory hook` in-process; their dependency floor is bumped by
+  release tooling, and `BM_BIN` overrides the uv-managed environment for
+  development.
+
 ## 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

@@ -42,12 +42,12 @@ Memory's durable graph**, rather than a memory layer of its own. See
   plugin-namespaced commands (`/basic-memory:<name>`).
 
 
-- **SessionStart hook** (`hooks/session-start.sh`) — briefs Claude at session
+- **SessionStart hook** (`hooks/session_start.py`) — briefs Claude at session
   start with active tasks from the graph (one structured `type: task` query) plus
   an always-on recall prompt. Works against the default project with zero config;
   pin a project via `basicMemory.primaryProject`. Plain-stdout output, capped well
   under the 10k limit, and silent if Basic Memory isn't installed.
-- **PreCompact hook** (`hooks/pre-compact.sh`) — writes a `type: session`
+- **PreCompact hook** (`hooks/pre_compact.py`) — writes a `type: session`
   checkpoint to the graph before context compaction (extractive in this phase;
   LLM-summarized capture is the next step). Only writes when a `primaryProject` is
   configured, so it never touches a graph the user hasn't opted in.
@@ -62,6 +62,16 @@ Memory's durable graph**, rather than a memory layer of its own. See
 
 ### Changed
 
+- **Hooks are now zero-logic uv scripts** (SPEC-55, #997). `session_start.py`
+  and `pre_compact.py` are self-contained PEP 723 scripts run via
+  `uv run --quiet --script`: uv resolves `basic-memory>=<floor>` (floor bumped
+  by release tooling) and the script invokes
+  `basic-memory hook <event> --harness claude` in-process with the hook JSON
+  on stdin. `BM_BIN` overrides the uv-managed environment for development.
+  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 required prerequisite; the first run fetches from
+  PyPI, later runs use uv's cache.
 - **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/DESIGN.md

@@ -63,8 +63,8 @@ plugins/claude-code/
 │   ├── plugin.json
 │   └── marketplace.json
 ├── hooks/
-│   ├── session-start.sh        # ambient: brief Claude on what's relevant
-│   └── pre-compact.sh          # ambient: checkpoint before amnesia
+│   ├── session_start.py        # ambient: brief Claude on what's relevant
+│   └── pre_compact.py          # ambient: checkpoint before amnesia
 ├── output-styles/
 │   └── basic-memory.md         # reflexes: search first, capture decisions
 │                               # NOTE: rules/ deferred — path-scoped rules don't load yet (Q5)
@@ -476,10 +476,10 @@ eventual default is `"summarized"` — the LLM pass is the first enrich step.
   (`status?(enum, desc): [a,b]`), not after the `[...]` value — the latter is invalid
   YAML. (Same latent bug exists in the canonical `memory-tasks` schema → flagged as a
   separate task.)
-- [x] Write `hooks/session-start.sh` — plain-stdout brief, single `type: task` /
+- [x] Write `hooks/session_start.py` — plain-stdout brief, single `type: task` /
   `status: active` query, recall prompt; works against the default project (pin via
   `primaryProject`); silent if BM absent. Tested end-to-end.
-- [x] Write `hooks/pre-compact.sh` — **extractive** checkpoint conforming to the
+- [x] Write `hooks/pre_compact.py` — **extractive** checkpoint conforming to the
   `session` schema; only writes when `primaryProject` is set; silent/no-op otherwise.
   Tested end-to-end (note written + queryable by `--type session`).
 - [x] Write `output-styles/basic-memory.md` — reflexes; `keep-coding-instructions: true`

plugins/claude-code/README.md

@@ -45,13 +45,37 @@ 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/)** — required: the hooks are PEP 723
+  scripts executed via `uv run --script`. 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. The hooks resolve their own `basic-memory` through uv, so no
+  PATH install is required for them.
 - Claude Code.
 
+### What the hooks execute
+
+The hook scripts are zero-logic PEP 723 uv scripts: `uv run --quiet --script`
+resolves `basic-memory>=<floor>` (pinned in each script's inline metadata) and
+the script invokes `basic-memory hook <event>` in-process with the hook JSON
+on stdin. All behavior lives in the released Python package — versioned,
+typed, and tested. Setting `BM_BIN` (a binary path or a quoted launcher
+string) overrides the uv-managed environment, e.g. for development against a
+local checkout. Two disclosures:
+
+- **Network fetch on first run.** uv 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`.
+
+Every failure path exits 0 — the hooks stay invisible rather than disrupt a
+session.
+
 ## Installation
 
 ```bash
@@ -101,6 +125,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.

plugins/claude-code/docs/architecture.md

@@ -59,7 +59,7 @@ of Claude *before the first prompt*, so the session starts oriented instead of c
 ```mermaid
 sequenceDiagram
     participant CC as Claude Code
-    participant H as session-start.sh
+    participant H as session_start.py
     participant BM as Basic Memory (bm CLI)
     participant C as Claude
 
@@ -95,7 +95,7 @@ would be lost), the hook writes a durable checkpoint so the next session can res
 ```mermaid
 sequenceDiagram
     participant CC as Claude Code
-    participant H as pre-compact.sh
+    participant H as pre_compact.py
     participant BM as Basic Memory
 
     CC->>H: PreCompact (transcript_path, cwd)
@@ -157,7 +157,7 @@ project names collide across workspaces. Reads route over the user's OAuth sessi
 
 | Path | Role |
 |------|------|
-| `hooks/session-start.sh`, `hooks/pre-compact.sh` | the ambient bridge (read / write) |
+| `hooks/session_start.py`, `hooks/pre_compact.py` | the ambient bridge (read / write) |
 | `hooks/hooks.json` | registers the hooks |
 | `output-styles/basic-memory.md` | the capture reflexes |
 | `skills/{bm-setup,bm-remember,bm-share,bm-status}/` | the deliberate slash commands |

plugins/claude-code/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh",
+            "command": "uv run --quiet --script \"${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py\"",
             "timeout": 20,
             "statusMessage": "Briefing from Basic Memory"
           }
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.sh",
+            "command": "uv run --quiet --script \"${CLAUDE_PLUGIN_ROOT}/hooks/pre_compact.py\"",
             "timeout": 120,
             "statusMessage": "Checkpointing session to Basic Memory"
           }