context-mode 1.0.103 → 1.0.104

package/build/adapters/codex/index.js

@@ -44,7 +44,7 @@ export class CodexAdapter extends BaseAdapter {
             toolName: input.tool_name ?? "",
             toolInput: input.tool_input ?? {},
             sessionId: this.extractSessionId(input),
-            projectDir: input.cwd,
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -55,7 +55,7 @@ export class CodexAdapter extends BaseAdapter {
             toolInput: input.tool_input ?? {},
             toolOutput: input.tool_response,
             sessionId: this.extractSessionId(input),
-            projectDir: input.cwd,
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -63,7 +63,7 @@ export class CodexAdapter extends BaseAdapter {
         const input = raw;
         return {
             sessionId: this.extractSessionId(input),
-            projectDir: input.cwd,
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -87,7 +87,7 @@ export class CodexAdapter extends BaseAdapter {
         return {
             sessionId: this.extractSessionId(input),
             source,
-            projectDir: input.cwd,
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -148,6 +148,14 @@ export class CodexAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".codex", "config.toml");
     }
+    getInstructionFiles() {
+        // Codex CLI honors AGENTS.md plus an optional override file.
+        return ["AGENTS.md", "AGENTS.override.md"];
+    }
+    getMemoryDir() {
+        // Codex uses "memories" (plural), not the default "memory".
+        return resolve(homedir(), ".codex", "memories");
+    }
     generateHookConfig(pluginRoot) {
         return {
             PreToolUse: [
@@ -298,6 +306,16 @@ export class CodexAdapter extends BaseAdapter {
         }
     }
     // ── Internal helpers ───────────────────────────────────
+    /**
+     * 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.
+     */
+    getProjectDir(input) {
+        return input.cwd ?? process.env.CODEX_PROJECT_DIR ?? process.cwd();
+    }
     /**
      * Extract session ID from Codex CLI hook input.
      * Priority: session_id field > fallback to ppid.

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

@@ -32,6 +32,13 @@ export declare class CursorAdapter extends BaseAdapter implements HookAdapter {
         text: string;
     };
     getSettingsPath(): string;
+    /**
+     * Cursor stores conventions per project under .cursor/. Always returned
+     * as an absolute path resolved against `projectDir` (or `process.cwd()`
+     * when omitted) per the HookAdapter.getConfigDir contract.
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/cursor/index.js

@@ -128,6 +128,17 @@ export class CursorAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(".cursor", "hooks.json");
     }
+    /**
+     * Cursor stores conventions per project under .cursor/. Always returned
+     * as an absolute path resolved against `projectDir` (or `process.cwd()`
+     * when omitted) per the HookAdapter.getConfigDir contract.
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? process.cwd(), ".cursor");
+    }
+    getInstructionFiles() {
+        return ["context-mode.mdc"];
+    }
     generateHookConfig(_pluginRoot) {
         const hooks = {
             [CURSOR_HOOK_NAMES.PRE_TOOL_USE]: [

package/build/adapters/detect.d.ts

@@ -23,7 +23,18 @@ import type { PlatformId, DetectionSignal, HookAdapter } from "./types.js";
  * Single source of truth — consumed by detectPlatform() below and by
  * tests that need to clear platform-related env vars deterministically.
  */
-export declare const PLATFORM_ENV_VARS: readonly [readonly ["claude-code", readonly ["CLAUDE_PROJECT_DIR", "CLAUDE_SESSION_ID"]], readonly ["gemini-cli", readonly ["GEMINI_PROJECT_DIR", "GEMINI_CLI"]], readonly ["openclaw", readonly ["OPENCLAW_HOME", "OPENCLAW_CLI"]], readonly ["kilo", readonly ["KILO", "KILO_PID"]], readonly ["opencode", readonly ["OPENCODE", "OPENCODE_PID"]], readonly ["codex", readonly ["CODEX_CI", "CODEX_THREAD_ID"]], readonly ["cursor", readonly ["CURSOR_TRACE_ID", "CURSOR_CLI"]], readonly ["vscode-copilot", readonly ["VSCODE_PID", "VSCODE_CWD"]], readonly ["jetbrains-copilot", readonly ["IDEA_INITIAL_DIRECTORY", "IDEA_HOME", "JETBRAINS_CLIENT_ID"]], readonly ["qwen-code", readonly ["QWEN_PROJECT_DIR", "QWEN_SESSION_ID"]]];
+export declare const PLATFORM_ENV_VARS: readonly [readonly ["claude-code", readonly ["CLAUDE_PROJECT_DIR", "CLAUDE_SESSION_ID"]], readonly ["antigravity", readonly ["ANTIGRAVITY_CLI_ALIAS"]], readonly ["cursor", readonly ["CURSOR_TRACE_ID", "CURSOR_CLI"]], readonly ["kilo", readonly ["KILO_PID"]], readonly ["opencode", readonly ["OPENCODE", "OPENCODE_PID"]], readonly ["zed", readonly ["ZED_SESSION_ID", "ZED_TERM"]], readonly ["codex", readonly ["CODEX_THREAD_ID", "CODEX_CI"]], readonly ["gemini-cli", readonly ["GEMINI_PROJECT_DIR", "GEMINI_CLI"]], readonly ["vscode-copilot", readonly ["VSCODE_PID", "VSCODE_CWD"]], readonly ["jetbrains-copilot", readonly ["IDEA_INITIAL_DIRECTORY"]], readonly ["qwen-code", readonly ["QWEN_PROJECT_DIR"]], readonly ["pi", readonly ["PI_PROJECT_DIR"]]];
+/**
+ * Sync map from platform identifier → home-relative path segments where that
+ * platform stores its config. Mirrors the `super([...])` argument passed by
+ * each adapter — kept in sync as the single source of truth used when we need
+ * a session dir BEFORE an adapter has been instantiated (race window between
+ * MCP server start and `initialize` handshake completion).
+ *
+ * Returns `null` for "unknown" or any string outside the supported set so the
+ * caller can decide on a safe fallback.
+ */
+export declare function getSessionDirSegments(platform: string): string[] | null;
 /**
  * Detect the current platform by checking env vars and config dirs.
  *

package/build/adapters/detect.js

@@ -27,17 +27,79 @@ import { CLIENT_NAME_TO_PLATFORM } from "./client-map.js";
  * tests that need to clear platform-related env vars deterministically.
  */
 export const PLATFORM_ENV_VARS = [
+    // Order matters: forks listed BEFORE the fork's parent so collision
+    // detection works. Every entry verified against platform's own runtime
+    // source code (PR #376 follow-up: full audit, May 2026 — see git blame).
     ["claude-code", ["CLAUDE_PROJECT_DIR", "CLAUDE_SESSION_ID"]],
-    ["gemini-cli", ["GEMINI_PROJECT_DIR", "GEMINI_CLI"]],
-    ["openclaw", ["OPENCLAW_HOME", "OPENCLAW_CLI"]],
-    ["kilo", ["KILO", "KILO_PID"]],
-    ["opencode", ["OPENCODE", "OPENCODE_PID"]],
-    ["codex", ["CODEX_CI", "CODEX_THREAD_ID"]],
+    // antigravity (Electron/VSCode fork) — google-gemini/gemini-cli
+    // packages/core/src/ide/detect-ide.ts checks ANTIGRAVITY_CLI_ALIAS as the
+    // canonical Antigravity marker. Listed before vscode-copilot.
+    ["antigravity", ["ANTIGRAVITY_CLI_ALIAS"]],
+    // cursor (VSCode fork) — listed before vscode-copilot. CURSOR_TRACE_ID has
+    // 800+ hits in major OSS detection libs (Vercel Next.js, Bun, Google
+    // gemini-cli, Nx, CrewAI).
     ["cursor", ["CURSOR_TRACE_ID", "CURSOR_CLI"]],
+    // kilo (OpenCode fork) — Kilo-Org/kilocode packages/opencode/src/index.ts:140
+    // sets `process.env.KILO_PID = String(process.pid)`. Bare KILO is NEVER set
+    // (verified). Kilo also sets OPENCODE=1 (fork) — listed before opencode.
+    ["kilo", ["KILO_PID"]],
+    // opencode — sst/opencode packages/opencode/src/index.ts:108-109 sets
+    // OPENCODE=1 + OPENCODE_PID=<pid> on every CLI invocation.
+    ["opencode", ["OPENCODE", "OPENCODE_PID"]],
+    // zed — zed-industries/zed crates/terminal/src/terminal.rs sets ZED_TERM=true
+    // in `insert_zed_terminal_env()`. Google's gemini-cli uses ZED_SESSION_ID.
+    ["zed", ["ZED_SESSION_ID", "ZED_TERM"]],
+    // codex — openai/codex codex-rs/core/src/exec_env.rs sets CODEX_THREAD_ID
+    // per exec; unified_exec/process_manager.rs sets CODEX_CI in CI mode.
+    ["codex", ["CODEX_THREAD_ID", "CODEX_CI"]],
+    // gemini-cli — GEMINI_PROJECT_DIR per google-gemini/gemini-cli
+    // docs/hooks/index.md; GEMINI_CLI is the MCP-server sentinel.
+    ["gemini-cli", ["GEMINI_PROJECT_DIR", "GEMINI_CLI"]],
+    // vscode-copilot — VSCODE_PID + VSCODE_CWD set by microsoft/vscode bootstrap.
+    // Listed AFTER cursor and antigravity since they inherit these vars as forks.
     ["vscode-copilot", ["VSCODE_PID", "VSCODE_CWD"]],
-    ["jetbrains-copilot", ["IDEA_INITIAL_DIRECTORY", "IDEA_HOME", "JETBRAINS_CLIENT_ID"]],
-    ["qwen-code", ["QWEN_PROJECT_DIR", "QWEN_SESSION_ID"]],
+    // jetbrains-copilot — IDEA_INITIAL_DIRECTORY set by JetBrains launcher.
+    // (IDEA_HOME and JETBRAINS_CLIENT_ID removed — no source-line evidence.)
+    ["jetbrains-copilot", ["IDEA_INITIAL_DIRECTORY"]],
+    // qwen-code — QWEN_PROJECT_DIR per QwenLM/qwen-code docs/users/features/hooks.md.
+    // (QWEN_SESSION_ID removed — 0 hits in qwen-code repository.)
+    ["qwen-code", ["QWEN_PROJECT_DIR"]],
+    // pi — PI_PROJECT_DIR consumed by src/pi-extension.ts:154 + src/server.ts:153
+    // — implies the Pi runtime sets it before invoking the extension.
+    ["pi", ["PI_PROJECT_DIR"]],
+    // openclaw — removed (runtime never sets OPENCLAW_HOME or OPENCLAW_CLI;
+    // detection falls through to ~/.openclaw/ config-dir tier below).
+    // kiro — not listed (no auto-set process env vars; ~/.kiro/ config-dir tier).
 ];
+/**
+ * Sync map from platform identifier → home-relative path segments where that
+ * platform stores its config. Mirrors the `super([...])` argument passed by
+ * each adapter — kept in sync as the single source of truth used when we need
+ * a session dir BEFORE an adapter has been instantiated (race window between
+ * MCP server start and `initialize` handshake completion).
+ *
+ * Returns `null` for "unknown" or any string outside the supported set so the
+ * caller can decide on a safe fallback.
+ */
+export function getSessionDirSegments(platform) {
+    switch (platform) {
+        case "claude-code": return [".claude"];
+        case "gemini-cli": return [".gemini"];
+        case "antigravity": return [".gemini"];
+        case "openclaw": return [".openclaw"];
+        case "codex": return [".codex"];
+        case "cursor": return [".cursor"];
+        case "vscode-copilot": return [".vscode"];
+        case "kiro": return [".kiro"];
+        case "pi": return [".pi"];
+        case "qwen-code": return [".qwen"];
+        case "kilo": return [".config", "kilo"];
+        case "opencode": return [".config", "opencode"];
+        case "zed": return [".config", "zed"];
+        case "jetbrains-copilot": return [".config", "JetBrains"];
+        default: return null;
+    }
+}
 /**
  * Detect the current platform by checking env vars and config dirs.
  *

package/build/adapters/gemini-cli/index.d.ts

@@ -34,6 +34,7 @@ export declare class GeminiCLIAdapter extends BaseAdapter implements HookAdapter
     formatPreCompactResponse(response: PreCompactResponse): unknown;
     formatSessionStartResponse(response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    getInstructionFiles(): string[];
     generateHookConfig(pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;
@@ -43,7 +44,13 @@ export declare class GeminiCLIAdapter extends BaseAdapter implements HookAdapter
     configureAllHooks(pluginRoot: string): string[];
     setHookPermissions(pluginRoot: string): string[];
     updatePluginRegistry(pluginRoot: string, version: string): void;
-    /** Get the project directory from environment variables. */
+    /**
+     * Resolve the project directory for a Gemini CLI hook input.
+     * Priority: input.cwd > GEMINI_PROJECT_DIR > CLAUDE_PROJECT_DIR > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even when the platform omits cwd
+     * from the wire payload (e.g. under worktrees).
+     */
     private getProjectDir;
     /**
      * Extract session ID from Gemini CLI hook input.

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

@@ -51,7 +51,7 @@ export class GeminiCLIAdapter extends BaseAdapter {
             toolName: input.tool_name ?? "",
             toolInput: input.tool_input ?? {},
             sessionId: this.extractSessionId(input),
-            projectDir: this.getProjectDir(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -63,7 +63,7 @@ export class GeminiCLIAdapter extends BaseAdapter {
             toolOutput: input.tool_output,
             isError: input.is_error,
             sessionId: this.extractSessionId(input),
-            projectDir: this.getProjectDir(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -71,7 +71,7 @@ export class GeminiCLIAdapter extends BaseAdapter {
         const input = raw;
         return {
             sessionId: this.extractSessionId(input),
-            projectDir: this.getProjectDir(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -95,7 +95,7 @@ export class GeminiCLIAdapter extends BaseAdapter {
         return {
             sessionId: this.extractSessionId(input),
             source,
-            projectDir: this.getProjectDir(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -160,6 +160,9 @@ export class GeminiCLIAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".gemini", "settings.json");
     }
+    getInstructionFiles() {
+        return ["GEMINI.md"];
+    }
     generateHookConfig(pluginRoot) {
         return {
             [GEMINI_HOOK_NAMES.BEFORE_TOOL]: [
@@ -394,9 +397,18 @@ export class GeminiCLIAdapter extends BaseAdapter {
         }
     }
     // ── Internal helpers ───────────────────────────────────
-    /** Get the project directory from environment variables. */
-    getProjectDir() {
-        return process.env.GEMINI_PROJECT_DIR ?? process.env.CLAUDE_PROJECT_DIR;
+    /**
+     * Resolve the project directory for a Gemini CLI hook input.
+     * Priority: input.cwd > GEMINI_PROJECT_DIR > CLAUDE_PROJECT_DIR > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even when the platform omits cwd
+     * from the wire payload (e.g. under worktrees).
+     */
+    getProjectDir(input) {
+        return (input.cwd
+            ?? process.env.GEMINI_PROJECT_DIR
+            ?? process.env.CLAUDE_PROJECT_DIR
+            ?? process.cwd());
     }
     /**
      * Extract session ID from Gemini CLI hook input.

package/build/adapters/jetbrains-copilot/index.d.ts

@@ -18,6 +18,13 @@ export declare class JetBrainsCopilotAdapter extends CopilotBaseAdapter {
     protected readonly hookSubdir = "jetbrains-copilot";
     protected extractSessionId(input: CopilotHookInput): string;
     protected getProjectDir(): string;
+    /**
+     * JetBrains Copilot honors .github/copilot-instructions.md per project.
+     * Always returned absolute, resolved against the supplied `projectDir`,
+     * the JetBrains-specific project env vars, or `process.cwd()`.
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
     validateHooks(pluginRoot: string): DiagnosticResult[];
     checkPluginRegistration(): DiagnosticResult;
     getInstalledVersion(): string;

package/build/adapters/jetbrains-copilot/index.js

@@ -9,6 +9,7 @@
  *   - validateHooks: JetBrains-specific warnings
  */
 import { readFileSync, } from "node:fs";
+import { resolve } from "node:path";
 import { CopilotBaseAdapter } from "../copilot-base.js";
 // ─────────────────────────────────────────────────────────
 // Hook constants (re-exported from hooks.ts)
@@ -42,6 +43,17 @@ export class JetBrainsCopilotAdapter extends CopilotBaseAdapter {
     getProjectDir() {
         return process.env.IDEA_INITIAL_DIRECTORY || process.env.CLAUDE_PROJECT_DIR || process.cwd();
     }
+    /**
+     * JetBrains Copilot honors .github/copilot-instructions.md per project.
+     * Always returned absolute, resolved against the supplied `projectDir`,
+     * the JetBrains-specific project env vars, or `process.cwd()`.
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? this.getProjectDir(), ".github");
+    }
+    getInstructionFiles() {
+        return ["copilot-instructions.md"];
+    }
     // ── Diagnostics (doctor) ─────────────────────────────────
     validateHooks(pluginRoot) {
         const results = [];

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

@@ -33,6 +33,14 @@ export declare class KiroAdapter extends BaseAdapter implements HookAdapter {
     formatPreCompactResponse(_response: PreCompactResponse): unknown;
     formatSessionStartResponse(_response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    /**
+     * Kiro stores per-project context under .kiro/ (steering files, etc).
+     * Auto-memory + rule detection use this project-relative dir, returned as
+     * an absolute path resolved against `projectDir` (or `process.cwd()`).
+     * (Settings/MCP config still live under ~/.kiro/.)
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
     generateHookConfig(pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/kiro/index.js

@@ -98,6 +98,18 @@ export class KiroAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".kiro", "settings", "mcp.json");
     }
+    /**
+     * Kiro stores per-project context under .kiro/ (steering files, etc).
+     * Auto-memory + rule detection use this project-relative dir, returned as
+     * an absolute path resolved against `projectDir` (or `process.cwd()`).
+     * (Settings/MCP config still live under ~/.kiro/.)
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? process.cwd(), ".kiro");
+    }
+    getInstructionFiles() {
+        return ["KIRO.md"];
+    }
     generateHookConfig(pluginRoot) {
         // Kiro CLI hook config format: { preToolUse: [{ matcher, command }] }
         // Note: This generates the entries for agent config files

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

@@ -31,6 +31,15 @@ export declare class OpenClawAdapter extends BaseAdapter implements HookAdapter
     formatPreCompactResponse(response: PreCompactResponse): unknown;
     formatSessionStartResponse(response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    /**
+     * OpenClaw stores everything in the project root — no separate config
+     * dir. Returned as the absolute project directory itself per the
+     * HookAdapter.getConfigDir contract (always-absolute).
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
+    /** Absolute <projectRoot>/memory directory. */
+    getMemoryDir(): string;
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;
@@ -41,6 +50,14 @@ export declare class OpenClawAdapter extends BaseAdapter implements HookAdapter
     backupSettings(): string | null;
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
+    /**
+     * Resolve the project directory for an OpenClaw hook input.
+     * Priority: input.cwd > OPENCLAW_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;
     /**
      * Extract session ID from OpenClaw hook input.
      */

package/build/adapters/openclaw/index.js

@@ -48,7 +48,7 @@ export class OpenClawAdapter extends BaseAdapter {
             toolName: input.toolName ?? input.tool_name ?? "",
             toolInput: input.params ?? input.tool_input ?? {},
             sessionId: this.extractSessionId(input),
-            projectDir: process.cwd(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -60,7 +60,7 @@ export class OpenClawAdapter extends BaseAdapter {
             toolOutput: input.output ?? input.tool_output,
             isError: input.isError ?? input.is_error,
             sessionId: this.extractSessionId(input),
-            projectDir: process.cwd(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -68,7 +68,7 @@ export class OpenClawAdapter extends BaseAdapter {
         const input = raw;
         return {
             sessionId: this.extractSessionId(input),
-            projectDir: process.cwd(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -92,7 +92,7 @@ export class OpenClawAdapter extends BaseAdapter {
         return {
             sessionId: this.extractSessionId(input),
             source,
-            projectDir: process.cwd(),
+            projectDir: this.getProjectDir(input),
             raw,
         };
     }
@@ -143,6 +143,21 @@ export class OpenClawAdapter extends BaseAdapter {
         // OpenClaw uses openclaw.json in the project root or ~/.openclaw/openclaw.json
         return resolve("openclaw.json");
     }
+    /**
+     * OpenClaw stores everything in the project root — no separate config
+     * dir. Returned as the absolute project directory itself per the
+     * HookAdapter.getConfigDir contract (always-absolute).
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? process.cwd());
+    }
+    getInstructionFiles() {
+        return ["AGENTS.md"];
+    }
+    /** Absolute <projectRoot>/memory directory. */
+    getMemoryDir() {
+        return join(this.getConfigDir(), "memory");
+    }
     generateHookConfig(_pluginRoot) {
         // OpenClaw uses TS plugin paradigm — hooks are registered via
         // api.registerHook() in the plugin entry point, not via config files.
@@ -394,6 +409,16 @@ export class OpenClawAdapter extends BaseAdapter {
         // OpenClaw manages plugins through npm/openclaw.json — no separate registry
     }
     // ── Internal helpers ───────────────────────────────────
+    /**
+     * Resolve the project directory for an OpenClaw hook input.
+     * Priority: input.cwd > OPENCLAW_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.
+     */
+    getProjectDir(input) {
+        return input.cwd ?? process.env.OPENCLAW_PROJECT_DIR ?? process.cwd();
+    }
     /**
      * Extract session ID from OpenClaw hook input.
      */

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

@@ -36,6 +36,14 @@ export declare class OpenCodeAdapter extends BaseAdapter implements HookAdapter
     getSettingsPath(): string;
     private paths;
     getSessionDir(): string;
+    /**
+     * OpenCode/KiloCode honor XDG_CONFIG_HOME on POSIX and APPDATA on Windows.
+     * Falls back to ~/.config/<platform> (or %APPDATA%\<platform>).
+     * Always absolute. `_projectDir` is accepted for interface symmetry but
+     * unused — config is home/XDG-rooted, never project-scoped.
+     */
+    getConfigDir(_projectDir?: string): string;
+    getInstructionFiles(): string[];
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/opencode/index.js

@@ -171,16 +171,28 @@ export class OpenCodeAdapter extends BaseAdapter {
         ];
     }
     getSessionDir() {
-        let configDir;
+        const dir = join(this.getConfigDir(), "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    /**
+     * OpenCode/KiloCode honor XDG_CONFIG_HOME on POSIX and APPDATA on Windows.
+     * Falls back to ~/.config/<platform> (or %APPDATA%\<platform>).
+     * Always absolute. `_projectDir` is accepted for interface symmetry but
+     * unused — config is home/XDG-rooted, never project-scoped.
+     */
+    getConfigDir(_projectDir) {
+        let root;
         if (process.platform === "win32") {
-            configDir = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+            root = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
         }
         else {
-            configDir = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+            root = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
         }
-        const dir = join(configDir, this.platform, "context-mode", "sessions");
-        mkdirSync(dir, { recursive: true });
-        return dir;
+        return join(root, this.platform);
+    }
+    getInstructionFiles() {
+        return ["AGENTS.md"];
     }
     generateHookConfig(_pluginRoot) {
         // OpenCode uses TS plugin paradigm — hooks are registered via plugin array

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

@@ -21,6 +21,7 @@ export declare class QwenCodeAdapter extends ClaudeCodeBaseAdapter implements Ho
     protected readonly projectDirEnvVar = "QWEN_PROJECT_DIR";
     readonly capabilities: PlatformCapabilities;
     getSettingsPath(): string;
+    getInstructionFiles(): string[];
     generateHookConfig(pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

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

@@ -40,6 +40,9 @@ export class QwenCodeAdapter extends ClaudeCodeBaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".qwen", "settings.json");
     }
+    getInstructionFiles() {
+        return ["QWEN.md"];
+    }
     generateHookConfig(pluginRoot) {
         // Qwen Code passes native tool names in hook stdin (verified from
         // packages/core/src/tools/tool-names.ts). Claude-style names (Bash, Read)

package/build/adapters/types.d.ts

@@ -160,6 +160,39 @@ export interface HookAdapter {
     getSessionDBPath(projectDir: string): string;
     /** Compute per-project session events file path. */
     getSessionEventsPath(projectDir: string): string;
+    /**
+     * Platform config directory.
+     *
+     * Contract: ALWAYS returns an absolute path. Never returns a relative
+     * segment, never returns an empty string. This eliminates the leaky-seam
+     * where callers could not tell whether the return needed further resolution.
+     *
+     * Resolution rules:
+     *   - Home-rooted platforms (claude-code, codex, qwen, gemini, antigravity,
+     *     zed, opencode, …) return paths under `homedir()` / XDG / APPDATA.
+     *   - Project-scoped platforms (cursor → `.cursor`, vscode-copilot &
+     *     jetbrains-copilot → `.github`, kiro → `.kiro`, openclaw → project root)
+     *     resolve their segment against the supplied `projectDir`. When
+     *     `projectDir` is omitted, `process.cwd()` is used as the fallback.
+     *
+     * @param projectDir Optional project root used to resolve project-scoped
+     *                   adapters. Ignored by home-rooted adapters.
+     */
+    getConfigDir(projectDir?: string): string;
+    /**
+     * Names of platform-native instruction/rule files that act as the
+     * project's "user CLAUDE.md equivalent" (e.g., ["CLAUDE.md"],
+     * ["AGENTS.md"], ["GEMINI.md"]). Auto-memory scans for these in the
+     * project root and config dir, and rule-detection emits "rule" events
+     * when they are read.
+     */
+    getInstructionFiles(): string[];
+    /**
+     * Directory where persistent per-user memory is stored
+     * (e.g., ~/.claude/memory, ~/.codex/memories). Auto-memory scans
+     * *.md files in this directory.
+     */
+    getMemoryDir(): string;
     /** Generate hook registration config for this platform. */
     generateHookConfig(pluginRoot: string): HookRegistration;
     /** Read current platform settings. */

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

@@ -20,6 +20,12 @@ export declare class VSCodeCopilotAdapter extends CopilotBaseAdapter {
     protected extractSessionId(input: CopilotHookInput): string;
     protected getProjectDir(): string;
     getSessionDir(): string;
+    /**
+     * VS Code Copilot honors .github/copilot-instructions.md per project.
+     * Always returned absolute, resolved against `projectDir` (or `cwd`).
+     */
+    getConfigDir(projectDir?: string): string;
+    getInstructionFiles(): string[];
     validateHooks(pluginRoot: string): DiagnosticResult[];
     checkPluginRegistration(): DiagnosticResult;
     getInstalledVersion(): string;

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

@@ -53,6 +53,16 @@ export class VSCodeCopilotAdapter extends CopilotBaseAdapter {
         mkdirSync(dir, { recursive: true });
         return dir;
     }
+    /**
+     * VS Code Copilot honors .github/copilot-instructions.md per project.
+     * Always returned absolute, resolved against `projectDir` (or `cwd`).
+     */
+    getConfigDir(projectDir) {
+        return resolve(projectDir ?? process.cwd(), ".github");
+    }
+    getInstructionFiles() {
+        return ["copilot-instructions.md"];
+    }
     // ── Diagnostics (doctor) ─────────────────────────────────
     validateHooks(pluginRoot) {
         const results = [];

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

@@ -26,6 +26,7 @@ export declare class ZedAdapter extends BaseAdapter implements HookAdapter {
     formatPreCompactResponse(_response: PreCompactResponse): unknown;
     formatSessionStartResponse(_response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    getInstructionFiles(): string[];
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/zed/index.js

@@ -66,6 +66,9 @@ export class ZedAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".config", "zed", "settings.json");
     }
+    getInstructionFiles() {
+        return ["AGENTS.md"];
+    }
     generateHookConfig(_pluginRoot) {
         // Zed does not support hooks — return empty registration
         return {};