context-mode 0.9.21 → 1.0.0

package/build/adapters/opencode/index.js

@@ -0,0 +1,386 @@
+/**
+ * adapters/opencode — OpenCode platform adapter.
+ *
+ * Implements HookAdapter for OpenCode's TypeScript plugin paradigm.
+ *
+ * OpenCode hook specifics:
+ *   - I/O: TS plugin functions (not JSON stdin/stdout)
+ *   - Hook names: tool.execute.before, tool.execute.after, experimental.session.compacting
+ *   - Arg modification: output.args mutation
+ *   - Blocking: throw Error in tool.execute.before
+ *   - Output modification: output.output mutation (TUI bug for bash #13575)
+ *   - SessionStart: broken (#14808, no hook #5409)
+ *   - Session ID: input.sessionID (camelCase!)
+ *   - Project dir: ctx.directory in plugin init (no env var)
+ *   - Config: opencode.json plugin array, .opencode/plugins/*.ts
+ *   - Session dir: ~/.config/opencode/context-mode/sessions/
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+// ─────────────────────────────────────────────────────────
+// Hook constants (re-exported from hooks.ts)
+// ─────────────────────────────────────────────────────────
+import { HOOK_TYPES as OPENCODE_HOOK_NAMES } from "./hooks.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class OpenCodeAdapter {
+    name = "OpenCode";
+    paradigm = "ts-plugin";
+    capabilities = {
+        preToolUse: true,
+        postToolUse: true,
+        preCompact: true, // experimental
+        sessionStart: true,
+        canModifyArgs: true,
+        canModifyOutput: true, // with TUI bug caveat for bash (#13575)
+        canInjectSessionContext: false,
+    };
+    // ── Input parsing ──────────────────────────────────────
+    parsePreToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.tool_name ?? "",
+            toolInput: input.tool_input ?? {},
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env.OPENCODE_PROJECT_DIR || 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.OPENCODE_PROJECT_DIR || process.cwd(),
+            raw,
+        };
+    }
+    parsePreCompactInput(raw) {
+        const input = raw;
+        return {
+            sessionId: this.extractSessionId(input),
+            projectDir: process.env.OPENCODE_PROJECT_DIR || 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.OPENCODE_PROJECT_DIR || process.cwd(),
+            raw,
+        };
+    }
+    // ── Response formatting ────────────────────────────────
+    formatPreToolUseResponse(response) {
+        if (response.decision === "deny") {
+            // OpenCode TS plugin paradigm: throw Error to block
+            throw new Error(response.reason ?? "Blocked by context-mode hook");
+        }
+        if (response.decision === "modify" && response.updatedInput) {
+            // OpenCode: output.args mutation
+            return { args: response.updatedInput };
+        }
+        if (response.decision === "ask") {
+            // OpenCode: no native "ask" mechanism — throw to be safe
+            throw new Error(response.reason ?? "Action requires user confirmation (security policy)");
+        }
+        // "context" — OpenCode's tool.execute.before cannot inject additionalContext
+        // in PreToolUse (platform limitation). The guidance is delivered via
+        // CLAUDE.md/AGENTS.md routing instructions instead. Passthrough.
+        // "allow" — passthrough
+        return undefined;
+    }
+    formatPostToolUseResponse(response) {
+        const result = {};
+        if (response.updatedOutput) {
+            // OpenCode: output.output mutation (TUI bug for bash #13575)
+            result.output = response.updatedOutput;
+        }
+        if (response.additionalContext) {
+            result.additionalContext = response.additionalContext;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    formatPreCompactResponse(response) {
+        // experimental.session.compacting — return context string
+        return response.context ?? "";
+    }
+    formatSessionStartResponse(response) {
+        return response.context ?? "";
+    }
+    // ── Configuration ──────────────────────────────────────
+    getSettingsPath() {
+        // OpenCode uses opencode.json in the project root or .opencode/opencode.json
+        return resolve("opencode.json");
+    }
+    getSessionDir() {
+        const dir = join(homedir(), ".config", "opencode", "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    getSessionDBPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}.db`);
+    }
+    getSessionEventsPath(projectDir) {
+        const hash = createHash("sha256")
+            .update(projectDir)
+            .digest("hex")
+            .slice(0, 16);
+        return join(this.getSessionDir(), `${hash}-events.md`);
+    }
+    generateHookConfig(_pluginRoot) {
+        // OpenCode uses TS plugin paradigm — hooks are registered via plugin array
+        // in opencode.json, not via command-based hook entries.
+        // Return the hook name mapping for documentation purposes.
+        return {
+            [OPENCODE_HOOK_NAMES.BEFORE]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+            [OPENCODE_HOOK_NAMES.AFTER]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+            [OPENCODE_HOOK_NAMES.COMPACTING]: [
+                {
+                    matcher: "",
+                    hooks: [
+                        {
+                            type: "plugin",
+                            command: "context-mode",
+                        },
+                    ],
+                },
+            ],
+        };
+    }
+    readSettings() {
+        // Try opencode.json, then .opencode/opencode.json
+        const paths = [
+            resolve("opencode.json"),
+            resolve(".opencode", "opencode.json"),
+        ];
+        for (const configPath of paths) {
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                return JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    writeSettings(settings) {
+        // Write to opencode.json in current directory
+        const configPath = resolve("opencode.json");
+        writeFileSync(configPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    }
+    // ── Diagnostics (doctor) ─────────────────────────────────
+    validateHooks(_pluginRoot) {
+        const results = [];
+        const settings = this.readSettings();
+        if (!settings) {
+            results.push({
+                check: "Plugin configuration",
+                status: "fail",
+                message: "Could not read opencode.json",
+                fix: "context-mode upgrade",
+            });
+            return results;
+        }
+        // Check for "context-mode" in plugin array
+        const plugins = settings.plugin;
+        if (plugins && Array.isArray(plugins)) {
+            const hasPlugin = plugins.some((p) => p.includes("context-mode"));
+            results.push({
+                check: "Plugin registration",
+                status: hasPlugin ? "pass" : "fail",
+                message: hasPlugin
+                    ? "context-mode found in plugin array"
+                    : "context-mode not found in plugin array",
+                fix: hasPlugin
+                    ? undefined
+                    : "context-mode upgrade",
+            });
+        }
+        else {
+            results.push({
+                check: "Plugin registration",
+                status: "fail",
+                message: "No plugin array found in opencode.json",
+                fix: "context-mode upgrade",
+            });
+        }
+        // Warn about SessionStart limitation
+        results.push({
+            check: "SessionStart hook",
+            status: "warn",
+            message: "SessionStart not supported in OpenCode (see issues #14808, #5409)",
+        });
+        return results;
+    }
+    checkPluginRegistration() {
+        const settings = this.readSettings();
+        if (!settings) {
+            return {
+                check: "Plugin registration",
+                status: "warn",
+                message: "Could not read opencode.json",
+            };
+        }
+        const plugins = settings.plugin;
+        if (plugins && Array.isArray(plugins)) {
+            const hasPlugin = plugins.some((p) => p.includes("context-mode"));
+            if (hasPlugin) {
+                return {
+                    check: "Plugin registration",
+                    status: "pass",
+                    message: "context-mode found in plugin array",
+                };
+            }
+        }
+        return {
+            check: "Plugin registration",
+            status: "fail",
+            message: "context-mode not found in opencode.json plugin array",
+            fix: "context-mode upgrade",
+        };
+    }
+    getInstalledVersion() {
+        // Check ~/.cache/opencode/node_modules/ for context-mode
+        try {
+            const pkgPath = resolve(homedir(), ".cache", "opencode", "node_modules", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            /* not found */
+        }
+        return "not installed";
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    configureAllHooks(_pluginRoot) {
+        const settings = this.readSettings() ?? {};
+        const changes = [];
+        // Add "context-mode" to the plugin array
+        const plugins = (settings.plugin ?? []);
+        if (!plugins.some((p) => p.includes("context-mode"))) {
+            plugins.push("context-mode");
+            changes.push("Added context-mode to plugin array");
+        }
+        else {
+            changes.push("context-mode already in plugin array");
+        }
+        settings.plugin = plugins;
+        this.writeSettings(settings);
+        return changes;
+    }
+    backupSettings() {
+        const paths = [
+            resolve("opencode.json"),
+            resolve(".opencode", "opencode.json"),
+        ];
+        for (const configPath of paths) {
+            try {
+                accessSync(configPath, constants.R_OK);
+                const backupPath = configPath + ".bak";
+                copyFileSync(configPath, backupPath);
+                return backupPath;
+            }
+            catch {
+                continue;
+            }
+        }
+        return null;
+    }
+    setHookPermissions(_pluginRoot) {
+        // OpenCode uses TS plugin paradigm — no shell scripts to chmod
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // OpenCode manages plugins through npm/opencode.json — no separate registry
+    }
+    // ── Routing Instructions (soft enforcement) ────────────
+    getRoutingInstructionsConfig() {
+        return {
+            fileName: "AGENTS.md",
+            globalPath: resolve(homedir(), ".config", "opencode", "AGENTS.md"),
+            projectRelativePath: "AGENTS.md",
+        };
+    }
+    writeRoutingInstructions(projectDir, pluginRoot) {
+        const config = this.getRoutingInstructionsConfig();
+        const targetPath = resolve(projectDir, config.projectRelativePath);
+        const sourcePath = resolve(pluginRoot, "configs", "opencode", config.fileName);
+        try {
+            const content = readFileSync(sourcePath, "utf-8");
+            try {
+                const existing = readFileSync(targetPath, "utf-8");
+                if (existing.includes("context-mode"))
+                    return null;
+                writeFileSync(targetPath, existing.trimEnd() + "\n\n" + content, "utf-8");
+                return targetPath;
+            }
+            catch {
+                writeFileSync(targetPath, content, "utf-8");
+                return targetPath;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Internal helpers ───────────────────────────────────
+    /**
+     * Extract session ID from OpenCode hook input.
+     * OpenCode uses camelCase sessionID.
+     */
+    extractSessionId(input) {
+        if (input.sessionID)
+            return input.sessionID;
+        return `pid-${process.ppid}`;
+    }
+}

package/build/adapters/types.d.ts

@@ -0,0 +1,218 @@
+/**
+ * adapters/types — Platform adapter interface for multi-platform hook support.
+ *
+ * Defines the contract that each platform adapter must implement.
+ * Three paradigms exist across supported platforms:
+ *   A) JSON stdin/stdout — Claude Code, Gemini CLI, VS Code Copilot, Copilot CLI, Cursor
+ *   B) TS Plugin Functions — OpenCode
+ *   C) MCP-only (no hooks) — Codex CLI
+ *
+ * The MCP server layer is 100% portable and needs no adapter.
+ * Only the hook layer requires platform-specific adapters.
+ */
+export type HookParadigm = "json-stdio" | "ts-plugin" | "mcp-only";
+export interface PlatformCapabilities {
+    /** Platform supports PreToolUse / BeforeTool / tool.execute.before hooks. */
+    preToolUse: boolean;
+    /** Platform supports PostToolUse / AfterTool / tool.execute.after hooks. */
+    postToolUse: boolean;
+    /** Platform supports PreCompact / PreCompress / session.compacting hooks. */
+    preCompact: boolean;
+    /** Platform supports SessionStart / session.created hooks. */
+    sessionStart: boolean;
+    /** Platform allows modifying tool input arguments via hooks. */
+    canModifyArgs: boolean;
+    /** Platform allows modifying tool output via PostToolUse hooks. */
+    canModifyOutput: boolean;
+    /** Platform allows injecting context during session start or compaction. */
+    canInjectSessionContext: boolean;
+}
+/** Normalized PreToolUse event — platform-agnostic representation. */
+export interface PreToolUseEvent {
+    /** Tool name being invoked (e.g., "Bash", "Read", "WebFetch"). */
+    toolName: string;
+    /** Tool input arguments as key-value pairs. */
+    toolInput: Record<string, unknown>;
+    /** Session ID extracted by the adapter. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input (for passthrough if needed). */
+    raw: unknown;
+}
+/** Normalized PostToolUse event — platform-agnostic representation. */
+export interface PostToolUseEvent {
+    /** Tool name that was invoked. */
+    toolName: string;
+    /** Tool input arguments. */
+    toolInput: Record<string, unknown>;
+    /** Tool output/response (if available). */
+    toolOutput?: string;
+    /** Whether the tool call resulted in an error. */
+    isError?: boolean;
+    /** Session ID extracted by the adapter. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Normalized PreCompact event. */
+export interface PreCompactEvent {
+    /** Session ID. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Normalized SessionStart event. */
+export interface SessionStartEvent {
+    /** Session ID. */
+    sessionId: string;
+    /** Lifecycle source: fresh start, compaction, resume, or clear. */
+    source: "startup" | "compact" | "resume" | "clear";
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Response from PreToolUse hook — can block, modify, inject context, or pass through. */
+export interface PreToolUseResponse {
+    /**
+     * "allow"   = pass through (no action)
+     * "deny"    = block tool execution
+     * "modify"  = change input args
+     * "context" = inject additional context (soft guidance)
+     * "ask"     = prompt user for confirmation (security policy match)
+     */
+    decision: "allow" | "deny" | "modify" | "context" | "ask";
+    /** Reason for denial (shown to the model). */
+    reason?: string;
+    /** Modified tool input (only when decision = "modify"). */
+    updatedInput?: Record<string, unknown>;
+    /** Additional context to inject (only when decision = "context"). */
+    additionalContext?: string;
+}
+/** Response from PostToolUse hook — can inject context or modify output. */
+export interface PostToolUseResponse {
+    /** Additional context to inject after tool output. */
+    additionalContext?: string;
+    /** Modified tool output (if platform supports it). */
+    updatedOutput?: string;
+}
+/** Response from PreCompact hook — injects context before compaction. */
+export interface PreCompactResponse {
+    /** Context to preserve across compaction. */
+    context?: string;
+}
+/** Response from SessionStart hook — injects context at session start. */
+export interface SessionStartResponse {
+    /** Context to inject at session start. */
+    context?: string;
+}
+/** A single hook entry in platform configuration. */
+export interface HookEntry {
+    /** Tool matcher pattern (empty = match all). */
+    matcher: string;
+    /** Hook commands/handlers to execute. */
+    hooks: Array<{
+        type: string;
+        command: string;
+    }>;
+}
+/** Hook registration map — maps hook types to their entries. */
+export type HookRegistration = Record<string, HookEntry[]>;
+/**
+ * HookAdapter — contract for platform-specific hook implementations.
+ *
+ * Each supported platform (Claude Code, Gemini CLI, OpenCode, etc.)
+ * provides an adapter that normalizes its hook I/O into a common format.
+ */
+export interface HookAdapter {
+    /** Human-readable platform name (e.g., "Claude Code", "Gemini CLI"). */
+    readonly name: string;
+    /** Hook I/O paradigm used by this platform. */
+    readonly paradigm: HookParadigm;
+    /** What this platform supports. */
+    readonly capabilities: PlatformCapabilities;
+    /** Parse raw PreToolUse input into normalized form. */
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    /** Parse raw PostToolUse input into normalized form. */
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    /** Parse raw PreCompact input (optional — not all platforms support it). */
+    parsePreCompactInput?(raw: unknown): PreCompactEvent;
+    /** Parse raw SessionStart input (optional — not all platforms support it). */
+    parseSessionStartInput?(raw: unknown): SessionStartEvent;
+    /** Format a PreToolUse response into platform-specific output. */
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    /** Format a PostToolUse response into platform-specific output. */
+    formatPostToolUseResponse(response: PostToolUseResponse): unknown;
+    /** Format a PreCompact response into platform-specific output. */
+    formatPreCompactResponse?(response: PreCompactResponse): unknown;
+    /** Format a SessionStart response into platform-specific output. */
+    formatSessionStartResponse?(response: SessionStartResponse): unknown;
+    /** Path to the platform's settings file (e.g., ~/.claude/settings.json). */
+    getSettingsPath(): string;
+    /** Directory where session data is stored. */
+    getSessionDir(): string;
+    /** Compute per-project session DB path. */
+    getSessionDBPath(projectDir: string): string;
+    /** Compute per-project session events file path. */
+    getSessionEventsPath(projectDir: string): string;
+    /** Generate hook registration config for this platform. */
+    generateHookConfig(pluginRoot: string): HookRegistration;
+    /** Read current platform settings. */
+    readSettings(): Record<string, unknown> | null;
+    /** Write platform settings. */
+    writeSettings(settings: Record<string, unknown>): void;
+    /** Validate that hooks are properly configured for this platform. */
+    validateHooks(pluginRoot: string): DiagnosticResult[];
+    /** Check if the plugin is registered/enabled on this platform. */
+    checkPluginRegistration(): DiagnosticResult;
+    /** Get the installed version from this platform's registry/marketplace. */
+    getInstalledVersion(): string;
+    /** Configure all hooks for this platform. Returns change descriptions. */
+    configureAllHooks(pluginRoot: string): string[];
+    /** Backup platform settings before modification. Returns backup path or null. */
+    backupSettings(): string | null;
+    /** Set executable permissions on hook scripts. Returns paths that were set. */
+    setHookPermissions(pluginRoot: string): string[];
+    /** Update platform's plugin registry to point to given path and version. */
+    updatePluginRegistry(pluginRoot: string, version: string): void;
+    /** Get the routing instructions file config for this platform. */
+    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
+    /** Write routing instructions file to project directory if not present. Returns path written or null if already exists. */
+    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
+}
+/** Configuration for platform-specific routing instruction files. */
+export interface RoutingInstructionsConfig {
+    /** File name the platform reads (e.g., "CLAUDE.md", "GEMINI.md", "AGENTS.md"). */
+    fileName: string;
+    /** Global path for this platform (e.g., "~/.claude/CLAUDE.md"). */
+    globalPath: string;
+    /** Project-level path relative to project root (e.g., "GEMINI.md", ".github/copilot-instructions.md"). */
+    projectRelativePath: string;
+}
+/** Result from a platform-specific diagnostic check. */
+export interface DiagnosticResult {
+    /** What was checked. */
+    check: string;
+    /** Pass, fail, or warning. */
+    status: "pass" | "fail" | "warn";
+    /** Human-readable message. */
+    message: string;
+    /** Suggested fix command (if applicable). */
+    fix?: string;
+}
+/** Supported platform identifiers. */
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "codex" | "copilot-cli" | "vscode-copilot" | "cursor" | "unknown";
+/** Detection signal used to identify which platform is running. */
+export interface DetectionSignal {
+    /** Platform identifier. */
+    platform: PlatformId;
+    /** Confidence: env var match > config dir match > fallback. */
+    confidence: "high" | "medium" | "low";
+    /** How it was detected. */
+    reason: string;
+}

package/build/adapters/types.js

@@ -0,0 +1,13 @@
+/**
+ * adapters/types — Platform adapter interface for multi-platform hook support.
+ *
+ * Defines the contract that each platform adapter must implement.
+ * Three paradigms exist across supported platforms:
+ *   A) JSON stdin/stdout — Claude Code, Gemini CLI, VS Code Copilot, Copilot CLI, Cursor
+ *   B) TS Plugin Functions — OpenCode
+ *   C) MCP-only (no hooks) — Codex CLI
+ *
+ * The MCP server layer is 100% portable and needs no adapter.
+ * Only the hook layer requires platform-specific adapters.
+ */
+export {};

package/build/adapters/vscode-copilot/config.d.ts

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

package/build/adapters/vscode-copilot/config.js

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

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

@@ -0,0 +1,49 @@
+/**
+ * adapters/vscode-copilot/hooks — VS Code Copilot hook definitions and matchers.
+ *
+ * Defines the hook types, matchers, and registration format specific to
+ * VS Code Copilot's hook system. This module is used by:
+ *   - CLI setup/upgrade commands (to configure hooks)
+ *   - Doctor command (to validate hook configuration)
+ *   - Hook config generation
+ *
+ * VS Code Copilot hook system reference:
+ *   - Hooks are registered in .github/hooks/*.json
+ *   - Hook names: PreToolUse, PostToolUse, PreCompact, SessionStart (PascalCase)
+ *   - Additional hooks: Stop, SubagentStart, SubagentStop (unique to VS Code)
+ *   - CRITICAL: matchers are parsed but IGNORED (all hooks fire on all tools)
+ *   - Input: JSON on stdin
+ *   - Output: JSON on stdout (or empty for passthrough)
+ *   - Preview status — API may change
+ */
+/** VS Code Copilot 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 STOP: "Stop";
+    readonly SUBAGENT_START: "SubagentStart";
+    readonly SUBAGENT_STOP: "SubagentStop";
+};
+export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
+/** Map of hook types to their script file names. */
+export declare const HOOK_SCRIPTS: Record<string, 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.
+ */
+export declare function isContextModeHook(entry: {
+    hooks?: Array<{
+        command?: string;
+    }>;
+}, hookType: HookType): boolean;
+/**
+ * Build the hook command string for a given hook type.
+ * Uses the CLI dispatcher: `context-mode hook vscode-copilot <event>`
+ * Requires global install: `npm install -g context-mode`
+ */
+export declare function buildHookCommand(hookType: HookType): string;