@vibe-commit/capture 0.1.0 → 0.2.0

package/dist/agent_hooks.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Registering our hook in an AGENT's own config — `CR-195`, D205.
+ *
+ * ⛔ **THIS IS NOT `install.ts`'s CHAINING, AND THE DIFFERENCE IS THE CONTAINER,
+ * NOT THE RULE.** The rule is the same one D154 settled for git hooks — *never
+ * clobber; whatever was there keeps working*. The MECHANISM cannot be the same:
+ *
+ *   - `.git/hooks/post-commit` is a **single-slot executable file**. One path,
+ *     one script, no way for two owners to coexist — so `writeHook` renames the
+ *     incumbent aside and invokes it explicitly. That is the only move available.
+ *   - `~/.claude/settings.json` is a **multi-slot document**, and `hooks.Stop`
+ *     is an ARRAY that already expresses coexistence natively.
+ *
+ * ⛔ **So renaming here would be catastrophic rather than conservative.** That
+ * file holds the user's model, permissions, enabled plugins, marketplaces and
+ * theme; moving it aside to write our own would delete all of it, and on a
+ * machine with an existing `Stop` hook it would fire on the very first
+ * `connect`. The faithful translation of *never clobber* into this container is
+ * **append into the array and leave every other byte alone**.
+ *
+ * ## The three rules, and what each one is defending against
+ *
+ *   1. **APPEND, never replace.** A foreign entry is never removed, rewritten or
+ *      reordered. Ours goes last.
+ *   2. **IDEMPOTENT via a marker.** JSON has nowhere to put a comment, so ours
+ *      carries `_vibecommit`. Without it, `connect` run twice appends twice and
+ *      the hook fires twice per event — two processes racing on one session
+ *      state file. ⚠ The marker field is TOLERATED by all three readers, and
+ *      that is measured rather than assumed: Codex parses and clamps with the
+ *      field present on the inner and outer object alike, and Cursor's validator
+ *      checks only known members (`HWu`/`jWu`/`$Wu` in its bundle).
+ *   3. ⛔ **REFUSE on unparseable, never overwrite.** A file we could not read is
+ *      a file whose contents we cannot preserve. Overwriting it would be the
+ *      destructive outcome wearing a success message — the exact defect class
+ *      this whole unit exists to delete. Fail-closed, the same direction as
+ *      `install.ts`'s `core.hooksPath` refusal.
+ *
+ * ## ⛔ TWO DOCUMENT SHAPES, MEASURED — they are NOT interchangeable
+ *
+ * The brief recorded all three agents as "identical to Claude Code". That is
+ * true of the STDIN payload and false of the CONFIG document:
+ *
+ * | | `claude` shape | `cursor` shape |
+ * |---|---|---|
+ * | used by | Claude Code, Codex CLI | Cursor |
+ * | top-level `version` | absent | ⛔ REQUIRED positive integer |
+ * | entry | `[{ hooks: [{ type, command, timeout }] }]` | ⛔ flat `[{ command, timeout }]` |
+ * | unknown event key | ignored | ⛔ validation ERROR |
+ *
+ * Cursor's is read out of its shipped bundle (`parseAndValidateHooksConfig` →
+ * `M6s` → `zWu` → `HWu`), which rejects a document with no numeric `version`
+ * outright. Codex's is MEASURED: a probe wrote the `claude` shape to a throwaway
+ * `CODEX_HOME` and Codex parsed it, recognised the event and clamped the
+ * timeout — which it could only do having read the inner entry.
+ *
+ * ⚠ **Writing the wrong shape does not error.** It produces a file that parses,
+ * registers nothing, and reports success — the same matches-nothing failure as
+ * an unrecognised event name, relocated to the document level.
+ */
+/**
+ * What marks an entry as ours.
+ *
+ * ⚠ **A FIELD, not a substring of the command.** Matching on the command text
+ * would claim a user's own hook that happens to mention this product, and would
+ * lose track of ours the moment the binary path changed — which is exactly when
+ * idempotence matters, because that is a re-`connect`.
+ */
+export declare const AGENT_HOOK_MARKER = "vibecommit-capture-hook v1";
+/** Which document shape an agent's hook config uses. See the module docblock. */
+export type HookDocShape = "claude" | "cursor";
+/** One event we want registered, already in the agent's own vocabulary. */
+export interface HookRegistration {
+    /** The agent's OWN spelling — `SessionEnd` or `sessionEnd`, never canonical. */
+    readonly event: string;
+    readonly command: string;
+    /** ⛔ SECONDS. Every one of the three configs is in seconds; our budgets are ms. */
+    readonly timeoutSec: number;
+}
+export type MergeOutcome = {
+    readonly kind: "merged";
+    readonly text: string;
+    /** Events where ours was newly appended. */
+    readonly added: readonly string[];
+    /** Events where ours was already present and was refreshed. */
+    readonly updated: readonly string[];
+    /** Foreign entries left untouched beside ours, across all events. */
+    readonly foreign: number;
+}
+/** ⛔ The document exists and could not be read. NOTHING is written. */
+ | {
+    readonly kind: "refused";
+    readonly why: string;
+};
+/**
+ * ⛔ **THE WHOLE MERGE, AS A PURE FUNCTION ON TEXT.**
+ *
+ * `raw` is the file's current contents, or `null` when it does not exist. No fs,
+ * no `home`, no clock — so the semantics that matter can be driven by a test
+ * without a temp directory, and the writer below is left with nothing but I/O.
+ * That split is deliberate: every rule in the module docblock is a property of
+ * this function, and none of them needs a real `~/.claude` to check.
+ */
+export declare function mergeHookDocument(raw: string | null, shape: HookDocShape, registrations: readonly HookRegistration[]): MergeOutcome;
+export type AgentHookInstall = {
+    readonly kind: "installed";
+    readonly path: string;
+    readonly events: readonly string[];
+} | {
+    readonly kind: "already";
+    readonly path: string;
+    readonly events: readonly string[];
+} | {
+    readonly kind: "refused";
+    readonly path: string;
+    readonly why: string;
+} | {
+    readonly kind: "failed";
+    readonly path: string;
+    readonly why: string;
+};
+/**
+ * Merge our registrations into `path` and write it back.
+ *
+ * ⚠ **Written through a temp file in the same directory, then renamed.** A
+ * partial write here is the user's settings truncated, and `rename(2)` within a
+ * directory is atomic — so a crash mid-write leaves the original intact rather
+ * than a half-document that the next run would then REFUSE to touch, locking
+ * the user out of their own config.
+ *
+ * ⚠ The file's existing mode is preserved when there is one. A settings file
+ * the user tightened to `0600` must not be widened by us having rewritten it.
+ */
+export declare function writeAgentHooks(path: string, shape: HookDocShape, registrations: readonly HookRegistration[]): AgentHookInstall;

