@mutmutco/codex-plugin 3.131.0

package/scripts/deny-gate-crash.mjs

@@ -0,0 +1,179 @@
+// Shared fail-closed crash path for PreToolUse deny gates (#2598).
+// Advisory hooks stay fail-open; this file is only for command-ladder/vault gates.
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readHookInput } from './hook-io.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+const THRESHOLD = 3;
+const ESCAPE_HATCH = 'MMI_GATES_FAIL_OPEN=1';
+
+/** A bypass env var is on for any value except unset / empty / `0` / `false` / `no` / `off`. */
+export function isFailOpenOn(value) {
+  if (value === undefined || value === null) return false;
+  const v = String(value).trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+
+function safeId(value) {
+  return createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+}
+
+function sessionId(env) {
+  // Fallback is cwd only — never ppid (#2992). Each hook invocation spawns through a fresh
+  // intermediate shell, so a ppid-keyed counter wrote a new state file per crash and the #2598
+  // breaker could never reach its threshold (permanently "Crash 1/3").
+  //
+  // #3591: `CLAUDE_CODE_SESSION_ID` is the name Claude Code actually exports; `CLAUDE_SESSION_ID`
+  // never resolved, so every Claude Code session fell straight through to the cwd fallback. That is
+  // not merely a weaker key, it is the WRONG one in both directions: two sessions working the same
+  // checkout shared one crash counter (one session's crashes trip the other's breaker), while one
+  // session moving between two checkouts got two counters and could never reach the threshold — the
+  // exact failure #2992 fixed for ppid, reintroduced through a name that does not exist.
+  return env.MMI_GATE_SESSION_ID || env.CLAUDE_SESSION_ID || env.CLAUDE_CODE_SESSION_ID || process.cwd();
+}
+
+function statePath(gateName, env) {
+  const root = env.MMI_GATE_STATE_DIR || join(tmpdir(), 'mmi-gate-crashes');
+  try {
+    mkdirSync(root, { recursive: true });
+  } catch {
+    return null;
+  }
+  return join(root, `${gateName}-${safeId(sessionId(env))}.json`);
+}
+
+function readState(path) {
+  if (!path) return { crashes: 0 };
+  if (!existsSync(path)) return { crashes: 0 };
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    return { crashes: Number.isInteger(state.crashes) ? state.crashes : 0 };
+  } catch {
+    return { crashes: 0 };
+  }
+}
+
+function writeState(path, state) {
+  if (!path) return;
+  try {
+    writeFileSync(path, JSON.stringify(state), 'utf8');
+  } catch {
+    // Keep the crash path non-crashing; fail-closed without persistent breaker state.
+  }
+}
+
+export function gateCrashReason(gateName, crashes) {
+  return (
+    `${gateName} gate crashed — re-run or set escape hatch ${ESCAPE_HATCH}. ` +
+    `Crash ${crashes}/${THRESHOLD}; after ${THRESHOLD} consecutive crashes this gate degrades fail-open with a warning banner.`
+  );
+}
+
+export function gateBreakerWarning(gateName, crashes) {
+  return (
+    `[mmi-hook] ${gateName} gate circuit breaker open after ${crashes} consecutive crashes — ` +
+    `failing open with degraded protection visible. Re-run after fixing the gate, or set ${ESCAPE_HATCH} for an explicit per-session escape hatch.\n`
+  );
+}
+
+export function gateEscapeWarning(gateName) {
+  return `[mmi-hook] ${gateName} gate crashed; ${ESCAPE_HATCH} is set — failing open for this session.\n`;
+}
+
+export function denyDecision(reason) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
+export function missingInputWarning(gateName) {
+  return (
+    `[mmi-hook] ${gateName} gate: no readable Claude hook payload on stdin — ` +
+    `gate not evaluated on this host; failing open (#2992).\n`
+  );
+}
+
+/** Out-of-contract invocation (#2992): stdin carried no readable Claude hook payload. The gates speak
+ *  the Claude payload shape (which Kimi also delivers verbatim); a host that runs the hook without
+ *  delivering it (Cursor's Claude-plugin import) gets a fail-open skip, not a fail-closed deny — whoever controls stdin
+ *  already controls the MMI_GATES_FAIL_OPEN env hatch, so denying here adds no protection and
+ *  permanently bricks the foreign host. Not counted as a crash: the breaker stays reserved for
+ *  genuine gate failures on a valid payload. */
+export function handleMissingHookInput(gateName) {
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: gateName,
+    outcome: 'skipped',
+    action: 'no readable Claude hook payload on stdin; gate fails open (#2992)',
+  });
+  return { stdout: '', stderr: missingInputWarning(gateName), degraded: false, crashes: 0 };
+}
+
+export function recordGateSuccess(gateName, env = process.env) {
+  const path = statePath(gateName, env);
+  writeState(path, { crashes: 0 });
+}
+
+export function handleGateCrash(gateName, env = process.env) {
+  if (isFailOpenOn(env.MMI_GATES_FAIL_OPEN)) {
+    appendHookActivity({
+      event: 'PreToolUse',
+      script: gateName,
+      outcome: 'failed',
+      action: `gate crashed; failing open (${ESCAPE_HATCH} set)`,
+    });
+    return { stdout: '', stderr: gateEscapeWarning(gateName), degraded: true, crashes: 0 };
+  }
+
+  const path = statePath(gateName, env);
+  const state = readState(path);
+  const crashes = state.crashes + 1;
+  writeState(path, { crashes });
+
+  if (crashes >= THRESHOLD) {
+    appendHookActivity({
+      event: 'PreToolUse',
+      script: gateName,
+      outcome: 'failed',
+      action: `gate crashed ${crashes}/${THRESHOLD}; circuit breaker open, failing open degraded`,
+    });
+    return { stdout: '', stderr: gateBreakerWarning(gateName, crashes), degraded: true, crashes };
+  }
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: gateName,
+    outcome: 'failed',
+    action: `gate crashed ${crashes}/${THRESHOLD}; failing closed`,
+  });
+  return { stdout: denyDecision(gateCrashReason(gateName, crashes)) + '\n', stderr: '', degraded: false, crashes };
+}
+
+async function main() {
+  const gateName = process.argv[2] || 'unknown';
+  try {
+    await readHookInput();
+  } catch {
+    // Input is unused for session keying; still drain stdin when present.
+  }
+
+  const res = handleGateCrash(gateName);
+  if (res.stdout) process.stdout.write(res.stdout);
+  if (res.stderr) process.stderr.write(res.stderr);
+  process.exit(0);
+}
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('deny-gate-crash.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/deny-gate-crash.mjs'))
+) {
+  main().catch(() => process.exit(0));
+}

