Los hooks para agentes de código son la capa que convierte una recomendación de seguridad en un límite ejecutable. El agente todavía razona, lee archivos, llama herramientas e intenta corregirse. La diferencia es que los comandos sensibles pasan por gates previsibles antes de tocar red, secretos, shell, MCP o archivos críticos.

En la documentación actual, Claude Code organiza hooks en 3 cadencias: una vez por sesión, una vez por turno y en cada llamada de herramienta dentro del loop agentic (Claude Code Docs, "Hooks reference", consultado el 2026-07-05). Ese detalle cambia la arquitectura: la seguridad deja de ser prompt y se vuelve punto de interceptación.

Resumen práctico

  • Usa PreToolUse para negar riesgo antes de ejecutar.
  • Usa PostToolUse para recolectar evidencia y corregir rumbo.
  • Usa Stop para exigir prueba antes del resumen final.
  • Trata MCP, setup y red como fronteras de permiso.

Flujo abstracto muestra un agente de código pasando por gates, sandbox y revisión sin texto visible.

¿Por qué los hooks se volvieron una capa de seguridad?

En la documentación actual, PreToolUse y PostToolUse corren en cada llamada de herramienta dentro del loop agentic (Claude Code Docs, "Hooks reference", consultado el 2026-07-05). Los hooks se volvieron capa de seguridad porque el riesgo real aparece cuando el agente intenta ejecutar, no cuando promete seguir instrucciones.

El problema práctico es simple: los buenos agentes obedecen contexto, setup, errores de terminal y documentación local. Eso es excelente para productividad. También crea una superficie donde contenido no confiable puede empujar una acción peligrosa con apariencia de mantenimiento normal.

En junio de 2026, 0din publicó "Clone This Repo and I Own Your Machine", donde describe un ataque en el que un repositorio aparentemente normal llevó a un agente a abrir una shell reversa mediante setup, manejo rutinario de errores y una carga buscada en DNS (0din, "Clone This Repo and I Own Your Machine", consultado el 2026-07-05). El punto no es una herramienta específica. Es la clase de riesgo.

Si ya montaste un harness para PRs confiables de agentes, los hooks son el siguiente paso natural. El harness define criterios. El hook aplica esos criterios en el momento correcto.

Cápsula citable: Los hooks para agentes de código reducen riesgo porque interceptan la acción en el punto de ejecución. La documentación de Claude Code separa hooks por sesión, turno y llamada de herramienta, lo que permite negar comandos antes del shell, registrar evidencia después de la acción y bloquear el cierre del loop sin prueba.

¿Dónde entra el hook en el loop agentic?

En la documentación actual, la tabla de eventos de Claude Code lista eventos como SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, Stop y SessionEnd (Claude Code Docs, "Hooks reference", consultado el 2026-07-05). El hook entra donde una decisión cambia costo, riesgo o evidencia.

Piensa en el loop como cuatro momentos. Primero, el agente recibe intención y contexto. Luego elige una herramienta. Después observa el resultado. Por último, decide si continúa, se corrige o termina. No necesitas hooks en todas partes; necesitas hooks en la frontera donde una falla saldría cara.

PreToolUse es el gate de permiso. Sirve para negar git push, curl suelto, npm install en repositorio desconocido, lectura de .env y comandos cloud que alteran estado. Esa decisión debe ser determinística, corta y auditable.

PostToolUse es el gate de evidencia. Puede ejecutar lint sobre el archivo editado, guardar diff, exigir la prueba más cercana o marcar que una herramienta MCP devolvió dato externo. Si la evidencia falla, el agente recibe un motivo concreto para intentar otra ruta.

Stop es el gate de listo. No debe volverse ceremonia; debe impedir un resumen final que dice "hecho" sin prueba, diff, riesgo residual y próximo paso. Esto conversa directamente con evals de PR en CI.

Loop abstracto muestra acción, gate, evidencia y retry de agentes de código sin texto visible.

Cápsula citable: El lugar correcto del hook es la frontera de decisión. PreToolUse bloquea antes de la acción, PostToolUse convierte resultado en evidencia y Stop impide cerrar sin prueba. Esa división mantiene autónomo al agente, pero le quita permiso implícito para cruzar riesgo sin control.

¿Qué debe ser deny, ask o allow?

En la documentación actual, el sistema de permisos de Claude Code separa reglas en allow, ask y deny, y evalúa en este orden efectivo: negar, preguntar y permitir (Claude Code Docs, "Configure permissions", consultado el 2026-07-05). Ese orden importa porque una negación amplia no debe depender de la cooperación del modelo.

