Referencia de hooks

​

Configuración

• ~/.claude/settings.json - Configuración de usuario
• .claude/settings.json - Configuración del proyecto
• .claude/settings.local.json - Configuración local del proyecto (no confirmada)
• Configuración de política gestionada por Enterprise

​

Estructura

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

• matcher: Patrón para coincidir con nombres de herramientas, sensible a mayúsculas (solo aplicable para PreToolUse y PostToolUse)
  • Las cadenas simples coinciden exactamente: Write coincide solo con la herramienta Write
  • Admite regex: Edit|Write o Notebook.*
  • Usa * para coincidir con todas las herramientas. También puedes usar una cadena vacía ("") o dejar matcher en blanco.
• hooks: Array de comandos a ejecutar cuando el patrón coincide
  • type: Actualmente solo se admite "command"
  • command: El comando bash a ejecutar (puede usar la variable de entorno $CLAUDE_PROJECT_DIR)
  • timeout: (Opcional) Cuánto tiempo debe ejecutarse un comando, en segundos, antes de cancelar ese comando específico.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

​

Scripts de Hook Específicos del Proyecto

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

​

Hooks de complementos

• Los hooks de complementos se definen en el archivo hooks/hooks.json del complemento o en un archivo dado por una ruta personalizada al campo hooks.
• Cuando un complemento está habilitado, sus hooks se fusionan con los hooks de usuario y proyecto
• Múltiples hooks de diferentes fuentes pueden responder al mismo evento
• Los hooks de complementos usan la variable de entorno ${CLAUDE_PLUGIN_ROOT} para hacer referencia a archivos de complementos

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• ${CLAUDE_PLUGIN_ROOT}: Ruta absoluta al directorio del complemento
• ${CLAUDE_PROJECT_DIR}: Directorio raíz del proyecto (igual que para hooks de proyecto)
• Todas las variables de entorno estándar están disponibles

​

Eventos de Hook

​

PreToolUse

• Task - Tareas de subagentes (consulta la documentación de subagentes)
• Bash - Comandos de shell
• Glob - Coincidencia de patrones de archivo
• Grep - Búsqueda de contenido
• Read - Lectura de archivo
• Edit - Edición de archivo
• Write - Escritura de archivo
• WebFetch, WebSearch - Operaciones web

​

PostToolUse

​

Notification

1. Claude necesita tu permiso para usar una herramienta. Ejemplo: “Claude necesita tu permiso para usar Bash”
2. La entrada del prompt ha estado inactiva durante al menos 60 segundos. “Claude está esperando tu entrada”

​

UserPromptSubmit

​

Stop

​

SubagentStop

​

PreCompact

• manual - Invocado desde /compact
• auto - Invocado desde compactación automática (debido a ventana de contexto llena)

​

SessionStart

• startup - Invocado desde el inicio
• resume - Invocado desde --resume, --continue o /resume
• clear - Invocado desde /clear
• compact - Invocado desde compactación automática o manual.

​

Persistencia de variables de entorno

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

​

SessionEnd

• clear - Sesión borrada con comando /clear
• logout - Usuario cerró sesión
• prompt_input_exit - Usuario salió mientras la entrada del prompt era visible
• other - Otras razones de salida

​

Entrada de Hook

{
  // Common fields
  session_id: string
  transcript_path: string  // Path to conversation JSON
  cwd: string              // The current working directory when the hook is invoked
  permission_mode: string  // Current permission mode: "default", "plan", "acceptEdits", or "bypassPermissions"

  // Event-specific fields
  hook_event_name: string
  ...
}

​

Entrada de PreToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

​

Entrada de PostToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

​

Entrada de Notification

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

​

Entrada de UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

​

Entrada de Stop y SubagentStop

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

​

Entrada de PreCompact

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

​

Entrada de SessionStart

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

​

Entrada de SessionEnd

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

​

Salida de Hook

​

Simple: Código de Salida

