@mutmutco/codex-plugin 3.131.0

package/scripts/throttle-core.mjs

@@ -0,0 +1,324 @@
+// Shell-dialect detection (#979/#2089) — pure, no IO; exported for the shell-redirect lint + tests.
+// Catches PowerShell syntax emitted into Bash and bash/zsh syntax emitted into PowerShell, so the
+// model re-issues the command in the correct dialect instead of burning a turn on a failed call.
+
+/** Remove quoted spans so redirect/log patterns in string literals do not trip the lint. */
+export function stripQuoted(cmd) {
+  return cmd.replace(/'[^']*'/g, ' ').replace(/"[^"]*"/g, ' ');
+}
+
+export function normalizeToolName(name) {
+  return String(name ?? '').trim();
+}
+
+// #3563: Codex canonicalises its shell call to `Bash` on 0.145.0, but the Codex hook manifest also
+// matches `shell`/`local_shell` for forward safety — and a matcher that fires a gate the gate itself
+// does not recognise is a decorative claim, not protection (cross-vendor check, openai-sol). One list,
+// used by every shell gate, so the matcher and the implementation cannot drift apart.
+const SHELL_TOOL_FAMILY = new Map([
+  ['Bash', 'bash'],
+  ['PowerShell', 'powershell'],
+  ['shell', 'bash'],
+  ['local_shell', 'bash'],
+]);
+
+export function isShellTool(toolName) {
+  return SHELL_TOOL_FAMILY.has(normalizeToolName(toolName));
+}
+
+export function shellFamilyFromToolName(toolName) {
+  return SHELL_TOOL_FAMILY.get(normalizeToolName(toolName)) ?? null;
+}
+
+export function normalizeShellFamily(shell, platform = process.platform) {
+  const s = String(shell ?? '').trim().toLowerCase();
+  if (/\b(pwsh|powershell|power-shell)\b/.test(s)) return 'powershell';
+  if (/\b(bash|zsh|sh|fish|git-bash|wsl)\b/.test(s)) return 'bash';
+  if (platform === 'win32') return 'powershell';
+  if (platform === 'darwin' || platform === 'linux' || platform === 'freebsd') return 'bash';
+  return null;
+}
+
+function shellUnquoted(command) {
+  return stripQuoted(String(command ?? ''));
+}
+
+function dialectReason(reasonId, reason) {
+  return { reasonId, reason };
+}
+
+function isExplicitCrossShellInvocation(cmd, family) {
+  const hasOuterSeparator = /(?:^|[^|])\|(?!\|)|;|&&|\|\|/.test(cmd);
+  if (hasOuterSeparator) return false;
+  if (family === 'bash') {
+    return /^\s*(?:pwsh|powershell)(?:\.exe)?\s+(?:(?:-NoProfile|-NonInteractive)\s+)*(?:-Command|-c)\b/i.test(cmd);
+  }
+  if (family === 'powershell') {
+    return /^\s*(?:bash|zsh|sh)(?:\.exe)?\s+-l?c\b/i.test(cmd) || /^\s*wsl(?:\.exe)?\b/i.test(cmd);
+  }
+  return false;
+}
+
+/**
+ * True when the command carries a real heredoc operator (`<<` / `<<-`) at a shell position — i.e. a `<<`
+ * that sits OUTSIDE any quoted span, followed by an (optionally quoted) delimiter word. The delimiter
+ * itself may be quoted (`<<'EOF'`), so we scan the RAW command for a `<<` outside quotes rather than the
+ * quote-stripped form. This is what distinguishes a genuine heredoc from a `<<` inside a string literal
+ * (e.g. `echo 'a << b'`), which must not trip the #2268 native-CLI heredoc lint.
+ * Returns the raw-command index of the `<<` (so callers can scope checks to the text BEFORE the
+ * heredoc, #2648), or -1 when no heredoc exists.
+ */
+function heredocIndexOutsideQuotes(command) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < command.length - 1; i += 1) {
+    const c = command[i];
+    if (inSingle) {
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; continue; }
+    if (c === '"') { inDouble = true; continue; }
+    if (c === '<' && command[i + 1] === '<') {
+      if (/^-?\s*['"]?[A-Za-z_]/.test(command.slice(i + 2))) return i;
+      i += 1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * True when a backtick sits at end-of-line OUTSIDE any quoted span — the real PowerShell
+ * line-continuation smell. A backtick+newline inside a single/double-quoted body (e.g. a Markdown
+ * code fence in an inert `printf '%s' '…'` payload) is data, not shell syntax, and must not trip
+ * the lint (#2648).
+ */
+function backtickAtEolOutsideQuotes(command) {
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < command.length; i += 1) {
+    const c = command[i];
+    if (inSingle) {
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      if (c === '\\') { i += 1; continue; }
+      if (c === '"') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; continue; }
+    if (c === '"') { inDouble = true; continue; }
+    if (c === '`' && (command[i + 1] === '\n' || (command[i + 1] === '\r' && command[i + 2] === '\n'))) return true;
+  }
+  return false;
+}
+
+/**
+ * Neutralize heredoc bodies so shell-dialect matching never trips on literal file content being written
+ * verbatim (#2746). A heredoc body is not shell to execute, so a `<<` header opens a BODY that must be kept
+ * out of the char-scanner:
+ *   - QUOTED heredoc (`<<'EOF' … EOF`): the body is 100% inert data, so it is BLANKED — PowerShell-cmdlet
+ *     tokens (`Select-Object`, `2>$null`), backticks, etc. inside authored Markdown become empty lines.
+ *   - UNQUOTED heredoc (`<<EOF … EOF`): the body may expand, so it is PASSED THROUGH unchanged for the other
+ *     lints — but it is STILL not scanned for quote state, because scanning it lets an odd quote in the body
+ *     (an apostrophe in prose, `don't`) poison the cross-line `inSingle`/`inDouble` state and suppress
+ *     detection of a LATER quoted heredoc (the recurrence #2750 fixes).
+ * The HEADER and TERMINATOR lines are kept (so the native-CLI/heredoc lints still see the `<<`, and no
+ * unterminated-heredoc artifact is created), text before the header and after the terminator is untouched, and
+ * every character index up to the header is preserved. Quote state is tracked ACROSS non-body lines so a
+ * `<<'…'` inside a multi-line quoted string is NOT mistaken for a real header. Plain `<<` needs an EXACT
+ * terminator; bash strips indentation only for `<<-`.
+ */
+export function stripQuotedHeredocBodies(command) {
+  const text = String(command ?? '');
+  if (!text.includes('<<')) return text;
+  const lines = text.split('\n');
+  const out = [];
+  let closer = null;       // marker word when inside a heredoc body (quoted OR unquoted)
+  let closerDash = false;  // `<<-` allows an indented terminator; plain `<<` needs an exact match
+  let closerBlank = false; // true = blank the body (quoted heredoc); false = pass it through (unquoted)
+  let inSingle = false;    // quote state carried ACROSS non-body lines
+  let inDouble = false;
+  for (const line of lines) {
+    if (closer !== null) {
+      const bare = line.replace(/\r$/, '');
+      if (closerDash ? bare.trim() === closer : bare === closer) {
+        out.push(line);                       // keep the terminator line intact
+        closer = null; closerDash = false; closerBlank = false;
+      } else {
+        out.push(closerBlank ? '' : line);    // blank a quoted body; pass an unquoted body through untouched
+      }
+      continue;                               // body lines never touch quote state
+    }
+    let marker = null;
+    let dash = false;
+    let quoted = false;
+    for (let i = 0; i < line.length; i += 1) {
+      const c = line[i];
+      if (inSingle) { if (c === "'") inSingle = false; continue; }
+      if (inDouble) { if (c === '\\') { i += 1; continue; } if (c === '"') inDouble = false; continue; }
+      if (c === "'") { inSingle = true; continue; }
+      if (c === '"') { inDouble = true; continue; }
+      if (marker === null && c === '<' && line[i + 1] === '<') {
+        const m = /^(-?)\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\2/.exec(line.slice(i + 2));
+        if (m) { dash = m[1] === '-'; quoted = m[2] !== ''; marker = m[3]; i += m[0].length + 1; continue; }
+        i += 1;
+      }
+    }
+    out.push(line);
+    if (marker !== null) { closer = marker; closerDash = dash; closerBlank = quoted; }
+  }
+  return out.join('\n');
+}
+
+/**
+ * ADVISORY (#2650): a Windows backslash-separated path (two or more `\`-joined segments, e.g.
+ * `docs\Architecture\x.md`) inside a Bash command body. The Bash tool's own pipeline can silently
+ * rewrite specific backslash+letter byte pairs (`\A` became a JSON-escaped bell, `\r` lost its
+ * backslash — harness-level, see #2650) before the interpreter runs, corrupting authored file
+ * content with no error. This never blocks — it warns and points at the safe patterns (forward
+ * slashes; the Write tool for file bodies). Single escapes like `printf '%s\n'` never match:
+ * the pattern requires two path separators.
+ */
+const WINDOWS_BACKSLASH_PATH_RE = /[A-Za-z0-9_.):-]+\\[A-Za-z][A-Za-z0-9_.-]*\\[A-Za-z0-9_.-]/;
+export function adviseBackslashPath(command) {
+  if (!command || typeof command !== 'string') return null;
+  if (!WINDOWS_BACKSLASH_PATH_RE.test(command)) return null;
+  return {
+    reasonId: 'shell_backslash_path_advisory',
+    reason:
+      'Windows backslash path in a Bash command body. The Bash tool pipeline can silently mangle '
+      + 'backslash+letter byte pairs (e.g. `\\A`, `\\r`) before the interpreter sees them (#2650) — '
+      + 'use forward slashes for paths, or author file bodies with the Write tool.',
+  };
+}
+
+export function analyzeShellDialect(command, shellFamily, platform = process.platform) {
+  if (!command || typeof command !== 'string') return null;
+  const family = shellFamily === 'bash' || shellFamily === 'powershell' ? shellFamily : null;
+  if (!family) return null;
+
+  const cmd = shellUnquoted(command).trim();
+  if (!cmd) return null;
+  if (isExplicitCrossShellInvocation(cmd, family)) return null;
+
+  if (family === 'bash') {
+    // #2746: a quoted heredoc body (`<<'EOF' … EOF`) is literal file content, not shell — strip it before
+    // dialect matching so PowerShell-cmdlet-shaped tokens, backticks, and `2>$null` inside authored Markdown
+    // never trip these Bash lints. The header, everything outside the body, and unquoted heredocs are
+    // matched exactly as before (indices up to the header are preserved by the blank-line substitution).
+    const bashScan = stripQuotedHeredocBodies(command);
+    const bashCmd = shellUnquoted(bashScan).trim();
+    // PowerShell stderr/stdout suppression smuggled into Bash: `2>$null`, `>$null`, `*>&$null`,
+    // or a piped `... | Out-Null`. In Bash `$null` is the empty string → ambiguous redirect.
+    if (/\$null\b/.test(bashCmd) || /\bOut-Null\b/.test(bashCmd)) {
+      return dialectReason(
+        'shell_dialect_powershell_redirect_in_bash',
+        'PowerShell `$null` in a Bash command. `$null` is empty in Bash, and redirects like `2>$null` leave '
+          + '`2>` with no target → "ambiguous redirect". Use `2>/dev/null` for stderr suppression, '
+          + '`>/dev/null` for stdout suppression, or Bash variables instead.',
+      );
+    }
+    if (/\bSelect-Object\b/i.test(bashCmd)) {
+      return dialectReason(
+        'shell_dialect_select_object_in_bash',
+        'PowerShell `Select-Object` in a Bash command. Use `head -n <n>` or `tail -n <n>` in Bash.',
+      );
+    }
+    if (/\bGet-Content\b/i.test(bashCmd)) {
+      return dialectReason(
+        'shell_dialect_get_content_in_bash',
+        'PowerShell `Get-Content` in a Bash command. Use `cat`, `head`, `tail`, or `sed -n` in Bash.',
+      );
+    }
+    if (/(^|[;&|]\s*)`[^\r\n]+/.test(bashCmd) || backtickAtEolOutsideQuotes(bashScan)) {
+      return dialectReason(
+        'shell_dialect_powershell_backtick_in_bash',
+        'Backtick reached the Bash tool. On a PowerShell-backed shell this is usually a here-string or '
+          + 'Markdown body, which the Bash tool mangles — write the body to a temp file with the Write tool '
+          + 'and pass its path (e.g. `--body-file <path>`). For a real Bash line continuation use `\\`.',
+      );
+    }
+    // #2268: on Windows the Bash tool is a `.cmd` shim whose stdin is not forwarded (#1511), so a
+    // heredoc feeding a native CLI silently sends an empty body. Redirect to the file-path pattern.
+    // #2648: test the native-CLI names only against the command SEGMENT that consumes the heredoc
+    // (the text between the last unquoted separator and the `<<`), never the heredoc BODY — markdown
+    // prose mentioning "mmi-cli" fed to `cat > file` is inert.
+    const heredocIdx = platform === 'win32' ? heredocIndexOutsideQuotes(bashScan) : -1;
+    if (
+      heredocIdx >= 0
+      && /\b(?:mmi-cli|jerv-cli|gh|git|npm|aws|node|claude)\b/i.test(
+        shellUnquoted(bashScan.slice(0, heredocIdx)).split(/[;&|]/).pop() ?? '',
+      )
+    ) {
+      return dialectReason(
+        'shell_dialect_heredoc_native_cli_windows',
+        'Bash heredoc feeding a native CLI fails on Windows: the Bash tool is a `.cmd` shim and stdin is '
+          + 'not forwarded (#1511), so the body arrives empty. Write the body to a temp file with the Write '
+          + 'tool and pass its path (e.g. `mmi-cli ... --body-file <path>`).',
+      );
+    }
+  }
+
+  if (family === 'powershell') {
+    // Bash device-null redirect smuggled into PowerShell: `2>/dev/null`, `>/dev/null`, `&>/dev/null`.
+    // PowerShell has no `/dev/null`; the correct sink is `$null`.
+    if (/[0-9&]?>\s*\/dev\/null\b/.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_bash_redirect_in_powershell',
+        'Bash redirect in a PowerShell command. PowerShell has no `/dev/null`. Use `2>$null` '
+          + '(or `| Out-Null`) to suppress output.',
+      );
+    }
+    if (/\|\s*head(?:\s|$|-)/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_head_in_powershell',
+        'Bash `head` in a PowerShell command. Use `Select-Object -First <n>`.',
+      );
+    }
+    if (/\|\s*tail(?:\s|$|-)/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_tail_in_powershell',
+        'Bash `tail` in a PowerShell command. Use `Select-Object -Last <n>` or `Get-Content -Tail <n>`.',
+      );
+    }
+    if (/(^|[;&|\r\n]\s*)sed\s+/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_sed_in_powershell',
+        'Bash `sed` in a PowerShell command. Use `Select-String`, `ForEach-Object`, or run it explicitly through `bash -lc`.',
+      );
+    }
+    if (/(^|[;&|\r\n]\s*)awk\s+/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_awk_in_powershell',
+        'Bash `awk` in a PowerShell command. Use PowerShell object processing, or run it explicitly through `bash -lc`.',
+      );
+    }
+    if (/(^|[;&|\r\n]\s*)xargs(?:\s|$)/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_xargs_in_powershell',
+        'Bash `xargs` in a PowerShell command. Use the PowerShell pipeline with `ForEach-Object`, or run it explicitly through `bash -lc`.',
+      );
+    }
+    if (/(^|[;&|\r\n]\s*)rm\s+-[^\s]*r[^\s]*f|(^|[;&|\r\n]\s*)rm\s+-[^\s]*f[^\s]*r/i.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_rm_rf_in_powershell',
+        'Bash `rm -rf` in a PowerShell command. Use `Remove-Item -Recurse -Force -LiteralPath <path>` after verifying the target path.',
+      );
+    }
+    if (/<<-?\s*['"]?[A-Za-z_][A-Za-z0-9_]*['"]?/.test(cmd)) {
+      return dialectReason(
+        'shell_dialect_heredoc_in_powershell',
+        'Bash heredoc syntax in a PowerShell command. Use a PowerShell here-string or write a temp file with `Set-Content`.',
+      );
+    }
+  }
+
+  return null;
+}

package/scripts/validate-hook.mjs

@@ -0,0 +1,156 @@
+// PreToolUse validate-hook (#2691): catch a bad mmi-cli WRITE before it spends a failed round-trip.
+// When a Bash/PowerShell tool call is a simple `mmi-cli <verb> ...` invocation, this re-runs the SAME
+// command with `--validate-only` (C3 middleware — a PURE LOCAL parse + flag/enum/ref check that writes
+// NOTHING and never hits the network) against the shipped bundle. A validation failure surfaces as an
+// ADVISORY (warn to stderr, never a deny) so the agent fixes the flags before the real write.
+//
+// FAST + FAIL-OPEN by contract: it only spawns for a detected simple mmi-cli command (never for general
+// shell), skips any compound/piped/redirected command (too risky to reconstruct), bounds the spawn with a
+// short timeout, and swallows every error — a validate probe must never block or slow a tool call it can't
+// help. Disabled by default (opt-in): enable with MMI_VALIDATE_HOOK=on.
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tokenizeShell } from './command-ladder-core.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+const SPAWN_TIMEOUT_MS = 6000;
+const MMI_BINARIES = new Set(['mmi-cli', 'mmi', 'mmi-cli.cmd', 'mmi.cmd']);
+const WRAPPER_TOKENS = new Set(['command', 'sudo', 'npx']);
+// Any of these in the raw command means it is not a single simple invocation — skip (do not reconstruct).
+const SHELL_META_RE = /[|&;`]|\$\(|[<>]|\|\||&&/;
+
+/** Strip one layer of matching surrounding quotes from a token so it becomes a real argv value. */
+function unquote(tok) {
+  if (tok.length >= 2 && ((tok[0] === '"' && tok.at(-1) === '"') || (tok[0] === "'" && tok.at(-1) === "'"))) {
+    return tok.slice(1, -1);
+  }
+  return tok;
+}
+
+/**
+ * Detect a single, simple `mmi-cli <args...>` invocation and return its argv (quote-stripped), or null.
+ * Conservative by design: rejects any command carrying shell metacharacters (pipes, redirects, compounds,
+ * substitutions) so we never mis-reconstruct a complex command. Tolerates leading `command`/`sudo`/`npx`
+ * wrappers and inline `VAR=val` assignments. Exported (pure) for tests.
+ * @param {string} command
+ * @returns {{ argv: string[] } | null}
+ */
+export function detectMmiCliCommand(command) {
+  if (!command || typeof command !== 'string') return null;
+  if (SHELL_META_RE.test(command)) return null;
+  const tokens = tokenizeShell(command);
+  let i = 0;
+  while (i < tokens.length && (WRAPPER_TOKENS.has(tokens[i]) || /^[A-Za-z_][\w]*=/.test(tokens[i]))) i += 1;
+  const bin = tokens[i];
+  if (!bin || !MMI_BINARIES.has(bin.toLowerCase())) return null;
+  const argv = tokens.slice(i + 1).map(unquote);
+  if (!argv.length) return null; // bare `mmi-cli` with no verb — nothing to validate
+  // `--validate-only` already present ⇒ the agent is deliberately dry-running; don't double up.
+  if (argv.includes('--validate-only') || argv.includes('--dry-run')) return null;
+  return { argv };
+}
+
+/**
+ * Interpret a `--validate-only` spawn result into an advisory line, or null (silent). Pure + testable.
+ *  - stdout `{ok:true,...}`  → the command validates → silent.
+ *  - stderr "unknown option/command" → not a mutating/known command (validate not applicable) → silent.
+ *  - non-zero exit otherwise → a real validation problem the write would hit → advise with the message.
+ * @param {{ status: number|null, stdout: string, stderr: string }} res
+ * @returns {string | null}
+ */
+export function interpretValidateResult(res) {
+  const stdout = String(res?.stdout ?? '').trim();
+  const stderr = String(res?.stderr ?? '').trim();
+  if (stdout.startsWith('{')) {
+    try {
+      if (JSON.parse(stdout).ok === true) return null; // validates cleanly
+    } catch {
+      /* fall through — non-JSON stdout is not a success signal */
+    }
+  }
+  if (/unknown option|unknown command/i.test(stderr)) return null; // validate not applicable to this command
+  if (res?.status && res.status !== 0) {
+    const firstLine = (stderr.split(/\r?\n/).find((l) => l.trim()) ?? stdout.split(/\r?\n/)[0] ?? '').trim();
+    return firstLine || null;
+  }
+  return null;
+}
+
+/** Resolve the shipped CLI bundle path: explicit override, then the plugin root, then a path relative to
+ *  this script (repo layout: scripts/ and cli/ are siblings). Returns null when none exists. */
+function resolveBundle(env) {
+  const candidates = [];
+  if (env.MMI_CLI_BUNDLE) candidates.push(env.MMI_CLI_BUNDLE);
+  if (env.CLAUDE_PLUGIN_ROOT) candidates.push(join(env.CLAUDE_PLUGIN_ROOT, 'cli', 'dist', 'index.cjs'));
+  candidates.push(resolve(dirname(fileURLToPath(import.meta.url)), '..', 'cli', 'dist', 'index.cjs'));
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+/**
+ * Run the validate advisory for a PreToolUse Bash/PowerShell input. IO-thin: gating + one guarded spawn.
+ * Injected `spawnFn` and `bundleResolver` keep it unit-testable without the real bundle.
+ */
+export function runValidateAdvisory(input, { stderr = process.stderr, env = process.env, spawnFn, bundleResolver = resolveBundle } = {}) {
+  // Default OFF (opt-in): the advisory spawns a ~150-400ms bundle on write-shaped mmi-cli calls, above the
+  // "tens of ms" hook budget, so it stays out of the hot path unless explicitly enabled with MMI_VALIDATE_HOOK=on.
+  if (String(env.MMI_VALIDATE_HOOK ?? '').toLowerCase() !== 'on') return { ran: false };
+  const tool = input?.tool_name;
+  if (tool !== 'Bash' && tool !== 'PowerShell') return { ran: false };
+
+  const detected = detectMmiCliCommand(input?.tool_input?.command);
+  if (!detected) return { ran: false };
+
+  const bundle = bundleResolver(env);
+  if (!bundle) return { ran: false };
+
+  let res;
+  try {
+    const run = spawnFn ?? ((args) => {
+      const r = execFileSync(process.execPath, [bundle, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: SPAWN_TIMEOUT_MS,
+        windowsHide: true,
+        env: { ...env, MMI_VALIDATE_HOOK: 'off' }, // guard against any re-entrant hook
+      });
+      return { status: 0, stdout: r, stderr: '' };
+    });
+    res = run([...detected.argv, '--validate-only']);
+  } catch (e) {
+    // execFileSync throws on a non-zero exit — that carries the validation failure on stdout/stderr.
+    if (e && (e.stdout !== undefined || e.stderr !== undefined)) {
+      res = { status: e.status ?? 1, stdout: String(e.stdout ?? ''), stderr: String(e.stderr ?? '') };
+    } else {
+      appendHookActivity({ event: 'PreToolUse', script: 'validate-hook', outcome: 'failed', action: 'spawn error', tool });
+      return { ran: false }; // spawn/timeout error — fail-open, silent
+    }
+  }
+
+  const advice = interpretValidateResult(res);
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: 'validate-hook',
+    outcome: advice ? 'observe' : 'ran',
+    action: advice ? advice.slice(0, 200) : 'valid',
+    tool,
+  });
+  if (advice) {
+    stderr.write(`[mmi-validate] --validate-only flagged this command before it runs: ${advice}\n`);
+    stderr.write('[mmi-validate] advisory only — fix the flags/enums above, or proceed if this is intended.\n');
+  }
+  return { ran: true, advised: Boolean(advice) };
+}
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('validate-hook.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/validate-hook.mjs'))
+) {
+  import('./hook-io.mjs')
+    .then(({ readHookInput }) => readHookInput())
+    .then((input) => runValidateAdvisory(input))
+    .catch(() => undefined)
+    .finally(() => process.exit(0));
+}

package/scripts/vault-edit-gate.mjs

@@ -0,0 +1,94 @@
+// No-env floor: deny Edit/Write on real .env files (#1706, hardened #2663).
+// PreToolUse on Claude Code for Edit|Write, and on Codex for Edit|Write|apply_patch (#3563) — Codex's
+// apply_patch carries the target paths inside the patch body, not in `file_path`, so path extraction is
+// shared with plan-edit-sync via edit-tool-paths.mjs. Allows .env.example and template paths.
+// The org is env-free — secrets/config are vault-native (mmi-cli stage injects them into the process env;
+// /secrets manages names). NO .env is ever created, even locally. Fail-closed on gate crashes (#2598).
+import { handleGateCrash, handleMissingHookInput, recordGateSuccess } from './deny-gate-crash.mjs';
+import { editedPaths, isEditTool } from './edit-tool-paths.mjs';
+import { isRealEnvToken } from './env-write-lint.mjs';
+import { readHookInput } from './hook-io.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+const MODE = process.env.MMI_VAULT_GATE_MODE ?? 'block';
+const GATE_NAME = 'vault-edit';
+
+/**
+ * @param {{ toolName?: string, filePath?: string }} input
+ * @returns {{ block: boolean, reason: string }}
+ */
+export function analyze(input) {
+  const toolName = input?.toolName;
+  if (!isEditTool(toolName)) return { block: false, reason: '' };
+  // #3563: `filePaths` is the list, because Codex's `apply_patch` carries no `file_path` and can touch
+  // several files in one call. A single-path caller still passes `filePath`.
+  const paths = (input?.filePaths ?? []).concat(typeof input?.filePath === 'string' ? [input.filePath] : []);
+  const hit = paths.find((p) => typeof p === 'string' && isRealEnvToken(p.replace(/\\/g, '/').split('/').pop() ?? ''));
+  if (!hit) return { block: false, reason: '' };
+
+  return {
+    block: true,
+    reason:
+      'No .env — the org is env-free. Never create, edit, or write a .env file (not even a local or '
+      + 'gitignored one). Deliver config vault-native: `mmi-cli stage` injects the declared secrets into the '
+      + 'compose process env (no file), and `mmi-cli vault secrets` manages the names. If something genuinely cannot '
+      + 'proceed without a .env, STOP and consult the board (file an issue) — do not create the file.',
+  };
+}
+
+/** Shared entry (#4118): awaitable and exit-free so hook-run.mjs can import it in-process instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runHookGate({ input } = {}) {
+  let parsed;
+  try {
+    parsed = await readHookInput(input);
+  } catch {
+    // Unreadable/absent payload = out-of-contract host (#2992): fail open without counting a crash.
+    const res = handleMissingHookInput(GATE_NAME);
+    if (res.stdout) process.stdout.write(res.stdout);
+    if (res.stderr) process.stderr.write(res.stderr);
+    return;
+  }
+  recordGateSuccess(GATE_NAME);
+
+  const { block, reason } = analyze({
+    toolName: parsed?.tool_name,
+    filePaths: editedPaths(parsed),
+  });
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: GATE_NAME,
+    outcome: block ? (MODE === 'observe' ? 'observe' : 'deny') : 'ran',
+    action: block ? reason : 'clean',
+    tool: parsed?.tool_name,
+  });
+
+  if (block) {
+    if (MODE === 'observe') {
+      process.stderr.write(`[mmi-vault-gate] would-block: ${reason}\n`);
+    } else {
+      const decision = JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: reason,
+        },
+      });
+      process.stdout.write(decision + '\n');
+    }
+  }
+}
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('vault-edit-gate.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/vault-edit-gate.mjs'))
+) {
+  runHookGate().then(() => process.exit(0)).catch(() => {
+    const res = handleGateCrash(GATE_NAME);
+    if (res.stdout) process.stdout.write(res.stdout);
+    if (res.stderr) process.stderr.write(res.stderr);
+    process.exit(0);
+  });
+}