Referencia a fondo · Hooks

Hooks

Código tuyo que se ejecuta automáticamente en momentos exactos del ciclo de vida de Claude Code. Es la única forma de convertir una regla en una garantía: formatear siempre, bloquear siempre, avisar siempre.

HOOKS · 1

Qué es un hook, en simple

En simpleUn hook es una regla del tipo "cuando pase X, ejecuta Y". Como un sensor de movimiento que prende la luz: no depende de que alguien se acuerde. Claude puede olvidar una instrucción de tu CLAUDE.md; un hook se ejecuta siempre, porque lo corre Claude Code, no el modelo.
CLAUDE.md dice…

"Corre prettier después de editar"

Sugerencia. El modelo decide si lo hace. Puede olvidarlo tras compactar.
vs
Un hook PostToolUse…

jq -r '.tool_input.file_path' | xargs npx prettier --write

Garantía. Corre después de cada Edit o Write, sin excepción.

Qué puedes hacer con hooks

BloquearImpedir comandos peligrosos o ediciones a .env, incluso en modo bypass.
AutomatizarFormatear, correr linters o tests después de cada cambio.
Inyectar contextoAgregar la rama actual, el sprint o recordatorios al prompt o tras compactar.
NotificarAviso de escritorio o Slack cuando Claude espera tu respuesta.
AprobarResponder automáticamente prompts de permiso que siempre aceptas.
AuditarRegistrar cada comando o cambio de configuración para cumplimiento.
Cinco tipos de handlerUn hook puede ser un comando de shell (command, el más común), un POST a una URL (http), una llamada a una herramienta MCP (mcp_tool), una evaluación de un LLM (prompt) o un subagente con herramientas (agent, experimental).
HOOKS · 2

El ciclo de vida, animado

Los eventos se disparan en un orden predecible. Reproduce una sesión típica y mira cuándo se enciende cada uno. Toca cualquier evento para ver qué puede hacer ahí.

Una sesión, evento por evento
Presiona Reproducir o avanza evento por evento con Siguiente.
ClavePreToolUse corre antes de cualquier chequeo de modo de permiso, en todos los modos. Si devuelve deny, bloquea incluso con --dangerously-skip-permissions. Al revés no: un hook que devuelve allow no salta las reglas deny de settings.
HOOKS · 3

Anatomía de la configuración

Los hooks viven en archivos de settings bajo la clave hooks, con tres niveles anidados. Toca cada nivel para ver qué parte del JSON es.

Tres niveles
1 · Evento¿Cuándo? PreToolUse, Stop, SessionStart…
2 · Grupo con matcher¿Para qué? "Bash", "Edit|Write", "mcp__.*"
3 · Handler(s)¿Qué hacer? type + command / url / prompt…

    

Dónde se definen

UbicaciónAlcance¿Se comparte?
~/.claude/settings.jsonTodos tus proyectosNo, es tuyo
.claude/settings.jsonEste proyectoSí, se commitea
.claude/settings.local.jsonEste proyecto, solo túNo (gitignored)
Managed settingsToda la organizaciónLo despliega el admin
Plugin hooks/hooks.jsonDonde el plugin esté activoCon el plugin
Frontmatter de skill o subagenteMientras esa skill/agente está activoCon la skill
  • Las ediciones a settings se recargan solas; no necesitas reiniciar. /hooks muestra un navegador de solo lectura con todo lo configurado y su origen.
  • Si varios hooks coinciden con un evento, todos corren en paralelo. Un deny de uno no detiene a los otros (sus efectos secundarios igual ocurren).
  • Para decisiones de permiso en PreToolUse gana la más restrictiva: deny > defer > ask > allow. El additionalContext de todos se combina.
  • "disableAllHooks": true apaga los hooks de un archivo (no los managed). Una organización puede forzar allowManagedHooksOnly.
HOOKS · 4

Catálogo completo de eventos

Hay más de 30 eventos. Filtra por categoría o por los que pueden bloquear, y toca uno para ver su ficha.

Eventos de hooks
HOOKS · 5

Matchers y el campo if

Sin matcher, el hook corre en cada ocurrencia del evento. El matcher filtra según un campo que depende del evento: el nombre de la herramienta en eventos de herramientas, el origen en SessionStart, el tipo en Notification, etc.

EscribesSe interpreta comoEjemplo
"*", "" u omitidoCoincide con todo""
Solo letras, dígitos, _, -, separados por | o ,Lista exacta de nombresEdit|Write = Edit, Write
Cualquier otro carácterExpresión regular JavaScript, sin anclarmcp__memory__.*
Probador de matchers

Filtra también por argumentos con if

El matcher solo ve el nombre de la herramienta. Para filtrar por qué hace, agrega if al handler con sintaxis de reglas de permiso. Así el proceso ni siquiera se lanza si no coincide:

.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-branch.sh"
          }
        ]
      }
    ]
  }
}
Ojo con BashClaude también puede modificar archivos con comandos de shell (sed -i, mv). Si tu hook debe ver todo cambio (auditoría, cumplimiento), agrega un hook Stop que revise el árbol con git status --porcelain una vez por turno. Los matchers distinguen mayúsculas.
HOOKS · 6

Entrada: el JSON que recibe tu hook

Cuando un evento se dispara, Claude Code le pasa a tu comando un JSON por stdin. Un hook HTTP lo recibe como body del POST. Todos los eventos comparten estos campos:

