Claude Code / Codex / Cursor Agent Hooks: configuración comparada, PreToolUse, script mínimo y prueba de fail-open

Las instrucciones, AGENTS.md y los skills son sugerencias que el modelo puede ignorar; los hooks son scripts deterministas que el harness ejecuta en momentos fijos. Este artículo compara las rutas de configuración, nombres de eventos, exit 2 / deny, fail-open y fail-closed de Claude Code, Codex y Cursor para PreToolUse (o su equivalente), e incluye un script mínimo de intercepción probado en Claude Code.

9 分钟阅读
Claude Code / Codex / Cursor Agent Hooks: configuración comparada, PreToolUse, script mínimo y prueba de fail-open

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 usa preToolUse (o el más específico beforeShellExecution). 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-me fue interceptado por PreToolUse (exit 2); echo hooks-allow-ok pasó 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

ElementoClaude CodeCodexCursor
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 herramientaPreToolUsePreToolUsepreToolUse; para comandos de shell también beforeShellExecution
Después de llamada a herramientaPostToolUsePostToolUsepostToolUse / afterFileEdit, etc.
Nombre de la herramienta Shell (matcher)BashBashShell (beforeShellExecution hace match sobre el texto del comando)
Bloqueoexit 2, o JSON permissionDecision: "deny"exit 2, o JSON permissionDecision: "deny" / antiguo decision: "block"exit 2, o JSON permission: "deny"
Fallo de hook por defectoLa 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ónLa confianza del workspace afecta a los hooks de proyectoLos 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:

  1. Instrucciones y preferencias → AGENTS.md / skills (explican intención, estilo, flujo).
  2. Reglas que deben cumplirse siempre → hooks (interceptan comandos peligrosos, reescriben comandos de build, auditan, registran el cierre de sesión).
  3. No uses los hooks como única defensa → algunos caminos saltan los hooks (por ejemplo, la documentación de Codex indica que write_stdin al 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.

bash
#!/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:

json
{
  "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:

json
{
  "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:

json
{
  "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.

  1. Ruta de paso: se pidió al modelo ejecutar echo hooks-allow-ok → salida hooks-allow-ok, en unos 8 segundos.
  2. 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:
text
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
  1. 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

EscenarioRecomendaciónCómo configurarlo
Conveniencia (filtrar logs de build, autoformat)fail-openEl 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-closedClaude Code: onFailure: "block"; Cursor: failClosed: true; y prueba tú mismo que "si se borra el script, la herramienta queda bloqueada"
Políticas gestionadas en CodexSegún requirements.toml empresarial / managed hooksVer 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

  1. 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.
  2. Timeout corto: el agente espera al hook; 5 segundos es habitual para hooks de conveniencia a nivel de usuario.
  3. Limita los bucles con Stop / stop: Cursor tiene loop_limit (por defecto 5) para stop / subagentStop; no dejes que "una nota al terminar" se convierta en un bucle infinito.
  4. No mezcles los nombres del matcher: la herramienta de shell en Claude Code / Codex se llama Bash; en Cursor, para el matcher general, se llama Shell.
  5. 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.toml global, usa experimental_bearer_token, name = "aicodewith", base_url = "https://api.aicodewith.ai/chatgpt/v1" (nota: es /chatgpt/v1, no /v1 a secas).

Crear API Key →

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 →

Fuentes

相关文章

Qué es el UI SDK y cómo se usa? La biblioteca de comportamientos de Vercel y shadcn para agentes, instalada y probada en Claude Code / Codex / Cursor (0.1.0-beta.1)

Qué es el UI SDK y cómo se usa? La biblioteca de comportamientos de Vercel y shadcn para agentes, instalada y probada en Claude Code / Codex / Cursor (0.1.0-beta.1)

El UI SDK es la biblioteca de comportamientos de Vercel para agentes, publicada el 12 de noviembre de 2026 como 0.1.0-beta.1. Los comportamientos viven en el paquete independiente del framework @ui-sdk/core y los renderizan adaptadores para React, Vue, Svelte, Solid y Web Components. Esta guía sigue la documentación oficial sobre qué es, cómo instalarlo y cómo añadir el skill para Claude Code, Codex y Cursor, y registra los comandos, tiempos y salidas de nuestra máquina de prueba.

¿Qué es AWS Emulator y cómo se instala? Prueba apps de AWS en local con Claude Code y Codex (probado en 1.0.322)

¿Qué es AWS Emulator y cómo se instala? Prueba apps de AWS en local con Claude Code y Codex (probado en 1.0.322)

AWS Emulator es el emulador local oficial de las API de AWS, con disponibilidad general desde el 11 de noviembre de 2026 (hora de EE. UU.). No tiene cargo adicional por el servicio, su código es abierto, no necesita cuenta de AWS y cubre más de 200 servicios. Probamos la versión 1.0.322 en Debian 13: comandos de instalación, AWS CLI apuntando al endpoint local para crear un bucket de S3 y una tabla de DynamoDB, los errores que encontramos y cómo hacer que Claude Code, Codex y Cursor escriban y prueben código contra el emulador.

¿Qué es T3 Code y cómo se instala? Conectar Claude Code y Codex, usar una API Key de terceros y resolver errores comunes (probado en 0.1.9)

¿Qué es T3 Code y cómo se instala? Conectar Claude Code y Codex, usar una API Key de terceros y resolver errores comunes (probado en 0.1.9)

T3 Code es la consola de código abierto de pingdotgg para manejar agentes de programación. No trae modelo propio: controla los CLI de Claude Code, Codex, Cursor y otros que ya tienes instalados. Probamos T3 Code 0.1.9 en Linux. Esta guía cubre los comandos de instalación, cómo conectar Claude Code y Codex a una API Key de AICodeWith para que T3 Code los controle, una ejecución completa de ambos agentes con el comando t3 thread y los errores que encontramos, con su solución.