context-mode 1.0.110 → 1.0.112

package/build/adapters/codex/hooks.js

@@ -1,12 +1,16 @@
 /**
  * adapters/codex/hooks — Codex CLI hook definitions.
  *
- * Codex CLI hooks are stable (codex_hooks Stage::Stable, default_enabled: true).
- * 5 hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop.
+ * Codex CLI hooks run behind the current `hooks` feature flag surface.
+ * Prefer `[features].hooks`; the legacy `[features].codex_hooks` alias is still
+ * accepted in current Codex builds.
+ * 6 hook events: PreToolUse, PostToolUse, PreCompact, SessionStart,
+ * UserPromptSubmit, Stop. PreCompact is runtime-gated on Codex builds that emit
+ * the event.
  * Same JSON stdin/stdout wire protocol as Claude Code.
  *
- * Config: ~/.codex/hooks.json (JSON format, same schema as Claude Code)
- * MCP: full support via [mcp_servers] in ~/.codex/config.toml
+ * Config: $CODEX_HOME/hooks.json or ~/.codex/hooks.json.
+ * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
  *
  * Known limitations:
  *   - PreToolUse: deny works, updatedInput not yet supported (openai/codex#18491)
@@ -16,10 +20,11 @@
 // ─────────────────────────────────────────────────────────
 // Hook type constants
 // ─────────────────────────────────────────────────────────
-/** Codex CLI hook types — mirrors Claude Code's 5-event model. */
+/** Codex CLI hook types — mirrors Claude Code's continuity events. */
 export const HOOK_TYPES = {
     PRE_TOOL_USE: "PreToolUse",
     POST_TOOL_USE: "PostToolUse",
+    PRE_COMPACT: "PreCompact",
     SESSION_START: "SessionStart",
     USER_PROMPT_SUBMIT: "UserPromptSubmit",
     STOP: "Stop",

package/build/adapters/codex/index.d.ts

@@ -4,10 +4,10 @@
  * Implements HookAdapter for Codex CLI's JSON stdin/stdout paradigm.
  *
  * Codex CLI hook specifics:
- *   - 5 hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop
+ *   - 6 hook events: PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit, Stop
  *   - Same wire protocol as Claude Code (JSON stdin → stdout)
- *   - Config: ~/.codex/hooks.json + ~/.codex/config.toml (TOML for MCP/features)
- *   - Session dir: ~/.codex/context-mode/sessions/
+ *   - Config: $CODEX_HOME or ~/.codex (hooks.json + config.toml)
+ *   - Session dir: $CODEX_HOME/context-mode/sessions/
  *
  * Hook dispatch is stable in Codex CLI. PreToolUse deny decisions work,
  * while input rewriting remains blocked on upstream updatedInput support.
@@ -28,16 +28,19 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
     formatPostToolUseResponse(response: PostToolUseResponse): unknown;
     formatPreCompactResponse(response: PreCompactResponse): unknown;
     formatSessionStartResponse(response: SessionStartResponse): unknown;
+    getConfigDir(_projectDir?: string): string;
     getSettingsPath(): string;
+    getSessionDir(): string;
     getInstructionFiles(): string[];
     getMemoryDir(): string;
-    generateHookConfig(pluginRoot: string): HookRegistration;
+    generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(_settings: Record<string, unknown>): void;
     validateHooks(_pluginRoot: string): DiagnosticResult[];
     checkPluginRegistration(): DiagnosticResult;
     getInstalledVersion(): string;
-    configureAllHooks(_pluginRoot: string): string[];
+    configureAllHooks(pluginRoot: string): string[];
+    backupSettings(): string | null;
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
     getRoutingInstructions(): string;
@@ -49,6 +52,15 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
      * platform omits cwd from the wire payload.
      */
     private getProjectDir;
+    getHooksPath(): string;
+    private backupFile;
+    private readHooksConfig;
+    private writeHooksConfig;
+    private upsertManagedHookEntry;
+    private isExpectedHookEntry;
+    private isManagedContextModeEntry;
+    private entryContainsManagedCommand;
+    private normalizeCommand;
     /**
      * Extract session ID from Codex CLI hook input.
      * Priority: session_id field > fallback to ppid.

package/build/adapters/codex/index.js

@@ -4,21 +4,91 @@
  * Implements HookAdapter for Codex CLI's JSON stdin/stdout paradigm.
  *
  * Codex CLI hook specifics:
- *   - 5 hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop
+ *   - 6 hook events: PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit, Stop
  *   - Same wire protocol as Claude Code (JSON stdin → stdout)
- *   - Config: ~/.codex/hooks.json + ~/.codex/config.toml (TOML for MCP/features)
- *   - Session dir: ~/.codex/context-mode/sessions/
+ *   - Config: $CODEX_HOME or ~/.codex (hooks.json + config.toml)
+ *   - Session dir: $CODEX_HOME/context-mode/sessions/
  *
  * Hook dispatch is stable in Codex CLI. PreToolUse deny decisions work,
  * while input rewriting remains blocked on upstream updatedInput support.
  * Track: https://github.com/openai/codex/issues/18491
  */
-import { readFileSync, } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { readFileSync, writeFileSync, accessSync, copyFileSync, constants, mkdirSync, } from "node:fs";
+import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { BaseAdapter } from "../base.js";
-import { buildNodeCommand, } from "../types.js";
+import { resolveCodexConfigDir } from "./paths.js";
+const PRE_TOOL_USE_MATCHER_PATTERN = "local_shell|shell|shell_command|exec_command|container.exec|functions\\.exec_command|Bash|Shell|apply_patch|functions\\.apply_patch|Edit|Write|grep_files|ctx_execute|ctx_execute_file|ctx_batch_execute|ctx_fetch_and_index|ctx_search|ctx_index|mcp__.*__ctx_execute|mcp__.*__ctx_execute_file|mcp__.*__ctx_batch_execute|mcp__.*__ctx_fetch_and_index|mcp__.*__ctx_search|mcp__.*__ctx_index";
+const CODEX_HOOK_COMMANDS = {
+    PreToolUse: "context-mode hook codex pretooluse",
+    PostToolUse: "context-mode hook codex posttooluse",
+    SessionStart: "context-mode hook codex sessionstart",
+    PreCompact: "context-mode hook codex precompact",
+    UserPromptSubmit: "context-mode hook codex userpromptsubmit",
+    Stop: "context-mode hook codex stop",
+};
+const LEGACY_HOOK_PATH_SUFFIXES = {
+    PreToolUse: ["hooks/pretooluse.mjs", "hooks/codex/pretooluse.mjs"],
+    PostToolUse: ["hooks/posttooluse.mjs", "hooks/codex/posttooluse.mjs"],
+    SessionStart: ["hooks/sessionstart.mjs", "hooks/codex/sessionstart.mjs"],
+    PreCompact: ["hooks/precompact.mjs", "hooks/codex/precompact.mjs"],
+    UserPromptSubmit: ["hooks/userpromptsubmit.mjs", "hooks/codex/userpromptsubmit.mjs"],
+    Stop: ["hooks/stop.mjs", "hooks/codex/stop.mjs"],
+};
+function getTomlSection(raw, sectionName) {
+    const lines = raw.split(/\r?\n/);
+    let inSection = false;
+    const body = [];
+    for (const line of lines) {
+        const section = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+        if (section) {
+            if (inSection)
+                break;
+            inSection = section[1]?.trim() === sectionName;
+            continue;
+        }
+        if (inSection)
+            body.push(line);
+    }
+    return inSection ? body.join("\n") : null;
+}
+function hasCodexHooksFeature(raw) {
+    const features = getTomlSection(raw, "features");
+    return features !== null && /^\s*hooks\s*=\s*true\s*(?:#.*)?$/mi.test(features);
+}
+function hasDeprecatedCodexHooksFeature(raw) {
+    const features = getTomlSection(raw, "features");
+    return features !== null && /^\s*codex_hooks\s*=\s*true\s*(?:#.*)?$/mi.test(features);
+}
+function ensureCodexHooksFeature(raw) {
+    if (hasCodexHooksFeature(raw))
+        return { text: raw, changed: false };
+    const newline = raw.includes("\r\n") ? "\r\n" : "\n";
+    const lines = raw.split(/\r?\n/);
+    const featuresIndex = lines.findIndex((line) => /^\s*\[features\]\s*(?:#.*)?$/.test(line));
+    if (featuresIndex === -1) {
+        const prefix = raw.length > 0 && !raw.endsWith("\n") ? newline : "";
+        return {
+            text: `${raw}${prefix}[features]${newline}hooks = true${newline}`,
+            changed: true,
+        };
+    }
+    let endIndex = lines.length;
+    for (let i = featuresIndex + 1; i < lines.length; i++) {
+        if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(lines[i] ?? "")) {
+            endIndex = i;
+            break;
+        }
+    }
+    for (let i = featuresIndex + 1; i < endIndex; i++) {
+        if (/^\s*hooks\s*=/.test(lines[i] ?? "")) {
+            lines[i] = "hooks = true";
+            return { text: lines.join(newline), changed: true };
+        }
+    }
+    lines.splice(featuresIndex + 1, 0, "hooks = true");
+    return { text: lines.join(newline), changed: true };
+}
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
 // ─────────────────────────────────────────────────────────
@@ -31,7 +101,7 @@ export class CodexAdapter extends BaseAdapter {
     capabilities = {
         preToolUse: true,
         postToolUse: true,
-        preCompact: false,
+        preCompact: true,
         sessionStart: true,
         canModifyArgs: false,
         canModifyOutput: false,
@@ -124,13 +194,9 @@ export class CodexAdapter extends BaseAdapter {
         return {};
     }
     formatPreCompactResponse(response) {
-        if (response.context) {
-            return {
-                hookSpecificOutput: {
-                    additionalContext: response.context,
-                },
-            };
-        }
+        // Codex PreCompact currently accepts only universal hook fields.
+        // The hook script stores snapshots in context-mode's DB; SessionStart
+        // injects them after compaction.
         return {};
     }
     formatSessionStartResponse(response) {
@@ -145,26 +211,40 @@ export class CodexAdapter extends BaseAdapter {
         return {};
     }
     // ── Configuration ──────────────────────────────────────
+    getConfigDir(_projectDir) {
+        return resolveCodexConfigDir();
+    }
     getSettingsPath() {
-        return resolve(homedir(), ".codex", "config.toml");
+        return join(this.getConfigDir(), "config.toml");
+    }
+    getSessionDir() {
+        const dir = join(this.getConfigDir(), "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
     }
+    // C2 narrowing (2026-05): the historical `getSessionDBPath` /
+    // `getSessionEventsPath` overrides were removed. Both delegated to the
+    // same canonical helpers (`resolveSessionDbPath` / `hashProjectDirCanonical`
+    // + `getWorktreeSuffix`) which already normalize the path internally —
+    // the explicit `normalizeWorktreePath` here was a no-op. Callers now reach
+    // the helpers directly through `adapter.getSessionDir()`.
     getInstructionFiles() {
         // Codex CLI honors AGENTS.md plus an optional override file.
         return ["AGENTS.md", "AGENTS.override.md"];
     }
     getMemoryDir() {
         // Codex uses "memories" (plural), not the default "memory".
-        return resolve(homedir(), ".codex", "memories");
+        return join(this.getConfigDir(), "memories");
     }
-    generateHookConfig(pluginRoot) {
+    generateHookConfig(_pluginRoot) {
         return {
             PreToolUse: [
                 {
-                    matcher: "local_shell|shell|shell_command|exec_command|container.exec|Bash|Shell|grep_files|mcp__plugin_context-mode_context-mode__ctx_execute|mcp__plugin_context-mode_context-mode__ctx_execute_file|mcp__plugin_context-mode_context-mode__ctx_batch_execute",
+                    matcher: PRE_TOOL_USE_MATCHER_PATTERN,
                     hooks: [
                         {
                             type: "command",
-                            command: buildNodeCommand(`${pluginRoot}/hooks/pretooluse.mjs`),
+                            command: CODEX_HOOK_COMMANDS.PreToolUse,
                         },
                     ],
                 },
@@ -175,7 +255,7 @@ export class CodexAdapter extends BaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: buildNodeCommand(`${pluginRoot}/hooks/posttooluse.mjs`),
+                            command: CODEX_HOOK_COMMANDS.PostToolUse,
                         },
                     ],
                 },
@@ -186,7 +266,18 @@ export class CodexAdapter extends BaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: buildNodeCommand(`${pluginRoot}/hooks/sessionstart.mjs`),
+                            command: CODEX_HOOK_COMMANDS.SessionStart,
+                        },
+                    ],
+                },
+            ],
+            PreCompact: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: CODEX_HOOK_COMMANDS.PreCompact,
                         },
                     ],
                 },
@@ -197,7 +288,7 @@ export class CodexAdapter extends BaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: buildNodeCommand(`${pluginRoot}/hooks/codex/userpromptsubmit.mjs`),
+                            command: CODEX_HOOK_COMMANDS.UserPromptSubmit,
                         },
                     ],
                 },
