@100xprompt/brain 0.0.0-stage → 0.1.1

package/src/handoff.ts

@@ -0,0 +1,104 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+// Pending handoffs: a brief waiting for the next session of a target tool in a project. `brain session
+// continue --in <tool>` writes one; the tool's session-start hook (hooks.ts) finds it, hands the brief to
+// the model once, and marks it used for that tool. Kept as plain files under ~/.brain/handoffs.
+
+export const HANDOFF_HOURS = 12
+
+export interface Handoff {
+  id: string
+  createdAt: string
+  expiresAt: string
+  /** The tool and portable id of the session being continued. */
+  fromTool: string
+  sessionId: string
+  title?: string
+  /** The project folder the brief is for. */
+  cwd: string
+  gitRemote?: string
+  /** The tool the person is moving to, or "any". */
+  target: string
+  brief: string
+  /** The brief as a Markdown file, for pasting by hand. */
+  briefPath: string
+  /** Tools whose sessions have already received it. */
+  consumedBy: string[]
+}
+
+export const handoffDir = (home: string) => join(home, ".brain", "handoffs")
+
+export function saveHandoff(home: string, h: Omit<Handoff, "briefPath" | "consumedBy" | "expiresAt" | "createdAt"> & { now?: number }): Handoff {
+  const now = h.now ?? Date.now()
+  const dir = handoffDir(home)
+  mkdirSync(dir, { recursive: true })
+  const briefPath = join(dir, `${h.id}.md`)
+  const { now: _, ...rest } = h
+  const full: Handoff = { ...rest, createdAt: new Date(now).toISOString(), expiresAt: new Date(now + HANDOFF_HOURS * 3_600_000).toISOString(), briefPath, consumedBy: [] }
+  writeFileSync(briefPath, `${h.brief}\n`)
+  writeFileSync(join(dir, `${h.id}.json`), `${JSON.stringify(full, null, 1)}\n`)
+  return full
+}
+
+export function listHandoffs(home: string): Handoff[] {
+  const dir = handoffDir(home)
+  let names: string[] = []
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith(".json"))
+  } catch {
+    return []
+  }
+  const out: Handoff[] = []
+  for (const n of names) {
+    try {
+      out.push(JSON.parse(readFileSync(join(dir, n), "utf8")) as Handoff)
+    } catch {
+      // A half-written or foreign file is not a handoff.
+    }
+  }
+  return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+const norm = (p: string) => p.replace(/\/+$/, "")
+/** The same project: the same folder, one inside the other, or the same git remote. */
+function sameProject(h: Handoff, cwd: string, gitRemote?: string): boolean {
+  const a = norm(h.cwd)
+  const b = norm(cwd)
+  return a === b || b.startsWith(`${a}/`) || a.startsWith(`${b}/`) || (!!gitRemote && !!h.gitRemote && h.gitRemote === gitRemote)
+}
+
+/** A tool's claim on a handoff: created exclusively, so two sessions starting at once cannot both take it. */
+const claimPath = (home: string, id: string, tool: string) => join(handoffDir(home), `${id}.${tool}.claimed`)
+
+/** The newest unexpired handoff for this project that `tool` has not received yet. */
+export function findHandoff(home: string, q: { cwd: string; tool: string; gitRemote?: string; now?: number }): Handoff | undefined {
+  const now = q.now ?? Date.now()
+  return listHandoffs(home).find(
+    (h) =>
+      Date.parse(h.expiresAt) > now &&
+      (h.target === q.tool || h.target === "any") &&
+      !h.consumedBy.includes(q.tool) &&
+      !existsSync(claimPath(home, h.id, q.tool)) &&
+      sameProject(h, q.cwd, q.gitRemote),
+  )
+}
+
+/** Claims the handoff for `tool`; false when another session of that tool already has it (deliver nothing then). */
+export function markConsumed(home: string, id: string, tool: string): boolean {
+  try {
+    writeFileSync(claimPath(home, id, tool), new Date().toISOString(), { flag: "wx" })
+  } catch {
+    return false
+  }
+  // Also recorded in the handoff itself, for listing; the claim file is what decides.
+  const path = join(handoffDir(home), `${id}.json`)
+  try {
+    const h = JSON.parse(readFileSync(path, "utf8")) as Handoff
+    if (!h.consumedBy.includes(tool)) h.consumedBy.push(tool)
+    writeFileSync(path, `${JSON.stringify(h, null, 1)}\n`)
+  } catch {
+    // Gone or unreadable: the claim file still stands.
+  }
+  return true
+}

