hippo-memory 1.60.0 → 1.62.0

package/dist/hooks/json-hooks.js

@@ -0,0 +1,356 @@
+/**
+ * Hook install/uninstall for AI coding tools.
+ *
+ * Two integration models live in this file:
+ *
+ * 1. JSON-hook install (Claude Code only). Writes a `hooks` block into the
+ *    tool's settings.json with two entries:
+ *      - SessionEnd: `hippo session-end --log-file <path>` - spawns a detached
+ *        child that runs `hippo sleep` then `hippo capture --last-session` in
+ *        sequence, writing both outputs to the log file. The parent returns in
+ *        <100ms so the TUI teardown can't kill the child before it finishes.
+ *      - SessionStart: `hippo last-sleep --path <path>` - prints the log
+ *        written by the previous session's detached worker to stderr, which
+ *        keeps it out of the model's context, and then clears it.
+ *    Earlier Claude Code forms are detected and migrated automatically:
+ *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
+ *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
+ *      - 0.22.x: separate sleep + capture SessionEnd entries.
+ *    PreCompact and PostCompact entries go in too: the first records the compaction and
+ *    asks the summariser for a "Memories for hippo" list, the second saves that list.
+ *    Codex's hooks.json gets only two groups (per-prompt memory and
+ *    compact-resume); see installCodexHooks.
+ *
+ * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
+ *    JSON-hook schema — its config has `additionalProperties: false` and no
+ *    `hooks` key, so v1.10.x-v1.11.1's JSON-hook installer broke opencode
+ *    launch (issue #24). Hippo now installs a TypeScript plugin at
+ *    `~/.config/opencode/plugins/hippo.ts` subscribing to opencode's
+ *    `session.idle` (→ `hippo session-end`) and `session.created` (→
+ *    `hippo last-sleep`) events. See OPENCODE_PLUGIN_SOURCE below for the
+ *    plugin file content + design rationale; see installOpencodePlugin for
+ *    the installer + the migration that removes any pre-existing broken
+ *    `hooks` block from opencode.json.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { isJsonString, isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, codexHomeDir, defaultPreCompactLogPath } from './shared.js';
+export function resolveJsonHookPaths(target) {
+    const home = homeDir();
+    const logsDir = path.join(home, '.hippo', 'logs');
+    switch (target) {
+        case 'claude-code':
+            return {
+                settings: path.join(home, '.claude', 'settings.json'),
+                logFile: path.join(logsDir, 'claude-code-sleep.log'),
+                display: 'Claude Code',
+            };
+        case 'codex':
+            return {
+                settings: path.join(codexHomeDir(home), 'hooks.json'),
+                logFile: path.join(logsDir, 'codex-sleep.log'),
+                display: 'Codex',
+            };
+    }
+}
+function hookArrayContains(hookArray, marker) {
+    if (!Array.isArray(hookArray))
+        return false;
+    return JSON.stringify(hookArray).includes(marker);
+}
+function addIncludeRecentToPinnedCommand(command) {
+    if (!command.includes(HIPPO_PINNED_INJECT_MARKER) || command.includes('--include-recent'))
+        return command;
+    return command.includes(' --format ')
+        ? command.replace(' --format ', ' --include-recent 5 --format ')
+        : `${command} --include-recent 5`;
+}
+function migratePinnedInjectRecentCommands(hookArray) {
+    if (!Array.isArray(hookArray))
+        return false;
+    let changed = false;
+    for (const entry of hookArray) {
+        if (!isJsonObject(entry))
+            continue;
+        const innerHooks = entry.hooks;
+        if (!Array.isArray(innerHooks))
+            continue;
+        for (const hook of innerHooks) {
+            if (!isJsonObject(hook))
+                continue;
+            if (!isJsonString(hook.command))
+                continue;
+            const next = addIncludeRecentToPinnedCommand(hook.command);
+            if (next !== hook.command) {
+                hook.command = next;
+                changed = true;
+            }
+        }
+    }
+    return changed;
+}
+/**
+ * Returns true when `hooks.SessionEnd` still contains either of the legacy
+ * v0.22.x split entries (bare `hippo sleep` / `hippo capture --last-session`)
+ * without the current consolidated `hippo session-end` entry.
+ */
+function hasLegacySplitSessionEnd(hookArray) {
+    if (!Array.isArray(hookArray))
+        return false;
+    const serialized = JSON.stringify(hookArray);
+    const hasSleep = serialized.includes(HIPPO_SLEEP_MARKER);
+    const hasCapture = serialized.includes(HIPPO_CAPTURE_MARKER);
+    return (hasSleep || hasCapture) && !serialized.includes(HIPPO_SESSION_END_MARKER);
+}
+function nothingInstalled(target, settingsPath) {
+    return {
+        target,
+        settingsPath,
+        installedSessionEnd: false,
+        installedSessionStart: false,
+        installedUserPromptSubmit: false,
+        installedPreCompact: false,
+        installedCompactResume: false,
+        installedPostCompact: false,
+        installedCaptureError: false,
+        migratedPinnedInjectRecent: false,
+        migratedFromStop: false,
+        migratedLegacySessionEnd: false,
+        migratedSplitSessionEnd: false,
+        invalidJson: false,
+    };
+}
+/** A command hook with a Windows form: Codex runs hooks in PowerShell there, whose execution policy can block npm's hippo.ps1. */
+function codexCommandHook(command, timeout) {
+    return { type: 'command', command, commandWindows: command.replace(/^hippo /, 'hippo.cmd '), timeout };
+}
+/** Codex keys trust to each hook's position and hash and re-asks for a changed one, so hippo only appends and never edits an entry. */
+function installCodexHooks(settingsPath, settings) {
+    const result = nothingInstalled('codex', settingsPath);
+    if (!isJsonObject(settings))
+        return { ...result, invalidJson: true };
+    if (settings.hooks === undefined)
+        settings.hooks = {};
+    const hooks = settings.hooks;
+    const events = ['UserPromptSubmit', 'SessionStart'];
+    if (!isJsonObject(hooks) || events.some((e) => hooks[e] !== undefined && !Array.isArray(hooks[e]))) {
+        return { ...result, invalidJson: true };
+    }
+    const append = (event, marker, group) => {
+        const groups = hooks[event];
+        if (hookArrayContains(groups, marker))
+            return false;
+        hooks[event] = [...(Array.isArray(groups) ? groups : []), group];
+        return true;
+    };
+    const installedUserPromptSubmit = append('UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, {
+        hooks: [codexCommandHook(HIPPO_PINNED_INJECT_COMMAND, 5)],
+    });
+    const installedCompactResume = append('SessionStart', HIPPO_COMPACT_RESUME_MARKER, {
+        matcher: 'compact',
+        hooks: [codexCommandHook(HIPPO_COMPACT_RESUME_MARKER, 10)],
+    });
+    if (installedUserPromptSubmit || installedCompactResume) {
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    }
+    return { ...result, installedUserPromptSubmit, installedCompactResume };
+}
+export function installJsonHooks(target) {
+    const { settings: settingsPath, logFile } = resolveJsonHookPaths(target);
+    const dir = path.dirname(settingsPath);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        }
+        catch {
+            return { ...nothingInstalled(target, settingsPath), invalidJson: true };
+        }
+    }
+    if (target === 'codex')
+        return installCodexHooks(settingsPath, settings);
+    return installClaudeCodeHooks(settingsPath, settings, logFile);
+}
+function migrateLegacyClaudeHooks(hooks) {
+    let migratedFromStop = false;
+    if (Array.isArray(hooks.Stop) && hookArrayContains(hooks.Stop, HIPPO_SLEEP_MARKER)) {
+        hooks.Stop = hooks.Stop.filter((entry) => !JSON.stringify(entry).includes(HIPPO_SLEEP_MARKER));
+        if (hooks.Stop.length === 0)
+            delete hooks.Stop;
+        migratedFromStop = true;
+    }
+    // Migrate legacy SessionEnd forms:
+    //   - pre-0.21 bare `hippo sleep`
+    //   - 0.21.x+ `hippo sleep --log-file` split across two entries
+    //   - 0.22.x `hippo capture --last-session --log-file` second entry
+    // All of these get collapsed into the single `hippo session-end` entry.
+    let migratedLegacySessionEnd = false;
+    let migratedSplitSessionEnd = false;
+    if (Array.isArray(hooks.SessionEnd) && hasLegacySplitSessionEnd(hooks.SessionEnd)) {
+        const before = hooks.SessionEnd.length;
+        hooks.SessionEnd = hooks.SessionEnd.filter((entry) => {
+            const s = JSON.stringify(entry);
+            return !s.includes(HIPPO_SLEEP_MARKER) && !s.includes(HIPPO_CAPTURE_MARKER);
+        });
+        if (hooks.SessionEnd.length === 0)
+            delete hooks.SessionEnd;
+        // If the removed entries used the log-file pattern (0.21.x-0.22.x) we
+        // call it a "split" migration; otherwise it was the older bare form.
+        migratedSplitSessionEnd = true;
+        migratedLegacySessionEnd = before > 1;
+    }
+    return { migratedFromStop, migratedLegacySessionEnd, migratedSplitSessionEnd };
+}
+function claudeCommandGroup(command, timeout, matcher) {
+    const hooks = [{ type: 'command', command, timeout }];
+    return matcher === undefined ? { hooks } : { matcher, hooks };
+}
+function appendHookIfMissing(hooks, event, marker, group) {
+    if (hookArrayContains(hooks[event], marker))
+        return false;
+    if (!Array.isArray(hooks[event]))
+        hooks[event] = [];
+    hooks[event].push(group);
+    return true;
+}
+function installClaudeCodeHooks(settingsPath, settings, logFile) {
+    if (!settings.hooks)
+        settings.hooks = {};
+    // SAFETY: settings.hooks is either freshly initialised to {} on the line above, or an
+    // existing value from settings.json — Claude Code's own schema always writes an object
+    // there; each event key below is still re-validated with Array.isArray before use.
+    const hooks = settings.hooks;
+    const migration = migrateLegacyClaudeHooks(hooks);
+    const installedSessionEnd = appendHookIfMissing(hooks, 'SessionEnd', HIPPO_SESSION_END_MARKER, claudeCommandGroup(`hippo session-end --log-file "${logFile}"`, 5));
+    const installedSessionStart = appendHookIfMissing(hooks, 'SessionStart', HIPPO_LAST_SLEEP_MARKER, claudeCommandGroup(`hippo last-sleep --path "${logFile}"`, 5));
+    // Mid-session pinned-rule re-injection: UserPromptSubmit runs every turn,
+    // so pinned memories stay in context even after the model would otherwise
+    // "forget" them in a long session. Include the fresh write tail so lessons
+    // saved earlier in the same session become visible on the next prompt even
+    // before the user pins them explicitly.
+    const migratedPinnedInjectRecent = migratePinnedInjectRecentCommands(hooks.UserPromptSubmit);
+    const installedUserPromptSubmit = appendHookIfMissing(hooks, 'UserPromptSubmit', HIPPO_PINNED_INJECT_MARKER, claudeCommandGroup(HIPPO_PINNED_INJECT_COMMAND, 5));
+    // PreCompact: fires on manual AND auto compaction (no matcher). Records the compaction, asks the
+    // summariser for a "Memories for hippo" list and saves a working-state snapshot before the summary drops detail.
+    // Exit-0 contract lives in the verb itself (src/capture.ts cmdPreCompact),
+    // not here — this is install-time wiring only.
+    const installedPreCompact = appendHookIfMissing(hooks, 'PreCompact', HIPPO_PRE_COMPACT_MARKER, claudeCommandGroup(`hippo pre-compact --log-file "${defaultPreCompactLogPath()}"`, 30));
+    // SessionStart(compact): a SECOND SessionStart entry alongside the
+    // un-matched last-sleep entry above. The matcher is an optimization, not
+    // a dependency — compact-resume itself checks payload.source too, so an
+    // older Claude Code that ignores the matcher just runs a silent no-op on
+    // normal starts. Marker check keys on the command string, so this stays
+    // idempotent alongside the sibling last-sleep entry.
+    const installedCompactResume = appendHookIfMissing(hooks, 'SessionStart', HIPPO_COMPACT_RESUME_MARKER, claudeCommandGroup('hippo compact-resume', 10, 'compact'));
+    // PostCompact: saves the memories the summariser listed and prints one line, which Claude Code only shows.
+    // PreCompact stdout, by contrast, is handed to the summariser as instructions, so pre-compact prints just the request.
+    const installedPostCompact = appendHookIfMissing(hooks, 'PostCompact', HIPPO_POST_COMPACT_MARKER, claudeCommandGroup(`hippo post-compact --log-file "${defaultPreCompactLogPath()}"`, 10));
+    // PostToolUseFailure: a failed tool call becomes an error memory, after
+    // `hippo capture-error` drops routine failures (interrupts, declined
+    // permissions, empty searches) and repeats. Same hook the plugin ships.
+    const installedCaptureError = appendHookIfMissing(hooks, 'PostToolUseFailure', HIPPO_CAPTURE_ERROR_MARKER, claudeCommandGroup('hippo capture-error', 10, '.*'));
+    const result = {
+        target: 'claude-code',
+        settingsPath,
+        installedSessionEnd,
+        installedSessionStart,
+        installedUserPromptSubmit,
+        installedPreCompact,
+        installedCompactResume,
+        installedPostCompact,
+        installedCaptureError,
+        migratedPinnedInjectRecent,
+        ...migration,
+        invalidJson: false,
+    };
+    if (Object.values(result).some((v) => v === true)) {
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    }
+    return result;
+}
+/** The exact command hippo writes for each Codex event; uninstall removes only these handlers. */
+const CODEX_HOOK_COMMANDS = [
+    ['UserPromptSubmit', HIPPO_PINNED_INJECT_COMMAND],
+    ['SessionStart', HIPPO_COMPACT_RESUME_MARKER],
+];
+/** A group loses only hippo's handlers and goes only once empty, so a user's hook beside or like hippo's stays. */
+function uninstallCodexHooks(hooks) {
+    let changed = false;
+    for (const [event, command] of CODEX_HOOK_COMMANDS) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        let removed = false;
+        const kept = groups.flatMap((group) => {
+            if (!isJsonObject(group) || !Array.isArray(group.hooks))
+                return [group];
+            const handlers = group.hooks.filter((h) => !(isJsonObject(h) && h.command === command));
+            if (handlers.length === group.hooks.length)
+                return [group];
+            removed = true;
+            return handlers.length > 0 ? [{ ...group, hooks: handlers }] : [];
+        });
+        if (!removed)
+            continue;
+        changed = true;
+        if (kept.length > 0)
+            hooks[event] = kept;
+        else
+            delete hooks[event];
+    }
+    return changed;
+}
+export function uninstallJsonHooks(target) {
+    const { settings: settingsPath } = resolveJsonHookPaths(target);
+    if (!fs.existsSync(settingsPath))
+        return false;
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    }
+    catch {
+        // Never rewrite a settings file we cannot parse; report nothing uninstalled.
+        return false;
+    }
+    if (!isJsonObject(settings) || !isJsonObject(settings.hooks))
+        return false;
+    const changed = target === 'codex' ? uninstallCodexHooks(settings.hooks) : uninstallClaudeCodeHooks(settings.hooks);
+    if (!changed)
+        return false;
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return true;
+}
+function uninstallClaudeCodeHooks(settingsHooks) {
+    // SAFETY: each event key below is re-validated with Array.isArray before use.
+    const hooks = settingsHooks;
+    let changed = false;
+    const markersByKey = {
+        SessionEnd: [HIPPO_SESSION_END_MARKER, HIPPO_SLEEP_MARKER, HIPPO_CAPTURE_MARKER],
+        // Both the un-matched last-sleep entry and the matcher:'compact'
+        // compact-resume entry live under the SessionStart key; the matcher
+        // field doesn't affect this substring match, so removal covers both.
+        SessionStart: [HIPPO_LAST_SLEEP_MARKER, HIPPO_COMPACT_RESUME_MARKER],
+        UserPromptSubmit: [HIPPO_PINNED_INJECT_MARKER],
+        PreCompact: [HIPPO_PRE_COMPACT_MARKER],
+        PostCompact: [HIPPO_POST_COMPACT_MARKER],
+        PostToolUseFailure: [HIPPO_CAPTURE_ERROR_MARKER],
+        Stop: [HIPPO_SLEEP_MARKER],
+    };
+    for (const [key, markers] of Object.entries(markersByKey)) {
+        if (!Array.isArray(hooks[key]))
+            continue;
+        const before = hooks[key].length;
+        hooks[key] = hooks[key].filter((entry) => !markers.some((m) => JSON.stringify(entry).includes(m)));
+        if (hooks[key].length !== before) {
+            changed = true;
+            if (hooks[key].length === 0)
+                delete hooks[key];
+        }
+    }
+    return changed;
+}
+//# sourceMappingURL=json-hooks.js.map

