Referencia de hooks

​

Ciclo de vida de los hooks

• por sesión: SessionStart y SessionEnd
• por turno: UserPromptSubmit, Stop y StopFailure
• en cada llamada a herramienta dentro del bucle agentico: PreToolUse y PostToolUse, excepto las llamadas EndConversation, que omiten ambas

​

Cómo se resuelve un hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # no decision; normal permission flow applies
fi

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          },
          {
            "type": "command",
            "if": "PowerShell(Remove-Item *)",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.ps1"
            ]
          }
        ]
      }
    ]
  }
}

# .claude/hooks/block-rm.ps1
$callInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
$command = $callInput.tool_input.command

if ($command -match 'rm -rf|Remove-Item.*-Recurse') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Destructive command blocked by hook"
    }
  } | ConvertTo-Json
} else {
  exit 0  # no decision; normal permission flow applies
}

{ "tool_name": "Bash", "tool_input": { "command": "rm -rf /tmp/build" }, ... }

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook"
  }
}

​

Configuración

1. Elige un evento de hook al que responder, como PreToolUse o Stop
2. Añade un grupo de matcher para filtrar cuándo se activa, como “solo para la herramienta Bash”
3. Define uno o más manejadores de hook para ejecutar cuando coincida

​

Ubicaciones de hooks

• Tus hooks de usuario, proyecto, local y plugin están bloqueados. Los hooks de plugins forzados a habilitarse en la configuración administrada enabledPlugins están exentos
• Claude Code también reduce tu configuración statusLine, fileSuggestion y subagentStatusLine a la configuración administrada
• Claude Code también deshabilita plugins con una fuente command, incluidos los plugins forzados a habilitarse en la configuración administrada enabledPlugins, a menos que disableCommandPluginSources esté explícitamente establecido en false. Las fuentes command requieren Claude Code v2.1.229 o posterior
• Claude Code también bloquea los comandos headersHelper del marketplace a menos que disableCommandPluginSources esté explícitamente establecido en false, excepto para un marketplace que la propia configuración administrada declare

• allowedHttpHookUrls: cuando se define en cualquier nivel de configuración, Claude Code ejecuta un manejador de hook HTTP solo si su URL coincide con la lista de permitidos fusionada
• httpHookAllowedEnvVars: cuando se define, Claude Code interpola solo las variables de entorno en esa lista en los encabezados de hook

​

Patrones de matcher

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

​

Coincidir herramientas MCP

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

• mcp__memory__.* coincide con todas las herramientas del servidor memory
• mcp__brave-search__.* coincide con todas las herramientas de un servidor cuyo nombre contiene un guión
• mcp__.*__write.* coincide con cualquier herramienta cuyo nombre comienza con write de cualquier servidor

{
  "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"
          }
        ]
      }
    ]
  }
}

​

Campos de manejador de hook

• Hooks de comando (type: "command"): ejecutan un comando de shell. Tu script recibe la entrada JSON del evento en stdin y comunica resultados de vuelta a través de códigos de salida y stdout.
• Hooks HTTP (type: "http"): envían la entrada JSON del evento como una solicitud HTTP POST a una URL. El punto final comunica resultados de vuelta a través del cuerpo de respuesta utilizando el mismo formato de salida JSON que los hooks de comando.
• Hooks de herramienta MCP (type: "mcp_tool"): llaman a una herramienta en un servidor MCP configurado. La salida de texto de la herramienta se trata como stdout de hook de comando.
• Hooks de prompt (type: "prompt"): envían un prompt a un modelo Claude para evaluación de un solo turno. El modelo devuelve su decisión como JSON. Consulta Hooks basados en prompt.
• Hooks de agente (type: "agent"): generan un subagente que puede usar herramientas como Read, Grep y Glob para verificar condiciones antes de devolver una decisión. Los hooks de agente son experimentales y pueden cambiar. Consulta Hooks basados en agente.

​

Campos comunes

​

Campos de hook de comando

{
  "type": "command",
  "command": "node",
  "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/format.js", "--fix"]
}

{
  "type": "command",
  "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/format.js --fix"
}

​

Campos de hook HTTP

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30,
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Campos de hook de herramienta MCP

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": { "file_path": "${tool_input.file_path}" }
          }
        ]
      }
    ]
  }
}

​

Campos de hook de prompt y agente

​

Referencia de scripts por ruta

