@mxalbert/context-mode 2.0.0

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

@@ -0,0 +1,106 @@
+/**
+ * adapters/claude-code/hooks — Claude Code hook definitions and matchers.
+ *
+ * Defines the hook types, matchers, and registration format specific to
+ * Claude Code's hook system. This module is used by:
+ *   - CLI setup/upgrade commands (to configure hooks in settings.json)
+ *   - Doctor command (to validate hook configuration)
+ *   - hooks.json generation
+ *
+ * Claude Code hook system reference:
+ *   - Hooks are registered in ~/.claude/settings.json under "hooks" key
+ *   - Each hook type maps to an array of { matcher, hooks } entries
+ *   - matcher: tool name pattern (empty = match all tools)
+ *   - hooks: array of { type: "command", command: "..." }
+ *   - Input: JSON on stdin
+ *   - Output: JSON on stdout (or empty for passthrough)
+ */
+/** Claude Code hook types. */
+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";
+};
+export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
+/**
+ * External MCP catch-all matcher for Claude Code (#529, #547 hotfix).
+ *
+ * Claude Code's hook matcher engine treats this entry as a substring match
+ * (it also accepts regex, but `mcp__` alone is enough — every MCP tool
+ * surfaces as `mcp__<server>__<tool>`). v1.0.124 used a negative lookahead
+ * `mcp__(?!plugin_context-mode_)` to skip context-mode's own MCP tools,
+ * but this same hooks.json is bundled to Codex CLI which uses Rust's
+ * `regex` crate (no look-around support) — Codex rejected the matcher at
+ * boot, breaking every Codex user (#547). Drop the lookaround on both
+ * sides; the hook BODY (`isExternalMcpTool()` in hooks/core/routing.mjs)
+ * already filters context-mode's own tools, so semantics are preserved.
+ */
+export declare const EXTERNAL_MCP_MATCHER_PATTERN = "mcp__";
+/** Tools that context-mode's PreToolUse hook intercepts. */
+export declare const PRE_TOOL_USE_MATCHERS: readonly ["Bash", "WebFetch", "Read", "Grep", "Agent", "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", "mcp__"];
+/**
+ * Combined matcher pattern for settings.json (pipe-separated).
+ * Used by the upgrade command when writing a single consolidated entry.
+ */
+export declare const PRE_TOOL_USE_MATCHER_PATTERN: string;
+/**
+ * Tools that context-mode's PostToolUse hook should fire on.
+ * Only tools that extractEvents() actually handles — all others
+ * produce zero events and cause false "hook error" display.
+ */
+export declare const POST_TOOL_USE_MATCHERS: readonly ["Bash", "Read", "Write", "Edit", "NotebookEdit", "Glob", "Grep", "TodoWrite", "TaskCreate", "TaskUpdate", "EnterPlanMode", "ExitPlanMode", "Skill", "Agent", "AskUserQuestion", "EnterWorktree", "mcp__"];
+/**
+ * Combined matcher pattern for PostToolUse in hooks.json / settings.json.
+ */
+export declare const POST_TOOL_USE_MATCHER_PATTERN: string;
+/** Map of hook types to their script file names. */
+export declare const HOOK_SCRIPTS: Record<HookType, string>;
+/** Required hooks that must be configured for context-mode to function. */
+export declare const REQUIRED_HOOKS: HookType[];
+/** Optional hooks that enhance functionality but aren't critical. */
+export declare const OPTIONAL_HOOKS: HookType[];
+/**
+ * Check if a hook entry points to a context-mode hook script.
+ * Matches both legacy format (node .../pretooluse.mjs) and
+ * CLI dispatcher format (context-mode hook claude-code pretooluse).
+ */
+export declare function isContextModeHook(entry: {
+    hooks?: Array<{
+        command?: string;
+    }>;
+}, hookType: HookType): boolean;
+/**
+ * Build the hook command string for a given hook type.
+ * Uses process.execPath + forward slashes to avoid PATH issues and MSYS
+ * path mangling on Windows (#369, #372).
+ * Falls back to CLI dispatcher if pluginRoot is not provided.
+ */
+export declare function buildHookCommand(hookType: HookType, pluginRoot?: string): string;
+/**
+ * Extract the hook script file path from a command string.
+ *
+ * Algo-D2 twin — same shape as `src/util/hook-config.ts::extractHookScriptPath`.
+ * Delegates to `parseNodeCommand` for canonical buildNodeCommand-shape;
+ * keeps narrow legacy fallbacks for pre-D3 settings.json entries
+ * (`node "X.mjs"` and `node X.mjs` with no internal whitespace).
+ *
+ * Pre-D2 this matched `node\s+"?([^"]+\.mjs)"?` — the unquoted fallback
+ * silently grabbed the tail after the last whitespace, producing the
+ * #548 doubled-path FAIL on Windows paths with spaces. The new shape
+ * refuses ambiguous input; doctor (Algo-D1) falls through to direct
+ * `existsSync` instead of trusting the regex.
+ */
+export declare function extractHookScriptPath(command: string): string | null;
+/**
+ * Check if a hook entry is a context-mode hook (any hook type).
+ * Broader than `isContextModeHook` — matches any context-mode script name
+ * without requiring a specific hookType.
+ */
+export declare function isAnyContextModeHook(entry: {
+    hooks?: Array<{
+        command?: string;
+    }>;
+}): boolean;

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