• Código de salida 0: Éxito. stdout se muestra al usuario en modo de transcripción (CTRL-R), excepto para UserPromptSubmit y SessionStart, donde stdout se agrega al contexto.
• Código de salida 2: Error de bloqueo. stderr se retroalimenta a Claude para procesar automáticamente. Consulta el comportamiento específico de cada evento de hook a continuación.
• Otros códigos de salida: Error no bloqueante. stderr se muestra al usuario y la ejecución continúa.

​

Comportamiento del Código de Salida 2

​

Avanzado: Salida JSON

​

Campos JSON Comunes

{
  "continue": true, // Whether Claude should continue after hook execution (default: true)
  "stopReason": "string", // Message shown when continue is false

  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
  "systemMessage": "string" // Optional warning message shown to the user
}

• Para PreToolUse, esto es diferente de "permissionDecision": "deny", que solo bloquea una llamada de herramienta específica y proporciona retroalimentación automática a Claude.
• Para PostToolUse, esto es diferente de "decision": "block", que proporciona retroalimentación automatizada a Claude.
• Para UserPromptSubmit, esto evita que el prompt sea procesado.
• Para Stop y SubagentStop, esto tiene prioridad sobre cualquier salida "decision": "block".
• En todos los casos, "continue" = false tiene prioridad sobre cualquier salida "decision": "block".

​

Control de Decisión de PreToolUse

• "allow" omite el sistema de permisos. permissionDecisionReason se muestra al usuario pero no a Claude.
• "deny" evita que la llamada de herramienta se ejecute. permissionDecisionReason se muestra a Claude.
• "ask" pide al usuario que confirme la llamada de herramienta en la interfaz de usuario. permissionDecisionReason se muestra al usuario pero no a Claude.

• updatedInput te permite modificar los parámetros de entrada de la herramienta antes de que la herramienta se ejecute. Este es un objeto Record<string, unknown> que contiene los campos que deseas cambiar o agregar.
• Esto es más útil con "permissionDecision": "allow" para modificar y aprobar llamadas de herramientas.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    }
  }
}

​

Control de Decisión de PostToolUse

• "block" solicita automáticamente a Claude con reason.
• undefined no hace nada. reason se ignora.
• "hookSpecificOutput.additionalContext" agrega contexto para que Claude considere.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

​

Control de Decisión de UserPromptSubmit

• "block" evita que el prompt sea procesado. El prompt enviado se borra del contexto. "reason" se muestra al usuario pero no se agrega al contexto.
• undefined permite que el prompt proceda normalmente. "reason" se ignora.
• "hookSpecificOutput.additionalContext" agrega la cadena al contexto si no está bloqueada.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

​

Control de Decisión de Stop/SubagentStop

• "block" evita que Claude se detenga. Debes completar reason para que Claude sepa cómo proceder.
• undefined permite que Claude se detenga. reason se ignora.

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

​

Control de Decisión de SessionStart

• "hookSpecificOutput.additionalContext" agrega la cadena al contexto.
• Los valores additionalContext de múltiples hooks se concatenan.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

​

Control de Decisión de SessionEnd

​

Ejemplo de Código de Salida: Validación de Comando Bash

#!/usr/bin/env python3
import json
import re
import sys

# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Validate the command
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

​

Ejemplo de Salida JSON: UserPromptSubmit para Agregar Contexto y Validación

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
The following is also equivalent:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Allow the prompt to proceed with the additional context
sys.exit(0)

​

Ejemplo de Salida JSON: PreToolUse con Aprobación

#!/usr/bin/env python3
import json
import sys

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Example: Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use JSON output to auto-approve the tool call
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Don't show in transcript mode
        }
        print(json.dumps(output))
        sys.exit(0)

# For other cases, let the normal permission flow proceed
sys.exit(0)

​

Trabajar con Herramientas MCP

​

Nomenclatura de Herramientas MCP

• mcp__memory__create_entities - Herramienta de crear entidades del servidor Memory
• mcp__filesystem__read_file - Herramienta de leer archivo del servidor Filesystem
• mcp__github__search_repositories - Herramienta de búsqueda del servidor GitHub

​

