@mxalbert/context-mode 2.0.0

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

@@ -0,0 +1,113 @@
+/**
+ * adapters/claude-code-base — Shared base for Claude Code wire-protocol adapters.
+ *
+ * Claude Code and Qwen Code use the identical JSON stdin/stdout hook protocol:
+ *   - Input fields: tool_name, tool_input, tool_output, is_error, session_id,
+ *     transcript_path, source
+ *   - Blocking: `permissionDecision: "deny"` in response
+ *   - Arg modification: `updatedInput` field in response
+ *   - Output modification: `updatedMCPToolOutput` field in response
+ *   - Context injection: `additionalContext` at response root (not wrapped)
+ *   - PreCompact/SessionStart: stdout on exit 0
+ *
+ * This base class implements the 8 shared parse/format methods.
+ * Subclasses provide platform-specific config (env vars, settings path,
+ * session ID priority, hook config, diagnostics, upgrade).
+ */
+import { BaseAdapter } from "./base.js";
+// ─────────────────────────────────────────────────────────
+// Base adapter for Claude Code wire protocol
+// ─────────────────────────────────────────────────────────
+export class ClaudeCodeBaseAdapter extends BaseAdapter {
+    // ── Input parsing (shared wire format) ─────────────────
+    parsePreToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.tool_name ?? "",
+            toolInput: input.tool_input ?? {},
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
+            raw,
+        };
+    }
+    parsePostToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.tool_name ?? "",
+            toolInput: input.tool_input ?? {},
+            toolOutput: input.tool_output,
+            isError: input.is_error,
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
+            raw,
+        };
+    }
+    parsePreCompactInput(raw) {
+        const input = raw;
+        return {
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
+            raw,
+        };
+    }
+    parseSessionStartInput(raw) {
+        const input = raw;
+        const rawSource = input.source ?? "startup";
+        let source;
+        switch (rawSource) {
+            case "compact":
+                source = "compact";
+                break;
+            case "resume":
+                source = "resume";
+                break;
+            case "clear":
+                source = "clear";
+                break;
+            default:
+                source = "startup";
+        }
+        return {
+            sessionId: this.extractSessionId(input),
+            source,
+            projectDir: process.env[this.projectDirEnvVar] ?? process.cwd(),
+            raw,
+        };
+    }
+    // ── Response formatting (shared wire format) ───────────
+    formatPreToolUseResponse(response) {
+        if (response.decision === "deny") {
+            return {
+                permissionDecision: "deny",
+                reason: response.reason ?? "Blocked by context-mode hook",
+            };
+        }
+        if (response.decision === "modify" && response.updatedInput) {
+            return { updatedInput: response.updatedInput };
+        }
+        if (response.decision === "context" && response.additionalContext) {
+            return { additionalContext: response.additionalContext };
+        }
+        if (response.decision === "ask") {
+            return { permissionDecision: "ask" };
+        }
+        // "allow" — return undefined for passthrough
+        return undefined;
+    }
+    formatPostToolUseResponse(response) {
+        const result = {};
+        if (response.additionalContext) {
+            result.additionalContext = response.additionalContext;
+        }
+        if (response.updatedOutput) {
+            result.updatedMCPToolOutput = response.updatedOutput;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    formatPreCompactResponse(response) {
+        return response.context ?? "";
+    }
+    formatSessionStartResponse(response) {
+        return response.context ?? "";
+    }
+}

package/build/adapters/client-map.d.ts

@@ -0,0 +1,10 @@
+/**
+ * adapters/client-map — MCP clientInfo.name → PlatformId mapping.
+ *
+ * Source: Apify MCP Client Capabilities Registry
+ * https://github.com/apify/mcp-client-capabilities
+ *
+ * Only includes platforms we have adapters for.
+ */
+import type { PlatformId } from "./types.js";
+export declare const CLIENT_NAME_TO_PLATFORM: Record<string, PlatformId>;

package/build/adapters/client-map.js

@@ -0,0 +1,42 @@
+/**
+ * adapters/client-map — MCP clientInfo.name → PlatformId mapping.
+ *
+ * Source: Apify MCP Client Capabilities Registry
+ * https://github.com/apify/mcp-client-capabilities
+ *
+ * Only includes platforms we have adapters for.
+ */
+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",
+    "Codex": "codex",
+    "codex-mcp-client": "codex",
+    "Kilo Code": "kilo",
+    "Kiro CLI": "kiro",
+    "Pi CLI": "pi",
+    "Pi Coding Agent": "pi",
+    // Issue #542 — Pi rebranded to OMP. Upstream
+    // refs/platforms/oh-my-pi/packages/coding-agent/src/mcp/client.ts:46-49
+    // ships clientInfo.name = "omp-coding-agent". Resolved to the OMP
+    // adapter (~/.omp/, PI_CODING_AGENT_DIR). Legacy "Pi CLI" /
+    // "Pi Coding Agent" entries above still resolve to the pi adapter.
+    "omp-coding-agent": "omp",
+    "Zed": "zed",
+    "zed": "zed",
+    "qwen-code": "qwen-code",
+    "qwen-cli-mcp-client": "qwen-code",
+    "kimi-code": "kimi",
+    "kimi": "kimi",
+    "Kimi Code": "kimi",
+};

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

