Módulo 6: Hooks Avanzados y SDK Headless

1. Introducción al Módulo — Hooks como Sistema Nervioso, SDK como Control Programático

Descripción

Hasta ahora, todo lo que has construido con Claude Code es interactivo. Tú escribes un prompt, Claude ejecuta, tú revisas. Creaste subagents con identidad propia, les diste memoria persistente, los coordinaste en paralelo, los organizaste en equipos con task boards, y los empaquetaste como plugins distribuibles. Todo funcional. Pero hay un patrón que probablemente notaste: siempre estás ahí. Siempre hay un humano iniciando la acción, supervisando la ejecución, decidiendo el siguiente paso.

Los hooks y el SDK headless eliminan esa dependencia. Los hooks son el sistema nervioso de Claude Code — detectan eventos internos (una herramienta se ejecuta, un subagent termina, una sesión arranca) y disparan acciones automáticas sin tu intervención. El SDK headless es el control programático — ejecuta Claude Code desde scripts de Python o TypeScript como si fuera una función más en tu pipeline.

La combinación es lo que transforma Claude Code de herramienta interactiva a sistema automatizable: un hook detecta que un subagent terminó de editar archivos → dispara un script de linting automático → si el linting falla, un script de SDK re-ejecuta Claude Code para corregir los errores → todo sin que toques el teclado.

Este módulo cierra la Phase 2 porque completa el stack: Agent Teams coordinan la ejecución, plugins la empaquetan, y hooks + SDK la automatizan. Cuando termines, tendrás un workflow end-to-end donde hooks detectan eventos, scripts SDK reaccionan, y el sistema se auto-corrige.

¿Dónde Estamos en la Guía?

Contexto en la Guía

Esta guía tiene 8 módulos organizados en 3 phases:

Phase 1: Subagents Avanzados (Módulos 1-3)           ← COMPLETADA
├── Módulo 1: Custom Subagents                        ✅
├── Módulo 2: Agent Memory y Scopes                   ✅
└── Módulo 3: Parallel Sub-Agent Delegation            ✅

Phase 2: Agent Teams y Plugins (Módulos 4-6)
├── Módulo 4: Agent Teams                              ✅
├── Módulo 5: Plugins: Crear y Distribuir              ✅
└── Módulo 6: Hooks Avanzados y SDK Headless           ← ESTÁS AQUÍ

Phase 3: Orquestación (Módulos 7-8)
├── Módulo 7: Remote Control y CLAUDE.md para Equipos
└── Módulo 8: Proyecto: Sistema Multi-Agente Completo

Duración total estimada: 8-10 horas (self-paced).

¿Qué cambia con hooks y SDK?

En los módulos anteriores, la automatización era a nivel de agentes: el team lead decide qué hacer, pero tú lo arrancas. Los hooks y el SDK mueven la automatización a nivel de sistema: eventos disparan acciones, scripts arrancan sesiones, y el ciclo completo puede funcionar sin intervención humana. El cambio mental es: dejas de ser el operador y empiezas a ser el diseñador del sistema de automatización.

De Herramienta Interactiva a Sistema Automatizado

Lo que tienes ahora

Después de 5 módulos, tu stack es:

┌─────────────────────────────────────────────┐
│              Tu Workflow Actual               │
│                                               │
│  TÚ ──prompt──→ Claude Code ──resultado──→ TÚ │
│       │                              │        │
│       │  ┌──────────────────────┐    │        │
│       └──│  Subagents (M1)      │    │        │
│          │  Memory (M2)         │    │        │
│          │  Parallelism (M3)    │────┘        │
│          │  Agent Teams (M4)    │             │
│          │  Plugins (M5)        │             │
│          └──────────────────────┘             │
└─────────────────────────────────────────────┘

Problema: TÚ sigues siendo el punto de inicio Y de control.

Lo que tendrás después de este módulo