Configurar Hooks para Herramientas MCP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

​

Ejemplos

​

Consideraciones de Seguridad

​

Descargo de Responsabilidad

• Eres el único responsable de los comandos que configures
• Los hooks pueden modificar, eliminar o acceder a cualquier archivo que tu cuenta de usuario pueda acceder
• Los hooks maliciosos o mal escritos pueden causar pérdida de datos o daño del sistema
• Anthropic no proporciona garantía y no asume responsabilidad por ningún daño resultante del uso de hooks
• Debes probar a fondo los hooks en un entorno seguro antes del uso en producción

​

Mejores Prácticas de Seguridad

1. Valida y desinfecta entradas - Nunca confíes en datos de entrada ciegamente
2. Siempre entrecomilla variables de shell - Usa "$VAR" no $VAR
3. Bloquea el recorrido de ruta - Verifica .. en rutas de archivo
4. Usa rutas absolutas - Especifica rutas completas para scripts (usa “$CLAUDE_PROJECT_DIR” para la ruta del proyecto)
5. Omite archivos sensibles - Evita .env, .git/, claves, etc.

​

Seguridad de Configuración

1. Captura una instantánea de hooks al inicio
2. Usa esta instantánea durante toda la sesión
3. Advierte si los hooks se modifican externamente
4. Requiere revisión en el menú /hooks para que los cambios se apliquen

​

Detalles de Ejecución de Hook

• Timeout: Límite de ejecución de 60 segundos por defecto, configurable por comando.
  • Un timeout para un comando individual no afecta a los otros comandos.
• Paralelización: Todos los hooks coincidentes se ejecutan en paralelo
• Deduplicación: Múltiples comandos de hook idénticos se deduplicarán automáticamente
• Entorno: Se ejecuta en el directorio actual con el entorno de Claude Code
  • La variable de entorno CLAUDE_PROJECT_DIR está disponible y contiene la ruta absoluta al directorio raíz del proyecto (donde se inició Claude Code)
  • La variable de entorno CLAUDE_CODE_REMOTE indica si el hook se ejecuta en un entorno remoto (web) ("true") o entorno CLI local (no establecido o vacío). Úsalo para ejecutar lógica diferente basada en el contexto de ejecución.
• Entrada: JSON a través de stdin
• Salida:
  • PreToolUse/PostToolUse/Stop/SubagentStop: Progreso mostrado en transcripción (Ctrl-R)
  • Notification/SessionEnd: Registrado solo en depuración (--debug)
  • UserPromptSubmit/SessionStart: stdout agregado como contexto para Claude

​

Depuración

​

Solución de Problemas Básica

1. Verifica la configuración - Ejecuta /hooks para ver si tu hook está registrado
2. Verifica la sintaxis - Asegúrate de que tu JSON de configuración sea válido
3. Prueba comandos - Ejecuta comandos de hook manualmente primero
4. Verifica permisos - Asegúrate de que los scripts sean ejecutables
5. Revisa registros - Usa claude --debug para ver detalles de ejecución de hooks

• Comillas no escapadas - Usa \" dentro de cadenas JSON
• Matcher incorrecto - Verifica que los nombres de herramientas coincidan exactamente (sensible a mayúsculas)
• Comando no encontrado - Usa rutas completas para scripts

​

Depuración Avanzada

1. Inspecciona la ejecución de hooks - Usa claude --debug para ver detalles de ejecución de hooks
2. Valida esquemas JSON - Prueba entrada/salida de hooks con herramientas externas
3. Verifica variables de entorno - Verifica que el entorno de Claude Code sea correcto
4. Prueba casos extremos - Intenta hooks con rutas de archivo o entradas inusuales
5. Monitorea recursos del sistema - Verifica el agotamiento de recursos durante la ejecución de hooks
6. Usa registro estructurado - Implementa registro en tus scripts de hook

​

Ejemplo de Salida de Depuración

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

• Qué hook se está ejecutando
• Comando siendo ejecutado
• Estado de éxito/fallo
• Mensajes de salida o error