Cargando
Cargando

Hooks

Este es el problema de decirle a Claude que haga algo en un archivo CLAUDE.md: es una solicitud, no una garantía. Puedes escribir "siempre formatea después de editar" y Claude normalmente hará caso. Normalmente. Pero en una ejecución larga que no estás observando, "normalmente" no es suficiente. Un hook soluciona esto. Un hook es código determinista que se ejecuta en un punto fijo del ciclo, por lo que puede garantizar un comportamiento en lugar de simplemente esperarlo. Convierte una regla de "Claude normalmente hace caso" en "Claude no puede saltársela".

Esa es toda la idea. Ahora veamos cómo funciona realmente.

Los eventos de hook

Claude Code dispara alrededor de 30 eventos de hook a lo largo de una sesión. No necesitas conocerlos todos, y la referencia de hooks enumera cada uno. Hay un pequeño puñado al que recurrirás una y otra vez, y se alinean con puntos del ciclo agéntico donde querrías intervenir.

Así es como se ubican en el ciclo. Una sesión comienza, llegan prompts, se llaman herramientas y, eventualmente, el turno termina. Cada uno de esos momentos tiene un hook al que puedes enganchar código.

Los que vale la pena conocer:

  • PreToolUse se dispara antes de una llamada a una herramienta. Este es tu primitivo de aplicación. Es el que puede detener algo antes de que suceda.
  • PostToolUse se dispara después de una llamada exitosa a una herramienta. Normalmente aquí es donde va el formateo automático o un lint automático.
  • Stop se dispara cuando Claude quiere terminar su turno. Puedes negarte y decir "no, todavía no has terminado" si no se cumple alguna condición. Existe un SubagentStop equivalente para cuando un sub-agente termina.
  • PreCompact y PostCompact se disparan antes y después de la compactación.
  • InstructionsLoaded se dispara cuando se carga un archivo CLAUDE.md o un archivo de reglas. Útil para auditar qué es lo que realmente llegó al contexto.
  • SessionStart se dispara al inicio y prepara el entorno. Usa la fuente startup si solo lo quieres en inicios nuevos.

Algo que suele confundir a la gente: para volver a inyectar contexto después de la compactación, no uses PostCompact. Usa SessionStart con el matcher compact. Ese es el que realmente devuelve su salida a la conversación.

PreToolUse: devolver una decisión como JSON

PreToolUse es donde está el poder real, porque puede bloquear una llamada a una herramienta antes de que se ejecute. La forma de responderle a Claude es imprimiendo JSON y saliendo con código cero. El campo clave es permissionDecision, y toma uno de tres valores:

  • allow — deja pasar la llamada
  • deny — detiene la llamada
  • ask — se lo devuelve al usuario para que decida

Técnicamente existe un cuarto valor, defer, pero solo se aplica a ejecuciones no interactivas con -p, donde un proceso que llama pausa la herramienta y la retoma más tarde. Rara vez recurrirás a él.

La forma se ve así:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Don't push to main. Open a pull request instead."
  }
}

En lugar de bloquear una llamada, puedes reescribirla. Devuelve allow o ask con updatedInput. Con ask, ves la llamada reescrita y la apruebas. Con allow, se ejecuta sin pedir confirmación:

json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "ask",
    "updatedInput": {
      "command": "..."
    }
  }
}

Así es como redactarías un secreto de un comando bash y aun así dejarías que se ejecute. Una advertencia: updatedInput reemplaza el objeto de entrada completo, así que tienes que repetir los campos que no estás cambiando, o los perderás.

Códigos de salida, para hooks que no devuelven JSON

No todos los hooks necesitan hablar JSON. Para hooks más simples, los códigos de salida hacen el trabajo. Hay tres números que importan.

  • 0 es éxito. Si la salida estándar es JSON, Claude la analiza. El texto plano se ignora en la mayoría de los eventos, pero en SessionStart, UserPromptSubmit y UserPromptExpansion, el texto plano se añade al contexto. Eso es exactamente lo que hace que funcione un hook preservador de estado.
  • 2 es un error bloqueante. El error estándar se devuelve a Claude como contexto. Este es el código de salida bloqueante en casi todos los casos.
  • Cualquier otro valor es no bloqueante. El error estándar se registra, y Claude continúa.

