@mutmutco/hermes-plugin 3.139.1

package/scripts/pretooluse-shell-gates.mjs

@@ -0,0 +1,564 @@
+// 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 { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+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 { handleGateCrash, handleMissingHookInput, recordGateSuccess } from './deny-gate-crash.mjs';
+import { readHookInput } from './hook-io.mjs';
+import { appendHookActivity } from './hook-trace.mjs';
+
+// Secret echoes are blocked before execution on every active host.
+const SECRET_ECHO_MODE = process.env.MMI_SECRET_ECHO_LINT || 'block';
+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 TEST_COMMAND_GATE_NAME = 'test-command-policy';
+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;
+}
+
+/**
+ * Recognize test execution only as a shell command, never as prose in an argument. The small
+ * command vocabulary deliberately covers the package-manager spellings agents actually emit and
+ * the direct runners they use when no package script exists.
+ */
+function testCommandInSegment(segment) {
+  const tokens = tokenizePowerShell(segment);
+  if (!tokens?.length) return false;
+  const values = tokens.map((token) => token.value);
+  let commandAt = 0;
+  while (/^[A-Za-z_][A-Za-z0-9_]*=.*/.test(values[commandAt] ?? '')) commandAt += 1;
+  if (values[commandAt] === 'command') commandAt += 1;
+  if (values[commandAt] === 'env') {
+    commandAt += 1;
+    while (/^(?:-[A-Za-z]+|[A-Za-z_][A-Za-z0-9_]*=.*)$/.test(values[commandAt] ?? '')) commandAt += 1;
+  }
+  const executable = executableName(values[commandAt]);
+  const args = values.slice(commandAt + 1);
+  const isTestScript = (value) => /^test(?:$|[:._-])/.test(value ?? '');
+  const positional = (items, valueOptions = new Set()) => {
+    const valuesOnly = [];
+    for (let i = 0; i < items.length; i += 1) {
+      if (valueOptions.has(items[i])) { i += 1; continue; }
+      if (items[i].startsWith('-')) continue;
+      valuesOnly.push(items[i]);
+    }
+    return valuesOnly;
+  };
+  const packageRunner = new Set(['npm', 'npm.cmd', 'pnpm', 'pnpm.cmd', 'yarn', 'yarn.cmd', 'bun', 'bun.exe']);
+  if (packageRunner.has(executable)) {
+    const words = positional(args, new Set(['--prefix', '--workspace', '-w', '--dir', '-C']));
+    if (isTestScript(words[0]) || executableName(words[0]) === 'vitest') return true;
+    if (words[0] === 'run') return isTestScript(words[1]);
+    if (words[0] === 'exec' || words[0] === 'dlx') return executableName(words[1]) === 'vitest';
+  }
+  if (executable === 'npx' || executable === 'npx.cmd' || executable === 'pnpx' || executable === 'bunx') {
+    return executableName(positional(args, new Set(['--package', '-p']))[0]) === 'vitest';
+  }
+  if (['vitest', 'vitest.cmd', 'vitest.exe', 'pytest', 'pytest.exe'].includes(executable)) return true;
+  if (executable === 'node' && args[0] === '--test') return true;
+  if (executable === 'python' || executable === 'python3' || executable === 'py') return args[0] === '-m' && args[1] === 'pytest';
+  if (executable === 'cargo' || executable === 'go' || executable === 'dotnet') return args[0] === 'test';
+  if (executable === 'mvn' || executable === 'mvnw' || executable === 'gradle' || executable === 'gradlew') return args.some((arg) => /(?:^|:)test$/i.test(arg));
+  return false;
+}
+
+function requestedTestCommand(command) {
+  return boundedShellSegments(command).some((segment) => testCommandInSegment(segment.text));
+}
+
+function git(root, args) {
+  return execFileSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 4 * 1024 * 1024,
+  });
+}
+
+function repositoryRoot(input) {
+  const candidates = [input?.cwd, process.cwd()]
+    .filter((cwd, index, values) => typeof cwd === 'string' && cwd && values.indexOf(cwd) === index);
+  for (const cwd of candidates) {
+    try {
+      return git(resolve(cwd), ['rev-parse', '--show-toplevel']).trim();
+    } catch {
+      // A host may launch the plugin from its own installation directory; try the next valid cwd.
+    }
+  }
+  return null;
+}
+
+function policyMandatoryGlobs(root) {
+  const path = resolve(root, 'test-policy.json');
+  if (!existsSync(path)) return null;
+  const parsed = JSON.parse(readFileSync(path, 'utf8'));
+  if (!Array.isArray(parsed.mandatory) || !parsed.mandatory.every((entry) => entry && typeof entry.glob === 'string')) {
+    throw new Error('test-policy.json mandatory entries are invalid');
+  }
+  return parsed.mandatory.map((entry) => entry.glob);
+}
+
+function policyGlobToRegExp(glob) {
+  let out = '';
+  for (let i = 0; i < glob.length; i += 1) {
+    const char = glob[i];
+    if (char === '*') {
+      if (glob[i + 1] === '*') {
+        if (glob[i + 2] === '/') { out += '(?:.*/)?'; i += 2; } else { out += '.*'; i += 1; }
+      } else out += '[^/]*';
+    } else if (char === '{') {
+      const close = glob.indexOf('}', i);
+      if (close === -1) out += '\\{';
+      else {
+        out += `(?:${glob.slice(i + 1, close).split(',').map(policyGlobToRegExp).join('|')})`;
+        i = close;
+      }
+    } else out += /[.+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+  }
+  return out;
+}
+
+function taskDiffPaths(root) {
+  const base = ['origin/development', 'origin/main'].find((ref) => {
+    try {
+      git(root, ['rev-parse', '--verify', `${ref}^{commit}`]);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  if (!base) throw new Error('neither origin/development nor origin/main resolves');
+  const outputs = [
+    git(root, ['diff', '--name-only', `${base}...HEAD`]),
+    git(root, ['diff', '--name-only', '--cached']),
+    git(root, ['diff', '--name-only']),
+    git(root, ['ls-files', '--others', '--exclude-standard']),
+  ];
+  return [...new Set(outputs.flatMap((output) => output.split(/\r?\n/).map((path) => path.trim()).filter(Boolean)))];
+}
+
+function runTestCommandPolicy(input, { stdout = process.stdout } = {}) {
+  if (!requestedTestCommand(input?.tool_input?.command)) return { denied: false };
+  const root = repositoryRoot(input);
+  let globs;
+  try {
+    // No declaration is the estate default: this hook does not regulate test execution there.
+    if (!root || (globs = policyMandatoryGlobs(root)) === null) return { denied: false };
+    const paths = taskDiffPaths(root);
+    if (paths.some((path) => globs.some((glob) => new RegExp(`^${policyGlobToRegExp(glob)}$`).test(path)))) return { denied: false };
+  } catch (error) {
+    const reason = 'TEST-POLICY TEST COMMAND REFUSED [test-command-policy-unresolvable]: '
+      + `a test-policy.json applies but its repository, policy, or task diff could not be established (${error.message}). `
+      + 'Do not run tests; use policy-approved non-test verification, or repair the repository/base reference before retrying.';
+    appendHookActivity({ event: 'PreToolUse', script: TEST_COMMAND_GATE_NAME, outcome: 'deny', action: reason, reasonId: 'test-command-policy-unresolvable', tool: input?.tool_name });
+    stdout.write(preToolUseDeny(reason) + '\n');
+    return { denied: true };
+  }
+  const reason = 'TEST-POLICY TEST COMMAND REFUSED [test-command-outside-mandatory-zone]: '
+    + 'the current diff does not touch any test-policy.json mandatory glob. Do not run tests; use policy-approved non-test verification, '
+    + 'or touch and run mandatory-zone coverage only when the diff actually requires it.';
+  appendHookActivity({ event: 'PreToolUse', script: TEST_COMMAND_GATE_NAME, outcome: 'deny', action: reason, reasonId: 'test-command-outside-mandatory-zone', tool: input?.tool_name });
+  stdout.write(preToolUseDeny(reason) + '\n');
+  return { denied: true };
+}
+
+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;
+  const testCommandPolicy = runTestCommandPolicy(input, { stdout });
+  if (testCommandPolicy.denied) return;
+  runCommandLadder(input, { stdout, stderr });
+
+}
+
+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));
+}