context-mode 1.0.161 → 1.0.163

package/build/adapters/antigravity-cli/index.js

@@ -0,0 +1,341 @@
+/**
+ * adapters/antigravity-cli — Google Antigravity CLI (`agy`) adapter.
+ *
+ * Integration: MCP tools plus agy's Claude-compatible hook surface. `agy`
+ * reads its global MCP profile from `~/.gemini/config/mcp_config.json`
+ * (distinct from the Antigravity IDE's `~/.gemini/antigravity/mcp_config.json`)
+ * and hooks from `~/.gemini/config/hooks.json`, or from an installed agy
+ * plugin's root `hooks.json`.
+ *
+ * context-mode wires only the surfaces that have a verified mapping:
+ *   - PreToolUse for bounded routing enforcement on Bash/Read/Grep/WebFetch
+ *   - PostToolUse capture for executed tool calls
+ *   - best-effort Stop capture for session-end continuity when agy emits it
+ *
+ * PreInvocation/PostInvocation are intentionally not registered here: there is
+ * no verified payload/response contract or shared context-mode pipeline target
+ * for those agy events yet.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { AntigravityAdapter } from "../antigravity/index.js";
+import { parseJsonc } from "../../util/jsonc.js";
+export function antigravityCliMcpConfigPath() {
+    return resolve(homedir(), ".gemini", "config", "mcp_config.json");
+}
+export function antigravityCliConfigDir() {
+    return resolve(homedir(), ".gemini", "antigravity-cli");
+}
+/** agy reads user hooks from ~/.gemini/config/hooks.json (sibling of mcp_config.json). */
+export function antigravityCliHooksPath() {
+    return resolve(homedir(), ".gemini", "config", "hooks.json");
+}
+/**
+ * `agy plugin install <bundle>` registers MCP + hook + skill into agy's plugin
+ * profile under ~/.gemini/config/plugins/<name>/ (verified on agy 1.0.6) — the
+ * canonical install. The global mcp_config.json / hooks.json paths above are the
+ * manual (no-plugin) fallback. doctor must recognize BOTH.
+ */
+export function antigravityCliPluginDir() {
+    return resolve(homedir(), ".gemini", "config", "plugins", "context-mode");
+}
+function antigravityCliPluginMcpPath() {
+    return resolve(antigravityCliPluginDir(), "mcp_config.json");
+}
+function antigravityCliPluginHooksPath() {
+    return resolve(antigravityCliPluginDir(), "hooks.json");
+}
+/** True if context-mode's MCP is registered in any agy profile (plugin or global). */
+function readMcpRegistered(paths) {
+    for (const path of paths) {
+        try {
+            const config = parseJsonc(readFileSync(path, "utf-8")) ?? {};
+            const mcpServers = config?.mcpServers ?? {};
+            if ("context-mode" in mcpServers)
+                return { ok: true, where: path };
+        }
+        catch {
+            /* unreadable/missing — try next */
+        }
+    }
+    return { ok: false };
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function agyProjectDir(raw) {
+    // Refs-backed FIRST: the only real upstream hook-payload example
+    // (refs/platforms/antigravity-cli/examples/title/title.sh:10, README.md:11)
+    // reads the working directory from `workspace.current_dir` — an OBJECT field,
+    // not an array. Prefer it.
+    const workspace = asRecord(raw.workspace);
+    if (typeof workspace.current_dir === "string" && workspace.current_dir) {
+        return workspace.current_dir;
+    }
+    // Fallback: `workspacePaths[0]` is empirically-derived/unverified (no upstream
+    // doc or example confirms this shape) — retained as a defensive fallback only.
+    const workspacePaths = raw.workspacePaths;
+    return Array.isArray(workspacePaths) && workspacePaths.length > 0
+        ? String(workspacePaths[0])
+        : undefined;
+}
+function agySessionId(raw) {
+    // `conversationId` is empirically-derived/unverified — no upstream agy doc or
+    // example confirms a session-id field in the hook payload. Kept as the
+    // best-available identifier; falls back to the process id when absent.
+    return typeof raw.conversationId === "string" && raw.conversationId
+        ? raw.conversationId
+        : `pid-${process.ppid}`;
+}
+function hookEntryHasCommand(entry, command) {
+    const e = asRecord(entry);
+    const nested = Array.isArray(e.hooks) ? e.hooks : [];
+    return nested.some((hook) => asRecord(hook).command === command);
+}
+function hookEntryJsonHasCommand(entry, command) {
+    return JSON.stringify(entry).includes(command);
+}
+function matcherCoversAgyPreToolUse(matcher) {
+    if (typeof matcher !== "string")
+        return false;
+    return ["run_command", "view_file", "grep_search", "web_fetch", "read_url_content"].every((tool) => matcher.includes(tool));
+}
+function hookGroupHasCommand(group, command) {
+    return Array.isArray(group) && group.some((entry) => hookEntryHasCommand(entry, command));
+}
+function hookGroupHasPreToolUse(group) {
+    return Array.isArray(group) && group.some((entry) => {
+        const e = asRecord(entry);
+        return matcherCoversAgyPreToolUse(e.matcher) && hookEntryHasCommand(entry, PRE_HOOK_COMMAND);
+    });
+}
+/** True if all context-mode agy hooks are registered in plugin/global profiles. */
+function readRegisteredHooks(paths) {
+    const found = { preOk: false, postOk: false, stopOk: false, where: undefined };
+    for (const path of paths) {
+        try {
+            const config = parseJsonc(readFileSync(path, "utf-8")) ?? {};
+            const hooks = config.hooks ?? {};
+            const preOk = hookGroupHasPreToolUse(hooks.PreToolUse);
+            const postOk = hookGroupHasCommand(hooks.PostToolUse, POST_HOOK_COMMAND);
+            const stopOk = hookGroupHasCommand(hooks.Stop, STOP_HOOK_COMMAND);
+            if ((preOk || postOk || stopOk) && !found.where)
+                found.where = path;
+            found.preOk ||= preOk;
+            found.postOk ||= postOk;
+            found.stopOk ||= stopOk;
+        }
+        catch {
+            /* unreadable/missing — try next */
+        }
+    }
+    // Stop is registered when possible, but agy 1.0.6 `-p` probes did not emit it.
+    // Treat it as best-effort so doctor does not mark a working Pre/Post install
+    // as degraded solely because Stop is absent.
+    return { ...found, ok: found.preOk && found.postOk };
+}
+/** Dispatcher commands agy invokes from hooks.json. */
+const PRE_HOOK_COMMAND = "context-mode hook antigravity-cli pretooluse";
+const PRE_HOOK_MATCHER = "run_command|view_file|grep_search|web_fetch|read_url_content";
+const POST_HOOK_COMMAND = "context-mode hook antigravity-cli posttooluse";
+const STOP_HOOK_COMMAND = "context-mode hook antigravity-cli stop";
+// Keep in sync with the identical agyContextReason in hooks/core/formatters.mjs:
+// two copies exist because the bundled .mjs formatter (runtime hook path) and
+// this TS adapter are separate layers; the deny-reason text must not drift.
+function agyContextReason(additionalContext) {
+    const text = String(additionalContext ?? "")
+        .replace(/<\/?context_guidance>/g, " ")
+        .replace(/<\/?tip>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return text
+        ? `context-mode: use the context-mode MCP tools instead of this native tool. ${text}`
+        : "context-mode: use the context-mode MCP tools instead of this native tool so raw bytes stay out of the conversation.";
+}
+function configureHookEntry(hooks, type, desired, command) {
+    const current = Array.isArray(hooks[type]) ? hooks[type] : [];
+    const desiredJson = JSON.stringify(desired);
+    const alreadyExact = current.some((entry) => JSON.stringify(entry) === desiredJson) &&
+        current.every((entry) => !hookEntryJsonHasCommand(entry, command) || JSON.stringify(entry) === desiredJson);
+    if (alreadyExact)
+        return false;
+    hooks[type] = [
+        ...current.filter((entry) => !hookEntryJsonHasCommand(entry, command)),
+        desired,
+    ];
+    return true;
+}
+export class AntigravityCliAdapter extends AntigravityAdapter {
+    name = "Antigravity CLI";
+    paradigm = "json-stdio";
+    capabilities = {
+        preToolUse: true,
+        postToolUse: true,
+        preCompact: false,
+        sessionStart: false,
+        canModifyArgs: false,
+        canModifyOutput: false,
+        canInjectSessionContext: false,
+    };
+    getSettingsPath() {
+        return antigravityCliMcpConfigPath();
+    }
+    getConfigDir(_projectDir) {
+        return antigravityCliConfigDir();
+    }
+    parsePreToolUseInput(raw) {
+        const payload = asRecord(raw);
+        const toolCall = asRecord(payload.toolCall);
+        return {
+            toolName: typeof toolCall.name === "string" ? toolCall.name : "",
+            toolInput: asRecord(toolCall.args),
+            sessionId: agySessionId(payload),
+            projectDir: agyProjectDir(payload),
+            raw,
+        };
+    }
+    parsePostToolUseInput(raw) {
+        const payload = asRecord(raw);
+        const toolCall = asRecord(payload.toolCall);
+        const error = typeof payload.error === "string" ? payload.error : "";
+        return {
+            toolName: typeof toolCall.name === "string" ? toolCall.name : "",
+            toolInput: asRecord(toolCall.args),
+            toolOutput: error,
+            isError: error.length > 0,
+            sessionId: agySessionId(payload),
+            projectDir: agyProjectDir(payload),
+            raw,
+        };
+    }
+    formatPreToolUseResponse(response) {
+        if (response.decision === "deny") {
+            return { decision: "deny", reason: response.reason ?? "Denied by context-mode" };
+        }
+        if (response.decision === "ask") {
+            // Fallback reason so a security-policy ask is never a bare prompt
+            // (mirrors hooks/core/formatters.mjs antigravity-cli.ask).
+            return {
+                decision: "ask",
+                reason: response.reason ?? "Action requires user confirmation",
+            };
+        }
+        if (response.decision === "context" && response.additionalContext) {
+            return {
+                decision: "deny",
+                reason: agyContextReason(response.additionalContext),
+            };
+        }
+        return null;
+    }
+    formatPostToolUseResponse(_response) {
+        return undefined;
+    }
+    checkPluginRegistration() {
+        // Accept the plugin profile (the canonical `agy plugin install` location,
+        // ~/.gemini/config/plugins/context-mode/mcp_config.json) OR the global
+        // mcp_config.json (the manual no-plugin fallback).
+        const { ok, where } = readMcpRegistered([
+            antigravityCliPluginMcpPath(),
+            this.getSettingsPath(),
+        ]);
+        if (ok) {
+            return {
+                check: "MCP registration",
+                status: "pass",
+                message: `context-mode found in Antigravity CLI mcpServers (${where})`,
+            };
+        }
+        return {
+            check: "MCP registration",
+            status: "fail",
+            message: "context-mode not found in Antigravity CLI mcpServers",
+            fix: "npm run install:agy",
+        };
+    }
+    getInstalledVersion() {
+        // Plugin install: read the real version from the installed plugin manifest so
+        // the doctor compares a true semver against npm latest (PASS when current,
+        // a meaningful "outdated bundle" WARN otherwise) — not the literal "configured"
+        // which produced the bogus "vconfigured, latest vX" line.
+        try {
+            const manifest = parseJsonc(readFileSync(resolve(antigravityCliPluginDir(), "plugin.json"), "utf-8"));
+            if (manifest && typeof manifest.version === "string" && manifest.version) {
+                return manifest.version;
+            }
+        }
+        catch {
+            /* not plugin-installed — fall through */
+        }
+        // Manual (global-profile) registration has no plugin manifest: report the
+        // version-less "standalone" MCP mode so doctor shows INFO, not a false WARN.
+        if (readMcpRegistered([this.getSettingsPath()]).ok)
+            return "standalone";
+        return "not installed";
+    }
+    /**
+     * Write/merge the agy hooks into ~/.gemini/config/hooks.json (manual,
+     * non-plugin path). Idempotent — unrelated hook entries are preserved.
+     */
+    configureAllHooks(_pluginRoot) {
+        const changes = [];
+        const hooksPath = antigravityCliHooksPath();
+        let config = {};
+        try {
+            config = parseJsonc(readFileSync(hooksPath, "utf-8")) ?? {};
+        }
+        catch {
+            /* fresh file */
+        }
+        const hooks = config.hooks ?? {};
+        const desiredPre = {
+            matcher: PRE_HOOK_MATCHER,
+            hooks: [{ type: "command", command: PRE_HOOK_COMMAND }],
+        };
+        const desiredPost = {
+            matcher: "",
+            hooks: [{ type: "command", command: POST_HOOK_COMMAND }],
+        };
+        const desiredStop = {
+            matcher: "",
+            hooks: [{ type: "command", command: STOP_HOOK_COMMAND }],
+        };
+        const changedPre = configureHookEntry(hooks, "PreToolUse", desiredPre, PRE_HOOK_COMMAND);
+        const changedPost = configureHookEntry(hooks, "PostToolUse", desiredPost, POST_HOOK_COMMAND);
+        const changedStop = configureHookEntry(hooks, "Stop", desiredStop, STOP_HOOK_COMMAND);
+        const changed = changedPre || changedPost || changedStop;
+        if (changed) {
+            config.hooks = hooks;
+            mkdirSync(dirname(hooksPath), { recursive: true });
+            writeFileSync(hooksPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+            changes.push(`Configured Antigravity CLI PreToolUse/PostToolUse hooks and best-effort Stop hook in ${hooksPath}`);
+        }
+        return changes;
+    }
+    /** Report agy hook status across plugin and manual profiles. */
+    validateHooks(_pluginRoot) {
+        // Accept the plugin profile (the canonical `agy plugin install` location,
+        // ~/.gemini/config/plugins/context-mode/hooks.json) OR the global hooks.json
+        // (the manual `context-mode upgrade` fallback).
+        const { ok, where, preOk, postOk, stopOk } = readRegisteredHooks([
+            antigravityCliPluginHooksPath(),
+            antigravityCliHooksPath(),
+        ]);
+        const missing = [
+            preOk ? null : "PreToolUse",
+            postOk ? null : "PostToolUse",
+            // Stop is best-effort; do not include it in the health gate.
+        ].filter(Boolean).join(", ");
+        return [
+            {
+                check: "Antigravity CLI hooks",
+                status: ok ? "pass" : "warn",
+                message: ok
+                    ? `PreToolUse guard and PostToolUse capture configured in ${where}${stopOk ? "; best-effort Stop hook also configured" : ""}`
+                    : `Antigravity CLI hooks incomplete (${missing || "none found"} missing) — MCP tools still work, but bounded routing enforcement and session capture are degraded. Run \`npm run install:agy\` (agy plugin) or \`context-mode upgrade\` to repair hooks.`,
+                ...(ok ? {} : { fix: "npm run install:agy" }),
+            },
+        ];
+    }
+}

package/build/adapters/claude-code/hooks.d.ts

@@ -22,6 +22,7 @@ export declare const HOOK_TYPES: {
     readonly PRE_COMPACT: "PreCompact";
     readonly SESSION_START: "SessionStart";
     readonly USER_PROMPT_SUBMIT: "UserPromptSubmit";
+    readonly STOP: "Stop";
 };
 export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
 /**

package/build/adapters/claude-code/hooks.js

@@ -26,6 +26,7 @@ export const HOOK_TYPES = {
     PRE_COMPACT: "PreCompact",
     SESSION_START: "SessionStart",
     USER_PROMPT_SUBMIT: "UserPromptSubmit",
+    STOP: "Stop",
 };
 // ─────────────────────────────────────────────────────────
 // PreToolUse matchers
@@ -102,6 +103,7 @@ export const HOOK_SCRIPTS = {
     PreCompact: "precompact.mjs",
     SessionStart: "sessionstart.mjs",
     UserPromptSubmit: "userpromptsubmit.mjs",
+    Stop: "stop.mjs",
 };
 // ─────────────────────────────────────────────────────────
 // Hook validation
@@ -116,6 +118,7 @@ export const OPTIONAL_HOOKS = [
     HOOK_TYPES.POST_TOOL_USE,
     HOOK_TYPES.PRE_COMPACT,
     HOOK_TYPES.USER_PROMPT_SUBMIT,
+    HOOK_TYPES.STOP,
 ];
 /**
  * Check if a hook entry points to a context-mode hook script.

package/build/adapters/claude-code/index.js

@@ -87,7 +87,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
         //     available, else `process.execPath` (#369 PATH resolution on Git
         //     Bash, #738 bun cold-start win).
         // Pre-D3 we hand-rolled `node "${pluginRoot}/hooks/X.mjs"` for all
-        // five events; bare `node` made claude-code the lone outlier and
+        // six events; bare `node` made claude-code the lone outlier and
         // dropping the execPath swap re-opened the Windows class. Algo-D3.5
         // (CI invariant in tests/adapters/claude-code.test.ts) locks this in
         // for adapter #16.
@@ -142,6 +142,17 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                     ],
                 },
             ],
+            Stop: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "command",
+                            command: buildHookRuntimeCommand(`${pluginRoot}/hooks/stop.mjs`),
+                        },
+                    ],
+                },
+            ],
         };
     }
     readSettings() {
@@ -396,10 +407,18 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
                 changes.push(`Removed ${removed} stale ${hookType} hook(s)`);
             }
         }
-        // If plugin hooks.json already covers all required hooks, skip settings.json
-        // registration entirely (Issue #198). Plugin installs don't need settings.json
-        // entries — hooks.json with ${CLAUDE_PLUGIN_ROOT} is the source of truth.
-        const pluginHooks = this.readPluginHooks(pluginRoot);
+        // If plugin hooks.json already covers all required hooks AND context-mode is
+        // actually installed as a Claude Code plugin (present in enabledPlugins), skip
+        // settings.json registration — hooks.json with ${CLAUDE_PLUGIN_ROOT} is the
+        // source of truth for plugin installs (Issue #198).
+        //
+        // Standalone / MacPorts installs are NOT in enabledPlugins. For those, the
+        // hooks/hooks.json shipped in the npm package is never consulted by Claude Code
+        // (it uses ${CLAUDE_PLUGIN_ROOT} which is only set in plugin mode). We must
+        // always write absolute-path hook commands to settings.json in that case.
+        const pluginRegistration = this.checkPluginRegistration();
+        const isPluginInstall = pluginRegistration.status === "pass";
+        const pluginHooks = isPluginInstall ? this.readPluginHooks(pluginRoot) : undefined;
         if (pluginHooks) {
             const allCovered = REQUIRED_HOOKS.every((ht) => this.checkHookType(undefined, pluginHooks, ht));
             if (allCovered) {

package/build/adapters/client-map.js

@@ -10,8 +10,13 @@ export const CLIENT_NAME_TO_PLATFORM = {
     "claude-code": "claude-code",
     "gemini-cli-mcp-client": "gemini-cli",
     "antigravity-client": "antigravity",
+    "antigravity-cli": "antigravity-cli",
+    "agy": "antigravity-cli",
     "cursor-vscode": "cursor",
     "Visual-Studio-Code": "vscode-copilot",
+    "copilot-cli": "copilot-cli",
+    "GitHub Copilot CLI": "copilot-cli",
+    "github-copilot-cli": "copilot-cli",
     "JetBrains Client": "jetbrains-copilot",
     "IntelliJ IDEA": "jetbrains-copilot",
     "PyCharm": "jetbrains-copilot",

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

@@ -13,7 +13,11 @@
  * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
  *
  * Known limitations:
- *   - PreToolUse: deny works, updatedInput not yet supported (openai/codex#18491)
+ *   - PreToolUse: deny works on all builds. permissionDecision:"allow" +
+ *     updatedInput (command rewrite) and additionalContext are honored on
+ *     codex-cli >= 0.141.0 (#845), detected at runtime by
+ *     hooks/core/codex-caps.mjs; older builds fail closed (redirect → deny).
+ *     `ask` remains unsupported.
  *   - PostToolUse: updatedMCPToolOutput parsed but logged as unsupported
  *   - PostToolUse does not fire on failing Bash calls (upstream bug)
  */

package/build/adapters/codex/hooks.js

@@ -13,7 +13,11 @@
  * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
  *
  * Known limitations:
- *   - PreToolUse: deny works, updatedInput not yet supported (openai/codex#18491)
+ *   - PreToolUse: deny works on all builds. permissionDecision:"allow" +
+ *     updatedInput (command rewrite) and additionalContext are honored on
+ *     codex-cli >= 0.141.0 (#845), detected at runtime by
+ *     hooks/core/codex-caps.mjs; older builds fail closed (redirect → deny).
+ *     `ask` remains unsupported.
  *   - PostToolUse: updatedMCPToolOutput parsed but logged as unsupported
  *   - PostToolUse does not fire on failing Bash calls (upstream bug)
  */

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

@@ -20,9 +20,14 @@ type CodexVersionRunner = (file: string, args: string[], options: {
     stdio: ["ignore", "pipe", "ignore"];
     timeout: number;
 }) => string | Buffer;
+interface CodexAdapterOptions {
+    codexPluginListRunner?: CodexVersionRunner;
+}
 export declare function probeCodexCliVersion(runCommand?: CodexVersionRunner): string | null;
+export declare function parseCodexContextModePluginRoot(raw: string): string | null;
 export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
-    constructor();
+    private readonly codexPluginListRunner;
+    constructor(options?: CodexAdapterOptions);
     readonly name = "Codex CLI";
     readonly paradigm: HookParadigm;
     readonly capabilities: PlatformCapabilities;
@@ -65,6 +70,9 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
     private upsertManagedHookEntry;
     private removeManagedHookEntries;
     private hasCodexPluginHookManifest;
+    private getCodexPluginHookStatus;
+    private probeCodexContextModePluginRoot;
+    private samePath;
     private pruneStaleUserHookTrustState;
     private isExpectedHookEntry;
     private isManagedContextModeEntry;

package/build/adapters/codex/index.js

@@ -75,6 +75,14 @@ export function probeCodexCliVersion(runCommand = execFileSync) {
         return null;
     }
 }
+export function parseCodexContextModePluginRoot(raw) {
+    for (const line of raw.split(/\r?\n/)) {
+        const match = line.match(/^\s*context-mode@context-mode\s+installed,\s+enabled\s+\S+\s+(.+?)\s*$/);
+        if (match?.[1])
+            return match[1].trim();
+    }
+    return null;
+}
 function getTomlSection(raw, sectionName) {
     const lines = raw.split(/\r?\n/);
     let inSection = false;
@@ -190,8 +198,10 @@ function parseTomlQuotedString(raw) {
 // Adapter implementation
 // ─────────────────────────────────────────────────────────
 export class CodexAdapter extends BaseAdapter {
-    constructor() {
+    codexPluginListRunner;
+    constructor(options = {}) {
         super([".codex"]);
+        this.codexPluginListRunner = options.codexPluginListRunner ?? execFileSync;
     }
     name = "Codex CLI";
     paradigm = "json-stdio";
@@ -479,13 +489,35 @@ export class CodexAdapter extends BaseAdapter {
             });
         }
         const expected = this.generateHookConfig("");
-        const codexPluginEnabled = settingsReadable && hasCodexPluginEnabled(settingsRaw);
-        const codexPluginHooksAvailable = codexPluginEnabled && this.hasCodexPluginHookManifest(pluginRoot);
+        const pluginHookStatus = this.getCodexPluginHookStatus(pluginRoot, settingsRaw, settingsReadable);
+        const codexPluginEnabled = pluginHookStatus.enabled;
+        const codexPluginHooksAvailable = pluginHookStatus.hooksAvailable;
+        if (codexPluginEnabled && pluginHookStatus.runtimeRoot) {
+            results.push({
+                check: "Codex plugin root",
+                status: pluginHookStatus.rootMismatch ? "warn" : "pass",
+                message: pluginHookStatus.rootMismatch
+                    ? `context-mode doctor is running from ${pluginHookStatus.configuredRoot}, but Codex plugin manager reports ${pluginHookStatus.runtimeRoot}`
+                    : `Codex plugin manager reports ${pluginHookStatus.runtimeRoot}`,
+                ...(pluginHookStatus.rootMismatch
+                    ? { fix: "Restart Codex after upgrade; run context-mode upgrade to keep native user-hook fallback until the plugin root converges" }
+                    : {}),
+            });
+        }
+        else if (codexPluginEnabled) {
+            results.push({
+                check: "Codex plugin root",
+                status: "warn",
+                message: "context-mode@context-mode is enabled, but `codex plugin list` did not report its runtime root",
+                fix: "Restart Codex or verify `codex plugin list` shows context-mode@context-mode installed and enabled",
+            });
+        }
         if (codexPluginEnabled && !codexPluginHooksAvailable) {
+            const expectedRoot = pluginHookStatus.runtimeRoot ?? pluginRoot;
             results.push({
                 check: "Codex plugin hooks",
                 status: "fail",
-                message: `context-mode Codex plugin is enabled, but ${join(pluginRoot, ".codex-plugin", "hooks.json")} is missing`,
+                message: `context-mode Codex plugin is enabled, but ${join(expectedRoot, ".codex-plugin", "hooks.json")} is missing`,
                 fix: "Reinstall or upgrade the context-mode Codex plugin",
             });
         }
@@ -659,7 +691,8 @@ export class CodexAdapter extends BaseAdapter {
         catch {
             settingsRaw = "";
         }
-        const codexPluginOwnsHooks = hasCodexPluginEnabled(settingsRaw) && this.hasCodexPluginHookManifest(pluginRoot);
+        const pluginHookStatus = this.getCodexPluginHookStatus(pluginRoot, settingsRaw, settingsRaw.length > 0);
+        const codexPluginOwnsHooks = pluginHookStatus.ownsHooksForUpgrade;
         let hookFile;
         if (hookConfig.ok) {
             hookFile = hookConfig.config;
@@ -839,6 +872,55 @@ export class CodexAdapter extends BaseAdapter {
     hasCodexPluginHookManifest(pluginRoot) {
         return existsSync(join(pluginRoot, ".codex-plugin", "hooks.json"));
     }
+    getCodexPluginHookStatus(pluginRoot, settingsRaw, settingsReadable) {
+        const enabled = settingsReadable && hasCodexPluginEnabled(settingsRaw);
+        const configuredRoot = resolve(pluginRoot);
+        const configuredManifestAvailable = this.hasCodexPluginHookManifest(configuredRoot);
+        const runtimeRoot = enabled ? this.probeCodexContextModePluginRoot() : null;
+        const runtimeManifestAvailable = runtimeRoot
+            ? this.hasCodexPluginHookManifest(runtimeRoot)
+            : false;
+        const rootMismatch = runtimeRoot
+            ? !this.samePath(configuredRoot, runtimeRoot)
+            : false;
+        const hooksAvailable = enabled && (runtimeManifestAvailable
+            || (!runtimeRoot && configuredManifestAvailable));
+        return {
+            enabled,
+            configuredRoot,
+            configuredManifestAvailable,
+            runtimeRoot,
+            runtimeManifestAvailable,
+            rootMismatch,
+            hooksAvailable,
+            ownsHooksForUpgrade: enabled
+                && runtimeRoot !== null
+                && runtimeManifestAvailable
+                && !rootMismatch,
+        };
+    }
+    probeCodexContextModePluginRoot() {
+        try {
+            const output = process.platform === "win32"
+                ? this.codexPluginListRunner("cmd.exe", ["/d", "/s", "/c", "codex plugin list"], {
+                    encoding: "utf-8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                    timeout: 5000,
+                })
+                : this.codexPluginListRunner("codex", ["plugin", "list"], {
+                    encoding: "utf-8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                    timeout: 5000,
+                });
+            return parseCodexContextModePluginRoot(String(output));
+        }
+        catch {
+            return null;
+        }
+    }
+    samePath(left, right) {
+        return this.normalizeCommand(resolve(left)) === this.normalizeCommand(resolve(right));
+    }
     pruneStaleUserHookTrustState(settingsRaw, hooks) {
         const hooksPath = this.normalizeCommand(this.getHooksPath());
         const eventNames = {

package/build/adapters/copilot-cli/hooks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * adapters/copilot-cli/hooks — GitHub Copilot CLI hook definitions.
+ *
+ * GitHub Copilot CLI's native hook events are the camelCase names
+ * preToolUse / postToolUse / sessionStart / userPromptSubmitted / agentStop /
+ * preCompact. Per the copilot-cli changelog, PascalCase event names are ALSO
+ * accepted and fire — the CLI loads hook configs across VS Code, Claude Code,
+ * and the CLI by accepting PascalCase event names alongside camelCase
+ * (copilot-cli changelog.md:1065; see also :811 and :1081). We register the
+ * camelCase KEYS below because they are the CLI's native names, not because
+ * PascalCase would fail. The CLI dispatch token (the `.mjs` script base, e.g.
+ * `pretooluse`) is independent and stays lowercase via buildHookCommand, so
+ * changing the event casing does not change the dispatcher.
+ */
+export declare const HOOK_TYPES: {
+    readonly PRE_TOOL_USE: "preToolUse";
+    readonly POST_TOOL_USE: "postToolUse";
+    readonly PRE_COMPACT: "preCompact";
+    readonly SESSION_START: "sessionStart";
+    readonly USER_PROMPT_SUBMIT: "userPromptSubmitted";
+    readonly STOP: "agentStop";
+};
+export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
+export declare const HOOK_SCRIPTS: Record<string, string>;
+export declare const REQUIRED_HOOKS: HookType[];
+export declare const OPTIONAL_HOOKS: HookType[];
+export declare function isContextModeHook(entry: {
+    command?: string;
+    hooks?: Array<{
+        command?: string;
+    }>;
+}, hookType: HookType): boolean;
+export declare function buildHookCommand(hookType: HookType, _pluginRoot?: string): string;