package/dist/hooks/opencode.d.ts

@@ -0,0 +1,50 @@
+declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
+/**
+ * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
+ *
+ * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
+ * async function returning hooks. We subscribe to `event` and route:
+ *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
+ *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
+ *
+ * Design choices forced by plan-eng-critic Rev 0 review (2026-05-23):
+ *
+ * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
+ *    publication status was unverifiable from the build sandbox (npmjs.com
+ *    returned 403); an unresolved type-only import would still crash the TS
+ *    runtime opencode uses to load the plugin. opencode infers plugin shape
+ *    from the returned object, so the type was convenience-only.
+ *
+ * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
+ *    `$` is the shell-template helper), but a future Node-mode deployment
+ *    would have `$` undefined in the destructured context and the plugin
+ *    would throw on every session.idle, killing opencode sessions in a
+ *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
+ *    Fail closed, let opencode continue.
+ *
+ * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
+ *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
+ *    The surrounding try/catch is belt-and-braces.
+ *
+ * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
+ *    fires per-token, not per-prompt-submit; no clean per-prompt event.
+ *    Users wanting pinned-context auto-injection can call `hippo context`
+ *    via the MCP server (`hippo mcp`).
+ *
+ * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
+ *    overwrite cleanly. The installer's idempotence check requires BOTH
+ *    marker match AND content equality, so a plugin-source revision under
+ *    the same V1 marker re-writes the file on next install.
+ */
+export declare const OPENCODE_PLUGIN_SOURCE = "// HIPPO_OPENCODE_PLUGIN_V1\n// hippo-memory opencode plugin. DO NOT EDIT \u2014 regenerated on every\n// `hippo hook install opencode` from src/hooks.ts OPENCODE_PLUGIN_SOURCE\n// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.\n\nexport const HippoPlugin = async ({ $ }) => {\n  return {\n    event: async ({ event }) => {\n      // Defense in depth: opencode currently runs in Bun where $ is the shell\n      // template helper. A non-Bun runtime would have $ as undefined; fail\n      // closed instead of crashing the host session.\n      if (typeof $ !== \"function\") return;\n      try {\n        if (event.type === \"session.idle\") {\n          await $`hippo session-end`.quiet().nothrow();\n        } else if (event.type === \"session.created\") {\n          await $`hippo last-sleep`.quiet().nothrow();\n        }\n      } catch {\n        // hippo CLI not on PATH or other failure \u2014 never crash the host session.\n      }\n    },\n  };\n};\n";
+export { HIPPO_OPENCODE_PLUGIN_MARKER };
+export interface OpencodePluginInstallResult {
+    installed: boolean;
+    pluginPath: string;
+    migratedLegacyHooks: boolean;
+    jsonRepairFailed: boolean;
+}
+export declare function resolveOpencodePluginPath(): string;
+export declare function installOpencodePlugin(): OpencodePluginInstallResult;
+export declare function uninstallOpencodePlugin(): boolean;
+//# sourceMappingURL=opencode.d.ts.map

