@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-hooks/src/hooks/briefing/index.ts

@@ -0,0 +1,320 @@
+/**
+ * The `briefing` hook kind.
+ *
+ * Ports `enact-m5/.agents/hooks/session-briefing/`
+ * (`session-briefing.mjs` + `src/render.mjs` + `src/warmup.mjs`) onto the
+ * `HookHandler` contract in `../contract.ts`.
+ *
+ * Two subprocess calls into `lean-ctx`, both behind the injected `Runner` so
+ * tests never touch a real binary:
+ *
+ *  1. `hook codex-session-start` — the base lean-ctx session briefing text,
+ *     read out of its `hookSpecificOutput.additionalContext` JSON.
+ *  2. `overview [task]` and `knowledge status` — the PROJECT WARMUP appendix,
+ *     always emitted (even with no lean-ctx at all) because its static
+ *     workflow block does not depend on either call succeeding.
+ *
+ * `lean-ctx` is a GLOBAL binary installed fleet-wide on `PATH` by
+ * global-tools (see its `manifest.json`'s `"lean-ctx"` entry) — unlike the
+ * reference tree, there is no repo-local `.agents/bin/lean-ctx-local`
+ * wrapper here, so every call below resolves `lean-ctx` off the ambient
+ * `PATH` directly. What stays repo-local is lean-ctx's own state: every call
+ * still sets `LEAN_CTX_CONFIG_DIR`/`LEAN_CTX_DATA_DIR`/`LEAN_CTX_STATE_DIR`/
+ * `LEAN_CTX_CACHE_DIR` rooted at `<root>/.agents/lean-ctx/<config/lean-ctx|data|state|cache>`
+ * (`../../lean-ctx/env.ts`'s `leanCtxEnv` — shared with the `lean-ctx`
+ * pre/post-tool-use hook kind, `../lean-ctx/index.ts`), so lean-ctx's
+ * config/data/state/cache stay per-repository even though the binary itself
+ * is now shared.
+ *
+ * HARDCUT (work item A.3): this used to set the plain `XDG_CONFIG_HOME`/
+ * `XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` vars, mirroring what the
+ * reference's wrapper script exported before exec'ing its own repo-local
+ * binary. `../../lean-ctx/env.ts`'s header records the live verification
+ * (this session, 2026-09-14) that the real v3.9.20 binary does not actually
+ * key its config/data/state/cache resolution on those XDG vars at all — only
+ * on the four `LEAN_CTX_*` ones now used here.
+ *
+ * lean-ctx missing or failing is advisory, never fatal: the warmup section
+ * still goes out and the failure is named on stderr, but this never returns
+ * exitCode 2 — a briefing hook has no host-visible "block" channel, and the
+ * reference script's own header says the same ("Advises only — never block
+ * the session or prompt"). A spawn that never exits (gap #1) degrades the
+ * same way: the injected `Runner` is timeout-enforcing (see
+ * `../../lib/spawn-with-timeout.ts`), so a hung `lean-ctx` child is killed
+ * and reported exactly like a failed/ENOENT spawn — `status: null` — rather
+ * than hanging the calling agent host.
+ *
+ * `deploy.mjs`-level concerns from the reference tree — wiring the hook into
+ * each host's config, `--self-test`/`--host=`/`--event=` argv parsing, the
+ * five-surface deploy fixture in `tests/test-wiring.mjs` — are out of scope
+ * here: `src/hosts/*` and `src/main.ts`'s dispatch own that, per this task's
+ * boundary.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { HookHandler, HookInvocation, HookResult, HostId } from '../contract.ts'
+import { spawnWithTimeout } from '../../lib/spawn-with-timeout.ts'
+import { leanCtxEnvFor } from '../../lean-ctx/env.ts'
+
+/** The marker lean-ctx's own `hook codex-session-start` output carries, when present. */
+export const MARKER = 'lean-ctx SESSION BRIEFING'
+export const WARMUP_MARKER = 'PROJECT WARMUP'
+
+const LEAN_CTX_BIN = 'lean-ctx'
+
+const OVERVIEW_MAX_LINES = 28
+const OVERVIEW_TIMEOUT_MS = 12_000
+const DEFAULT_TIMEOUT_MS = 8_000
+
+export interface RunResult {
+  readonly status: number | null
+  readonly stdout: string
+  readonly stderr: string
+  /** `true` only when the spawn was killed for exceeding `timeoutMs` — see gap #1. */
+  readonly timedOut?: boolean
+}
+
+export interface RunOptions {
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly input?: string
+  /** Wall-clock spawn timeout in ms; overridable per call, defaults per call site below. */
+  readonly timeoutMs?: number
+}
+
+/** Process spawning, injected so tests never need a real `lean-ctx` binary. */
+export type Runner = (cmd: string, args: readonly string[], opts: RunOptions) => Promise<RunResult>
+
+function deliveredStateDir(root: string): string {
+  return join(root, '.agents/lean-ctx/state/session-briefing-delivered')
+}
+
+function sessionId(payload: Record<string, unknown>): string {
+  const raw = payload['session_id'] ?? payload['conversation_id']
+  return typeof raw === 'string' && raw.trim().length > 0 ? raw.trim() : 'unknown'
+}
+
+/** Cursor and Kimi have no host-native "fire once at SessionStart" channel; gate on a marker file instead. */
+function usesPromptGate(host: HostId): boolean {
+  return host === 'cursor' || host === 'kimi'
+}
+
+function deliveredPath(root: string, host: HostId, session: string): string {
+  return join(deliveredStateDir(root), `${host}-${session}.done`)
+}
+
+function alreadyDelivered(root: string, host: HostId, session: string): boolean {
+  if (!usesPromptGate(host)) return false
+  return existsSync(deliveredPath(root, host, session))
+}
+
+function markDelivered(root: string, host: HostId, session: string): void {
+  if (!usesPromptGate(host)) return
+  mkdirSync(deliveredStateDir(root), { recursive: true })
+  writeFileSync(deliveredPath(root, host, session), `${new Date().toISOString()}\n`)
+}
+
+function runLeanCtx(
+  run: Runner,
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  args: readonly string[],
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<RunResult> {
+  return run(LEAN_CTX_BIN, args, { cwd: root, env: leanCtxEnvFor(root, env), timeoutMs })
+}
+
+function truncateLines(text: string, maxLines: number): string {
+  const lines = text.split('\n')
+  if (lines.length <= maxLines) return text
+  return `${lines.slice(0, maxLines).join('\n')}\n… (${lines.length - maxLines} more lines; call ctx_overview for full map)`
+}
+
+function taskFromPayload(payload: Record<string, unknown>): string {
+  const prompt = payload['prompt']
+  const trimmed = typeof prompt === 'string' ? prompt.trim() : ''
+  if (trimmed.length < 8) return ''
+  return trimmed.length > 120 ? `${trimmed.slice(0, 117)}…` : trimmed
+}
+
+function workflowBlock(): string {
+  return [
+    WARMUP_MARKER,
+    '',
+    'Start every session (ctx_* or lean-ctx; use ctx_call when not advertised):',
+    '• ctx_overview / lean-ctx overview ["task"] — project map; FIRST on unfamiliar work',
+    '• ctx_knowledge(action="wakeup") — cross-session facts and decisions',
+    '• ctx_session(action="status") — last session findings in this repo',
+    '',
+    'Knowledge: ctx_knowledge or lean-ctx knowledge — status | recall | search | remember | consolidate',
+    'Checkpoints: ctx_session(action="task"|"decision", …) after significant progress',
+    '',
+    'After orientation: ctx_compose → ctx_read/ctx_search → ctx_shell (verify) → persist.',
+  ].join('\n')
+}
+
+/**
+ * The PROJECT WARMUP appendix. Always non-empty — its static workflow block
+ * does not depend on `lean-ctx` at all — so a briefing is never fully silent
+ * just because the binary is missing.
+ */
+async function projectWarmupAppendix(
+  run: Runner,
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  payload: Record<string, unknown>,
+): Promise<string> {
+  const parts = [workflowBlock()]
+
+  const task = taskFromPayload(payload)
+  const overviewArgs = task ? ['overview', task] : ['overview']
+  const overview = await runLeanCtx(run, root, env, overviewArgs, OVERVIEW_TIMEOUT_MS)
+  if (overview.status === 0 && overview.stdout.trim()) {
+    parts.push('', '--- ctx_overview (cached snapshot) ---', truncateLines(overview.stdout.trim(), OVERVIEW_MAX_LINES))
+  }
+
+  const knowledge = await runLeanCtx(run, root, env, ['knowledge', 'status'])
+  if (knowledge.status === 0 && knowledge.stdout.trim()) {
+    parts.push('', '--- ctx_knowledge status ---', knowledge.stdout.trim())
+  }
+
+  return parts.join('\n')
+}
+
+function composeBriefing(base: string, warmup: string): string {
+  const b = base.trim()
+  const w = warmup.trim()
+  if (b && w) return `${b}\n\n${w}`
+  return b || w
+}
+
+interface BaseBriefing {
+  readonly text: string
+  readonly failureNote: string
+  readonly outcome: 'ok' | 'timeout' | 'error'
+}
+
+/** Runs `lean-ctx hook codex-session-start`; failure degrades to an empty base text plus a stderr note. */
+async function baseBriefing(
+  run: Runner,
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  payload: Record<string, unknown>,
+): Promise<BaseBriefing> {
+  const result = await run(LEAN_CTX_BIN, ['hook', 'codex-session-start'], {
+    cwd: root,
+    env: leanCtxEnvFor(root, env),
+    input: JSON.stringify(payload),
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  })
+
+  if (result.status !== 0 || !result.stdout.trim()) {
+    const reason = result.stderr.trim() || `lean-ctx exited with status ${String(result.status)}`
+    return {
+      text: '',
+      failureNote: `session-briefing: lean-ctx hook codex-session-start failed — ${reason}\n`,
+      outcome: result.timedOut ? 'timeout' : 'error',
+    }
+  }
+
+  try {
+    const parsed = JSON.parse(result.stdout) as { hookSpecificOutput?: { additionalContext?: unknown } }
+    const text = parsed.hookSpecificOutput?.additionalContext
+    return { text: typeof text === 'string' ? text : '', failureNote: '', outcome: 'ok' }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return {
+      text: '',
+      failureNote: `session-briefing: lean-ctx hook codex-session-start returned invalid JSON — ${message}\n`,
+      outcome: 'error',
+    }
+  }
+}
+
+/**
+ * Wrap briefing text in a host's native envelope.
+ *
+ * Per official docs where they differ from the reference tree:
+ *  - Claude / Codex SessionStart (and any other event): `hookSpecificOutput.additionalContext`.
+ *  - Cursor: flat `additional_context` — the reference's nested
+ *    `hookSpecificOutput` shape for Cursor `UserPromptSubmit` is not part of
+ *    Cursor's documented hook contract, so it is not ported here.
+ *  - Kimi: bare stdout text (its `UserPromptSubmit` hook has no JSON envelope).
+ *  - OpenCode: `{"advice": "..."}`, consumed by this repo's own OpenCode plugin.
+ */
+function renderBriefing(host: HostId, event: string, text: string): string {
+  if (!text) return ''
+  if (host === 'kimi') return `${text}\n`
+  if (host === 'opencode') return JSON.stringify({ advice: text })
+  if (host === 'cursor') return JSON.stringify({ additional_context: text })
+  return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } })
+}
+
+export function createBriefingHandler(deps: { run: Runner }): HookHandler {
+  return async (inv: HookInvocation): Promise<HookResult> => {
+    const { host, root, env } = inv
+    const payload = inv.payload
+    const event = inv.event ?? 'SessionStart'
+    const session = sessionId(payload)
+
+    if (alreadyDelivered(root, host, session)) {
+      inv.record?.({ reason: 'SKIP already delivered this session' })
+      return { stdout: '', stderr: '', exitCode: 0 }
+    }
+
+    const { text: base, failureNote, outcome } = await baseBriefing(deps.run, root, env, payload)
+    const warmup = await projectWarmupAppendix(deps.run, root, env, payload)
+    const text = composeBriefing(base, warmup)
+
+    markDelivered(root, host, session)
+    const reasons = { ok: 'PASS', timeout: 'TIMEOUT lean-ctx hook codex-session-start', error: 'ERROR lean-ctx hook codex-session-start' }
+    inv.record?.({
+      reason: reasons[outcome],
+      message: failureNote.trim(),
+      downstream: 'lean-ctx hook codex-session-start, lean-ctx overview, lean-ctx knowledge status',
+    })
+
+    return {
+      stdout: renderBriefing(host, event, text),
+      stderr: failureNote,
+      exitCode: 0,
+    }
+  }
+}
+
+/**
+ * The production `Runner`: a real, timeout-enforcing subprocess via
+ * `spawnWithTimeout` (see `../../lib/spawn-with-timeout.ts`) — replaces the
+ * reference tree's `Bun.spawnSync`, which had no timeout and could hang the
+ * calling agent host forever on a stuck `lean-ctx` child (gap #1). A timeout
+ * degrades exactly like an ENOENT/failed spawn: `status: null` with the
+ * reason on stderr, plus `timedOut: true` so callers can tell the two apart.
+ */
+export const bunRunner: Runner = async (cmd, args, opts) => {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  try {
+    const result = await spawnWithTimeout(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env,
+      timeoutMs,
+      ...(opts.input !== undefined ? { stdin: opts.input } : {}),
+    })
+    if (result.timedOut) {
+      return {
+        status: null,
+        stdout: result.stdout,
+        stderr: result.stderr.trim() || `${cmd} timed out after ${timeoutMs}ms`,
+        timedOut: true,
+      }
+    }
+    return { status: result.exitCode, stdout: result.stdout, stderr: result.stderr }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { status: null, stdout: '', stderr: message }
+  }
+}
+
+export const handleBriefing: HookHandler = createBriefingHandler({ run: bunRunner })
+export default handleBriefing

