context-mode 1.0.110 → 1.0.112

package/bin/statusline.mjs

@@ -2,9 +2,12 @@
 /**
  * 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).
+ * Reads stats DIRECTLY from SessionDB (`session_events` + `session_resume`),
+ * mirroring the `ctx_stats` MCP handler at src/server.ts:2807-2891 so the
+ * statusline and ctx_stats never drift. The legacy per-PID sidecar JSON
+ * (`stats-pid-*.json`) is no longer the source of truth — sidecars were
+ * eventually-consistent (500ms+30s throttles) and PID-scoped (multiple
+ * Claude sessions colliding on the same shell ppid).
  *
  * Discipline (Datadog / Stripe / Vercel pattern):
  *   - "context-mode" full brand label, never abbreviated
@@ -13,32 +16,46 @@
  *   - 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):
+ * Wire it up in ~/.claude/settings.json:
  *   {
  *     "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 { existsSync, readFileSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 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;
+// ── Analytics import — resolved relative to this script ─────────────────
+// statusline.mjs ships in `bin/`; the compiled analytics module lives in
+// `build/session/analytics.js`. Import lazily so a missing build doesn't
+// crash the renderer — degrade to the substantiated headline instead.
+//
+// The dynamic import target MUST be a `file://` URL on Windows. Node's
+// ESM loader rejects absolute drive-letter paths (`C:\...`) with
+// ERR_UNSUPPORTED_ESM_URL_SCHEME — which the catch below silently
+// swallows, leaving `_analytics = null` and rendering the empty-state
+// headline forever. Convert to a file URL so Windows accepts it.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ANALYTICS_PATH = resolve(__dirname, "..", "build", "session", "analytics.js");
+const ANALYTICS_URL = pathToFileURL(ANALYTICS_PATH).href;
+
+let _analytics = null;
+async function loadAnalytics() {
+  if (_analytics) return _analytics;
+  try {
+    _analytics = await import(ANALYTICS_URL);
+  } catch {
+    _analytics = null;
+  }
+  return _analytics;
+}
 
 // Test seams — keep production behaviour identical when env vars unset.
 //   CTX_TEST_PLATFORM — override process.platform for cross-OS resolver tests
@@ -69,7 +86,7 @@ const yellow = (t) => ansi("33", t);     // degraded dot
 const red = (t) => ansi("31", t);        // stale dot
 const SEP = dim("·");
 
-// ── Stats file lookup ────────────────────────────────────────────────────
+// ── Stdin drain ─────────────────────────────────────────────────────────
 function readStdinJson() {
   try {
     const raw = readFileSync(0, "utf-8");
@@ -100,7 +117,7 @@ function resolveSessionDir() {
  *   - 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.
+ * shell ppid and collide on per-PID stats lookup.
  */
 function findClaudePid() {
   const plat = platform();
@@ -137,7 +154,6 @@ 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)],
@@ -148,7 +164,6 @@ function findClaudePidDarwin() {
       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;
@@ -164,158 +179,160 @@ function resolveSessionId() {
   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("●");
+function statusDot(pct) {
   if (pct >= 50) return green("●");
   if (pct >= 1) return yellow("●");
   return green("●");
 }
 
 // ── Main render ──────────────────────────────────────────────────────────
-function main() {
+async function main() {
   readStdinJson(); // drain stdin even if unused, keeps Claude Code happy
-  const sessionDir = resolveSessionDir();
+  const sessionsDir = 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) {
+  const analytics = await loadAnalytics();
+
+  // BRAND-NEW / build missing — substantiated headline only
+  if (!analytics) {
     process.stdout.write(
       `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
     );
     return;
   }
 
-  const stats = loadStats(statsFile);
-  if (!stats) {
+  const {
+    getRealBytesStats,
+    getMultiAdapterLifetimeStats,
+    OPUS_INPUT_PRICE_PER_TOKEN,
+  } = analytics;
+
+  // Sessions dir doesn't exist yet — first ever launch
+  if (!existsSync(sessionsDir)) {
     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) {
+  // Lifetime real-bytes across this adapter's sessions dir.
+  // Mirrors src/server.ts:2860 — the same call ctx_stats uses.
+  let lifetime;
+  try {
+    lifetime = getRealBytesStats({ sessionsDir });
+  } catch {
+    lifetime = null;
+  }
+
+  // Per-conversation real-bytes for the session $ KPI.
+  // Statusline doesn't know the worktree hash, so scan every db in the
+  // dir and let getRealBytesStats filter by sessionId.
+  let conversation;
+  try {
+    conversation = getRealBytesStats({ sessionsDir, sessionId });
+  } catch {
+    conversation = null;
+  }
+
+  // Cross-adapter lifetime — drives the "across N tools" headline when
+  // 2+ real adapters are present. Mirrors src/server.ts:2840.
+  let multi;
+  try {
+    multi = getMultiAdapterLifetimeStats();
+  } catch {
+    multi = null;
+  }
+
+  const PRICE = OPUS_INPUT_PRICE_PER_TOKEN ?? (15 / 1_000_000);
+  const lifetimeTokens = lifetime?.totalSavedTokens ?? 0;
+  const sessionTokens = conversation?.totalSavedTokens ?? 0;
+  const lifetimeUsd = lifetimeTokens * PRICE;
+  const sessionUsd = sessionTokens * PRICE;
+
+  // Reduction % — bytes avoided + snapshot bytes vs returned bytes.
+  // Mirrors persistStats() math in src/server.ts:565-568.
+  const totalReturned = lifetime?.bytesReturned ?? 0;
+  const totalKept =
+    (lifetime?.bytesAvoided ?? 0)
+    + (lifetime?.snapshotBytes ?? 0)
+    + (lifetime?.eventDataBytes ?? 0);
+  const totalProcessed = totalKept + totalReturned;
+  const pct = totalProcessed > 0
+    ? Math.round((totalKept / totalProcessed) * 100)
+    : 0;
+
+  const dot = statusDot(pct);
+
+  // Multi-adapter aggregation. Real adapters = those passing the isReal
+  // filter (>=100 events, >=5 distinct projects, recent activity, avg
+  // bytes >= 50). When 2+ real adapters exist, surface a cross-tool $.
+  // multi.totalBytes is dataBytes + rescueBytes, NOT bytes-avoided — so
+  // it's a different (and typically smaller) lens than getRealBytesStats.
+  // Render the multi $ alongside lifetime $ rather than instead of it.
+  const realAdapters = (multi?.perAdapter ?? []).filter((a) => a?.isReal);
+  const multiTotalTokens = (multi?.totalBytes ?? 0) / 4;
+  const multiUsd = multiTotalTokens * PRICE;
+  const showMultiAdapter = realAdapters.length >= 2 && multiUsd > 0;
+
+  // BRAND-NEW: no local SessionDB data at all → headline.
+  // Multi-adapter alone (without local data) means another tool has
+  // history but THIS Claude session is fresh — still show headline,
+  // not someone else's lifetime $, to avoid surprising users with a
+  // number they can't trace to their current adapter.
+  if (lifetimeTokens === 0 && sessionTokens === 0) {
     process.stdout.write(
-      `${brand("context-mode")}  ${red("●")}  ${dim("stale — restart to resume saving")}`,
+      `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
     );
     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")}`,
-      );
+  // FRESH session, no session $ yet — lead with persistence value.
+  if (sessionUsd === 0 && lifetimeUsd > 0) {
+    const blocks = [
+      `${bold(fmtUsd(lifetimeUsd))} ${dim("saved across sessions")}`,
+    ];
+    if (showMultiAdapter) {
+      blocks.push(`${bold(fmtUsd(multiUsd))} ${dim(`across ${realAdapters.length} tools`)}`);
     }
+    blocks.push(dim("preserved across compact, restart & upgrade"));
+    process.stdout.write(
+      `${brand("context-mode")}  ${dot}  ${blocks.join(`  ${SEP}  `)}`,
+    );
     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".
+  // ACTIVE: session $ · lifetime $ · [multi $] · % efficient
   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));
+  if (showMultiAdapter) {
+    valueBlocks.push(`${bold(fmtUsd(multiUsd))} ${dim(`across ${realAdapters.length} tools`)}`);
+  }
+  if (pct > 0) {
+    valueBlocks.push(`${bold(`${pct}%`)} ${dim("efficient")}`);
+  }
 
   const head = `${brand("context-mode")}  ${dot}  `;
   const tail = valueBlocks.join(`  ${SEP}  `);
   process.stdout.write(head + tail);
 }
 
-main();
+main().catch(() => {
+  // Last-resort fallback — a thrown error must never produce a blank statusline.
+  try {
+    process.stdout.write(
+      `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
+    );
+  } catch { /* ignore */ }
+});

package/build/adapters/base.d.ts

@@ -1,13 +1,10 @@
 /**
  * BaseAdapter — shared implementation for methods identical across all adapters.
  *
- * Eliminates ~288 lines of duplication across 12 adapters.
  * Each concrete adapter extends this and provides platform-specific logic.
  *
  * Shared methods:
  *   - getSessionDir()       — builds session dir from sessionDirSegments
- *   - getSessionDBPath()    — SHA-256 hash of projectDir → .db file
- *   - getSessionEventsPath()— SHA-256 hash of projectDir → -events.md file
  *   - backupSettings()      — copies settings file to .bak
  *
  * Adapters with custom logic override the relevant method:
@@ -15,13 +12,19 @@
  *   - opencode: overrides getSessionDir (XDG_CONFIG_HOME / APPDATA)
  *              and backupSettings (calls checkPluginRegistration first)
  *   - openclaw: overrides backupSettings (searches 3 config paths)
+ *
+ * NOTE — C2 narrowing (2026-05): `getSessionDBPath` and `getSessionEventsPath`
+ * were removed. Both were SHALLOW pure derivatives of `getSessionDir() +
+ * projectDir` (interface complexity == implementation complexity). All
+ * adapter-storage path computation now flows through ONE site:
+ * `resolveSessionDbPath({ projectDir, sessionsDir: adapter.getSessionDir() })`
+ * in `src/session/db.ts`. Adapters expose only `getSessionDir()` for
+ * storage-related path concerns.
  */
 export declare abstract class BaseAdapter {
     protected readonly sessionDirSegments: string[];
     constructor(sessionDirSegments: string[]);
     getSessionDir(): string;
-    getSessionDBPath(projectDir: string): string;
-    getSessionEventsPath(projectDir: string): string;
     /**
      * Default: build config dir from sessionDirSegments rooted at $HOME.
      *

package/build/adapters/base.js

@@ -1,13 +1,10 @@
 /**
  * BaseAdapter — shared implementation for methods identical across all adapters.
  *
- * Eliminates ~288 lines of duplication across 12 adapters.
  * Each concrete adapter extends this and provides platform-specific logic.
  *
  * Shared methods:
  *   - getSessionDir()       — builds session dir from sessionDirSegments
- *   - getSessionDBPath()    — SHA-256 hash of projectDir → .db file
- *   - getSessionEventsPath()— SHA-256 hash of projectDir → -events.md file
  *   - backupSettings()      — copies settings file to .bak
  *
  * Adapters with custom logic override the relevant method:
@@ -15,8 +12,15 @@
  *   - opencode: overrides getSessionDir (XDG_CONFIG_HOME / APPDATA)
  *              and backupSettings (calls checkPluginRegistration first)
  *   - openclaw: overrides backupSettings (searches 3 config paths)
+ *
+ * NOTE — C2 narrowing (2026-05): `getSessionDBPath` and `getSessionEventsPath`
+ * were removed. Both were SHALLOW pure derivatives of `getSessionDir() +
+ * projectDir` (interface complexity == implementation complexity). All
+ * adapter-storage path computation now flows through ONE site:
+ * `resolveSessionDbPath({ projectDir, sessionsDir: adapter.getSessionDir() })`
+ * in `src/session/db.ts`. Adapters expose only `getSessionDir()` for
+ * storage-related path concerns.
  */
-import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { accessSync, copyFileSync, constants, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -30,20 +34,6 @@ export class BaseAdapter {
         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`);
-    }
     /**
      * Default: build config dir from sessionDirSegments rooted at $HOME.
      *

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

@@ -6,9 +6,10 @@
  *
  * Claude Code hook specifics:
  *   - Session ID: transcript_path UUID > session_id > CLAUDE_SESSION_ID > ppid
- *   - Config: ~/.claude/settings.json
- *   - Session dir: ~/.claude/context-mode/sessions/
- *   - Plugin registry: ~/.claude/plugins/installed_plugins.json
+ *   - Config root: $CLAUDE_CONFIG_DIR (when set) or ~/.claude
+ *   - Settings: <configDir>/settings.json
+ *   - Session dir: <configDir>/context-mode/sessions/
+ *   - Plugin registry: <configDir>/plugins/installed_plugins.json
  */
 import { ClaudeCodeBaseAdapter, type ClaudeCodeWireInput } from "../claude-code-base.js";
 import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, HookRegistration } from "../types.js";
@@ -18,6 +19,26 @@ export declare class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter implements
     readonly paradigm: HookParadigm;
     protected readonly projectDirEnvVar = "CLAUDE_PROJECT_DIR";
     readonly capabilities: PlatformCapabilities;
+    /**
+     * Honor `CLAUDE_CONFIG_DIR` (the canonical Claude Code config root) before
+     * falling back to `~/.claude`. Mirrors the contract that
+     * `hooks/session-helpers.mjs::resolveConfigDir` already follows — including
+     * tilde expansion for shells that pass `~/foo` through unchanged — so server
+     * and hooks agree on where session-scoped state lives. See issue #453.
+     *
+     * Tilde regex `/^~[/\\]?/` only handles the current-user form (`~`, `~/`,
+     * `~\`); `~user/` is NOT expanded to a per-user homedir (matches
+     * `resolveConfigDir`). Non-tilde values are run through `resolve()` to
+     * normalize relative paths to absolute against cwd; the hook helper
+     * intentionally leaves them raw, but the adapter contract guarantees an
+     * absolute path (BaseAdapter.getConfigDir docstring).
+     *
+     * Issue #460 round-3: routed through the canonical
+     * `resolveClaudeConfigDir` util so server, CLI, security, and adapter
+     * agree byte-for-byte (incl. empty/whitespace-only env fallback).
+     */
+    getConfigDir(_projectDir?: string): string;
+    getSessionDir(): string;
     getSettingsPath(): string;
     generateHookConfig(pluginRoot: string): HookRegistration;
     readSettings(): Record<string, unknown> | null;

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

@@ -6,14 +6,16 @@
  *
  * Claude Code hook specifics:
  *   - Session ID: transcript_path UUID > session_id > CLAUDE_SESSION_ID > ppid
- *   - Config: ~/.claude/settings.json
- *   - Session dir: ~/.claude/context-mode/sessions/
- *   - Plugin registry: ~/.claude/plugins/installed_plugins.json
+ *   - Config root: $CLAUDE_CONFIG_DIR (when set) or ~/.claude
+ *   - Settings: <configDir>/settings.json
+ *   - Session dir: <configDir>/context-mode/sessions/
+ *   - Plugin registry: <configDir>/plugins/installed_plugins.json
  */
-import { readFileSync, writeFileSync, existsSync, readdirSync, chmodSync, accessSync, constants, } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, readdirSync, chmodSync, accessSync, mkdirSync, constants, } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { ClaudeCodeBaseAdapter } from "../claude-code-base.js";
+import { resolveClaudeConfigDir } from "../../util/claude-config.js";
 import { HOOK_TYPES, HOOK_SCRIPTS, REQUIRED_HOOKS, PRE_TOOL_USE_MATCHER_PATTERN, isContextModeHook, isAnyContextModeHook, extractHookScriptPath, buildHookCommand, } from "./hooks.js";
 // ─────────────────────────────────────────────────────────
 // Adapter implementation
@@ -35,8 +37,34 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
         canInjectSessionContext: true,
     };
     // ── Configuration ──────────────────────────────────────
+    /**
+     * Honor `CLAUDE_CONFIG_DIR` (the canonical Claude Code config root) before
+     * falling back to `~/.claude`. Mirrors the contract that
+     * `hooks/session-helpers.mjs::resolveConfigDir` already follows — including
+     * tilde expansion for shells that pass `~/foo` through unchanged — so server
+     * and hooks agree on where session-scoped state lives. See issue #453.
+     *
+     * Tilde regex `/^~[/\\]?/` only handles the current-user form (`~`, `~/`,
+     * `~\`); `~user/` is NOT expanded to a per-user homedir (matches
+     * `resolveConfigDir`). Non-tilde values are run through `resolve()` to
+     * normalize relative paths to absolute against cwd; the hook helper
+     * intentionally leaves them raw, but the adapter contract guarantees an
+     * absolute path (BaseAdapter.getConfigDir docstring).
+     *
+     * Issue #460 round-3: routed through the canonical
+     * `resolveClaudeConfigDir` util so server, CLI, security, and adapter
+     * agree byte-for-byte (incl. empty/whitespace-only env fallback).
+     */
+    getConfigDir(_projectDir) {
+        return resolveClaudeConfigDir();
+    }
+    getSessionDir() {
+        const dir = join(this.getConfigDir(), "context-mode", "sessions");
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
     getSettingsPath() {
-        return resolve(homedir(), ".claude", "settings.json");
+        return join(this.getConfigDir(), "settings.json");
     }
     generateHookConfig(pluginRoot) {
         const preToolUseCommand = `node ${pluginRoot}/hooks/pretooluse.mjs`;
@@ -121,7 +149,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
             results.push({
                 check: "PreToolUse hook",
                 status: "fail",
-                message: "Could not read ~/.claude/settings.json",
+                message: `Could not read ${this.getSettingsPath()}`,
                 fix: "context-mode upgrade",
             });
             return results;
@@ -221,7 +249,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
     getInstalledVersion() {
         // Primary: read from installed_plugins.json
         try {
-            const ipPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+            const ipPath = join(this.getConfigDir(), "plugins", "installed_plugins.json");
             const ipRaw = JSON.parse(readFileSync(ipPath, "utf-8"));
             const plugins = ipRaw.plugins ?? {};
             for (const [key, entries] of Object.entries(plugins)) {
@@ -236,11 +264,16 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
         catch {
             /* fallback below */
         }
-        // Fallback: scan common plugin cache locations
-        const bases = [
+        // Fallback: scan common plugin cache locations.
+        // `resolveClaudeConfigDir` honors $CLAUDE_CONFIG_DIR; the literal
+        // `~/.claude` is also retained as a hard floor so environments that
+        // misconfigure the env still find the canonical dir if it exists.
+        const bases = Array.from(new Set([
+            this.getConfigDir(),
+            resolveClaudeConfigDir(),
             resolve(homedir(), ".claude"),
             resolve(homedir(), ".config", "claude"),
-        ];
+        ]));
         for (const base of bases) {
             const cacheDir = resolve(base, "plugins", "cache", "context-mode", "context-mode");
             try {
@@ -421,7 +454,7 @@ export class ClaudeCodeAdapter extends ClaudeCodeBaseAdapter {
     }
     updatePluginRegistry(pluginRoot, version) {
         try {
-            const ipPath = resolve(homedir(), ".claude", "plugins", "installed_plugins.json");
+            const ipPath = join(this.getConfigDir(), "plugins", "installed_plugins.json");
             const ipRaw = JSON.parse(readFileSync(ipPath, "utf-8"));
             for (const [key, entries] of Object.entries(ipRaw.plugins || {})) {
                 if (!key.toLowerCase().includes("context-mode"))

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

@@ -1,22 +1,27 @@
 /**
  * adapters/codex/hooks — Codex CLI hook definitions.
  *
- * Codex CLI hooks are stable (codex_hooks Stage::Stable, default_enabled: true).
- * 5 hook events: PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop.
+ * Codex CLI hooks run behind the current `hooks` feature flag surface.
+ * Prefer `[features].hooks`; the legacy `[features].codex_hooks` alias is still
+ * accepted in current Codex builds.
+ * 6 hook events: PreToolUse, PostToolUse, PreCompact, SessionStart,
+ * UserPromptSubmit, Stop. PreCompact is runtime-gated on Codex builds that emit
+ * the event.
  * Same JSON stdin/stdout wire protocol as Claude Code.
  *
- * Config: ~/.codex/hooks.json (JSON format, same schema as Claude Code)
- * MCP: full support via [mcp_servers] in ~/.codex/config.toml
+ * Config: $CODEX_HOME/hooks.json or ~/.codex/hooks.json.
+ * MCP: full support via [mcp_servers] in $CODEX_HOME/config.toml.
  *
  * Known limitations:
  *   - PreToolUse: deny works, updatedInput not yet supported (openai/codex#18491)
  *   - PostToolUse: updatedMCPToolOutput parsed but logged as unsupported
  *   - PostToolUse does not fire on failing Bash calls (upstream bug)
  */
-/** Codex CLI hook types — mirrors Claude Code's 5-event model. */
+/** Codex CLI hook types — mirrors Claude Code's continuity events. */
 export declare const HOOK_TYPES: {
     readonly PRE_TOOL_USE: "PreToolUse";
     readonly POST_TOOL_USE: "PostToolUse";
+    readonly PRE_COMPACT: "PreCompact";
     readonly SESSION_START: "SessionStart";
     readonly USER_PROMPT_SUBMIT: "UserPromptSubmit";
     readonly STOP: "Stop";