package/dist/agent_hooks.js

@@ -0,0 +1,228 @@
+/**
+ * Registering our hook in an AGENT's own config — `CR-195`, D205.
+ *
+ * ⛔ **THIS IS NOT `install.ts`'s CHAINING, AND THE DIFFERENCE IS THE CONTAINER,
+ * NOT THE RULE.** The rule is the same one D154 settled for git hooks — *never
+ * clobber; whatever was there keeps working*. The MECHANISM cannot be the same:
+ *
+ *   - `.git/hooks/post-commit` is a **single-slot executable file**. One path,
+ *     one script, no way for two owners to coexist — so `writeHook` renames the
+ *     incumbent aside and invokes it explicitly. That is the only move available.
+ *   - `~/.claude/settings.json` is a **multi-slot document**, and `hooks.Stop`
+ *     is an ARRAY that already expresses coexistence natively.
+ *
+ * ⛔ **So renaming here would be catastrophic rather than conservative.** That
+ * file holds the user's model, permissions, enabled plugins, marketplaces and
+ * theme; moving it aside to write our own would delete all of it, and on a
+ * machine with an existing `Stop` hook it would fire on the very first
+ * `connect`. The faithful translation of *never clobber* into this container is
+ * **append into the array and leave every other byte alone**.
+ *
+ * ## The three rules, and what each one is defending against
+ *
+ *   1. **APPEND, never replace.** A foreign entry is never removed, rewritten or
+ *      reordered. Ours goes last.
+ *   2. **IDEMPOTENT via a marker.** JSON has nowhere to put a comment, so ours
+ *      carries `_vibecommit`. Without it, `connect` run twice appends twice and
+ *      the hook fires twice per event — two processes racing on one session
+ *      state file. ⚠ The marker field is TOLERATED by all three readers, and
+ *      that is measured rather than assumed: Codex parses and clamps with the
+ *      field present on the inner and outer object alike, and Cursor's validator
+ *      checks only known members (`HWu`/`jWu`/`$Wu` in its bundle).
+ *   3. ⛔ **REFUSE on unparseable, never overwrite.** A file we could not read is
+ *      a file whose contents we cannot preserve. Overwriting it would be the
+ *      destructive outcome wearing a success message — the exact defect class
+ *      this whole unit exists to delete. Fail-closed, the same direction as
+ *      `install.ts`'s `core.hooksPath` refusal.
+ *
+ * ## ⛔ TWO DOCUMENT SHAPES, MEASURED — they are NOT interchangeable
+ *
+ * The brief recorded all three agents as "identical to Claude Code". That is
+ * true of the STDIN payload and false of the CONFIG document:
+ *
+ * | | `claude` shape | `cursor` shape |
+ * |---|---|---|
+ * | used by | Claude Code, Codex CLI | Cursor |
+ * | top-level `version` | absent | ⛔ REQUIRED positive integer |
+ * | entry | `[{ hooks: [{ type, command, timeout }] }]` | ⛔ flat `[{ command, timeout }]` |
+ * | unknown event key | ignored | ⛔ validation ERROR |
+ *
+ * Cursor's is read out of its shipped bundle (`parseAndValidateHooksConfig` →
+ * `M6s` → `zWu` → `HWu`), which rejects a document with no numeric `version`
+ * outright. Codex's is MEASURED: a probe wrote the `claude` shape to a throwaway
+ * `CODEX_HOME` and Codex parsed it, recognised the event and clamped the
+ * timeout — which it could only do having read the inner entry.
+ *
+ * ⚠ **Writing the wrong shape does not error.** It produces a file that parses,
+ * registers nothing, and reports success — the same matches-nothing failure as
+ * an unrecognised event name, relocated to the document level.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * What marks an entry as ours.
+ *
+ * ⚠ **A FIELD, not a substring of the command.** Matching on the command text
+ * would claim a user's own hook that happens to mention this product, and would
+ * lose track of ours the moment the binary path changed — which is exactly when
+ * idempotence matters, because that is a re-`connect`.
+ */
+export const AGENT_HOOK_MARKER = "vibecommit-capture-hook v1";
+/** The field carrying it. Leading underscore: a hint that it is not the agent's. */
+const MARKER_KEY = "_vibecommit";
+/** The `version` we mint when CREATING a `cursor` document. */
+const CURSOR_CONFIG_VERSION = 1;
+/**
+ * ⛔ **THE WHOLE MERGE, AS A PURE FUNCTION ON TEXT.**
+ *
+ * `raw` is the file's current contents, or `null` when it does not exist. No fs,
+ * no `home`, no clock — so the semantics that matter can be driven by a test
+ * without a temp directory, and the writer below is left with nothing but I/O.
+ * That split is deliberate: every rule in the module docblock is a property of
+ * this function, and none of them needs a real `~/.claude` to check.
+ */
+export function mergeHookDocument(raw, shape, registrations) {
+    let doc;
+    if (raw === null || raw.trim() === "") {
+        doc = {};
+    }
+    else {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            // ⛔ RULE 3. We hold the user's settings in our hands here; a parse we do
+            // not understand is not permission to replace them.
+            return {
+                kind: "refused",
+                why: error instanceof Error ? error.message : "not valid JSON",
+            };
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { kind: "refused", why: "the document is not a JSON object" };
+        }
+        doc = { ...parsed };
+    }
+    // ⛔ MINTED ONLY ON CREATE. An existing `version` is the user's (or another
+    // tool's) and is left exactly as found — bumping someone else's schema version
+    // is the same class of act as renaming their settings file, in a smaller hat.
+    if (shape === "cursor" && doc.version === undefined) {
+        doc.version = CURSOR_CONFIG_VERSION;
+    }
+    const existingHooks = doc.hooks;
+    if (existingHooks !== undefined) {
+        if (existingHooks === null || typeof existingHooks !== "object" || Array.isArray(existingHooks)) {
+            // Present and not an object: we cannot merge into it without destroying it.
+            return { kind: "refused", why: "`hooks` is present but is not an object" };
+        }
+    }
+    const hooks = {
+        ...(existingHooks ?? {}),
+    };
+    const added = [];
+    const updated = [];
+    let foreign = 0;
+    for (const registration of registrations) {
+        const current = hooks[registration.event];
+        if (current !== undefined && !Array.isArray(current)) {
+            return {
+                kind: "refused",
+                why: `\`hooks.${registration.event}\` is present but is not an array`,
+            };
+        }
+        const entries = [...(current ?? [])];
+        const ours = entryFor(shape, registration);
+        const at = entries.findIndex(isOurs);
+        if (at >= 0) {
+            // ⛔ REFRESH IN PLACE, and the position is kept. The binary path moves on
+            // every reinstall, so this arm is the ordinary one on a re-`connect` — and
+            // appending instead would grow the array without bound.
+            entries[at] = ours;
+            updated.push(registration.event);
+        }
+        else {
+            entries.push(ours);
+            added.push(registration.event);
+        }
+        foreign += entries.filter((entry) => !isOurs(entry)).length;
+        hooks[registration.event] = entries;
+    }
+    doc.hooks = hooks;
+    return { kind: "merged", text: `${JSON.stringify(doc, null, 2)}\n`, added, updated, foreign };
+}
+/** Ours? ⛔ By the marker alone — never by the command, which changes. */
+function isOurs(entry) {
+    return (entry !== null &&
+        typeof entry === "object" &&
+        !Array.isArray(entry) &&
+        entry[MARKER_KEY] === AGENT_HOOK_MARKER);
+}
+/** Our entry, in the shape that agent's reader actually validates. */
+function entryFor(shape, registration) {
+    if (shape === "cursor") {
+        // ⛔ FLAT. `zWu` validates `hooks[event]` as an array of hook SCRIPTS, and
+        // `HWu` requires a `command` on each — so a nested `{ hooks: [...] }` object
+        // is rejected outright for having none.
+        return {
+            [MARKER_KEY]: AGENT_HOOK_MARKER,
+            command: registration.command,
+            timeout: registration.timeoutSec,
+        };
+    }
+    // ⛔ NESTED, and `matcher` is deliberately omitted rather than set to `"*"` —
+    // these three events carry no tool name to match on, and the plugin's own
+    // `hooks.json` omits it too.
+    return {
+        [MARKER_KEY]: AGENT_HOOK_MARKER,
+        hooks: [
+            { type: "command", command: registration.command, timeout: registration.timeoutSec },
+        ],
+    };
+}
+/**
+ * Merge our registrations into `path` and write it back.
+ *
+ * ⚠ **Written through a temp file in the same directory, then renamed.** A
+ * partial write here is the user's settings truncated, and `rename(2)` within a
+ * directory is atomic — so a crash mid-write leaves the original intact rather
+ * than a half-document that the next run would then REFUSE to touch, locking
+ * the user out of their own config.
+ *
+ * ⚠ The file's existing mode is preserved when there is one. A settings file
+ * the user tightened to `0600` must not be widened by us having rewritten it.
+ */
+export function writeAgentHooks(path, shape, registrations) {
+    let raw = null;
+    let mode;
+    try {
+        raw = readFileSync(path, "utf8");
+        mode = statSync(path).mode & 0o777;
+    }
+    catch {
+        // Absent is the ordinary case on a first install; anything else surfaces on
+        // the write below rather than being guessed at here.
+        raw = null;
+    }
+    const merged = mergeHookDocument(raw, shape, registrations);
+    if (merged.kind === "refused")
+        return { kind: "refused", path, why: merged.why };
+    const temp = join(dirname(path), `.${AGENT_HOOK_MARKER.replace(/\W+/g, "-")}.tmp`);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(temp, merged.text, { mode: mode ?? 0o600 });
+        if (mode !== undefined)
+            chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    catch (error) {
+        return { kind: "failed", path, why: error instanceof Error ? error.message : "write failed" };
+    }
+    const events = registrations.map((registration) => registration.event);
+    // "already" is not "nothing happened" — the command was still refreshed. It is
+    // the answer to *did this connect ADD anything*, which is what a user reads.
+    return merged.added.length === 0
+        ? { kind: "already", path, events }
+        : { kind: "installed", path, events };
+}
+//# sourceMappingURL=agent_hooks.js.map