CampoContenido
session_idID de la sesión
transcript_pathRuta al JSON de la conversación (se escribe de forma asíncrona; puede ir atrasado)
cwdDirectorio de trabajo cuando se disparó
permission_modedefault, plan, acceptEdits, auto, dontAsk o bypassPermissions
hook_event_nameEl evento que lo disparó
effortObjeto con level (low … max)
prompt_id, scratchpad_dirUUID del prompt en proceso y carpeta temporal de la sesión
agent_id, agent_typeSolo si corre dentro de un subagente o con --agent

Cada evento agrega lo suyo. Elige uno para ver un ejemplo de stdin realista:

Ejemplos de stdin

Leerlo en tu script

bash · con jq
#!/bin/bash
INPUT=$(cat)                                      # todo el JSON de stdin
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
python · sin dependencias
#!/usr/bin/env python3
import json, sys
data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")
HOOKS · 7

Salida: exit codes y JSON

Tu hook le responde a Claude Code de dos formas. Elige una por hook:

Forma simple: exit code0 = sin objeción · 2 = bloquear (el motivo va a stderr) · otro = error no bloqueante, la acción sigue.
Forma estructurada: JSONSales con 0 e imprimes un objeto JSON en stdout. Permite permitir, denegar, preguntar, reescribir la entrada o agregar contexto.
Simulador: ¿qué pasa si mi hook responde…?

Campos JSON universales

CampoEfecto
continue: falseDetiene a Claude por completo después del hook (más fuerte que bloquear una acción).
stopReasonMensaje que ve el usuario cuando continue es false.
systemMessageAviso que se muestra al usuario.
hookSpecificOutput.additionalContextTexto que Claude lee como recordatorio del sistema. Debe ir dentro de hookSpecificOutput: arriba se ignora en silencio.
hookSpecificOutput.updatedInputEn PreToolUse: reescribe los argumentos de la herramienta antes de ejecutarla.

Decisión por evento

EventosCómo deciden
PreToolUse, PreModelSwitchhookSpecificOutput.permissionDecision: allow / deny / ask (y defer en -p) + permissionDecisionReason
PermissionRequesthookSpecificOutput.decision.behavior: allow / deny; opcional updatedInput y updatedPermissions
UserPromptSubmit, PostToolUse, Stop, SubagentStop, PreCompact, ConfigChange…decision: "block" + reason en el nivel superior
SessionStart, UserPromptSubmitEl texto plano de stdout (o additionalContext) entra al contexto de Claude
El error más comúnTu perfil de shell (~/.bashrc, ~/.zshrc) imprime algo como "Shell ready". Esa línea se antepone a tu JSON, ya no empieza con { y Claude Code lo ignora sin avisar. Envuelve esos echo en if [[ $- == *i* ]] o usa la forma exec con "args": [].
HOOKS · 8

Los cinco tipos de handler

Opciones comunes a todos

CampoPara qué
timeoutSegundos. Por defecto: 600 en command/http/mcp_tool (30 en UserPromptSubmit y cambios de modelo), 30 en prompt, 60 en agent. Los SessionEnd comparten un presupuesto de 1,5 s.
ifFiltro con sintaxis de reglas de permiso (solo eventos de herramientas).
statusMessageTexto que se muestra mientras corre.
async: true(command) Corre en segundo plano sin bloquear. asyncRewake despierta a Claude cuando termina.
args: [](command) Forma exec: lanza el ejecutable sin shell. Evita problemas de comillas y rutas con espacios.
onFailure: "block"(command, http) Si el hook falla o expira, bloquea la acción en vez de dejarla pasar. Úsalo en guardrails críticos.
once: true(solo en frontmatter de skills) Corre una vez por sesión.

Variables disponibles en los comandos: $CLAUDE_PROJECT_DIR (raíz del proyecto, úsala para rutas a scripts), ${CLAUDE_PLUGIN_ROOT} y ${CLAUDE_PLUGIN_DATA} en plugins, y $CLAUDE_ENV_FILE en SessionStart, CwdChanged y FileChanged para persistir variables de entorno en los siguientes comandos Bash.

HOOKS · 9

Recetario: 10 hooks listos para copiar

Las recetas más útiles de la documentación oficial, comentadas. Elige una.

Recetas

HOOKS · 10

Constructor de hooks

Arma tu hook eligiendo opciones; el JSON se genera solo y te dice dónde pegarlo.

Generador
AtajoTambién puedes describirlo en lenguaje natural con /update-config agrega un hook que… y Claude edita el settings correcto.
HOOKS · 11

Depurar y usar hooks con seguridad

Diagnóstico guiado: mi hook…

Prueba tu script sin Claude

bash
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf build"}}' | ./.claude/hooks/block-rm.sh
echo $?    # 2 = bloquearía · 0 = sin objeción
  • Ctrl+O abre el transcript: ahí ves bloqueos y avisos hook error. El éxito no muestra nada.
  • Para ver stdout, stderr y exit codes completos: claude --debug-file /tmp/claude.log y tail -f en otra terminal, o /debug a mitad de sesión.
  • Un hook Stop que bloquea 8 veces seguidas sin que Claude use herramientas es ignorado. Revisa stop_hook_active en la entrada y sal con 0 si es true.
SeguridadLos hooks de comando corren con tus permisos de usuario, sin sandbox. Revisa cualquier hook que venga en un repo clonado o un plugin antes de confiar en la carpeta. Usa rutas absolutas o $CLAUDE_PROJECT_DIR, cita variables ("$VAR"), valida la entrada y no imprimas secretos.
QUIZ

Quiz · Hooks