@saulwade/swl-ses 1.0.0

package/hooks/degradacion-instintos.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: degradacion-instintos.js
+ * Tipo: PostToolUse  (aplica a: Bash, Write, Edit)
+ *
+ * Detecta cuando un aprendizaje registrado en APRENDIZAJES.md es contradecido
+ * por la actividad actual del agente. Busca patrones donde:
+ *
+ *   1. Un anti-patron registrado fue usado exitosamente (falso positivo)
+ *   2. Un patron registrado como "siempre usar X" fue ignorado con exito
+ *   3. Un error se repite a pesar de que existe un aprendizaje que lo cubre
+ *
+ * Si detecta contradiccion:
+ *   - Agrega marca [CONTRADICHO: YYYY-MM-DD] a la entrada en APRENDIZAJES.md
+ *   - Tras 3 contradicciones en la misma entrada, la marca como [DEGRADADO]
+ *
+ * El hook nunca bloquea (siempre exit 0).
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteSync } = require('./lib/atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const RUTA_APRENDIZAJES = path.join(process.cwd(), '.planning', 'APRENDIZAJES.md');
+const MAX_CONTRADICCIONES = 3;
+
+// Palabras clave que indican exito en el output del agente
+const KEYWORDS_EXITO = [
+  'exitosamente', 'successfully', 'completado', 'completed',
+  'passed', 'aprobado', 'correcto', 'funciona', 'works',
+  'test passed', 'tests passed', 'all tests pass', 'build succeeded',
+];
+
+// Palabras clave de anti-patrones en aprendizajes existentes
+const KEYWORDS_ANTIPATRON = [
+  'nunca', 'never', 'no usar', 'evitar', 'prohibido',
+  'anti-patrón', 'antipatron', 'no hacer', 'bad practice',
+];
+
+// Palabras clave de patrones obligatorios en aprendizajes existentes
+const KEYWORDS_PATRON = [
+  'siempre', 'always', 'obligatorio', 'required',
+  'siempre usar', 'must use', 'nunca omitir',
+];
+
+// ---------------------------------------------------------------------------
+// Funciones de analisis
+// ---------------------------------------------------------------------------
+
+/**
+ * Lee y parsea las entradas de APRENDIZAJES.md.
+ * @returns {Array<{indice: number, linea: string, descripcion: string, contradicciones: number}>}
+ */
+function leerEntradas() {
+  try {
+    const contenido = fs.readFileSync(RUTA_APRENDIZAJES, 'utf8');
+    const lineas = contenido.split('\n');
+    const entradas = [];
+
+    for (let i = 0; i < lineas.length; i++) {
+      if (!lineas[i].startsWith('## ')) continue;
+
+      const descripcion = lineas[i]
+        .replace(/^##\s+\[\d{4}-\d{2}-\d{2}\]\s+\w+[-\w]*\s+—\s+/, '')
+        .trim()
+        .toLowerCase();
+
+      // Contar contradicciones existentes buscando marcas en lineas siguientes
+      let contradicciones = 0;
+      for (let j = i + 1; j < Math.min(i + 15, lineas.length); j++) {
+        if (lineas[j].startsWith('## ')) break;
+        const matchesContra = lineas[j].match(/\[CONTRADICHO:/g);
+        if (matchesContra) contradicciones += matchesContra.length;
+      }
+
+      entradas.push({
+        indice: i,
+        linea: lineas[i],
+        descripcion,
+        contradicciones,
+      });
+    }
+
+    return entradas;
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Extrae texto relevante del payload del hook.
+ * @param {object} data
+ * @returns {string}
+ */
+function extraerTexto(data) {
+  const toolResult = data.tool_result || data.tool?.result || {};
+  const fragmentos = [];
+
+  if (typeof toolResult === 'string') {
+    fragmentos.push(toolResult);
+  }
+
+  if (toolResult && typeof toolResult === 'object') {
+    for (const campo of ['output', 'content', 'stdout', 'text', 'result']) {
+      if (typeof toolResult[campo] === 'string') {
+        fragmentos.push(toolResult[campo]);
+      }
+    }
+  }
+
+  return fragmentos.join('\n').slice(0, 30000).toLowerCase();
+}
+
+/**
+ * Detecta si el output actual contradice algun aprendizaje existente.
+ *
+ * Contradiccion = el output muestra exito + contiene terminos de un
+ * anti-patron registrado, o ignora un patron obligatorio con exito.
+ *
+ * @param {string} texto - Output del agente (lowercase)
+ * @param {Array} entradas - Entradas parseadas de APRENDIZAJES.md
+ * @returns {Array<{indice: number, motivo: string}>}
+ */
+function detectarContradicciones(texto, entradas) {
+  // Verificar si el output indica exito
+  const hayExito = KEYWORDS_EXITO.some(kw => texto.includes(kw));
+  if (!hayExito) return [];
+
+  const contradicciones = [];
+
+  for (const entrada of entradas) {
+    // Ya esta degradada — no procesar mas
+    if (entrada.contradicciones >= MAX_CONTRADICCIONES) continue;
+
+    const desc = entrada.descripcion;
+
+    // Caso 1: Anti-patron registrado pero el agente hizo lo contrario con exito
+    const esAntiPatron = KEYWORDS_ANTIPATRON.some(kw => desc.includes(kw));
+    if (esAntiPatron) {
+      // Extraer la accion prohibida del anti-patron
+      const accionProhibida = desc
+        .replace(/nunca|never|no usar|evitar|prohibido|anti-patrón|antipatron|no hacer|bad practice/gi, '')
+        .trim()
+        .split(/\s+/)
+        .filter(p => p.length > 3)
+        .slice(0, 3)
+        .join(' ');
+
+      if (accionProhibida && texto.includes(accionProhibida)) {
+        contradicciones.push({
+          indice: entrada.indice,
+          motivo: `Accion prohibida "${accionProhibida}" usada con exito`,
+        });
+      }
+    }
+
+    // Caso 2: Error repetido a pesar de aprendizaje existente
+    if (desc.includes('error') || desc.includes('bug') || desc.includes('fallo')) {
+      const terminos = desc
+        .split(/\s+/)
+        .filter(p => p.length > 4 && !['error', 'corregido', 'solucion', 'resuelto'].includes(p))
+        .slice(0, 3);
+
+      const terminosEnOutput = terminos.filter(t => texto.includes(t));
+      if (terminosEnOutput.length >= 2 && texto.includes('error')) {
+        contradicciones.push({
+          indice: entrada.indice,
+          motivo: `Error similar recurrente a pesar del aprendizaje`,
+        });
+      }
+    }
+  }
+
+  return contradicciones;
+}
+
+/**
+ * Aplica las marcas de contradiccion al archivo APRENDIZAJES.md.
+ * @param {Array<{indice: number, motivo: string}>} contradicciones
+ */
+function aplicarDegradaciones(contradicciones) {
+  if (contradicciones.length === 0) return;
+
+  try {
+    const contenido = fs.readFileSync(RUTA_APRENDIZAJES, 'utf8');
+    const lineas = contenido.split('\n');
+    const fecha = new Date().toISOString().slice(0, 10);
+
+    for (const { indice, motivo } of contradicciones) {
+      if (indice >= lineas.length) continue;
+
+      // Buscar donde insertar la marca (despues de la linea de Contexto)
+      let insertIdx = indice + 1;
+      for (let j = indice + 1; j < Math.min(indice + 15, lineas.length); j++) {
+        if (lineas[j].startsWith('---') || lineas[j].startsWith('## ')) {
+          insertIdx = j;
+          break;
+        }
+        insertIdx = j + 1;
+      }
+
+      // Contar contradicciones existentes para esta entrada
+      let contadorContra = 0;
+      for (let j = indice; j < insertIdx; j++) {
+        const matches = lineas[j].match(/\[CONTRADICHO:/g);
+        if (matches) contadorContra += matches.length;
+      }
+
+      if (contadorContra + 1 >= MAX_CONTRADICCIONES) {
+        // Marcar como degradado
+        lineas.splice(insertIdx, 0, `**[DEGRADADO: ${fecha}]** Contradicho ${MAX_CONTRADICCIONES}+ veces. Este aprendizaje ya no es confiable.`);
+      } else {
+        // Agregar marca de contradiccion
+        lineas.splice(insertIdx, 0, `**[CONTRADICHO: ${fecha}]** ${motivo}`);
+      }
+    }
+
+    atomicWriteSync(RUTA_APRENDIZAJES, lineas.join('\n'));
+  } catch (err) {
+    // Error al escribir — ignorar silenciosamente
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => {
+  inputRaw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(inputRaw);
+    const toolName = String(data.tool_name || data.tool?.name || '');
+
+    // Solo analizar herramientas que producen resultados de accion
+    if (!['Bash', 'Write', 'Edit'].includes(toolName)) {
+      return;
+    }
+
+    // Verificar que existe el archivo de aprendizajes
+    if (!fs.existsSync(RUTA_APRENDIZAJES)) {
+      return;
+    }
+
+    const texto = extraerTexto(data);
+    if (!texto || texto.length < 20) {
+      return;
+    }
+
+    const entradas = leerEntradas();
+    if (entradas.length === 0) {
+      return;
+    }
+
+    const contradicciones = detectarContradicciones(texto, entradas);
+    aplicarDegradaciones(contradicciones);
+
+  } catch (err) {
+    // No escribir a stderr — Claude Code lo reporta como hook error
+  }
+});

package/hooks/escaneo-secretos.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: escaneo-secretos.js
+ * Tipo: PreToolUse  (aplica a: Write, Edit)
+ *
+ * Escanea el contenido que Claude Code está a punto de escribir en disco
+ * buscando patrones conocidos de secretos y credenciales sensibles:
+ *
+ *   - API keys de Anthropic / OpenAI (sk-ant-*, sk-proj-*, sk-live-*, sk-test-*)
+ *   - Tokens de AWS (AKIA*, ASIA*)
+ *   - Tokens de GitHub (ghp_*, gho_*, ghu_*, ghs_*, ghr_*)
+ *   - Tokens de GitLab (glpat-*)
+ *   - Claves privadas PEM / SSH
+ *   - Passwords hardcodeados en asignaciones de variable comunes
+ *   - Tokens JWT (tres segmentos base64 separados por puntos)
+ *   - Connection strings con credenciales embebidas (usuario:contraseña@host)
+ *   - Variables de entorno sensibles hardcodeadas en código
+ *
+ * Resultado:
+ *   - Secreto detectado → razón en stdout + exit code 2 (block)
+ *   - Sin secreto       → sin output, proceso termina naturalmente
+ *   - Error interno     → sin output (nunca bloquear por fallo del hook)
+ *
+ * NOTA: Este hook es una primera línea de defensa heurística, no un escáner
+ * de seguridad exhaustivo. Complementar con herramientas como trufflehog,
+ * gitleaks o detect-secrets en el pipeline CI.
+ */
+
+const { normalizeForDetection } = require('./lib/normalize-input');
+const { normalizar, formatear } = require('./lib/normalize-error');
+
+// Importar taxonomía de issue codes con guard de robustez.
+let issueCodes = null;
+try {
+  issueCodes = require('./lib/agent-issue-codes');
+} catch (_) {
+  // Módulo no disponible — continuar sin códigos estandarizados
+}
+
+// ---------------------------------------------------------------------------
+// Patrones de detección
+// ---------------------------------------------------------------------------
+
+/**
+ * Cada entrada describe un tipo de secreto con:
+ *   - nombre:   Etiqueta para el mensaje de error.
+ *   - patron:   Expresión regular para detectarlo.
+ *   - ejemplos: Comentario ilustrativo (no se usa en código).
+ */
+const PATRONES_SECRETOS = [
+  {
+    nombre: 'Anthropic API Key (sk-ant-*)',
+    // sk-ant-api03-xxxxxxxx...
+    patron: /\bsk-ant-[A-Za-z0-9\-_]{20,}\b/,
+  },
+  {
+    nombre: 'OpenAI API Key (sk-proj-* / sk-live-* / sk-test-* / sk-[a-z0-9]{48})',
+    // sk-proj-..., sk-live-..., sk-test-..., sk-<48 chars alfanum>
+    patron: /\bsk-(?:proj|live|test)-[A-Za-z0-9\-_]{20,}\b|\bsk-[A-Za-z0-9]{48,}\b/,
+  },
+  {
+    nombre: 'AWS Access Key ID (AKIA* / ASIA*)',
+    // AKIAIOSFODNN7EXAMPLE  o  ASIAXXX...
+    patron: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/,
+  },
+  {
+    nombre: 'GitHub Personal Access Token (ghp_* / gho_* / ghu_* / ghs_* / ghr_*)',
+    patron: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/,
+  },
+  {
+    nombre: 'GitLab Personal Access Token (glpat-*)',
+    patron: /\bglpat-[A-Za-z0-9\-_]{20,}\b/,
+  },
+  {
+    nombre: 'Clave privada PEM (RSA / EC / OpenSSH)',
+    // -----BEGIN RSA PRIVATE KEY-----  o  -----BEGIN OPENSSH PRIVATE KEY-----
+    patron: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |)PRIVATE KEY-----/,
+  },
+  {
+    nombre: 'Password hardcodeado en variable',
+    // password = "valor", passwd='valor', pwd="valor"  (no vacío, no placeholder)
+    // Se ignoran valores que claramente son placeholders: "xxx", "your_", "<", "ENV", os.environ
+    patron: /(?:password|passwd|pwd|secret|secret_key|api_secret)\s*[:=]\s*["'](?!(?:your_|<|xxx|ENV|os\.environ|\$\{|%\w+%))[^"'\s]{6,}["']/i,
+  },
+  {
+    nombre: 'Token JWT (tres segmentos base64url)',
+    // eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c3IifQ.xxxx
+    // Solo se marca si el header decodifica como JSON con "alg" (heurística fuerte)
+    patron: /\beyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\b/,
+  },
+  {
+    nombre: 'Connection string con credenciales (usuario:contraseña@host)',
+    // postgresql://user:pass@host, mysql://user:pass@host, mongodb://user:pass@host
+    patron: /(?:postgresql|mysql|mongodb|redis|amqp|mssql|jdbc):\/\/[^:@\s]+:[^@\s]+@[^\s"']+/i,
+  },
+  {
+    nombre: 'Stripe Secret Key (sk_live_* / sk_test_*)',
+    patron: /\bsk_(?:live|test)_[A-Za-z0-9]{24,}\b/,
+  },
+  {
+    nombre: 'Slack Bot / App Token (xoxb-* / xoxa-* / xoxe-*)',
+    patron: /\bxox[bpae]-[A-Za-z0-9\-]{20,}\b/,
+  },
+  {
+    nombre: 'Twilio Account SID / Auth Token',
+    // AC seguido de 32 hex chars
+    patron: /\bAC[0-9a-fA-F]{32}\b/,
+  },
+  {
+    nombre: 'Google API Key (AIzaSy*)',
+    patron: /\bAIzaSy[A-Za-z0-9\-_]{33}\b/,
+  },
+  {
+    nombre: 'Secreto en variable de entorno hardcodeado',
+    // SECRET_KEY="valor_largo_no_placeholder"  fuera de archivos .env.example
+    patron: /(?:SECRET_KEY|AUTH_TOKEN|ACCESS_TOKEN|PRIVATE_KEY|CLIENT_SECRET)\s*=\s*["'][^"'\s]{10,}["']/,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Mapping de patrones a códigos de issue estandarizados
+// ---------------------------------------------------------------------------
+
+/**
+ * Relaciona el nombre de cada patrón de secreto con su código de issue
+ * correspondiente en la taxonomía agent-scan (agent-issue-codes.js).
+ *
+ * Reglas de mapeo:
+ *   - Secreto hardcodeado (API key, token, password) → W008
+ *   - Manejo inseguro de credenciales (connection string con user:pass) → W007
+ *   - Token con permisos amplios (sin contexto de acotamiento) → W009 si financiero, W008 en general
+ *
+ * @type {Object.<string, string>}
+ */
+const PATRON_A_CODIGO_ISSUE = {
+  'Anthropic API Key (sk-ant-*)':                                          'W008',
+  'OpenAI API Key (sk-proj-* / sk-live-* / sk-test-* / sk-[a-z0-9]{48})': 'W008',
+  'AWS Access Key ID (AKIA* / ASIA*)':                                     'W008',
+  'GitHub Personal Access Token (ghp_* / gho_* / ghu_* / ghs_* / ghr_*)': 'W008',
+  'GitLab Personal Access Token (glpat-*)':                                'W008',
+  'Clave privada PEM (RSA / EC / OpenSSH)':                                'W008',
+  'Password hardcodeado en variable':                                      'W007',
+  'Token JWT (tres segmentos base64url)':                                  'W007',
+  'Connection string con credenciales (usuario:contraseña@host)':          'W007',
+  'Stripe Secret Key (sk_live_* / sk_test_*)':                             'W008',
+  'Slack Bot / App Token (xoxb-* / xoxa-* / xoxe-*)':                     'W008',
+  'Twilio Account SID / Auth Token':                                       'W008',
+  'Google API Key (AIzaSy*)':                                              'W008',
+  'Secreto en variable de entorno hardcodeado':                            'W008',
+};
+
+/**
+ * Obtiene el código de issue para un patrón detectado.
+ * Retorna el objeto completo si el módulo agent-issue-codes está disponible,
+ * o solo el código como string si no lo está.
+ *
+ * @param {string} nombrePatron - Nombre del patrón detectado.
+ * @returns {{ codigo: string, severidad: string }|null}
+ */
+function obtenerIssueDePatron(nombrePatron) {
+  const codigo = PATRON_A_CODIGO_ISSUE[nombrePatron];
+  if (!codigo) return null;
+
+  if (issueCodes) {
+    const issue = issueCodes.obtenerCodigo(codigo);
+    if (issue) return { codigo: issue.codigo, severidad: issue.severidad };
+  }
+
+  // Fallback si el módulo no está cargado: inferir severidad del prefijo
+  const severidad = codigo.startsWith('E') ? 'error' : 'warning';
+  return { codigo, severidad };
+}
+
+// ---------------------------------------------------------------------------
+// Lógica de exclusión (falsos positivos comunes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Patrones que indican que el contenido es un archivo de ejemplo, test o
+ * documentación donde los secretos son ficticios.
+ * Si el file_path o el contenido coincide con alguno, se omite el bloqueo.
+ */
+const PATRONES_EXCLUSION_RUTA = [
+  /\.example$/i,
+  /\.sample$/i,
+  /\.test\.[jt]s$/i,
+  /\.spec\.[jt]s$/i,
+  /test[s]?[/\\]/i,
+  /__tests__[/\\]/i,
+  /fixtures?[/\\]/i,
+  /mocks?[/\\]/i,
+  /README/i,
+  /CHANGELOG/i,
+  /\.md$/i,
+];
+
+/**
+ * Cadenas que indican un valor ficticio o placeholder dentro del contenido.
+ * Si la línea que contiene el patrón también contiene alguna de estas cadenas,
+ * se considera falso positivo.
+ */
+const MARCADORES_PLACEHOLDER = [
+  'YOUR_',
+  'your_',
+  '<YOUR',
+  'PLACEHOLDER',
+  'placeholder',
+  'example.com',
+  'example_',
+  'fake_',
+  'dummy_',
+  'test_token',
+  'test_key',
+  'xxxxxxxx',
+  '# noqa',
+  '// nosec',
+  'pragma: allowlist secret',
+];
+
+// ---------------------------------------------------------------------------
+// Funciones auxiliares
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica si la ruta del archivo indica que el contenido es un ejemplo/test.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function esArchivoExcluido(filePath) {
+  return PATRONES_EXCLUSION_RUTA.some(p => p.test(filePath));
+}
+
+/**
+ * Verifica si la línea que contiene el match parece ser un placeholder.
+ * @param {string} linea
+ * @returns {boolean}
+ */
+function esPlaceholder(linea) {
+  return MARCADORES_PLACEHOLDER.some(m => linea.includes(m));
+}
+
+/**
+ * Extrae el contenido textual a escanear desde el payload del hook.
+ * Para Write: campo "content".
+ * Para Edit: campos "new_string" y "content".
+ *
+ * @param {string} toolName - Nombre de la herramienta ("Write" | "Edit").
+ * @param {object} toolInput - Parámetros de la herramienta.
+ * @returns {string} Contenido concatenado a escanear.
+ */
+function extraerContenido(toolName, toolInput) {
+  const partes = [];
+
+  if (toolName === 'Write') {
+    if (typeof toolInput.content === 'string') partes.push(toolInput.content);
+  } else if (toolName === 'Edit') {
+    // Solo escanear lo que se está insertando, no el texto que se reemplaza
+    if (typeof toolInput.new_string === 'string') partes.push(toolInput.new_string);
+    // Algunos editores pasan "content" como campo alternativo
+    if (typeof toolInput.content === 'string') partes.push(toolInput.content);
+  }
+
+  return partes.join('\n');
+}
+
+/**
+ * Escanea el contenido contra todos los patrones de secretos.
+ * Retorna la primera coincidencia encontrada, o null si el contenido es seguro.
+ *
+ * @param {string} contenido
+ * @param {string} filePath - Ruta del archivo destino (para contexto en mensajes).
+ * @returns {{ nombrePatron: string, linea: string, numeroLinea: number }|null}
+ */
+function escanear(contenido, filePath) {
+  if (!contenido) return null;
+
+  // Normalizar para prevenir bypass con fullwidth, ANSI escapes o null bytes
+  const contenidoNorm = normalizeForDetection(contenido);
+  const lineas = contenidoNorm.split('\n');
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Saltar líneas comentadas con marcadores de exclusión explícitos
+    if (esPlaceholder(linea)) continue;
+
+    for (const { nombre, patron } of PATRONES_SECRETOS) {
+      if (patron.test(linea)) {
+        const issueInfo = obtenerIssueDePatron(nombre);
+        return {
+          nombrePatron: nombre,
+          // Ofuscar el valor real en el mensaje de error para no exponerlo en logs
+          linea: linea.replace(patron, (match) => {
+            const visible = match.slice(0, 8);
+            return `${visible}${'*'.repeat(Math.max(0, match.length - 8))}`;
+          }),
+          numeroLinea:  i + 1,
+          filePath,
+          // Campos enriquecidos con la taxonomía estandarizada (nuevos — no rompen contrato)
+          codigo_issue: issueInfo ? issueInfo.codigo    : null,
+          severidad:    issueInfo ? issueInfo.severidad : 'warning',
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint principal
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => {
+  inputRaw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(inputRaw);
+
+    const toolName  = String(data.tool_name  || data.tool?.name || '');
+    const toolInput = data.tool_input || data.tool?.input || {};
+    const filePath  = String(toolInput.file_path || toolInput.path || '');
+    const sessionId = String(data.session_id || 'default');
+
+    // Este hook solo aplica a Write y Edit
+    if (!['Write', 'Edit'].includes(toolName)) {
+      return;
+    }
+
+    // Si la ruta indica archivo de ejemplo/test, saltar escaneo
+    if (filePath && esArchivoExcluido(filePath)) {
+      return;
+    }
+
+    // Extraer y escanear el contenido
+    const contenido = extraerContenido(toolName, toolInput);
+    const coincidencia = escanear(contenido, filePath);
+
+    // Registrar activación en métricas de guardrail (siempre que se analice el contenido)
+    try {
+      const { recordActivation } = require('./lib/guardrail-metrics');
+      if (coincidencia) {
+        recordActivation('escaneo-secretos.js', sessionId, true); // bloqueó
+      } else {
+        recordActivation('escaneo-secretos.js', sessionId, false); // pasó
+      }
+    } catch (_) { /* métricas opcionales — nunca bloquear */ }
+
+    if (coincidencia) {
+      // BLOQUEAR: exit code 2 = block en Claude Code hooks API
+      // Incluir código de issue estandarizado si está disponible
+      const lineaIssue = coincidencia.codigo_issue
+        ? `Código:   ${coincidencia.codigo_issue} [${coincidencia.severidad}]`
+        : null;
+
+      const razon = [
+        `Secreto detectado antes de escribir en disco.`,
+        ``,
+        `Tipo:     ${coincidencia.nombrePatron}`,
+        lineaIssue,
+        `Archivo:  ${coincidencia.filePath || '(desconocido)'}`,
+        `Línea:    ${coincidencia.numeroLinea}`,
+        `Contexto: ${coincidencia.linea.trim().slice(0, 120)}`,
+        ``,
+        `Acciones recomendadas:`,
+        `  1. Mover el secreto a una variable de entorno (.env, no commiteado).`,
+        `  2. Usar un gestor de secretos (Vault, AWS Secrets Manager, etc.).`,
+        `  3. Si es un valor ficticio, agregar un marcador como YOUR_TOKEN,`,
+        `     o una línea: # pragma: allowlist secret`,
+      ].filter(l => l !== null).join('\n');
+
+      process.stderr.write(razon);
+      process.exit(2);
+    }
+
+    // Sin secretos detectados — permitir la escritura
+
+  } catch (err) {
+    // El hook nunca bloquea por errores internos propios
+    const errNorm = normalizar(err, { fuente: 'escaneo-secretos' });
+    process.stderr.write(`[escaneo-secretos] ${formatear(errNorm)}\n`);
+  }
+});