Usa allow para comandos repetitivos, locales y reversibles. Pruebas, typecheck, lectura y generación de artefacto temporal suelen entrar aquí. Aun así, prefiere comandos exactos. npm test es más seguro que permitir cualquier cosa que empiece por npm.

Usa ask cuando la acción puede ser legítima, pero necesita intención humana. Actualizar lockfile, instalar dependencia, abrir red, correr migración local y cambiar workflow de CI son buenos candidatos. El objetivo no es congelar al agente; es marcar transición de riesgo.

Usa deny para fronteras que no tienen sentido en una sesión agentic común. Leer secretos, escribir en .git, desplegar, publicar paquete, cambiar credencial, borrar directorios amplios y acceder a dominio inesperado deben fallar temprano.

En mi práctica, empiezo con una matriz pequeña. Una línea para shell. Una para archivos sensibles. Una para red. Una para MCP. Si la regla no cabe ahí, probablemente todavía es opinión, no política operativa.

Superficie Patrón inicial Motivo
Pruebas locales allow con comando exacto Da autonomía sin riesgo alto.
Instalación y red ask por defecto Setup puede esconder carga externa.
Secretos y credenciales deny explícito El agente no necesita leerlos para codar.
Deploy y push deny en dev local Cambio externo exige humano.

Cápsula citable: La matriz allow, ask y deny evita confundir autonomía con permiso irrestricto. La documentación de Claude Code afirma que deny, ask y allow tienen precedencia definida, así que los comandos irreversibles deben estar en deny, mientras pruebas locales pueden recibir allow estrecho y auditable.

¿Cómo cambia MCP la amenaza?

En la especificación de 2025-06-18, MCP define 3 roles centrales: hosts, clients y servers, además de recursos, prompts y herramientas expuestos por servidores (Model Context Protocol, "Specification", consultado el 2026-07-05). MCP cambia la amenaza porque una herramienta externa pasa a formar parte del loop del agente.

MCP es excelente cuando entrega contexto bajo demanda, como búsqueda en codebase, issue tracker, base de datos de lectura o documentación interna. El riesgo aparece cuando el servidor combina escritura, red, credenciales y descripciones de herramienta que el agente trata como confiables.

La propia especificación alerta que las herramientas representan caminos de ejecución de código y exigen cautela, consentimiento y autorización. Eso debe convertirse en política local. Un servidor MCP de lectura no debería volverse servidor de escritura solo porque la herramienta existe.

Empieza con allowlist por servidor. Da permiso de lectura a servidores de contexto. Exige confirmación para herramientas que escriben, crean issues, comentan PRs o disparan workflows. Bloquea servidores desconocidos en proyectos sensibles.

Ese patrón profundiza la idea de MCP de codebase RAG para agentes. MCP es mejor cuando reduce contexto y amplía precisión; se vuelve peligroso cuando amplía autoridad sin gate.

Cápsula citable: MCP no es solo contexto; es superficie de herramienta. La especificación de 2025-06-18 define hosts, clients y servers, y advierte que tools pueden abrir caminos de ejecución. Por eso los servidores MCP deben entrar al harness con allowlist, alcance de lectura y confirmación para escritura.

¿Cómo diseñar un hook sin teatro de seguridad?

En la documentación actual, los hooks pueden devolver decisiones como negar una llamada de herramienta en PreToolUse, mientras una salida silenciosa mantiene el flujo normal de permiso (Claude Code Docs, "Hooks reference", consultado el 2026-07-05). Un buen hook es pequeño, testeable y aburrido a propósito.

Evita hooks que intentan "entender intención" con lenguaje vago. Eso pertenece al agente. El hook debe checar hechos: comando, ruta, dominio, tipo de herramienta, branch, archivo cambiado, presencia de secreto o prueba de test.

Un PreToolUse de shell puede bloquear borrado amplio, red vía shell y deploy. Un PostToolUse puede registrar comando, salida resumida, archivos tocados y estado. Un Stop puede negar finalización si el agente cambió código sin prueba o explicación.

El insight útil es separar "el agente decide el plan" de "el harness decide el permiso". Cuando esos papeles se mezclan, vuelves a depender del prompt. Cuando quedan separados, el agente puede ser creativo dentro de una caja clara.

En flujos largos, el contexto también se vuelve costo y riesgo. Uso RemoteCode como extensión de contexto para Claude Code y Codex en flujos agentic largos cuando quiero que el agente llegue más lejos sin volcar todo el historial al prompt principal; es una herramienta mía, así que la referencia aquí es editorial y contextual.

Cápsula citable: Un buen hook no intenta reemplazar el juicio humano ni el razonamiento del agente. Verifica hechos observables: comando, ruta, dominio, herramienta y evidencia. Esa separación deja trabajar con autonomía a Claude Code, Codex y subagentes, mientras el harness aplica límites determinísticos.