• ${CLAUDE_PROJECT_DIR}: la raíz del proyecto donde comenzó la sesión. Claude Code también establece esta variable en el entorno de servidores MCP stdio y servidores LSP de plugin.
• ${CLAUDE_PLUGIN_ROOT}: el directorio de instalación del plugin, para scripts incluidos con un plugin. Consulta variables de entorno de plugin para saber cómo se comporta la ruta entre actualizaciones.
• ${CLAUDE_PLUGIN_DATA}: el directorio de datos persistentes del plugin, para dependencias y estado que deben sobrevivir a las actualizaciones del plugin.

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

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

​

Hooks en skills y agentes

• Hooks de subagente: Claude Code los ejecuta solo mientras ese subagente se está ejecutando y los elimina cuando termina. Claude Code convierte un hook Stop aquí a SubagentStop, el evento que se activa cuando un subagente se completa.
• Hooks de skill: Claude Code los registra cuando tú o Claude invocas la skill y los mantiene ejecutándose durante el resto de la sesión, en turnos después del turno propio de la skill también. Para que Claude Code elimine un hook después de su primera ejecución exitosa en su lugar, establece once: true en él.

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

​

El menú /hooks

• User Settings: de ~/.claude/settings.json
• Project Settings: de .claude/settings.json
• Local Settings: de .claude/settings.local.json
• Plugin Hooks: de hooks/hooks.json de un plugin
• Session Hooks: registrado en memoria para la sesión actual

​

Deshabilitar o eliminar hooks

​

Entrada y salida de hooks

​

Campos de entrada comunes

{
  "session_id": "abc123",
  "prompt_id": "550e8400-e29b-41d4-a716-446655440000",
  "transcript_path": "/home/user/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/user/my-project",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite",
    "timeout": 120000,
    "run_in_background": false
  },
  "tool_use_id": "toolu_01ABC123..."
}

​

Salida de código de salida

​

Exit code 0

• Comienza con { y termina con }: Claude Code lo analiza como JSON. Cuando la salida son dos o más líneas que cada una se analiza como JSON por su cuenta, y ninguna línea es un objeto JSON output que establece un campo, Claude Code trata toda la salida como texto plano. Cuando una de esas líneas sí establece un campo, toda la salida es un fallo de análisis, descrito a continuación.
• Comienza con { pero no termina con }: Claude Code lo trata como texto plano.
• Comienza con cualquier otra cosa: Claude Code lo trata como texto plano, una matriz JSON o una cadena JSON entrecomillada incluida.

​

Exit code 2

#!/bin/bash
# Lee entrada JSON desde stdin, verifica el comando
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")

if [[ "$command" == rm* ]]; then
  echo "Blocked: rm commands are not allowed" >&2
  exit 2  # Blocking error: tool call is prevented
fi

exit 0  # No decision: the normal permission flow applies

​

Otros códigos de salida

• Con un objeto analizado que pasa la validación del esquema, para eventos que usan el modelo de decisión estándar, Claude Code ignora el código de salida y solo el JSON decide el resultado:
  • Cada campo que el evento admite se honra, incluyendo permissionDecision, additionalContext, updatedInput y systemMessage, y el hook no se reporta como un error.
  • Decision control enumera los campos de decisión por evento; campos universales como systemMessage siguen la tabla JSON output.
• Con un objeto analizado que falla la validación del esquema, para eventos que usan el modelo de decisión estándar, es el mismo error sin bloqueo que en exit 0: la acción procede, y el aviso <hook name> hook error lleva el mensaje de validación.
• Con stdout que Claude Code intenta analizar como JSON y no puede, Claude Code reporta el mismo error sin bloqueo que en exit 0 para eventos que usan el modelo de decisión estándar. La acción procede, y el aviso lleva el mensaje de análisis.
• Con stdout que Claude Code trata como texto plano, o con stdout vacío, es un error sin bloqueo para la mayoría de eventos de hook: la acción procede, y la transcripción muestra un aviso <hook name> hook error seguido de la primera línea de stderr, prefijado con Failed with non-blocking status code:. Para capturar el stderr completo, habilite debug logging.

​

Tiempos de espera

• Un hook command, http o mcp_tool agotado no bloquea la llamada a herramienta. La llamada continúa a través del flujo de permiso normal, así que no cuente con un hook estancado para actuar como puerta.
• Un hook de callback Agent SDK que excede su timeout bloquea la llamada a herramienta.

​

Comportamiento del código de salida 2 por evento

​

Manejo de respuesta HTTP