@@ -208,7 +299,7 @@ export class CodexAdapter extends BaseAdapter {
                     hooks: [
                         {
                             type: "command",
-                            command: buildNodeCommand(`${pluginRoot}/hooks/codex/stop.mjs`),
+                            command: CODEX_HOOK_COMMANDS.Stop,
                         },
                     ],
                 },
@@ -235,13 +326,81 @@ export class CodexAdapter extends BaseAdapter {
     }
     // ── Diagnostics (doctor) ─────────────────────────────────
     validateHooks(_pluginRoot) {
-        return [
-            {
-                check: "Hook support",
-                status: "pass",
-                message: "Codex CLI hooks are stable. Configure ~/.codex/hooks.json for PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, and Stop.",
-            },
-        ];
+        const results = [];
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            const enabled = hasCodexHooksFeature(raw);
+            const deprecatedOnly = !enabled && hasDeprecatedCodexHooksFeature(raw);
+            results.push({
+                check: "Codex hooks feature flag",
+                status: enabled ? "pass" : "fail",
+                message: enabled
+                    ? `[features].hooks enabled in ${this.getSettingsPath()}`
+                    : deprecatedOnly
+                        ? `[features].codex_hooks is deprecated; [features].hooks is missing in ${this.getSettingsPath()}`
+                        : `[features].hooks missing from ${this.getSettingsPath()}`,
+                ...(enabled ? {} : { fix: "context-mode upgrade" }),
+            });
+        }
+        catch {
+            results.push({
+                check: "Codex hooks feature flag",
+                status: "warn",
+                message: `Could not read ${this.getSettingsPath()}`,
+                fix: "context-mode upgrade",
+            });
+        }
+        const hookConfig = this.readHooksConfig();
+        if (!hookConfig.ok) {
+            if (hookConfig.reason === "missing") {
+                return results.concat([{
+                        check: "Hooks config",
+                        status: "fail",
+                        message: `No readable ${this.getHooksPath()} found`,
+                        fix: "Copy configs/codex/hooks.json to hooks.json or run context-mode upgrade",
+                    }]);
+            }
+            if (hookConfig.reason === "invalid_json") {
+                return results.concat([{
+                        check: "Hooks config",
+                        status: "fail",
+                        message: `${this.getHooksPath()} is not valid JSON: ${hookConfig.error}`,
+                        fix: "Repair hooks.json so it contains valid JSON, then rerun context-mode upgrade if needed",
+                    }]);
+            }
+            return results.concat([{
+                    check: "Hooks config",
+                    status: "fail",
+                    message: `Could not read ${this.getHooksPath()}: ${hookConfig.error}`,
+                    fix: "Check permissions and file accessibility for hooks.json, then rerun context-mode upgrade if needed",
+                }]);
+        }
+        if (!hookConfig.config.hooks) {
+            return results.concat([{
+                    check: "Hooks config",
+                    status: "fail",
+                    message: `${this.getHooksPath()} is missing the top-level hooks object`,
+                    fix: `Update ${this.getHooksPath()} to match configs/codex/hooks.json`,
+                }]);
+        }
+        const expected = this.generateHookConfig("");
+        return results.concat(Object.entries(expected).map(([hookName, entries]) => {
+            const actualEntries = hookConfig.config.hooks?.[hookName];
+            const expectedEntry = entries[0];
+            const ok = Array.isArray(actualEntries)
+                && actualEntries.some((entry) => this.isExpectedHookEntry(hookName, entry, expectedEntry));
+            const missingStatus = hookName === "PreCompact" ? "warn" : "fail";
+            return {
+                check: `${hookName} hook`,
+                status: ok ? "pass" : missingStatus,
+                message: ok
+                    ? `${hookName} hook configured in ${this.getHooksPath()}`
+                    : hookName === "PreCompact"
+                        ? `${hookName} hook missing or not pointing to context-mode; compaction snapshots require a Codex build that emits PreCompact`
+                        : `${hookName} hook missing or not pointing to context-mode`,
+                fix: ok ? undefined : `Update ${this.getHooksPath()} to match configs/codex/hooks.json`,
+            };
+        }));
     }
     checkPluginRegistration() {
         // Check for context-mode in [mcp_servers] section of config.toml
@@ -261,21 +420,21 @@ export class CodexAdapter extends BaseAdapter {
                     check: "MCP registration",
                     status: "fail",
                     message: "[mcp_servers] section exists but context-mode not found",
-                    fix: 'Add context-mode to [mcp_servers] in ~/.codex/config.toml',
+                    fix: `Add context-mode to [mcp_servers] in ${this.getSettingsPath()}`,
                 };
             }
             return {
                 check: "MCP registration",
                 status: "fail",
                 message: "No [mcp_servers] section in config.toml",
-                fix: 'Add [mcp_servers.context-mode] to ~/.codex/config.toml',
+                fix: `Add [mcp_servers.context-mode] to ${this.getSettingsPath()}`,
             };
         }
         catch {
             return {
                 check: "MCP registration",
                 status: "warn",
-                message: "Could not read ~/.codex/config.toml",
+                message: `Could not read ${this.getSettingsPath()}`,
             };
         }
     }
