context-mode 1.0.21 → 1.0.23

package/build/adapters/client-map.js

@@ -0,0 +1,18 @@
+/**
+ * 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",
+    "cursor-vscode": "cursor",
+    "Visual-Studio-Code": "vscode-copilot",
+    "Codex": "codex",
+    "codex-mcp-client": "codex",
+    "Kiro CLI": "kiro",
+};

package/build/adapters/detect.d.ts

@@ -10,6 +10,7 @@
  *   - Claude Code:    CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID | ~/.claude/
  *   - Gemini CLI:     GEMINI_PROJECT_DIR (hooks), GEMINI_CLI (MCP) | ~/.gemini/
  *   - OpenCode:       OPENCODE, OPENCODE_PID | ~/.config/opencode/
+ *   - OpenClaw:       OPENCLAW_HOME, OPENCLAW_PROJECT_DIR | ~/.openclaw/
  *   - Codex CLI:      CODEX_CI, CODEX_THREAD_ID | ~/.codex/
  *   - Cursor:         CURSOR_TRACE_ID (MCP), CURSOR_CLI (terminal) | ~/.cursor/
  *   - VS Code Copilot: VSCODE_PID, VSCODE_CWD | ~/.vscode/
@@ -17,8 +18,14 @@
 import type { PlatformId, DetectionSignal, HookAdapter } from "./types.js";
 /**
  * Detect the current platform by checking env vars and config dirs.
+ *
+ * @param clientInfo - Optional MCP clientInfo from initialize handshake.
+ *   When provided, takes highest priority (zero-config detection).
  */
-export declare function detectPlatform(): DetectionSignal;
+export declare function detectPlatform(clientInfo?: {
+    name: string;
+    version?: string;
+}): DetectionSignal;
 /**
  * Get the adapter instance for a given platform.
  * Lazily imports platform-specific adapter modules.

package/build/adapters/detect.js

@@ -10,6 +10,7 @@
  *   - Claude Code:    CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID | ~/.claude/
  *   - Gemini CLI:     GEMINI_PROJECT_DIR (hooks), GEMINI_CLI (MCP) | ~/.gemini/
  *   - OpenCode:       OPENCODE, OPENCODE_PID | ~/.config/opencode/
+ *   - OpenClaw:       OPENCLAW_HOME, OPENCLAW_PROJECT_DIR | ~/.openclaw/
  *   - Codex CLI:      CODEX_CI, CODEX_THREAD_ID | ~/.codex/
  *   - Cursor:         CURSOR_TRACE_ID (MCP), CURSOR_CLI (terminal) | ~/.cursor/
  *   - VS Code Copilot: VSCODE_PID, VSCODE_CWD | ~/.vscode/
@@ -17,10 +18,40 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
+import { CLIENT_NAME_TO_PLATFORM } from "./client-map.js";
 /**
  * Detect the current platform by checking env vars and config dirs.
+ *
+ * @param clientInfo - Optional MCP clientInfo from initialize handshake.
+ *   When provided, takes highest priority (zero-config detection).
  */