┌─────────────────────────────────────────────────────┐
│              Tu Workflow Automatizado                 │
│                                                       │
│  ┌──────────┐    ┌──────────────┐    ┌────────────┐  │
│  │  HOOKS   │───→│ Claude Code  │───→│  HOOKS     │  │
│  │ (inicio) │    │  (ejecuta)   │    │ (reacción) │  │
│  └──────────┘    └──────┬───────┘    └──────┬─────┘  │
│       ▲                 │                    │        │
│       │          ┌──────┴───────┐           │        │
│       │          │  SDK Script  │◀──────────┘        │
│       └──────────│  (Python/TS) │                    │
│                  └──────────────┘                     │
│                                                       │
│  TÚ: diseñas el sistema, no lo operas                │
└─────────────────────────────────────────────────────┘

La diferencia: los hooks detectan eventos y el SDK permite que scripts reaccionen programáticamente. Tú diseñas las reglas una vez y el sistema las ejecuta cada vez.

Hooks: El Sistema Nervioso

Qué son los hooks

Un hook es una acción automática que se dispara cuando ocurre un evento específico dentro de Claude Code. No es un plugin, no es un subagent — es un trigger: "cuando pase X, ejecuta Y."

Evento                          Hook                    Acción
─────────────────────────────────────────────────────────────────
Sesión arranca              →  SessionStart         →  Instalar deps
Herramienta va a ejecutarse →  PreToolUse           →  Validar comando
Herramienta terminó         →  PostToolUse          →  Auto-lint
Subagent arranca            →  SubagentStart        →  Log inicio
Subagent terminó            →  SubagentStop         →  Generar reporte
Claude va a responder       →  Stop                 →  Quality check
Permiso solicitado          →  PermissionRequest    →  Auto-aprobar

Los 7 eventos de hooks

Evento	Cuándo se dispara	Matcher	Caso de uso típico
`SessionStart`	Cuando arranca una sesión	No aplica	Setup de entorno, verificar deps
`PreToolUse`	Antes de ejecutar una herramienta	Nombre de la herramienta	Validar, bloquear, modificar
`PostToolUse`	Después de ejecutar una herramienta	Nombre de la herramienta	Lint, test, logging
`SubagentStart`	Cuando un subagent arranca	Tipo de agente	Logging, resource allocation
`SubagentStop`	Cuando un subagent termina	Tipo de agente	Reportes, cleanup
`Stop`	Cuando Claude termina de responder	No aplica	Validación final, cleanup
`PermissionRequest`	Cuando se necesita un permiso	No aplica	Auto-aprobación condicional

Hook types

Un hook puede ejecutar tres tipos de acciones:

1. Command (shell script):

{
  "type": "command",
  "command": "./scripts/validate.sh"
}

2. HTTP endpoint:

{
  "type": "http",
  "url": "https://my-api.com/webhook",
  "method": "POST"
}

3. MCP tool:

{
  "type": "mcp",
  "server": "my-server",
  "tool": "my-tool"
}

El tipo command es el más común y el que usarás en el 90% de los casos en este módulo.

Exit codes: el lenguaje de los hooks

Cuando un hook de tipo command ejecuta un script, el exit code determina qué pasa:

Exit Code	Significado	Claude Code hace...
`0`	Éxito, continuar	Permite la operación
`1`	Error, reportar	Reporta el error a Claude para que decida
`2`	Bloquear	Cancela la operación completamente

Exit code 2 es particularmente poderoso en PreToolUse — convierte el hook en un guardián que puede bloquear herramientas peligrosas antes de que se ejecuten.

SDK Headless: Control Programático

Qué es el modo headless

Claude Code normalmente es interactivo — lo abres en la terminal, escribes, esperas. En modo headless, Claude Code es un servicio invocable: lo llamas desde un script, le pasas un prompt, y recibes el resultado como datos estructurados.

# Interactivo (lo que siempre haces)
claude

# Headless (lo que aprenderás aquí)
claude -p "Genera el changelog del último sprint" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json

Los tres formatos de output

