context-mode 1.0.103 → 1.0.105

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Claude Code plugins by Mert Koseoğlu",
-    "version": "1.0.103"
+    "version": "1.0.105"
   },
   "plugins": [
     {
       "name": "context-mode",
       "source": "./",
       "description": "Claude Code MCP plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-      "version": "1.0.103",
+      "version": "1.0.105",
       "author": {
         "name": "Mert Koseoğlu"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.103",
+  "version": "1.0.105",
   "description": "MCP server that saves 98% of your context window with session continuity. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and automatic state restore across compactions.",
   "author": {
     "name": "Mert Koseoğlu",

package/.openclaw-plugin/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "Context Mode",
   "kind": "tool",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
-  "version": "1.0.103",
+  "version": "1.0.105",
   "sandbox": {
     "mode": "permissive",
     "filesystem_access": "full",

package/.openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mode",
-  "version": "1.0.103",
+  "version": "1.0.105",
   "description": "OpenClaw plugin that saves 98% of your context window. Sandboxed code execution in 11 languages, FTS5 knowledge base with BM25 ranking, and intent-driven search.",
   "author": {
     "name": "Mert Koseoğlu",

package/README.md

@@ -83,7 +83,7 @@ Restart Claude Code (or run `/reload-plugins`).
 
 All checks should show `[x]`. The doctor validates runtimes, hooks, FTS5, and plugin registration.
 
-**Routing:** Automatic. The SessionStart hook injects routing instructions at runtime — no file is written to your project. The plugin registers all hooks (PreToolUse, PostToolUse, PreCompact, SessionStart) and 6 sandbox tools (`ctx_batch_execute`, `ctx_execute`, `ctx_execute_file`, `ctx_index`, `ctx_search`, `ctx_fetch_and_index`) plus meta-tools (`ctx_stats`, `ctx_doctor`, `ctx_upgrade`, `ctx_purge`, `ctx_insight`).
+**Routing:** Automatic. The SessionStart hook injects routing instructions at runtime — no file is written to your project. The plugin registers all hooks (PreToolUse, PostToolUse, PreCompact, SessionStart) and 11 MCP tools — six sandbox tools (`ctx_batch_execute`, `ctx_execute`, `ctx_execute_file`, `ctx_index`, `ctx_search`, `ctx_fetch_and_index`) plus five meta-tools (`ctx_stats`, `ctx_doctor`, `ctx_upgrade`, `ctx_purge`, `ctx_insight`).
 
 | Slash Command | What it does |
 |---|---|
@@ -95,6 +95,19 @@ All checks should show `[x]`. The doctor validates runtimes, hooks, FTS5, and pl
 
 > **Note:** Slash commands are a Claude Code plugin feature. On other platforms, type `ctx stats`, `ctx doctor`, `ctx upgrade`, or `ctx insight` in the chat — the model calls the MCP tool automatically. See [Utility Commands](#utility-commands).
 
+**Status line (optional):** Claude Code's plugin manifest cannot declare a status line, so this is a one-time manual edit to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "context-mode statusline"
+  }
+}
+```
+
+After saving, restart Claude Code. The bar shows `$ saved this session · $ saved across sessions · % efficient` so you can see savings accumulate in real time. The wiring is path-free — `context-mode statusline` resolves through the bundled CLI regardless of where the plugin cache lives.
+
 <details>
 <summary>Alternative — MCP-only install (no hooks or slash commands)</summary>
 
@@ -102,7 +115,7 @@ All checks should show `[x]`. The doctor validates runtimes, hooks, FTS5, and pl
 claude mcp add context-mode -- npx -y context-mode
 ```
 
-This gives you the 6 sandbox tools without automatic routing. The model can still use them — it just won't be nudged to prefer them over raw Bash/Read/WebFetch. Good for trying it out before committing to the full plugin.
+This gives you all 11 MCP tools without automatic routing. The model can still use them — it just won't be nudged to prefer them over raw Bash/Read/WebFetch. Good for trying it out before committing to the full plugin.
 
 </details>
 
@@ -389,7 +402,7 @@ Full configs: [`configs/cursor/hooks.json`](configs/cursor/hooks.json) | [`confi
    }
    ```
 
-   The `mcp` entry registers the 6 sandbox tools. The `plugin` entry enables hooks — OpenCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
+   The `mcp` entry registers all 11 MCP tools. The `plugin` entry enables hooks — OpenCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
 
 3. *(Optional)* Copy the routing rules file. OpenCode lacks a SessionStart hook, so the model needs an `AGENTS.md` file for routing awareness:
 
@@ -439,7 +452,7 @@ Full configs: [`configs/opencode/opencode.json`](configs/opencode/opencode.json)
    }
    ```
 
-   The `mcp` entry registers the 6 sandbox tools. The `plugin` entry enables hooks — KiloCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
+   The `mcp` entry registers all 11 MCP tools. The `plugin` entry enables hooks — KiloCode calls the plugin's TypeScript functions directly before and after each tool execution, blocking dangerous commands and enforcing sandbox routing.
 
 3. *(Optional)* Copy the routing rules file. KiloCode shares the OpenCode plugin architecture and lacks SessionStart, so the model needs an `AGENTS.md` file for routing awareness:
 
@@ -835,12 +848,12 @@ npm install -g context-mode
 
 | Tool | What it does | Context saved |
 |---|---|---|
-| `ctx_batch_execute` | Run multiple commands + search multiple queries in ONE call. | 986 KB → 62 KB |
+| `ctx_batch_execute` | Run multiple commands + search multiple queries in ONE call. Opt-in `concurrency: 1-8` for I/O-bound batches. | 986 KB → 62 KB |
 | `ctx_execute` | Run code in 11 languages. Only stdout enters context. | 56 KB → 299 B |
 | `ctx_execute_file` | Process files in sandbox. Raw content never leaves. | 45 KB → 155 B |
 | `ctx_index` | Chunk markdown into FTS5 with BM25 ranking. | 60 KB → 40 B |
 | `ctx_search` | Query indexed content with multiple queries in one call. | On-demand retrieval |
-| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. | 60 KB → 40 B |
+| `ctx_fetch_and_index` | Fetch URL, chunk and index. 24h TTL cache — repeat calls skip network. `force: true` to bypass. Pass `requests: [{url, source}, ...]` + `concurrency: 1-8` for parallel multi-URL. | 60 KB → 40 B |
 | `ctx_stats` | Show context savings, call counts, and session statistics. | — |
 | `ctx_doctor` | Diagnose installation: runtimes, hooks, FTS5, versions. | — |
 | `ctx_upgrade` | Upgrade to latest version from GitHub, rebuild, reconfigure hooks. | — |
@@ -1055,7 +1068,7 @@ Detailed event data is also indexed into FTS5 for on-demand retrieval via `ctx_s
 >
 > **Kiro** supports native `preToolUse` and `postToolUse` hooks for routing enforcement and tool event capture. `agentSpawn` (SessionStart equivalent) and `stop` are not yet wired. Requires manually copying `KIRO.md` to your project root. Kiro is auto-detected via MCP protocol handshake (`clientInfo.name`).
 >
-> **Pi Coding Agent** runs context-mode as an extension with full hook support. The extension registers `tool_call`, `tool_result`, `session_start`, and `session_before_compact` events, providing high session continuity coverage. The MCP server provides the 6 sandbox tools.
+> **Pi Coding Agent** runs context-mode as an extension with full hook support. The extension registers `tool_call`, `tool_result`, `session_start`, and `session_before_compact` events, providing high session continuity coverage. The MCP server provides all 11 MCP tools.
 
 ### Routing Enforcement
 
@@ -1207,6 +1220,25 @@ Commands chained with `&&`, `;`, or `|` are split — each part is checked separ
 
 **deny** always wins over **allow**. More specific (project-level) rules override global ones.
 
+### Network fetch hardening
+
+`ctx_fetch_and_index` blocks dangerous URL targets by default:
+
+- **Schemes**: only `http:` and `https:` allowed (no `file://`, `gopher://`, `javascript:`, `data:`).
+- **Cloud metadata + link-local**: `169.254.0.0/16` (incl. AWS/GCP/Azure IMDS endpoint `169.254.169.254`) hard-blocked even if a hostname resolves to it (DNS-rebinding defense).
+- **Multicast / reserved**: `224.0.0.0/4`, `0.0.0.0/8`, IPv6 `ff00::/8`, `fe80::/10` blocked.
+- **Loopback + RFC1918** (`localhost`, `127.x`, `10.x`, `172.16-31.x`, `192.168.x`, IPv6 `::1`, `fc00::/7`) **allowed by default** so local dev servers + internal-network fetches keep working.
+
+For hosted/CI environments where you want to block private targets too, set:
+
+```bash
+export CTX_FETCH_STRICT=1
+```
+
+That blocks loopback + RFC1918 + ULA in addition to the always-blocked ranges. Useful when context-mode runs as a shared service, not on a developer's own machine.
+
+`tool_input` for any `mcp__*` tool call is also redacted before persistence — keys matching `authorization`, `token`, `secret`, `password`, `api_key`, `cookie`, `signature`, `private_key` get masked to `[REDACTED]` so credentials in MCP arguments don't end up in the session DB.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and TDD guidelines.

package/bin/statusline.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * context-mode status line — Claude Code statusLine integration.
+ *
+ * Reads the persisted stats file written by the MCP server and prints a
+ * single-line, value-first status string designed for enterprise dev
+ * surfaces (Loom demos, Slack screen shares, over-the-shoulder closes).
+ *
+ * Discipline (Datadog / Stripe / Vercel pattern):
+ *   - "context-mode" full brand label, never abbreviated
+ *   - ONE chromatic accent (status dot ●), everything else monochrome
+ *   - Bold for KPI numbers ($, %), dim for context
+ *   - No counts (calls / tokens / events) — only $ and % pass the
+ *     value-per-pixel test
+ *
+ * Wire it up in ~/.claude/settings.json (path-free — uses the bundled CLI
+ * forwarder so users don't have to know the absolute install path):
+ *   {
+ *     "statusLine": {
+ *       "type": "command",
+ *       "command": "context-mode statusline"
+ *     }
+ *   }
+ *
+ * Or, if you prefer to skip the CLI shim, point directly at this file:
+ *     "command": "node /absolute/path/to/context-mode/bin/statusline.mjs"
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+
+// ── Schema versioning ───────────────────────────────────────────────────
+// Bumped by the MCP writer (src/server.ts) when the persisted stats payload
+// shape changes. Statusline reads `schemaVersion` from the payload:
+//   - missing  → legacy v1.0.103 era, proceed with sensible defaults
+//   - <= KNOWN → safe to render fully
+//   - >  KNOWN → newer writer than this reader; warn once + render what we
+//                still understand (graceful degrade rather than blank bar)
+const KNOWN_SCHEMA_VERSION = 1;
+
+// Test seams — keep production behaviour identical when env vars unset.
+//   CTX_TEST_PLATFORM — override process.platform for cross-OS resolver tests
+//   CTX_TEST_PROC_DIR — override /proc base dir for Linux PID-walk tests
+const TEST_PLATFORM = process.env.CTX_TEST_PLATFORM;
+const PROC_DIR = process.env.CTX_TEST_PROC_DIR || "/proc";
+function platform() {
+  return TEST_PLATFORM || process.platform;
+}
+
+// Single-shot stderr warning latch — keep noise out of Claude Code's
+// statusline output even when our parent runs us repeatedly per session.
+let __winWarned = false;
+function warnOnce(key, msg) {
+  if (key === "win" && __winWarned) return;
+  if (key === "win") __winWarned = true;
+  try { process.stderr.write(`context-mode statusline: ${msg}\n`); } catch { /* ignore */ }
+}
+
+// ── ANSI palette (single chromatic accent on the status dot) ────────────
+const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
+const ansi = (code, text) => (NO_COLOR ? text : `\x1b[${code}m${text}\x1b[0m`);
+const brand = (t) => ansi("1;36", t);   // bold cyan — brand presence
+const bold = (t) => ansi("1", t);        // bold default fg — KPI numbers
+const dim = (t) => ansi("2", t);         // dim default fg — context
+const green = (t) => ansi("32", t);      // healthy dot
+const yellow = (t) => ansi("33", t);     // degraded dot
+const red = (t) => ansi("31", t);        // stale dot
+const SEP = dim("·");
+
+// ── Stats file lookup ────────────────────────────────────────────────────
+function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function resolveSessionDir() {
+  if (process.env.CONTEXT_MODE_SESSION_DIR) {
+    return process.env.CONTEXT_MODE_SESSION_DIR;
+  }
+  return join(homedir(), ".claude", "context-mode", "sessions");
+}
+
+/**
+ * Walk up the parent process chain to find the Claude Code PID.
+ *
+ * Claude Code spawns the status line through a shell, so process.ppid is
+ * the intermediate shell, not Claude Code itself. We walk up until we find
+ * a process whose name matches /claude/i.
+ *
+ * Per-OS resolver:
+ *   - linux: read PPid + Name from /proc/<pid>/status
+ *   - darwin: ps -o ppid=,comm= -p <pid> (BSD ps; works without /proc)
+ *   - win32: degraded — process.ppid only, with a one-shot stderr warning
+ *
+ * Without this walk, multiple concurrent Claude sessions all see the same
+ * shell ppid and collide on the fuzzy mtime fallback in findStatsFile.
+ */
+function findClaudePid() {
+  const plat = platform();
+  if (plat === "linux") return findClaudePidLinux();
+  if (plat === "darwin") return findClaudePidDarwin();
+  if (plat === "win32") {
+    warnOnce(
+      "win",
+      "Windows process-tree walk unsupported; multiple concurrent Claude sessions may collide. Set CLAUDE_SESSION_ID for deterministic resolution.",
+    );
+    return process.ppid;
+  }
+  return process.ppid;
+}
+
+function findClaudePidLinux() {
+  let pid = process.ppid;
+  for (let i = 0; i < 8 && pid && pid > 1; i++) {
+    try {
+      const status = readFileSync(`${PROC_DIR}/${pid}/status`, "utf-8");
+      const nameMatch = status.match(/^Name:\s+(.+)$/m);
+      const ppidMatch = status.match(/^PPid:\s+(\d+)/m);
+      const name = nameMatch?.[1]?.trim() ?? "";
+      if (/claude/i.test(name)) return pid;
+      pid = ppidMatch ? Number(ppidMatch[1]) : 0;
+    } catch {
+      return process.ppid;
+    }
+  }
+  return process.ppid;
+}
+
+function findClaudePidDarwin() {
+  let pid = process.ppid;
+  for (let i = 0; i < 8 && pid && pid > 1; i++) {
+    try {
+      // `ps -o ppid=,comm= -p <pid>` → "  12345 /path/to/claude"
+      const out = execFileSync(
+        "ps",
+        ["-o", "ppid=,comm=", "-p", String(pid)],
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+      ).trim();
+      if (!out) return process.ppid;
+      const m = out.match(/^\s*(\d+)\s+(.+)$/);
+      if (!m) return process.ppid;
+      const parentPid = Number(m[1]);
+      const comm = m[2].trim();
+      // comm may be a path; check basename for claude
+      const base = comm.split("/").pop() || comm;
+      if (/claude/i.test(base)) return pid;
+      pid = parentPid;
+    } catch {
+      return process.ppid;
+    }
+  }
+  return process.ppid;
+}
+
+function resolveSessionId() {
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+  return `pid-${findClaudePid()}`;
+}
+
+function findStatsFile(sessionDir, sessionId) {
+  const direct = join(sessionDir, `stats-${sessionId}.json`);
+  if (existsSync(direct)) return direct;
+
+  try {
+    const candidates = readdirSync(sessionDir)
+      .filter((f) => f.startsWith("stats-") && f.endsWith(".json"))
+      .map((f) => {
+        const full = join(sessionDir, f);
+        try {
+          return { full, mtime: statSync(full).mtimeMs };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => b.mtime - a.mtime);
+
+    // Only fall back to a file modified within the last 30 minutes —
+    // older files almost always belong to a stopped MCP server.
+    const fresh = candidates.find(
+      (c) => Date.now() - c.mtime < 30 * 60 * 1000,
+    );
+    if (fresh) return fresh.full;
+  } catch { /* ignore — sessionDir might not exist yet */ }
+
+  return null;
+}
+
+function loadStats(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (parsed && typeof parsed === "object") {
+      // schemaVersion is optional — legacy v1.0.103 payloads omit it.
+      // Default to 0 so unknown-newer detection still has a clean compare.
+      const version = Number.isFinite(parsed.schemaVersion)
+        ? parsed.schemaVersion
+        : 0;
+      if (version > KNOWN_SCHEMA_VERSION) {
+        try {
+          process.stderr.write(
+            `context-mode statusline: stats schemaVersion=${version} newer than known=${KNOWN_SCHEMA_VERSION}; rendering known fields only. Upgrade context-mode to suppress this warning.\n`,
+          );
+        } catch { /* ignore */ }
+      }
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// ── Formatters ───────────────────────────────────────────────────────────
+function fmtUsd(n) {
+  const safe = Number.isFinite(n) && n >= 0 ? n : 0;
+  if (safe >= 100) return `$${safe.toFixed(0)}`;
+  if (safe >= 10) return `$${safe.toFixed(2)}`;
+  return `$${safe.toFixed(2)}`;
+}
+
+function fmtUptime(ms) {
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return remMin > 0 ? `${hr}h${remMin}m` : `${hr}h`;
+}
+
+// ── Status dot — the ONE accent ──────────────────────────────────────────
+function statusDot(pct, isStale) {
+  if (isStale) return red("●");
+  if (pct >= 50) return green("●");
+  if (pct >= 1) return yellow("●");
+  return green("●");
+}
+
+// ── Main render ──────────────────────────────────────────────────────────
+function main() {
+  readStdinJson(); // drain stdin even if unused, keeps Claude Code happy
+  const sessionDir = resolveSessionDir();
+  const sessionId = resolveSessionId();
+  const statsFile = findStatsFile(sessionDir, sessionId);
+
+  // BRAND-NEW — no stats file. Use only the substantiated README headline
+  // claim ("saves ~98% of context window"). No fabricated $/dev/month or
+  // social-proof numbers we cannot back with data.
+  if (!statsFile) {
+    process.stdout.write(
+      `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
+    );
+    return;
+  }
+
+  const stats = loadStats(statsFile);
+  if (!stats) {
+    process.stdout.write(
+      `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
+    );
+    return;
+  }
+
+  // STALE — stats file >30min old, MCP likely stopped
+  const ageMs = Date.now() - (stats.updated_at || 0);
+  const stale = ageMs > 30 * 60 * 1000;
+  if (stale) {
+    process.stdout.write(
+      `${brand("context-mode")}  ${red("●")}  ${dim("stale — restart to resume saving")}`,
+    );
+    return;
+  }
+
+  const sessionUsd = stats.dollars_saved_session ?? 0;
+  const lifetimeUsd = stats.dollars_saved_lifetime ?? 0;
+  const pct = stats.reduction_pct ?? 0;
+  const uptime = fmtUptime(stats.uptime_ms ?? 0);
+  const dot = statusDot(pct, false);
+
+  // FRESH — no session $ yet, lead with persistence value
+  if (sessionUsd === 0) {
+    if (lifetimeUsd > 0) {
+      // Lifetime $ exists — persistence as primary value, brand-poem echo
+      process.stdout.write(
+        `${brand("context-mode")}  ${dot}  ${bold(fmtUsd(lifetimeUsd))} ${dim("saved across sessions")}  ${SEP}  ${dim("preserved across compact, restart & upgrade")}`,
+      );
+    } else {
+      // First-ever session, no lifetime data yet — substantiated headline only
+      process.stdout.write(
+        `${brand("context-mode")}  ${dot}  ${dim("ready — saves ~98% of context window")}`,
+      );
+    }
+    return;
+  }
+
+  // ACTIVE / DEGRADED — session $ · [lifetime $ when present] · % efficient · uptime
+  // Status dot color encodes degraded vs healthy via pct.
+  // Lifetime block is conditional: persistStats omits dollars_saved_lifetime
+  // when no analytics aggregator is available, so we degrade gracefully to
+  // a session-only render rather than printing "$0.00 saved across sessions".
+  const valueBlocks = [
+    `${bold(fmtUsd(sessionUsd))} ${dim("saved this session")}`,
+  ];
+  if (lifetimeUsd > 0) {
+    valueBlocks.push(`${bold(fmtUsd(lifetimeUsd))} ${dim("saved across sessions")}`);
+  }
+  valueBlocks.push(`${bold(`${pct}%`)} ${dim("efficient")}`);
+  valueBlocks.push(dim(uptime));
+
+  const head = `${brand("context-mode")}  ${dot}  `;
+  const tail = valueBlocks.join(`  ${SEP}  `);
+  process.stdout.write(head + tail);
+}
+
+main();

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

@@ -32,6 +32,12 @@ export declare class AntigravityAdapter extends BaseAdapter implements HookAdapt
     formatPreCompactResponse(_response: PreCompactResponse): unknown;
     formatSessionStartResponse(_response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    /**
+     * Antigravity nests under ~/.gemini/antigravity/. Always absolute.
+     * `_projectDir` accepted for interface symmetry but unused — home-rooted.
+     */
+    getConfigDir(_projectDir?: string): string;
+    getInstructionFiles(): string[];
     generateHookConfig(_pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(settings: Record<string, unknown>): void;

package/build/adapters/antigravity/index.js

@@ -72,6 +72,16 @@ export class AntigravityAdapter extends BaseAdapter {
     getSettingsPath() {
         return resolve(homedir(), ".gemini", "antigravity", "mcp_config.json");
     }
+    /**
+     * Antigravity nests under ~/.gemini/antigravity/. Always absolute.
+     * `_projectDir` accepted for interface symmetry but unused — home-rooted.
+     */
+    getConfigDir(_projectDir) {
+        return resolve(homedir(), ".gemini", "antigravity");
+    }
+    getInstructionFiles() {
+        return ["GEMINI.md"];
+    }
     generateHookConfig(_pluginRoot) {
         return {};
     }

package/build/adapters/base.d.ts

@@ -22,6 +22,29 @@ export declare abstract class BaseAdapter {
     getSessionDir(): string;
     getSessionDBPath(projectDir: string): string;
     getSessionEventsPath(projectDir: string): string;
+    /**
+     * Default: build config dir from sessionDirSegments rooted at $HOME.
+     *
+     * Contract: ALWAYS returns an absolute path. Adapters with project-scoped
+     * or non-home-rooted config dirs (cursor, vscode-copilot, jetbrains-copilot,
+     * openclaw, opencode) override this and resolve their segments against
+     * `projectDir` (or `process.cwd()` when omitted).
+     *
+     * @param _projectDir Unused by the home-rooted default — accepted so
+     *                    project-scoped overrides honor the same signature.
+     */
+    getConfigDir(_projectDir?: string): string;
+    /**
+     * Default: Claude Code convention. Most adapters override with their
+     * own platform-specific instruction file name (AGENTS.md, GEMINI.md, ...).
+     */
+    getInstructionFiles(): string[];
+    /**
+     * Default: <configDir>/memory. Always absolute (configDir is absolute by
+     * contract). Adapters with a different memory dir name (e.g., codex uses
+     * "memories" plural) override this.
+     */
+    getMemoryDir(): string;
     backupSettings(): string | null;
     abstract getSettingsPath(): string;
 }

package/build/adapters/base.js

@@ -44,6 +44,35 @@ export class BaseAdapter {
             .slice(0, 16);
         return join(this.getSessionDir(), `${hash}-events.md`);
     }
+    /**
+     * Default: build config dir from sessionDirSegments rooted at $HOME.
+     *
+     * Contract: ALWAYS returns an absolute path. Adapters with project-scoped
+     * or non-home-rooted config dirs (cursor, vscode-copilot, jetbrains-copilot,
+     * openclaw, opencode) override this and resolve their segments against
+     * `projectDir` (or `process.cwd()` when omitted).
+     *
+     * @param _projectDir Unused by the home-rooted default — accepted so
+     *                    project-scoped overrides honor the same signature.
+     */
+    getConfigDir(_projectDir) {
+        return join(homedir(), ...this.sessionDirSegments);
+    }
+    /**
+     * Default: Claude Code convention. Most adapters override with their
+     * own platform-specific instruction file name (AGENTS.md, GEMINI.md, ...).
+     */
+    getInstructionFiles() {
+        return ["CLAUDE.md"];
+    }
+    /**
+     * Default: <configDir>/memory. Always absolute (configDir is absolute by
+     * contract). Adapters with a different memory dir name (e.g., codex uses
+     * "memories" plural) override this.
+     */
+    getMemoryDir() {
+        return join(this.getConfigDir(), "memory");
+    }
     backupSettings() {
         const settingsPath = this.getSettingsPath();
         try {

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

@@ -29,6 +29,8 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
     formatPreCompactResponse(response: PreCompactResponse): unknown;
     formatSessionStartResponse(response: SessionStartResponse): unknown;
     getSettingsPath(): string;
+    getInstructionFiles(): string[];
+    getMemoryDir(): string;
     generateHookConfig(pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;
     writeSettings(_settings: Record<string, unknown>): void;
@@ -39,6 +41,14 @@ export declare class CodexAdapter extends BaseAdapter implements HookAdapter {
     setHookPermissions(_pluginRoot: string): string[];
     updatePluginRegistry(_pluginRoot: string, _version: string): void;
     getRoutingInstructions(): string;
+    /**
+     * Resolve the project directory for a Codex hook input.
+     * Priority: input.cwd > CODEX_PROJECT_DIR env > process.cwd().
+     * Mirrors the cursor / opencode pattern so downstream hooks always
+     * receive a defined projectDir even under worktrees or when the
+     * platform omits cwd from the wire payload.
+     */
+    private getProjectDir;
     /**
      * Extract session ID from Codex CLI hook input.
      * Priority: session_id field > fallback to ppid.

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.