-export function detectPlatform() {
+export function detectPlatform(clientInfo) {
+    // ── Highest priority: MCP clientInfo ──────────────────
+    if (clientInfo?.name) {
+        const platform = CLIENT_NAME_TO_PLATFORM[clientInfo.name];
+        if (platform) {
+            return {
+                platform,
+                confidence: "high",
+                reason: `MCP clientInfo.name="${clientInfo.name}"`,
+            };
+        }
+    }
+    // ── Explicit platform override ────────────────────────
+    const platformOverride = process.env.CONTEXT_MODE_PLATFORM;
+    if (platformOverride) {
+        const validPlatforms = [
+            "claude-code", "gemini-cli", "opencode", "codex",
+            "vscode-copilot", "cursor", "antigravity", "kiro",
+        ];
+        if (validPlatforms.includes(platformOverride)) {
+            return {
+                platform: platformOverride,
+                confidence: "high",
+                reason: `CONTEXT_MODE_PLATFORM=${platformOverride} override`,
+            };
+        }
+    }
     // ── High confidence: environment variables ─────────────
     if (process.env.CLAUDE_PROJECT_DIR || process.env.CLAUDE_SESSION_ID) {
         return {
@@ -36,6 +67,13 @@ export function detectPlatform() {
             reason: "GEMINI_PROJECT_DIR or GEMINI_CLI env var set",
         };
     }
+    if (process.env.OPENCLAW_HOME || process.env.OPENCLAW_PROJECT_DIR) {
+        return {
+            platform: "openclaw",
+            confidence: "high",
+            reason: "OPENCLAW_HOME or OPENCLAW_PROJECT_DIR env var set",
+        };
+    }
     if (process.env.OPENCODE || process.env.OPENCODE_PID) {
         return {
             platform: "opencode",
@@ -94,6 +132,13 @@ export function detectPlatform() {
             reason: "~/.cursor/ directory exists",
         };
     }
+    if (existsSync(resolve(home, ".openclaw"))) {
+        return {
+            platform: "openclaw",
+            confidence: "medium",
+            reason: "~/.openclaw/ directory exists",
+        };
+    }
     if (existsSync(resolve(home, ".config", "opencode"))) {
         return {
             platform: "opencode",
@@ -127,6 +172,10 @@ export async function getAdapter(platform) {
             const { OpenCodeAdapter } = await import("./opencode/index.js");
             return new OpenCodeAdapter();
         }
+        case "openclaw": {
+            const { OpenClawAdapter } = await import("./openclaw/index.js");
+            return new OpenClawAdapter();
+        }
         case "codex": {
             const { CodexAdapter } = await import("./codex/index.js");
             return new CodexAdapter();
@@ -139,6 +188,14 @@ export async function getAdapter(platform) {
             const { CursorAdapter } = await import("./cursor/index.js");
             return new CursorAdapter();
         }
+        case "antigravity": {
+            const { AntigravityAdapter } = await import("./antigravity/index.js");
+            return new AntigravityAdapter();
+        }
+        case "kiro": {
+            const { KiroAdapter } = await import("./kiro/index.js");
+            return new KiroAdapter();
+        }
         default: {
             // Unsupported platform — fall back to Claude Code adapter
             // (MCP server works everywhere, hooks may not)

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

@@ -0,0 +1,32 @@
+/**
+ * adapters/kiro/hooks — Kiro CLI hook definitions and matchers.
+ *
+ * Kiro CLI hook system reference:
+ *   - Hooks are in agent config files (~/.kiro/agents/<name>.json) under "hooks" key
+ *   - Each hook type maps to an array of { matcher, command } entries
+ *   - Hook names: preToolUse, postToolUse, agentSpawn, userPromptSubmit
+ *   - Input: JSON on stdin
+ *   - Output: exit codes (0=allow, 2=block) + stdout/stderr
+ *
+ * Source: https://kiro.dev/docs/cli/custom-agents/configuration-reference#hooks-field
+ */
+export declare const HOOK_TYPES: {
+    readonly PRE_TOOL_USE: "preToolUse";
+    readonly POST_TOOL_USE: "postToolUse";
+    readonly AGENT_SPAWN: "agentSpawn";
+    readonly USER_PROMPT_SUBMIT: "userPromptSubmit";
+};
+export type HookType = (typeof HOOK_TYPES)[keyof typeof HOOK_TYPES];
+export declare const HOOK_SCRIPTS: Record<string, string>;
+export declare const REQUIRED_HOOKS: string[];
+export declare const OPTIONAL_HOOKS: string[];
+/**
+ * Check if a hook entry points to a context-mode hook script.
+ */
+export declare function isContextModeHook(entry: {
+    command?: string;
+}, hookType: string): boolean;
+/**
+ * Build the hook command string for a given hook type.
+ */
+export declare function buildHookCommand(hookType: string, pluginRoot?: string): string;

package/build/adapters/kiro/hooks.js

@@ -0,0 +1,47 @@
+/**
+ * adapters/kiro/hooks — Kiro CLI hook definitions and matchers.
+ *
+ * Kiro CLI hook system reference:
+ *   - Hooks are in agent config files (~/.kiro/agents/<name>.json) under "hooks" key
+ *   - Each hook type maps to an array of { matcher, command } entries
+ *   - Hook names: preToolUse, postToolUse, agentSpawn, userPromptSubmit
+ *   - Input: JSON on stdin
+ *   - Output: exit codes (0=allow, 2=block) + stdout/stderr
+ *
+ * Source: https://kiro.dev/docs/cli/custom-agents/configuration-reference#hooks-field
+ */
+export const HOOK_TYPES = {
+    PRE_TOOL_USE: "preToolUse",
+    POST_TOOL_USE: "postToolUse",
+    AGENT_SPAWN: "agentSpawn",
+    USER_PROMPT_SUBMIT: "userPromptSubmit",
+};
+export const HOOK_SCRIPTS = {
+    [HOOK_TYPES.PRE_TOOL_USE]: "pretooluse.mjs",
+    [HOOK_TYPES.POST_TOOL_USE]: "posttooluse.mjs",
+};
+export const REQUIRED_HOOKS = [
+    HOOK_TYPES.PRE_TOOL_USE,
+];
+export const OPTIONAL_HOOKS = [
+    HOOK_TYPES.POST_TOOL_USE,
+];
+/**
+ * Check if a hook entry points to a context-mode hook script.
+ */
+export function isContextModeHook(entry, hookType) {
+    const scriptName = HOOK_SCRIPTS[hookType];
+    if (!scriptName)
+        return false;
+    return entry.command?.includes(scriptName) || entry.command?.includes("context-mode hook kiro") || false;
+}
+/**
+ * Build the hook command string for a given hook type.
+ */
+export function buildHookCommand(hookType, pluginRoot) {
+    const scriptName = HOOK_SCRIPTS[hookType];
+    if (pluginRoot && scriptName) {
+        return `node "${pluginRoot}/hooks/kiro/${scriptName}"`;
+    }
+    return `context-mode hook kiro ${hookType.toLowerCase()}`;
+}

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

@@ -0,0 +1,50 @@
+/**
+ * adapters/kiro — Kiro IDE/CLI platform adapter.
+ *
+ * Implements HookAdapter for Kiro's hooks-capable paradigm (json-stdio).
+ *
+ * Kiro specifics:
+ *   - Hooks via agent config files (~/.kiro/agents/<name>.json)
+ *   - Config: ~/.kiro/settings/mcp_config.json (JSON format)
+ *   - MCP: full support via mcpServers in mcp_config.json
+ *   - Hook exit codes: 0=allow, 2=block
+ *   - Cannot modify tool input (exit codes only)
+ *   - Session dir: ~/.kiro/context-mode/sessions/
+ *   - Routing file: KIRO.md
+ *
+ * Sources:
+ *   - MCP config: https://kiro.dev/docs/mcp/configuration/
+ *   - clientInfo.name: https://github.com/kirodotdev/Kiro/issues/5205 ("Kiro CLI")
+ *   - CLI hooks: https://kiro.dev/docs/cli/custom-agents/configuration-reference#hooks-field
+ */
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration, RoutingInstructionsConfig } from "../types.js";
+export declare class KiroAdapter implements HookAdapter {
+    readonly name = "Kiro";
+    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;
+    getSettingsPath(): string;
+    getSessionDir(): string;
+    getSessionDBPath(projectDir: string): string;
+    getSessionEventsPath(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;
+    getRoutingInstructionsConfig(): RoutingInstructionsConfig;
+    writeRoutingInstructions(projectDir: string, pluginRoot: string): string | null;
+    getRoutingInstructions(): string;
+}

package/build/adapters/kiro/index.js

@@ -0,0 +1,325 @@
+/**
+ * adapters/kiro — Kiro IDE/CLI platform adapter.
+ *
+ * Implements HookAdapter for Kiro's hooks-capable paradigm (json-stdio).
+ *
+ * Kiro specifics:
+ *   - Hooks via agent config files (~/.kiro/agents/<name>.json)
+ *   - Config: ~/.kiro/settings/mcp_config.json (JSON format)
+ *   - MCP: full support via mcpServers in mcp_config.json
+ *   - Hook exit codes: 0=allow, 2=block
+ *   - Cannot modify tool input (exit codes only)
+ *   - Session dir: ~/.kiro/context-mode/sessions/
+ *   - Routing file: KIRO.md
+ *
+ * Sources:
+ *   - MCP config: https://kiro.dev/docs/mcp/configuration/
+ *   - clientInfo.name: https://github.com/kirodotdev/Kiro/issues/5205 ("Kiro CLI")
+ *   - CLI hooks: https://kiro.dev/docs/cli/custom-agents/configuration-reference#hooks-field
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, accessSync, constants, } from "node:fs";
+import { resolve, join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { HOOK_TYPES as KIRO_HOOK_TYPES, buildHookCommand as buildKiroHookCommand, isContextModeHook as isKiroContextModeHook, } from "./hooks.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class KiroAdapter {
+    name = "Kiro";
+    paradigm = "json-stdio";
+    capabilities = {
+        preToolUse: true,
+        postToolUse: true,
+        preCompact: false,
+        sessionStart: false,
+        canModifyArgs: false, // Kiro CLI uses exit codes, can't modify input
+        canModifyOutput: false,
+        canInjectSessionContext: false,
+    };
+    // ── Input parsing ──────────────────────────────────────
+    parsePreToolUseInput(raw) {
+        const input = raw;
+        return {
+            toolName: input.tool_name ?? "",
+            toolInput: input.tool_input ?? {},
+            sessionId: `pid-${process.ppid}`,
+            projectDir: input.cwd ?? process.cwd(),
+            raw,
+        };
+    }
+    parsePostToolUseInput(raw) {
+        const input = raw;
+        const toolResponse = input.tool_response;
+        return {
+            toolName: input.tool_name ?? "",
+            toolInput: input.tool_input ?? {},
+            toolOutput: typeof toolResponse === "string"
+                ? toolResponse
+                : JSON.stringify(toolResponse ?? ""),
+            sessionId: `pid-${process.ppid}`,
+            projectDir: input.cwd ?? process.cwd(),
+            raw,
+        };
+    }
+    parsePreCompactInput(_raw) {
+        throw new Error("Kiro does not support PreCompact hooks");
+    }
+    parseSessionStartInput(_raw) {
+        throw new Error("Kiro does not support SessionStart hooks (yet)");
+    }
+    // ── Response formatting ────────────────────────────────
+    formatPreToolUseResponse(response) {
+        // Kiro CLI uses exit codes — this format is for adapter interface completeness.
+        // The actual hook script handles exit codes directly.
+        switch (response.decision) {
+            case "deny":
+                return { exitCode: 2, stderr: response.reason ?? "Blocked by context-mode" };
+            case "context":
+                return { exitCode: 0, stdout: response.additionalContext ?? "" };
+            default:
+                return undefined; // allow — no output needed
+        }
+    }
+    formatPostToolUseResponse(_response) {
+        return undefined; // PostToolUse is non-blocking
+    }
+    formatPreCompactResponse(_response) {
+        return undefined;
+    }
+    formatSessionStartResponse(_response) {
+        return undefined;
+    }
+    // ── Configuration ──────────────────────────────────────
+    getSettingsPath() {
+        return resolve(homedir(), ".kiro", "settings", "mcp_config.json");
+    }
+    getSessionDir() {
+        const dir = join(homedir(), ".kiro", "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) {
+        // Kiro CLI hook config format: { preToolUse: [{ matcher, command }] }
+        // Note: This generates the entries for agent config files
+        return {
+            [KIRO_HOOK_TYPES.PRE_TOOL_USE]: [{
+                    matcher: "*",
+                    hooks: [{ type: "command", command: buildKiroHookCommand(KIRO_HOOK_TYPES.PRE_TOOL_USE, pluginRoot) }],
+                }],
+            [KIRO_HOOK_TYPES.POST_TOOL_USE]: [{
+                    matcher: "*",
+                    hooks: [{ type: "command", command: buildKiroHookCommand(KIRO_HOOK_TYPES.POST_TOOL_USE, pluginRoot) }],
+                }],
+        };
+    }
+    readSettings() {
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    writeSettings(settings) {
+        const settingsPath = this.getSettingsPath();
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), "utf-8");
+    }
+    // ── Diagnostics (doctor) ─────────────────────────────────
+    validateHooks(pluginRoot) {
+        const results = [];
+        const defaultAgent = resolve(homedir(), ".kiro", "agents", "default.json");
+        try {
+            const config = JSON.parse(readFileSync(defaultAgent, "utf-8"));
+            const hooks = config.hooks ?? {};
+            // Check required hooks
+            for (const hookType of [KIRO_HOOK_TYPES.PRE_TOOL_USE]) {
+                const entries = hooks[hookType] ?? [];
+                const found = entries.some((e) => isKiroContextModeHook(e, hookType));
+                results.push({
+                    check: `Hook: ${hookType}`,
+                    status: found ? "pass" : "fail",
+                    message: found
+                        ? `context-mode ${hookType} hook found`
+                        : `context-mode ${hookType} hook not configured`,
+                    ...(found ? {} : { fix: `Run: context-mode upgrade` }),
+                });
+            }
+            // Check optional hooks
+            for (const hookType of [KIRO_HOOK_TYPES.POST_TOOL_USE]) {
+                const entries = hooks[hookType] ?? [];
+                const found = entries.some((e) => isKiroContextModeHook(e, hookType));
+                results.push({
+                    check: `Hook: ${hookType}`,
+                    status: found ? "pass" : "warn",
+                    message: found
+                        ? `context-mode ${hookType} hook found`
+                        : `context-mode ${hookType} hook not configured (optional)`,
+                });
+            }
+        }
+        catch {
+            results.push({
+                check: "Hook configuration",
+                status: "warn",
+                message: "Could not read ~/.kiro/agents/default.json",
+                fix: "Run: context-mode upgrade",
+            });
+        }
+        return results;
+    }
+    checkPluginRegistration() {
+        try {
+            const raw = readFileSync(this.getSettingsPath(), "utf-8");
+            const config = JSON.parse(raw);
+            const mcpServers = config?.mcpServers ?? {};
+            if ("context-mode" in mcpServers) {
+                return {
+                    check: "MCP registration",
+                    status: "pass",
+                    message: "context-mode found in mcpServers config",
+                };
+            }
+            return {
+                check: "MCP registration",
+                status: "fail",
+                message: "context-mode not found in mcpServers",
+                fix: "Add context-mode to mcpServers in ~/.kiro/settings/mcp_config.json",
+            };
+        }
+        catch {
+            return {
+                check: "MCP registration",
+                status: "warn",
+                message: "Could not read ~/.kiro/settings/mcp_config.json",
+            };
+        }
+    }
+    getInstalledVersion() {
+        try {
+            const pkgPath = resolve(homedir(), ".kiro", "extensions", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            return pkg.version ?? "unknown";
+        }
+        catch {
+            return "not installed";
+        }
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    configureAllHooks(pluginRoot) {
+        const changes = [];
+        const configDir = resolve(homedir(), ".kiro", "agents");
+        const defaultAgent = resolve(configDir, "default.json");
+        try {
+            mkdirSync(configDir, { recursive: true });
+            let config = {};
+            try {
+                config = JSON.parse(readFileSync(defaultAgent, "utf-8"));
+            }
+            catch {
+                // No existing config — create new
+            }
+            const hooks = (config.hooks ?? {});
+            // Add preToolUse hook if not present
+            const preToolUseEntries = (hooks[KIRO_HOOK_TYPES.PRE_TOOL_USE] ?? []);
+            if (!preToolUseEntries.some(e => isKiroContextModeHook(e, KIRO_HOOK_TYPES.PRE_TOOL_USE))) {
+                preToolUseEntries.push({
+                    matcher: "*",
+                    command: buildKiroHookCommand(KIRO_HOOK_TYPES.PRE_TOOL_USE, pluginRoot),
+                });
+                hooks[KIRO_HOOK_TYPES.PRE_TOOL_USE] = preToolUseEntries;
+                changes.push(`Added ${KIRO_HOOK_TYPES.PRE_TOOL_USE} hook to ${defaultAgent}`);
+            }
+            // Add postToolUse hook if not present
+            const postToolUseEntries = (hooks[KIRO_HOOK_TYPES.POST_TOOL_USE] ?? []);
+            if (!postToolUseEntries.some(e => isKiroContextModeHook(e, KIRO_HOOK_TYPES.POST_TOOL_USE))) {
+                postToolUseEntries.push({
+                    matcher: "*",
+                    command: buildKiroHookCommand(KIRO_HOOK_TYPES.POST_TOOL_USE, pluginRoot),
+                });
+                hooks[KIRO_HOOK_TYPES.POST_TOOL_USE] = postToolUseEntries;
+                changes.push(`Added ${KIRO_HOOK_TYPES.POST_TOOL_USE} hook to ${defaultAgent}`);
+            }
+            config.hooks = hooks;
+            writeFileSync(defaultAgent, JSON.stringify(config, null, 2), "utf-8");
+        }
+        catch (err) {
+            changes.push(`Failed to configure hooks: ${err.message}`);
+        }
+        return changes;
+    }
+    backupSettings() {
+        const settingsPath = this.getSettingsPath();
+        try {
+            accessSync(settingsPath, constants.R_OK);
+            const backupPath = settingsPath + ".bak";
+            copyFileSync(settingsPath, backupPath);
+            return backupPath;
+        }
+        catch {
+            return null;
+        }
+    }
+    setHookPermissions(_pluginRoot) {
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // Kiro plugin registry is managed via mcp_config.json
+    }
+    // ── Routing Instructions (soft enforcement) ────────────
+    getRoutingInstructionsConfig() {
+        return {
+            fileName: "KIRO.md",
+            globalPath: resolve(homedir(), ".kiro", "KIRO.md"),
+            projectRelativePath: "KIRO.md",
+        };
+    }
+    writeRoutingInstructions(projectDir, pluginRoot) {
+        const config = this.getRoutingInstructionsConfig();
+        const targetPath = resolve(projectDir, config.projectRelativePath);
+        const sourcePath = resolve(pluginRoot, "configs", "kiro", 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;
+        }
+    }
+    getRoutingInstructions() {
+        const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "configs", "kiro", "KIRO.md");
+        try {
+            return readFileSync(instructionsPath, "utf-8");
+        }
+        catch {
+            return "# context-mode\n\nUse context-mode MCP tools (execute, execute_file, batch_execute, fetch_and_index, search) instead of run_command/view_file for data-heavy operations.";
+        }
+    }
+}

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

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

package/build/adapters/openclaw/config.js

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

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

@@ -0,0 +1,50 @@
+/**
+ * adapters/openclaw/hooks — OpenClaw hook definitions and validators.
+ *
+ * Defines the hook types and validation helpers specific to OpenClaw's
+ * TypeScript plugin paradigm. This module is used by:
+ *   - CLI setup/upgrade commands (to configure plugin in openclaw.json)
+ *   - Doctor command (to validate plugin configuration)
+ *
+ * OpenClaw hook system reference:
+ *   - I/O: TS plugin functions via api.registerHook() and api.on()
+ *   - Hook events: tool_call:before, tool_call:after, command:new, command:reset
+ *   - Lifecycle: session_start, before_compaction, after_compaction, before_prompt_build, before_model_resolve
+ *   - Context engine: api.registerContextEngine() with ownsCompaction
+ *   - Blocking: return { block: true, blockReason } from tool_call:before
+ *   - Config: openclaw.json plugins.entries, ~/.openclaw/extensions/
+ */
+/** OpenClaw hook event names (registered via api.registerHook). */
+export declare const HOOK_EVENTS: {
+    readonly TOOL_CALL_BEFORE: "tool_call:before";
+    readonly TOOL_CALL_AFTER: "tool_call:after";
+    readonly COMMAND_NEW: "command:new";
+    readonly COMMAND_RESET: "command:reset";
+    readonly COMMAND_STOP: "command:stop";
+};
+/** OpenClaw lifecycle hook names (registered via api.on). */
+export declare const LIFECYCLE_HOOKS: {
+    readonly SESSION_START: "session_start";
+    readonly BEFORE_COMPACTION: "before_compaction";
+    readonly AFTER_COMPACTION: "after_compaction";
+    readonly BEFORE_PROMPT_BUILD: "before_prompt_build";
+    readonly BEFORE_MODEL_RESOLVE: "before_model_resolve";
+    readonly BEFORE_AGENT_START: "before_agent_start";
+};
+export type HookEvent = (typeof HOOK_EVENTS)[keyof typeof HOOK_EVENTS];
+export type LifecycleHook = (typeof LIFECYCLE_HOOKS)[keyof typeof LIFECYCLE_HOOKS];
+/**
+ * Required hooks that must be active for context-mode to function.
+ * OpenClaw registers these via api.registerHook() in the plugin entry point.
+ */
+export declare const REQUIRED_HOOKS: HookEvent[];
+/**
+ * Optional hooks that enhance functionality but aren't critical.
+ * command:new provides session cleanup; context engine handles compaction.
+ */
+export declare const OPTIONAL_HOOKS: HookEvent[];
+/**
+ * Check if a plugin entry is the context-mode plugin.
+ * OpenClaw plugins are registered by id in plugins.entries.
+ */
+export declare function isContextModePlugin(pluginId: string): boolean;