Formato	Flag	Cuándo usarlo
`text`	`--output-format text`	Scripts simples, logging
`json`	`--output-format json`	Parsing programático, CI/CD
`stream-json`	`--output-format stream-json`	Monitoring en tiempo real

SDK en Python y TypeScript

Además de la CLI, Claude Code se puede invocar desde SDKs nativos:

Python — Ideal para pipelines de datos, scripts de CI, automatización:

import subprocess
import json

result = subprocess.run(
    ["claude", "-p", "Analiza src/ y reporta issues",
     "--output-format", "json",
     "--allowedTools", "Read,Grep,Glob"],
    capture_output=True, text=True
)
output = json.loads(result.stdout)

TypeScript — Ideal para tooling de desarrollo, build scripts, integración con frameworks JS:

import { execSync } from "child_process";

const result = execSync(
  'claude -p "Analiza src/ y reporta issues" --output-format json --allowedTools "Read,Grep,Glob"',
  { encoding: "utf-8" }
);
const output = JSON.parse(result);

La Combinación: Hooks + SDK

El superpoder real

Hooks y SDK son útiles por separado. Juntos son transformadores.

Escenario: Cada vez que editas un archivo, se auto-formatea y testea

PostToolUse hook (matcher: "Edit|Write")
  → Ejecuta ./scripts/lint-and-test.sh
    → Si el lint falla (exit 1):
      → Script SDK ejecuta: claude -p "Fix lint errors in {file}"
      → Claude Code corrige automáticamente
      → El hook PostToolUse se dispara de nuevo
      → El ciclo se repite hasta que pasa el lint

Escenario: Report automático al final de cada sesión

Stop hook
  → Ejecuta ./scripts/generate-report.sh
    → El script usa SDK para:
      → claude -p "Resume lo que hiciste en esta sesión"
      → Guarda el output en reports/session-{date}.md
      → Envía notificación a Slack

El pipeline completo

SessionStart ──→ Setup environment (install deps, check versions)
     │
PreToolUse ───→ Validate (block dangerous commands, restrict paths)
     │
[Claude works]
     │
PostToolUse ──→ React (auto-lint, auto-test after edits)
     │
SubagentStop ─→ Report (log what each subagent did)
     │
Stop ─────────→ Cleanup (generate session report, push to git)
     │
SDK Script ───→ Orchestrate (trigger next session, parse results)

Cada cápsula de este módulo te enseña una pieza de este pipeline. Al final, en el proyecto (cápsula 06), lo construyes completo.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Configurar hooks SessionStart y PreToolUse para setup automático y validación de comandos
✅ Usar PostToolUse para auto-linting y auto-testing después de cada edición
✅ Implementar SubagentStart/SubagentStop para tracking del ciclo de vida de subagents
✅ Usar Stop y PermissionRequest para cleanup y aprobación automática
✅ Ejecutar Claude Code desde Python con subprocess y parsing de JSON
✅ Ejecutar Claude Code desde TypeScript/Node.js con child_process o el paquete SDK
✅ Combinar hooks + SDK en un workflow automatizado end-to-end

Objetivo profesional

Hooks + SDK son la capa que convierte Claude Code en infraestructura de desarrollo automatizada. Los equipos que dominan esta combinación construyen pipelines de CI que auto-corrigen código, scripts de changelog que se generan solos, y sistemas de calidad que validan cada cambio sin intervención. Es la diferencia entre "uso Claude Code" y "Claude Code trabaja para mí."

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué aprenderás	Tipo
01	Introducción (esta)	Contexto, modelo mental hooks + SDK, por qué importa la combinación	Intro
02	SessionStart y PreToolUse Avanzado	Setup de entorno automático, validación condicional, bloqueo de comandos	Técnica
03	PostToolUse, Subagent Events y Stop	Reacciones post-ejecución, ciclo de vida de subagents, cleanup final	Técnica
04	SDK Headless — Python	Ejecutar Claude Code desde Python, parsing JSON, scripts de automatización	Técnica
05	SDK Headless — TypeScript	Ejecutar Claude Code desde Node.js, integración con tooling JS	Técnica
06	Proyecto: Workflow Automatizado	Pipeline completo: hooks + SDK integrados end-to-end	Proyecto

