@bli-cockpit/memory-mcp 0.1.0 → 0.1.2

package/dist/hooks/stop.js

@@ -0,0 +1,97 @@
+/**
+ * `bli-memory-mcp hook stop` (BLI-3580).
+ *
+ * Stop fires when a turn finishes. This hook is the only one that WRITES: it
+ * takes the last user/assistant exchange out of the transcript, masks anything
+ * secret-like, and hands it to `POST /api/memory/save` in `extract` mode — so
+ * the librarian (extract → reconcile) decides what, if anything, in that turn
+ * is worth keeping. Saving the exchange verbatim on every Stop would fill a
+ * container with conversation, which is the dump this repo refuses.
+ *
+ * Two guards, both from the host's own contract:
+ *
+ *  - `stop_hook_active: true` means Claude Code is running Stop as a result of
+ *    a Stop hook's own continuation. Calling save again there is a loop, and
+ *    the host publishes that flag precisely so a hook can refuse it. Exit 0,
+ *    nothing saved, `reentrant`.
+ *  - Nothing is printed on stdout, ever. Stop's stdout is shown to the person
+ *    in transcript mode, and "I saved a memory" on every turn is noise.
+ */
+import { createHash } from "node:crypto";
+import { doorReason, postMemoryDoor } from "../door.js";
+import { HOOK_BUDGETS } from "./contract.js";
+import { maskSecretsForMemory } from "./redact.js";
+import { readLastExchange } from "./transcript.js";
+export async function runStopHook(context, options = {}) {
+    const budget = HOOK_BUDGETS.stop;
+    if (context.payload.stop_hook_active === true) {
+        return { status: "skipped", reason: "reentrant", stdout: "", saved: 0 };
+    }
+    const transcriptPath = (context.payload.transcript_path ?? "").trim();
+    if (transcriptPath.length === 0) {
+        return { status: "skipped", reason: "no_transcript_path", stdout: "", saved: 0 };
+    }
+    const read = readLastExchange({
+        path: transcriptPath,
+        ...(options.readTail ? { readTail: options.readTail } : {}),
+    });
+    if (!read.ok) {
+        // Not a failure of ours and not a success: a session whose transcript has
+        // no completed exchange yet (a slash command, a cancelled turn) is normal.
+        return { status: "skipped", reason: read.reason, stdout: "", saved: 0 };
+    }
+    const masked = maskSecretsForMemory(read.exchange.text);
+    if (!masked.ok) {
+        return {
+            status: "failed",
+            reason: masked.reason ?? "redaction_failed",
+            stdout: "",
+            saved: 0,
+        };
+    }
+    const response = await postMemoryDoor({
+        session: context.session,
+        fetchImpl: context.fetchImpl,
+        path: "/api/memory/save",
+        body: {
+            containerTag: context.container.containerTag,
+            content: masked.text,
+            // The librarian decides what is worth keeping, and reconcile skips what
+            // the container already knows.
+            mode: "extract",
+            // One row per session rather than one per turn, matching the vendor
+            // plugin's `customId: <session id>`.
+            ...(context.payload.session_id ? { customId: context.payload.session_id } : {}),
+            sourceRef: {
+                kind: "claude_code_session",
+                session_id: context.payload.session_id ?? null,
+                // The workspace, identified without naming it: a cwd carries a home
+                // directory, and a home directory names a person.
+                cwd_hash: hashCwd(context.cwd),
+            },
+        },
+        timeoutMs: budget.requestMs,
+    });
+    if (!response.ok) {
+        return { status: "failed", reason: doorReason(response), stdout: "", saved: 0 };
+    }
+    const decisions = response.body["decisions"];
+    const written = Array.isArray(decisions)
+        ? decisions.filter((decision) => decision &&
+            typeof decision === "object" &&
+            decision["verb"] !== "skip").length
+        : response.body["id"]
+            ? 1
+            : 0;
+    return {
+        status: written > 0 ? "ok" : "empty",
+        reason: written > 0 ? String(response.body["outcome"] ?? "saved") : "nothing_worth_keeping",
+        stdout: "",
+        saved: written,
+        chars: masked.text.length,
+        masked: masked.masked,
+    };
+}
+function hashCwd(cwd) {
+    return createHash("sha256").update(cwd, "utf8").digest("hex").slice(0, 16);
+}