package/packages/agent-hooks/src/hooks/contract.ts

@@ -0,0 +1,112 @@
+/**
+ * The shared hook contract.
+ *
+ * `controls hook <kind> --host=X` is invoked by agent hosts (Claude Code,
+ * Codex, Cursor, OpenCode, Kimi) with a JSON payload on stdin. Every kind
+ * (`pre-tool-use`, `user-prompt-submit`, `briefing`, `crg`, `lean-ctx`
+ * pre-tool-use/post-tool-use) is dispatched from `src/main.ts` through one
+ * `HookHandler` shape, so a handler never sees `process`, argv, or stdin
+ * directly — only the `HookInvocation` it is called with, and it returns a
+ * `HookResult` for `main.ts` to write to stdout/stderr and turn into a
+ * process exit code. `lean-ctx mcp` is the one exception: it is not a
+ * `HookHandler` at all — see `src/lean-ctx/mcp.ts`'s header.
+ *
+ * This file is intentionally the *only* place that shape is defined: other
+ * agents implementing `src/hooks/user-prompt-submit/`, `src/hooks/briefing/`,
+ * and `src/hooks/crg/` code against it without needing to read `main.ts`.
+ * Keep `HookInvocation`, `HookResult`, `HookHandler`, and `payloadCwd`'s
+ * signature exactly as they are here — helpers may be added, but changing
+ * these shapes breaks every handler built against them.
+ */
+
+import type { HostId } from '../hosts/spec.ts'
+
+export type { HostId } from '../hosts/spec.ts'
+
+/**
+ * What a handler tells the activity log about one invocation (see `./log.ts`).
+ * Optional and side-channel on purpose: it never changes the `HookResult`.
+ */
+export interface ActivityNote {
+  /** `PASS`, `DENY <rule>`, `ERROR <what>`, `TIMEOUT <what>`, or `SKIP <why>`. */
+  readonly reason: string
+  readonly message?: string
+  /** What the hook invoked downstream, e.g. `lean-ctx hook redirect`, `skills: tdd, research`. */
+  readonly downstream?: string
+  /** Set only for a blocked pre-tool-use decision: the rule id written to the deny log. */
+  readonly denyRuleId?: string
+  /**
+   * Set only when an identity decision was actually made for this
+   * invocation (a rewrite, or a deny/pass decided by one of the four
+   * identity rules — `adl.session-required-for-writes`, `adl.git-identity`,
+   * `adl.token-minting-role`, `tool.azure-devops`): where the effective
+   * agent identity came from, per the one-agent-identity standard's own
+   * resolution order (STATUS.md 12p, "The
+   * standard") — `inline` (a valid `ADL_AGENT_ID_AGENT=` on the command
+   * itself), `env` (the session environment), `default-file` (the machine
+   * default-agent file), or `none` (nothing resolved at all). See
+   * `../pre-tool-use/handler.ts`'s `identitySourceFor`.
+   */
+  readonly identitySource?: 'inline' | 'env' | 'default-file' | 'none'
+  /**
+   * M8 (STATUS.md 12p): the EFFECTIVE agent
+   * identity this decision actually used — set together with
+   * `identitySource`, whenever that is set to anything but `'none'`. Read
+   * by `./log.ts` for the `agent` column INSTEAD OF the session's raw
+   * `ADL_AGENT_ID_AGENT` env var — the two differ exactly when a command
+   * carries a valid inline override naming a DIFFERENT agent than the
+   * session's own (`ADL_AGENT_ID_AGENT=agent-vivek git push …` in an
+   * agent-tarun session): the override, not the session, is the identity
+   * that actually acted, and the log's `agent` column must say so.
+   */
+  readonly identityAgent?: string
+}
+
+export interface HookInvocation {
+  readonly kind: 'pre-tool-use' | 'user-prompt-submit' | 'briefing' | 'crg' | 'lean-ctx'
+  readonly host: HostId
+  readonly event?: string
+  readonly subcommand?: string
+  readonly payload: Record<string, unknown>
+  readonly root: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  /** Activity-log side channel, set by `./log.ts`'s `runLogged`; absent in plain handler calls. */
+  readonly record?: (note: ActivityNote) => void
+}
+
+export interface HookResult {
+  readonly stdout: string
+  readonly stderr: string
+  readonly exitCode: number
+}
+
+export type HookHandler = (inv: HookInvocation) => Promise<HookResult>
+
+/**
+ * The working directory a host's hook payload carries, if any.
+ *
+ * Every host's stdin payload includes it, spelled differently:
+ *
+ *  - Claude Code, Codex, Kimi: `cwd` (string), alongside `session_id`.
+ *  - Cursor: `workspace_roots` (a string array) alongside `conversation_id`;
+ *    the first entry is the one that matters here.
+ *
+ * `main.ts` uses this (falling back to the process's own cwd when it is
+ * absent) to resolve the repository root a hook invocation applies to,
+ * rather than trusting the invoking process's own working directory — which
+ * is what makes one globally-installed hook (Kimi has no repo-local hook
+ * configuration at all) safe to run from inside any repository, controlled
+ * or not.
+ */
+export function payloadCwd(payload: Record<string, unknown>): string | undefined {
+  const cwd = payload.cwd
+  if (typeof cwd === 'string' && cwd.length > 0) return cwd
+
+  const roots = payload.workspace_roots
+  if (Array.isArray(roots)) {
+    const first = roots[0]
+    if (typeof first === 'string' && first.length > 0) return first
+  }
+
+  return undefined
+}