package/dist/agent_hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_hooks.js","sourceRoot":"","sources":["../src/agent_hooks.ts"],"names":[],"mappings":"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"}

package/dist/agent_install.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Registering capture with every agent on this machine — `CR-195`/U4b, D205.
+ *
+ * ⛔ **THIS IS THE FILE `/install` HAS BEEN DESCRIBING SINCE BEFORE IT EXISTED.**
+ * `app/install/page.tsx` told users that `vibecommit connect` *"wires Claude Code
+ * hooks on Stop, PreCompact and SessionEnd"*. It did not: `connect` wrote GIT
+ * hooks only, and nothing in `src/` ever wrote `settings.json`. The three events
+ * were registered in exactly one place — `claude-plugin/hooks/hooks.json` — so
+ * the npm path gave a user no session capture at all, silently, while the page
+ * said otherwise.
+ *
+ * ## What is written, and what decides it
+ *
+ * Everything below is DERIVED from the registry rather than restated here:
+ *
+ *   - **which file** — `dialect.hookConfig.path(home, env)`, honouring
+ *     `CLAUDE_CONFIG_DIR` and `CODEX_HOME` because those products honour them;
+ *   - **which document shape** — `dialect.hookConfig.shape`, two shapes across
+ *     three agents (Cursor's is its own);
+ *   - **which event names** — `dialect.eventNames`, camelCase for Cursor;
+ *   - **which timeouts** — `dialect.events[event].registeredTimeoutMs`, so the
+ *     number written into an agent's config and the number this client checks
+ *     its own watchdog against cannot drift apart.
+ *
+ * ⚠ That last one matters more than it looks. `EventBudget` requires
+ * `clientBudgetMs < registeredTimeoutMs`, and until this file existed the
+ * "registered" half was a MIRROR of a JSON file hand-maintained in another
+ * repository — `test/agent-registry.test.ts` says so, and says a drift in it is
+ * invisible from here. For the three files this writes, the mirror becomes the
+ * source.
+ *
+ * ## ⛔ Only agents that are actually here
+ *
+ * A config is written only when the directory that would contain it already
+ * exists. Creating `~/.cursor/hooks.json` on a machine with no Cursor is not
+ * harmless: it is a file the user never asked for, in a tool they do not run,
+ * that a future Cursor install would silently inherit. ⚠ The directory — never
+ * the config file — is the evidence, because the file's absence is the ordinary
+ * first-install case and is exactly what this function is for.
+ */
+import { type AgentHookInstall, type HookRegistration } from "./agent_hooks.js";
+import { type AgentId, type TranscriptDialect } from "./agents/types.js";
+/** What happened for one agent. `null` install means the agent is not here. */
+export interface AgentHookOutcome {
+    readonly agentId: AgentId;
+    readonly path: string;
+    readonly install: AgentHookInstall | null;
+}
+/**
+ * The command an agent's config invokes.
+ *
+ * ⛔ **`hook` LEADS, AND THE FLAG NEVER DOES.** `invocationMode` returns `"hook"`
+ * only when `argv[0] === "hook"`, so a registered command whose first argument
+ * is `--agent=` runs the binary INTERACTIVELY — inside a hook, printing to a
+ * stream the agent reads back into the user's turn. `registry.ts` names this as
+ * the trap the wave was most likely to ship, and `test/agent-registry.test.ts`
+ * holds both arms.
+ *
+ * ⚠ **The flag is passed explicitly for every agent, Claude Code included**,
+ * even though `DEFAULT_AGENT_ID` makes it redundant there. A config that names
+ * its own agent is self-describing, and — since Cursor reads Claude Code's
+ * settings and maps them onto its own events — it is the only thing that tells
+ * the two invocations apart when both fire.
+ */
+export declare function hookCommand(binPath: string, agentId: AgentId): string;
+/** Every event this client registers, in one agent's own vocabulary. */
+export declare function registrationsFor(dialect: TranscriptDialect, binPath: string): readonly HookRegistration[];
+/** Is this agent on the machine at all? The DIRECTORY, never the config file. */
+export declare function agentPresent(dialect: TranscriptDialect, home: string, env: NodeJS.ProcessEnv): boolean;
+/**
+ * Register capture with every agent present on this machine.
+ *
+ * ⚠ **Never throws and never partially aborts.** Each agent is independent: a
+ * refusal to overwrite one unparseable `settings.json` must not stop the other
+ * two being wired, and the caller reports all three. That is the same shape
+ * `installCaptureHooks` uses for its two git hooks and the same reason —
+ * a per-target verdict is the only honest answer when the targets are unrelated.
+ */
+export declare function installAgentHooks(home: string, env: NodeJS.ProcessEnv, binPath: string): readonly AgentHookOutcome[];

package/dist/agent_install.js

@@ -0,0 +1,108 @@
+/**
+ * Registering capture with every agent on this machine — `CR-195`/U4b, D205.
+ *
+ * ⛔ **THIS IS THE FILE `/install` HAS BEEN DESCRIBING SINCE BEFORE IT EXISTED.**
+ * `app/install/page.tsx` told users that `vibecommit connect` *"wires Claude Code
+ * hooks on Stop, PreCompact and SessionEnd"*. It did not: `connect` wrote GIT
+ * hooks only, and nothing in `src/` ever wrote `settings.json`. The three events
+ * were registered in exactly one place — `claude-plugin/hooks/hooks.json` — so
+ * the npm path gave a user no session capture at all, silently, while the page
+ * said otherwise.
+ *
+ * ## What is written, and what decides it
+ *
+ * Everything below is DERIVED from the registry rather than restated here:
+ *
+ *   - **which file** — `dialect.hookConfig.path(home, env)`, honouring
+ *     `CLAUDE_CONFIG_DIR` and `CODEX_HOME` because those products honour them;
+ *   - **which document shape** — `dialect.hookConfig.shape`, two shapes across
+ *     three agents (Cursor's is its own);
+ *   - **which event names** — `dialect.eventNames`, camelCase for Cursor;
+ *   - **which timeouts** — `dialect.events[event].registeredTimeoutMs`, so the
+ *     number written into an agent's config and the number this client checks
+ *     its own watchdog against cannot drift apart.
+ *
+ * ⚠ That last one matters more than it looks. `EventBudget` requires
+ * `clientBudgetMs < registeredTimeoutMs`, and until this file existed the
+ * "registered" half was a MIRROR of a JSON file hand-maintained in another
+ * repository — `test/agent-registry.test.ts` says so, and says a drift in it is
+ * invisible from here. For the three files this writes, the mirror becomes the
+ * source.
+ *
+ * ## ⛔ Only agents that are actually here
+ *
+ * A config is written only when the directory that would contain it already
+ * exists. Creating `~/.cursor/hooks.json` on a machine with no Cursor is not
+ * harmless: it is a file the user never asked for, in a tool they do not run,
+ * that a future Cursor install would silently inherit. ⚠ The directory — never
+ * the config file — is the evidence, because the file's absence is the ordinary
+ * first-install case and is exactly what this function is for.
+ */
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { writeAgentHooks } from "./agent_hooks.js";
+import { DIALECTS } from "./agents/registry.js";
+import { HOOK_EVENTS } from "./agents/types.js";
+/**
+ * The command an agent's config invokes.
+ *
+ * ⛔ **`hook` LEADS, AND THE FLAG NEVER DOES.** `invocationMode` returns `"hook"`
+ * only when `argv[0] === "hook"`, so a registered command whose first argument
+ * is `--agent=` runs the binary INTERACTIVELY — inside a hook, printing to a
+ * stream the agent reads back into the user's turn. `registry.ts` names this as
+ * the trap the wave was most likely to ship, and `test/agent-registry.test.ts`
+ * holds both arms.
+ *
+ * ⚠ **The flag is passed explicitly for every agent, Claude Code included**,
+ * even though `DEFAULT_AGENT_ID` makes it redundant there. A config that names
+ * its own agent is self-describing, and — since Cursor reads Claude Code's
+ * settings and maps them onto its own events — it is the only thing that tells
+ * the two invocations apart when both fire.
+ */
+export function hookCommand(binPath, agentId) {
+    return `${quote(binPath)} hook --agent=${agentId}`;
+}
+/** Double-quote for the shells these configs are read by. */
+function quote(value) {
+    return `"${value.replace(/(["\\$`])/g, "\\$1")}"`;
+}
+/** Every event this client registers, in one agent's own vocabulary. */
+export function registrationsFor(dialect, binPath) {
+    return HOOK_EVENTS.map((event) => ({
+        event: dialect.eventNames[event],
+        command: hookCommand(binPath, dialect.id),
+        // ⛔ SECONDS, from the registry's milliseconds. Every one of the three
+        // configs takes seconds; `EventBudget` is in milliseconds because the
+        // client's own watchdog is. For Codex this lands `SessionEnd` on 3 s, which
+        // is exactly the cap Codex clamps to whatever we ask for — measured, so the
+        // number we write is the number that takes effect.
+        timeoutSec: Math.max(1, Math.round(dialect.events[event].registeredTimeoutMs / 1000)),
+    }));
+}
+/** Is this agent on the machine at all? The DIRECTORY, never the config file. */
+export function agentPresent(dialect, home, env) {
+    return existsSync(dirname(dialect.hookConfig.path(home, env)));
+}
+/**
+ * Register capture with every agent present on this machine.
+ *
+ * ⚠ **Never throws and never partially aborts.** Each agent is independent: a
+ * refusal to overwrite one unparseable `settings.json` must not stop the other
+ * two being wired, and the caller reports all three. That is the same shape
+ * `installCaptureHooks` uses for its two git hooks and the same reason —
+ * a per-target verdict is the only honest answer when the targets are unrelated.
+ */
+export function installAgentHooks(home, env, binPath) {
+    return DIALECTS.map((dialect) => {
+        const path = dialect.hookConfig.path(home, env);
+        if (!agentPresent(dialect, home, env)) {
+            return { agentId: dialect.id, path, install: null };
+        }
+        return {
+            agentId: dialect.id,
+            path,
+            install: writeAgentHooks(path, dialect.hookConfig.shape, registrationsFor(dialect, binPath)),
+        };
+    });
+}
+//# sourceMappingURL=agent_install.js.map