package/dist/hooks/transcript.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The last exchange out of a Claude Code transcript (BLI-3580).
+ *
+ * The Stop hook is handed `transcript_path`: a JSONL file, one record per line,
+ * appended to for the whole session. What the save door wants is the LAST
+ * user/assistant exchange — the turn that just finished — and nothing else.
+ *
+ * Everything here is bounded, in both directions:
+ *
+ *  - Only the **tail** of the file is read (`TAIL_BYTES`). A long session's
+ *    transcript is tens of megabytes; reading it whole on every Stop would cost
+ *    the hook its deadline and the machine its memory, to then throw away all
+ *    but the last two records.
+ *  - Only the last **12 KB of text** travels (`STOP_CHUNK_CHARS`), and the USER
+ *    side is kept whole in preference to the assistant's — a person's question
+ *    is what makes an assistant answer legible, and a truncated question is a
+ *    memory nobody can place.
+ *
+ * A record shape that is not recognised is skipped, never guessed at. The
+ * reader returns null rather than half an exchange: half a turn saved as a
+ * memory is a memory that says something the person did not.
+ */
+/** How much of the file's end is read. Big enough for a long final turn. */
+export declare const TAIL_BYTES: number;
+export interface LastExchange {
+    user: string;
+    assistant: string;
+    /** The chunk as it will be saved, already capped. */
+    text: string;
+}
+export interface ReadTranscriptOptions {
+    path: string;
+    tailBytes?: number;
+    maxChars?: number;
+    /** Injected in tests; reads the last `bytes` of `path`. */
+    readTail?: (path: string, bytes: number) => string;
+}
+export type ReadTranscriptResult = {
+    ok: true;
+    exchange: LastExchange;
+} | {
+    ok: false;
+    reason: "transcript_unreadable" | "transcript_no_exchange";
+};
+export declare function readLastExchange(options: ReadTranscriptOptions): ReadTranscriptResult;
+/**
+ * The user's turn whole, the assistant's trimmed to fit. Both labelled, because
+ * the extraction door reads this as a conversation chunk and needs to know who
+ * said which half.
+ */
+export declare function capExchange(user: string, assistant: string, maxChars: number): string;

package/dist/hooks/transcript.js

