Capítulo 6: Hooks: Automatización por Eventos

¿Qué son los Hooks?

Los hooks son automatizaciones que se disparan cuando ocurren eventos específicos en Claude Code. Ejemplo: advertir sobre console.log cada vez que se edita un archivo JS.

Tipos de Eventos

Evento	Cuándo se dispara
PreToolUse	Antes de ejecutar una herramienta
PostToolUse	Después de ejecutar una herramienta
Stop	Cuando el agente termina
SessionStart	Al iniciar sesión
SessionEnd	Al cerrar sesión

Anatomía de un Hook

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Componentes:

• matcher — expresión que filtra cuándo disparar
• type — command (ejecutar script)
• command — el script a ejecutar

Hooks Incluidos en ECC

Memory Persistence

Guardan y restauran contexto entre sesiones automáticamente:

• SessionStart → cargar contexto guardado de la sesión anterior
• SessionEnd → guardar estado actual de la sesión
• Pre-compact → guardar estado antes de compactación

Strategic Compact

Sugiere /compact en momentos lógicos en vez de esperar al auto-compact al 95%.

Seguridad

• beforeSubmitPrompt (Cursor) — detecta secrets (sk-, ghp_, AKIA) en prompts
• beforeTabFileRead (Cursor) — bloquea lectura de .env, .key, .pem

Code Quality

• afterFileEdit — auto-format + TypeScript check + console.log warning
• beforeShellExecution — bloquea dev servers fuera de tmux

Hook Runtime Controls

Controlar hooks en runtime sin editar archivos:

# Perfil de severidad
export ECC_HOOK_PROFILE=minimal    # minimal | standard | strict

# Deshabilitar hooks específicos
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

Scripts Cross-Platform

Los hooks usan scripts Node.js para compatibilidad cross-platform:

scripts/
├── lib/
│   ├── utils.js              # Utilidades de archivos y sistema
│   └── package-manager.js    # Detección de package manager
└── hooks/
    ├── session-start.js      # Cargar contexto
    ├── session-end.js        # Guardar estado
    ├── pre-compact.js        # Pre-compactación
    ├── suggest-compact.js    # Sugerencias de compactación
    └── evaluate-session.js   # Extraer patrones

Hooks en Diferentes Herramientas

Claude Code	Cursor	OpenCode
PreToolUse	beforeShellExecution	tool.execute.before
PostToolUse	afterFileEdit	tool.execute.after
Stop	—	session.idle
SessionStart	—	session.created
8 tipos	15 tipos	11 tipos

Cursor tiene un DRY adapter (adapter.js) que transforma el formato de Cursor al de Claude Code, reutilizando los mismos scripts.

Crear tu Propio Hook

Ejemplo: alertar cuando un archivo supera 200 líneas:

{
  "matcher": "tool == \"Edit\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\nLINES=$(wc -l < \"$file_path\"); [ $LINES -gt 200 ] && echo \"[Hook] $file_path tiene $LINES líneas (máx 200)\" >&2"
  }]
}