• 2xx con un cuerpo vacío: éxito, equivalente a código de salida 0 sin salida
• 2xx con un cuerpo de objeto JSON: analizado usando el mismo esquema JSON output que los hooks de comando. Un cuerpo que falla la validación del esquema es un error sin bloqueo
• 2xx con cualquier otro cuerpo, como texto plano: error sin bloqueo, manejado igual que un estado que no es 2xx. Claude Code no agrega el texto al contexto de Claude
• Estado que no es 2xx: error sin bloqueo, la ejecución continúa
• Fallo de conexión: error sin bloqueo, la ejecución continúa
• Tiempo de espera: el hook se cancela, como se describe bajo Timeouts

​

Salida JSON

• Alcance: Claude Code mide cada cadena por su cuenta, incluso cuando varios hooks se ejecutan para el mismo evento. Para salida JSON, cada campo se mide por separado; stdout plano se mide en su totalidad.
• Sobre el límite: Claude Code guarda la salida en un archivo en el directorio de sesión y la reemplaza con la ruta del archivo y una vista previa de hasta los primeros 2.000 caracteres. Un resultado de Bash válido grande se maneja de la misma manera, descrito bajo Output limits. A diferencia de ese techo de Bash, este límite no tiene configuración o variable de entorno para aumentarlo.
• Lectura del archivo: Claude Code no le pide a Claude que lea el archivo, así que mantenga cualquier cosa que Claude siempre deba ver dentro del límite.

• Campos universales como continue se enumeran en la tabla a continuación. Cada evento los acepta, pero algunos eventos los descartan o entregan systemMessage en otro lugar que no sea la transcripción. Cada sección de evento lo indica. terminalSequence funciona en esos eventos también, con las excepciones enumeradas bajo Emit terminal notifications.
• decision y reason de nivel superior son utilizados por algunos eventos para bloquear o proporcionar retroalimentación.
• hookSpecificOutput es un objeto anidado para eventos que necesitan control más rico. Requiere un campo hookEventName establecido en el nombre del evento.

{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

​

Emitir notificaciones de terminal

• OSC 0, 1, 2: títulos de ventana e icono
• OSC 9: notificaciones de iTerm2, ConEmu, Windows Terminal y WezTerm, incluyendo progreso de barra de tareas 9;4
• OSC 99: notificaciones de Kitty
• OSC 777: notificaciones de urxvt, Ghostty y Warp
• BEL desnudo

• Claude Code escribe la secuencia solo en una sesión interactiva, y solo mientras su interfaz está en pantalla. En modo no interactivo con la bandera -p y en Agent SDK, ignora el campo.
• Un hook de comando WorktreeCreate no puede devolver JSON, porque Claude Code lee su stdout como la ruta de worktree. Un hook HTTP WorktreeCreate devuelve JSON y puede incluir el campo.

#!/bin/bash
# Hook de notificación: ping al escritorio cuando Claude Code necesita atención.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

​

Agregar contexto para Claude

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "This file is generated. Edit src/schema.ts and run `bun generate` instead."
  }
}

• SessionStart y SubagentStart: al inicio de la conversación, antes del primer prompt
• UserPromptSubmit y UserPromptExpansion: junto al prompt enviado
• PreToolUse, PostToolUse, PostToolUseFailure y PostToolBatch: junto al resultado de la herramienta
• Stop y SubagentStop: al final del turno. La conversación continúa para que Claude pueda actuar sobre la retroalimentación. Consulte Stop decision control
• PostModelSwitch: con la siguiente solicitud después del cambio. Consulte PostModelSwitch decision control para el tiempo

• Estado del entorno: la rama actual, destino de implementación o banderas de características activas
• Reglas de proyecto condicionales: qué comando de prueba se aplica al archivo que acaba de editar, qué directorios son de solo lectura en este worktree
• Datos externos: problemas abiertos asignados a usted, resultados recientes de CI, contenido obtenido de un servicio interno

​

Control de decisión

• PreToolUse: updatedInput directamente bajo hookSpecificOutput reemplaza los argumentos de una herramienta antes de que se ejecute. Consulte PreToolUse decision control
• PermissionRequest: updatedInput dentro del objeto decision. Consulte PermissionRequest decision control
• PostToolUse: updatedToolOutput reemplaza el resultado de la herramienta. Consulte PostToolUse decision control
• UserPromptSubmit: no puede reemplazar el prompt; solo inyecta additionalContext junto a él

{
  "decision": "block",
  "reason": "Test suite must pass before proceeding"
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Eventos de hooks

​

SessionStart

​

Entrada de SessionStart

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionStart",
  "source": "resume",
  "model": "claude-opus-5",
  "seconds_since_last_response": 5400,
  "context_tokens": 182340,
  "prompt_cache_likely_expired": true,
  "estimated_cache_write_usd": 1.1396
}

