¿Qué son los hooks de un agente?

¿Qué es?

Un hook es un comando que el entorno de un agente ejecuta automáticamente cuando ocurre un evento de su ciclo de vida: abrir una sesión, enviar un prompt, usar una herramienta, terminar una respuesta. No es una instrucción que el modelo lee y pondera: es código que corre por fuera del modelo, siempre, con o sin su acuerdo.

La diferencia con una regla escrita es de naturaleza, no de énfasis. Una línea en CLAUDE.md que dice "corre los tests después de editar" entra al contexto y compite por la atención del modelo con todo lo demás que hay ahí. Un hook que corre los tests después de cada edición no compite con nada: se dispara solo. La documentación oficial de Claude Code lo plantea sin rodeos: a diferencia de las instrucciones de CLAUDE.md, que son consultivas, los hooks son deterministas y garantizan que la acción ocurra.

Por eso el hook es la pieza que se usa cuando "casi siempre" no alcanza.

Modelo mental

Un cartel que dice "no pasar" y un torniquete resuelven el mismo problema con mecanismos distintos. El cartel informa y delega la decisión en quien lo lee; el torniquete no informa nada, simplemente no gira. Una regla en el prompt es el cartel. Un hook es el torniquete.

flowchart LR P[Regla escrita en el prompt] --> M[Modelo] M -->|la pondera y decide| A[Acción] E[Evento del ciclo de vida] --> H[Hook] H -->|se ejecuta siempre| A

Los dos caminos terminan en la misma acción, pero solo uno pasa por una decisión. Esa es toda la diferencia, y es la razón por la que un harness serio combina ambos en vez de elegir uno.

¿Cómo se usa?

Los hooks se configuran en un archivo de settings: ~/.claude/settings.json para todas tus sesiones, o .claude/settings.json dentro del proyecto para compartirlos con el equipo. Cada nombre de evento es una clave dentro de un único objeto hooks:

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

El matcher filtra a qué herramientas aplica el hook, y el comando recibe por stdin un JSON con los datos del evento — de ahí el jq para extraer la ruta del archivo editado.

Hay dos familias de uso, con propósitos distintos.

Automatizar algo que debería pasar siempre: formatear tras cada edición, correr el linter, registrar actividad. El hook actúa después del hecho y no interfiere con la decisión del agente.

Bloquear algo que no debe ocurrir. Un hook de PreToolUse corre antes de que la herramienta se ejecute y puede impedirla. Si el script termina con código de salida 2, la llamada queda bloqueada y lo que haya escrito en stderr vuelve al agente como motivo:

#!/bin/bash
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")
 
if echo "$command" | grep -q 'rm -rf'; then
  echo "Bloqueado: rm -rf no está permitido en este proyecto" >&2
  exit 2
fi
 
exit 0

Para un control más fino, el mismo hook puede salir con código 0 y devolver un JSON con permissionDecision en allow, deny o ask, en lugar del corte binario del código 2. Eso permite escalar al humano en vez de bloquear de plano.

Los eventos disponibles cubren casi todo el ciclo de vida: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, PreCompact y SessionEnd, entre varios otros. La lista crece entre versiones, así que conviene consultar la referencia oficial antes de asumir que un evento existe.

¿Cuándo usarlo / cuándo no?

Conviene un hook cuando:

La acción debe ocurrir siempre, sin excepción, y el costo de que se saltee una sola vez es alto.
La tarea es mecánica y verificable: formatear, lintear, correr tests, registrar.
Necesitas un límite que no dependa de que el modelo recuerde una instrucción entre miles de tokens.
El equipo entero necesita el mismo comportamiento, no solo la máquina de quien lo configuró.

No conviene cuando:

La decisión requiere criterio: un comando determinista no puede evaluar "¿esto tiene sentido aquí?". Para eso están el prompt, las skills, o los hooks basados en modelo.
Es una preferencia de estilo cuyo incumplimiento no rompe nada. Un hook para eso solo agrega fricción.
Todavía estás explorando el flujo de trabajo. Fijar en código un proceso que aún no se estabilizó cuesta más de lo que ahorra.
El comando es lento: el hook se dispara en medio del ciclo de trabajo y su latencia se suma a cada evento que lo activa.