@mutmutco/hermes-plugin 3.139.1

package/scripts/secret-echo-lint.mjs

@@ -0,0 +1,177 @@
+// Secret-echo PreToolUse lint (#2611): zero-LLM guard against printing secrets-inserted env
+// vars to the transcript. Runs before every Bash / PowerShell tool use (PreToolUse hook).
+// Flags echo/printf/printenv of env vars whose name matches the secret-name pattern, and
+// whole-environment dumps (bare env, printenv, set, Get-ChildItem env:). Never crashes a
+// turn — every failure path exits 0 and allows the call.
+//
+// MODE: advisory by default (warn on stderr, exit 0). MMI_SECRET_ECHO_LINT=block flips to
+// emit the PreToolUse deny JSON. Ship: advisory.
+const MODE = process.env.MMI_SECRET_ECHO_LINT ?? 'advisory';
+
+import { readHookInput } from './hook-io.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+// ---------------------------------------------------------------------------
+// Pure detection logic — exported for tests (no IO here).
+// ---------------------------------------------------------------------------
+
+/**
+ * Secret-name pattern reused from scripts/sensitive-value-mask.mjs secret-assignment matcher.
+ */
+const SECRET_NAME_RE = /(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PASSPHRASE|PRIVATE[_-]?KEY|CLIENT[_-]?SECRET|ACCESS[_-]?KEY|CREDENTIALS?)/i;
+
+function isSecretName(name) {
+  return SECRET_NAME_RE.test(name);
+}
+
+// Whole-environment dump patterns (per-segment anchors)
+const BARE_ENV = /^\s*env\s*$/;
+const BARE_PRINTENV = /^\s*printenv\s*$/;
+const BARE_SET = /^\s*set\s*$/;
+const PS_ENV_DUMP = /\b(?:Get-ChildItem|gci|ls|dir)\s+env:/i;
+
+/**
+ * Inspect a shell command for secret-named env var print or whole-environment dumps.
+ * Returns null (clean) or { block: true, reason }.
+ *
+ * @param {string} command
+ * @returns {{ block: boolean, reason: string } | null}
+ */
+export function analyze(command) {
+  if (!command || typeof command !== 'string') return null;
+  const trimmed = command.trim();
+  if (!trimmed) return null;
+
+  // Split first so `secrets use` exemptions and dump checks are per-segment
+  // (closes compound bypass + newline-separated dump miss; lone-CR line breaks split too).
+  const segments = trimmed.split(/[;&|]|[\r\n]+/);
+  for (const raw of segments) {
+    const seg = raw.trim();
+    if (!seg) continue;
+    if (/^secrets\s+use\b/.test(seg)) continue;
+    if (/^(?:export|local|declare|typeset)\s/.test(seg)) continue;
+
+    if (BARE_ENV.test(seg)) {
+      return { block: true, reason: 'bare `env` dumps all environment variables including secrets-sealed values' };
+    }
+    if (BARE_PRINTENV.test(seg)) {
+      return { block: true, reason: 'bare `printenv` dumps all environment variables including secrets-sealed values' };
+    }
+    if (BARE_SET.test(seg)) {
+      return { block: true, reason: 'bare `set` dumps all environment variables including secrets-sealed values' };
+    }
+    if (PS_ENV_DUMP.test(seg)) {
+      return { block: true, reason: '`Get-ChildItem env:` dumps all environment variables including secrets-sealed values' };
+    }
+
+    const hit = checkBashPrint(seg) || checkPsPrint(seg);
+    if (hit) return hit;
+  }
+
+  return null;
+}
+
+function checkBashPrint(segment) {
+  // printenv SECRET_NAME
+  const peMatch = segment.match(/(?:^|\s)printenv\s+(\w+)(?:\s|$)/);
+  if (peMatch && isSecretName(peMatch[1])) {
+    return { block: true, reason: `printenv of $${peMatch[1]} prints a secret-named env var` };
+  }
+
+  // echo/printf with $SECRET_VAR
+  if (/\b(?:echo|printf)\b/.test(segment)) {
+    for (const m of segment.matchAll(/\$[\{]?(\w+)/g)) {
+      if (isSecretName(m[1])) {
+        return { block: true, reason: `echo/printf of $${m[1]} prints a secret-named env var` };
+      }
+    }
+  }
+
+  return null;
+}
+
+function checkPsPrint(segment) {
+  // PowerShell accepts both $env:SECRET_VAR and ${env:SECRET_VAR}; keep one matcher so the braced form
+  // cannot bypass the same output checks as the ordinary form.
+  const envReference = /\$(?:\{env:(\w+)\}|env:(\w+))/gi;
+  const envName = (match) => match[1] ?? match[2];
+
+  // Write-Output / Write-Host / echo with $env:SECRET_VAR
+  if (/\b(?:Write-Output|Write-Host|echo)\b/i.test(segment)) {
+    for (const m of segment.matchAll(envReference)) {
+      const name = envName(m);
+      if (isSecretName(name)) {
+        return { block: true, reason: `Write/echo of $env:${name} prints a secret-named env var` };
+      }
+    }
+  }
+
+  // $env:SECRET_VAR in output position (start of command or after pipe, not assignment LHS)
+  for (const m of segment.matchAll(new RegExp(`(?:^|[;&|]\\s*)${envReference.source}`, 'gi'))) {
+    const name = envName(m);
+    const after = segment.slice(m.index + m[0].length);
+    if (/^\s*=(?!=)/.test(after)) continue; // assignment LHS, not output
+    if (isSecretName(name)) {
+      return { block: true, reason: `$env:${name} in output position prints a secret-named env var` };
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// IO + main — only runs when this file is the entry point.
+// ---------------------------------------------------------------------------
+
+function preToolUseDeny(reason) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
+async function main() {
+  let input;
+  try {
+    input = await readHookInput();
+  } catch {
+    appendHookActivity({
+      event: 'PreToolUse',
+      script: 'secret-echo-lint',
+      outcome: 'failed',
+      action: 'could not read hook input',
+    });
+    process.exit(0);
+  }
+
+  const result = analyze(input?.tool_input?.command);
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: 'secret-echo-lint',
+    outcome: result?.block ? (MODE === 'block' ? 'deny' : 'observe') : 'ran',
+    action: result?.block ? result.reason : 'clean',
+    tool: input?.tool_name,
+  });
+
+  if (result?.block) {
+    if (MODE === 'block') {
+      process.stdout.write(preToolUseDeny(result.reason) + '\n');
+    } else {
+      process.stderr.write(`[mmi-secret-echo-lint] would-block: ${result.reason}\n`);
+    }
+  }
+
+  process.exit(0);
+}
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('secret-echo-lint.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/secret-echo-lint.mjs'))
+) {
+  main().catch(() => process.exit(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/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);
+  });
+}