Hooks en Claude Code

Sistema de hooks para automatizar validaciones y acciones en Claude Code.

Modelo 2026

Los hooks se definen en formato JSON dentro del plugin, no como scripts sueltos.

Ubicación

.claude-plugin/
├── hooks.json           # Definición de hooks
└── scripts/             # Scripts ejecutables
    ├── security-check.sh
    └── validate-command.sh

Eventos Disponibles

Evento	Cuándo se dispara
`PreToolUse`	Antes de ejecutar cualquier tool
`PostToolUse`	Después de ejecutar cualquier tool
`Stop`	Cuando Claude termina de responder

Tipos de Hooks

Tipo	Descripción
`command`	Ejecuta un script/comando
`prompt`	Agrega un prompt al contexto

Estructura de hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/security-check.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash(git commit:*)",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Commit exitoso. ¿Hay docs que actualizar?"
          }
        ]
      }
    ]
  }
}

Matchers

Los matchers filtran cuándo se ejecuta el hook:

Matcher	Descripción
`Bash`	Cualquier comando Bash
`Bash(git commit:*)`	Comandos que empiezan con `git commit`
`Write`	Cualquier escritura de archivo
`Edit`	Cualquier edición de archivo

Variables de Entorno

Variable	Descripción
`CLAUDE_PLUGIN_ROOT`	Ruta al directorio del plugin

Scripts de Hook

Los scripts reciben JSON por stdin con la estructura:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "git status"
  }
}

Respuestas

Para bloquear una acción:

{
  "decision": "block",
  "reason": "Explicación del bloqueo"
}

Para permitir (o no responder nada):

exit 0

Hooks Incluidos en llm-toolkit

security-check.sh (PreToolUse)

Detecta:

Patrones de secrets (API keys, tokens, passwords)
Comandos destructivos (rm -rf /, dd, etc.)
Curl/wget piped a bash

validate-command.sh (PreToolUse)

Valida:

Push directo a main/master (sugiere PR)
npm install con flags que ignoran lockfile

post-commit-docs.sh (PostToolUse)

Analiza commits y sugiere documentación a actualizar:

Archivos cambiados	Sugerencia
`skills/*`	Verificar README.md y marketplace.json
`agents/*`	Verificar README.md
`.claude-plugin/*`	Verificar docs/guides/hooks.md
`commands/*`	Verificar README.md
`index.ts`, `package.json`	Verificar CHANGELOG.md

Agregar Nuevo Hook

Crear script en .claude-plugin/scripts/
Dar permisos: chmod +x script.sh
Agregar entrada en hooks.json
Testear con comando que dispare el matcher