@mutmutco/claude-plugin 3.131.0

package/scripts/hook-run.mjs

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+// Shared hook process core. Every active host calls this runner with only its surface token and a
+// policy gate id. Host-specific event/tool matching stays in the adapter; policy and failure behavior
+// stay here.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { hookGate, hookSurface } from './hook-policy.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// #4118: every fire used to be THREE process boots — launcher, this runner, then a SECOND node for the
+// gate script. The gate is ordinary ESM in the same tree, so it is imported here instead; measured
+// against the live 4,002-fire log that second boot was ~70ms of the ~226ms median, on every fire of
+// all three gates. The gate's own logic was 10-25ms of it.
+//
+// Losing the child process also loses the isolation it provided, so the boundary is rebuilt explicitly
+// and the five things the spawn used to guarantee are each restored by hand:
+//   - stdout/stderr are captured (the child's pipes) rather than reaching the host raw, and the
+//     captured stdout is then REDUCED to the one decision envelope before it leaves this runner (see
+//     decisionEnvelope below — capture alone never bought that, and did not on base either: an injected
+//     `process.stdout.write` inside a gate reaches the host ahead of the deny, byte-identical spawned or
+//     imported, and the host's JSON.parse fails on the stream). What is guaranteed is narrower than "a
+//     stray write can never be read as a decision": stdout that cannot be reduced to exactly ONE decision
+//     envelope is not forwarded at all, and on a fail-closed gate that is a gate FAULT (#4016) — the
+//     fallback deny runs. So on a gate's DENY path a stray write can suppress the gate's own answer (the
+//     fallback's reason replaces it) but cannot weaken the outcome. On a gate's ALLOW path it is not
+//     contained: with no carrier of the gate's own to outrank it, a stray write carrying a well-formed
+//     allow envelope is elected and forwarded, turning "no decision, defer to the host's prompt" into an
+//     explicit auto-approve — measured, and unchanged from base and from 8730324a, so this is the shape
+//     #4016 did NOT close. Measured on vault-edit and command-ladder, all ten fault
+//     shapes in the #4016 matrix deny, and four consecutive fires of the unterminated-stray shape all deny
+//     — the gate still records its own success, so that shape never reaches the #2598 breaker threshold.
+//     The breaker is otherwise unchanged: three consecutive GENUINE crashes still degrade fail-open behind
+//     its warning banner;
+//   - process.exit is trapped (the child's exit code) so a gate that exits mid-run yields a STATUS
+//     instead of taking the whole hook process — and with it the fail-closed fallback — down with it;
+//   - unhandled rejections and uncaught exceptions are trapped for the same reason: those are the two
+//     faults an `await` cannot see, and untrapped they kill the RUNNER (see trapAsyncFaults below);
+//   - process.env is set to the gate's effective env before the import, because the gates read
+//     surface-dependent modes at MODULE LOAD, and restored after;
+//   - the import is cache-busted per fire so a second run in one process re-reads those module-level
+//     constants exactly as a fresh child would.
+// Anything that escapes all of that lands in the catch as status 1, which is the same signal a crashed
+// child gave: fail-CLOSED for command-ladder and vault-edit (deny-gate-crash.mjs), fail-open for
+// secret-output. See scripts/hook-policy.mjs for the per-gate posture.
+let fireCount = 0;
+
+/** Thrown in place of a gate's process.exit so the runner keeps ownership of the exit code. */
+class GateExit extends Error {
+  constructor(code) {
+    super(`gate exited ${code}`);
+    this.code = code;
+  }
+}
+
+export function parseHookArgv(argv) {
+  const parsed = { surface: '', gate: '' };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--surface') parsed.surface = argv[++index] ?? '';
+    else if (argv[index] === '--gate') parsed.gate = argv[++index] ?? '';
+  }
+  return parsed;
+}
+
+export function pluginRoot(surfaceToken, env = process.env, here = HERE) {
+  const surface = hookSurface(surfaceToken);
+  for (const name of surface.rootEnv) {
+    const candidate = env[name];
+    if (candidate && existsSync(join(candidate, 'scripts', 'hook-policy.mjs'))) return resolve(candidate);
+  }
+  return resolve(here, '..');
+}
+
+export function payloadMeta(input) {
+  try {
+    const payload = JSON.parse(Buffer.from(input).toString('utf8'));
+    return {
+      sessionId: typeof payload?.session_id === 'string' ? payload.session_id : '',
+      cwd: typeof payload?.cwd === 'string' ? payload.cwd : '',
+    };
+  } catch {
+    return { sessionId: '', cwd: '' };
+  }
+}
+
+/** Codex's spelling of the one shell tool. The redactor's UPDATABLE_TOOLS is the Claude vocabulary, so
+ *  the secret-output matcher can only equal it once the host name is translated — untranslated, a Codex
+ *  `shell` detection took the "cannot be masked for this TOOL" arm and blamed the tool for what is a
+ *  HOST limit (#4118). Translated for secret-output ONLY: the PreToolUse shell gates match these names
+ *  directly and pick a dialect from them (scripts/pretooluse-shell-gates.mjs). */
+export const CODEX_SHELL_TOOLS = Object.freeze(['shell', 'local_shell']);
+
+function normalizeInput(surface, gate, input) {
+  const codexShell = surface === 'codex' && gate === 'secret-output';
+  if (surface !== 'cursor' && !codexShell) return input;
+  try {
+    const payload = JSON.parse(Buffer.from(input).toString('utf8'));
+    if (!payload || typeof payload !== 'object') return input;
+    if (payload.tool_name === 'Shell' || (codexShell && CODEX_SHELL_TOOLS.includes(payload.tool_name))) {
+      // Keep the name the HOST fired for the trace to read back. Translated-only, activity.jsonl logged
+      // BOTH Codex spellings as `tool: "PowerShell"` — a tool Codex does not have, and the two names
+      // became indistinguishable in the one log doctor, the Stop summary and this gate's own
+      // justification are counted from. secret-redact.mjs prefers this field when stamping `tool`.
+      payload.mmi_host_tool_name = payload.tool_name;
+      payload.tool_name = process.platform === 'win32' ? 'PowerShell' : 'Bash';
+    }
+    if (surface !== 'cursor') return Buffer.from(JSON.stringify(payload));
+    if (!payload.session_id && typeof payload.conversation_id === 'string') {
+      payload.session_id = payload.conversation_id;
+    }
+    if (gate === 'secret-output' && payload.tool_response == null && payload.tool_output != null) {
+      payload.tool_response = payload.tool_output;
+    }
+    return Buffer.from(JSON.stringify(payload));
+  } catch {
+    return input;
+  }
+}
+
+/** Split a gate's stdout into the ONE decision envelope and everything else. Every gate writes at most
+ *  one envelope and always as a single line of JSON (pretooluse-shell-gates.mjs, vault-edit-gate.mjs,
+ *  secret-redact.mjs) — the same shape .kilo-plugin/server.mjs already reads back off this launcher.
+ *  Stray text is moved to stderr rather than dropped: still a symptom worth seeing, just not somewhere a
+ *  decision can be read from.
+ *
+ *  #4016: "the first line beginning with `{`" was the wrong test and measurably fails OPEN on a
+ *  fail-CLOSED gate in two shapes. With a `.env` Write driven through vault-edit and the write injected at
+ *  the gate entry: a stray line that is ITSELF JSON (`{"mmi_debug":"noise"}`) was elected the envelope and
+ *  the real deny went to stderr — the host then parses a well-formed NON-decision and allows, which base
+ *  could not do because base's stream did not parse at all; and a stray write with no trailing newline
+ *  merges with the envelope into one line that starts with `h`, so no line matched, stdout came back EMPTY
+ *  and the deny was gone. So the line is elected by PARSING it, `hookSpecificOutput` carriers first, and
+ *  the result reports `malformed` when stdout exists but cannot be reduced to exactly one — which
+ *  runPolicyGate treats as a gate fault, i.e. the fail-closed fallback for vault-edit/command-ladder. */
+export function decisionEnvelope(stdout) {
+  if (!stdout.trim()) return { envelope: '', stray: '', malformed: false };
+  const lines = stdout.split(/\r?\n/);
+  const objects = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    let value;
+    try {
+      value = JSON.parse(lines[index]);
+    } catch {
+      continue;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) objects.push({ index, value });
+  }
+  const carriers = objects.filter(({ value }) => value.hookSpecificOutput !== undefined);
+  const candidates = carriers.length ? carriers : objects;
+  if (candidates.length !== 1) return { envelope: '', stray: stdout, malformed: true };
+  const at = candidates[0].index;
+  const stray = lines.filter((_, index) => index !== at).join('\n').trim();
+  return { envelope: `${lines[at]}\n`, stray: stray ? `${stray}\n` : '', malformed: false };
+}
+
+function adaptOutput(surface, stdout) {
+  if (surface !== 'cursor') return stdout;
+  // Jerv-PowerTools #4751: cursor's preToolUse entries carry failClosed:true, and cursor reads
+  // EMPTY stdout as a hook FAILURE — so the gates' clean-allow contract (exit 0, no envelope)
+  // denied every Shell and Write on the surface. `{}` is cursor's documented intentional no-op
+  // (staff guidance in the fail-closed report thread), and on cursor only `deny` overrides the
+  // host's own permission flow — so this defers exactly like empty stdout does on other surfaces.
+  if (!stdout.trim()) return '{}\n';
+  try {
+    const payload = JSON.parse(stdout);
+    const decision = payload?.hookSpecificOutput;
+    // #4331: a gate that DECIDES anything other than deny must still leave cursor a parseable envelope.
+    // #4300 fixed the no-envelope path and stopped here, so an explicit `allow`/`ask` envelope still
+    // adapted to EMPTY stdout — the exact byte stream cursor's failClosed reader grades as a hook
+    // failure, denying the call the gate had just passed. Same no-op as the empty case: `{}` is
+    // cursor's documented "no decision, defer to the host". It must NOT become `permission: 'allow'`
+    // — on cursor only an explicit decision overrides the host's own permission flow, so that would
+    // auto-approve calls the user would otherwise be prompted for. Deny stays byte-identical below.
+    if (decision?.permissionDecision !== 'deny') return '{}\n';
+    const reason = decision.permissionDecisionReason || 'MMI policy denied this tool call.';
+    return `${JSON.stringify({ permission: 'deny', user_message: reason, agent_message: reason })}\n`;
+  } catch {
+    return stdout;
+  }
+}
+
+function childEnv(surface, input, env) {
+  const meta = payloadMeta(input);
+  return {
+    ...env,
+    MMI_HOOK_SURFACE: surface,
+    ...(meta.sessionId && !env.MMI_GATE_SESSION_ID ? { MMI_GATE_SESSION_ID: meta.sessionId } : {}),
+    ...(meta.cwd && !env.MMI_HOOK_ACTIVITY_CWD ? { MMI_HOOK_ACTIVITY_CWD: meta.cwd } : {}),
+  };
+}
+
+function inlineDeny(surface, gate, root, fault = `its fail-closed fallback is missing from the plugin install at ${root}`) {
+  return `${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: `MMI ${gate} gate could not run on ${surface} and ${fault}. Reinstall the MMI plugin, or set MMI_GATES_FAIL_OPEN=1 to proceed unguarded.`,
+    },
+  })}\n`;
+}
+
+function invoke(target, args, input, env, timeoutMs) {
+  const result = spawnSync(process.execPath, [target, ...args], {
+    input,
+    encoding: 'utf8',
+    env,
+    timeout: timeoutMs,
+    windowsHide: true,
+  });
+  return {
+    status: result.status ?? 1,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    error: result.error,
+  };
+}
+
+/** Point process.env at the gate's effective env for one in-process run, then put it back. */
+function applyProcessEnv(env) {
+  if (env === process.env) return () => {};
+  const prior = { ...process.env };
+  const sync = (target) => {
+    for (const key of Object.keys(process.env)) if (!(key in target)) delete process.env[key];
+    for (const [key, value] of Object.entries(target)) {
+      if (value === undefined) delete process.env[key];
+      else if (process.env[key] !== value) process.env[key] = value;
+    }
+  };
+  sync(env);
+  return () => sync(prior);
+}
+
+/** Buffer everything the gate writes, the way the child's pipes used to. */
+function captureStdio() {
+  const chunks = { stdout: [], stderr: [] };
+  const prior = { stdout: process.stdout.write, stderr: process.stderr.write };
+  const sink = (name) => function write(chunk, encoding, callback) {
+    chunks[name].push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    const done = typeof encoding === 'function' ? encoding : callback;
+    if (typeof done === 'function') done();
+    return true;
+  };
+  process.stdout.write = sink('stdout');
+  process.stderr.write = sink('stderr');
+  return () => {
+    process.stdout.write = prior.stdout;
+    process.stderr.write = prior.stderr;
+    return { stdout: chunks.stdout.join(''), stderr: chunks.stderr.join('') };
+  };
+}
+
+/** The child's `timeout` option: a gate that never settles must not hold the turn open. The timer is
+ *  deliberately NOT unref'd — an unref'd timer lets the event loop drain when the gate settles nothing
+ *  and holds no handle, and the runner then exits 0 with no output, which is fail-OPEN. clearTimeout in
+ *  the `finally` is what keeps it from holding the loop open on the ordinary path. */
+function withTimeout(promise, timeoutMs) {
+  if (!timeoutMs) return promise;
+  return new Promise((settle, fail) => {
+    const timer = setTimeout(() => fail(new Error(`gate exceeded ${timeoutMs}ms`)), timeoutMs);
+    promise.then(settle, fail).finally(() => clearTimeout(timer));
+  });
+}
+
+/**
+ * The child process absorbed a gate's ASYNC faults — a detached rejection or a throw from a timer
+ * crashed the child, the runner read status 1, and the fail-closed fallback ran. In-process those two
+ * faults reach the runner's own default handler and kill it: measured against 1326c2db, a detached
+ * rejection inside vault-edit-gate left the runner at exit 1 with NO stdout, and a hook that exits 1
+ * is a non-blocking error on Claude Code, so the tool call proceeds unguarded. `await` cannot see
+ * either fault, so the only place to catch them is the process handlers, for the length of the run.
+ * Prior handlers are saved and restored: a host that embeds runPolicyGate keeps its own.
+ */
+function trapAsyncFaults() {
+  let onFault = () => {};
+  const fault = new Promise((_, fail) => {
+    onFault = (err) => fail(err instanceof Error ? err : new Error(String(err)));
+  });
+  // A fault that lands after the gate already settled has nothing racing it; swallow it here rather
+  // than let the rejection this function created become the next unhandled rejection.
+  fault.catch(() => {});
+  const prior = {
+    unhandledRejection: process.rawListeners('unhandledRejection'),
+    uncaughtException: process.rawListeners('uncaughtException'),
+  };
+  for (const event of Object.keys(prior)) {
+    process.removeAllListeners(event);
+    process.on(event, onFault);
+  }
+  return {
+    fault,
+    release() {
+      for (const [event, listeners] of Object.entries(prior)) {
+        process.removeAllListeners(event);
+        for (const listener of listeners) process.on(event, listener);
+      }
+    },
+  };
+}
+
+async function invokeInProcess(target, input, env, timeoutMs) {
+  const restoreEnv = applyProcessEnv(env);
+  const drain = captureStdio();
+  const faults = trapAsyncFaults();
+  const priorExit = process.exit;
+  process.exit = (code) => {
+    throw new GateExit(typeof code === 'number' ? code : 0);
+  };
+  let status = 0;
+  let error;
+  let legacy = false;
+  try {
+    const gateModule = await Promise.race([
+      faults.fault,
+      import(`${pathToFileURL(target).href}?mmi-hook-fire=${(fireCount += 1)}`),
+    ]);
+    // A gate from before #4118 is still a runnable script with its own self-run guard. Treating the
+    // missing export as a crash made every Edit/Write/Bash deny under the version skew the plugin's
+    // own `upgrade.mechanism: reinstall` creates (installed cache older than the tree); the spawn is
+    // the compatibility path, not a fallback for failure.
+    if (typeof gateModule.runHookGate !== 'function') legacy = true;
+    else await withTimeout(Promise.race([faults.fault, gateModule.runHookGate({ input })]), timeoutMs);
+  } catch (err) {
+    if (err instanceof GateExit) status = err.code;
+    else {
+      status = 1;
+      error = err;
+    }
+  } finally {
+    process.exit = priorExit;
+    faults.release();
+  }
+  const { stdout, stderr } = drain();
+  restoreEnv();
+  return { status, stdout, stderr, error, legacy };
+}
+
+export async function runPolicyGate({ surface, gate: gateId, input = Buffer.alloc(0), env = process.env, here = HERE }) {
+  const gate = hookGate(gateId);
+  hookSurface(surface);
+  const root = pluginRoot(surface, env, here);
+  const target = join(root, 'scripts', gate.script);
+  const normalizedInput = normalizeInput(surface, gateId, stripUtf8Bom(input));
+  const effectiveEnv = childEnv(surface, normalizedInput, env);
+  let result;
+
+  if (!existsSync(target)) {
+    result = { status: 1, stdout: '', stderr: `[mmi-${surface}-hook] ${gate.script} not found under ${root}\n` };
+  } else {
+    result = await invokeInProcess(target, normalizedInput, effectiveEnv, gate.timeoutMs);
+    if (result.legacy) result = invoke(target, [], normalizedInput, effectiveEnv, gate.timeoutMs);
+    if (result.status === 0 || result.status === 2) {
+      const { envelope, stray, malformed } = decisionEnvelope(result.stdout);
+      if (!malformed) {
+        return { ...result, stdout: adaptOutput(surface, envelope), stderr: `${result.stderr}${stray}` };
+      }
+      // #4016: the gate exited cleanly but its stdout does not reduce to one decision. The runner cannot
+      // tell "allowed, then printed junk" from "denied, and the deny got mangled" — the second is exactly
+      // what an unterminated stray write produces — so this is a gate fault, not an allow.
+      result = { ...result, status: 1, stdout: '', stderr: `${result.stderr}${stray}` };
+      result.stderr += `[mmi-${surface}-hook] ${gate.script} wrote stdout with no single decision envelope\n`;
+    } else {
+      result.stderr += `[mmi-${surface}-hook] ${gate.script} exited ${result.status}`;
+      result.stderr += result.error ? `: ${result.error.message}\n` : '\n';
+    }
+  }
+
+  if (gate.failure === 'open') return { ...result, status: 0 };
+
+  // The fallback deliberately keeps its own process. Whatever just failed did so INSIDE this one, so a
+  // fail-closed deny must not be computed by the same module registry and globals that produced it.
+  const crashGate = join(root, 'scripts', 'deny-gate-crash.mjs');
+  if (!existsSync(crashGate)) {
+    return { status: 0, stdout: inlineDeny(surface, gate.fallbackGate, root), stderr: result.stderr };
+  }
+  const fallback = invoke(crashGate, [gate.fallbackGate], normalizedInput, effectiveEnv, gate.timeoutMs);
+  const { envelope, stray, malformed } = decisionEnvelope(fallback.stdout);
+  // An EMPTY fallback stdout is intentional (breaker open, or MMI_GATES_FAIL_OPEN) and stays empty;
+  // `malformed` is the other case — the fallback itself emitted something unreadable — and that must not
+  // become an allow either (#4016).
+  if (malformed) {
+    return {
+      status: 0,
+      stdout: inlineDeny(surface, gate.fallbackGate, root, 'its fail-closed fallback wrote no readable decision'),
+      stderr: `${result.stderr}${fallback.stderr}${stray}`,
+    };
+  }
+  return {
+    ...fallback,
+    stdout: adaptOutput(surface, envelope),
+    stderr: `${result.stderr}${fallback.stderr}${stray}`,
+  };
+}
+
+/** #4878: Cursor's Windows payload transport pipes the hook payload through PowerShell with
+ *  `$OutputEncoding = [System.Text.Encoding]::UTF8` — the BOM-EMITTING encoder — so the JSON arrives
+ *  prefixed with EF BB BF. JSON.parse refuses a BOM, every parse in this chain (normalizeInput,
+ *  payloadMeta, the gate scripts) came back empty, and the fail-open no-payload arm (#2992) silently
+ *  waved the call through. Stripped once at the gate entry so every consumer parses the same bytes. */
+function stripUtf8Bom(input) {
+  const buffer = Buffer.from(input);
+  return buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf ? buffer.subarray(3) : buffer;
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const { surface, gate } = parseHookArgv(argv);
+  let result;
+  try {
+    result = await runPolicyGate({ surface, gate, input: readStdin() });
+  } catch (error) {
+    process.stderr.write(`[mmi-hook] ${error.message}\n`);
+    process.exit(1);
+  }
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exit(result.status);
+}
+
+// Codex may import this file from a replacement cache while process.argv[1] still names the deleted
+// cache path captured when the session loaded. Match the stable relative suffix, not URL identity.
+if (process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('scripts/hook-run.mjs')) {
+  main().catch((error) => {
+    process.stderr.write(`[mmi-hook] ${error && error.message}\n`);
+    process.exit(1);
+  });
+}