​

Control de decisión de SessionStart

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Current branch: feat/auth-refactor\nUncommitted changes: src/auth.ts, src/login.tsx\nActive issue: #4211 Migrate to OAuth2",
    "sessionTitle": "auth-refactor"
  }
}

#!/bin/bash

git -C ~/.claude/skills/team-skills pull --quiet 2>/dev/null || \
  git clone --quiet https://git.example.com/your-org/team-skills.git ~/.claude/skills/team-skills

echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

​

Persistir variables de entorno

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export DEBUG_LOG=true' >> "$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

​

Setup

​

Entrada de Setup

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Setup",
  "trigger": "init"
}

​

Control de decisión de Setup

​

InstructionsLoaded

​

Entrada de InstructionsLoaded

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "InstructionsLoaded",
  "file_path": "/Users/my-project/CLAUDE.md",
  "memory_type": "Project",
  "load_reason": "session_start"
}

​

Control de decisión de InstructionsLoaded

​

UserPromptSubmit

​

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"
}

​

Control de decisión de UserPromptSubmit

• Stdout de texto plano: Claude Code añade stdout que trata como texto plano al contexto de Claude
• JSON con additionalContext: usa el formato JSON a continuación para más control. El campo additionalContext se añade como contexto

{
  "decision": "block",
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here",
    "sessionTitle": "My session title"
  }
}

​

UserPromptExpansion

​

Entrada de UserPromptExpansion

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../00893aaf.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptExpansion",
  "expansion_type": "slash_command",
  "command_name": "example-skill",
  "command_args": "arg1 arg2",
  "command_source": "plugin",
  "prompt": "/example-skill arg1 arg2"
}

​

Control de decisión de UserPromptExpansion

{
  "decision": "block",
  "reason": "This slash command is not available",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptExpansion",
    "additionalContext": "Additional context for this expansion"
  }
}

​

MessageDisplay

• eliminar markdown para una visualización mínima
• transformar el texto que una aplicación del Agent SDK muestra a sus usuarios
• redactar claves API o nombres de host internos de las respuestas de Claude

​

Entrada de MessageDisplay

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "MessageDisplay",
  "turn_id": "0c9e6a2f-7d41-4f4e-9a15-3f4f7c2b8d10",
  "message_id": "5b2a9c8e-1f63-4d8a-b7c4-9e0d2a6f1c3b",
  "index": 0,
  "final": false,
  "delta": "Here is the plan:\n"
}

​

Salida de MessageDisplay

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

#!/bin/bash
jq '{hookSpecificOutput: {hookEventName: "MessageDisplay", displayContent: (.delta | gsub("\\*\\*"; "") | gsub("`"; ""))}}'

{
  "hooks": {
    "MessageDisplay": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe",
            "args": [
              "-NoProfile",
              "-ExecutionPolicy",
              "Bypass",
              "-File",
              "${CLAUDE_PROJECT_DIR}/.claude/hooks/plain-display.ps1"
            ]
          }
        ]
      }
    ]
  }
}

$batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
$text = $batch.delta -replace '\*\*', '' -replace '`', ''
@{
  hookSpecificOutput = @{
    hookEventName = "MessageDisplay"
    displayContent = $text
  }
} | ConvertTo-Json

​

PreToolUse

​

Entrada de PreToolUse

• Claude Code expande ~ y rutas relativas antes de que se ejecuten los hooks, por lo que un hook que coincida en rutas no puede ser eludido a través de ~ o un deletreo relativo de la misma ruta
• En Windows, la ruta llega con separadores de barra invertida, incluso cuando tu hook se ejecuta bajo Git Bash donde $PWD se ve como /c/project
• Una comparación escrita con barras diagonales, como una verificación /src/, nunca coincide con una ruta de barra invertida, y la llamada de herramienta continúa como si el hook no tuviera nada que bloquear
• Normaliza separadores antes de comparar: FILE_PATH="${FILE_PATH//\\//}" en Bash, o file_path.replace("\\", "/") en Python, luego coincide con un segmento de ruta como /src/ en lugar de anclar con ^, ya que la ruta es absoluta

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "C:\\project\\src\\index.ts",
    "content": "..."
  },
  ...
}

• En Windows, dondequiera que la herramienta PowerShell esté habilitada, Claude trata PowerShell como el shell principal y enruta comandos de shell a través de él.
• En Windows sin Git Bash, la herramienta se habilita automáticamente y Claude Code no registra la herramienta Bash en absoluto.
• Un hook que coincide solo con Bash nunca se dispara allí.