package/dist/hooks/opencode.js

@@ -0,0 +1,202 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isJsonString, isJsonObject, homeDir } from './shared.js';
+const HIPPO_OPENCODE_PLUGIN_MARKER = 'HIPPO_OPENCODE_PLUGIN_V1';
+/**
+ * The opencode plugin file we install at ~/.config/opencode/plugins/hippo.ts.
+ *
+ * Per https://opencode.ai/docs/plugins/, plugins are TS/JS modules exporting an
+ * async function returning hooks. We subscribe to `event` and route:
+ *   session.idle    → `hippo session-end` (Claude Code's SessionEnd equiv)
+ *   session.created → `hippo last-sleep` (Claude Code's SessionStart equiv)
+ *
+ * Design choices forced by plan-eng-critic Rev 0 review (2026-05-23):
+ *
+ * 1. No `import type { Plugin } from "@opencode-ai/plugin"`. The package's npm
+ *    publication status was unverifiable from the build sandbox (npmjs.com
+ *    returned 403); an unresolved type-only import would still crash the TS
+ *    runtime opencode uses to load the plugin. opencode infers plugin shape
+ *    from the returned object, so the type was convenience-only.
+ *
+ * 2. Defensive `typeof $ !== 'function'` guard. opencode runs in Bun (where
+ *    `$` is the shell-template helper), but a future Node-mode deployment
+ *    would have `$` undefined in the destructured context and the plugin
+ *    would throw on every session.idle, killing opencode sessions in a
+ *    hard-to-recover way (the idempotence marker prevents auto-reinstall).
+ *    Fail closed, let opencode continue.
+ *
+ * 3. `.quiet().nothrow()` on each `$\`...\`` so a missing hippo binary
+ *    (e.g. PATH-misconfigured user) does NOT throw out of the event handler.
+ *    The surrounding try/catch is belt-and-braces.
+ *
+ * 4. UserPromptSubmit equivalent NOT wired. opencode's `message.updated`
+ *    fires per-token, not per-prompt-submit; no clean per-prompt event.
+ *    Users wanting pinned-context auto-injection can call `hippo context`
+ *    via the MCP server (`hippo mcp`).
+ *
+ * 5. Versioned marker `HIPPO_OPENCODE_PLUGIN_V1` allows future versions to
+ *    overwrite cleanly. The installer's idempotence check requires BOTH
+ *    marker match AND content equality, so a plugin-source revision under
+ *    the same V1 marker re-writes the file on next install.
+ */
+export const OPENCODE_PLUGIN_SOURCE = `// ${HIPPO_OPENCODE_PLUGIN_MARKER}
+// hippo-memory opencode plugin. DO NOT EDIT — regenerated on every
+// \`hippo hook install opencode\` from src/hooks.ts OPENCODE_PLUGIN_SOURCE
+// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.
+
+export const HippoPlugin = async ({ $ }) => {
+  return {
+    event: async ({ event }) => {
+      // Defense in depth: opencode currently runs in Bun where $ is the shell
+      // template helper. A non-Bun runtime would have $ as undefined; fail
+      // closed instead of crashing the host session.
+      if (typeof $ !== "function") return;
+      try {
+        if (event.type === "session.idle") {
+          await $\`hippo session-end\`.quiet().nothrow();
+        } else if (event.type === "session.created") {
+          await $\`hippo last-sleep\`.quiet().nothrow();
+        }
+      } catch {
+        // hippo CLI not on PATH or other failure — never crash the host session.
+      }
+    },
+  };
+};
+`;
+export { HIPPO_OPENCODE_PLUGIN_MARKER };
+export function resolveOpencodePluginPath() {
+    return path.join(homeDir(), '.config', 'opencode', 'plugins', 'hippo.ts');
+}
+function resolveOpencodeConfigPath() {
+    return path.join(homeDir(), '.config', 'opencode', 'opencode.json');
+}
+/**
+ * Return true iff a single hook-array entry's command string starts with
+ * `hippo ` (the verb-prefix). Used to surgically remove only hippo-owned
+ * commands when migrating an opencode.json. We own the install side, so only
+ * the canonical `hippo <verb>` form needs to match — and only canonical verbs
+ * hippo itself installs (session-end, last-sleep, sleep, capture, context),
+ * not any third-party tool that happens to be named `hippo`.
+ *
+ * Critic-mandated structural check (Rev 0): substring matching against
+ * arbitrary user content is unsafe — a user's
+ * `echo "remember to hippo sleep your laptop"` is not a hippo-owned hook.
+ *
+ * Per-hook (not per-entry) granularity (Rev 1 review): an entry whose inner
+ * hooks array mixes hippo-installed commands with user-authored commands
+ * must NOT lose the user-authored commands. The migration filters the inner
+ * array per-hook, then drops the entry only when its inner array is empty.
+ */
+const HIPPO_OWNED_COMMAND_RE = /^\s*hippo\s+(session-end|last-sleep|sleep|capture|context)\b/;
+function hookIsHippoOwned(hook) {
+    if (!isJsonObject(hook))
+        return false;
+    const cmd = hook.command;
+    return isJsonString(cmd) && HIPPO_OWNED_COMMAND_RE.test(cmd);
+}
+/**
+ * Structurally strip every hippo-owned hook from opencode.json's hooks key.
+ * Returns one of:
+ *   { migrated: true,  jsonRepairFailed: false } — at least one hook removed.
+ *   { migrated: false, jsonRepairFailed: false } — file fine, nothing to do.
+ *   { migrated: false, jsonRepairFailed: true  } — file present but unparseable.
+ *
+ * Per-hook surgery:
+ *   - For each entry in each event-key array, filter the inner `hooks` array
+ *     to remove hippo-owned hooks only. User-authored hooks in the same
+ *     inner array are preserved.
+ *   - When an entry's inner `hooks` array becomes empty, that entry is
+ *     removed from the outer array.
+ *   - When an event-key array becomes empty, the key is deleted.
+ *   - When the top-level `hooks` object becomes empty, it is deleted.
+ *   - Other keys (theme, etc.) are always preserved.
+ */
+function migrateLegacyOpencodeHooksBlock() {
+    const configPath = resolveOpencodeConfigPath();
+    if (!fs.existsSync(configPath))
+        return { migrated: false, jsonRepairFailed: false };
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        return { migrated: false, jsonRepairFailed: true };
+    }
+    const hooks = settings.hooks;
+    // Non-object hooks values (string, array, null) are user content we don't
+    // recognise — leave them alone, return migrated=false.
+    if (!isJsonObject(hooks)) {
+        return { migrated: false, jsonRepairFailed: false };
+    }
+    const hooksObj = hooks;
+    let changed = false;
+    for (const key of Object.keys(hooksObj)) {
+        if (!Array.isArray(hooksObj[key]))
+            continue;
+        const survivingEntries = [];
+        for (const entry of hooksObj[key]) {
+            if (!isJsonObject(entry)) {
+                survivingEntries.push(entry);
+                continue;
+            }
+            const innerHooks = entry.hooks;
+            if (!Array.isArray(innerHooks)) {
+                survivingEntries.push(entry);
+                continue;
+            }
+            const beforeInner = innerHooks.length;
+            const survivingInner = innerHooks.filter((h) => !hookIsHippoOwned(h));
+            if (survivingInner.length !== beforeInner)
+                changed = true;
+            if (survivingInner.length === 0)
+                continue; // drop entry, nothing left
+            entry.hooks = survivingInner;
+            survivingEntries.push(entry);
+        }
+        if (survivingEntries.length !== hooksObj[key].length)
+            changed = true;
+        hooksObj[key] = survivingEntries;
+        if (hooksObj[key].length === 0)
+            delete hooksObj[key];
+    }
+    if (!changed)
+        return { migrated: false, jsonRepairFailed: false };
+    if (Object.keys(hooksObj).length === 0)
+        delete settings.hooks;
+    fs.writeFileSync(configPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+    return { migrated: true, jsonRepairFailed: false };
+}
+export function installOpencodePlugin() {
+    const pluginPath = resolveOpencodePluginPath();
+    const { migrated, jsonRepairFailed } = migrateLegacyOpencodeHooksBlock();
+    // Idempotence: skip the write only if BOTH the marker is present AND the
+    // content matches the current source. Marker-only matches (with stale
+    // content) overwrite cleanly so future plugin-source patches reach
+    // existing installs.
+    if (fs.existsSync(pluginPath)) {
+        const existing = fs.readFileSync(pluginPath, 'utf8');
+        if (existing.includes(HIPPO_OPENCODE_PLUGIN_MARKER) && existing === OPENCODE_PLUGIN_SOURCE) {
+            return { installed: false, pluginPath, migratedLegacyHooks: migrated, jsonRepairFailed };
+        }
+    }
+    fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+    fs.writeFileSync(pluginPath, OPENCODE_PLUGIN_SOURCE, 'utf8');
+    return { installed: true, pluginPath, migratedLegacyHooks: migrated, jsonRepairFailed };
+}
+export function uninstallOpencodePlugin() {
+    const pluginPath = resolveOpencodePluginPath();
+    let removedFile = false;
+    if (fs.existsSync(pluginPath)) {
+        const existing = fs.readFileSync(pluginPath, 'utf8');
+        if (existing.includes(HIPPO_OPENCODE_PLUGIN_MARKER)) {
+            fs.unlinkSync(pluginPath);
+            removedFile = true;
+        }
+    }
+    // Always run the legacy migration on uninstall — the downgrade path (user
+    // removing hippo entirely) must leave opencode launchable.
+    const { migrated } = migrateLegacyOpencodeHooksBlock();
+    return removedFile || migrated;
+}
+//# sourceMappingURL=opencode.js.map