package/scripts/edit-tool-paths.mjs

@@ -0,0 +1,113 @@
+// The files one edit-shaped tool call touches, across BOTH host contracts (#3563).
+//
+// Claude sends `Edit`/`Write` with `tool_input.file_path`. Codex also sends `apply_patch`, and puts the
+// whole patch in `tool_input.command` — there is no `file_path` at all. A gate that reads only
+// `file_path` therefore sees nothing to check and exits 0: on Codex the vault-edit gate FAILED OPEN and
+// `apply_patch` could create a `.env`, while the guide claimed the path was protected (cross-vendor
+// check, openai-sol). Matching `apply_patch` in a hook manifest does not rewrite the payload.
+//
+// One extractor, used by every edit-shaped hook, so a new host contract is taught in one place.
+
+/** Tool names that mean "this call writes files". */
+export const EDIT_TOOL_NAMES = new Set(['Edit', 'Write', 'apply_patch', 'ApplyPatch']);
+
+export function isEditTool(toolName) {
+  return typeof toolName === 'string' && EDIT_TOOL_NAMES.has(toolName);
+}
+
+// `*** Add File: path`, `*** Update File: path`, `*** Delete File: path`, and the `*** Move to: path`
+// destination of a rename. Case-insensitive on the verb; the path runs to end of line.
+const PATCH_TOUCH = /^\*\*\*\s+(add|update|delete)\s+file:\s*(.+?)\s*$/gim;
+const PATCH_MOVE = /^\*\*\*\s+move\s+to:\s*(.+?)\s*$/gim;
+
+function scan(re, patch, onMatch) {
+  re.lastIndex = 0;
+  for (let m = re.exec(patch); m; m = re.exec(patch)) onMatch(m);
+}
+
+/** Every path an `apply_patch` body TOUCHES — created, updated, deleted, or renamed onto. */
+export function applyPatchTargets(patch) {
+  if (typeof patch !== 'string' || !patch) return [];
+  const out = [];
+  scan(PATCH_TOUCH, patch, (m) => out.push(m[2]));
+  scan(PATCH_MOVE, patch, (m) => out.push(m[1]));
+  return out;
+}
+
+/** Only the paths a patch CREATES or WRITES — `Add`, `Update`, and a rename destination. A `Delete File:`
+ *  target is excluded: the no-env floor blocks creating a `.env`, never removing one, and treating every
+ *  extracted target as a write turned a delete-only patch into a denial (cross-vendor check, openai-sol). */
+export function applyPatchWriteTargets(patch) {
+  if (typeof patch !== 'string' || !patch) return [];
+  const out = [];
+  scan(PATCH_TOUCH, patch, (m) => { if (m[1].toLowerCase() !== 'delete') out.push(m[2]); });
+  scan(PATCH_MOVE, patch, (m) => out.push(m[1]));
+  return out;
+}
+
+/** True when a shell command actually INVOKES `apply_patch` — as the COMMAND of some segment, not merely
+ *  as a word in it.
+ *
+ *  Patch-looking text is not a patch: `cat <<EOF … *** Add File: .env … EOF` writes nothing. But a bare
+ *  word-boundary test was wrong both ways — `"apply_patch" <<EOF` (quoted) and `/usr/bin/apply_patch`
+ *  slipped through, while `echo apply_patch <<EOF` was denied for running `echo` (cross-vendor check,
+ *  openai-sol). So: split into segments, take each segment's first token, strip quotes and any directory
+ *  prefix, and skip the leading `env`/`command`/`exec`/`sudo` wrappers that only prefix a real command. */
+const INVOKE_PREFIXES = new Set(['env', 'command', 'exec', 'sudo', 'nohup', 'time']);
+// `bash -lc "apply_patch …"` is how Codex delivers a patch through a shell tool: the real command sits
+// inside the wrapper's argument, so the wrapper and its flags are stepped over too.
+const SHELL_WRAPPERS = new Set(['bash', 'sh', 'zsh', 'dash', 'pwsh', 'powershell', 'cmd', 'cmd.exe']);
+
+export function invokesApplyPatch(command) {
+  if (typeof command !== 'string' || !command) return false;
+  // Redirects may abut the command word — `apply_patch<<'EOF'` and `apply_patch<<<"$P"` are both valid
+  // shell, and both hid the command name from a whitespace tokenizer (cross-vendor check, kimi-k3).
+  // Separating the operators first is what makes the command word its own token in every form.
+  const spaced = command.replace(/([<>]+)/g, ' $1 ');
+  for (const segment of spaced.split(/\|\||&&|[;&|\n]|<<-?\s*['"]?\w+['"]?/)) {
+    let wrapped = false;
+    for (const raw of segment.trim().split(/\s+/).filter(Boolean)) {
+      const bare = raw.replace(/^['"]+|['"]+$/g, '').replace(/\\/g, '/').split('/').pop() ?? '';
+      if (bare === 'apply_patch') return true;
+      // Step over wrappers, their env assignments, and — once inside a shell wrapper — its flags.
+      // Anything else in command position means this segment runs something other than apply_patch.
+      if (SHELL_WRAPPERS.has(bare.toLowerCase())) { wrapped = true; continue; }
+      if (INVOKE_PREFIXES.has(bare) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(raw)) continue;
+      if (wrapped && /^[-/]/.test(raw)) continue;
+      break;
+    }
+  }
+  return false;
+}
+
+/**
+ * Every file path a tool call writes to. Returns `[]` for non-edit tools and unreadable payloads —
+ * callers treat an empty list as "nothing to check", exactly as they treated a missing `file_path`.
+ * @param {{ tool_name?: unknown, tool_input?: Record<string, unknown> }} input raw hook payload
+ * @returns {string[]}
+ */
+export function editedPaths(input) {
+  const toolName = input?.tool_name;
+  if (!isEditTool(toolName)) return [];
+  return collectEditedPaths(input?.tool_input ?? {});
+}
+
+/** Every write target in a tool_input, from a direct path AND from any patch body it carries.
+ *
+ *  Union, never first-match. Returning early on `file_path` meant an `apply_patch` carrying a harmless
+ *  `file_path: "safe.txt"` alongside `*** Add File: .env` reported only `safe.txt`, and the vault gate
+ *  allowed it — a fail-open reachable by adding one benign field (cross-vendor check, openai-sol). A
+ *  gate must see every path a call writes, not the first one it finds. */
+export function collectEditedPaths(toolInput) {
+  const ti = toolInput ?? {};
+  const out = [];
+  for (const direct of [ti.file_path, ti.path]) {
+    if (typeof direct === 'string' && direct) out.push(direct);
+  }
+  // Codex `apply_patch`: the patch text arrives as `command` (or `patch`/`input` on some builds).
+  // WRITE targets only — the shell path already excluded a `*** Delete File:` and this one did not, so a
+  // delete-only patch was allowed through the shell and denied through the tool (cross-vendor check,
+  // openai-sol). One rule, both doors.
+  for (const field of ['command', 'patch', 'input']) out.push(...applyPatchWriteTargets(ti[field]));
+  return [...new Set(out)];
+}

package/scripts/env-write-lint.mjs

@@ -0,0 +1,137 @@
+// No-env floor, shell surface (#2663): deny Bash/PowerShell/shell commands that CREATE a real .env file.
+// #3563 adds the patch form: Codex accepts `apply_patch <<'EOF' … EOF` through its SHELL tools, which the
+// Edit|Write|apply_patch matcher never sees, so patch bodies are read here too.
+// The Edit/Write vault-edit-gate already blocks hand-writing a .env through the file tools; this closes the
+// shell bypass — `cp .env.example .env`, `echo ... > .env`, `tee .env`, `Out-File .env`, etc. Reads
+// (`cat .env`, `source .env`, `< .env`), deletes (`rm .env`), and the allowed template names
+// (`.env.example`, `*.template`) are NOT blocked. Pure detection — exported for tests, no IO here.
+
+import { applyPatchWriteTargets, invokesApplyPatch } from './edit-tool-paths.mjs';
+
+const DENY_REASON =
+  'No .env — the org is env-free. This command creates a .env file; don\'t. Deliver config vault-native '
+  + '(`mmi-cli stage` injects secrets into the process env; `mmi-cli vault secrets` manages names). If something '
+  + 'genuinely cannot proceed without a .env, STOP and consult the board (file an issue) — do not create it.';
+
+/** True for a token that names a REAL .env file (`.env` or `.env.<suffix>`), excluding the allowed template
+ *  names (`.env.example`, anything ending `.example`, anything containing `.template`). Strips surrounding
+ *  quotes and any directory prefix. */
+export function isRealEnvToken(token) {
+  if (!token || typeof token !== 'string') return false;
+  const unquoted = token.replace(/^['"]/, '').replace(/['"]$/, '');
+  const base = unquoted.replace(/\\/g, '/').split('/').pop() ?? '';
+  // Win32 strips trailing dots and spaces from the final path component, so `.env.` and `.env ` both
+  // CREATE `.env` — through any writer that goes via Win32 path normalisation, which includes Rust's
+  // std::fs, the writer behind Codex's apply_patch. Node/libuv uses verbatim paths and is the exception,
+  // which is why this never showed up from a Node probe (cross-vendor check, kimi-k3).
+  const b = base.replace(/[. ]+$/, '').toLowerCase() || base.toLowerCase();
+  if (!/^\.env(\.[^/]+)?$/.test(b)) return false;
+  if (b === '.env.example' || b.endsWith('.example') || b.includes('.template')) return false;
+  return true;
+}
+
+// A path-ish token: no shell metacharacters. Used to pull redirect/cmdlet targets out of a command.
+const PATH_TOKEN = "(['\"]?[^\\s'\"|;&<>()]+['\"]?)";
+
+// Redirection to a target: >, >>, 1>, 2>, &>, >| — the classic `echo x > .env` / `cat > .env` create.
+const REDIRECT_RE = new RegExp(`(?:\\d?>>?\\|?|&>)\\s*${PATH_TOKEN}`, 'g');
+// tee / Tee-Object (with any flags) writing a file.
+const TEE_RE = new RegExp(`\\b(?:tee|Tee-Object)\\b(?:\\s+-{1,2}\\S+)*\\s+${PATH_TOKEN}`, 'gi');
+// PowerShell content writers targeting a file (positional or -Path/-FilePath/-LiteralPath).
+const PS_WRITE_RE = new RegExp(
+  `\\b(?:Out-File|Set-Content|Add-Content|New-Item)\\b[^|;&]*?(?:-(?:Path|FilePath|LiteralPath)\\s+)?${PATH_TOKEN}`,
+  'gi',
+);
+// Copy/move/link verbs — the destination is (conventionally) the LAST path token; block when it is a real .env.
+// `copy`/`move` are the cmd.exe spellings AND the default PowerShell aliases for Copy-Item/Move-Item, so
+// `copy .env.example .env` reached disk past every analyzer (pre-existing since #2663; found by the #3563
+// cross-vendor check, openai-sol). `xcopy`/`robocopy` are the other two Windows spellings.
+const COPY_VERBS = /^(?:cp|mv|install|ln|rsync|copy|move|xcopy|robocopy|Copy-Item|Move-Item)$/i;
+
+/** Inspect one command for a real-.env CREATE. Returns { block, reason, reasonId } or null (clean). */
+export function analyze({ toolName, command } = {}) {
+  void toolName;
+  if (!command || typeof command !== 'string') return null;
+
+  // #3563: a patch can arrive through the SHELL, not just the `apply_patch` tool — Codex accepts
+  // `apply_patch <<'EOF' … EOF` and `bash -lc "apply_patch <<'EOF' …"` via its shell tools. Those calls
+  // carry `tool_name: "shell"`, so the Edit|Write|apply_patch matcher never fires the vault gate, and the
+  // shell lints below see no redirect, tee or copy to catch. Same matcher-vs-payload gap as the tool
+  // form, one door over (cross-vendor check, kimi-k3), so the shell gate reads patch bodies too.
+  //
+  // Two precision rules, both from a false deny: the command must actually INVOKE `apply_patch` (patch
+  // text inside a `cat` heredoc writes nothing), and only WRITE targets count (a `*** Delete File: .env`
+  // removes a .env, which this floor has never blocked).
+  if (invokesApplyPatch(command)) {
+    for (const target of applyPatchWriteTargets(command)) {
+      if (isRealEnvToken(target)) return deny('env_write_apply_patch');
+    }
+  }
+
+  for (const m of command.matchAll(REDIRECT_RE)) {
+    if (isRealEnvToken(m[1])) return deny('env_write_redirect');
+  }
+  for (const m of command.matchAll(TEE_RE)) {
+    if (isRealEnvToken(m[1])) return deny('env_write_tee');
+  }
+  for (const m of command.matchAll(PS_WRITE_RE)) {
+    if (isRealEnvToken(m[1])) return deny('env_write_ps');
+  }
+
+  // Copy/move/link: only the DESTINATION (last path token in the segment) creating a real .env is a write —
+  // `cat .env` (read) stays allowed. A COPY of a .env is itself a .env-shaped secret file, so
+  // `cp .env .env.bak` is blocked too; an earlier version of this comment promised otherwise and the code
+  // never did (cross-vendor check, openai-sol). Under "no .env ever" the code is right.
+  //
+  // The verb is found ANYWHERE in the segment, not only at token 0: `cmd /c copy …`, `sudo cp …` and
+  // `bash -lc "cp …"` all put a wrapper first. And the destination is not always last — PowerShell takes
+  // `-Destination`, and `cp <file> <dir>/` names the directory while the basename comes from the source
+  // (all four ALLOWED before this; cross-vendor check, openai-sol).
+  for (const raw of command.split(/(?:\|\||&&|[;&|])/)) {
+    const seg = raw.trim();
+    if (!seg) continue;
+    const tokens = seg.split(/\s+/).filter(Boolean);
+    const verbAt = tokens.findIndex((t) => COPY_VERBS.test(t.replace(/\\/g, '/').split('/').pop() ?? ''));
+    if (verbAt === -1) continue;
+    const after = tokens.slice(verbAt + 1);
+    // Named destination wins when present (`Copy-Item -Destination .env -Path x` puts it first).
+    const namedAt = after.findIndex((t) => /^-(?:Destination|dest)$/i.test(t));
+    if (namedAt !== -1 && isRealEnvToken(after[namedAt + 1])) return deny('env_write_copy');
+    const paths = after.filter((t) => !t.startsWith('-'));
+    if (isRealEnvToken(paths[paths.length - 1])) return deny('env_write_copy');
+    // `cp .env dir/` lands `dir/.env`: a directory destination takes the SOURCE's basename.
+    const dest = paths[paths.length - 1];
+    if (paths.length > 1 && dest && /[\\/]$/.test(dest) && paths.slice(0, -1).some((p) => isRealEnvToken(p))) {
+      return deny('env_write_copy');
+    }
+  }
+
+  // `git checkout <ref> -- <path>` / `git restore --source <ref> <path>` materialise a file from history.
+  for (const raw of command.split(/(?:\|\||&&|[;&|])/)) {
+    const tokens = raw.trim().split(/\s+/).filter(Boolean);
+    const gitAt = tokens.findIndex((t) => (t.replace(/\\/g, '/').split('/').pop() ?? '') === 'git');
+    if (gitAt === -1 || !/^(?:checkout|restore)$/i.test(tokens[gitAt + 1] ?? '')) continue;
+    if (tokens.slice(gitAt + 2).some((t) => isRealEnvToken(t))) return deny('env_write_git_restore');
+  }
+
+  // touch: any non-flag arg that is a real .env token creates the file.
+  for (const raw of command.split(/(?:\|\||&&|[;&|])/)) {
+    const seg = raw.trim();
+    if (!seg) continue;
+    const tokens = seg.split(/\s+/).filter(Boolean);
+    if (!tokens.length || tokens[0].toLowerCase() !== 'touch') continue;
+    const paths = tokens.slice(1).filter((t) => !t.startsWith('-'));
+    if (paths.some((p) => isRealEnvToken(p))) return deny('env_write_touch');
+  }
+
+  // dd of=<path>: block when the of= target is a real .env token.
+  for (const m of command.matchAll(/\bdd\b[^|;&]*?\bof=(['"]?[^\s'"|;&]+['"]?)/gi)) {
+    if (isRealEnvToken(m[1])) return deny('env_write_dd');
+  }
+
+  return null;
+}
+
+function deny(reasonId) {
+  return { block: true, reason: DENY_REASON, reasonId };
+}

package/scripts/hook-io.mjs

@@ -0,0 +1,22 @@
+// Shared stdin reader for Claude Code hook scripts (#1668).
+// Each hook script receives a JSON payload on stdin. This helper reads it and
+// returns the parsed object. Throws on any read or parse error so callers can
+// catch and exit 0 (hooks must never crash a turn).
+import { createInterface } from 'node:readline';
+
+/**
+ * Read all stdin lines and JSON-parse them.
+ * #4118: the shared runner now runs a gate IN-PROCESS and has already drained stdin, so it passes the
+ * buffered payload in. Parsing it here keeps ONE contract — same throw on unreadable input, so every
+ * gate's fail-open/fail-closed branch is reached identically whether it was spawned or imported.
+ * @param {Buffer|string} [buffered] Payload already read by the caller; stdin is read when absent.
+ * @returns {Promise<unknown>} Parsed JSON payload.
+ * @throws {Error} On readline or JSON parse failure.
+ */
+export async function readHookInput(buffered) {
+  if (buffered !== undefined) return JSON.parse(Buffer.isBuffer(buffered) ? buffered.toString('utf8') : String(buffered));
+  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+  const lines = [];
+  for await (const line of rl) lines.push(line);
+  return JSON.parse(lines.join('\n'));
+}

package/scripts/hook-policy.mjs

@@ -0,0 +1,73 @@
+// Canonical MMI hook policy. Host adapters select a named gate; they do not choose scripts,
+// failure posture, timeouts, or response semantics themselves.
+
+export const HOOK_POLICY_VERSION = 1;
+
+export const HOOK_GATES = Object.freeze({
+  'command-ladder': Object.freeze({
+    event: 'PreToolUse',
+    script: 'pretooluse-shell-gates.mjs',
+    failure: 'closed',
+    fallbackGate: 'command-ladder',
+    timeoutMs: 10_000,
+  }),
+  'vault-edit': Object.freeze({
+    event: 'PreToolUse',
+    script: 'vault-edit-gate.mjs',
+    failure: 'closed',
+    fallbackGate: 'vault-edit',
+    timeoutMs: 5_000,
+  }),
+  'secret-output': Object.freeze({
+    event: 'PostToolUse',
+    script: 'secret-redact.mjs',
+    failure: 'open',
+    fallbackGate: null,
+    timeoutMs: 5_000,
+  }),
+});
+
+export const HOOK_SURFACES = Object.freeze({
+  claude: Object.freeze({
+    lifecycle: 'active',
+    rootEnv: Object.freeze(['CLAUDE_PLUGIN_ROOT', 'PLUGIN_ROOT']),
+    postToolOutput: 'rewrite',
+    finalOutput: 'unsupported',
+  }),
+  codex: Object.freeze({
+    lifecycle: 'active',
+    rootEnv: Object.freeze(['PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT']),
+    postToolOutput: 'detect-only',
+    finalOutput: 'unsupported',
+  }),
+  kimi: Object.freeze({
+    lifecycle: 'active',
+    rootEnv: Object.freeze(['KIMI_PLUGIN_ROOT', 'PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT']),
+    postToolOutput: 'detect-only',
+    finalOutput: 'unsupported',
+  }),
+  cursor: Object.freeze({
+    lifecycle: 'active',
+    rootEnv: Object.freeze([]),
+    postToolOutput: 'detect-only',
+    finalOutput: 'unsupported',
+  }),
+  kilo: Object.freeze({
+    lifecycle: 'active',
+    rootEnv: Object.freeze(['KILO_PLUGIN_ROOT', 'PLUGIN_ROOT', 'CLAUDE_PLUGIN_ROOT']),
+    postToolOutput: 'rewrite',
+    finalOutput: 'rewrite',
+  }),
+});
+
+export function hookGate(id) {
+  const gate = HOOK_GATES[id];
+  if (!gate) throw new Error(`unknown MMI hook gate: ${id || '(empty)'}`);
+  return gate;
+}
+
+export function hookSurface(token) {
+  const surface = HOOK_SURFACES[token];
+  if (!surface) throw new Error(`unknown MMI hook surface: ${token || '(empty)'}`);
+  return surface;
+}