@@ -0,0 +1,183 @@
+import { buildHookRuntimeCommand, parseNodeCommand } from "../types.js";
+/**
+ * adapters/claude-code/hooks — Claude Code hook definitions and matchers.
+ *
+ * Defines the hook types, matchers, and registration format specific to
+ * Claude Code's hook system. This module is used by:
+ *   - CLI setup/upgrade commands (to configure hooks in settings.json)
+ *   - Doctor command (to validate hook configuration)
+ *   - hooks.json generation
+ *
+ * Claude Code hook system reference:
+ *   - Hooks are registered in ~/.claude/settings.json under "hooks" key
+ *   - Each hook type maps to an array of { matcher, hooks } entries
+ *   - matcher: tool name pattern (empty = match all tools)
+ *   - hooks: array of { type: "command", command: "..." }
+ *   - Input: JSON on stdin
+ *   - Output: JSON on stdout (or empty for passthrough)
+ */
+// ─────────────────────────────────────────────────────────
+// Hook type constants
+// ─────────────────────────────────────────────────────────
+/** Claude Code hook types. */
+export const HOOK_TYPES = {
+    PRE_TOOL_USE: "PreToolUse",
+    POST_TOOL_USE: "PostToolUse",
+    PRE_COMPACT: "PreCompact",
+    SESSION_START: "SessionStart",
+    USER_PROMPT_SUBMIT: "UserPromptSubmit",
+    STOP: "Stop",
+};
+// ─────────────────────────────────────────────────────────
+// PreToolUse matchers
+// ─────────────────────────────────────────────────────────
+/**
+ * External MCP catch-all matcher for Claude Code (#529, #547 hotfix).
+ *
+ * Claude Code's hook matcher engine treats this entry as a substring match
+ * (it also accepts regex, but `mcp__` alone is enough — every MCP tool
+ * surfaces as `mcp__<server>__<tool>`). v1.0.124 used a negative lookahead
+ * `mcp__(?!plugin_context-mode_)` to skip context-mode's own MCP tools,
+ * but this same hooks.json is bundled to Codex CLI which uses Rust's
+ * `regex` crate (no look-around support) — Codex rejected the matcher at
+ * boot, breaking every Codex user (#547). Drop the lookaround on both
+ * sides; the hook BODY (`isExternalMcpTool()` in hooks/core/routing.mjs)
+ * already filters context-mode's own tools, so semantics are preserved.
+ */
+export const EXTERNAL_MCP_MATCHER_PATTERN = "mcp__";
+/** Tools that context-mode's PreToolUse hook intercepts. */
+export const PRE_TOOL_USE_MATCHERS = [
+    "Bash",
+    "WebFetch",
+    "Read",
+    "Grep",
+    "Agent",
+    "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",
+    EXTERNAL_MCP_MATCHER_PATTERN,
+];
+/**
+ * Combined matcher pattern for settings.json (pipe-separated).
+ * Used by the upgrade command when writing a single consolidated entry.
+ */
+export const PRE_TOOL_USE_MATCHER_PATTERN = PRE_TOOL_USE_MATCHERS.join("|");
+// ─────────────────────────────────────────────────────────
+// PostToolUse matchers (#229)
+// ─────────────────────────────────────────────────────────
+/**
+ * Tools that context-mode's PostToolUse hook should fire on.
+ * Only tools that extractEvents() actually handles — all others
+ * produce zero events and cause false "hook error" display.
+ */
+export const POST_TOOL_USE_MATCHERS = [
+    "Bash",
+    "Read",
+    "Write",
+    "Edit",
+    "NotebookEdit",
+    "Glob",
+    "Grep",
+    "TodoWrite",
+    "TaskCreate",
+    "TaskUpdate",
+    "EnterPlanMode",
+    "ExitPlanMode",
+    "Skill",
+    "Agent",
+    "AskUserQuestion",
+    "EnterWorktree",
+    "mcp__",
+];
+/**
+ * Combined matcher pattern for PostToolUse in hooks.json / settings.json.
+ */
+export const POST_TOOL_USE_MATCHER_PATTERN = POST_TOOL_USE_MATCHERS.join("|");
+// ─────────────────────────────────────────────────────────
+// Hook script file names
+// ─────────────────────────────────────────────────────────
+/** Map of hook types to their script file names. */
+export const HOOK_SCRIPTS = {
+    PreToolUse: "pretooluse.mjs",
+    PostToolUse: "posttooluse.mjs",
+    PreCompact: "precompact.mjs",
+    SessionStart: "sessionstart.mjs",
+    UserPromptSubmit: "userpromptsubmit.mjs",
+    Stop: "stop.mjs",
+};
+// ─────────────────────────────────────────────────────────
+// Hook validation
+// ─────────────────────────────────────────────────────────
+/** Required hooks that must be configured for context-mode to function. */
+export const REQUIRED_HOOKS = [
+    HOOK_TYPES.PRE_TOOL_USE,
+    HOOK_TYPES.SESSION_START,
+];
+/** Optional hooks that enhance functionality but aren't critical. */
+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.
+ * Matches both legacy format (node .../pretooluse.mjs) and
+ * CLI dispatcher format (context-mode hook claude-code pretooluse).
+ */
+export function isContextModeHook(entry, hookType) {
+    const scriptName = HOOK_SCRIPTS[hookType];
+    const cliCommand = buildHookCommand(hookType);
+    return (entry.hooks?.some((h) => h.command?.includes(scriptName) || h.command?.includes(cliCommand)) ?? false);
+}
+/**
+ * Build the hook command string for a given hook type.
+ * Uses process.execPath + forward slashes to avoid PATH issues and MSYS
+ * path mangling on Windows (#369, #372).
+ * Falls back to CLI dispatcher if pluginRoot is not provided.
+ */
+export function buildHookCommand(hookType, pluginRoot) {
+    if (pluginRoot) {
+        const scriptName = HOOK_SCRIPTS[hookType];
+        return buildHookRuntimeCommand(`${pluginRoot}/hooks/${scriptName}`);
+    }
+    return `context-mode hook claude-code ${hookType.toLowerCase()}`;
+}
+/**
+ * Extract the hook script file path from a command string.
+ *
+ * Algo-D2 twin — same shape as `src/util/hook-config.ts::extractHookScriptPath`.
+ * Delegates to `parseNodeCommand` for canonical buildNodeCommand-shape;
+ * keeps narrow legacy fallbacks for pre-D3 settings.json entries
+ * (`node "X.mjs"` and `node X.mjs` with no internal whitespace).
+ *
+ * Pre-D2 this matched `node\s+"?([^"]+\.mjs)"?` — the unquoted fallback
+ * silently grabbed the tail after the last whitespace, producing the
+ * #548 doubled-path FAIL on Windows paths with spaces. The new shape
+ * refuses ambiguous input; doctor (Algo-D1) falls through to direct
+ * `existsSync` instead of trusting the regex.
+ */
+export function extractHookScriptPath(command) {
+    const parsed = parseNodeCommand(command);
+    if (parsed) {
+        return parsed.scriptPath.endsWith(".mjs") ? parsed.scriptPath : null;
+    }
+    const legacyQuoted = command.match(/^\s*node\s+"([^"]+\.mjs)"\s*$/);
+    if (legacyQuoted)
+        return legacyQuoted[1];
+    const legacyBare = command.match(/^\s*node\s+(\S+\.mjs)\s*$/);
+    if (legacyBare)
+        return legacyBare[1];
+    return null;
+}
+/**
+ * Check if a hook entry is a context-mode hook (any hook type).
+ * Broader than `isContextModeHook` — matches any context-mode script name
+ * without requiring a specific hookType.
+ */
+export function isAnyContextModeHook(entry) {
+    const scriptNames = Object.values(HOOK_SCRIPTS);
+    return (entry.hooks?.some((h) => h.command != null &&
+        (scriptNames.some((s) => h.command.includes(s)) ||
+            h.command.includes("context-mode hook"))) ?? false);
+}

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

