Hooks de Claude Code: control determinista sobre lo que hace el agente

Anatomía de un hook

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

Tres partes: el evento, un patrón de coincidencia (una expresión regular sobre el nombre de la herramienta para los eventos de herramientas; omítelo para que coincida con todo) y uno o más comandos. El comando recibe en stdin un objeto JSON que describe el evento; para los eventos de herramientas, incluye tool_name y tool_input, que es lo que permite al ejemplo anterior encontrar el archivo que se acaba de editar. Colócalo en .claude/settings.json para compartirlo con el repositorio, ~/.claude/settings.json para uso personal, o ejecuta /hooks y deja que Claude Code lo escriba.

Los eventos

• PreToolUse — antes de que se ejecute una herramienta. El único evento que puede bloquear: el código de salida 2 cancela la llamada y Claude lee tu stderr como motivo.
• PostToolUse — después de que una herramienta se ejecute correctamente. Formateadores, analizadores de código y comprobaciones de tipos sobre el archivo editado.
• UserPromptSubmit — cuando envías un prompt; puede incorporar contexto o rechazar el prompt.
• Stop / SubagentStop — cuando el agente (o un subagente) está a punto de finalizar. Aquí, el código de salida 2 significa «aún no ha terminado»; el uso clásico consiste en impedir que finalice mientras las pruebas fallen.
• PreCompact — antes de /compact; guarda todo lo que necesites de la transcripción completa.
• SessionStart — cuando una sesión comienza o se reanuda; carga el entorno e imprime recordatorios.
• Notification — cuando Claude Code necesita tu atención (solicitud de permiso, inactividad); conéctalo a una notificación de escritorio o de Slack.

Bloquear comandos peligrosos

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

El código de salida 2 es el contrato: la llamada a la herramienta no se realiza y todo lo que el hook haya escrito en stderr se convierte en la explicación que ve Claude, para que pueda elegir otro enfoque en lugar de volver a intentar lo mismo. Cualquier otro código de salida distinto de cero se registra, pero no bloquea.

«No finalices hasta que las pruebas pasen»

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Combínalo con un límite de --max-turns en las ejecuciones sin interfaz para que un fallo realmente imposible de corregir no genere un bucle infinito.

Hooks frente a CLAUDE.md y permisos

CLAUDE.md contiene recomendaciones que el modelo lee; /permissions es una lista de lo que puede hacer sin preguntar; los hooks son código que se ejecuta en cualquier caso. Usa CLAUDE.md para el estilo y el contexto, los permisos para delimitar qué se permite y qué requiere aprobación, y los hooks para todo lo que deba cumplirse siempre: formato, detección de secretos, controles de pruebas y registros de auditoría. Se combinan: un permiso permite ejecutar Bash(git *) , pero un hook PreToolUse sigue bloqueando git push --force.

Los hooks y la pasarela

Los hooks se ejecutan localmente y nunca acceden a la API, por lo que nada cambia cuando Claude Code apunta a ANTHROPIC_BASE_URL=https://aiprimetech.io. Una combinación útil: un hook Stop que imprime datos de uso al estilo de /costa partir de tus propios registros, para que un equipo con créditos de pago por uso vea el precio de cada sesión cuando finaliza.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Preguntas frecuentes

AI Prime Tech es una pasarela API independiente y no está afiliada a Anthropic, ni cuenta con su respaldo o patrocinio. «Claude» y «Claude Code» son marcas comerciales de Anthropic. Las funciones de Claude Code descritas aquí se basan en la documentación pública de Anthropic en el momento de la redacción y cambian con frecuencia; los precios y las listas de modelos de esta página se obtienen de la configuración actual de esta pasarela.