Muros y hooks
Lo que el agente NO puede hacer aunque quiera — y lo que se le recuerda solo.
Hooks en Node (.mjs, agnósticos de OS: funcionan igual en Windows/macOS/Linux). Los que BLOQUEAN salen
con exit 2 y el motivo; el resto solo informa. Solo Claude Code ejecuta hooks: en Codex/Cursor/Windsurf el
trabajo lo hacen las tablas de activación de las reglas generadas y los githooks (sync.ps1 -GitHooks).
| Hook | Evento | Qué hace |
|---|---|---|
session-start.mjs |
SessionStart | Inyecta estado: si Senzu está DESACTUALIZADO (qué hacer y qué se pierde, de core/novedades.json), stack/perfil, el SIGUIENTE PASO del método que falta (/instalar, /adoptar; sin plan, saber qué se hace o preguntarlo), idioma, diario propio detectado, versiones con aviso EOL, convenciones adoptadas, git, design system, plan, devlog y protocolo de skills. |
prompt-router.mjs |
UserPromptSubmit | Sugiere la skill que encaja con la petición (señales de docs/skills.md), una vez por skill y sesión. |
guard.mjs |
PreToolUse Bash/PowerShell | Mira lo que se EJECUTA, no lo citado (mensajes de commit, heredocs a un archivo, echo, grep). BLOQUEA: git push a una rama principal, forzado o sin ver a qué rama va (a las de trabajo, sí), escribir, mover, borrar o restaurar las convenciones selladas desde la terminal (sin escape para el agente), destructivos de BD/git, rm -rf, deploy a prod sin aprobación (escape SENZU_ALLOW_DEPLOY=1), generadores de logos con logo ya elegido (SENZU_ALLOW_LOGO=1), jQuery/Bootstrap (SENZU_ALLOW_LIB=1), devops peligroso (curl|bash, chmod 777, dd, mkfs, docker prune, parar servicios, vaciar firewall, crontab -r); commits: rama protegida, Conventional ≤72, sin co-autores. |
supply-guard.mjs |
PreToolUse Bash/PowerShell | Muro de cadena de suministro. En un comando de instalación (npm/pip/composer…) mira los NOMBRES de paquete (typosquatting, denylist de malware conocido) antes de que entren; al hacer git commit escanea lo que entra (manifests de dependencias, archivos de skills/plugins y .mcp.json) buscando scripts de instalación con red/shell, inyección de prompt, exfiltración (lee secretos y abre red), ofuscación (eval/base64/hex), caracteres unicode ocultos y servidores MCP que descargan y ejecutan. BLOQUEA lo grave, AVISA del resto. «Citar no es hacer»: mira lo que se ejecuta, no el texto citado, y también DENTRO de un script que el comando ejecuta (bash x.sh, python x.py…). Offline y determinista (listas en core/hooks/data/). No se puede apagar. Escape tras verificar: SENZU_ALLOW_SUPPLY=1. |
pentest-guard.mjs |
PreToolUse Bash/PowerShell | Muro de ALCANCE de pentesting. BLOQUEA ejecutar herramientas de seguridad ofensiva: escaneo de red (nmap, masscan, hping3), descubrimiento y fuzzing web (gobuster, ffuf, nikto, wpscan, nuclei, wfuzz), inyección y explotación (sqlmap, commix, metasploit/msfconsole/msfvenom), fuerza bruta de credenciales (hydra, medusa, ncrack), cracking (hashcat, john) y enumeración o post-explotación de red o AD (enum4linux, crackmapexec, responder, evil-winrm, wifi). «Citar no es hacer»: mira lo que se ejecuta, no el texto citado, y también DENTRO de un script que el comando ejecuta (bash x.sh, ./x.sh…). Senzu ayuda con pentesting AUTORIZADO: con permiso por escrito y alcance documentados en el devlog, escape SENZU_ALLOW_PENTEST=1. No se puede apagar. |
protect-files.mjs |
PreToolUse Edit/Write | BLOQUEA editar: generados por Senzu, secretos (.env, *.pem, credentials), dependencias/artefactos, migraciones versionadas, conventions.md/json sellados (no se puede apagar), maestros del logo elegido (logos/final/) y protectedPaths del proyecto. |
secrets-guard.mjs |
PreToolUse Edit/Write | BLOQUEA escribir credenciales reales (AWS, GitHub, Stripe, OpenAI/Anthropic, PEM, JWT, cadenas con password); ignora placeholders. |
code-hygiene.mjs |
PreToolUse Edit/Write | BLOQUEA introducir (no en scripts de la carpeta temporal del agente): console.log/debugger/dd()/var_dump/ray, términos vetados en gustos.md §No, marcadores de conflicto de git, .only/.skip/xit en tests, y la lista negra anti-IA (badges de disponibilidad, numeración de secciones). Escape puntual: comentario senzu-allow. |
conventions-guard.mjs |
PreToolUse Edit/Write | BLOQUEA código que viole las reglas ejecutables de conventions.json (/adoptar): la convención del proyecto gana. No se puede apagar. La ruta se normaliza (C:, C:/, /c/ de Git Bash, relativa) antes de aplicar las reglas. |
arquitectura-guard.mjs |
PreToolUse Edit/Write | Solo si el proyecto DECLARA su arquitectura (senzu/arquitectura/capas.json, de /adoptar o /plan). BLOQUEA lo que introduce: una capa que usa otra que no puede (dominio con framework u ORM, aplicación con HTTP), un contexto de DDD que usa otro por dentro y el controlador que habla con la base de datos. AVISA del array de la petición pasado en vez de un DTO y del código nuevo fuera de las carpetas declaradas. Imports reales: use + PSR-4, import + alias de tsconfig, módulos de Python. No se puede apagar. |
backend-guard.mjs |
PreToolUse Edit/Write | BLOQUEA introducir: migraciones destructivas en la parte que se aplica (borrar o renombrar columnas o tablas: patrón expandir → contraer), env() fuera de config/ en Laravel, datos personales en logs (request completa, cuerpos, contraseñas o tokens), migraciones sin down() honesto, asignación masiva (la request entera al modelo) y errores tragados (catch vacío, except: pass). AVISA de varias escrituras en la misma función sin transacción y de consultas en bucle (N+1). Escape: senzu-allow con el motivo. |
security-guard.mjs |
PreToolUse Edit/Write | AVISA (no bloquea; una vez por archivo y sesión) de puntos de inyección que se introducen en el código: XSS (dangerouslySetInnerHTML, v-html, set:html, {@html}, Blade {!! $x !!}, innerHTML/insertAdjacentHTML/document.write con una variable), SQL injection (Prisma $queryRawUnsafe, DB::raw/whereRaw de Laravel con $, execute con f-string o concatenación en Python) e inyección de comando o ejecución dinámica (exec/execSync/shell_exec/os.system con variable, shell=True, eval). Solo mira lo introducido y el código sin comentarios. Escape por línea: senzu-allow. |
pool-guard.mjs |
PreToolUse Edit/Write | AVISA (no bloquea; una vez por archivo y sesión) de lo que agota el pool de conexiones a la BD en Node/TS y Python: new PrismaClient() sin singleton global (en serverless abre una conexión por invocación), y crear un pool/cliente/engine dentro de código por petición (rutas, controladores, endpoints). PHP-FPM queda fuera. Receta: code-quality/references/database-design.md (§Conexiones y pool). |
back-skill-reminder.mjs |
PreToolUse Edit/Write (backend) | Primera edición de backend en la sesión: recuerda la receta del stack, las convenciones selladas y la versión real del framework. No bloquea. |
depurar-coach.mjs |
PostToolUse Bash/PowerShell | Si falla un test, build o verificación que se EJECUTA (no al leer un archivo de test), activa el método de la skill depurar (reproducir, test que falla, hipótesis, acotar, arreglar la causa). Como mucho una vez cada 20 minutos. |
front-skill-reminder.mjs |
PreToolUse Edit/Write (front) | Primera edición de UI: BLOQUEA una vez si no hay design system NI brief (obliga a preguntar); después recuerda ui-ux-pro-max, el set de iconos del MASTER y las reglas duras de UI. |
format-on-save.mjs |
PostToolUse | Formatea el archivo guardado con la herramienta del stack (Pint/Prettier/ruff) si existe. Nunca bloquea. |
edit-tracker.mjs |
PostToolUse | Apunta cada archivo que toca la sesión (para cierre-limpio) y marca que se editó código (stop-guard exige verificación posterior). |
memoria-viva.mjs |
UserPromptSubmit | Si dices una regla o una corrección («no vuelvas a…», «te dije…», «a partir de ahora…»), pide al agente apuntarla en la memoria del proyecto o en la tuya (todos tus proyectos). Guarda tus últimas peticiones para /retomar. |
memoria-archivo.mjs |
PreToolUse Edit/Write | La primera vez que se va a tocar un archivo, le pasa al agente lo que la memoria y el devlog dicen de él (decisiones, lo que no funcionó). No bloquea. |
estado-sesion.mjs |
Stop · PreCompact | Guarda en qué se quedó la sesión (peticiones, archivos, lo que quedó sin commitear, tarea en curso) para la siguiente y para /retomar. Al cerrar, BLOQUEA una vez si diste una regla o corrección y no quedó apuntada en la memoria. |
arranque-guard.mjs |
PreToolUse Edit/Write (código y manifiestos) | BLOQUEA, una vez por paso y sesión, la primera edición de código si falta instalar Senzu o /adoptar (proyecto con código sin convenciones). Sin plan NO bloquea: recuerda que hay que saber qué se va a hacer y, si no está claro, hablarlo con el usuario; /plan o /brief solo si es grande. Nunca para senzu/, CLAUDE.md, AGENTS.md ni la documentación. El usuario puede quitar un paso con init.mjs –omitir-paso. |
tarjeta-guard.mjs |
PreToolUse Edit/Write (senzu/plan/PLAN.md) | BLOQUEA pasar una tarjeta a [done] sin «Verificado:» (la evidencia real), «Cumple:» (cómo cumple su «Para qué»: el objetivo del usuario o el hallazgo de la auditoría que resuelve) y un «Devlog:» que exista. Vale igual para las tarjetas del plan y las de /auditar. |
feature-guard.mjs |
Stop · PostToolUse Bash | Backend. BLOQUEA el cierre (una vez por conjunto de archivos) si la sesión tocó código de backend y ningún test, si creó o tocó migraciones sin ejecutarlas o sin probar su rollback (apunta los migrate que se ejecutan), o si el código usa variables de entorno nuevas que no están en .env.example. |
cierre-limpio.mjs |
Stop | BLOQUEA el cierre (una vez) si dejas sin commitear archivos que tocaste en esta sesión: o terminas y commiteas (en una rama), o commiteas y dices qué falta. Los cambios que NO tocaste (otro agente como Codex, otra sesión o el usuario) solo los avisa: no se commitean ni se descartan sin preguntar. |
stop-guard.mjs |
Stop | BLOQUEA el cierre (una vez) si falta: devlog del día, verify-build tras editar código, o ui-verify móvil tras tocar UI. Además avisa de assets pesados añadidos en las últimas 24 h (imágenes de más de 500 KB, fuentes sin woff2, vídeos grandes). |
pre-compact.mjs |
PreCompact | Re-inyecta lo esencial (stack, versiones, design system, plan, reglas) para sobrevivir a la compactación de contexto. |
session-end.mjs |
SessionEnd | Limpia los marcadores de sesión. |
Escapes (siempre con aprobación explícita del usuario, documentada en el devlog)
Sección titulada «Escapes (siempre con aprobación explícita del usuario, documentada en el devlog)»Las llaves SENZU_ALLOW_* van como prefijo del comando (SENZU_ALLOW_PENTEST=1 nmap …): autorizan solo ESE comando, no toda la sesión. Exportar la variable ya no abre la puerta.
SENZU_ALLOW_DEPLOY=1— deploy a producción tras la aprobación del checklist/desplegar.SENZU_ALLOW_LIB=1— instalar una librería vetada (jQuery/Bootstrap) si el usuario lo pide.- Comentario
senzu-allowen la línea — excepción puntual de code-hygiene (script CLI con console.log, test .skip justificado, patrón anti-IA pedido por su nombre). - Convenciones selladas: se cambian borrando
conventions.*y re-ejecutando/adoptar(decisión del usuario).