@@ -284,9 +443,69 @@ export class CodexAdapter extends BaseAdapter {
         return "not installed";
     }
     // ── Upgrade ────────────────────────────────────────────
-    configureAllHooks(_pluginRoot) {
-        // Codex CLI hook configuration is done via hooks.json, not config.toml
-        return [];
+    configureAllHooks(pluginRoot) {
+        const hookConfig = this.readHooksConfig();
+        const changes = [];
+        let hookFile;
+        if (hookConfig.ok) {
+            hookFile = hookConfig.config;
+        }
+        else if (hookConfig.reason === "missing") {
+            hookFile = { hooks: {} };
+        }
+        else if (hookConfig.reason === "invalid_json") {
+            const backupPath = this.backupFile(this.getHooksPath(), ".broken");
+            changes.push(`Backed up malformed Codex hooks to ${backupPath}`);
+            hookFile = { hooks: {} };
+        }
+        else {
+            throw new Error(`Failed to update ${this.getHooksPath()}: ${hookConfig.error}`);
+        }
+        const hooks = hookFile.hooks && typeof hookFile.hooks === "object" && !Array.isArray(hookFile.hooks)
+            ? hookFile.hooks
+            : {};
+        const desiredHooks = this.generateHookConfig(pluginRoot);
+        for (const [hookName, entries] of Object.entries(desiredHooks)) {
+            this.upsertManagedHookEntry(hooks, hookName, entries[0], changes);
+        }
+        if (changes.length > 0) {
+            hookFile.hooks = hooks;
+            this.writeHooksConfig(hookFile);
+            changes.push(`Wrote native Codex hooks to ${this.getHooksPath()}`);
+        }
+        const settingsPath = this.getSettingsPath();
+        let settingsRaw = "";
+        try {
+            settingsRaw = readFileSync(settingsPath, "utf-8");
+        }
+        catch {
+            settingsRaw = "";
+        }
+        const enabledSettings = ensureCodexHooksFeature(settingsRaw);
+        if (enabledSettings.changed) {
+            const newline = enabledSettings.text.includes("\r\n") ? "\r\n" : "\n";
+            const text = enabledSettings.text.endsWith("\n")
+                ? enabledSettings.text
+                : `${enabledSettings.text}${newline}`;
+            mkdirSync(dirname(settingsPath), { recursive: true });
+            writeFileSync(settingsPath, text, "utf-8");
+            changes.push("Enabled Codex hooks feature flag");
+        }
+        return changes;
+    }
+    backupSettings() {
+        let firstBackupPath = null;
+        for (const settingsPath of [this.getHooksPath(), this.getSettingsPath()]) {
+            try {
+                accessSync(settingsPath, constants.R_OK);
+                const backupPath = this.backupFile(settingsPath);
+                firstBackupPath ??= backupPath;
+            }
+            catch {
+                continue;
+            }
+        }
+        return firstBackupPath;
     }
     setHookPermissions(_pluginRoot) {
         // Hook permissions are set during plugin install
@@ -316,6 +535,87 @@ export class CodexAdapter extends BaseAdapter {
     getProjectDir(input) {
         return input.cwd ?? process.env.CODEX_PROJECT_DIR ?? process.cwd();
     }
+    getHooksPath() {
+        return join(this.getConfigDir(), "hooks.json");
+    }
+    backupFile(filePath, suffix = "") {
+        const backupPath = suffix
+            ? `${filePath}${suffix}-${new Date().toISOString().replace(/[:.]/g, "-")}.bak`
+            : `${filePath}.bak`;
+        copyFileSync(filePath, backupPath);
+        return backupPath;
+    }
+    readHooksConfig() {
+        const hooksPath = this.getHooksPath();
+        try {
+            return { ok: true, config: JSON.parse(readFileSync(hooksPath, "utf-8")) };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? String(error.code ?? "")
+                : "";
+            if (code === "ENOENT") {
+                return { ok: false, reason: "missing" };
+            }
+            if (error instanceof SyntaxError) {
+                return { ok: false, reason: "invalid_json", error: message };
+            }
+            return { ok: false, reason: "read_error", error: message };
+        }
+    }
+    writeHooksConfig(config) {
+        const hooksPath = this.getHooksPath();
+        mkdirSync(dirname(hooksPath), { recursive: true });
+        writeFileSync(hooksPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    }
+    upsertManagedHookEntry(hooks, hookName, expectedEntry, changes) {
+        const currentEntries = Array.isArray(hooks[hookName]) ? [...hooks[hookName]] : [];
+        const managedIndices = currentEntries
+            .map((entry, index) => this.isManagedContextModeEntry(hookName, entry) ? index : -1)
+            .filter((index) => index >= 0);
+        if (managedIndices.length === 0) {
+            currentEntries.push(expectedEntry);
+            hooks[hookName] = currentEntries;
+            changes.push(`Added ${hookName} hook`);
+            return;
+        }
+        const primaryIndex = managedIndices[0];
+        if (JSON.stringify(currentEntries[primaryIndex]) !== JSON.stringify(expectedEntry)) {
+            currentEntries[primaryIndex] = expectedEntry;
+            changes.push(`Updated ${hookName} hook`);
+        }
+        for (const duplicateIndex of managedIndices.slice(1).reverse()) {
+            currentEntries.splice(duplicateIndex, 1);
+            changes.push(`Removed duplicate ${hookName} context-mode hook`);
+        }
+        hooks[hookName] = currentEntries;
+    }
+    isExpectedHookEntry(hookName, entry, expectedEntry) {
+        if (!entry || typeof entry !== "object")
+            return false;
+        if (hookName === "PreToolUse" && entry.matcher !== expectedEntry.matcher) {
+            return false;
+        }
+        return this.entryContainsManagedCommand(hookName, entry);
+    }
+    isManagedContextModeEntry(hookName, entry) {
+        if (!entry || typeof entry !== "object")
+            return false;
+        return this.entryContainsManagedCommand(hookName, entry);
+    }
+    entryContainsManagedCommand(hookName, entry) {
+        const normalizedCommands = (Array.isArray(entry.hooks) ? entry.hooks : [])
+            .map((hook) => this.normalizeCommand(hook.command))
+            .filter((command) => command.length > 0);
+        const expectedCliCommand = this.normalizeCommand(CODEX_HOOK_COMMANDS[hookName] ?? "");
+        const legacySuffixes = LEGACY_HOOK_PATH_SUFFIXES[hookName] ?? [];
+        return normalizedCommands.some((command) => command.includes(expectedCliCommand)
+            || legacySuffixes.some((suffix) => command.includes(suffix)));
+    }
+    normalizeCommand(command) {
+        return (command ?? "").replace(/\\/g, "/");
+    }
     /**
      * Extract session ID from Codex CLI hook input.
      * Priority: session_id field > fallback to ppid.

package/build/adapters/codex/paths.d.ts

@@ -0,0 +1 @@
+export declare function resolveCodexConfigDir(): string;

package/build/adapters/codex/paths.js

@@ -0,0 +1,12 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+export function resolveCodexConfigDir() {
+    const envVal = process.env.CODEX_HOME;
+    if (envVal) {
+        if (envVal.startsWith("~")) {
+            return resolve(homedir(), envVal.replace(/^~[/\\]?/, ""));
+        }
+        return resolve(envVal);
+    }
+    return resolve(homedir(), ".codex");
+}

package/build/adapters/cursor/index.d.ts

@@ -43,6 +43,12 @@ export declare class CursorAdapter extends BaseAdapter implements HookAdapter {
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;
     validateHooks(_pluginRoot: string): DiagnosticResult[];
+    /**
+     * Detects context-mode plugin installations under Cursor's plugin directories.
+     * Returns absolute paths to any `.cursor-plugin/plugin.json` files whose
+     * `name` matches `context-mode`.
+     */
+    private detectPluginInstalls;
     checkPluginRegistration(): DiagnosticResult;
     getInstalledVersion(): string;
     configureAllHooks(_pluginRoot: string): string[];