package/scripts/hook-trace.mjs

@@ -0,0 +1,151 @@
+// Uniform greppable hook-activity log (#2599). Every hook invocation appends ONE line so a
+// user/agent can see "what just ran" (ran / healed X / denied Y / failed Z) and a recurring silent
+// failure is grep-discoverable. This generalizes the per-hook trace pattern that lived only in
+// shell-redirect-lint.mjs into one shared mechanism every hook reuses (epic #2589 transparency lane).
+//
+// Format: one JSONL line per invocation with stable keys —
+//   { "ts","surface","event","script","outcome","action", ... }
+// outcome vocabulary: "ran" (pass-through) | "deny" (blocked) | "heal" (transformed output) |
+//   "observe" (would-block, observe mode) | "bypass" (escape hatch used) | "failed" (hook errored).
+//
+// Path: repo-local gitignored state (.git/mmi-runtime/hooks/activity.jsonl — never tracked); falls
+// back to a per-cwd tmpdir path outside a repo so the trace still works anywhere. Fail-soft always:
+// the trace must never crash a turn or block a tool call.
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const DEFAULT_SURFACE = 'claude';
+
+// #3642: four hooks append on every tool call and nothing ever pruned, so the trace reached 17 MB on
+// the Hub checkout — in `.git/`, so invisible to `git status` and to every worktree/scratch sweep.
+// Trim on append: past MAX_BYTES, keep the last KEEP_BYTES. KEEP sits above the 512 KB tail the
+// doctor's redactor-liveness probe reads (cli/src/hook-activity.ts), so trimming never shortens the
+// window a reader sees. MAX is high enough that the read-rewrite happens once every few weeks.
+// The CLI mirror in cli/src/hook-activity.ts deliberately has no copy of this: with the SessionStart
+// hook retired (#3630) it writes at most a row a session, and the bound is a property of the FILE —
+// whoever appends next enforces it, and that is effectively always this writer.
+const MAX_BYTES = 4 * 1024 * 1024;
+const KEEP_BYTES = 1024 * 1024;
+
+/**
+ * Drop the oldest rows once the log passes MAX_BYTES, keeping the last KEEP_BYTES from the first
+ * line boundary (a byte-slice would leave a torn row at the head). Fail-soft: a trim that cannot
+ * run leaves the log as it is rather than losing the append behind it.
+ *
+ * @param {string} path
+ * @returns {void}
+ */
+function trimIfOversized(path) {
+  try {
+    if (statSync(path).size <= MAX_BYTES) return;
+    const tail = readFileSync(path, 'utf8').slice(-KEEP_BYTES);
+    const firstBreak = tail.indexOf('\n');
+    writeFileSync(path, firstBreak === -1 ? '' : tail.slice(firstBreak + 1), 'utf8');
+  } catch {
+    /* no log yet, or an unreadable one — the append below is still worth attempting */
+  }
+}
+
+function fallbackPath(cwd) {
+  const hash = createHash('sha256').update(resolve(cwd)).digest('hex').slice(0, 16);
+  return join(tmpdir(), 'mmi-cli', hash, 'hooks', 'activity.jsonl');
+}
+
+// #4118: resolving the repo-local path used to shell out to `git rev-parse --git-path` — a fresh
+// process on EVERY hook fire, 4,002 of them in the sampled window, so memoising inside the process
+// would have saved nothing. Re-measured with the exact call it replaced, 25 samples in each of three
+// checkouts: median 24.4/25.2/27.3ms, max 48.3/49.0/51.3ms. (An earlier note here quoted the ~49ms tail
+// as the per-fire rate; it is roughly twice the median.) The answer is a pure function of the .git
+// layout, so it is read off the filesystem instead. This is the resolution cli/src/repo-runtime-state.ts
+// already performs for the CLI half of the same log; the two mirrors now agree by construction rather
+// than by two different mechanisms happening to land on the same path.
+//
+// Two layouts, both of which `--git-path` answers identically: a `.git` DIRECTORY (ordinary checkout),
+// and a `.git` FILE naming a private gitdir (a linked worktree — this org's normal working state —
+// or a submodule, where the named path may be relative). Unlike the CLI mirror this walks UP, because a
+// hook's cwd is the session's cwd and may sit below the repo root. A bare repo, where the cwd IS the
+// gitdir, is not resolved: hooks do not run there, and the tmpdir fallback below still gives a log.
+const GIT_DIR_MEMO = new Map();
+
+function gitDir(cwd, env) {
+  if (env.GIT_DIR) return resolve(cwd, env.GIT_DIR);
+  if (GIT_DIR_MEMO.has(cwd)) return GIT_DIR_MEMO.get(cwd);
+  let dir = resolve(cwd);
+  let found = '';
+  for (;;) {
+    const dotGit = join(dir, '.git');
+    let stats;
+    try {
+      stats = statSync(dotGit);
+    } catch {
+      stats = null;
+    }
+    if (stats?.isDirectory()) {
+      found = dotGit;
+      break;
+    }
+    if (stats?.isFile()) {
+      try {
+        const named = /^gitdir:\s*(.+)$/im.exec(readFileSync(dotGit, 'utf8').trim())?.[1]?.trim();
+        if (named) found = isAbsolute(named) ? named : resolve(dir, named);
+      } catch {
+        /* unreadable .git file — fall through to the tmpdir fallback */
+      }
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  GIT_DIR_MEMO.set(cwd, found);
+  return found;
+}
+
+/**
+ * Resolve the hook-activity log path for a working directory.
+ * Prefers the repo-local gitignored state dir (`.git/mmi-runtime/hooks/activity.jsonl`, resolved from
+ * the .git layout by `gitDir` above); falls back to a per-cwd tmpdir path so the trace still works
+ * outside a repo. Env overrides: `MMI_HOOK_ACTIVITY_LOG` (full path, wins outright) and
+ * `MMI_HOOK_ACTIVITY_CWD` (resolve against this directory instead of the hook process's own cwd —
+ * the Kimi launcher stamps it from the hook payload because Kimi runs plugin hooks with cwd = the
+ * plugin root, which is not a repo).
+ *
+ * @param {string} [cwd]
+ * @param {Record<string,string|undefined>} [env]
+ * @returns {string}
+ */
+export function activityLogPath(cwd = process.cwd(), env = process.env) {
+  if (env.MMI_HOOK_ACTIVITY_LOG) return env.MMI_HOOK_ACTIVITY_LOG;
+  const effectiveCwd = env.MMI_HOOK_ACTIVITY_CWD || cwd;
+  const dir = gitDir(effectiveCwd, env);
+  if (dir && existsSync(dir)) return join(dir, 'mmi-runtime', 'hooks', 'activity.jsonl');
+  return fallbackPath(effectiveCwd);
+}
+
+/**
+ * Append one hook-activity line. Fail-soft: any IO error is swallowed (the trace must never crash a
+ * turn). `ts` is stamped and `surface` defaulted when absent.
+ *
+ * @param {{ surface?: string, event: string, script: string, outcome: string, action?: string, [k: string]: unknown }} entry
+ * @param {{ cwd?: string, env?: Record<string,string|undefined> }} [opts]
+ * @returns {void}
+ */
+export function appendHookActivity(entry, opts = {}) {
+  try {
+    const path = activityLogPath(opts.cwd, opts.env);
+    const line = {
+      ts: new Date().toISOString(),
+      // #3563: the same scripts now run under Codex too, and a Codex deny logged as `surface: "claude"`
+      // sends anyone reading the trace to the wrong manifest. The Codex launcher sets MMI_HOOK_SURFACE.
+      surface: (opts.env ?? process.env).MMI_HOOK_SURFACE || DEFAULT_SURFACE,
+      ...entry,
+    };
+    mkdirSync(dirname(path), { recursive: true });
+    trimIfOversized(path);
+    appendFileSync(path, `${JSON.stringify(line)}\n`, 'utf8');
+  } catch {
+    /* fail-soft — never crash a turn for the trace */
+  }
+}