@mxalbert/context-mode 2.0.0

package/bin/statusline.mjs

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+/**
+ * context-mode status line — Claude Code statusLine integration.
+ *
+ * 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
+ *   - 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:
+ *   {
+ *     "statusLine": {
+ *       "type": "command",
+ *       "command": "context-mode statusline"
+ *     }
+ *   }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
+import {
+  ensureWritableStorageDir,
+  resolveDefaultSessionDir,
+  resolveSessionStorageDir,
+} from "../hooks/session-db.bundle.mjs";
+
+// ── 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
+//   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.
+const __warnedKeys = new Set();
+function warnOnce(key, msg) {
+  if (__warnedKeys.has(key)) return;
+  __warnedKeys.add(key);
+  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("·");
+
+// ── Stdin drain ─────────────────────────────────────────────────────────
+function readStdinJson() {
+  try {
+    const raw = readFileSync(0, "utf-8");
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch (err) {
+    // The payload is load-bearing — it carries session_id, which resolves the
+    // per-session KPI. Empty stdin (normal first render) returned above and
+    // stays silent; a non-empty payload that fails to parse is a real anomaly
+    // worth one latched stderr line (never pollutes the statusline's stdout).
+    warnOnce("stdin-parse", `failed to parse statusline stdin JSON: ${err?.message ?? err}`);
+    return {};
+  }
+}
+
+function resolveSessionDir() {
+  return ensureWritableStorageDir(
+    resolveSessionStorageDir(() => resolveDefaultSessionDir({
+      configDir: ".claude",
+      configDirEnv: "CLAUDE_CONFIG_DIR",
+      legacySessionDirEnv: "CONTEXT_MODE_SESSION_DIR",
+      onLegacySessionDir: () => {
+        warnOnce(
+          "legacy-session-dir",
+          "CONTEXT_MODE_SESSION_DIR is deprecated; set CONTEXT_MODE_DIR to the parent context-mode root.",
+        );
+      },
+    })),
+  );
+}
+
+/**
+ * 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 per-PID stats lookup.
+ */
+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 {
+      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();
+      const base = comm.split("/").pop() || comm;
+      if (/claude/i.test(base)) return pid;
+      pid = parentPid;
+    } catch {
+      return process.ppid;
+    }
+  }
+  return process.ppid;
+}
+
+function resolveSessionId(payload) {
+  // PRIMARY: the session_id Claude Code delivers in the statusLine stdin
+  // payload. This is the SAME id the recording hooks key session_events by,
+  // so it's the only source that reliably matches stored per-session data.
+  //
+  // Claude Code does NOT export a CLAUDE_SESSION_ID env var — session_id is
+  // delivered only in the stdin JSON (statusline.md "Available data"). And the
+  // /proc PID walk yields `pid-<n>`, which never matches a UUID-keyed session.
+  // So without reading the payload, the per-session KPI is unreachable and the
+  // bar falls back to the global lifetime aggregate — identical in every
+  // session and seemingly "frozen".
+  const fromPayload = payload?.session_id;
+  if (typeof fromPayload === "string" && fromPayload) return fromPayload;
+  // Fallback when the payload carries no session_id (and how test fixtures
+  // pin a deterministic id). NOT an override — payload wins when present.
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+  // Last resort: walk the process tree (only matches pid-keyed events).
+  return `pid-${findClaudePid()}`;
+}
+
+// ── Formatters ───────────────────────────────────────────────────────────
+function fmtUsd(n) {
+  const safe = Number.isFinite(n) && n >= 0 ? n : 0;
+  if (safe >= 100) return `$${safe.toFixed(0)}`;
+  return `$${safe.toFixed(2)}`;
+}
+
+// ── Status dot — the ONE accent ──────────────────────────────────────────
+function statusDot(pct) {
+  if (pct >= 50) return green("●");
+  if (pct >= 1) return yellow("●");
+  return green("●");
+}
+
+// ── Main render ──────────────────────────────────────────────────────────
+async function main() {
+  const payload = readStdinJson(); // canonical source of session_id
+  const sessionsDir = resolveSessionDir();
+  const sessionId = resolveSessionId(payload);
+
+  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 {
+    getRealBytesStats,
+    getMultiAdapterLifetimeStats,
+    kb,
+  } = 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;
+  }
+
+  // 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;
+  }
+
+  // v1.0.118: drop the $ math — ctx_stats's narrative renderer is the source
+  // of truth and uses byte-based metrics. Statusline mirrors the same
+  // formulas so the two displays never diverge again.
+  //
+  // Lifetime bytes — multi-adapter aggregate when present, else local-DB
+  // real bytes. Mirrors src/session/analytics.ts:1684 narrative renderer.
+  const lifetimeBytes = (multi?.totalBytes && multi.totalBytes > 0)
+    ? multi.totalBytes
+    : (lifetime?.totalSavedTokens ?? 0) * 4;
+
+  // This-chat bytes — real bytes accounting (data + bytes-avoided + snapshot).
+  const sessionBytes = conversation
+    ? ((conversation.eventDataBytes ?? 0)
+       + (conversation.bytesAvoided ?? 0)
+       + (conversation.snapshotBytes ?? 0))
+    : 0;
+
+  // Per-day average — same lifetime-day computation ctx_stats opener uses.
+  const sinceMs = lifetime?.firstEventMs ?? multi?.perAdapter?.[0]?.firstMs ?? 0;
+  const lifetimeDays = sinceMs > 0
+    ? Math.max(1, Math.round((Date.now() - sinceMs) / 86_400_000))
+    : 0;
+  const perDayBytes = lifetimeDays > 0 ? lifetimeBytes / lifetimeDays : 0;
+
+  // Reduction % — same as before (bytes-avoided + snapshot vs returned).
+  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);
+
+  // Cross-tool count — used in the headline when 2+ real adapters detected.
+  const realAdapters = (multi?.perAdapter ?? []).filter((a) => a?.isReal);
+  const showMultiAdapter = realAdapters.length >= 2;
+
+  // BRAND-NEW: no data at all → marketing headline.
+  if (lifetimeBytes === 0 && sessionBytes === 0) {
+    process.stdout.write(
+      `${brand("context-mode")}  ${green("●")}  ${dim("saves ~98% of context window")}`,
+    );
+    return;
+  }
+
+  // FRESH session, no this-chat data yet — lead with lifetime number.
+  if (sessionBytes === 0 && lifetimeBytes > 0) {
+    const blocks = [`${bold(kb(lifetimeBytes))} ${dim("kept out")}`];
+    if (perDayBytes > 0) {
+      blocks.push(`${bold(kb(perDayBytes) + "/day")}`);
+    }
+    if (showMultiAdapter) {
+      blocks.push(`${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: this-chat · lifetime · [N tools] · % efficient
+  const valueBlocks = [
+    `${bold(kb(sessionBytes))} ${dim("this chat")}`,
+  ];
+  if (lifetimeBytes > 0) {
+    valueBlocks.push(`${bold(kb(lifetimeBytes))} ${dim("lifetime")}`);
+  }
+  if (showMultiAdapter) {
+    valueBlocks.push(`${dim(`across ${realAdapters.length} tools`)}`);
+  }
+  if (pct > 0) {
+    valueBlocks.push(`${bold(`${pct}%`)} ${dim("kept out")}`);
+  }
+
+  const head = `${brand("context-mode")}  ${dot}  `;
+  const tail = valueBlocks.join(`  ${SEP}  `);
+  process.stdout.write(head + tail);
+}
+
+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/antigravity/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * adapters/antigravity — Google Antigravity platform adapter.
+ *
+ * Implements HookAdapter for Antigravity's MCP-only paradigm.
+ *
+ * Antigravity hook specifics:
+ *   - NO hook support (MCP-only, same as Codex CLI)
+ *   - Config: ~/.gemini/antigravity/mcp_config.json (JSON format)
+ *   - MCP: full support via mcpServers in mcp_config.json
+ *   - All capabilities are false — MCP is the only integration path
+ *   - Session dir: ~/.gemini/context-mode/sessions/
+ *   - Routing file: GEMINI.md (shared with Gemini CLI filename, different content)
+ *
+ * Sources:
+ *   - Config path: https://github.com/google-gemini/gemini-cli/issues/16058
+ *   - MCP support: https://antigravity.google/docs/mcp
+ *   - Tool list: System prompt leak (21 verified tools)
+ */
+import { BaseAdapter } from "../base.js";
+import type { HookAdapter, HookParadigm, PlatformCapabilities, DiagnosticResult, PreToolUseEvent, PostToolUseEvent, PreCompactEvent, SessionStartEvent, PreToolUseResponse, PostToolUseResponse, PreCompactResponse, SessionStartResponse, HookRegistration } from "../types.js";
+export declare class AntigravityAdapter extends BaseAdapter implements HookAdapter {
+    constructor();
+    readonly name: string;
+    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;
+    /**
+     * 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;
+    validateHooks(_pluginRoot: string): DiagnosticResult[];
+    checkPluginRegistration(): DiagnosticResult;
+    getInstalledVersion(): string;
+    configureAllHooks(_pluginRoot: string): string[];
+    setHookPermissions(_pluginRoot: string): string[];
+    updatePluginRegistry(_pluginRoot: string, _version: string): void;
+    getRoutingInstructions(): string;
+}

package/build/adapters/antigravity/index.js

@@ -0,0 +1,169 @@
+/**
+ * adapters/antigravity — Google Antigravity platform adapter.
+ *
+ * Implements HookAdapter for Antigravity's MCP-only paradigm.
+ *
+ * Antigravity hook specifics:
+ *   - NO hook support (MCP-only, same as Codex CLI)
+ *   - Config: ~/.gemini/antigravity/mcp_config.json (JSON format)
+ *   - MCP: full support via mcpServers in mcp_config.json
+ *   - All capabilities are false — MCP is the only integration path
+ *   - Session dir: ~/.gemini/context-mode/sessions/
+ *   - Routing file: GEMINI.md (shared with Gemini CLI filename, different content)
+ *
+ * Sources:
+ *   - Config path: https://github.com/google-gemini/gemini-cli/issues/16058
+ *   - MCP support: https://antigravity.google/docs/mcp
+ *   - Tool list: System prompt leak (21 verified tools)
+ */
+import { readFileSync, writeFileSync, mkdirSync, } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { BaseAdapter } from "../base.js";
+// ─────────────────────────────────────────────────────────
+// Adapter implementation
+// ─────────────────────────────────────────────────────────
+export class AntigravityAdapter extends BaseAdapter {
+    constructor() {
+        super([".gemini"]);
+    }
+    name = "Antigravity";
+    paradigm = "mcp-only";
+    capabilities = {
+        preToolUse: false,
+        postToolUse: false,
+        preCompact: false,
+        sessionStart: false,
+        canModifyArgs: false,
+        canModifyOutput: false,
+        canInjectSessionContext: false,
+    };
+    // ── Input parsing ──────────────────────────────────────
+    // Antigravity does not support hooks. These methods exist to satisfy the
+    // interface contract but will throw if called.
+    parsePreToolUseInput(_raw) {
+        throw new Error("Antigravity does not support hooks");
+    }
+    parsePostToolUseInput(_raw) {
+        throw new Error("Antigravity does not support hooks");
+    }
+    parsePreCompactInput(_raw) {
+        throw new Error("Antigravity does not support hooks");
+    }
+    parseSessionStartInput(_raw) {
+        throw new Error("Antigravity does not support hooks");
+    }
+    // ── Response formatting ────────────────────────────────
+    // Antigravity does not support hooks. Return undefined for all responses.
+    formatPreToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPostToolUseResponse(_response) {
+        return undefined;
+    }
+    formatPreCompactResponse(_response) {
+        return undefined;
+    }
+    formatSessionStartResponse(_response) {
+        return undefined;
+    }
+    // ── Configuration ──────────────────────────────────────
+    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 {};
+    }
+    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) {
+        return [
+            {
+                check: "Hook support",
+                status: "warn",
+                message: "Antigravity does not support hooks. " +
+                    "Only MCP integration is available.",
+            },
+        ];
+    }
+    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 ~/.gemini/antigravity/mcp_config.json",
+            };
+        }
+        catch {
+            return {
+                check: "MCP registration",
+                status: "warn",
+                message: "Could not read ~/.gemini/antigravity/mcp_config.json",
+            };
+        }
+    }
+    getInstalledVersion() {
+        try {
+            const pkgPath = resolve(homedir(), ".gemini", "extensions", "context-mode", "package.json");
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            return pkg.version ?? "unknown";
+        }
+        catch {
+            return "not installed";
+        }
+    }
+    // ── Upgrade ────────────────────────────────────────────
+    configureAllHooks(_pluginRoot) {
+        return [];
+    }
+    setHookPermissions(_pluginRoot) {
+        return [];
+    }
+    updatePluginRegistry(_pluginRoot, _version) {
+        // Antigravity plugin registry is managed via mcp_config.json
+    }
+    getRoutingInstructions() {
+        const instructionsPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "configs", "antigravity", "GEMINI.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/antigravity-cli/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * adapters/antigravity-cli — Google Antigravity CLI (`agy`) adapter.
+ *
+ * Integration: MCP tools plus agy's Claude-compatible hook surface. `agy`
+ * reads its global MCP profile from `~/.gemini/config/mcp_config.json`
+ * (distinct from the Antigravity IDE's `~/.gemini/antigravity/mcp_config.json`)
+ * and hooks from `~/.gemini/config/hooks.json`, or from an installed agy
+ * plugin's root `hooks.json`.
+ *
+ * context-mode wires only the surfaces that have a verified mapping:
+ *   - PreToolUse for bounded routing enforcement on Bash/Read/Grep/WebFetch
+ *   - PostToolUse capture for executed tool calls
+ *   - best-effort Stop capture for session-end continuity when agy emits it
+ *
+ * PreInvocation/PostInvocation are intentionally not registered here: there is
+ * no verified payload/response contract or shared context-mode pipeline target
+ * for those agy events yet.
+ */
+import { AntigravityAdapter } from "../antigravity/index.js";
+import type { DiagnosticResult, HookParadigm, PlatformCapabilities, PostToolUseEvent, PostToolUseResponse, PreToolUseEvent, PreToolUseResponse } from "../types.js";
+export declare function antigravityCliMcpConfigPath(): string;
+export declare function antigravityCliConfigDir(): string;
+/** agy reads user hooks from ~/.gemini/config/hooks.json (sibling of mcp_config.json). */
+export declare function antigravityCliHooksPath(): string;
+/**
+ * `agy plugin install <bundle>` registers MCP + hook + skill into agy's plugin
+ * profile under ~/.gemini/config/plugins/<name>/ (verified on agy 1.0.6, re-verified 1.0.10) — the
+ * canonical install. The global mcp_config.json / hooks.json paths above are the
+ * manual (no-plugin) fallback. doctor must recognize BOTH.
+ */
+export declare function antigravityCliPluginDir(): string;
+export declare class AntigravityCliAdapter extends AntigravityAdapter {
+    readonly name = "Antigravity CLI";
+    readonly paradigm: HookParadigm;
+    readonly capabilities: PlatformCapabilities;
+    getSettingsPath(): string;
+    getConfigDir(_projectDir?: string): string;
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    formatPostToolUseResponse(_response: PostToolUseResponse): unknown;
+    checkPluginRegistration(): DiagnosticResult;
+    getInstalledVersion(): string;
+    /**
+     * Write/merge the agy hooks into ~/.gemini/config/hooks.json (manual,
+     * non-plugin path). Idempotent — unrelated hook entries are preserved.
+     */
+    configureAllHooks(_pluginRoot: string): string[];
+    /** Report agy hook status across plugin and manual profiles. */
+    validateHooks(_pluginRoot: string): DiagnosticResult[];
+}