Source: https://aiprimetech.io/es/claude-code/hooks/

[Inicio](/es/) › [Claude Code](/es/claude-code/) › Hooks

[Descripción general](/es/claude-code/)[Instalación](/es/claude-code/install/)[referencia de la CLI](/es/claude-code/cli/)[Precios y límites](/es/claude-code/pricing/)[Agent SDK](/es/claude-code/sdk/)[Habilidades y plugins](/es/claude-code/skills/)[GitHub](/es/claude-code/github/)[Web, escritorio e IDE](/es/claude-code/web-and-desktop/)[Modelos](/es/claude-code/models/)[Errores](/es/claude-code/errors/)[¿Código abierto?](/es/claude-code/open-source/)[Tutorial](/es/claude-code/tutorial/)[Para estudiantes](/es/claude-code/for-students/)[Automatización de QA](/es/claude-code/qa-automation/)[Comparación con Cursor](/es/claude-code/vs-cursor/)[Comparación con Codex y OpenCode](/es/claude-code/vs-codex/)[Subagentes](/es/claude-code/subagents/)[Hooks](/es/claude-code/hooks/)[MCP](/es/claude-code/mcp/)[Ecosistema](/es/claude-code/ecosystem/)[VS Code](/es/claude-code/vscode/)[OpenRouter](/es/claude-code/openrouter/)[Límites de solicitudes](/es/claude-code/rate-limits/)[Guía en chino](/claude-code/zh/)

Última actualización: 11 de octubre de 2026

# Hooks de Claude Code: control determinista sobre lo que hace el agente

Los hooks son comandos de shell que Claude Code ejecuta en puntos fijos de su ciclo: antes de llamar a una herramienta, después de hacerlo, cuando envías un prompt y cuando termina. A diferencia de las instrucciones de CLAUDE.md, que el modelo puede seguir o no, un hook siempre se ejecuta. Son la forma de establecer reglas que se cumplen.

## TLDR
- Se configuran en .claude/settings.json (proyecto) o ~/.claude/settings.json (usuario), o con /hooks.
- Eventos: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart.
- El hook recibe JSON en stdin (nombre de la herramienta, entrada, sesión); el código de salida 0 permite la ejecución, mientras que el código 2 la bloquea y devuelve stderr a Claude.
- Usos habituales: aplicar formato después de cada edición, bloquear comandos peligrosos, exigir pruebas antes de finalizar y mostrar notificaciones de escritorio.

## Anatomía de un hook 

```
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}
```

Tres partes: el evento, un patrón de coincidencia (una expresión regular sobre el nombre de la herramienta para los eventos de herramientas; omítelo para que coincida con todo) y uno o más comandos. El comando recibe en stdin un objeto JSON que describe el evento; para los eventos de herramientas, incluye tool_name y tool_input, que es lo que permite al ejemplo anterior encontrar el archivo que se acaba de editar. Colócalo en .claude/settings.json para compartirlo con el repositorio, ~/.claude/settings.json para uso personal, o ejecuta /hooks y deja que Claude Code lo escriba. 

## Los eventos 
- PreToolUse — antes de que se ejecute una herramienta. El único evento que puede bloquear: el código de salida 2 cancela la llamada y Claude lee tu stderr como motivo.
- PostToolUse — después de que una herramienta se ejecute correctamente. Formateadores, analizadores de código y comprobaciones de tipos sobre el archivo editado.
- UserPromptSubmit — cuando envías un prompt; puede incorporar contexto o rechazar el prompt.
- Stop / SubagentStop — cuando el agente (o un subagente) está a punto de finalizar. Aquí, el código de salida 2 significa «aún no ha terminado»; el uso clásico consiste en impedir que finalice mientras las pruebas fallen.
- PreCompact — antes de /compact; guarda todo lo que necesites de la transcripción completa.
- SessionStart — cuando una sesión comienza o se reanuda; carga el entorno e imprime recordatorios.
- Notification — cuando Claude Code necesita tu atención (solicitud de permiso, inactividad); conéctalo a una notificación de escritorio o de Slack. 

## Bloquear comandos peligrosos 

```
#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0
```

El código de salida 2 es el contrato: la llamada a la herramienta no se realiza y todo lo que el hook haya escrito en stderr se convierte en la explicación que ve Claude, para que pueda elegir otro enfoque en lugar de volver a intentar lo mismo. Cualquier otro código de salida distinto de cero se registra, pero no bloquea. 

## «No finalices hasta que las pruebas pasen» 

```
#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi
```

Combínalo con un límite de --max-turns en las ejecuciones sin interfaz para que un fallo realmente imposible de corregir no genere un bucle infinito. 

## Hooks frente a CLAUDE.md y permisos 

CLAUDE.md contiene recomendaciones que el modelo lee; /permissions es una lista de lo que puede hacer sin preguntar; los hooks son código que se ejecuta en cualquier caso. Usa CLAUDE.md para el estilo y el contexto, los permisos para delimitar qué se permite y qué requiere aprobación, y los hooks para todo lo que deba cumplirse siempre: formato, detección de secretos, controles de pruebas y registros de auditoría. Se combinan: un permiso permite ejecutar Bash(git *) , pero un hook PreToolUse sigue bloqueando git push --force. 