package/src/hooks.ts

@@ -0,0 +1,455 @@
+import { CLI_PATH, selfArgs, stableBun } from "./self.ts"
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { toolLabel } from "./brief.ts"
+import { gitInfo, isDir } from "./fsutil.ts"
+import { findHandoff, type Handoff, markConsumed } from "./handoff.ts"
+import { syncInBackground } from "./memory/sync.ts"
+
+// Session-start hooks: how a pending handoff (handoff.ts) reaches the model in the target tool without the
+// person pasting anything. Each tool runs `<bun> brain/src/cli.ts session hook session-start --tool <tool>`
+// when a session starts; runHook finds the newest handoff for that folder the tool has not received yet,
+// prints it in the shape the tool expects, and marks it received.
+//
+// Checked against the installed versions on 2026-11-08, from their docs and their own code:
+// - Claude Code 2.1.316: ~/.claude/settings.json hooks.SessionStart [{hooks:[{type,command,timeout}]}];
+//   stdout JSON hookSpecificOutput.additionalContext, capped at 10,000 characters.
+// - Codex 0.147.0: ~/.codex/hooks.json (also [hooks] in config.toml; both are merged); hooks are on by
+//   default but each must be trusted once by the person (/hooks), and trust is keyed by the hook's position
+//   in the file. Plain stdout becomes developer context, spilled to a file above ~2,500 tokens unless the
+//   handler sets additionalContextLimit.
+// - Cursor 3.27.22: ~/.cursor/hooks.json {version:1, hooks:{sessionStart:[{command}]}}; stdout JSON
+//   additional_context, at most 10,000 characters. Its input has workspace_roots, not cwd. Cursor also runs
+//   the hooks in ~/.claude/settings.json, so the Claude Code hook stays quiet when Cursor runs it.
+// - Gemini CLI 0.33.1: ~/.gemini/settings.json hooks.SessionStart (timeouts in milliseconds; user hooks run
+//   only in folders Gemini trusts); stdout JSON hookSpecificOutput.additionalContext, injected as the first
+//   turn, and systemMessage, shown to the person.
+
+type Json = Record<string, any>
+
+/** Tools whose session-start hook this module can install. */
+export const HOOK_TOOLS: string[] = ["claude-code", "codex", "cursor-ide", "gemini-cli"]
+
+/** The words every installed hook command ends with (before `--tool <tool>`); how uninstall finds its own entries. */
+const MARK = "session hook session-start"
+/** The hook reads a few small files; a stuck one must never hold up a session for long. */
+const TIMEOUT_S = 10
+const CLI = CLI_PATH
+
+interface Spec {
+  /** The folder the tool creates when it first runs, relative to home; without it there is nothing to hook. */
+  dir: string
+  /** The user-level config file the hook goes in, relative to home. */
+  file: string
+  /** The session-start event's key in that file. */
+  event: string
+  /** Grouped events hold [{matcher?, hooks: [handler]}] (Claude Code, Codex, Gemini CLI); Cursor's hold handlers. */
+  grouped: boolean
+  handler: (command: string) => Json
+  /** Characters of context the tool takes whole from a session-start hook. */
+  limit: number
+  /** UTF-8 bytes of context the tool takes whole, where it counts bytes rather than characters (Codex). */
+  bytes?: number
+  /** What the tool expects on stdout: the context for the model, and a line for the person where it shows one. */
+  output: (context: string, notice: string) => string
+  /** Why the file cannot take the hook as it is, if it cannot. */
+  check?: (config: Json) => string | undefined
+  /** Fields a new file needs besides the hook. */
+  init?: (config: Json) => void
+  /** What the person should know about this tool's hooks, from its settings. */
+  notes?: (home: string, config: Json) => string[]
+  /** Why the tool will not run the hook although it is in the file (its settings turn hooks off), if so. */
+  off?: (config: Json) => string | undefined
+  /** Hook trust is keyed by position in the file, so removing an entry shifts the ones after it (Codex). */
+  positional?: boolean
+}
+
+/** Claude Code and Gemini CLI read the same output shape. */
+const claudeStyle = (context: string, notice: string) => JSON.stringify({ systemMessage: notice, hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } })
+
+const SPECS: Record<string, Spec> = {
+  "claude-code": {
+    dir: ".claude",
+    file: ".claude/settings.json",
+    event: "SessionStart",
+    grouped: true,
+    handler: (command) => ({ type: "command", command, timeout: TIMEOUT_S }),
+    limit: 9_800,
+    output: claudeStyle,
+    off: (config) => (config.disableAllHooks === true ? "hooks are turned off in Claude Code's settings (disableAllHooks)" : undefined),
+  },
+  codex: {
+    dir: ".codex",
+    file: ".codex/hooks.json",
+    event: "SessionStart",
+    grouped: true,
+    // Codex counts a token as 4 bytes of UTF-8 and spills context over the limit to a temp file, leaving the model a
+    // preview: 4,000 tokens is 16,000 bytes, so the brief is cut to fit in bytes as well as characters.
+    handler: (command) => ({ type: "command", command, timeout: TIMEOUT_S, additionalContextLimit: 4_000 }),
+    limit: 9_000,
+    bytes: 15_600,
+    output: (context) => context,
+    positional: true,
+    notes: (home) => {
+      const out = ["Codex runs it once you trust it: accept the prompt when Codex starts, or use /hooks"]
+      let toml = ""
+      try {
+        toml = readFileSync(join(home, ".codex", "config.toml"), "utf8")
+      } catch {
+        // No config.toml: nothing to merge with.
+      }
+      if (tomlHasHooks(toml)) out.push("config.toml also has hooks; Codex merges both and warns at startup")
+      return out
+    },
+  },
+  "cursor-ide": {
+    dir: ".cursor",
+    file: ".cursor/hooks.json",
+    event: "sessionStart",
+    grouped: false,
+    handler: (command) => ({ command, timeout: TIMEOUT_S }),
+    limit: 9_800,
+    output: (context) => JSON.stringify({ additional_context: context }),
+    check: (config) => (config.version === undefined || config.version === 1 ? undefined : `hooks.json version ${JSON.stringify(config.version)} is not one this was checked against (1)`),
+    init: (config) => {
+      config.version ??= 1
+    },
+  },
+  "gemini-cli": {
+    dir: ".gemini",
+    file: ".gemini/settings.json",
+    event: "SessionStart",
+    grouped: true,
+    // A name lets the person turn it off with hooksConfig.disabled; Gemini's timeout is in milliseconds.
+    handler: (command) => ({ type: "command", name: "brain-handoff", command, timeout: TIMEOUT_S * 1000 }),
+    limit: 9_800,
+    output: claudeStyle,
+    notes: (_home, config) => (config.security?.folderTrust?.enabled !== false ? ["Gemini runs it only in folders you have trusted"] : []),
+    off: (config) => {
+      if (config.hooksConfig?.enabled === false || config.hooks?.enabled === false) return "hooks are turned off in Gemini's settings (hooksConfig.enabled)"
+      // Gemini matches hooksConfig.disabled against a hook's name, which is ours.
+      const disabled = config.hooksConfig?.disabled
+      return Array.isArray(disabled) && disabled.includes("brain-handoff") ? "Gemini's settings turn this hook off (hooksConfig.disabled)" : undefined
+    },
+  },
+}
+
+/**
+ * Whether Codex's config.toml defines hooks of its own. [hooks.state] does not count: it is where Codex records the
+ * hooks the person trusted or turned off (ours included), not a hook.
+ */
+function tomlHasHooks(toml: string): boolean {
+  if (!toml.trim()) return false
+  try {
+    const hooks = (Bun.TOML.parse(toml) as Json).hooks
+    return !!hooks && typeof hooks === "object" && Object.entries(hooks).some(([k, v]) => k !== "state" && Array.isArray(v) && v.length > 0)
+  } catch {
+    return /^\s*\[\[?hooks\.(?!state\b)/m.test(toml)
+  }
+}
+
+/** "cursor" is what `continue --in` calls Cursor; its handoffs are recorded for "cursor-ide". */
+const toolId = (tool: string) => (tool === "cursor" ? "cursor-ide" : tool)
+
+const sh = (s: string) => (/^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+/** The command a tool's hook runs; `program` (default: this bun and cli.ts, or the pinned package: self.ts) is what tests override. */
+/** What a hook starts brain with: this bun, then cli.ts (or, run through bunx, the pinned package: self.ts). */
+export const hookProgram = (cli: string = CLI_PATH) => [stableBun(), ...selfArgs(cli)].map(sh).join(" ")
+
+function hookCommand(tool: string, program = hookProgram()): string {
+  return `${program} ${MARK} --tool ${tool}`
+}
+
+const isOurs = (h: unknown, tool: string) => typeof (h as Json)?.command === "string" && (h as Json).command.trimEnd().endsWith(`${MARK} --tool ${tool}`)
+
+// ---- reading and writing the tools' config files ----
+
+type Loaded = { config: Json; indent: string } | { error: string }
+
+function load(path: string): Loaded {
+  if (!existsSync(path)) return { config: {}, indent: "  " }
+  let text: string
+  try {
+    text = readFileSync(path, "utf8")
+  } catch (e) {
+    return { error: `cannot read it (${(e as Error).message})` }
+  }
+  if (!text.trim()) return { config: {}, indent: "  " }
+  try {
+    const v = JSON.parse(text)
+    if (!v || typeof v !== "object" || Array.isArray(v)) return { error: "it is not a JSON object; left as it is" }
+    // Keep the file's own indentation so a rewrite changes only what it must.
+    return { config: v, indent: text.match(/\n([ \t]+)"/)?.[1] ?? "  " }
+  } catch {
+    return { error: "it is not plain JSON (comments?); left as it is" }
+  }
+}
+
+const backupOf = (path: string) => `${path}.brain-backup`
+
+/** Writes atomically through a symlink (dotfile managers), backing up the original once. */
+function save(path: string, config: Json, indent: string) {
+  const real = existsSync(path) ? realpathSync(path) : path
+  mkdirSync(dirname(real), { recursive: true })
+  if (existsSync(real) && !existsSync(backupOf(path))) copyFileSync(real, backupOf(path))
+  const tmp = `${real}.brain-tmp`
+  let mode: number | undefined
+  try {
+    mode = statSync(real).mode & 0o777
+  } catch {
+    // A new file keeps the default mode.
+  }
+  // Create the copy with the file's own mode: Claude Code's settings are 0600 and can hold API keys, so they must
+  // not sit readable by everyone, even for a moment. A copy left by an interrupted run would keep its old mode.
+  rmSync(tmp, { force: true })
+  writeFileSync(tmp, `${JSON.stringify(config, null, indent)}\n`, mode === undefined ? {} : { mode })
+  if (mode !== undefined) chmodSync(tmp, mode)
+  renameSync(tmp, real)
+}
+
+interface Pos {
+  i: number
+  j: number
+}
+
+/** The event's list in a config, or undefined when the config has none; an error when it is not shaped as expected. */
+function eventList(config: Json, spec: Spec): Json[] | undefined | { error: string } {
+  if (config.hooks === undefined) return undefined
+  if (!config.hooks || typeof config.hooks !== "object" || Array.isArray(config.hooks)) return { error: `"hooks" is not an object; left as it is` }
+  const list = config.hooks[spec.event]
+  if (list === undefined) return undefined
+  return Array.isArray(list) ? list : { error: `"hooks.${spec.event}" is not a list; left as it is` }
+}
+
+const handlersOf = (entry: Json, spec: Spec): Json[] => (spec.grouped ? (Array.isArray(entry?.hooks) ? entry.hooks : []) : [entry])
+
+/** Where this tool's brain hooks sit in the list, in file order. */
+function positions(list: Json[], spec: Spec, tool: string): Pos[] {
+  const out: Pos[] = []
+  list.forEach((entry, i) => handlersOf(entry, spec).forEach((h, j) => isOurs(h, tool) && out.push({ i, j })))
+  return out
+}
+
+function removeAt(list: Json[], spec: Spec, p: Pos) {
+  if (!spec.grouped) {
+    list.splice(p.i, 1)
+    return
+  }
+  list[p.i]!.hooks.splice(p.j, 1)
+  if (!list[p.i]!.hooks.length) list.splice(p.i, 1)
+}
+
+const same = (a: Json, b: Json) => Object.keys(a).length === Object.keys(b).length && Object.keys(b).every((k) => a[k] === b[k])
+
+/**
+ * Whether the brain's session-start hook is installed for `tool` under `home` and the tool's settings let it run;
+ * brief-writers.ts tells the person to paste the brief by hand when it is not.
+ */
+export function hookInstalled(tool: string, home: string): boolean {
+  const id = toolId(tool)
+  const spec = SPECS[id]
+  if (!spec) return false
+  const loaded = load(join(home, spec.file))
+  if ("error" in loaded) return false
+  const list = eventList(loaded.config, spec)
+  return Array.isArray(list) && positions(list, spec, id).length > 0 && !spec.off?.(loaded.config)
+}
+
+export interface HookChange {
+  tool: string
+  /** The config file changed (or that would be). */
+  path: string
+  action: "installed" | "already-installed" | "removed" | "not-installed" | "skipped"
+  why?: string
+}
+
+/** Checks shared by install and uninstall: a known tool, its folder, a readable config of the expected shape. */
+function prepare(tool: string, home: string): { id: string; spec: Spec; path: string; loaded: Extract<Loaded, { config: Json }>; list: Json[] | undefined } | HookChange {
+  const id = toolId(tool)
+  const spec = SPECS[id]
+  if (!spec) return { tool, path: "", action: "skipped", why: `no session-start hook for "${tool}"; hooks exist for ${HOOK_TOOLS.join(", ")}` }
+  const path = join(home, spec.file)
+  if (!isDir(join(home, spec.dir))) return { tool: id, path, action: "skipped", why: `no ~/${spec.dir} here: ${toolLabel(id)} has not run on this machine` }
+  const loaded = load(path)
+  if ("error" in loaded) return { tool: id, path, action: "skipped", why: loaded.error }
+  const bad = spec.check?.(loaded.config)
+  if (bad) return { tool: id, path, action: "skipped", why: bad }
+  const list = eventList(loaded.config, spec)
+  if (list && !Array.isArray(list)) return { tool: id, path, action: "skipped", why: list.error }
+  return { id, spec, path, loaded, list }
+}
+
+/**
+ * Adds the brain's session-start hook to each tool's user config (with a backup); idempotent. Merges with
+ * the person's hooks and always appends its own entry, so the positions of theirs never change. A dry run
+ * reports the current state and, in `why`, what an install would do. `command` replaces the program part of
+ * the hook command (`<bun> <cli.ts>`); the rest stays, since that is how uninstall finds the entry.
+ */
+export async function installHooks(tools: string[], home: string, opts: { dryRun?: boolean; command?: string } = {}): Promise<HookChange[]> {
+  const out: HookChange[] = []
+  for (const tool of [...new Set(tools)]) {
+    const p = prepare(tool, home)
+    if (!("spec" in p)) {
+      out.push(p)
+      continue
+    }
+    const { id, spec, path, loaded } = p
+    const fresh = spec.handler(hookCommand(id, opts.command))
+    const off = spec.off?.(loaded.config)
+    const notes = [...(off ? [off] : []), ...(spec.notes?.(home, loaded.config) ?? [])]
+    const change = (action: HookChange["action"], ...parts: string[]): HookChange => {
+      const why = [...parts, ...notes].join("; ")
+      return { tool: id, path, action, ...(why ? { why } : {}) }
+    }
+    const found = p.list ? positions(p.list, spec, id) : []
+    const current = found.length ? handlersOf(p.list![found[0]!.i]!, spec)[found[0]!.j]! : undefined
+    if (found.length === 1 && same(current!, fresh)) {
+      out.push(change("already-installed"))
+      continue
+    }
+    if (opts.dryRun) {
+      out.push(found.length ? change("already-installed", "would update it to the current command") : change("not-installed", "would add it"))
+      continue
+    }
+    const config = loaded.config
+    if (!found.length) {
+      spec.init?.(config)
+      config.hooks ??= {}
+      config.hooks[spec.event] ??= []
+      config.hooks[spec.event].push(spec.grouped ? { hooks: [fresh] } : fresh)
+    } else {
+      // Update the first in place (keeping its position, which Codex's trust is keyed by) and drop duplicates, last first.
+      const list = p.list!
+      for (const d of found.slice(1).reverse()) removeAt(list, spec, d)
+      if (spec.grouped) list[found[0]!.i]!.hooks[found[0]!.j] = fresh
+      else list[found[0]!.i] = fresh
+    }
+    save(path, config, loaded.indent)
+    out.push(found.length ? change("installed", "updated it in place") : change("installed"))
+  }
+  return out
+}
+
+/** Removes exactly what installHooks added. */
+export async function uninstallHooks(tools: string[], home: string, opts: { dryRun?: boolean } = {}): Promise<HookChange[]> {
+  const out: HookChange[] = []
+  for (const tool of [...new Set(tools)]) {
+    const p = prepare(tool, home)
+    if (!("spec" in p)) {
+      out.push(p)
+      continue
+    }
+    const { id, spec, path, loaded, list } = p
+    const found = list ? positions(list, spec, id) : []
+    if (!found.length) {
+      out.push({ tool: id, path, action: "not-installed" })
+      continue
+    }
+    // Codex keys trust by position: entries after ours move up and must be trusted again.
+    const shifts = spec.positional && list!.length - 1 > found[0]!.i ? "hooks listed after it move up one place, so Codex will ask you to trust them again" : undefined
+    if (opts.dryRun) {
+      out.push({ tool: id, path, action: "installed", why: ["would remove it", shifts].filter(Boolean).join("; ") })
+      continue
+    }
+    const config = loaded.config
+    for (const d of [...found].reverse()) removeAt(list!, spec, d)
+    if (!list!.length) {
+      delete config.hooks[spec.event]
+      if (!Object.keys(config.hooks).length) delete config.hooks
+    }
+    // A file that did not exist before install (no backup) and now holds nothing of the person's goes away.
+    const leftover = Object.keys(config).filter((k) => !(k === "version" && !spec.grouped))
+    if (!leftover.length && !existsSync(backupOf(path))) unlinkSync(path)
+    else save(path, config, loaded.indent)
+    out.push({ tool: id, path, action: "removed", ...(shifts ? { why: shifts } : {}) })
+  }
+  return out
+}
+
+// ---- running as a tool's hook ----
+
+/**
+ * Which tool is running the hook, from its input: Cursor runs Claude Code's user hooks, so does VS Code's Copilot
+ * Chat when chat.useClaudeHooks is on (VS Code 1.144), and Codex's /import copies them.
+ */
+function hostOf(input: Json): string | undefined {
+  if (typeof input.cursor_version === "string") return "cursor-ide"
+  const path = typeof input.transcript_path === "string" ? input.transcript_path : ""
+  // Copilot Chat keeps its transcripts in its own extension storage and starts sessions with source "new", which
+  // none of the four tools sends (the Copilot CLI documents the same value).
+  if (/\/github\.copilot-chat\//i.test(path) || input.source === "new") return "vscode-copilot"
+  const m = path.match(/\/\.(claude|codex|gemini|cursor)\//)
+  return m ? ({ claude: "claude-code", codex: "codex", gemini: "gemini-cli", cursor: "cursor-ide" } as Record<string, string>)[m[1]!] : undefined
+}
+
+/** The session's folders: `cwd` (Claude Code, Codex, Gemini CLI), else Cursor's workspace roots. Never the hook's own cwd. */
+function foldersOf(input: Json): string[] {
+  const all = [input.cwd, ...(Array.isArray(input.workspace_roots) ? input.workspace_roots : [])]
+  return [...new Set(all.filter((p): p is string => typeof p === "string" && p.startsWith("/")).map((p) => p.replace(/(.)\/+$/, "$1")))]
+}
+
+function pending(home: string, cwd: string, tool: string): Handoff | undefined {
+  const remote = gitInfo(cwd).gitRemote
+  const h = findHandoff(home, { cwd, tool, ...(remote ? { gitRemote: remote } : {}) })
+  if (!h) return undefined
+  // A session opened at the home folder or above it (/Users, /) contains every project below: only an exact match counts.
+  const root = home.replace(/\/+$/, "")
+  const top = cwd === "/" || cwd === root || root.startsWith(`${cwd}/`)
+  return top && h.cwd.replace(/(.)\/+$/, "$1") !== cwd ? undefined : h
+}
+
+function since(when: string): string {
+  const m = Math.round((Date.now() - Date.parse(when)) / 60_000)
+  if (!Number.isFinite(m) || m < 2) return "just now"
+  return m < 90 ? `${m} minutes ago` : `${Math.round(m / 60)} hours ago`
+}
+
+/** `s` cut to at most `chars` characters and `bytes` bytes of UTF-8, marked with "…" where cut; never splits a character. */
+function fit(s: string, chars: number, bytes = Number.POSITIVE_INFINITY): string {
+  if (s.length <= chars && Buffer.byteLength(s) <= bytes) return s
+  let out = ""
+  let size = Buffer.byteLength("…")
+  for (const ch of s) {
+    const n = Buffer.byteLength(ch)
+    if (out.length + ch.length > chars - 1 || size + n > bytes) break
+    out += ch
+    size += n
+  }
+  return `${out.trimEnd()}…`
+}
+
+/**
+ * Runs as a tool's hook: reads the hook's JSON input, finds a pending handoff for the session's folder,
+ * and returns what the tool expects on stdout (empty when there is nothing to hand over). Never throws:
+ * a hook that fails must not get in the way of the session it runs in.
+ */
+export async function runHook(event: string, tool: string, input: string, home: string): Promise<string> {
+  try {
+    const id = toolId(tool)
+    const spec = SPECS[id]
+    if (!spec || !/^session-?start$/i.test(event)) return ""
+    const parsed = input.trim() ? JSON.parse(input) : {}
+    const inp: Json = parsed && typeof parsed === "object" ? parsed : {}
+    if (typeof inp.hook_event_name === "string" && !/^session-?start$/i.test(inp.hook_event_name)) return ""
+    // After a compaction the session is already under way; a background agent is not the person carrying on.
+    if (inp.source === "compact" || inp.is_background_agent === true) return ""
+    const host = hostOf(inp)
+    if (host && host !== id) return ""
+    // Memory catches up on this project's earlier sessions in the background (once memory has been set up; see sync.ts).
+    const first = foldersOf(inp)[0]
+    if (first) syncInBackground(home, first, CLI)
+    for (const cwd of foldersOf(inp)) {
+      const h = pending(home, cwd, id)
+      if (!h) continue
+      const from = `${toolLabel(h.fromTool)}${h.title ? ` ("${fit(h.title.replace(/\s+/g, " ").trim(), 80)}")` : ""}, handed over ${since(h.createdAt)}`
+      const context = fit(`Continuing from ${from}.\n\n${h.brief}`, spec.limit, spec.bytes)
+      // Claimed before it is printed: another session of this tool that started at the same moment gets nothing.
+      if (!markConsumed(home, h.id, id)) continue
+      return spec.output(context, `brain: continuing from ${from}; the model has the brief.`)
+    }
+    return ""
+  } catch {
+    return ""
+  }
+}