@@ -0,0 +1,80 @@
+/**
+ * adapters/claude-code — Claude Code platform adapter.
+ *
+ * Extends ClaudeCodeBaseAdapter (shared wire-protocol parse/format methods)
+ * with Claude Code-specific configuration, diagnostics, and upgrade logic.
+ *
+ * Claude Code hook specifics:
+ *   - Session ID: transcript_path UUID > session_id > CLAUDE_SESSION_ID > ppid
+ *   - Config root: $CLAUDE_CONFIG_DIR (when set) or ~/.claude
+ *   - Settings: <configDir>/settings.json
+ *   - Session dir: <configDir>/context-mode/sessions/
+ *   - Plugin registry: <configDir>/plugins/installed_plugins.json
+ */
+import { ClaudeCodeBaseAdapter, type ClaudeCodeWireInput } from "../claude-code-base.js";
+import { type HookAdapter, type HookParadigm, type PlatformCapabilities, type DiagnosticResult, type HookRegistration, type HealthCheck } from "../types.js";
+export declare class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter implements HookAdapter {
+    constructor();
+    readonly name = "Claude Code";
+    readonly paradigm: HookParadigm;
+    protected readonly projectDirEnvVar = "CLAUDE_PROJECT_DIR";
+    readonly capabilities: PlatformCapabilities;
+    /**
+     * Honor `CLAUDE_CONFIG_DIR` (the canonical Claude Code config root) before
+     * falling back to `~/.claude`. Mirrors the contract that
+     * `hooks/session-helpers.mjs::resolveConfigDir` already follows — including
+     * tilde expansion for shells that pass `~/foo` through unchanged — so server
+     * and hooks agree on where session-scoped state lives. See issue #453.
+     *
+     * Tilde regex `/^~[/\\]?/` only handles the current-user form (`~`, `~/`,
+     * `~\`); `~user/` is NOT expanded to a per-user homedir (matches
+     * `resolveConfigDir`). Non-tilde values are run through `resolve()` to
+     * normalize relative paths to absolute against cwd; the hook helper
+     * intentionally leaves them raw, but the adapter contract guarantees an
+     * absolute path (BaseAdapter.getConfigDir docstring).
+     *
+     * Issue #460 round-3: routed through the canonical
+     * `resolveClaudeConfigDir` util so server, CLI, security, and adapter
+     * agree byte-for-byte (incl. empty/whitespace-only env fallback).
+     */
+    getConfigDir(_projectDir?: string): string;
+    getSessionDir(): string;
+    getSettingsPath(): string;
+    generateHookConfig(pluginRoot: string): HookRegistration;
+    readSettings(): Record<string, unknown> | null;
+    writeSettings(settings: Record<string, unknown>): void;
+    validateHooks(pluginRoot: string): DiagnosticResult[];
+    /**
+     * Adapter-defined health checks (Algo-D1 + Algo-D5).
+     *
+     * For each entry in HOOK_SCRIPTS (the canonical hookType → scriptName
+     * map), emit a HealthCheck that joins `pluginRoot + "hooks" +
+     * scriptName` and probes via `existsSync`. Crucially, this NEVER
+     * parses a hook command — pluginRoot and scriptName are both in our
+     * hand, so the regex round-trip that produced the #548 doubled-path
+     * FAIL is bypassed entirely.
+     *
+     * The hook check derives from HOOK_SCRIPTS (single source of truth in
+     * src/adapters/claude-code/hooks.ts), so adding a new hook event in
+     * that map auto-extends doctor coverage — no parallel hardcoded list
+     * to maintain.
+     *
+     * Algo-D5: appends a single "Plugin cache integrity" check that
+     * delegates to the same helper start.mjs uses at boot
+     * (scripts/plugin-cache-integrity.mjs::assertPluginCacheIntegrity).
+     * Same code, two callsites — boot fail-fast and doctor diagnostic
+     * agree byte-for-byte. Users hitting #550 get the actionable signal
+     * without restarting the MCP server.
+     */
+    getHealthChecks(pluginRoot: string): readonly HealthCheck[];
+    /** Read plugin hooks from hooks/hooks.json or .claude-plugin/hooks/hooks.json */
+    private readPluginHooks;
+    /** Check if a hook type is configured in either settings.json or plugin hooks */
+    private checkHookType;
+    checkPluginRegistration(): DiagnosticResult;
+    getInstalledVersion(): string;
+    configureAllHooks(pluginRoot: string): string[];
+    setHookPermissions(pluginRoot: string): string[];
+    updatePluginRegistry(pluginRoot: string, version: string): void;
+    protected extractSessionId(input: ClaudeCodeWireInput): string;
+}