package/packages/agent-hooks/src/hooks/crg/handler.ts

@@ -0,0 +1,22 @@
+/**
+ * `main.ts`-facing entry point for the `crg` hook kind.
+ *
+ * Thin wiring only: `main.ts` dispatches every `HookInvocation` through one
+ * `HookHandler` shape (see `../contract.ts`) and imports this exact
+ * `handleCrg` export from this exact path — the actual crg logic
+ * (`after-file-edit` / `pre-commit` / `session-stop`, selected by
+ * `inv.subcommand`) lives in `./index.ts`, built against an injectable
+ * `Runner` so it can be unit-tested without a real `code-review-graph`
+ * binary. This file wires that logic to the production, timeout-enforcing
+ * `bunRunner` — the same shape the reference tree's `main.ts` used to wire
+ * `handleCrg` straight from `./index.ts`.
+ */
+
+import type { HookInvocation, HookResult } from '../contract.ts'
+import { bunRunner, createCrgHandler } from './index.ts'
+
+const crgHandler = createCrgHandler({ run: bunRunner })
+
+export async function handleCrg(inv: HookInvocation): Promise<HookResult> {
+  return crgHandler(inv)
+}

package/packages/agent-hooks/src/hooks/crg/index.ts

@@ -0,0 +1,209 @@
+/**
+ * The `crg` hook kind.
+ *
+ * Ports `enact-m5/.agents/hooks/crg/{after-file-edit,pre-commit,session-stop}.sh`
+ * onto the `HookHandler` contract in `../contract.ts`. `inv.subcommand`
+ * selects which of the three shell scripts this mirrors; the resolved
+ * `code-review-graph` binary comes from `PATH` (global install), exactly as
+ * the shell scripts assume by calling it unqualified.
+ *
+ * All three reference scripts share one shape: run the real command, and
+ * `|| true` past a non-zero exit rather than failing the hook — a code
+ * review graph being stale or unbuildable must never block an edit, a
+ * commit, or a session end. That is preserved verbatim here: every
+ * subcommand below always exits 0, whatever `code-review-graph` did.
+ *
+ * Two additions over the reference:
+ *  - When the binary itself cannot be found (the injected `Runner` reports
+ *    `status: null`, matching how the default runner surfaces `ENOENT`), a
+ *    stderr note names that — the shell scripts swallow it silently via
+ *    `>/dev/null 2>&1` or `2>&1` into a captured variable, per this task's
+ *    brief.
+ *  - Every spawn is timeout-enforcing (gap #1): the reference's
+ *    `Bun.spawnSync` had no timeout, so a hung `code-review-graph` child
+ *    (an embedding-model call, a huge repo scan) would block the calling
+ *    agent host forever. A timeout degrades exactly like a missing binary —
+ *    `status: null`, `timedOut: true` — so `missingBinaryNote` below already
+ *    covers it without change.
+ *
+ * `pre-commit` command detection (work item B): the reference's
+ * `pre-commit.sh` only ever ran because Cursor's own `beforeShellExecution`
+ * hook matcher (`^git\s+commit`, see `.cursor/hooks.json`) gated it — the
+ * script itself never inspected the shell command at all. `adl-extensions`
+ * now registers `adl hook crg pre-commit --host=X` on `PreToolUse` for
+ * every host (every Bash-shaped call, not just `git commit` ones), so that
+ * gating has to move into the runtime: `preCommit` below only calls
+ * `code-review-graph` when the payload's shell command actually is a `git
+ * commit` invocation (by any path — `git -C x commit`, an `env FOO=bar`
+ * prefix, a `cmd1 && git commit -m x` chain, `sudo`/`timeout`/... wrapped,
+ * ...); anything else is a silent no-op (exit 0, empty stdout, no
+ * `code-review-graph` call at all — not even the "missing binary" note,
+ * since no spawn is attempted). Detection reuses the SAME shell parser the
+ * pre-tool-use guard itself uses (`../../rules/shell/invocation.ts`'s
+ * `invocations()`, via `../../pre-tool-use/handler.ts`'s `toDecideInput` to
+ * read the command out of the host's own payload shape) rather than a
+ * bespoke regex, so it inherits that parser's robustness for free.
+ */
+
+import type { HookHandler, HookInvocation, HookResult } from '../contract.ts'
+import { spawnWithTimeout } from '../../lib/spawn-with-timeout.ts'
+import { toDecideInput } from '../../pre-tool-use/handler.ts'
+import { invocations } from '../../rules/shell/invocation.ts'
+
+export interface RunResult {
+  readonly status: number | null
+  readonly stdout: string
+  readonly stderr: string
+  /** `true` only when the spawn was killed for exceeding `timeoutMs` — see gap #1. */
+  readonly timedOut?: boolean
+}
+
+export interface RunOptions {
+  readonly cwd: string
+  readonly env: Readonly<Record<string, string | undefined>>
+  readonly input?: string
+  /** Wall-clock spawn timeout in ms; overridable per call, defaults to `DEFAULT_TIMEOUT_MS`. */
+  readonly timeoutMs?: number
+}
+
+/** Process spawning, injected so tests never need a real `code-review-graph` binary. */
+export type Runner = (cmd: string, args: readonly string[], opts: RunOptions) => Promise<RunResult>
+
+const BIN = 'code-review-graph'
+
+/**
+ * `code-review-graph` runs an incremental Tree-sitter parse plus (for
+ * `status`/`detect-changes`) a graph query — comfortably under a few
+ * seconds on a warm cache, but `update` can re-embed on a cold one. 15s
+ * gives real work headroom while still failing a hung child well within
+ * any host's own tool-call timeout.
+ */
+const DEFAULT_TIMEOUT_MS = 15_000
+
+async function runCrg(run: Runner, inv: HookInvocation, args: readonly string[]): Promise<RunResult> {
+  const result = await run(BIN, args, {
+    cwd: inv.root,
+    env: inv.env,
+    input: JSON.stringify(inv.payload),
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  })
+  const invoked = `${BIN} ${args.join(' ')}`
+  const outcome = result.timedOut ? `TIMEOUT ${invoked}` : result.status === null ? `ERROR ${invoked}` : result.status === 0 ? 'PASS' : `ERROR ${invoked} exit=${result.status}`
+  inv.record?.({ reason: outcome, message: missingBinaryNote(String(inv.subcommand), result).trim(), downstream: invoked })
+  return result
+}
+
+function missingBinaryNote(subcommand: string, result: RunResult): string {
+  if (result.status !== null) return ''
+  const reason = result.stderr.trim() || 'not found on PATH'
+  return `crg ${subcommand}: ${BIN} ${reason}\n`
+}
+
+/** `after-file-edit.sh`: silent `update --skip-flows`, stdout `{}`, always exit 0. */
+async function afterFileEdit(run: Runner, inv: HookInvocation): Promise<HookResult> {
+  const result = await runCrg(run, inv, ['update', '--skip-flows'])
+  return { stdout: '{}\n', stderr: missingBinaryNote('after-file-edit', result), exitCode: 0 }
+}
+
+/**
+ * True iff the payload's shell command (any host's own field spelling — see
+ * `toDecideInput`) is a `git commit` invocation, by any path
+ * `../../rules/shell/invocation.ts` can classify as one.
+ *
+ * For Cursor this has to read BOTH of its documented shell-command shapes
+ * (verified against https://cursor.com/docs/agent/hooks, this session,
+ * 2026-09-14) — a `preToolUse` Shell call's `tool_input.command`, and a
+ * `beforeShellExecution` call's top-level `command` — which `toDecideInput`
+ * already handles generically; see that function's own doc comment for the
+ * exact payload shapes quoted from the docs.
+ */
+function isGitCommitInvocation(payload: Record<string, unknown>): boolean {
+  const input = toDecideInput(payload)
+  if (input === null || input.kind !== 'command') return false
+  return invocations(input.command).some((inv) => inv.kind === 'git' && inv.subcommand === 'commit')
+}
+
+/**
+ * `pre-commit.sh`: silent `detect-changes --brief`, stdout `{"passed":true}`,
+ * always exit 0 — but ONLY when the invoking payload's shell command is
+ * actually a `git commit` (see this file's header, work item B). Anything
+ * else — no shell command at all (a non-Bash tool call), or a shell command
+ * that is not `git commit` — is a silent no-op: exit 0, empty stdout, no
+ * `code-review-graph` call attempted at all.
+ */
+async function preCommit(run: Runner, inv: HookInvocation): Promise<HookResult> {
+  if (!isGitCommitInvocation(inv.payload)) {
+    inv.record?.({ reason: 'SKIP not a git commit' })
+    return { stdout: '', stderr: '', exitCode: 0 }
+  }
+  const result = await runCrg(run, inv, ['detect-changes', '--brief'])
+  return { stdout: '{"passed":true}\n', stderr: missingBinaryNote('pre-commit', result), exitCode: 0 }
+}
+
+/**
+ * `session-stop.sh`: `status`, wrapped as `{"message": ..., "passed": true}`.
+ * On failure (including a missing binary or a timeout) the message falls
+ * back to "graph not built — run: crg build", exactly as the reference
+ * script's own
+ * `output="$(code-review-graph status 2>&1)" || output="graph not built — run: crg build"`.
+ */
+async function sessionStop(run: Runner, inv: HookInvocation): Promise<HookResult> {
+  const result = await runCrg(run, inv, ['status'])
+  const note = missingBinaryNote('session-stop', result)
+  const combined = `${result.stdout}${result.stderr}`.trim()
+  const body = result.status === 0 && combined ? combined : 'graph not built — run: crg build'
+  const message = `${body}\n\nCRG MCP: get_minimal_context_tool first; CLI: crg query …`
+  return { stdout: `${JSON.stringify({ message, passed: true })}\n`, stderr: note, exitCode: 0 }
+}
+
+export function createCrgHandler(deps: { run: Runner }): HookHandler {
+  return async (inv: HookInvocation): Promise<HookResult> => {
+    switch (inv.subcommand) {
+      case 'after-file-edit':
+        return afterFileEdit(deps.run, inv)
+      case 'pre-commit':
+        return preCommit(deps.run, inv)
+      case 'session-stop':
+        return sessionStop(deps.run, inv)
+      default:
+        return {
+          stdout: '',
+          stderr: `crg: unknown subcommand: ${String(inv.subcommand)} (expected after-file-edit | pre-commit | session-stop)\n`,
+          exitCode: 2,
+        }
+    }
+  }
+}
+
+/**
+ * The production `Runner`: a real, timeout-enforcing subprocess via
+ * `spawnWithTimeout` (see `../../lib/spawn-with-timeout.ts`), resolving
+ * `code-review-graph` off `PATH`. Replaces the reference tree's
+ * `Bun.spawnSync`, which had no timeout (gap #1).
+ */
+export const bunRunner: Runner = async (cmd, args, opts) => {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  try {
+    const result = await spawnWithTimeout(cmd, args, {
+      cwd: opts.cwd,
+      env: opts.env,
+      timeoutMs,
+      ...(opts.input !== undefined ? { stdin: opts.input } : {}),
+    })
+    if (result.timedOut) {
+      return {
+        status: null,
+        stdout: result.stdout,
+        stderr: result.stderr.trim() || `${cmd} timed out after ${timeoutMs}ms`,
+        timedOut: true,
+      }
+    }
+    return { status: result.exitCode, stdout: result.stdout, stderr: result.stderr }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { status: null, stdout: '', stderr: message }
+  }
+}
+
+export const handleCrg: HookHandler = createCrgHandler({ run: bunRunner })
+export default handleCrg