El que suele atrapar a la gente es el código de salida 1. Parece un error, pero no bloquea. Claude ejecuta el comando de todos modos. Así que si querías detener algo, usa la salida 2, no la 1.

Un par de complicaciones más. La salida 2 incluso puede bloquear Stop, que es como le dices a Claude que no ha terminado. Pero PostToolUse se dispara después de que la herramienta ya se ejecutó, así que bloquear ahí es demasiado tarde para detener la llamada, aunque todavía puede devolver texto a Claude. Y algunos eventos ignoran el bloqueo por completo, como Notification y SessionStart. SessionStart te muestra el error estándar solo a ti, Notification lo ignora, y ambos continúan de todos modos.

Una salvaguarda real: redactar en lugar de bloquear

Unamos todo esto con algo práctico. Digamos que quieres una salvaguarda de PreToolUse en la herramienta Bash. Registras un hook en un archivo de configuración. Pon este en .claude/settings.json y confírmalo (commit), y tu equipo podrá compartirlo:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/redact-secrets.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

El matcher elige la herramienta a observar, y un campo if opcional en el hook puede reducirlo a un comando específico, como "if": "Bash(curl *)". Ejecuta /hooks para verificar que el hook esté registrado.

El movimiento obvio es devolver deny y detener una llamada peligrosa. Eso está bien. Pero el movimiento menos conocido y más interesante es devolver updatedInput para reescribir la llamada. Así es como eliminas un secreto de un comando y aun así lo dejas ejecutarse, en lugar de simplemente rechazarlo.

Esto es lo que se ve en la práctica. Se le pide a Claude que ejecute un comando que incluye un secreto con apariencia de estar activo. El hook lo intercepta, detecta el patrón sk_live_ y lo sustituye por un marcador de posición antes de que el comando llegue a ejecutarse.

Aquí está el script, .claude/hooks/redact-secrets.sh. Necesita jq, y lo haces ejecutable con chmod +x:

bash
#!/bin/bash
# Reemplaza claves con apariencia real antes de ejecutar el comando.
jq 'if (.tool_input.command // "" | test("sk_live_\\w+")) then {
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "ask",
    permissionDecisionReason: "Replaced a live key with a placeholder",
    updatedInput: (.tool_input | .command |= gsub("sk_live_\\w+"; "REDACTED"))
  }
} else empty end'

Devuelve ask, así que tú apruebas el comando reescrito. Devolver allow omitiría esa confirmación para cada comando que coincida con el patrón. Una vez que lo apruebas, el comando se ejecuta sin el secreto. Esa es la diferencia entre bloquear y redactar, y es el tipo de cosa que un hook puede aplicar siempre, sin excepción.

Preservar el estado a través de una compactación

Un patrón más que vale la pena configurar. Cuando Claude compacta una conversación larga, pierde mucho detalle. Un hook de SessionStart con el matcher compact se ejecuta justo después de la compactación. Haz que imprima un breve resumen de los archivos en los que has estado trabajando. Ese resumen vuelve al contexto, de modo que Claude retoma justo donde lo dejó en lugar de empezar desde cero. Este ejemplo enumera tus cambios sin confirmar:

json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [{ "type": "command", "command": "git status --short" }]
      }
    ]
  }
}

Para cerrar

Los hooks convierten una regla que Claude normalmente sigue en una que siempre sigue. Ve más allá del formateo automático: protege las herramientas con PreToolUse, controla el turno con Stop y preserva el estado a través de una compactación. La configuración requiere un poco de esfuerzo inicial, pero se recompensa la primera vez que detiene algo en una ejecución que ni siquiera estabas observando.