fapony 0.2.0 → 0.3.0

package/src/install/claude.ts

@@ -105,6 +105,10 @@ export function cmdInstallClaude(
       console.error(`  (Claude Code user scope)`);
       const dir = claudeSkillsDir(deps.homedir ?? homedir);
       reportSkills(linkSkills(dir, dryRun), dir, dryRun);
+      // MCP is already wired, but a hook can be new since the last install
+      // (e.g. the Edit hint) — always ensure the hook wiring, not only on a
+      // fresh MCP add. This is the upgrade path for existing installs.
+      installClaudeHooks(dryRun, deps);
       return;
     }
     console.error(
@@ -120,6 +124,9 @@ export function cmdInstallClaude(
   if (dryRun) {
     console.error(`── dry-run: would run ──`);
     console.error(`  ${addArgs.join(" ")}`);
+    // Dry-run shows the hook wiring too — the installers are dry-run-safe
+    // ("would write", no writes), so the preview stays truthful.
+    installClaudeHooks(dryRun, deps);
     return;
   }
 
@@ -148,9 +155,9 @@ export function cmdInstallClaude(
   installStatusline(dryRun, deps);
 
   // Wire the Stop hook that refuses to end a turn with ungraded commits,
-  // and the Read hint that annotates large-file reads (annotate-only).
-  installStopHook(dryRun, deps);
-  installReadHintHook(dryRun, deps);
+  // and the Read/Edit hints that annotate reads of large files and edits to
+  // files with importers (both annotate-only).
+  installClaudeHooks(dryRun, deps);
 }
 
 /**
@@ -336,6 +343,19 @@ function ensureClaudeHook(
   );
 }
 
+/**
+ * Wire every hook fapony owns: the Stop hook that refuses to end a turn with
+ * ungraded commits, and the Read/Edit PreToolUse hints (annotate-only).
+ * Idempotent and dry-run-safe. Called on every install, not just a fresh MCP
+ * add — an existing install must still pick up a hook added later.
+ */
+function installClaudeHooks(dryRun: boolean, deps: InstallDeps): void {
+  installStopHook(dryRun, deps);
+  installReadHintHook(dryRun, deps);
+  installEditHintHook(dryRun, deps);
+  installSessionStartHook(dryRun, deps);
+}
+
 function installStopHook(dryRun: boolean, deps: InstallDeps): void {
   ensureClaudeHook(dryRun, deps, {
     event: "Stop",
@@ -361,3 +381,31 @@ function installReadHintHook(dryRun: boolean, deps: InstallDeps): void {
     label: "read hint",
   });
 }
+
+/**
+ * PreToolUse hook on Edit: annotates an edit with the file's importer count
+ * plus the review-seed command that lists them, once per (session, file).
+ * Annotate only — no permissionDecision is ever returned, the edit always
+ * proceeds. The matcher "Edit" keeps the spawn off every other tool call.
+ */
+function installEditHintHook(dryRun: boolean, deps: InstallDeps): void {
+  ensureClaudeHook(dryRun, deps, {
+    event: "PreToolUse",
+    matcher: "Edit",
+    subcommand: "hook-edit-hint",
+    label: "edit hint",
+  });
+}
+
+/**
+ * SessionStart hook: injects `fapony mem kickoff` as context when the repo has
+ * a mem log, and stays silent when it does not. Context only — SessionStart
+ * cannot block, and a repo without mem never sees a line.
+ */
+function installSessionStartHook(dryRun: boolean, deps: InstallDeps): void {
+  ensureClaudeHook(dryRun, deps, {
+    event: "SessionStart",
+    subcommand: "hook-session-start",
+    label: "session start",
+  });
+}

package/src/install/codex.ts

@@ -1,17 +1,30 @@
 // src/install/codex.ts — Codex install provider
 //
-// Reads/writes ~/.codex/config.toml directly. Codex has no CLI for MCP config.
+// Reads/writes ~/.codex/config.toml directly for MCP config.
+// Reads/writes ~/.codex/hooks.json for lifecycle hooks (Stop, SessionStart).
+// Symlinks skills into ~/.agents/skills/ (same dir as ZCode).
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CODEX_MCP_ENTRY, defaultExit, type InstallDeps } from "./types.js";
+import { agentsSkillsDir, linkSkills, reportSkills } from "./skills.js";
+import {
+  CODEX_MCP_ENTRY,
+  defaultExit,
+  INSTALL_ROOT,
+  type InstallDeps,
+} from "./types.js";
 
 export function findCodexConfig(getHome: () => string): string | null {
   const p = join(getHome(), ".codex", "config.toml");
   return existsSync(p) ? p : null;
 }
 
+export function findCodexHooksJson(getHome: () => string): string | null {
+  const p = join(getHome(), ".codex", "hooks.json");
+  return existsSync(p) ? p : null;
+}
+
 function isCodexConfigured(content: string): boolean {
   // Check if [mcp_servers.fapony] section exists with our command
   const sectionRegex = /\[mcp_servers\.fapony\]/;
@@ -20,9 +33,124 @@ function isCodexConfigured(content: string): boolean {
   return content.includes("fapony.ts") && content.includes("mcp");
 }
 
+function readJsonObject(path: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append a fapony command hook to one event group in ~/.codex/hooks.json.
+ * Never replaces other hook groups or foreign entries within the group.
+ * A fapony-owned entry is identified by the subcommand string
+ * ("hook-stop" / "hook-session-start") inside its command — per-group
+ * idempotence, so an existing install with only Stop still picks up
+ * SessionStart on the next run.
+ */
+function installCodexHookGroup(
+  dryRun: boolean,
+  getHome: () => string,
+  opts: { event: "Stop" | "SessionStart"; subcommand: string; label: string },
+): void {
+  const hooksPath = join(getHome(), ".codex", "hooks.json");
+  let config: Record<string, unknown> = {};
+  if (existsSync(hooksPath)) {
+    const parsed = readJsonObject(hooksPath);
+    if (!parsed) {
+      console.error(
+        `  ${opts.label}: ${hooksPath} is unreadable or malformed — skipping`,
+      );
+      return;
+    }
+    config = parsed;
+  }
+
+  const hookMap = config.hooks;
+  if (
+    hookMap !== undefined &&
+    (typeof hookMap !== "object" || Array.isArray(hookMap))
+  ) {
+    console.error(
+      `  ${opts.label}: ${hooksPath} has an unexpected "hooks" shape — skipping`,
+    );
+    return;
+  }
+
+  const map = (hookMap ?? {}) as Record<string, unknown>;
+  // Codex event arrays: each element is { matcher?, hooks: [...] }
+  const group = Array.isArray(map[opts.event])
+    ? (map[opts.event] as unknown[])
+    : [];
+
+  // Check if the fapony hook is already present in this group (by subcommand)
+  const serialized = JSON.stringify(group);
+  if (serialized.includes(opts.subcommand)) {
+    console.error(
+      `  ${opts.label}: already configured in hooks.json — no change`,
+    );
+    return;
+  }
+
+  const command = `bun ${join(INSTALL_ROOT, "fapony.ts")} ${opts.subcommand}`;
+  const faponyEntry = { hooks: [{ type: "command", command }] };
+  const after = {
+    ...config,
+    hooks: { ...map, [opts.event]: [...group, faponyEntry] },
+  };
+
+  if (!dryRun) {
+    try {
+      writeFileSync(hooksPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
+    } catch (e) {
+      console.error(
+        `  ${opts.label}: failed to write — ${(e as Error).message}`,
+      );
+      return;
+    }
+  }
+  console.error(
+    `  ${opts.label}: ${dryRun ? "would write" : "wrote"} hooks.${opts.event} → ${hooksPath}`,
+  );
+  console.error(
+    `    review and trust via Codex /hooks before the hook will run`,
+  );
+}
+
+function installStopHook(dryRun: boolean, getHome: () => string): void {
+  installCodexHookGroup(dryRun, getHome, {
+    event: "Stop",
+    subcommand: "hook-stop",
+    label: "stop hook",
+  });
+}
+
+/**
+ * SessionStart hook: injects `fapony mem kickoff` as context when the repo
+ * has a mem log, silent when it does not (cmdHookSessionStart exits quiet).
+ * Same `hookSpecificOutput.additionalContext` contract Claude uses — Codex
+ * SessionStart reads that channel too. No matcher: match-all fires on every
+ * source including `clear` and on versions that send no source at all, where
+ * a `startup|resume` matcher would silently never fire; kickoff is capped at
+ * 4k and costs one cheap spawn, so the /clear path stays fast.
+ */
+function installSessionStartHook(dryRun: boolean, getHome: () => string): void {
+  installCodexHookGroup(dryRun, getHome, {
+    event: "SessionStart",
+    subcommand: "hook-session-start",
+    label: "session start",
+  });
+}
+
 export function cmdInstallCodex(dryRun: boolean, deps: InstallDeps = {}): void {
   const exitFn = deps.exit ?? defaultExit;
-  const configPath = findCodexConfig(deps.homedir ?? homedir);
+  const getHome = deps.homedir ?? homedir;
+  const configPath = findCodexConfig(getHome);
 
   if (!configPath) {
     console.error(
@@ -44,18 +172,21 @@ export function cmdInstallCodex(dryRun: boolean, deps: InstallDeps = {}): void {
   if (isCodexConfigured(content)) {
     console.error(`✓ mcp_servers.fapony already configured — no change needed`);
     console.error(`  (${configPath})`);
-    return;
-  }
-
-  if (dryRun) {
+  } else if (dryRun) {
     console.error(`── dry-run: would append to ${configPath} ──`);
     console.log(CODEX_MCP_ENTRY);
-    return;
+  } else {
+    const newContent = `${content.trimEnd()}\n\n${CODEX_MCP_ENTRY}`;
+    writeFileSync(configPath, newContent);
+    console.error(`✓ added mcp_servers.fapony to ${configPath}`);
+    console.error(`  restart Codex to load the MCP server`);
   }
 
-  // Append the fapony MCP server entry to the end of the config file
-  const newContent = `${content.trimEnd()}\n\n${CODEX_MCP_ENTRY}`;
-  writeFileSync(configPath, newContent);
-  console.error(`✓ added mcp_servers.fapony to ${configPath}`);
-  console.error(`  restart Codex to load the MCP server`);
+  // --- Stop + SessionStart hooks (~/.codex/hooks.json) ---
+  installStopHook(dryRun, getHome);
+  installSessionStartHook(dryRun, getHome);
+
+  // --- Skills (~/.agents/skills/) ---
+  const skillsDir = agentsSkillsDir(getHome);
+  reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
 }

package/src/install/opencode.ts

@@ -113,6 +113,8 @@ export function cmdInstallOpencode(
     reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
     installReadHintPlugin(dryRun, getHome);
     installCommitHintPlugin(dryRun, getHome);
+    installEditHintPlugin(dryRun, getHome);
+    installSessionStartPlugin(dryRun, getHome);
     return;
   }
 
@@ -136,6 +138,8 @@ export function cmdInstallOpencode(
     console.log(computeDiff(before, after));
     installReadHintPlugin(dryRun, getHome);
     installCommitHintPlugin(dryRun, getHome);
+    installEditHintPlugin(dryRun, getHome);
+    installSessionStartPlugin(dryRun, getHome);
     return;
   }
 
@@ -157,6 +161,8 @@ export function cmdInstallOpencode(
   reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
   installReadHintPlugin(dryRun, getHome);
   installCommitHintPlugin(dryRun, getHome);
+  installEditHintPlugin(dryRun, getHome);
+  installSessionStartPlugin(dryRun, getHome);
 }
 
 /**
@@ -228,7 +234,7 @@ export const FaponyReadHint = async ({ directory }) => {
               const { relative } = require("node:path");
               const { join: pjoin } = require("node:path");
               const wt = ctx.worktree;
-              const abs = realpathSync(filePath.startsWith("/") ? filePath : pjoin(wt, filePath));
+              const abs = realpathSync(filePath.startsWith("/") ? filePath : pjoin(directory, filePath));
               const r = relative(wt, abs).split("\\\\").join("/");
               return r.startsWith("..") ? null : r;
             } catch { return null; }
@@ -308,6 +314,80 @@ export const FaponyCommitHint = async ({ directory }) => {
 `;
 }
 
+/**
+ * OpenCode plugin — the edit hint's in-process shape. `tool.execute.after`
+ * on the edit and write tools: when the touched file has importers, appends
+ * the importer count plus the review-seed command that lists them. Annotate
+ * only (no block, no dedupe beyond what editHintFor does itself).
+ *
+ * This is the OpenCode parity of Claude's Edit PreToolUse hook
+ * (PLAN-edit-importer-hint): same shared logic (editHintFor in src/hook.ts),
+ * same once-per-(session, file) dedupe, same `"edit"` fire surface. One
+ * known difference: OpenCode's only annotate channel is `after`, so the hint
+ * lands one step after the edit instead of before it — the `before` hook can
+ * only mutate args or throw, and a hint must never block a tool call.
+ *
+ * `write` is guarded alongside `edit` for free: a write to a new file
+ * resolves to null inside editHintFor (nothing imports it yet), so only a
+ * write that overwrites an imported file fires. `apply_patch` is out of
+ * scope — its paths live inside patchText, not filePath (separate plan).
+ */
+export function editHintPluginSource(root: string): string {
+  const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
+  return `// fapony edit hint — annotates edits to source files that have importers
+// with the importer count plus the review-seed command that lists them.
+// Annotate only: never blocks, dedupe per (session, file) inside editHintFor.
+// Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
+import { editHintFor, recordHintFire } from ${hookModule};
+
+export const FaponyEditHint = async ({ directory }) => {
+  return {
+    "tool.execute.after": async (input, output) => {
+      try {
+        if (input.tool !== "edit" && input.tool !== "write") return;
+        // The only channel that reaches the agent is output.output; if it is
+        // not a string the hint cannot surface, so bail before editHintFor
+        // spends the per-session dedupe row or logs a fire that never showed.
+        if (typeof output.output !== "string") return;
+        const filePath = input.args?.filePath;
+        const hint = editHintFor({
+          filePath,
+          cwd: directory,
+          session: input.sessionID,
+        });
+
+        // --- hint-fire log (PLAN-edit-importer-hint, opencode parity) ---
+        // After output — best-effort, never block the hint.
+        if (hint) {
+          output.output = output.output + "\\n" + hint;
+          try {
+            const { spawnSync } = require("node:child_process");
+            const git = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: directory, encoding: "utf-8" });
+            if (git.status === 0) {
+              const worktree = require("node:fs").realpathSync(git.stdout.trim());
+              const rel = typeof filePath === "string" ? (() => {
+                try {
+                  const { relative, join: pjoin } = require("node:path");
+                  const abs = require("node:fs").realpathSync(filePath.startsWith("/") ? filePath : pjoin(directory, filePath));
+                  const r = relative(worktree, abs).split("\\\\").join("/");
+                  return r.startsWith("..") ? null : r;
+                } catch { return null; }
+              })() : null;
+              recordHintFire({ ts: new Date().toISOString(), worktree, surface: "edit", file: rel, count: 1 });
+            }
+          } catch {
+            // best-effort
+          }
+        }
+      } catch {
+        // a hint must never break an edit
+      }
+    },
+  };
+};
+`;
+}
+
 function installReadHintPlugin(dryRun: boolean, getHome: () => string): void {
   const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
   const pluginPath = join(pluginsDir, "fapony-read-hint.ts");
@@ -373,3 +453,131 @@ function installCommitHintPlugin(dryRun: boolean, getHome: () => string): void {
     `  commit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
   );
 }
+
+function installEditHintPlugin(dryRun: boolean, getHome: () => string): void {
+  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
+  const pluginPath = join(pluginsDir, "fapony-edit-hint.ts");
+  if (existsSync(pluginPath)) {
+    let current = "";
+    try {
+      current = readFileSync(pluginPath, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (current.includes("editHintFor")) {
+      console.error(`  edit hint: already installed — no change`);
+      return;
+    }
+    console.error(
+      `  edit hint: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+    );
+    return;
+  }
+  if (!dryRun) {
+    try {
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(pluginPath, editHintPluginSource(INSTALL_ROOT), "utf-8");
+    } catch (e) {
+      console.error(`  edit hint: failed to write — ${(e as Error).message}`);
+      return;
+    }
+  }
+  console.error(
+    `  edit hint: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  );
+}
+
+/**
+ * OpenCode plugin — session-start context via `fapony mem kickoff`, the
+ * OpenCode parity of Claude's SessionStart hook.
+ *
+ * Why `experimental.chat.system.transform` and not the `event` hook on
+ * `session.created`: the event hook is observer-only (returns void, no
+ * injection channel), while system.transform's `output.system` is the
+ * documented injection point (`packages/plugin/src/index.ts`: input
+ * `{ sessionID?, model }`, output `{ system: string[] }`). The context lands
+ * on the first model dispatch instead of at session creation — one step late,
+ * the same shape as every other OpenCode hint (annotate-after), and arguably
+ * better: sessions that never dispatch never pay the spawn.
+ *
+ * Once per session (closure Set — the factory runs once per server), silent
+ * when kickoff exits nonzero or prints nothing (no mem log in scope), never
+ * throws. `process.execPath` is the bun running opencode itself — no PATH
+ * dependency. Logic shared via `capContext` in src/hook.ts, same one-copy
+ * shape as the other three plugins.
+ */
+export function sessionStartPluginSource(root: string): string {
+  const hookModule = JSON.stringify(join(root, "src", "hook.ts"));
+  const faponyTs = JSON.stringify(join(root, "fapony.ts"));
+  return `// fapony session start — injects \`fapony mem kickoff\` as context once per
+// session, silent when the repo has no mem log. Annotate only: never blocks.
+// Generated by \`fapony install\` — edit src/hook.ts in the fapony checkout.
+import { capContext } from ${hookModule};
+
+export const FaponySessionStart = async ({ directory }) => {
+  const seen = new Set();
+  return {
+    "experimental.chat.system.transform": async (input, output) => {
+      try {
+        const sessionID = input?.sessionID;
+        if (!sessionID || seen.has(sessionID)) return;
+        seen.add(sessionID);
+        const { spawnSync } = require("node:child_process");
+        const kick = spawnSync(process.execPath, [${faponyTs}, "mem", "kickoff"], {
+          cwd: directory,
+          encoding: "utf-8",
+        });
+        if (kick.status !== 0) return;
+        const out = (kick.stdout ?? "").toString().trim();
+        if (!out) return;
+        output.system.push(capContext(out));
+      } catch {
+        // context must never break a session start
+      }
+    },
+  };
+};
+`;
+}
+
+function installSessionStartPlugin(
+  dryRun: boolean,
+  getHome: () => string,
+): void {
+  const pluginsDir = join(getHome(), ".config", "opencode", "plugins");
+  const pluginPath = join(pluginsDir, "fapony-session-start.ts");
+  if (existsSync(pluginPath)) {
+    let current = "";
+    try {
+      current = readFileSync(pluginPath, "utf-8");
+    } catch {
+      current = "";
+    }
+    if (current.includes("capContext")) {
+      console.error(`  session start: already installed — no change`);
+      return;
+    }
+    console.error(
+      `  session start: ${pluginPath} exists but isn't fapony's — not overwriting.`,
+    );
+    return;
+  }
+  if (!dryRun) {
+    try {
+      mkdirSync(pluginsDir, { recursive: true });
+      writeFileSync(
+        pluginPath,
+        sessionStartPluginSource(INSTALL_ROOT),
+        "utf-8",
+      );
+    } catch (e) {
+      console.error(
+        `  session start: failed to write — ${(e as Error).message}`,
+      );
+      return;
+    }
+  }
+  console.error(
+    `  session start: ${dryRun ? "would write" : "wrote"} ${pluginPath}`,
+  );
+}

package/src/install.ts

@@ -28,12 +28,13 @@ export {
   claudeGetPointsToFapony,
   cmdInstallClaude,
 } from "./install/claude.js";
-export { cmdInstallCodex } from "./install/codex.js";
+export { cmdInstallCodex, findCodexHooksJson } from "./install/codex.js";
 export { cmdInstallCursor } from "./install/cursor.js";
 export { detectClients } from "./install/detect.js";
 export {
   cmdInstallOpencode,
   commitHintPluginSource,
+  editHintPluginSource,
   readHintPluginSource,
 } from "./install/opencode.js";
 export {

package/src/lint-baseline.ts

@@ -14,6 +14,7 @@
 import { execSync } from "node:child_process";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
+import { DEFAULT_EVIDENCE_FILE } from "./db/index.js";
 import { faponyDir } from "./db/load.js";
 import { assertSafe } from "./safety.js";
 
@@ -51,13 +52,13 @@ function gitSha(cwd: string): string {
   return p.exitCode === 0 ? p.stdout.toString().trim().slice(0, 12) : "none";
 }
 
-function baselinePath(worktree: string): string {
+export function baselinePath(worktree: string): string {
   const key = worktree.replace(/[^A-Za-z0-9._-]+/g, "_");
   return join(faponyDir(), "lint-baseline", `${key}.json`);
 }
 
-function readEvidenceLintCmd(worktree: string): string | null {
-  const evidence = join(worktree, ".fapony", "evidence.json");
+export function readEvidenceLintCmd(worktree: string): string | null {
+  const evidence = join(worktree, DEFAULT_EVIDENCE_FILE);
   try {
     const parsed = JSON.parse(readFileSync(evidence, "utf-8")) as {
       commands?: { name?: string; cmd?: string }[];

package/src/mcp/evidence.ts

@@ -17,7 +17,13 @@
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
-import { type Config, evidenceFile, safetyDeny } from "../db/index.js";
+import {
+  type Config,
+  EVIDENCE_FILENAME,
+  evidenceFile,
+  FAPONY_DIR,
+  safetyDeny,
+} from "../db/index.js";
 import { assertSafe } from "../safety.js";
 import type { EvidenceItem, EvidenceStatus } from "./primitives.js";
 
@@ -80,7 +86,13 @@ export function resolveEvidencePath(
       APP_GROUPS.includes(group) &&
       heads.every(([g, a]) => g === group && a === app)
     ) {
-      const candidate = join(worktree, group, app, ".fapony", "evidence.json");
+      const candidate = join(
+        worktree,
+        group,
+        app,
+        FAPONY_DIR,
+        EVIDENCE_FILENAME,
+      );
       if (existsSync(candidate)) return candidate;
     }
   }

package/src/mcp/tools/index.ts

@@ -9,8 +9,7 @@
 import { VERDICT_GRADES } from "../../parse.js";
 import { REASON_CODES, REGIME_CODES } from "../types.js";
 
-export { toolMemAdd, toolMemFind } from "./mem.js";
-export { toolPassiveUsage } from "./usage.js";
+export { toolMemAdd, toolMemClose, toolMemFind } from "./mem.js";
 export { toolVerdictSubmit } from "./verdict.js";
 
 // --- Tool definitions ---
@@ -179,43 +178,29 @@ export const TOOLS = [
     },
   },
   {
-    name: "fapony_usage",
+    name: "mem_close",
     description:
-      "Query passive usage across every coding client on this machine — " +
-      "OpenCode, Claude Code, Codex, and ZCode — on one ruler: token counts, " +
-      "cost, and breakdown by model. No client's own session log can see " +
-      "another's, so this is the only way to compare them. Filter by " +
-      "worktree and time range.",
+      "Close a mem row by id with a tombstone message (what was done). " +
+      "The write half of closing what mem_find shows as open — id must exist. " +
+      "Returns the ref and timestamp.",
     inputSchema: {
       type: "object" as const,
       properties: {
         worktree: {
           type: "string",
-          description: "Filter by worktree path (absolute)",
-        },
-        since: {
-          type: "number",
-          description:
-            "Unix timestamp — include sessions created at or after this time",
-        },
-        until: {
-          type: "number",
           description:
-            "Unix timestamp — include sessions created at or before this time",
+            "Absolute path (git rev-parse --show-toplevel) — required",
         },
-        detail: {
-          type: "boolean",
-          description:
-            "If true, include tool-call breakdown + step counts per session " +
-            "(activity signal, not quality). Default false keeps output compact.",
+        id: {
+          type: "string",
+          description: "The row id to close",
         },
-        json: {
-          type: "boolean",
-          description:
-            "If true, return raw JSON PassiveUsageResult. If false (default), return human-readable text.",
+        text: {
+          type: "string",
+          description: "Tombstone message — what was done (commit sha counts)",
         },
       },
-      required: [],
+      required: ["worktree", "id", "text"],
     },
   },
 ];