package/dist/agent_install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_install.js","sourceRoot":"","sources":["../src/agent_install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAgD,MAAM,kBAAkB,CAAC;AACjG,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAwC,MAAM,mBAAmB,CAAC;AAStF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,OAAgB;IAC3D,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,OAAO,EAAE,CAAC;AACrD,CAAC;AAED,6DAA6D;AAC7D,SAAS,KAAK,CAAC,KAAa;IAC1B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC;AACpD,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,gBAAgB,CAC9B,OAA0B,EAC1B,OAAe;IAEf,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACjC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC;QAChC,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;QACzC,sEAAsE;QACtE,sEAAsE;QACtE,4EAA4E;QAC5E,4EAA4E;QAC5E,mDAAmD;QACnD,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;KACtF,CAAC,CAAC,CAAC;AACN,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,OAA0B,EAAE,IAAY,EAAE,GAAsB;IAC3F,OAAO,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,GAAsB,EACtB,OAAe;IAEf,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAChD,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YACtC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACtD,CAAC;QACD,OAAO;YACL,OAAO,EAAE,OAAO,CAAC,EAAE;YACnB,IAAI;YACJ,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7F,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/agents/claude_code.js

@@ -9,7 +9,7 @@
  */
 import { readdirSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
-import { isInside, isTranscriptFile, transcriptRoot } from "../paths.js";
+import { claudeSettingsPath, isInside, isTranscriptFile, transcriptRoot } from "../paths.js";
 /**
  * The client-side backstop, per event.
  *
@@ -138,6 +138,17 @@ export const CLAUDE_CODE = {
     // `subagents/` directory, so every file here is already a transcript; there is
     // no interior shape to require, unlike Cursor's.
     admitsFile: isTranscriptFile,
+    // ⛔ IDENTITY, and it is the reference the other two are measured AGAINST —
+    // `HOOK_EVENTS` is spelled the way Claude Code spells it, because this is the
+    // agent the client was built for. Declared explicitly rather than defaulted so
+    // that a dialect added later must ANSWER the question; a default would let a
+    // camelCase agent inherit Claude's spellings and match nothing (`CR-195`).
+    eventNames: { Stop: "Stop", PreCompact: "PreCompact", SessionEnd: "SessionEnd" },
+    // ⛔ `~/.claude/settings.json`, honouring `CLAUDE_CONFIG_DIR`. ⚠ This is the
+    // file the PLUGIN path does not need — the plugin ships its own `hooks.json`
+    // — and the npm path had no writer at all, which is the defect `/install`
+    // has been advertising past since it first claimed `connect` wires hooks.
+    hookConfig: { path: claudeSettingsPath, shape: "claude" },
     events: {
         Stop: {
             registeredTimeoutMs: CLAUDE_REGISTERED_STOP_MS,

package/dist/agents/claude_code.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude_code.js","sourceRoot":"","sources":["../../src/agents/claude_code.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude_code.js","sourceRoot":"","sources":["../../src/agents/claude_code.ts"],"names":[],"mappings":"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"}

package/dist/agents/codex_cli.js

@@ -11,7 +11,7 @@
  * measured by this task.** They are recorded as the brief stated them so a later
  * reader can check them against the product rather than against this file.
  */
-import { codexTranscriptRoot, isTranscriptFile } from "../paths.js";
+import { codexHooksPath, codexTranscriptRoot, isTranscriptFile } from "../paths.js";
 /**
  * `SessionEnd` is the tight one — 3 s registered, 2.2 s client.
  *
@@ -33,6 +33,26 @@ export const CODEX_CLI = {
     // shape to require here either. ⚠ CARRIED FROM THE BRIEF like the numbers
     // above: this task did not re-walk a Codex tree to confirm it.
     admitsFile: isTranscriptFile,
+    // ⛔ **IDENTITY — MEASURED, and it is the one member on this dialect that is
+    // no longer carried from the brief** (`CR-195`, D205). Read out of the native
+    // binary's embedded JSON schema, where every `hook_event_name` is a `const`:
+    // `PermissionRequest PostCompact PostToolUse PreCompact PreToolUse SessionEnd
+    // SessionStart Stop SubagentStart SubagentStop UserPromptSubmit`. All three of
+    // ours are present and spelled exactly as Claude Code spells them.
+    //
+    // ⚠ **The binary ALSO carries a snake_case enum** (`session_end`,
+    // `pre_compact`, …) beside a TOML-serialisation error string, and taking it
+    // for the config vocabulary was the near-miss of this unit. A differential run
+    // against three throwaway `CODEX_HOME`s settled it: `SessionEnd` is recognised
+    // and says so by clamping, while `session_end` and a bogus key produce NO
+    // diagnostic — a file that parses, registers nothing, and reports success.
+    eventNames: { Stop: "Stop", PreCompact: "PreCompact", SessionEnd: "SessionEnd" },
+    // ⛔ `~/.codex/hooks.json`, honouring `CODEX_HOME` — MEASURED, since every
+    // probe in this unit drove a real `codex` through a throwaway `CODEX_HOME`
+    // and it read the `hooks.json` there. The NESTED shape, also measured: a
+    // document in this form was parsed, its event recognised and its timeout
+    // clamped, which Codex can only do having read the inner entry.
+    hookConfig: { path: codexHooksPath, shape: "claude" },
     events: {
         Stop: {
             registeredTimeoutMs: CODEX_TURN_REGISTERED_MS,

package/dist/agents/codex_cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex_cli.js","sourceRoot":"","sources":["../../src/agents/codex_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpE;;;;;;GAMG;AACH,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAC9C,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC,MAAM,CAAC,MAAM,SAAS,GAAsB;IAC1C,EAAE,EAAE,WAAW;IACf,SAAS,EAAE,QAAQ;IACnB,cAAc,EAAE,mBAAmB;IACnC,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,+DAA+D;IAC/D,UAAU,EAAE,gBAAgB;IAC5B,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,+BAA+B;YACpD,cAAc,EAAE,2BAA2B;SAC5C;KACF;IACD,+EAA+E;IAC/E,6EAA6E;IAC7E,oEAAoE;IACpE,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,WAAW;IACtB,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,8BAA8B;IAC9B,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,oDAAoD;CACrD,CAAC"}
+{"version":3,"file":"codex_cli.js","sourceRoot":"","sources":["../../src/agents/codex_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpF;;;;;;GAMG;AACH,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAC9C,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC,MAAM,CAAC,MAAM,SAAS,GAAsB;IAC1C,EAAE,EAAE,WAAW;IACf,SAAS,EAAE,QAAQ;IACnB,cAAc,EAAE,mBAAmB;IACnC,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,+DAA+D;IAC/D,UAAU,EAAE,gBAAgB;IAC5B,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,+EAA+E;IAC/E,mEAAmE;IACnE,EAAE;IACF,kEAAkE;IAClE,4EAA4E;IAC5E,+EAA+E;IAC/E,+EAA+E;IAC/E,0EAA0E;IAC1E,2EAA2E;IAC3E,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE;IAChF,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,gEAAgE;IAChE,UAAU,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE;IACrD,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,+BAA+B;YACpD,cAAc,EAAE,2BAA2B;SAC5C;KACF;IACD,+EAA+E;IAC/E,6EAA6E;IAC7E,oEAAoE;IACpE,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,WAAW;IACtB,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,8BAA8B;IAC9B,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,oDAAoD;CACrD,CAAC"}