@mutmutco/codex-plugin 3.131.0

package/scripts/pretooluse-shell-gates.mjs

@@ -0,0 +1,424 @@
+// Consolidated PreToolUse shell gates (#2600): one Node boot for the Bash/PowerShell hook pair.
+// #3630 trimmed bundle: env-write-lint first, secret-echo second (Codex-only by default — Claude's
+// PostToolUse redaction masks an echoed value, Codex cannot), the narrow Windows operator-input guard,
+// then command-ladder. The broad shell-dialect advisory remains retired.
+import { analyze as analyzeSecretEcho } from './secret-echo-lint.mjs';
+import { analyze as analyzeEnvWrite } from './env-write-lint.mjs';
+import { decide as decideCommandLadder, matchedVerb } from './command-ladder-gate.mjs';
+import { runValidateAdvisory } from './validate-hook.mjs';
+import { handleGateCrash, handleMissingHookInput, recordGateSuccess } from './deny-gate-crash.mjs';
+import { readHookInput } from './hook-io.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+// #3630: on Codex and Kimi a secret echoed to the terminal can never be masked afterwards (no
+// updatedToolOutput channel — Codex PostToolUse is decision-only, Kimi PostToolUse is
+// observation-only), so the echo gate fail-closes there by default; on Claude the PostToolUse
+// redactor owns the exposure and the gate stays off unless explicitly enabled.
+const SECRET_ECHO_MODE =
+  process.env.MMI_SECRET_ECHO_LINT || (['codex', 'kimi'].includes(process.env.MMI_HOOK_SURFACE || 'claude') ? 'block' : 'off');
+const ENV_WRITE_MODE = process.env.MMI_ENV_WRITE_MODE ?? 'block';
+const WINDOWS_OPERATOR_GUARD_ON = !/^(?:0|false|no|off)$/i.test(process.env.MMI_WINDOWS_OPERATOR_GUARD ?? 'on');
+const GATE_NAME = 'command-ladder';
+const OPERATOR_GATE_NAME = 'windows-operator-input';
+const MAX_SEGMENT_CHARS = 32_768;
+
+// #3121 fast-path: trivially-safe read-only commands that need no gate evaluation.
+// Any chaining/substitution character anywhere in the command disqualifies the fast path.
+const SHELL_META_CHARS = /[|&;`]|\$\(|[<>]|\|\||&&/;
+const FAST_PATH_COMMANDS = new Set([
+  'git status',
+  'git log',
+  'git diff',
+  'ls',
+  'Get-ChildItem',
+  'dir',
+]);
+
+function preToolUseDeny(reason) {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  });
+}
+
+/** Split only on unquoted compound-command operators. Text is retained solely for analyzers and is never surfaced. */
+function boundedShellSegments(command) {
+  const source = String(command ?? '');
+  const segments = [];
+  let start = 0;
+  let quote = null;
+  const push = (end) => {
+    const text = source.slice(start, end).trim();
+    if (text) segments.push({ ordinal: segments.length + 1, text: text.slice(0, MAX_SEGMENT_CHARS) });
+  };
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote === "'") {
+      if (ch === "'" && source[i + 1] === "'") i += 1;
+      else if (ch === "'") quote = null;
+      continue;
+    }
+    if (quote === '"') {
+      if (ch === '`') i += 1;
+      else if (ch === '"') quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (ch === ';' || ch === '|' || ch === '&' || ch === '\r' || ch === '\n') {
+      push(i);
+      if ((ch === '|' || ch === '&') && source[i + 1] === ch) i += 1;
+      if (ch === '\r' && source[i + 1] === '\n') i += 1;
+      start = i + 1;
+    }
+  }
+  push(source.length);
+  return segments;
+}
+
+function locateBlockedSegment(command, analyzer, semanticClass) {
+  for (const segment of boundedShellSegments(command)) {
+    const result = analyzer(segment.text);
+    if (result?.block) return { ordinal: segment.ordinal, semanticClass: semanticClass(result) };
+  }
+  return { ordinal: 1, semanticClass: semanticClass(null) };
+}
+
+function expectedProtectionReason(original, input, analyzer, semanticClass) {
+  const located = locateBlockedSegment(input?.tool_input?.command, analyzer, semanticClass);
+  const recovery = located.semanticClass === 'environment enumeration'
+    ? 'Query only the required variables by explicit non-secret name, in a separate tool call.'
+    : located.semanticClass === 'secret-value output'
+      ? 'Use a verifier or consumer that returns status without values; when its contract requires vault injection, invoke it through `mmi-cli vault secrets use`.'
+      : 'Use the vault-native route named above, and run any safe sibling diagnostics as separate tool calls.';
+  return `${original} Entire compound tool call was cancelled before execution; safe sibling diagnostics did not run. `
+    + `This is an expected safety refusal, not a tool defect. Rejected segment ${located.ordinal}: `
+    + `${located.semanticClass}. ${recovery}`;
+}
+
+function tokenizePowerShell(segment) {
+  const matches = [...segment.matchAll(/"(?:`.|[^"])*"|'(?:''|[^'])*'|[^\s'"]+/g)];
+  if (!matches.length) return [];
+  // Adjacent lexical pieces mean mixed quoting (`foo"bar"`); unmatched text means malformed quoting.
+  // Both are ambiguous, so the operator guard fails open.
+  let end = 0;
+  for (const match of matches) {
+    const gap = segment.slice(end, match.index);
+    if (end > 0 && gap.length === 0) return null;
+    if (gap.trim()) return null;
+    end = (match.index ?? 0) + match[0].length;
+  }
+  if (segment.slice(end).trim()) return null;
+  const tokens = [];
+  for (const match of matches) {
+    const raw = match[0];
+    const quote = raw[0];
+    const fullyQuoted = (quote === '"' || quote === "'") && raw.endsWith(quote);
+    let value = fullyQuoted ? raw.slice(1, -1) : raw;
+    if (quote === '"') value = value.replace(/`(.)/g, '$1');
+    if (quote === "'") value = value.replace(/''/g, "'");
+    tokens.push({
+      value,
+      raw,
+      fullyDoubleQuoted: quote === '"' && fullyQuoted,
+    });
+  }
+  return tokens;
+}
+
+function executableName(token) {
+  return String(token ?? '').replace(/\\/g, '/').split('/').pop()?.toLowerCase() ?? '';
+}
+
+const RG_VALUE_OPTIONS = {
+  '-e': 'pattern', '--regexp': 'pattern', '-f': 'pattern', '--file': 'pattern',
+  '-g': 'glob', '--glob': 'glob', '--iglob': 'glob', '-t': 'type', '--type': 'type', '--type-add': 'type',
+};
+const RG_SAFE_FLAGS = new Set((
+  '--files --hidden --no-ignore --line-number -n --fixed-strings -F --word-regexp -w --case-sensitive -s '
+  + '--ignore-case -i --smart-case -S --multiline -U --pcre2 -P --text -a --count -c '
+  + '--files-with-matches -l --files-without-match --no-messages --quiet -q --json'
+).split(' '));
+
+function analyzeRgWildcard(tokens) {
+  if (!tokens?.length || !['rg', 'rg.exe'].includes(executableName(tokens[0].value))) return null;
+  const positional = [];
+  let explicitPattern = false;
+  let filesMode = false;
+  let afterOptions = false;
+  for (let i = 1; i < tokens.length; i += 1) {
+    const arg = tokens[i].value;
+    if (!afterOptions && arg === '--') {
+      afterOptions = true;
+      continue;
+    }
+    if (!afterOptions) {
+      const longEquals = arg.match(/^(--(?:regexp|file|glob|iglob|type|type-add))=(.*)$/);
+      if (longEquals) {
+        if (['--regexp', '--file'].includes(longEquals[1])) explicitPattern = true;
+        continue;
+      }
+      const optionKind = RG_VALUE_OPTIONS[arg];
+      if (optionKind) {
+        if (i + 1 >= tokens.length) return null;
+        if (optionKind === 'pattern') explicitPattern = true;
+        i += 1;
+        continue;
+      }
+      const shortAttached = arg.match(/^-(e|f|g|t)(.+)$/);
+      if (shortAttached) {
+        if (shortAttached[1] === 'e' || shortAttached[1] === 'f') explicitPattern = true;
+        continue;
+      }
+      if (RG_SAFE_FLAGS.has(arg)) {
+        if (arg === '--files') filesMode = true;
+        continue;
+      }
+      // Unknown options may consume the next token. Shell parsing is undecidable; fail open on ambiguity.
+      if (arg.startsWith('-')) return null;
+    }
+    positional.push(arg);
+  }
+  const paths = explicitPattern || filesMode ? positional : positional.slice(1);
+  return paths.some((path) => /[*?\[]/.test(path))
+    ? { reasonId: 'operator_input_rg_wildcard_path', semanticClass: 'unresolved wildcard path argument' }
+    : null;
+}
+
+const SSH_VALUE_OPTIONS = new Set('-b -c -D -E -e -F -I -i -J -L -l -m -O -o -P -p -Q -R -S -W -w'.split(' '));
+const SSH_SAFE_FLAGS = new Set('-4 -6 -A -a -C -f -G -g -K -k -M -N -n -s -T -t -V -v -X -x -Y -y'.split(' '));
+
+function hasUnescapedPowerShellVariable(text) {
+  for (const match of text.matchAll(/\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)/g)) {
+    const index = match.index ?? 0;
+    let backticks = 0;
+    for (let i = index - 1; i >= 0 && text[i] === '`'; i -= 1) backticks += 1;
+    if (backticks % 2 === 1) continue;
+    if (/^\$env:/i.test(text.slice(index))) continue;
+    return true;
+  }
+  return false;
+}
+
+function analyzeSshInterpolation(tokens) {
+  if (!tokens?.length || !['ssh', 'ssh.exe'].includes(executableName(tokens[0].value))) return null;
+  let hostAt = -1;
+  for (let i = 1; i < tokens.length; i += 1) {
+    const arg = tokens[i].value;
+    if (arg === '--') {
+      hostAt = i + 1;
+      break;
+    }
+    if (SSH_VALUE_OPTIONS.has(arg)) {
+      if (i + 1 >= tokens.length) return null;
+      i += 1;
+      continue;
+    }
+    if (SSH_SAFE_FLAGS.has(arg) || /^-[bcDEeFIiJLMmOoPpQRSWw].+/.test(arg)) continue;
+    if (arg.startsWith('-')) return null;
+    hostAt = i;
+    break;
+  }
+  if (hostAt < 0 || hostAt + 1 >= tokens.length) return null;
+  for (const token of tokens.slice(hostAt + 1)) {
+    if (!token.fullyDoubleQuoted) continue;
+    const remote = token.raw.slice(1, -1);
+    if (hasUnescapedPowerShellVariable(remote)) {
+      return { reasonId: 'operator_input_ssh_powershell_interpolation', semanticClass: 'PowerShell-interpolated remote program' };
+    }
+  }
+  return null;
+}
+
+function isPowerShellShapedTool(toolName) {
+  const tool = String(toolName ?? '').trim();
+  return tool === 'PowerShell' || (process.platform === 'win32' && (tool === 'shell' || tool === 'local_shell'));
+}
+
+function analyzeOperatorInput(input) {
+  if (!WINDOWS_OPERATOR_GUARD_ON || !isPowerShellShapedTool(input?.tool_name)) return null;
+  for (const segment of boundedShellSegments(input?.tool_input?.command)) {
+    const tokens = tokenizePowerShell(segment.text);
+    if (!tokens) continue;
+    const hit = analyzeRgWildcard(tokens) ?? analyzeSshInterpolation(tokens);
+    if (hit) return { ...hit, ordinal: segment.ordinal };
+  }
+  return null;
+}
+
+
+function runEnvWriteLint(input, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  const result = analyzeEnvWrite({ toolName: input?.tool_name, command: input?.tool_input?.command });
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: 'env-write-lint',
+    outcome: result?.block ? (ENV_WRITE_MODE === 'observe' ? 'observe' : 'deny') : 'ran',
+    action: result?.block ? result.reason : 'clean',
+    reasonId: result?.reasonId,
+    tool: input?.tool_name,
+  });
+
+  if (!result?.block) return { denied: false };
+
+  if (ENV_WRITE_MODE === 'observe') {
+    stderr.write(`[mmi-env-write] would-block: ${result.reason}\n`);
+    return { denied: false };
+  }
+
+  const reason = expectedProtectionReason(
+    result.reason,
+    input,
+    (segment) => analyzeEnvWrite({ toolName: input?.tool_name, command: segment }),
+    (segmentResult) => segmentResult?.reasonId === 'env_write_apply_patch'
+      ? 'environment-file patch write'
+      : 'environment-file write',
+  );
+  stdout.write(preToolUseDeny(reason) + '\n');
+  return { denied: true };
+}
+
+function runSecretEchoLint(input, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (SECRET_ECHO_MODE === 'off') return { denied: false };
+  const result = analyzeSecretEcho(input?.tool_input?.command);
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: 'secret-echo-lint',
+    outcome: result?.block ? (SECRET_ECHO_MODE === 'block' ? 'deny' : 'observe') : 'ran',
+    action: result?.block ? result.reason : 'clean',
+    tool: input?.tool_name,
+  });
+
+  if (!result?.block) return { denied: false };
+
+  if (SECRET_ECHO_MODE !== 'block') {
+    stderr.write(`[mmi-secret-echo-lint] would-block: ${result.reason}\n`);
+    return { denied: false };
+  }
+
+  const reason = expectedProtectionReason(
+    result.reason,
+    input,
+    analyzeSecretEcho,
+    (segmentResult) => /dumps all environment variables/i.test(segmentResult?.reason ?? '')
+      ? 'environment enumeration'
+      : 'secret-value output',
+  );
+  stdout.write(preToolUseDeny(reason) + '\n');
+  return { denied: true };
+}
+
+function runOperatorInputGuard(input, { stdout = process.stdout } = {}) {
+  const result = analyzeOperatorInput(input);
+  if (!result) return { denied: false };
+  const recovery = result.reasonId === 'operator_input_rg_wildcard_path'
+    ? 'Discover candidates with `rg --files`, then pass resolved literal paths or move wildcard selection to `-g`/`--glob`; do not guess a path, and keep recursive queries and output bounded.'
+    : 'Put the remote program in a temporary literal script and pipe it to `ssh host bash -s`; select the intended remote runtime explicitly, and verify the inner program exit and output.';
+  const reason = `Entire compound tool call was cancelled before execution; safe sibling segments did not run. `
+    + `This is an expected operator-input refusal, not a tool defect. Rejected segment ${result.ordinal}: `
+    + `${result.semanticClass}. ${recovery}`;
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: OPERATOR_GATE_NAME,
+    outcome: 'deny',
+    action: reason,
+    reasonId: result.reasonId,
+    tool: input?.tool_name,
+  });
+  stdout.write(preToolUseDeny(reason) + '\n');
+  return { denied: true };
+}
+
+function runCommandLadder(input, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  recordGateSuccess(GATE_NAME);
+
+  const decision = decideCommandLadder({ toolName: input?.tool_name, command: input?.tool_input?.command });
+
+  appendHookActivity({
+    event: 'PreToolUse',
+    script: GATE_NAME,
+    outcome: decision.action === 'allow' ? 'ran' : decision.action,
+    action: decision.reason ?? 'clean',
+    reasonId: decision.reasonId,
+    tool: input?.tool_name,
+  });
+
+  if (decision.action === 'bypass') {
+    stderr.write(
+      `[mmi-ladder] BYPASS ${new Date().toISOString()} ${matchedVerb(decision.reasonId)} ` +
+        `(covered by ${decision.replacement}); MMI_ALLOW_RAW_GH set — allowing raw gh\n`,
+    );
+  } else if (decision.action === 'observe') {
+    stderr.write(`[mmi-ladder] would-block: ${decision.reason}\n`);
+  } else if (decision.action === 'deny') {
+    stdout.write(preToolUseDeny(decision.reason) + '\n');
+  }
+}
+
+/** #4118: exported as `runHookGate` too — the uniform in-process entry hook-run.mjs imports instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runPreToolUseShellGates({ input: buffered, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let input;
+  try {
+    input = await readHookInput(buffered);
+  } catch {
+    // Unreadable/absent payload = out-of-contract host (Cursor's Claude-plugin import, #2992):
+    // fail open without counting a crash. Post-parse crashes below stay fail-closed (#2598).
+    const res = handleMissingHookInput(GATE_NAME);
+    if (res.stdout) stdout.write(res.stdout);
+    if (res.stderr) stderr.write(res.stderr);
+    return;
+  }
+
+  const command = input?.tool_input?.command;
+  if (typeof command === 'string' && command.length > 0 && !SHELL_META_CHARS.test(command)) {
+    const trimmed = command.trim();
+    if (FAST_PATH_COMMANDS.has(trimmed)) {
+      recordGateSuccess(GATE_NAME);
+      appendHookActivity({
+        event: 'PreToolUse',
+        script: GATE_NAME,
+        outcome: 'ran',
+        action: 'fast-path allow (trivially-safe read-only)',
+        tool: input?.tool_name,
+      });
+      return;
+    }
+  }
+
+  const envWrite = runEnvWriteLint(input, { stdout, stderr });
+  if (envWrite.denied) return;
+  const echo = runSecretEchoLint(input, { stdout, stderr });
+  if (echo.denied) return;
+  const operatorInput = runOperatorInputGuard(input, { stdout });
+  if (operatorInput.denied) return;
+  runCommandLadder(input, { stdout, stderr });
+  // Validate-hook (#2691): a mmi-cli WRITE gets a `--validate-only` pre-flight so bad flags/enums surface
+  // as an advisory before the real write spends a failed round-trip. ADVISORY ONLY (stderr, never a deny),
+  // fail-open, and self-gated to a simple mmi-cli command — never touches general shell.
+  try {
+    runValidateAdvisory(input, { stderr });
+  } catch {
+    /* fail-open: a validate probe must never block a tool call */
+  }
+}
+
+export { runPreToolUseShellGates as runHookGate };
+
+if (
+  process.argv[1] &&
+  (process.argv[1].endsWith('pretooluse-shell-gates.mjs') ||
+    process.argv[1].replace(/\\/g, '/').endsWith('scripts/pretooluse-shell-gates.mjs'))
+) {
+  runPreToolUseShellGates().catch(() => {
+    const res = handleGateCrash(GATE_NAME);
+    if (res.stdout) process.stdout.write(res.stdout);
+    if (res.stderr) process.stderr.write(res.stderr);
+  }).finally(() => process.exit(0));
+}

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/secret-redact.mjs SECRET_ASSIGNMENT.
+ */
+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));
+}