Flujo de aprendizaje

Primero entenderás los hooks de inicio y validación — SessionStart para configurar el entorno automáticamente y PreToolUse para bloquear operaciones peligrosas (cápsula 02). Luego verás los hooks de reacción — PostToolUse para actuar después de cada edición, SubagentStart/SubagentStop para el ciclo de vida de subagents, y Stop para cleanup final (cápsula 03). Después aprenderás a ejecutar Claude Code desde Python — scripts de automatización, parsing de resultados, integración con CI/CD (cápsula 04). Continuarás con TypeScript — el mismo poder programático pero integrado con tooling de JavaScript (cápsula 05). Finalmente, construirás un workflow automatizado completo que combina hooks + SDK en un pipeline funcional (cápsula 06).

La progresión es: configurar el entorno → validar → reaccionar → automatizar desde Python → automatizar desde TypeScript → integrar todo.

Cada cápsula es independiente en concepto pero construye sobre la anterior en el proyecto final. Las cápsulas 02 y 03 cubren hooks. Las cápsulas 04 y 05 cubren SDK. La cápsula 06 integra todo.

Duración estimada del módulo: 1.25-1.5 horas.

Conexión con el Proyecto

Proyecto del módulo: Workflow Automatizado End-to-End

En la cápsula 06 construirás un pipeline completo:

SessionStart hook — Configura el entorno: verifica dependencias, corre migraciones pendientes, checkea el estado de git.
PreToolUse hook — Valida comandos: bloquea rm -rf, restringe rutas de archivos, impide operaciones en production.
PostToolUse hook — Auto-lint: cada vez que Claude edita un archivo, el linter corre automáticamente. Si falla, Claude recibe el error.
SubagentStop hook — Genera reporte: cuando un subagent termina, se loguea qué hizo, cuánto tardó, y qué archivos tocó.
Python SDK script — Orquesta el pipeline: un script Python arranca Claude Code, le pasa la tarea, y procesa los resultados.

Tu script Python
  ↓
claude -p "Implementa feature X" (SDK)
  ↓
SessionStart hook → setup automático
  ↓
Claude trabaja → PreToolUse valida cada comando
  ↓
Claude edita archivos → PostToolUse auto-lint
  ↓
Subagent termina → SubagentStop genera log
  ↓
Claude termina → Stop genera reporte
  ↓
Tu script Python ← recibe resultado JSON
  ↓
Procesa, notifica, trigger siguiente tarea

Conexión con el proyecto final (Módulo 8)

En el proyecto integrador, este pipeline se convierte en la capa de automatización del sistema multi-agente completo. Los hooks validan cada acción de cada agente, y el SDK permite orchestrar sesiones múltiples desde un script central. Sin hooks + SDK, el sistema multi-agente necesita supervisión humana constante.

Prerequisitos

Conocimientos necesarios

✅ Módulos 1-5 completados — Custom subagents, memory, delegación paralela, Agent Teams, plugins
✅ Hooks básicos — Has usado PreToolUse al menos una vez en guías anteriores
✅ settings.json de Claude Code — Sabes que existe y dónde configurar preferencias
✅ Python básico — Puedes escribir scripts con subprocess, json, y manejo de archivos
✅ Terminal — Sabes escribir y ejecutar shell scripts (.sh)

Verificación rápida

Si puedes responder "sí" a estas preguntas, estás listo:

¿Sabes qué es un hook PreToolUse y cuándo se dispara?
¿Puedes ejecutar claude -p "algo" en la terminal?
¿Sabes qué es un exit code y la diferencia entre exit 0 y exit 1?
¿Puedes escribir un script Python que ejecute un comando y capture su output?
¿Entiendes JSON lo suficiente para parsear un objeto con json.loads()?

No necesitas