¿Cuál es un diseño mínimo para empezar?

En la documentación actual, las configuraciones de Claude Code tienen alcances de usuario, proyecto, local y gestionado, y el alcance gestionado tiene mayor precedencia (Claude Code Docs, "Claude Code settings", consultado el 2026-07-05). El diseño mínimo debe empezar en el proyecto y subir a política gestionada cuando se vuelve estándar de equipo.

Empieza con tres archivos o bloques: permisos, hooks y criterios de listo. Permisos dicen qué entra en allow, ask y deny. Hooks aplican los bordes. Criterios de listo dicen qué evidencia debe encontrar Stop.

Para un repositorio TypeScript, empezaría así: permitir npm test y npm run typecheck, preguntar antes de npm install, negar lectura de .env, negar git push y bloquear shell con red en repositorio recién clonado.

Después agrega un PostToolUse para correr la prueba cercana cuando cambien archivos de src/. Si la prueba falla, el agente recibe el error e intenta corregir. Si no hay prueba cercana, debe declarar el motivo en el resumen final.

Matriz abstracta muestra zonas de permiso, revisión y bloqueo para agentes de código sin texto visible.

Ese mínimo combina con AGENTS.md ligero para agentes de código. AGENTS.md orienta comportamiento. Hooks y permisos imponen fronteras. CI confirma la prueba.

Cápsula citable: Un diseño mínimo de hooks empieza con permisos estrechos, bloqueo de secretos, confirmación para red y gate final de evidencia. Como Claude Code separa alcances de usuario, proyecto, local y gestionado, los equipos pueden probar en el proyecto antes de promover política para todos.

Preguntas frecuentes sobre hooks para agentes de código

¿Un hook reemplaza la revisión humana?

No. En la documentación actual, los hooks interceptan eventos como PreToolUse, PostToolUse y Stop, pero no evalúan solos impacto de producto. Usa hook para negar riesgo mecánico y exigir evidencia. Usa revisión humana para arquitectura, comportamiento de negocio y decisión de merge.

¿Necesito hook si ya tengo CI?

Sí, cuando el agente puede ejecutar acciones antes del CI. El CI atrapa el PR. El hook atrapa comando local, herramienta MCP, setup y cierre de sesión. En la práctica, hook reduce daño antes del commit; CI valida el resultado después.

¿Qué queda en AGENTS.md y qué se vuelve hook?

AGENTS.md debe orientar elección, comando y criterio. Hook debe imponer límite. Si la regla es "prefiere correr prueba cercana", escríbela en AGENTS.md. Si la regla es "no leas .env", ponla en permiso o hook. Prompt no es frontera de seguridad.

¿Los hooks funcionan con subagentes?

Sí, cuando la herramienta expone eventos de subagentes. La documentación de Claude Code lista SubagentStart y SubagentStop, además de eventos de herramienta. Usa eso para registrar fan-out, limitar alcance y exigir que cada subagente devuelva evidencia, no solo conclusión.

¿Cómo evito hooks demasiado lentos?

Usa matcher estrecho. La documentación de Claude Code permite filtrar eventos por herramienta, agente o patrón. No ejecutes script pesado en cada llamada. Bloquea antes del riesgo, recolecta evidencia después de escritura y deja el test caro para CI cuando el feedback local no cambia la decisión.

Cierre

Los agentes de código necesitan autonomía, pero autonomía sin borde se convierte en permiso accidental. Hooks resuelven eso porque actúan en el punto donde el agente intenta cruzar una frontera: shell, red, secreto, MCP, subagente, escritura y cierre.

Empieza pequeño. Bloquea secretos, pregunta antes de red, permite pruebas exactas y exige prueba antes del resumen final. Después conecta el mismo patrón a tus evals de PR, a tu MCP de codebase y a tu fan-out de subagentes. El agente sigue rápido. Solo deja de correr suelto donde el daño cuesta caro.

Fuentes consultadas

  • Claude Code Docs, "Hooks reference", consultado el 2026-07-05, https://code.claude.com/docs/en/hooks
  • Claude Code Docs, "Configure permissions", consultado el 2026-07-05, https://code.claude.com/docs/en/permissions
  • Claude Code Docs, "Claude Code settings", consultado el 2026-07-05, https://code.claude.com/docs/en/settings
  • Model Context Protocol, "Specification 2025-06-18", consultado el 2026-07-05, https://modelcontextprotocol.io/specification/2025-06-18
  • 0din, "Clone This Repo and I Own Your Machine", consultado el 2026-07-05, https://0din.ai/blog/clone-this-repo-and-i-own-your-machine