@@ -0,0 +1,169 @@
+/**
+ * The last exchange out of a Claude Code transcript (BLI-3580).
+ *
+ * The Stop hook is handed `transcript_path`: a JSONL file, one record per line,
+ * appended to for the whole session. What the save door wants is the LAST
+ * user/assistant exchange — the turn that just finished — and nothing else.
+ *
+ * Everything here is bounded, in both directions:
+ *
+ *  - Only the **tail** of the file is read (`TAIL_BYTES`). A long session's
+ *    transcript is tens of megabytes; reading it whole on every Stop would cost
+ *    the hook its deadline and the machine its memory, to then throw away all
+ *    but the last two records.
+ *  - Only the last **12 KB of text** travels (`STOP_CHUNK_CHARS`), and the USER
+ *    side is kept whole in preference to the assistant's — a person's question
+ *    is what makes an assistant answer legible, and a truncated question is a
+ *    memory nobody can place.
+ *
+ * A record shape that is not recognised is skipped, never guessed at. The
+ * reader returns null rather than half an exchange: half a turn saved as a
+ * memory is a memory that says something the person did not.
+ */
+import fs from "node:fs";
+import { STOP_CHUNK_CHARS } from "./contract.js";
+/** How much of the file's end is read. Big enough for a long final turn. */
+export const TAIL_BYTES = 512 * 1024;
+export function readLastExchange(options) {
+    let raw;
+    try {
+        raw = (options.readTail ?? readFileTail)(options.path, options.tailBytes ?? TAIL_BYTES);
+    }
+    catch {
+        return { ok: false, reason: "transcript_unreadable" };
+    }
+    const records = parseJsonlTail(raw);
+    // Walk backwards: the last assistant message, then the last user message
+    // BEFORE it. A user message after the assistant's is the next turn starting,
+    // which is not what just finished.
+    let assistantIndex = -1;
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        if (roleOf(records[index]) === "assistant" && textOf(records[index]).length > 0) {
+            assistantIndex = index;
+            break;
+        }
+    }
+    if (assistantIndex < 0)
+        return { ok: false, reason: "transcript_no_exchange" };
+    let userIndex = -1;
+    for (let index = assistantIndex - 1; index >= 0; index -= 1) {
+        if (roleOf(records[index]) === "user" && textOf(records[index]).length > 0) {
+            userIndex = index;
+            break;
+        }
+    }
+    if (userIndex < 0)
+        return { ok: false, reason: "transcript_no_exchange" };
+    const user = textOf(records[userIndex]);
+    const assistant = textOf(records[assistantIndex]);
+    return {
+        ok: true,
+        exchange: {
+            user,
+            assistant,
+            text: capExchange(user, assistant, options.maxChars ?? STOP_CHUNK_CHARS),
+        },
+    };
+}
+/**
+ * The user's turn whole, the assistant's trimmed to fit. Both labelled, because
+ * the extraction door reads this as a conversation chunk and needs to know who
+ * said which half.
+ */
+export function capExchange(user, assistant, maxChars) {
+    const userBlock = `User: ${user.trim()}`;
+    const label = "\n\nAssistant: ";
+    const room = maxChars - userBlock.length - label.length;
+    if (room <= 0) {
+        // A single question longer than the whole budget: keep its END, which is
+        // where the actual ask usually is, and say it was cut.
+        return `User (truncated): …${user.trim().slice(-Math.max(maxChars - 24, 0))}`;
+    }
+    const assistantText = assistant.trim();
+    const kept = assistantText.length > room ? `${assistantText.slice(0, room - 1)}…` : assistantText;
+    return `${userBlock}${label}${kept}`;
+}
+function readFileTail(path, bytes) {
+    const handle = fs.openSync(path, "r");
+    try {
+        const size = fs.fstatSync(handle).size;
+        const length = Math.min(size, bytes);
+        const start = size - length;
+        const buffer = Buffer.alloc(length);
+        fs.readSync(handle, buffer, 0, length, start);
+        return buffer.toString("utf8");
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}
+/**
+ * Every whole line that parses. The FIRST line of a tail read is usually half a
+ * record — it is dropped by failing to parse, which is the correct outcome and
+ * needs no special case.
+ */
+function parseJsonlTail(raw) {
+    const records = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return records;
+}
+function roleOf(record) {
+    if (!record)
+        return "";
+    const message = record["message"];
+    if (message && typeof message === "object" && !Array.isArray(message)) {
+        const role = message["role"];
+        if (typeof role === "string")
+            return role;
+    }
+    const type = record["type"];
+    return typeof type === "string" ? type : "";
+}
+/**
+ * The text of a record, whichever of the three shapes it uses: a string
+ * `content`, an array of blocks with `type: "text"`, or a bare `text`. A tool
+ * result or an image block contributes nothing, on purpose — a memory made of
+ * tool output is the transcript dump this repo refuses.
+ */
+function textOf(record) {
+    if (!record)
+        return "";
+    const message = record["message"];
+    const source = message && typeof message === "object" && !Array.isArray(message)
+        ? message
+        : record;
+    const content = source["content"] ?? source["text"];
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === "string") {
+            parts.push(block);
+            continue;
+        }
+        if (!block || typeof block !== "object")
+            continue;
+        const record_ = block;
+        if (record_["type"] !== "text")
+            continue;
+        const text = record_["text"];
+        if (typeof text === "string")
+            parts.push(text);
+    }
+    return parts.join("\n").trim();
+}

package/dist/index.d.ts

@@ -10,9 +10,18 @@
  * Usage:
  *   bli-memory-mcp                          run the server over stdio
  *   bli-memory-mcp --print-config           both host blocks
- *   bli-memory-mcp --print-config --claude  the Claude Code JSON block
+ *   bli-memory-mcp --print-config --claude  the Claude Code install block
  *   bli-memory-mcp --print-config --codex   the Codex TOML block
  *   bli-memory-mcp --print-config=claude    the same, as one token