package/dist/hooks/shared.d.ts

@@ -0,0 +1,54 @@
+import type { JsonValue, JsonObject } from '../working-memory.js';
+/** JSON-value string check. `constructor` narrows a primitive via its boxed wrapper
+ *  instead of inspecting the `typeof` tag (anti-slop/no-runtime-typeof); equivalent to
+ *  `typeof value === 'string'` for every value JSON.parse can ever produce. */
+export declare function isJsonString(value: JsonValue | undefined): value is string;
+/** JSON-value plain-object check (excludes arrays and null), typeof-free for the same
+ *  reason as isJsonString above. */
+export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
+export type JsonHookTarget = 'claude-code' | 'codex';
+export interface ToolDetection {
+    name: string;
+    configDir: string;
+    detected: boolean;
+    kind: 'json-hook' | 'markdown-instruction' | 'plugin' | 'wrapper';
+    notes?: string;
+}
+export declare const HIPPO_SLEEP_MARKER = "hippo sleep";
+export declare const HIPPO_LAST_SLEEP_MARKER = "hippo last-sleep";
+export declare const HIPPO_CAPTURE_MARKER = "hippo capture --last-session";
+export declare const HIPPO_SESSION_END_MARKER = "hippo session-end";
+export declare const HIPPO_PINNED_INJECT_MARKER = "hippo context --pinned-only";
+export declare const HIPPO_PINNED_INJECT_COMMAND = "hippo context --pinned-only --include-recent 5 --format additional-context";
+export declare const HIPPO_CODEX_WRAPPER_MARKER = "hippo codex wrapper";
+export declare const HIPPO_PRE_COMPACT_MARKER = "hippo pre-compact";
+export declare const HIPPO_COMPACT_RESUME_MARKER = "hippo compact-resume";
+export declare const HIPPO_CAPTURE_ERROR_MARKER = "hippo capture-error";
+export declare const HIPPO_POST_COMPACT_MARKER = "hippo post-compact";
+export declare function homeDir(): string;
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
+/** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
+export declare function isCodexPresent(home?: string): boolean;
+/** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
+export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+/**
+ * Default log path consumed by `hippo last-sleep`. Shared fallback when
+ * a caller doesn't pass --path explicitly.
+ */
+export declare function defaultSleepLogPath(): string;
+/**
+ * Diagnostic-only log path for `hippo pre-compact`. Deliberately separate
+ * from the SessionEnd sleep log: `hippo last-sleep` truncates that file on
+ * every SessionStart, which would wipe pre-compact lines before anyone
+ * could read them. Nothing consumes this file programmatically — it exists
+ * for manual troubleshooting only. Overridden by `--log-file`.
+ */
+export declare function defaultPreCompactLogPath(): string;
+export declare function ensureDir(dir: string): void;
+/**
+ * Detect which AI coding tools are installed based on config directory presence.
+ * Used by `hippo setup` to decide which JSON-hook installs to run.
+ */
+export declare function detectInstalledTools(): ToolDetection[];
+//# sourceMappingURL=shared.d.ts.map