Conclusión directa:
- AGENTS.md / skills / instrucciones de sistema son sugerencias: el modelo las lee, pero puede olvidarlas o saltárselas.
- Los hooks son scripts que ejecuta el harness: se lanzan en momentos fijos (antes o después de una llamada a herramienta) sin depender de que el modelo "recuerde" las reglas.
- Los tres entornos pueden interceptar llamadas a herramienta: Claude Code / Codex usan
PreToolUse; Cursor usapreToolUse(o el más específicobeforeShellExecution). La forma más habitual de bloquear es con exit code 2 o devolviendo un JSON de deny. - El comportamiento por defecto suele ser fail-open: si el script falla, supera el timeout o sale con un código distinto de 0 o 2, la llamada a herramienta suele continuar. Las políticas de seguridad deben configurarse explícitamente como fail-closed (Claude Code:
onFailure: "block"; Cursor:failClosed: true). Según la documentación oficial de Codex, un fallo de hook genera un hook failure pero no se trata como bloqueo duro por defecto. - Probado en Claude Code: un Bash que coincide con
rm -rf /tmp/hooks-deny-mefue interceptado por PreToolUse (exit 2);echo hooks-allow-okpasó sin problemas. Cursor no puede probarse de forma equivalente en un entorno sin interfaz gráfica local; la configuración de Cursor se recoge de la documentación oficial y no se afirma haber sido probada.
Según el artículo de SwiftLee / Antoine van der Lee del 02-11-2026 y el retweet de @peterfriese en X: los hooks son mucho más fiables que escribir reglas en AGENTS.md. El resto del artículo se basa en la documentación oficial de cada plataforma; donde haya discrepancias con artículos de terceros, prevalece la oficial y se indica la fuente.
Contexto relacionado: los plugins pueden registrar hooks de SessionStart de forma silenciosa (ver revisión y eliminación del plugin Postman); AGENTS.md también puede verse afectado por el contexto de directorios (ver secuestro por directorio Downloads). Los hooks no reemplazan la recomendación de no abrir el agente en Downloads, pero sí permiten aplicar reglas duras que el markdown no puede garantizar. Para MCP y límites de permisos, ver la guía de seguridad Codex Playwright MCP; para la división de responsabilidades entre skills y hooks, ver cómo usar Skills en un AI Agent.
Tabla comparativa de un vistazo
| Elemento | Claude Code | Codex | Cursor |
|---|---|---|---|
| Configuración de usuario | ~/.claude/settings.json | ~/.codex/hooks.json o config.toml | ~/.cursor/hooks.json |
| Configuración de proyecto | .claude/settings.json | .codex/hooks.json o config.toml | .cursor/hooks.json (requiere workspace de confianza) |
| Antes de llamada a herramienta | PreToolUse | PreToolUse | preToolUse; para comandos de shell también beforeShellExecution |
| Después de llamada a herramienta | PostToolUse | PostToolUse | postToolUse / afterFileEdit, etc. |
| Nombre de la herramienta Shell (matcher) | Bash | Bash | Shell (beforeShellExecution hace match sobre el texto del comando) |
| Bloqueo | exit 2, o JSON permissionDecision: "deny" | exit 2, o JSON permissionDecision: "deny" / antiguo decision: "block" | exit 2, o JSON permission: "deny" |
| Fallo de hook por defecto | La mayoría de eventos continúan (fail-open); se puede configurar onFailure: "block" | Genera hook failure, no trata el fallo como bloqueo duro (según documentación oficial de Hooks) | fail-open por defecto; se puede configurar failClosed: true |
| Confianza / revisión | La confianza del workspace afecta a los hooks de proyecto | Los hooks no gestionados requieren revisión con /hooks y trust; se puede usar --dangerously-bypass-hook-trust (puntual) | Los hooks de proyecto solo se cargan en workspaces de confianza |
Documentación oficial: Claude Code Hooks · Codex Hooks · Cursor Hooks.
Por qué no basta con escribir en AGENTS.md
Según la experiencia descrita en el artículo de SwiftLee: tras escribir "filtrar la salida de xcodebuild" en las instrucciones globales, el agente seguía metiendo los logs en bruto en el contexto. El texto de las instrucciones entra en el prompt y el modelo decide si las sigue; el hook se ejecuta en la capa del harness, sin que el modelo tenga ningún veto sobre si el hook se lanza o no.
División recomendada:
- Instrucciones y preferencias → AGENTS.md / skills (explican intención, estilo, flujo).
- Reglas que deben cumplirse siempre → hooks (interceptan comandos peligrosos, reescriben comandos de build, auditan, registran el cierre de sesión).
- No uses los hooks como única defensa → algunos caminos saltan los hooks (por ejemplo, la documentación de Codex indica que
write_stdinal sondear un comando que ya pasó PreToolUse no vuelve a ejecutar PreToolUse).
Script mínimo: interceptar un Bash peligroso (fail-open)
El siguiente script vale para los tres entornos: lee el JSON de stdin, extrae el comando; si hay coincidencia, bloquea; si no, deja pasar; si el parseo falla, hace exit 0 (fail-open). Guárdalo como ejecutable, por ejemplo en ~/.agents/hooks/block-rm-demo.sh.
#!/bin/bash
# fail-open: si falta jq o el JSON es incorrecto → exit 0, no bloquea el trabajo
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)
if [[ -z "$command" ]]; then
exit 0
fi
if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
# Cursor: si hay campo cursor_version, usar JSON deny (según documentación oficial de Cursor Hooks y escritura del artículo de SwiftLee)
if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
exit 0
fi
# Claude Code / Codex: stderr + exit 2
echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
exit 2
fi
exit 0
Aplica chmod +x antes de registrarlo en la configuración.
Registro en Claude Code
En ~/.claude/settings.json o en .claude/settings.json del proyecto:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
"timeout": 5
}
]
}
]
}
}
A nivel de usuario se puede usar una ruta absoluta. Para hooks de política de seguridad se recomienda añadir "onFailure": "block" (requiere versión reciente; ver la referencia oficial de Hooks), para evitar que un error en la ruta del script desactive toda la política.
Registro en Codex
La estructura es similar a Claude Code; se coloca en ~/.codex/hooks.json o en .codex/hooks.json del proyecto:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
"timeout": 5,
"statusMessage": "Checking Bash command"
}
]
}
]
}
}
Nota: Codex exige revisar los hooks no gestionados con /hooks en la CLI y darles trust; los hooks a nivel de proyecto además requieren que el directorio .codex/ del proyecto sea de confianza. Para automatización puntual existe --dangerously-bypass-hook-trust (documentación oficial). Se pueden deshabilitar globalmente con [features] hooks = false.
Registro en Cursor
El hooks.json de Cursor es más plano y requiere el campo version:
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "~/.agents/hooks/block-rm-demo.sh",
"matcher": "Shell",
"timeout": 5
}
]
}
}
La ruta de proyecto es relativa a la raíz del repositorio, por ejemplo .cursor/hooks/block-rm-demo.sh. Para hooks críticos de seguridad, añade "failClosed": true. También puedes usar beforeShellExecution, donde el matcher hace match directamente sobre el texto del comando (p. ej. rm\\s+-rf).
Prueba: Claude Code PreToolUse (clave propia del sitio)
Entorno: Claude Code CLI 2.1.319, .claude/settings.json dentro del proyecto con el script fail-open anterior registrado, ejecutado en modo no interactivo -p a través de la interfaz compatible de aicodewith.
- Ruta de paso: se pidió al modelo ejecutar
echo hooks-allow-ok→ salidahooks-allow-ok, en unos 8 segundos. - Ruta de bloqueo: se pidió al modelo ejecutar
rm -rf /tmp/hooks-deny-me→ devolvió error de PreToolUse hook, el comando no se ejecutó, en unos 9 segundos. Fragmento del error:
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
- fail-open a nivel unitario: se alimentó stdin con JSON inválido → el script hace exit 0 (no bloquea lo siguiente).
Cursor no fue probado de forma equivalente en un entorno sin interfaz gráfica local; la columna de Cursor en la tabla se basa en la documentación oficial de Cursor Hooks. La configuración de Codex se ha contrastado con la documentación oficial; para esta prueba de integración se eligió únicamente la cadena de Claude Code para no duplicar el consumo.
Si usas Codex, registra el mismo script en PreToolUse + matcher Bash, haz el trust con /hooks y pide que ejecute un comando que coincida y otro que no para validarlo por tu cuenta.
fail-open o fail-closed
| Escenario | Recomendación | Cómo configurarlo |
|---|---|---|
| Conveniencia (filtrar logs de build, autoformat) | fail-open | El comportamiento por defecto es suficiente; el script también hace exit 0 si el parseo falla |
| Seguridad / cumplimiento (prohibir borrado, filtrado de datos, modificación de archivos de claves) | fail-closed | Claude Code: onFailure: "block"; Cursor: failClosed: true; y prueba tú mismo que "si se borra el script, la herramienta queda bloqueada" |
| Políticas gestionadas en Codex | Según requirements.toml empresarial / managed hooks | Ver documentación oficial de Managed hooks; los hooks de usuario local no bloquean por defecto en caso de fallo |
Según el artículo de SwiftLee: los hooks de conveniencia deben ser fail-open para que un hook roto no te impida trabajar; solo los hooks que bloquean operaciones peligrosas deben ser fail-closed.
Puntos de atención comunes a los tres entornos
- Lee antes de activar: los hooks que vienen con un repositorio o plugin son scripts locales con los mismos permisos que tú. Plugins como Postman han instalado hooks de SessionStart de forma automática; revisa qué hay registrado antes de instalar.
- Timeout corto: el agente espera al hook; 5 segundos es habitual para hooks de conveniencia a nivel de usuario.
- Limita los bucles con Stop / stop: Cursor tiene
loop_limit(por defecto 5) parastop/subagentStop; no dejes que "una nota al terminar" se convierta en un bucle infinito. - No mezcles los nombres del matcher: la herramienta de shell en Claude Code / Codex se llama
Bash; en Cursor, para el matcher general, se llamaShell. - Hooks ≠ skills: los skills son paquetes de capacidades que se invocan por nombre o descripción; los hooks se disparan por eventos, sin que nadie los llame explícitamente.
Usar una clave de aicodewith con Claude Code / Codex (opcional)
Probar hooks no depende de ningún proveedor de modelo concreto. Si accedes a los modelos a través de aicodewith:
- Claude Code: configura la Base URL compatible y la clave según la documentación del sitio.
- Codex: en
~/.codex/config.tomlglobal, usaexperimental_bearer_token,name = "aicodewith",base_url = "https://api.aicodewith.ai/chatgpt/v1"(nota: es/chatgpt/v1, no/v1a secas).
Preguntas frecuentes
¿Qué diferencia hay entre hooks y AGENTS.md?
AGENTS.md entra en el contexto y el modelo puede ignorarlo; los hooks los ejecuta directamente Claude Code / Codex / Cursor en eventos del ciclo de vida. La intención va en el markdown; las restricciones duras van en los hooks.
¿Exit code 2 o JSON deny?
Ambos bloquean. Claude Code / Codex suelen usar stderr + exit 2; cuando se necesita una razón estructurada o reescribir la entrada se usa JSON (permissionDecision / updatedInput). Cursor en hooks de permission prefiere el campo permission en el JSON de stdout; exit 2 también equivale a deny.
¿Por qué no se ejecutan los hooks de mi proyecto?
Comprueba: si el workspace / proyecto es de confianza; si en Codex has hecho el trust con /hooks; si las rutas son correctas (los hooks de proyecto en Cursor son relativas a la raíz del repositorio); si el nombre del matcher corresponde al de la herramienta; en Claude Code puedes usar el menú /hooks para verificar el origen.
¿Pueden los hooks reemplazar completamente una política de seguridad?
No. La documentación oficial reconoce que algunos caminos no pasan por los hooks; además, los plugins y scripts de SessionStart son en sí mismos una superficie de riesgo. Los hooks son una capa de protección determinista que debe combinarse con el modelo de permisos, la gestión de claves y la elección del directorio de trabajo.
¿Es fiable ask en preToolUse de Cursor?
Según la documentación oficial de Cursor: en preToolUse, el valor "ask" en la salida no se aplica de forma forzosa actualmente; para bloquear una operación usa "deny" o exit 2. Eventos como beforeShellExecution sí admiten allow / deny / ask.
Resumen
Eleva las reglas que "el modelo debería recordar" a hooks que "el harness ejecuta siempre". Empieza con un script mínimo de PreToolUse / preToolUse: matcher apuntando a Bash o Shell, exit 2 / deny en caso de coincidencia, fail-open por defecto y fail-closed solo para escenarios de seguridad. Los archivos de configuración y los nombres de eventos difieren entre Claude Code, Codex y Cursor, pero el esquema evento → matcher → script → decisión es el mismo en los tres.
Crear API Key → · Ver modelos y documentación de integración →