+ *   bli-memory-mcp hook session-start       the SessionStart hook
+ *   bli-memory-mcp hook prompt              the UserPromptSubmit hook
+ *   bli-memory-mcp hook stop                the Stop hook
+ *
+ * The three `hook` subcommands are what `cockpit memory install` registers with
+ * Claude Code. Each reads the host's JSON payload on stdin, prints either one
+ * context block or NOTHING, logs one metadata line to stderr, and **always
+ * exits 0** — see `hooks/contract.ts` for the budgets and why a hook may never
+ * block or fail loudly.
  *
  * Both spellings are accepted deliberately. `cockpit memory install`
  * (BLI-3580's installer slice) spawns this with separate flags; a person

package/dist/index.js

@@ -10,9 +10,18 @@
  * Usage:
  *   bli-memory-mcp                          run the server over stdio
  *   bli-memory-mcp --print-config           both host blocks
- *   bli-memory-mcp --print-config --claude  the Claude Code JSON block
+ *   bli-memory-mcp --print-config --claude  the Claude Code install block
  *   bli-memory-mcp --print-config --codex   the Codex TOML block
  *   bli-memory-mcp --print-config=claude    the same, as one token
+ *   bli-memory-mcp hook session-start       the SessionStart hook
+ *   bli-memory-mcp hook prompt              the UserPromptSubmit hook
+ *   bli-memory-mcp hook stop                the Stop hook
+ *
+ * The three `hook` subcommands are what `cockpit memory install` registers with
+ * Claude Code. Each reads the host's JSON payload on stdin, prints either one
+ * context block or NOTHING, logs one metadata line to stderr, and **always
+ * exits 0** — see `hooks/contract.ts` for the budgets and why a hook may never
+ * block or fail loudly.
  *
  * Both spellings are accepted deliberately. `cockpit memory install`
  * (BLI-3580's installer slice) spawns this with separate flags; a person
@@ -25,14 +34,30 @@
  * `BLI_MEMORY_DASHBOARD_URL`, `BLI_MEMORY_CONTAINER_TAG`,
  * `BLI_MEMORY_ISOLATE_WORKTREES=1`.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { resolveContainerTag } from "./container-tag.js";
-import { parseFormat, printConfig } from "./print-config.js";
-import { createServer, SERVER_NAME } from "./server.js";
+import { HOOK_EVENTS, hookEventFromArgv } from "./hooks/contract.js";
+import { runHook } from "./hooks/run.js";
+import { MEMORY_MCP_BIN, parseFormat, printConfig, SERVER_NAME, } from "./print-config.js";
 import { loadMemorySession } from "./session.js";
 const TAG = "[bli-memory-mcp]";
 async function main() {
     const argv = process.argv.slice(2);
+    // The hook path is checked FIRST and never falls through. Before this
+    // existed, `hook prompt` matched nothing here and started the stdio MCP
+    // server, which waits on stdin forever — so every registered hook on every
+    // machine hung until its host killed it (BLI-3580, observed on CLI 0.2.50).
+    if (argv[0] === "hook") {
+        const event = hookEventFromArgv(argv.slice(1));
+        if (!event) {
+            process.stderr.write(`${TAG} unknown hook event — one of ${HOOK_EVENTS.join(", ")}\n`);
+            // Still 0: a host reading a stale config must not see a hook error.
+            await exitQuietly();
+            return;
+        }
+        await runHook(event);
+        await exitQuietly();
+        return;
+    }
     const format = parseFormat(argv);
     if (format === "invalid") {
         process.stderr.write(`${TAG} unknown --print-config value — use claude, codex, or omit it for both\n`);
@@ -42,8 +67,11 @@ async function main() {
         // The one thing that goes to stdout besides the protocol: an installer
         // pipes this straight into a config file.
         process.stdout.write(`${printConfig(format, {
-            command: "npx",
-            args: ["-y", "@bli-cockpit/memory-mcp"],
+            // The BIN, never `npx`: an `npx -y` launch would re-resolve the package
+            // from the registry on every agent start, and `cockpit memory install`
+            // substitutes the absolute path it resolved on this machine.
+            command: MEMORY_MCP_BIN,
+            args: [],
             serverName: SERVER_NAME,
         })}\n`);
         return;
@@ -58,6 +86,15 @@ async function main() {
     // host, where the credential came from. Never the token, never a path.
     process.stderr.write(`${TAG} ready — container ${container.containerTag} (${container.basis}), ` +
         `dashboard ${session.session.dashboardUrl}, auth ${session.session.source}\n`);
+    // The MCP SDK is loaded HERE and nowhere else. A static import at the top of
+    // this file made every hook run — one per prompt, on every machine — load the
+    // whole SDK and its schemas before it could ask a single question, and it
+    // also made `--print-config` fail outright on an install whose SDK was
+    // missing. Only the server branch needs it.
+    const [{ StdioServerTransport }, { createServer }] = await Promise.all([
+        import("@modelcontextprotocol/sdk/server/stdio.js"),
+        import("./server.js"),
+    ]);
     const server = createServer({
         session: session.session,
         fetchImpl: globalThis.fetch,
@@ -65,6 +102,37 @@ async function main() {
     });
     await server.connect(new StdioServerTransport());
 }
+/**
+ * Exit now, without waiting for anything still in flight.
+ *
+ * A hook that has printed its answer must give the host its process back: an
+ * in-flight `fetch` would otherwise hold the event loop until its own abort
+ * fires, and the host counts that against the hook's timeout. stdout is drained
+ * first — `process.exit` truncates a pending pipe write, and a truncated
+ * injection block is worse than no injection.
+ */
+async function exitQuietly() {
+    process.stdin.pause();
+    await drain(process.stdout);
+    await drain(process.stderr);
+    process.exit(0);
+}
+function drain(stream) {
+    return new Promise((resolve) => {
+        if (stream.writableLength === 0) {
+            resolve();
+            return;
+        }
+        // A 250 ms ceiling: a blocked stdout may never drain, and hanging here
+        // would reintroduce exactly the hang this file exists to remove.
+        const timer = setTimeout(resolve, 250);
+        timer.unref?.();
+        stream.write("", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
 main().catch((error) => {
     process.stderr.write(`${TAG} fatal: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(1);

package/dist/print-config.d.ts

@@ -2,18 +2,32 @@
  * `bli-memory-mcp --print-config` — the exact block each host wants
  * (BLI-3580).
  *
- * A third slice of this ticket builds `cockpit memory install`, which registers
- * this server on every machine, for Claude Code and for Codex. That installer
- * must not hand-assemble JSON or TOML from a template it maintains separately —
- * that is how the two drift and how a fleet ends up half-registered. It reads
- * THESE strings verbatim, and so does a person doing it by hand.
+ * `cockpit memory install` registers this server on every machine, for Claude
+ * Code and for Codex. That installer must not hand-assemble JSON or TOML from a
+ * template it maintains separately — that is how the two drift and how a fleet
+ * ends up half-registered. It reads THESE strings verbatim, and so does a
+ * person doing it by hand.
  *
  * Two hosts, two formats, one server:
  *
- *   claude → the `mcpServers` entry for `~/.claude.json` (project or global) or
- *            a plugin's `.mcp.json`. Claude Code speaks stdio here.
+ *   claude → the INSTALLER CONTRACT, `bli-memory-install-config.v1`: the MCP
+ *            server entry plus the three hooks and their timeouts, which is
+ *            what `parsePrintedMemoryInstallConfig`
+ *            (`collector/commands/memory-install-contract.ts`) reads. It is
+ *            deliberately NOT Claude's raw `mcpServers` object: the hooks have
+ *            to travel with the server entry, and this bin is the only thing
+ *            that knows which hook subcommands it implements. Printing the raw
+ *            `mcpServers` shape is what made every machine fall back to the
+ *            installer's built-in template (`bin_present_template_used`) on
+ *            0.1.0.
  *   codex  → the `[mcp_servers.bli-memory]` block for `~/.codex/config.toml`.
  *
+ * `command` is the bare bin name in both. The installer substitutes the
+ * absolute path it resolved on that machine; a person copying the block by hand
+ * gets whatever is on their PATH. It is never `npx -y @bli-cockpit/memory-mcp`,
+ * which would re-resolve the package from the registry on every agent launch
+ * on every intern's machine.
+ *
  * The stdio contract, stated once because both installers depend on it:
  * **stdout is the MCP protocol channel and carries nothing else.** Every
  * operational line — the startup banner, an auth failure, a warning — goes to
@@ -29,6 +43,47 @@ export interface PrintConfigOptions {
     env?: Record<string, string>;
 }
 export type ConfigFormat = "claude" | "codex" | "both";
+/** The published bin name. Both hosts spawn this; the installer path-qualifies it. */
+export declare const MEMORY_MCP_BIN = "bli-memory-mcp";
+/**
+ * The server id an MCP client registers, and the `mcp__<server>__<tool>` prefix.
+ *
+ * It lives HERE rather than in `server.ts` on purpose: `index.ts` needs it for
+ * `--print-config` and for the hook receipts, and `server.ts` pulls in the whole
+ * MCP SDK. Importing it from there made every hook run load the SDK before it
+ * could do anything, on the one hook a person is waiting for. `server.ts`
+ * re-exports it, so nothing that already imports it from there had to change.
+ */
+export declare const SERVER_NAME = "bli-memory";
+/** The installer contract's schema id, printed so a reader can pin it. */
+export declare const INSTALL_CONFIG_SCHEMA = "bli-memory-install-config.v1";
+/**
+ * The three Claude Code hooks, their subcommands and their HOST timeouts, in
+ * the order the installer writes them.
+ *
+ * A host timeout is not the hook's own deadline: each hook budgets itself well
+ * below its timeout and abandons the work rather than being killed
+ * (`hooks/contract.ts`). These numbers are the outer bound, and they mirror the
+ * vendor plugin's own budgets.
+ */
+export declare const INSTALL_HOOKS: readonly [{
+    readonly event: "SessionStart";
+    readonly subcommand: "hook session-start";
+    readonly timeout_seconds: 30;
+}, {
+    readonly event: "UserPromptSubmit";
+    readonly subcommand: "hook prompt";
+    readonly timeout_seconds: 5;
+}, {
+    readonly event: "Stop";
+    readonly subcommand: "hook stop";
+    readonly timeout_seconds: 30;
+}];
+/**
+ * Auto-approved tools. READ ONLY, deliberately: a memory the agent can
+ * silently overwrite is worse than one it has to ask about.
+ */
+export declare function autoApproveTools(serverName: string): string[];
 export declare function claudeConfigBlock(options: PrintConfigOptions): string;
 export declare function codexConfigBlock(options: PrintConfigOptions): string;
 export declare function printConfig(format: ConfigFormat, options: PrintConfigOptions): string;

package/dist/print-config.js

@@ -2,32 +2,100 @@
  * `bli-memory-mcp --print-config` — the exact block each host wants
  * (BLI-3580).
  *
- * A third slice of this ticket builds `cockpit memory install`, which registers
- * this server on every machine, for Claude Code and for Codex. That installer
- * must not hand-assemble JSON or TOML from a template it maintains separately —
- * that is how the two drift and how a fleet ends up half-registered. It reads
- * THESE strings verbatim, and so does a person doing it by hand.
+ * `cockpit memory install` registers this server on every machine, for Claude
+ * Code and for Codex. That installer must not hand-assemble JSON or TOML from a
+ * template it maintains separately — that is how the two drift and how a fleet
+ * ends up half-registered. It reads THESE strings verbatim, and so does a
+ * person doing it by hand.
  *
  * Two hosts, two formats, one server:
  *
- *   claude → the `mcpServers` entry for `~/.claude.json` (project or global) or
- *            a plugin's `.mcp.json`. Claude Code speaks stdio here.
+ *   claude → the INSTALLER CONTRACT, `bli-memory-install-config.v1`: the MCP
+ *            server entry plus the three hooks and their timeouts, which is
+ *            what `parsePrintedMemoryInstallConfig`
+ *            (`collector/commands/memory-install-contract.ts`) reads. It is
+ *            deliberately NOT Claude's raw `mcpServers` object: the hooks have
+ *            to travel with the server entry, and this bin is the only thing
+ *            that knows which hook subcommands it implements. Printing the raw
+ *            `mcpServers` shape is what made every machine fall back to the
+ *            installer's built-in template (`bin_present_template_used`) on
+ *            0.1.0.
  *   codex  → the `[mcp_servers.bli-memory]` block for `~/.codex/config.toml`.
  *
+ * `command` is the bare bin name in both. The installer substitutes the
+ * absolute path it resolved on that machine; a person copying the block by hand
+ * gets whatever is on their PATH. It is never `npx -y @bli-cockpit/memory-mcp`,
+ * which would re-resolve the package from the registry on every agent launch
+ * on every intern's machine.
+ *
  * The stdio contract, stated once because both installers depend on it:
  * **stdout is the MCP protocol channel and carries nothing else.** Every
  * operational line — the startup banner, an auth failure, a warning — goes to
  * stderr. A single stray `console.log` here corrupts the JSON-RPC stream and
  * the host reports a server that "does not work" with no reason attached.
  */
+/** The published bin name. Both hosts spawn this; the installer path-qualifies it. */
+export const MEMORY_MCP_BIN = "bli-memory-mcp";
+/**
+ * The server id an MCP client registers, and the `mcp__<server>__<tool>` prefix.
+ *
+ * It lives HERE rather than in `server.ts` on purpose: `index.ts` needs it for
+ * `--print-config` and for the hook receipts, and `server.ts` pulls in the whole
+ * MCP SDK. Importing it from there made every hook run load the SDK before it
+ * could do anything, on the one hook a person is waiting for. `server.ts`
+ * re-exports it, so nothing that already imports it from there had to change.
+ */
+export const SERVER_NAME = "bli-memory";
+/** The installer contract's schema id, printed so a reader can pin it. */
+export const INSTALL_CONFIG_SCHEMA = "bli-memory-install-config.v1";
+/**
+ * The three Claude Code hooks, their subcommands and their HOST timeouts, in
+ * the order the installer writes them.
+ *
+ * A host timeout is not the hook's own deadline: each hook budgets itself well
+ * below its timeout and abandons the work rather than being killed
+ * (`hooks/contract.ts`). These numbers are the outer bound, and they mirror the
+ * vendor plugin's own budgets.
+ */
+export const INSTALL_HOOKS = [
+    { event: "SessionStart", subcommand: "hook session-start", timeout_seconds: 30 },
+    { event: "UserPromptSubmit", subcommand: "hook prompt", timeout_seconds: 5 },
+    { event: "Stop", subcommand: "hook stop", timeout_seconds: 30 },
+];
+/**
+ * Auto-approved tools. READ ONLY, deliberately: a memory the agent can
+ * silently overwrite is worse than one it has to ask about.
+ */
+export function autoApproveTools(serverName) {
+    return [`mcp__${serverName}__search_memory`];
+}
 export function claudeConfigBlock(options) {
     const entry = {
         command: options.command,
         args: options.args,
+        env: options.env ?? {},
     };
-    if (options.env && Object.keys(options.env).length > 0)
-        entry.env = options.env;
-    return JSON.stringify({ mcpServers: { [options.serverName]: entry } }, null, 2);
+    return JSON.stringify({
+        schema: INSTALL_CONFIG_SCHEMA,
+        server_id: options.serverName,
+        mcp_server: entry,
+        hooks: INSTALL_HOOKS.map((hook) => ({
+            event: hook.event,
+            command: `${quoteCommandPath(options.command)} ${hook.subcommand}`,
+            timeout_seconds: hook.timeout_seconds,
+        })),
+        permissions_allow: autoApproveTools(options.serverName),
+    }, null, 2);
+}
+/**
+ * A Claude Code hook `command` is a shell string by the platform's design, so a
+ * path with a space in it is quoted. The installer refuses a path that could
+ * not be quoted safely rather than escaping it cleverly (`isUnsafeBinPath`),
+ * and it re-quotes whatever it substitutes — this is for the person who copies
+ * the printed block by hand.
+ */
+function quoteCommandPath(command) {
+    return /\s/u.test(command) ? `"${command}"` : command;
 }
 export function codexConfigBlock(options) {
     const lines = [
@@ -49,7 +117,9 @@ export function printConfig(format, options) {
     if (format === "codex")
         return codexConfigBlock(options);
     return [
-        "# Claude Code — merge into ~/.claude.json (or a plugin's .mcp.json)",
+        "# Claude Code — the install contract `cockpit memory install` consumes.",
+        "# By hand: mcp_server goes under `mcpServers.bli-memory` in ~/.claude.json,",
+        "# and each hook under `hooks.<event>` in ~/.claude/settings.json.",
         claudeConfigBlock(options),
         "",
         "# Codex — append to ~/.codex/config.toml",