Hooks de Claude Code: dale a tu agente el contexto correcto en el momento justo (con ejemplos)

La documentación de Anthropic lo dice directo: Claude trata CLAUDE.md y la memoria automática como contexto, no como configuración obligatoria. Para bloquear una acción sin importar lo que Claude decida, recomienda un hook PreToolUse.

La guía de hooks los describe como control determinista: ciertas acciones siempre ocurren, en vez de depender de que el modelo decida hacerlas. Es la diferencia entre decirle algo al agente una vez y asegurarte de que lo tenga cada vez que importa.

Claude Code tiene más de treinta eventos de hooks. Para que la información correcta llegue al agente en el momento justo, estos son los útiles:

• SessionStart: al iniciar o reanudar una sesión (su entrada dice si fue startup, resume, clear, compact o fork). Lo que el hook imprime se agrega al contexto.
• UserPromptSubmit: cada vez que mandas un mensaje, antes de que Claude lo procese. El hook recibe el texto de tu mensaje en el campo prompt y puede agregar contexto para ese mensaje en particular.
• PreToolUse: justo antes de que corra una herramienta (Bash, Edit, Write, una herramienta MCP…). El hook recibe tool_name y tool_input y puede bloquear la llamada.
• PreCompact: antes de compactar el contexto, útil para guardar lo que no se debe perder.
• Stop: cuando Claude termina de responder, útil para registrar lo que pasó.

• ~/.claude/settings.json: todos tus proyectos, en tu máquina.
• .claude/settings.json: un proyecto, compartido con tu equipo por el repositorio.
• .claude/settings.local.json: un proyecto, sin compartir.
• También pueden definir hooks la configuración administrada por la organización, los plugins, los skills y los subagentes.

Las entradas de los distintos niveles se suman, no se reemplazan. El comando /hooks muestra todos los hooks configurados y de dónde vienen; para agregar o cambiar uno, se edita el JSON de configuración.

Un proyecto guarda sus decisiones en .claude/decisions.md. Este hook las carga al iniciar cada sesión, también después de una compactación:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "cat \"$CLAUDE_PROJECT_DIR/.claude/decisions.md\"" }
        ]
      }
    ]
  }
}

El texto que imprime un hook SessionStart se agrega al contexto de Claude. Si prefieres salida estructurada, devuelve JSON con hookSpecificOutput.additionalContext. En ambos casos la documentación limita cada inyección a 10,000 caracteres: si te pasas, Claude sólo recibe la ruta de un archivo y una vista previa, así que pon primero lo esencial.

Cargar todo al inicio no escala. Un hook UserPromptSubmit puede ver el mensaje y agregar sólo lo que aplica. Aquí, si el mensaje menciona un despliegue, agrega las reglas de despliegue:

#!/usr/bin/env bash
prompt=$(jq -r '.prompt')
if grep -qiE 'deploy|despleg|producci' <<<"$prompt"; then
  cat "$CLAUDE_PROJECT_DIR/.claude/context/reglas-despliegue.md"
fi
exit 0

Se registra en UserPromptSubmit igual que el Ejemplo 1. Que sea rápido: en este evento el tiempo límite por defecto es de 30 segundos y el agente lo espera.

Ejemplo ilustrativo: un equipo decidió que nadie hace force-push, porque una vez reescribió la historia compartida. En vez de confiar en que el agente se acuerde, un hook PreToolUse lo detiene:

#!/usr/bin/env bash
cmd=$(jq -r '.tool_input.command // empty')
if grep -qE 'git push.*(--force|-f( |$))' <<<"$cmd"; then
  echo "Bloqueado: en este repositorio no se hace force-push (ya reescribió la historia compartida)." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/sin-force-push.sh\"" }
        ]
      }
    ]
  }
}

El código de salida 2 bloquea la llamada y Claude ve el mensaje de stderr como el motivo, así que puede buscar otro camino. Cualquier otro código distinto de cero no bloquea: la acción sigue y sólo se muestra un error del hook. La alternativa estructurada es salir con 0 y devolver hookSpecificOutput.permissionDecision en "deny" con un permissionDecisionReason.

Un archivo en el repositorio sirve para un proyecto en una máquina. Se queda corto cuando la decisión se tomó en otra herramienta (ChatGPT, Cursor), en otra máquina o en otro proyecto, o cuando deja de ser cierta y nadie actualiza el archivo.

NEXUS es una fuente de esa información para todos tus agentes: lo que cualquiera de ellos registra (decisiones, reglas del negocio, incidentes y cómo se corrigieron) se le entrega a los demás. En Claude Code llega por hooks: uno al iniciar la sesión con el resumen (metas activas, tareas pendientes), uno en cada mensaje con lo relevante para ese mensaje y uno al terminar el turno que guarda lo que pasó. Sólo se instalan si los apruebas: pídele a tu agente la herramienta get_setup_kit después de conectar NEXUS.

Para ser precisos con lo que hace hoy: los hooks de NEXUS entregan contexto; no bloquean acciones. Para bloquear, escribe tu propio hook PreToolUse como el del Ejemplo 3.

Para conectarlo: crea una cuenta gratis en https://nexus.eblas.link/signup, luego ejecuta claude mcp add --transport http nexus-agi https://nexus.eblas.link/mcp y autoriza con /mcp.

• Los hooks ejecutan comandos en tu máquina con tus permisos. Lee cada script antes de agregarlo, incluidos los nuestros.
• Los scripts de ejemplo necesitan jq para leer el JSON que recibe el hook y deben ser ejecutables: chmod +x .claude/hooks/*.sh.
• Que sean rápidos y seguros ante fallas: si la fuente de información no responde, el hook no debe imprimir nada y salir con 0, no detener tu trabajo.
• Sólo el código de salida 2 bloquea. Úsalo a propósito y explica siempre el motivo en stderr.

Comandos, llamadas HTTP o prompts que Claude Code ejecuta automáticamente en momentos específicos de la sesión, como al iniciarla, en cada mensaje o antes de usar una herramienta. Se configuran en el JSON de configuración y siempre corren, a diferencia de las instrucciones de CLAUDE.md.

Con un hook SessionStart o UserPromptSubmit: el texto que imprime se agrega al contexto de Claude, o puede devolver JSON con hookSpecificOutput.additionalContext. Cada inyección tiene un límite de 10,000 caracteres.

Con un hook PreToolUse que sale con código 2 y escribe el motivo en stderr; Claude ve ese motivo. Otra opción es salir con 0 y devolver JSON con hookSpecificOutput.permissionDecision en "deny".

No. CLAUDE.md sigue siendo el lugar para las reglas estables del proyecto. NEXUS agrega lo que viene de tus otros agentes, máquinas y proyectos, y lo entrega por hooks cuando es relevante.