@@ -0,0 +1,8 @@
+/**
+ * adapters/codex/config — Thin re-exports from CodexAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { CodexAdapter } from "./index.js";
+export { HOOK_TYPES, ROUTING_INSTRUCTIONS_PATH } from "./hooks.js";

package/build/adapters/codex/config.js

@@ -0,0 +1,8 @@
+/**
+ * adapters/codex/config — Thin re-exports from CodexAdapter.
+ *
+ * This module exists for backward compatibility. All logic lives in the
+ * adapter class (index.ts). New code should use getAdapter() from detect.ts.
+ */
+export { CodexAdapter } from "./index.js";
+export { HOOK_TYPES, ROUTING_INSTRUCTIONS_PATH } from "./hooks.js";

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

@@ -0,0 +1,55 @@
+/**
+ * adapters/codex/hooks — Codex CLI hook definitions.
+ *
+ * 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_HOME/hooks.json or ~/.codex/hooks.json.
+ * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
+ *
+ * Known limitations:
+ *   - 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)
+ */
+/** Codex CLI hook types — mirrors Claude Code's continuity events. */
+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: "UserPromptSubmit";
+    readonly STOP: "Stop";
+};
+/**
+ * External MCP catch-all matcher for Codex CLI (#529, #547 hotfix).
+ *
+ * Codex CLI's hook `tool_name` payload uses `mcp__<server>__<tool>` for any
+ * MCP-namespaced tool. Originally this constant used a negative lookahead
+ * `mcp__(?!.*context-mode)` to exclude context-mode's own MCP tools at the
+ * matcher layer. v1.0.124 shipped that pattern and Codex (Rust `regex` crate)
+ * rejected the matcher at boot with "look-around not supported", breaking
+ * every Codex user (#547).
+ *
+ * Fix: drop the lookaround. The matcher is now a charset-clean literal
+ * (`[A-Za-z0-9_|]` only), satisfying Codex's `is_exact_matcher`
+ * (refs/platforms/codex/codex-rs/hooks/src/events/common.rs:152) which
+ * short-circuits the regex engine entirely. context-mode's own MCP tools are
+ * already filtered in the hook BODY by `isExternalMcpTool()` in
+ * hooks/core/routing.mjs — semantics preserved.
+ */
+export declare const EXTERNAL_MCP_MATCHER_PATTERN = "mcp__";
+/**
+ * Path to the routing instructions file for Codex CLI.
+ * Used as fallback routing awareness alongside hook-based enforcement.
+ */
+export declare const ROUTING_INSTRUCTIONS_PATH = "configs/codex/AGENTS.md";

package/build/adapters/codex/hooks.js