## Los hooks y la pasarela 

Los hooks se ejecutan localmente y nunca acceden a la API, por lo que nada cambia cuando Claude Code apunta a ANTHROPIC_BASE_URL=https://aiprimetech.io. Una combinación útil: un hook Stop que imprime datos de uso al estilo de /costa partir de tus propios registros, para que un equipo con créditos de pago por uso vea el precio de cada sesión cuando finaliza.

## Pruébalo gratis primero

Las cuentas nuevas reciben $5 de crédito gratuito para la API con el código CLAUDECODE — suficiente para una tarde de Claude Code con Sonnet — y después créditos por 7.69231× su valor nominal.

```
export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key
```

[Crea una cuenta con el código CLAUDECODE](/register?promo=CLAUDECODE)

## Preguntas frecuentes

¿Qué son los hooks de Claude Code?

Comandos de shell que Claude Code ejecuta automáticamente en eventos de su ciclo: antes y después de las llamadas a herramientas, al enviar un prompt y al finalizar. Son deterministas, a diferencia de las instrucciones de CLAUDE.md.¿Cómo bloqueo un comando con un hook?

Con un hook PreToolUse cuyo patrón de coincidencia sea Bash, que inspeccione tool_input.command desde stdin y termine con el código 2; el texto de stderr se muestra a Claude como motivo.¿Dónde se colocan los hooks?

En .claude/settings.json dentro del proyecto (compartidos) o en ~/.claude/settings.json (personales), bajo la clave hooks; /hooks permite editarlos de forma interactiva.

## Ejecuta Claude Code con la pasarela

Los mismos modelos, dos variables de entorno y créditos por 7.69231× su valor nominal, o un plan ilimitado de tarifa plana. Cuentas nuevas: $5 de crédito gratuito para la API con el código CLAUDECODE.[Obtener una clave de API](/register?promo=CLAUDECODE) [Ver planes ilimitados](/es/plans/)

AI Prime Tech es una pasarela API independiente y no está afiliada a Anthropic, ni cuenta con su respaldo o patrocinio. «Claude» y «Claude Code» son marcas comerciales de Anthropic. Las funciones de Claude Code descritas aquí se basan en la documentación pública de Anthropic en el momento de la redacción y cambian con frecuencia; los precios y las listas de modelos de esta página se obtienen de la configuración actual de esta pasarela.

## Más guías de Claude Code

[Claude Code: la guía completa](/es/claude-code/)[Cómo instalar Claude Code](/es/claude-code/install/)[Documentación de la CLI de Claude Code: comandos y opciones](/es/claude-code/cli/)[Precios y límites de Claude Code, explicados](/es/claude-code/pricing/)[El SDK de Claude Code, ahora Claude Agent SDK](/es/claude-code/sdk/)[Habilidades y plugins de Claude Code](/es/claude-code/skills/)[Claude Code en GitHub: la App, la Action y @claude](/es/claude-code/github/)[¿Claude Code tiene una interfaz web? Explicación de las versiones web, de escritorio y para IDE](/es/claude-code/web-and-desktop/)[Qué modelo utiliza Claude Code y cómo cambiarlo](/es/claude-code/models/)[Errores de Claude Code y cómo solucionarlos](/es/claude-code/errors/)[¿Claude Code es de código abierto?](/es/claude-code/open-source/)[Tutorial de Claude Code: tu primera sesión real](/es/claude-code/tutorial/)[Claude para estudiantes: Claude Code, la API y qué ofrece realmente el ámbito educativo](/es/claude-code/for-students/)[Cómo usar Claude Code para automatizar QA](/es/claude-code/qa-automation/)[Claude Code frente a Cursor: cuál usar, cuándo y cómo ejecutar ambos](/es/claude-code/vs-cursor/)[Claude Code vs Codex vs OpenCode: comparativa de los agentes de terminal](/es/claude-code/vs-codex/)[Subagentes de Claude Code: cómo funcionan, cómo definirlos y equipos de agentes](/es/claude-code/subagents/)[MCP en Claude Code: conexión de servidores, ámbitos, MCP remoto y ejemplos reales](/es/claude-code/mcp/)[El ecosistema de Claude Code: enrutadores, frameworks, plugins y las listas que los recopilan](/es/claude-code/ecosystem/)[Claude Code en VS Code: la extensión, el uso desde la terminal y los errores](/es/claude-code/vscode/)[Cómo usar OpenRouter en Claude Code (y cuándo no hacerlo)](/es/claude-code/openrouter/)[Error de límite de solicitudes de Claude: qué significa «Error de API: se ha alcanzado el límite de solicitudes» y cómo solucionarlo](/es/claude-code/rate-limits/)[Cómo usar Claude Code: desde la instalación hasta el uso diario](/claude-code/zh/)