​

Control de decisión de PreToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    },
    "additionalContext": "Current environment: production. Proceed with caution."
  }
}

​

Diferir una llamada de herramienta para más tarde

1. Claude llama a AskUserQuestion. Se dispara el hook PreToolUse.
2. El hook devuelve permissionDecision: "defer". La herramienta no se ejecuta. El proceso sale con stop_reason: "tool_deferred" y la llamada de herramienta pendiente preservada en la transcripción.
3. El proceso de llamada lee deferred_tool_use del resultado del SDK, muestra la pregunta en su propia UI, y espera una respuesta.
4. El proceso de llamada ejecuta claude -p --resume <session-id> con el mismo host de permiso. Se dispara la misma llamada de herramienta PreToolUse nuevamente.
5. El hook devuelve permissionDecision: "allow" con la respuesta en updatedInput. La herramienta se ejecuta y Claude continúa.

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

​

PermissionRequest

​

Entrada de PermissionRequest

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

​

Control de decisión de PermissionRequest

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

​

Entradas de actualización de permiso

​

PostToolUse

• Para ejecutar un hook después de que cualquier herramienta se complete exitosamente, omite el matcher o establécelo en "*". Tu hook puede entonces descubrir qué cambió por sí mismo, por ejemplo ejecutando git status --porcelain, que también enumera archivos sin seguimiento que git diff pierde. Para llamadas de herramienta que fallan, añade el mismo hook bajo PostToolUseFailure.
• Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, usa FileChanged. Claude Code no ejecuta un hook PostToolUse que coincida con Edit|Write cuando un comando Bash o un proceso fuera de Claude Code reescribe el mismo archivo.

​

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",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

​

Control de decisión de PostToolUse

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

​

Anotar un resultado para el clasificador de modo automático

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

• Hooks configurados en Claude Code: para hooks de archivos de configuración, plugins, skills y frontmatter del agente, el clasificador trata la nota como contexto no verificado proporcionado por la aplicación. La nota nunca establece intención del usuario, y si afirma que aprobaste o solicitaste algo, el clasificador verifica esa afirmación contra tus propios mensajes en la conversación
• Callbacks del Agent SDK en proceso: cuando una aplicación que integra Claude Code registra el hook como un callback del SDK de TypeScript y devuelve la nota durante la sesión en vivo, el clasificador puede pesar una declaración del usuario retransmitida en la nota como intención del usuario. Tal declaración puede satisfacer un requisito de consentimiento que el clasificador aceptaría de un mensaje que envíes, pero nunca levanta un bloqueo que tu propio mensaje tampoco pudiera levantar. Después de que se reanuda una sesión, Claude Code trata las notas restauradas como contexto no verificado. Cuando hooks de ambos grupos anotan la misma llamada, el clasificador trata la nota combinada como no verificada

• Longitud: Claude Code limita las notas para una llamada de herramienta a 2,000 caracteres y trunca el resto. El límite se comparte en cada hook que responde a esa llamada
• Solo respuestas sincrónicas: Claude Code ignora el campo en la respuesta de un hook que se ejecuta en segundo plano, porque esa respuesta llega después de que Claude Code registra el resultado de la herramienta
• Llamadas que el clasificador no registra: la transcripción del clasificador omite búsquedas de solo lectura como lecturas de archivo y búsquedas. Claude Code descarta una nota adjunta a una de esas llamadas
• Interacción con reescrituras: cuando la nota describe salida que estás reemplazando con updatedToolOutput, devuelve ambos campos en la misma respuesta del hook. Claude Code descarta la nota si esa reescritura se rechaza u otro hook la reemplaza. Claude Code entrega una nota que devuelves sin una reescritura incluso cuando otro hook reescribe la salida

​

PostToolUseFailure

​

Entrada de PostToolUseFailure

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

• Para Bash y PowerShell, un comando que se ejecutó y salió produce una primera línea Exit code N, luego cualquier salida que el comando produjo como un bloque con stdout y stderr intercalados
• Un payload también puede llevar un mensaje de fallo desnudo sin línea de código de salida, cuando Claude Code no pudo iniciar el proceso de shell en sí
• Claude Code trunca a mitad de cadenas largas alrededor de un marcador ... [N characters truncated] ..., e puede insertar líneas propias, como Command timed out after 2m 0s

​

Control de decisión de PostToolUseFailure

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

​

PostToolBatch