@@ -0,0 +1,64 @@
+/**
+ * adapters/codex/hooks — Codex CLI hook definitions.
+ *
+ * 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_HOME/hooks.json or ~/.codex/hooks.json.
+ * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
+ *
+ * Known limitations:
+ *   - 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)
+ */
+// ─────────────────────────────────────────────────────────
+// Hook type constants
+// ─────────────────────────────────────────────────────────
+/** 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",
+};
+// ─────────────────────────────────────────────────────────
+// External MCP routing matcher (#529)
+// ─────────────────────────────────────────────────────────
+/**
+ * External MCP catch-all matcher for Codex CLI (#529, #547 hotfix).
+ *
+ * Codex CLI's hook `tool_name` payload uses `mcp__<server>__<tool>` for any
+ * MCP-namespaced tool. Originally this constant used a negative lookahead
+ * `mcp__(?!.*context-mode)` to exclude context-mode's own MCP tools at the
+ * matcher layer. v1.0.124 shipped that pattern and Codex (Rust `regex` crate)
+ * rejected the matcher at boot with "look-around not supported", breaking
+ * every Codex user (#547).
+ *
+ * Fix: drop the lookaround. The matcher is now a charset-clean literal
+ * (`[A-Za-z0-9_|]` only), satisfying Codex's `is_exact_matcher`
+ * (refs/platforms/codex/codex-rs/hooks/src/events/common.rs:152) which
+ * short-circuits the regex engine entirely. context-mode's own MCP tools are
+ * already filtered in the hook BODY by `isExternalMcpTool()` in
+ * hooks/core/routing.mjs — semantics preserved.
+ */
+export const EXTERNAL_MCP_MATCHER_PATTERN = "mcp__";
+// ─────────────────────────────────────────────────────────
+// Routing instructions
+// ─────────────────────────────────────────────────────────
+/**
+ * Path to the routing instructions file for Codex CLI.
+ * Used as fallback routing awareness alongside hook-based enforcement.
+ */
+export const ROUTING_INSTRUCTIONS_PATH = "configs/codex/AGENTS.md";

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

@@ -0,0 +1,87 @@
+/**
+ * adapters/codex — Codex CLI platform adapter.
+ *
+ * Implements HookAdapter for Codex CLI's JSON stdin/stdout paradigm.
+ *
+ * Codex CLI hook specifics:
+ *   - 6 hook events: PreToolUse, PostToolUse, PreCompact, SessionStart, UserPromptSubmit, Stop
+ *   - Same wire protocol as Claude Code (JSON stdin → stdout)
+ *   - 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 { BaseAdapter } from "../base.js";
+import { type HookAdapter, type HookParadigm, type PlatformCapabilities, type DiagnosticResult, type PreToolUseEvent, type PostToolUseEvent, type PreCompactEvent, type SessionStartEvent, type PreToolUseResponse, type PostToolUseResponse, type PreCompactResponse, type SessionStartResponse, type HookRegistration } from "../types.js";
+type CodexVersionRunner = (file: string, args: string[], options: {
+    encoding: BufferEncoding;
+    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 {
+    private readonly codexPluginListRunner;
+    constructor(options?: CodexAdapterOptions);
+    readonly name = "Codex CLI";
+    readonly paradigm: HookParadigm;
+    readonly capabilities: PlatformCapabilities;
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    parsePreCompactInput(raw: unknown): PreCompactEvent;
+    parseSessionStartInput(raw: unknown): SessionStartEvent;
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    formatPostToolUseResponse(response: PostToolUseResponse): unknown;
+    formatPreCompactResponse(response: PreCompactResponse): unknown;
+    formatSessionStartResponse(response: SessionStartResponse): unknown;
+    getConfigDir(_projectDir?: string): string;
+    getSettingsPath(): string;
+    getSessionDir(): string;
+    getInstructionFiles(): string[];
+    getMemoryDir(projectDir?: string): string;
+    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[];
+    backupSettings(): string | null;
+    setHookPermissions(_pluginRoot: string): string[];
+    updatePluginRegistry(_pluginRoot: string, _version: string): void;
+    getRoutingInstructions(): string;
+    /**
+     * Resolve the project directory for a Codex hook input.
+     * Priority: input.cwd > CODEX_PROJECT_DIR env > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even under worktrees or when the
+     * platform omits cwd from the wire payload.
+     */
+    private getProjectDir;
+    getHooksPath(): string;
+    private backupFile;
+    private readHooksConfig;
+    private writeHooksConfig;
+    private upsertManagedHookEntry;
+    private removeManagedHookEntries;
+    private hasCodexPluginHookManifest;
+    private getCodexPluginHookStatus;
+    private probeCodexContextModePluginRoot;
+    private samePath;
+    private pruneStaleUserHookTrustState;
+    private isExpectedHookEntry;
+    private isManagedContextModeEntry;
+    private entryContainsManagedCommand;
+    private normalizeCommand;
+    /**
+     * Extract session ID from Codex CLI hook input.
+     * Priority: session_id field > fallback to ppid.
+     */
+    private extractSessionId;
+}
+export {};