Hooks y permisos

Personaliza el comportamiento de Claude y pon límites de seguridad

⏱ Estim. ~6 min

01 · Leer

Los hooks te permiten correr tu propio código en momentos específicos del flujo de Claude. ¿Antes de usar una herramienta? ¿Después de editar? ¿Al iniciar la sesión? Puedes interceptar estos eventos y agregar tu propia lógica: autoformato, chequeos de seguridad, notificaciones, validación personalizada.

Los permisos controlan lo que Claude puede hacer. Por defecto, Claude pregunta antes de correr comandos o editar archivos. Pero puedes preaprobar acciones seguras (como npm test), bloquear las peligrosas (como git push --force) y dejar que Claude corra más rápido en tareas rutinarias y seguro en las riesgosas.

💡 Imagínalo asíLos hooks son como puntos de control en una línea de producción. En cada estación, un inspector (tu script) revisa el trabajo y o lo pasa (exit 0) o lo regresa (exit 2). Los permisos son como un sistema de credenciales: algunas puertas siempre están abiertas (leer archivos), algunas piden pasar la tarjeta (comandos) y otras están cerradas con llave (operaciones peligrosas).

Puntos clave

Hooks: tu código corre en momentos específicos del flujo de Claude
Permisos: controlan lo que Claude puede y no puede hacer
Los hooks interceptan eventos; los permisos ponen reglas generales
Juntos personalizan y protegen a Claude para tu flujo

02 · Leer

Estos son los eventos de hook más útiles: - PreToolUse: se dispara antes de que Claude use una herramienta (Read, Edit, Bash, etc.). Puedes inspeccionar lo que está por hacer y bloquearlo. - PostToolUse: se dispara después de que una herramienta tiene éxito. Perfecto para autoformatear archivos editados o registrar cambios. - SessionStart: se dispara cuando inicia una sesión. Úsalo para inyectar recordatorios de contexto, sobre todo después de un compact. - Notification: se dispara cuando Claude necesita tu atención. Bueno para notificaciones de escritorio. - Stop: se dispara cuando Claude termina de responder.

Los hooks se comunican vía exit codes: exit 0 permite la acción, exit 2 la bloquea (tu mensaje de error en stderr se vuelve feedback para Claude).

Puntos clave

PreToolUse: inspecciona y opcionalmente bloquea antes de que corra la herramienta
PostToolUse: reacciona después del éxito (autoformato, logging)
SessionStart: inyecta contexto al inicio de sesión o tras compact
Exit 0 = permitir, Exit 2 = bloquear (stderr se vuelve feedback)

03 · Ejemplo de código

Este es un hook PostToolUse que autoformatea archivos después de que Claude los edita. Vive en el .claude/settings.json de tu proyecto.

.claude/settings.json — hook de autoformato

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

El campo matcher usa regex para emparejar nombres de herramienta. Edit|Write significa que este hook se dispara tras cualquier llamada a Edit o Write. El comando recibe JSON en stdin con los detalles de la llamada, extrae la ruta del archivo y corre Prettier sobre él. Cada archivo que edita Claude queda autoformateado.

04 · Ejemplo de código

Este es un hook PreToolUse que bloquea comandos Bash peligrosos.

.claude/hooks/protect.sh

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if [[ "$CMD" =~ "rm -rf" ]]; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 2  # Block the action
fi

exit 0  # Allow everything else

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/protect.sh"
      }]
    }]
  }
}

Este hook intercepta cada comando Bash que Claude intenta correr. Lee el comando desde stdin (como JSON), revisa si contiene 'rm -rf' y lo bloquea con exit code 2. El mensaje de error en stderr le dice a Claude por qué fue bloqueado, y Claude respeta la restricción.

05 · Leer

Los permisos te dan reglas generales de permitir/denegar sin necesidad de escribir scripts. Usan emparejamiento flexible con wildcards.

Reglas allow preaprueban acciones para que Claude no pregunte: - Bash(npm run ): cualquier npm script - Bash(git commit ): commitear cambios - Read(*.env): leer archivos env

Reglas deny bloquean acciones por completo: - Bash(git push --force ): nada de force push - Edit(package-lock.json): no tocar el lockfile - Bash(rm -rf ): nada de borrado recursivo

Las reglas deny siempre ganan a las reglas allow. La configuración se revisa de la más específica a la menos específica: local del proyecto > proyecto > usuario.

Puntos clave

Reglas allow: preaprueban acciones seguras (sin prompt de permiso)
Reglas deny: bloquean acciones por completo
Wildcards: Bash(npm *) empareja cualquier comando npm
Deny siempre gana cuando hay conflicto con allow
La config local sobrescribe la del proyecto, que sobrescribe la del usuario

06 · Quiz

Tu hook PreToolUse detecta que Claude está por correr rm -rf /tmp/build. ¿Qué exit code debería devolver tu script de hook para bloquear esta acción?

Exit code 0: éxito
Exit code 2: bloquea la acción
Exit code 1: error general
Exit code 255: error crítico

07 · Emparejar

Empareja cada evento de hook con su mejor caso de uso.

(Esta sección es interactiva — activa JavaScript para usarla.)

Otras lecciones de este capítulo

⚠ La experiencia interactiva completa necesita JavaScript. Actívalo y vuelve a cargar la página.

※ Este es un proyecto educativo independiente — no es un producto oficial de Anthropic. Claude™ es una marca registrada de Anthropic, PBC.