theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/scripts/hooks/verificacion-factual.js

@@ -1,1278 +0,0 @@
-#!/usr/bin/env node
-/**
- * Hook PreToolUse: puerta de verificación factual (forzado de hechos)
- *
- * Obliga al agente a investigar antes de editar archivos o ejecutar comandos.
- * En vez de preguntar "¿estás seguro?" (que un modelo siempre responde "sí"),
- * esta puerta exige hechos concretos: quién importa el archivo, qué API
- * pública se ve afectada, qué esquemas de datos hay.
- *
- * El acto de investigar crea una conciencia que la autoevaluación nunca logró.
- *
- * Puertas:
- *   - Edit/Write: listar importadores, API afectada, verificar esquemas de
- *     datos y citar la instrucción del usuario
- *   - Bash (destructivo): listar objetivos, plan de reversión y citar la
- *     instrucción
- *   - Bash (rutinario): citar la instrucción vigente (una vez por sesión)
- *
- * Compatible con run-with-flags.js vía module.exports.run().
- * Multiplataforma (Windows, macOS, Linux).
- */
-
-'use strict';
-
-const crypto = require('crypto');
-const fs = require('fs');
-const path = require('path');
-const { extractCommandSubstitutions, extractSubshellGroups, extractBraceGroups } = require('../lib/shell-substitution');
-const { resolveAgentDataHome } = require('../lib/agent-data-home');
-
-// Estado de sesión — con ámbito por sesión para evitar carreras entre sesiones.
-const STATE_DIR = process.env.THEUS_VERIFICACION_STATE_DIR || path.join(resolveAgentDataHome(), 'verificacion-factual');
-let activeStateFile = null;
-
-// State expires after 30 minutes of inactivity
-const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
-const READ_HEARTBEAT_MS = 60 * 1000;
-
-// Maximum checked entries to prevent unbounded growth
-const MAX_CHECKED_ENTRIES = 500;
-const MAX_SESSION_KEYS = 50;
-const ROUTINE_BASH_SESSION_KEY = '__bash_session__';
-const EDIT_WRITE_HOOK_ID = 'pre-edit-write-verificacion-factual';
-const BASH_HOOK_ID = 'pre-bash-verificacion-factual';
-const DISABLE_VALUES = new Set(['0', 'false', 'off', 'disabled', 'disable']);
-const ENABLE_VALUES = new Set(['1', 'true', 'on', 'enabled', 'enable', 'yes']);
-
-// SQL-keyword + dd patterns stay as a single regex — they are stable
-// phrases without shell-flag ordering concerns. Quoted strings are
-// stripped before this regex runs so a commit message mentioning
-// "drop table" no longer triggers a false positive.
-const DESTRUCTIVE_SQL_DD = /\b(drop\s+table|delete\s+from|truncate|dd\s+if=)\b/i;
-
-// Operator-supplied additional destructive patterns. Lazily compiled from
-// `THEUS_VERIFICACION_EXTRA_DESTRUCTIVOS` (regex source) on first use, then
-// memoized keyed by the env-var value so a test or long-running process
-// that flips the env between calls re-reads it without paying for a
-// recompile on every invocation. A malformed regex is treated as
-// "not configured" (the gate falls back to the built-in patterns) and
-// the parse failure is logged once via `[verificacion-factual]` to
-// stderr — hooks must never crash tool execution because of operator
-// config errors.
-let extraDestructiveCacheKey = null;
-let extraDestructiveCacheRegex = null;
-let extraDestructiveWarnLogged = false;
-function getExtraDestructiveRegex() {
-  const raw = process.env.THEUS_VERIFICACION_EXTRA_DESTRUCTIVOS || '';
-  if (!raw) {
-    extraDestructiveCacheKey = '';
-    extraDestructiveCacheRegex = null;
-    return null;
-  }
-  if (raw === extraDestructiveCacheKey) {
-    return extraDestructiveCacheRegex;
-  }
-  // The env value just changed; reset the once-per-pattern warning gate
-  // so a subsequent *different* invalid regex is also reported once. The
-  // previous shape kept the flag sticky and silently swallowed the
-  // second bad pattern in a long-running process.
-  extraDestructiveCacheKey = raw;
-  extraDestructiveWarnLogged = false;
-  try {
-    extraDestructiveCacheRegex = new RegExp(raw, 'i');
-  } catch (err) {
-    extraDestructiveCacheRegex = null;
-    if (!extraDestructiveWarnLogged) {
-      try {
-        process.stderr.write(`[verificacion-factual] se ignora el regex inválido de THEUS_VERIFICACION_EXTRA_DESTRUCTIVOS: ${err.message}\n`);
-      } catch (_) {
-        /* stderr write failure is non-fatal */
-      }
-      extraDestructiveWarnLogged = true;
-    }
-  }
-  return extraDestructiveCacheRegex;
-}
-
-// Operator-supplied path exemptions. Comma-separated globs (`THEUS_VERIFICACION_GLOBS_EXENTOS`)
-// matched against the normalized (forward-slash, lowercased) file path. First-touch
-// fact-forcing is skipped for a matching Edit/Write/MultiEdit target — intended for
-// low-import-value trees (tests, generated artifacts, scratch dirs) where "who imports
-// this / what schema" carries no signal. Memoized on the env value; fail-open (a
-// malformed pattern is dropped, never throws). `*` matches within a path segment,
-// `**` across segments, `?` a single char.
-let exemptCacheKey = null;
-let exemptCacheRegexes = null;
-function getExemptMatchers() {
-  const raw = process.env.THEUS_VERIFICACION_GLOBS_EXENTOS || '';
-  if (raw === exemptCacheKey) {
-    return exemptCacheRegexes;
-  }
-  exemptCacheKey = raw;
-  exemptCacheRegexes = raw
-    .split(',')
-    .map(s => s.trim())
-    .filter(Boolean)
-    .map(glob => {
-      const source = glob
-        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // escape regex metachars, keep * and ?
-        .split('**')                           // ** boundaries (cross-segment)
-        .map(part => part.replace(/\*/g, '[^/]*').replace(/\?/g, '.'))
-        .join('.*');                           // ** -> across segments
-      try {
-        return new RegExp(source);
-      } catch (_) {
-        return null;
-      }
-    })
-    .filter(Boolean);
-  return exemptCacheRegexes;
-}
-
-function isExemptPath(filePath) {
-  const norm = normalizeForMatch(filePath);
-  return getExemptMatchers().some(re => re.test(norm));
-}
-
-function isRoutineBashGateDisabled() {
-  return ENABLE_VALUES.has(normalizeEnvValue(process.env.THEUS_VERIFICACION_BASH_RUTINARIO_OFF));
-}
-
-/**
- * Strip the contents of single- and double-quoted strings so phrases
- * mentioned inside a commit message or echoed argument do not trigger
- * the destructive detector. Command substitutions are scanned separately
- * before this runs because they execute even inside double quotes.
- *
- * @param {string} input
- * @returns {string}
- */
-function stripQuotedStrings(input) {
-  return input.replace(/'(?:[^'\\]|\\.)*'/g, "''").replace(/"(?:[^"\\]|\\.)*"/g, '""');
-}
-
-/**
- * Promote subshell delimiters to top-level segment separators so the
- * destructive check applies inside `$(...)` and backtick subshells.
- * Without this, `echo y | $(rm -rf /tmp)` and ``echo y | `rm -rf /tmp` ``
- * slip past the segment splitter because the destructive command lives
- * inside a sub-expression. Run iteratively to handle a layer of nesting.
- *
- * @param {string} input
- * @returns {string}
- */
-function explodeSubshells(input) {
-  let out = input;
-  for (let i = 0; i < 4; i += 1) {
-    const before = out;
-    out = out.replace(/\$\(([^()`]*)\)/g, ';$1;');
-    out = out.replace(/`([^`]*)`/g, ';$1;');
-    if (out === before) break;
-  }
-  return out;
-}
-
-/**
- * Split a command line into top-level segments at unquoted shell
- * separators (`;`, `|`, `&`, `&&`, `||`) and across subshells
- * (`$(...)` / backticks). Quoted strings are stripped first so
- * separators inside quotes are not split on. Per-segment comments
- * are also stripped.
- *
- * @param {string} input
- * @returns {string[]}
- */
-function splitCommandSegments(input) {
-  const stripped = explodeSubshells(stripQuotedStrings(input));
-  return stripped
-    .split(/[;|&]+/)
-    .map(segment => segment.replace(/(^|\s)#.*/, '$1').trim())
-    .filter(Boolean);
-}
-
-/**
- * Tokenize a single command segment by whitespace. Quoted strings
- * are already collapsed to empty quotes by `stripQuotedStrings`, so
- * naive whitespace splitting is sufficient.
- *
- * @param {string} segment
- * @returns {string[]}
- */
-function tokenize(segment) {
-  return segment.split(/\s+/).filter(Boolean);
-}
-
-/**
- * Tokenize a short allowlisted shell command while preserving quoted
- * arguments. This is intentionally smaller than a full shell parser: the
- * caller rejects shell control characters before invoking it, so this only
- * needs to keep spaces inside quotes together for read-only git commands.
- *
- * @param {string} input
- * @returns {string[] | null}
- */
-function tokenizeAllowlistedShellWords(input) {
-  const tokens = [];
-  let current = '';
-  let quote = null;
-  let escaped = false;
-
-  for (const char of String(input || '')) {
-    if (escaped) {
-      current += char;
-      escaped = false;
-      continue;
-    }
-
-    if (char === '\\') {
-      escaped = true;
-      continue;
-    }
-
-    if (quote) {
-      if (char === quote) {
-        quote = null;
-      } else {
-        current += char;
-      }
-      continue;
-    }
-
-    if (char === '"' || char === "'") {
-      quote = char;
-      continue;
-    }
-
-    if (/\s/.test(char)) {
-      if (current) {
-        tokens.push(current);
-        current = '';
-      }
-      continue;
-    }
-
-    current += char;
-  }
-
-  if (escaped) current += '\\';
-  if (quote) return null;
-  if (current) tokens.push(current);
-  return tokens;
-}
-
-const SHELL_SEGMENT_SEPARATORS = new Set([';', '|', '&', '\n', '\r']);
-
-/**
- * Quote-aware split of a command line into segments, with quotes removed from
- * the resulting words. Splits only on UNQUOTED `;`, `|`, `&`, and newlines so:
- *  - a quoted command word (`'rm'`, `"rm"`) normalizes to `rm` (the shell
- *    treats quotes around a command name as transparent), and
- *  - a newline behaves as a command separator (the shell runs each line),
- * neither of which `stripQuotedStrings` + naive splitting handles — both were
- * destructive-classifier bypasses (GHSA-4v57-ph3x-gf55).
- *
- * @param {string} input
- * @returns {string[][]} array of dequoted token arrays, one per segment
- */
-function quoteAwareSegments(input) {
-  const segments = [];
-  let words = [];
-  let current = '';
-  let hasWord = false;
-  let quote = null;
-  let escaped = false;
-
-  const flushWord = () => {
-    if (hasWord) words.push(current);
-    current = '';
-    hasWord = false;
-  };
-  const flushSegment = () => {
-    flushWord();
-    if (words.length) segments.push(words);
-    words = [];
-  };
-
-  for (const ch of String(input || '')) {
-    if (escaped) {
-      current += ch;
-      hasWord = true;
-      escaped = false;
-      continue;
-    }
-    if (ch === '\\') {
-      escaped = true;
-      hasWord = true;
-      continue;
-    }
-    if (quote) {
-      if (ch === quote) quote = null;
-      else current += ch;
-      hasWord = true;
-      continue;
-    }
-    if (ch === '"' || ch === "'") {
-      quote = ch;
-      hasWord = true; // entering a quote starts a word, even if its content is empty
-      continue;
-    }
-    if (SHELL_SEGMENT_SEPARATORS.has(ch)) {
-      flushSegment();
-      continue;
-    }
-    if (/\s/.test(ch)) {
-      flushWord();
-      continue;
-    }
-    current += ch;
-    hasWord = true;
-  }
-  flushSegment();
-  return segments;
-}
-
-const SHELL_WRAPPERS = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh']);
-
-/**
- * Quote-aware destructive check: catches quoted command words, newline
- * separators, quoted `find -exec`, and `sh -c`/`bash -c` wrappers that evade
- * the quote-stripping path (GHSA-4v57-ph3x-gf55).
- *
- * @param {string} raw
- * @param {number} [depth] recursion guard for shell -c wrappers
- * @returns {boolean}
- */
-function isDestructiveQuoteAware(raw, depth = 0) {
-  if (depth > 4) return false;
-  for (const tokens of quoteAwareSegments(raw)) {
-    if (tokens.length === 0) continue;
-    if (isDestructiveRm(tokens)) return true;
-    if (isDestructiveGit(tokens)) return true;
-    if (isDestructiveFindExec(tokens.join(' '))) return true;
-    const base = commandBasename(tokens[0]);
-    if (SHELL_WRAPPERS.has(base)) {
-      const ci = tokens.indexOf('-c');
-      if (ci !== -1 && tokens[ci + 1] && isDestructiveQuoteAware(tokens[ci + 1], depth + 1)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-/**
- * Strip a leading path and trailing `.exe` from a command token so
- * `/usr/bin/git`, `git.exe`, and `GIT` all normalize to `git`.
- *
- * @param {string} token
- * @returns {string}
- */
-function commandBasename(token) {
-  if (!token) return '';
-  return token
-    .replace(/^.*[\\/]/, '')
-    .replace(/\.exe$/i, '')
-    .toLowerCase();
-}
-
-/**
- * Detect `rm` invocations that recursively force-delete files. Handles
- * combined (`-rf`, `-fr`, `-Rf`) and split (`-r -f`) flag forms.
- *
- * @param {string[]} tokens
- * @returns {boolean}
- */
-function isDestructiveRm(tokens) {
-  if (tokens.length === 0 || commandBasename(tokens[0]) !== 'rm') return false;
-  let hasR = false;
-  let hasF = false;
-  for (const t of tokens.slice(1)) {
-    if (t === '--recursive') {
-      hasR = true;
-      continue;
-    }
-    if (t === '--force') {
-      hasF = true;
-      continue;
-    }
-    if (!t.startsWith('-') || t.startsWith('--')) continue;
-    const body = t.slice(1);
-    if (/[rR]/.test(body)) hasR = true;
-    if (/f/.test(body)) hasF = true;
-  }
-  return hasR && hasF;
-}
-
-/**
- * Locate the git subcommand within a token list, skipping over git's
- * global options like `-c key=value`, `-C <path>`, `--git-dir=...`,
- * `--work-tree=...`, `--namespace=...`, `--super-prefix=...`.
- *
- * @param {string[]} tokens
- * @returns {{ command: string, rest: string[] } | null}
- */
-function findGitSubcommand(tokens) {
-  if (tokens.length === 0 || commandBasename(tokens[0]) !== 'git') return null;
-  const valueConsumingShort = new Set(['-c', '-C']);
-  const valueConsumingLong = new Set(['--git-dir', '--work-tree', '--namespace', '--super-prefix']);
-  let i = 1;
-  while (i < tokens.length) {
-    const t = tokens[i];
-    if (valueConsumingShort.has(t) || valueConsumingLong.has(t)) {
-      i += 2;
-      continue;
-    }
-    if (t.startsWith('--git-dir=') || t.startsWith('--work-tree=') || t.startsWith('--namespace=') || t.startsWith('--super-prefix=')) {
-      i += 1;
-      continue;
-    }
-    if (t.startsWith('-')) {
-      // Unknown global option — skip without consuming a value.
-      i += 1;
-      continue;
-    }
-    return { command: t.toLowerCase(), rest: tokens.slice(i + 1) };
-  }
-  return null;
-}
-
-/**
- * Detect destructive `git` invocations: `reset --hard`, `checkout --`,
- * `clean -f...`, `push --force` (but not `--force-with-lease`),
- * `commit --amend`, `rm -rf`.
- *
- * @param {string[]} tokens
- * @returns {boolean}
- */
-function isDestructiveGit(tokens) {
-  const sub = findGitSubcommand(tokens);
-  if (!sub) return false;
-  const { command, rest } = sub;
-
-  if (command === 'reset') {
-    return rest.includes('--hard');
-  }
-
-  if (command === 'checkout') {
-    // `git checkout -- <path>`, `git checkout .`, and the force forms
-    // (`--force` / `-f`) all discard uncommitted working-tree changes,
-    // mirroring the `switch` handler below.
-    return rest.some(t => {
-      if (t === '--' || t === '.' || t === '--force') return true;
-      if (!t.startsWith('-') || t.startsWith('--')) return false;
-      return t.slice(1).includes('f');
-    });
-  }
-
-  if (command === 'clean') {
-    // `git clean -f`, `-fd`, `-fdx`, `-df`, `--force`
-    return rest.some(t => {
-      if (t === '--force') return true;
-      if (!t.startsWith('-') || t.startsWith('--')) return false;
-      return t.slice(1).includes('f');
-    });
-  }
-
-  if (command === 'push') {
-    // Only `--force-with-lease` qualifies as a safety-checked force.
-    // `--force-if-includes` is a no-op when used WITHOUT
-    // `--force-with-lease` (per git-scm.com/docs/git-push), and when
-    // combined with a bare `--force` the bare force is still in effect.
-    // So `--force --force-if-includes` must be treated as destructive.
-    //
-    // A `+` refspec prefix (e.g. `git push origin +main`,
-    // `+refs/heads/main:refs/heads/main`) also forces a non-fast-forward
-    // update of that ref and is destructive on its own.
-    let withLease = false;
-    let bareForce = false;
-    let plusRefspecForce = false;
-    for (const t of rest) {
-      if (t === '--force-with-lease' || t.startsWith('--force-with-lease=')) {
-        withLease = true;
-        continue;
-      }
-      if (t === '--force' || t.startsWith('--force=')) {
-        bareForce = true;
-        continue;
-      }
-      if (t.startsWith('-') && !t.startsWith('--') && t.slice(1).includes('f')) {
-        bareForce = true;
-        continue;
-      }
-      // Refspec prefix: `+<src>[:<dst>]`. Match tokens like `+main`,
-      // `+refs/heads/main`, `+HEAD:branch`, `+:branch`. Exclude bare
-      // `+` and numeric-only `+123` which are not refspecs.
-      if (t.startsWith('+') && t.length > 1 && /^\+(?:[a-zA-Z_/.:]|HEAD)/.test(t)) {
-        plusRefspecForce = true;
-      }
-    }
-    return bareForce || (plusRefspecForce && !withLease);
-  }
-
-  if (command === 'commit') {
-    return rest.includes('--amend');
-  }
-
-  if (command === 'rm') {
-    // `git rm -r` / `-rf` / `-r -f` — destructive within the index too.
-    let hasR = false;
-    for (const t of rest) {
-      if (!t.startsWith('-') || t.startsWith('--')) continue;
-      if (/[rR]/.test(t.slice(1))) hasR = true;
-    }
-    return hasR;
-  }
-
-  if (command === 'switch') {
-    // `git switch` can discard local working-tree changes in three forms:
-    //   --discard-changes           explicit discard
-    //   --force / -f                ignore conflicts and overwrite
-    //   -C <branch>                 force-create (overwrites existing branch)
-    return rest.some(t => {
-      if (t === '--discard-changes' || t === '--force') return true;
-      if (!t.startsWith('-') || t.startsWith('--')) return false;
-      // Short combined form: -f, -fC, -Cf, -C
-      const body = t.slice(1);
-      return /[fC]/.test(body);
-    });
-  }
-
-  return false;
-}
-
-/**
- * Decide whether a bash command line contains a destructive action
- * the fact-forcing gate should challenge. Combines SQL-keyword
- * detection (regex on quote-stripped input) with per-segment shell
- * tokenization for shell commands.
- *
- * @param {string} command
- * @returns {boolean}
- */
-/**
- * Walk every executable body reachable from a raw command line and
- * return them as a flat list. Bodies that bash will execute live in
- * three different syntactic constructs, each handled by a sibling
- * extractor in `scripts/lib/shell-substitution.js`:
- *   - `$(...)` and backticks via `extractCommandSubstitutions`
- *   - plain `(...)` subshells   via `extractSubshellGroups`
- *   - `{ ...; }` brace groups   via `extractBraceGroups`
- *
- * Each extractor recurses into its own syntax. The BFS here adds
- * cross-syntax discovery — e.g. a `(...)` inside a `$(...)` body, or
- * a `{ ...; }` inside a `(...)` body — by feeding every harvested
- * body back through all three extractors. A `seen` set bounds the
- * cost to O(unique bodies).
- *
- * @param {string} raw
- * @returns {string[]}
- */
-function collectExecutableBodies(raw) {
-  const bodies = [raw];
-  const queue = [raw];
-  const seen = new Set();
-
-  while (queue.length) {
-    const current = queue.shift();
-    if (seen.has(current)) continue;
-    seen.add(current);
-
-    for (const body of extractCommandSubstitutions(current)) {
-      if (seen.has(body)) continue;
-      bodies.push(body);
-      queue.push(body);
-    }
-    for (const body of extractSubshellGroups(current)) {
-      if (seen.has(body)) continue;
-      bodies.push(body);
-      queue.push(body);
-    }
-    for (const body of extractBraceGroups(current)) {
-      if (seen.has(body)) continue;
-      bodies.push(body);
-      queue.push(body);
-    }
-  }
-
-  return bodies;
-}
-
-/**
- * Detect destructive commands inside `find ... -exec` invocations.
- * Handles `-exec rm {} \;`, `-exec rm -rf {} \;`, `-exec rmdir {} \;`,
- * `-exec unlink {} \;`, `-exec git reset --hard {} \;`.
- *
- * @param {string} command
- * @returns {boolean}
- */
-function isDestructiveFindExec(command) {
-  const raw = String(command || '');
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    return false;
-  }
-
-  // Tokenize the whole command line
-  const tokens = tokenize(trimmed);
-  if (!tokens || tokens.length === 0) {
-    return false;
-  }
-
-  // Must start with `find`
-  if (commandBasename(tokens[0]) !== 'find') {
-    return false;
-  }
-
-  // Find the `-exec` token
-  const execIndex = tokens.indexOf('-exec');
-  if (execIndex === -1) {
-    return false;
-  }
-
-  // Collect tokens after `-exec` until we hit a terminator (`;`, `\;`, or `+`)
-  const execTokens = [];
-  for (let i = execIndex + 1; i < tokens.length; i++) {
-    const token = tokens[i];
-    if (token === ';' || token === '\\;' || token === '+') {
-      break;
-    }
-    execTokens.push(token);
-  }
-
-  if (execTokens.length === 0) {
-    return false;
-  }
-
-  const baseCmd = commandBasename(execTokens[0]);
-
-  // Directly destructive commands inside -exec
-  if (baseCmd === 'rmdir' || baseCmd === 'unlink') {
-    return true;
-  }
-
-  // `rm` with any flags (including none) inside -exec is destructive
-  if (baseCmd === 'rm') {
-    return true;
-  }
-
-  // `git reset --hard` inside -exec
-  if (baseCmd === 'git') {
-    const sub = findGitSubcommand(execTokens);
-    if (sub && sub.command === 'reset' && sub.rest.includes('--hard')) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-function isDestructiveBash(command) {
-  // The SQL/dd phrases live in command bodies, not as flag-bearing
-  // arguments, so we still match them by regex — but on the input
-  // after quoting AND subshell delimiters are normalized so phrases
-  // inside `$(...)` or backticks are also caught.
-  const raw = String(command || '');
-  const flattened = explodeSubshells(stripQuotedStrings(raw));
-  if (DESTRUCTIVE_SQL_DD.test(flattened)) return true;
-
-  // Operator-supplied additional destructive patterns. Same scope as the
-  // built-in SQL/dd regex: matched against the quote-stripped, subshell-
-  // exploded command so a phrase inside `$(...)` or backticks is caught.
-  const extra = getExtraDestructiveRegex();
-  if (extra && extra.test(flattened)) return true;
-
-  // Check for destructive find -exec patterns on raw body segments (before quote-stripping)
-  // so that quoted exec binaries and compound-command prefixes are both handled correctly.
-  // splitCommandSegments strips quotes before splitting, so passing its output to
-  // isDestructiveFindExec would turn `find . -exec 'rm' {} \;` into `find . -exec  {} \;`
-  // — the binary name disappears and the check returns false.  Using raw body text avoids
-  // that false-negative while also catching `&&`, `;`, `|`, and `||` compound forms.
-  const bodies = collectExecutableBodies(raw);
-  for (const body of bodies) {
-    for (const rawSeg of body
-      .split(/[;|&]+/)
-      .map(s => s.trim())
-      .filter(Boolean)) {
-      if (isDestructiveFindExec(rawSeg)) return true;
-    }
-  }
-
-  const segments = bodies.flatMap(splitCommandSegments);
-  for (const segment of segments) {
-    const stripped = stripQuotedStrings(segment);
-    if (DESTRUCTIVE_SQL_DD.test(stripped)) return true;
-    if (extra && extra.test(stripped)) return true;
-    const tokens = tokenize(segment);
-    if (isDestructiveRm(tokens)) return true;
-    if (isDestructiveGit(tokens)) return true;
-  }
-
-  // Quote-aware pass: closes the quoted-command-word, newline-separator,
-  // quoted-find-exec, and sh/bash -c bypasses (GHSA-4v57-ph3x-gf55).
-  if (isDestructiveQuoteAware(raw)) return true;
-
-  return false;
-}
-
-// --- State management (per-session, atomic writes, bounded) ---
-
-function normalizeEnvValue(value) {
-  return String(value || '')
-    .trim()
-    .toLowerCase();
-}
-
-function isVerificacionFactualDisabled() {
-  if (normalizeEnvValue(process.env.THEUS_VERIFICACION_FACTUAL_OFF) === '1') {
-    return true;
-  }
-
-  return DISABLE_VALUES.has(normalizeEnvValue(process.env.THEUS_VERIFICACION_FACTUAL));
-}
-
-function sanitizeSessionKey(value) {
-  const raw = String(value || '').trim();
-  if (!raw) {
-    return '';
-  }
-
-  const sanitized = raw.replace(/[^a-zA-Z0-9_-]/g, '_');
-  if (sanitized && sanitized.length <= 64) {
-    return sanitized;
-  }
-
-  return hashSessionKey('sid', raw);
-}
-
-function hashSessionKey(prefix, value) {
-  return `${prefix}-${crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 24)}`;
-}
-
-function resolveSessionKey(data) {
-  const directCandidates = [data && data.session_id, data && data.sessionId, data && data.session && data.session.id, process.env.THEUS_SESSION_ID];
-
-  for (const candidate of directCandidates) {
-    const sanitized = sanitizeSessionKey(candidate);
-    if (sanitized) {
-      return sanitized;
-    }
-  }
-
-  const transcriptPath = (data && (data.transcript_path || data.transcriptPath)) || process.env.THEUS_TRANSCRIPT_PATH;
-  if (transcriptPath && String(transcriptPath).trim()) {
-    return hashSessionKey('tx', path.resolve(String(transcriptPath).trim()));
-  }
-
-  const projectFingerprint = process.env.THEUS_PROJECT_DIR || process.cwd();
-  return hashSessionKey('proj', path.resolve(projectFingerprint));
-}
-
-function getStateFile(data) {
-  if (!activeStateFile) {
-    const sessionKey = resolveSessionKey(data);
-    activeStateFile = path.join(STATE_DIR, `state-${sessionKey}.json`);
-  }
-  return activeStateFile;
-}
-
-function loadState() {
-  const stateFile = getStateFile();
-  try {
-    if (fs.existsSync(stateFile)) {
-      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-      const lastActive = state.last_active || 0;
-      if (Date.now() - lastActive > SESSION_TIMEOUT_MS) {
-        try {
-          fs.unlinkSync(stateFile);
-        } catch (_) {
-          /* ignore */
-        }
-        return { checked: [], last_active: Date.now() };
-      }
-      return state;
-    }
-  } catch (_) {
-    /* ignore */
-  }
-  return { checked: [], last_active: Date.now() };
-}
-
-function pruneCheckedEntries(checked) {
-  if (checked.length <= MAX_CHECKED_ENTRIES) {
-    return checked;
-  }
-
-  const preserved = checked.includes(ROUTINE_BASH_SESSION_KEY) ? [ROUTINE_BASH_SESSION_KEY] : [];
-  const sessionKeys = checked.filter(k => k.startsWith('__') && k !== ROUTINE_BASH_SESSION_KEY);
-  const fileKeys = checked.filter(k => !k.startsWith('__'));
-  const remainingSessionSlots = Math.max(MAX_SESSION_KEYS - preserved.length, 0);
-  const cappedSession = sessionKeys.slice(-remainingSessionSlots);
-  const remainingFileSlots = Math.max(MAX_CHECKED_ENTRIES - preserved.length - cappedSession.length, 0);
-  const cappedFiles = fileKeys.slice(-remainingFileSlots);
-  return [...preserved, ...cappedSession, ...cappedFiles];
-}
-
-function saveState(state) {
-  const stateFile = getStateFile();
-  let tmpFile = null;
-  try {
-    fs.mkdirSync(STATE_DIR, { recursive: true });
-
-    let mergedChecked = Array.isArray(state.checked) ? state.checked : [];
-    let mergedLastActive = typeof state.last_active === 'number' ? state.last_active : 0;
-    let mergedDenials = getDenialCount(state);
-
-    try {
-      if (fs.existsSync(stateFile)) {
-        const diskState = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
-        if (Array.isArray(diskState.checked)) {
-          mergedChecked = Array.from(new Set([...diskState.checked, ...mergedChecked]));
-        }
-        if (typeof diskState.last_active === 'number') {
-          mergedLastActive = Math.max(mergedLastActive, diskState.last_active);
-        }
-        mergedDenials = Math.max(mergedDenials, getDenialCount(diskState));
-      }
-    } catch (_) {
-      /* ignore malformed or transient disk state */
-    }
-
-    const finalState = {
-      checked: pruneCheckedEntries(mergedChecked),
-      last_active: Math.max(mergedLastActive, Date.now()),
-      fact_force_denials: mergedDenials
-    };
-
-    // Atomic write: temp file + rename prevents partial reads
-    tmpFile = `${stateFile}.tmp.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
-    fs.writeFileSync(tmpFile, JSON.stringify(finalState, null, 2), 'utf8');
-    try {
-      fs.renameSync(tmpFile, stateFile);
-    } catch (error) {
-      if (error && (error.code === 'EEXIST' || error.code === 'EPERM')) {
-        try {
-          fs.unlinkSync(stateFile);
-        } catch (_) {
-          /* ignore */
-        }
-        fs.renameSync(tmpFile, stateFile);
-      } else {
-        throw error;
-      }
-    }
-    tmpFile = null;
-    return true;
-  } catch (_) {
-    if (tmpFile) {
-      try {
-        fs.unlinkSync(tmpFile);
-      } catch (_) {
-        /* ignore */
-      }
-    }
-    return false;
-  }
-}
-
-function markChecked(key) {
-  const state = loadState();
-  if (!state.checked.includes(key)) {
-    state.checked.push(key);
-    return saveState(state);
-  }
-  return true;
-}
-
-// --- Fact-force denial dampening (#2142) ---
-//
-// In long sessions the near-identical four-fact deny blocks accumulate in
-// the context window and measurably raise the odds of the model dropping
-// into a degenerate repetition loop. Emit the full four-fact block only for
-// the first THEUS_VERIFICACION_BLOQUEOS_COMPLETOS denials per session (default
-// 3); afterwards emit a condensed single-line denial that carries the
-// denial ordinal, so consecutive denials are structurally different and
-// never textually identical. True retries of an already-gated target are
-// unaffected (they were always allowed). Destructive-Bash and routine-Bash
-// gates are unchanged.
-
-const DEFAULT_FULL_DENIALS = 3;
-
-function getFullDenialBudget() {
-  const raw = Number.parseInt(process.env.THEUS_VERIFICACION_BLOQUEOS_COMPLETOS || '', 10);
-  if (Number.isInteger(raw) && raw >= 0) {
-    return raw;
-  }
-  return DEFAULT_FULL_DENIALS;
-}
-
-function getDenialCount(state) {
-  const n = Number(state && state.fact_force_denials);
-  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
-}
-
-/**
- * Record a first-touch target AND count the fact-force denial in the same
- * state write. Returns the new denial ordinal (1-based) plus whether the
- * write persisted.
- */
-function markCheckedAndCountDenial(key) {
-  const state = loadState();
-  if (!state.checked.includes(key)) {
-    state.checked.push(key);
-  }
-  const denials = getDenialCount(state) + 1;
-  state.fact_force_denials = denials;
-  return { ok: saveState(state), denials };
-}
-
-function isChecked(key) {
-  const state = loadState();
-  const found = state.checked.includes(key);
-  if (found && Date.now() - (state.last_active || 0) > READ_HEARTBEAT_MS) {
-    saveState(state);
-  }
-  return found;
-}
-
-// Prune stale session files older than 1 hour
-(function pruneStaleFiles() {
-  try {
-    const files = fs.readdirSync(STATE_DIR);
-    const now = Date.now();
-    for (const f of files) {
-      const isStateFile = f.startsWith('state-') && (f.endsWith('.json') || f.includes('.json.tmp.'));
-      if (!isStateFile) continue;
-      const fp = path.join(STATE_DIR, f);
-      try {
-        const stat = fs.statSync(fp);
-        if (now - stat.mtimeMs > SESSION_TIMEOUT_MS * 2) {
-          fs.unlinkSync(fp);
-        }
-      } catch (_) {
-        // Ignore files that disappear between readdir/stat/unlink.
-      }
-    }
-  } catch (_) {
-    /* ignore */
-  }
-})();
-
-// --- Sanitize file path against injection ---
-
-function sanitizePath(filePath) {
-  // Strip control chars (including null), bidi overrides, and newlines
-  let sanitized = '';
-  for (const char of String(filePath || '')) {
-    const code = char.codePointAt(0);
-    const isAsciiControl = code <= 0x1f || code === 0x7f;
-    const isBidiOverride = (code >= 0x200e && code <= 0x200f) || (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069);
-    sanitized += isAsciiControl || isBidiOverride ? ' ' : char;
-  }
-  return sanitized.trim().slice(0, 500);
-}
-
-function normalizeForMatch(value) {
-  return String(value || '')
-    .replace(/\\/g, '/')
-    .toLowerCase();
-}
-
-function isTheusSettingsPath(filePath) {
-  const normalized = normalizeForMatch(filePath);
-  return /(^|\/)\.theus\/settings(?:\.[^/]+)?\.json$/.test(normalized);
-}
-
-function isReadOnlyGitIntrospection(command) {
-  const trimmed = String(command || '').trim();
-  if (!trimmed || /[\r\n;&|><`$()]/.test(trimmed)) {
-    return false;
-  }
-
-  const segments = splitCommandSegments(trimmed);
-  if (segments.length !== 1) {
-    return false;
-  }
-
-  const tokens = tokenizeAllowlistedShellWords(trimmed);
-  if (!tokens) {
-    return false;
-  }
-  if (commandBasename(tokens[0]) !== 'git' || tokens.length < 2) {
-    return false;
-  }
-
-  const subcommand = tokens[1].toLowerCase();
-  const args = tokens.slice(2);
-
-  if (subcommand === 'status') {
-    return args.every(arg => ['--porcelain', '--short', '--branch'].includes(arg));
-  }
-
-  if (subcommand === 'diff') {
-    const allowedDiffArgs = new Set(['--name-only', '--name-status', '--cached', '--staged', '--stat']);
-    // git diff without arguments is read-only introspection
-    if (args.length === 0) return true;
-    return args.length <= 2 && args.every(arg => allowedDiffArgs.has(arg));
-  }
-
-  if (subcommand === 'log') {
-    return args.every(arg => arg === '--oneline' || /^--max-count=\d+$/.test(arg));
-  }
-
-  if (subcommand === 'show') {
-    // Permite: git show <ref>, git show --stat, git show --name-only,
-    // git show <ref> --stat, git show <ref> --name-only
-    if (args.length === 0) return false;
-    if (args.length === 1) {
-      const arg = args[0];
-      if (arg === '--stat' || arg === '--name-only') return true;
-      // ref
-      return !arg.startsWith('--') && /^[a-zA-Z0-9._:/ -]+$/.test(arg);
-    }
-    if (args.length === 2) {
-      const [first, second] = args;
-      // ref + flag
-      if (!first.startsWith('--') && /^[a-zA-Z0-9._:/ -]+$/.test(first) && (second === '--stat' || second === '--name-only')) {
-        return true;
-      }
-      return false;
-    }
-    return false;
-  }
-
-  if (subcommand === 'branch') {
-    return args.length === 1 && args[0] === '--show-current';
-  }
-
-  if (subcommand === 'rev-parse') {
-    return args.length === 2 && args[0] === '--abbrev-ref' && /^head$/i.test(args[1]);
-  }
-
-  return false;
-}
-
-// --- Gate messages ---
-
-function editGateMsg(filePath) {
-  const safe = sanitizePath(filePath);
-  return [
-    '[Puerta de verificación factual]',
-    '',
-    `Antes de editar ${safe}, presenta estos hechos:`,
-    '',
-    '1. Lista TODOS los archivos que importan/requieren este archivo (busca en el árbol — Glob/Grep, o find/grep vía Bash)',
-    '2. Lista las funciones/clases públicas afectadas por este cambio',
-    '3. Si este archivo lee/escribe archivos de datos, muestra nombres de campos, estructura y formato de fecha (usa valores sintéticos o censurados, nunca datos reales de producción)',
-    '4. Cita textualmente la instrucción vigente del usuario',
-    '',
-    'Presenta los hechos y reintenta la misma operación.'
-  ].join('\n');
-}
-
-function writeGateMsg(filePath) {
-  const safe = sanitizePath(filePath);
-  return [
-    '[Puerta de verificación factual]',
-    '',
-    `Antes de crear ${safe}, presenta estos hechos:`,
-    '',
-    '1. Nombra el/los archivo(s) y línea(s) que llamarán a este archivo nuevo',
-    '2. Confirma que ningún archivo existente cumple el mismo propósito (busca en el árbol — Glob/Grep, o find/grep vía Bash)',
-    '3. Si este archivo lee/escribe archivos de datos, muestra nombres de campos, estructura y formato de fecha (usa valores sintéticos o censurados, nunca datos reales de producción)',
-    '4. Cita textualmente la instrucción vigente del usuario',
-    '',
-    'Presenta los hechos y reintenta la misma operación.'
-  ].join('\n');
-}
-
-/**
- * Condensed single-line denial used after the full-block budget is spent
- * (#2142). Carries the denial ordinal so consecutive denials differ
- * textually, and a one-line recovery hint instead of the multi-line block.
- */
-function condensedGateMsg(action, filePath, ordinal) {
-  const safe = sanitizePath(filePath);
-  return (
-    `[Puerta de verificación factual] (bloqueo #${ordinal} en esta sesión) Primer ${action} de ${safe}: ` +
-    'indica brevemente importadores/llamadores, API afectada, esquemas de datos si los hay y la instrucción textual del usuario; luego reintenta. ' +
-    '(THEUS_VERIFICACION_FACTUAL=off desactiva esta puerta.)'
-  );
-}
-
-function destructiveBashMsg() {
-  return [
-    '[Puerta de verificación factual]',
-    '',
-    'Comando destructivo detectado. Antes de ejecutarlo, presenta:',
-    '',
-    '1. Lista todos los archivos/datos que este comando modificará o eliminará',
-    '2. Escribe un procedimiento de reversión de una línea',
-    '3. Cita textualmente la instrucción vigente del usuario',
-    '',
-    'Presenta los hechos y reintenta la misma operación.'
-  ].join('\n');
-}
-
-function routineBashMsg() {
-  return [
-    '[Puerta de verificación factual]',
-    '',
-    'Antes del primer comando Bash de esta sesión, presenta estos hechos:',
-    '',
-    '1. La petición vigente del usuario en una sola oración',
-    '2. Qué verifica o produce este comando en concreto',
-    '',
-    'Presenta los hechos y reintenta la misma operación.'
-  ].join('\n');
-}
-
-function withRecoveryHint(message, hookIds = [EDIT_WRITE_HOOK_ID]) {
-  const disableTargets = hookIds.map(hookId => `\`${hookId}\``).join(' or ');
-  return [message, '', `Recuperación: si la verificación factual bloquea trabajo de configuración o reparación, corre esta sesión con \`THEUS_VERIFICACION_FACTUAL=off\` o añade ${disableTargets} a \`THEUS_DISABLED_HOOKS\`.`].join('\n');
-}
-
-function isSubagentInvocation(data) {
-  if (!data || typeof data !== 'object') {
-    return false;
-  }
-
-  const candidates = [data.agent_id, data.agentId, data.parent_tool_use_id, data.parentToolUseId];
-
-  return candidates.some(candidate => typeof candidate === 'string' && candidate.trim());
-}
-
-// --- Deny helper ---
-
-function denyResult(reason, options = {}) {
-  const includeRecoveryHint = options.includeRecoveryHint !== false;
-  const hookIds = Array.isArray(options.hookIds) && options.hookIds.length > 0 ? options.hookIds : [EDIT_WRITE_HOOK_ID];
-  return {
-    stdout: JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'deny',
-        permissionDecisionReason: includeRecoveryHint ? withRecoveryHint(reason, hookIds) : reason
-      }
-    }),
-    exitCode: 0
-  };
-}
-
-function allowWithStateWarning() {
-  return {
-    stderr: '[Puerta de verificación factual] No se pudo persistir el estado de la verificación factual; se permite esta operación para evitar un bucle de reintentos permanente. Revisa THEUS_VERIFICACION_STATE_DIR o los permisos del sistema de archivos.',
-    exitCode: 0
-  };
-}
-
-// --- Core logic (exported for run-with-flags.js) ---
-
-function run(rawInput) {
-  let data;
-  try {
-    data = typeof rawInput === 'string' ? JSON.parse(rawInput) : rawInput;
-  } catch (_) {
-    return rawInput; // allow on parse error
-  }
-
-  if (isVerificacionFactualDisabled()) {
-    return rawInput;
-  }
-
-  activeStateFile = null;
-  getStateFile(data);
-
-  const rawToolName = data.tool_name || '';
-  const toolInput = data.tool_input || {};
-  // Normalize: case-insensitive matching via lookup map
-  const TOOL_MAP = { edit: 'Edit', write: 'Write', multiedit: 'MultiEdit', bash: 'Bash' };
-  const toolName = TOOL_MAP[rawToolName.toLowerCase()] || rawToolName;
-  const inSubagent = isSubagentInvocation(data);
-
-  if (toolName === 'Edit' || toolName === 'Write') {
-    const filePath = toolInput.file_path || '';
-    if (!filePath || isTheusSettingsPath(filePath) || isExemptPath(filePath)) {
-      return rawInput; // allow
-    }
-
-    if (inSubagent) {
-      return rawInput; // parent session already passed the first-touch file gate
-    }
-
-    if (!isChecked(filePath)) {
-      const { ok, denials } = markCheckedAndCountDenial(filePath);
-      if (!ok) {
-        return allowWithStateWarning();
-      }
-      if (denials > getFullDenialBudget()) {
-        const action = toolName === 'Edit' ? 'edit' : 'creation';
-        return denyResult(condensedGateMsg(action, filePath, denials), { includeRecoveryHint: false });
-      }
-      return denyResult(toolName === 'Edit' ? editGateMsg(filePath) : writeGateMsg(filePath));
-    }
-
-    return rawInput; // allow
-  }
-
-  if (toolName === 'MultiEdit') {
-    if (inSubagent) {
-      return rawInput; // parent session already passed the first-touch file gate
-    }
-
-    const edits = toolInput.edits || [];
-    for (const edit of edits) {
-      const filePath = edit.file_path || '';
-      if (filePath && !isTheusSettingsPath(filePath) && !isExemptPath(filePath) && !isChecked(filePath)) {
-        const { ok, denials } = markCheckedAndCountDenial(filePath);
-        if (!ok) {
-          return allowWithStateWarning();
-        }
-        if (denials > getFullDenialBudget()) {
-          return denyResult(condensedGateMsg('edit', filePath, denials), { includeRecoveryHint: false });
-        }
-        return denyResult(editGateMsg(filePath));
-      }
-    }
-    return rawInput; // allow
-  }
-
-  if (toolName === 'Bash') {
-    const command = toolInput.command || '';
-    if (isReadOnlyGitIntrospection(command)) {
-      return rawInput;
-    }
-
-    if (isDestructiveBash(command)) {
-      // Gate destructive commands on first attempt; allow retry after facts presented
-      const key = '__destructive__' + crypto.createHash('sha256').update(command).digest('hex').slice(0, 16);
-      if (!isChecked(key)) {
-        if (!markChecked(key)) {
-          return allowWithStateWarning();
-        }
-        return denyResult(destructiveBashMsg(), { includeRecoveryHint: false });
-      }
-      return rawInput; // allow retry after facts presented
-    }
-
-    // Operator opt-out: skip the routine-bash gate entirely. The destructive
-    // gate above still fires. Es la válvula de escape documentada para
-    // entornos donde la puerta rutinaria única por sesión es fricción sin señal.
-    if (isRoutineBashGateDisabled()) {
-      return rawInput; // routine gate opted out via env
-    }
-
-    if (!isChecked(ROUTINE_BASH_SESSION_KEY)) {
-      if (!markChecked(ROUTINE_BASH_SESSION_KEY)) {
-        return allowWithStateWarning();
-      }
-      return denyResult(routineBashMsg(), { hookIds: [BASH_HOOK_ID] });
-    }
-
-    return rawInput; // allow
-  }
-
-  return rawInput; // allow
-}
-
-module.exports = { run };