❌ Experiencia con todos los hooks — solo necesitas saber que existen
❌ Experiencia con el SDK headless — se cubre completamente aquí
❌ TypeScript avanzado — los ejemplos son básicos y están comentados
❌ Infraestructura de CI/CD — se menciona pero se cubre a fondo en la guía de CI/CD Pipelines

Límites: Qué NO Se Cubre en Este Módulo

❌ CI/CD completo — Se cubre en la guía de CI/CD Pipelines. Aquí se menciona como preview
❌ Remote control — Se cubre en el Módulo 7. Aquí todo es local
❌ Hooks HTTP y MCP — Se mencionan pero el foco está en hooks de tipo command
❌ SDK avanzado con sessions persistentes — Se cubre solo la invocación one-shot
❌ Debugging avanzado de hooks — Se cubren los errores comunes, no edge cases

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Tienes un hook SessionStart que configura tu entorno automáticamente al abrir Claude Code
✅ Un hook PreToolUse bloquea comandos peligrosos con exit code 2
✅ Un hook PostToolUse auto-lintea después de cada edición de archivo
✅ Un hook SubagentStop genera un log cuando un subagent termina
✅ Un script Python ejecuta Claude Code, parsea el resultado JSON, y toma decisiones basadas en el output
✅ Un script TypeScript hace lo mismo desde el ecosistema Node.js
✅ Puedes explicar cómo hooks + SDK se combinan para crear un pipeline automatizado

Test rápido de autoevaluación

Si puedes responder estas preguntas al terminar:

¿Cuál es la diferencia entre exit code 1 y exit code 2 en un hook?
¿Cómo configuras un hook que solo se dispara para la herramienta Bash?
¿Qué flag usas para ejecutar Claude Code en modo headless?
¿Cómo parseas el resultado de Claude Code en Python?
¿Por qué --allowedTools es importante en modo headless?

Resumen

Este módulo enseña las dos capas de automatización de Claude Code: hooks (control desde adentro) y SDK headless (control desde afuera)
Los hooks son el sistema nervioso — detectan 7 tipos de eventos (SessionStart, PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop, PermissionRequest) y ejecutan acciones automáticas
El SDK headless permite ejecutar Claude Code desde scripts Python o TypeScript con claude -p y parsear resultados como JSON
La combinación hooks + SDK es lo que convierte Claude Code de herramienta interactiva a sistema automatizado: hooks detectan → SDK reacciona → el ciclo se repite
Los hooks usan exit codes (0 = continuar, 1 = error, 2 = bloquear) para comunicar decisiones
El módulo cierra Phase 2 conectando plugins (empaquetado) con la automatización que Phase 3 (Remote Control, proyecto integrador) necesita
El proyecto construye un pipeline automatizado end-to-end: SessionStart → PreToolUse → PostToolUse → SubagentStop → SDK script orquestador

Recursos Adicionales

Claude Code Hooks (Anthropic Docs) — Documentación oficial de hooks, eventos, exit codes, y configuración
Claude Code CLI Reference — Flag -p, --output-format, --allowedTools para modo headless
Claude Code Settings — Configuración de hooks en settings.json
Create Custom Subagents — Hooks en frontmatter de subagents
Claude Code Best Practices — Buenas prácticas que incluyen hooks y automatización
Claude Code Overview — Contexto general de Claude Code como sistema
Claude Code Tips and Tricks — Tips de automatización y hooks
Multi-Agent Orchestration — Patrones de orquestación donde hooks y SDK encajan

Siguiente cápsula: En la cápsula 02 configurarás tus primeros hooks avanzados — SessionStart para que Claude Code configure tu entorno automáticamente al arrancar, y PreToolUse avanzado para validar comandos, bloquear operaciones peligrosas, y restringir rutas de archivos. Verás la configuración en settings.json, el formato de input JSON via stdin, y dominarás los exit codes que controlan el flujo.

← Anterior5. Proyecto — Plugin de Code Quality Completo Siguiente →2. SessionStart y PreToolUse Avanzado — Setup Automático y Validación