SSD Nodes Learn Hosting plans →
Guías Matt ConnorPor Matt Connor

Hooks de Claude Code: eventos, ubicación y código 2

Aprende dónde se configuran los hooks de Claude Code, qué eventos los activan y cómo el código de salida 2 bloquea una herramienta antes de ejecutarse.

Qué es un hook de Claude Code

Los hooks de Claude Code son comandos de shell que Claude Code ejecuta automáticamente en puntos concretos de su propio ciclo de vida. Esta es la diferencia principal entre un hook y un archivo de reglas. Una instrucción en CLAUDE.md es una recomendación, y el modelo la pondera frente al resto del contexto. Un hook es código y se ejecuta tanto si el modelo está de acuerdo como si no. Si el agente sigue omitiendo el formateador que le indicó dos veces, no necesita una instrucción más firme. Necesita un hook.

El mecanismo es sencillo. Registra un comando en un archivo de configuración bajo el nombre de un evento. Cuando se activa ese evento, Claude Code ejecuta el comando y escribe los datos del evento en su entrada estándar (stdin) como JSON (notación de objetos de JavaScript). El comando lee esos datos, realiza su trabajo y responde con un estado de salida. El estado de salida 2 de un hook PreToolUse cancela la llamada a la herramienta antes de que se ejecute, y lo que el script haya escrito en la salida de error estándar (stderr) se devuelve al modelo como motivo, salvo que el hook también imprima JSON con una decisión de bloqueo, cuyo motivo tiene prioridad.

Los nombres de los eventos y de los campos indicados aquí proceden de la referencia de hooks de Claude Code, consultada el 12 de noviembre de 2026. Esta interfaz cambia rápidamente, así que consulte la referencia correspondiente a su versión antes de copiar JSON de cualquier publicación de blog, incluida esta. Muestre la suya con claude --version.

Dónde se encuentra la configuración de los hooks

Un hook es un bloque JSON dentro de un archivo de configuración. Puede definirse en seis ubicaciones, y el ámbito del archivo determina el ámbito del hook.

  • ~/.claude/settings.json: todos los proyectos de su equipo, pero sólo en su máquina.
  • .claude/settings.json: un proyecto, confirmado en el repositorio, para que todos los que lo clonen obtengan el hook.
  • .claude/settings.local.json: un proyecto, únicamente en su máquina.
  • Configuración de políticas administradas: para toda la organización, definida por un administrador.
  • hooks/hooks.json dentro de un plugin: permanece activo mientras el plugin esté habilitado.
  • Frontmatter de una skill o de un subagent. Los hooks de una skill permanecen activos durante el resto de la sesión una vez invocada la skill, y los hooks de un subagent están activos mientras se ejecuta ese subagent.

Las entradas de hook de estos archivos se combinan en lugar de sobrescribirse. Un archivo de configuración del proyecto añade sus hooks a los definidos en la configuración del usuario, en lugar de reemplazarlos. Por tanto, un evento puede contener varios hooks procedentes de varios archivos. Definir "disableAllHooks": true los desactiva, con una excepción: los hooks de la configuración de políticas administradas siguen ejecutándose, a menos que ese ajuste también se aplique en la configuración administrada.

Ejecute /hooks dentro de una sesión para mostrar todos los hooks registrados actualmente, agrupados por evento, junto con el archivo de origen y el matcher de cada uno. El menú es de sólo lectura, por lo que debe modificar un hook editando el archivo de configuración. El observador de archivos suele detectar el cambio sin necesidad de reiniciar.

Qué eventos de hooks existen en Claude Code

La referencia de hooks enumera treinta y tres eventos, desde SessionStart hasta SessionEnd, que abarcan la compactación, los subagentes, los worktrees y los archivos de configuración. En la administración de servidores se utilizan unos pocos.

  • PreToolUse: antes de que se ejecute una llamada a una herramienta, excepto EndConversation. Es el único que puede bloquearla.
  • PostToolUse: después de que una llamada a una herramienta se complete correctamente, excepto EndConversation. PostToolUseFailure se activa cuando falla, por lo que un hook que deba recibir todos los resultados necesita ambos.
  • PermissionRequest: cuando una llamada a una herramienta necesita una decisión de permisos, es decir, en el momento en que aparecería la solicitud de aprobación.
  • UserPromptSubmit: cuando se envía un prompt, antes de que Claude lo procese. La salida stdout de texto plano de un hook completado correctamente se añade al contexto del modelo.
  • SessionStart y SessionEnd: al inicio y al final de cada sesión. SessionStart también se activa después de la compactación, con el valor de matcher compact.
  • Stop: cuando Claude termina de responder. Se activa una vez por turno, no una vez por tarea completada.

En los eventos que admiten matchers, un grupo puede incluir un matcher que determina en qué casos se ejecuta el hook. En los eventos de herramientas, filtra por nombre de herramienta, por lo que "Edit|Write" se activa en las ediciones de archivos y en ningún otro caso. Los matchers distinguen mayúsculas y minúsculas. Un matcher vacío se activa en todos los casos. Las herramientas de un servidor MCP (protocolo de contexto del modelo) se denominan mcp__<server>__<tool>, por lo que un matcher "mcp__github__.*" captura las herramientas de un servidor y deja fuera las demás.

Los hooks Stop tienen una particularidad que conviene conocer antes de escribir uno. Un hook Stop que bloquea devuelve el modelo al trabajo y, de forma predeterminada, Claude Code anula el siguiente bloqueo después de ocho continuaciones consecutivas. El contador se restablece cada vez que Claude llama a una herramienta. Lea el campo stop_hook_active de la entrada del hook y salga con el código 0 cuando su valor sea true; de lo contrario, el hook puede devolver continuamente Claude al trabajo.

Qué recibe un hook por stdin

Cuando Claude está a punto de ejecutar npm test, un hook PreToolUse en Bash lee lo siguiente por stdin:

{
  "session_id": "abc123",
  "cwd": "/home/deploy/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Los campos de entrada habituales incluyen session_id, cwd, transcript_path y hook_event_name; permission_mode no se envía en todos los eventos. Los eventos de herramientas añaden tool_name, tool_input y tool_use_id. Otros eventos tienen sus propios campos: UserPromptSubmit recibe el texto prompt, y SessionStart recibe un source de startup, resume, clear, compact o fork.

jq es la forma habitual de leer estos datos dentro de un script de shell, y una imagen de servidor mínima no lo incluye. Instálelo primero con sudo apt install -y jq en Ubuntu y Debian.

Qué efecto tiene el estado de salida sobre la llamada a la herramienta en curso

Hay tres resultados posibles.

  • El estado de salida 0 indica éxito, y los campos de decisión válidos de JSON siguen aplicándose, incluido el bloqueo o la denegación. En PreToolUse, un estado de salida 0 sin una decisión no constituye una aprobación, y el flujo normal de permisos sigue ejecutándose. En UserPromptSubmit, UserPromptExpansion, SessionStart y PostModelSwitch, la salida estándar en texto plano se añade al contexto del modelo. En la mayoría de los demás eventos, la salida estándar sólo se escribe en el registro de depuración.
  • El estado de salida 2 bloquea la acción en los eventos que admiten bloqueos, incluido PreToolUse, y el error estándar se convierte en el mensaje asociado al bloqueo, salvo que la salida JSON contenga una decisión de bloqueo; en ese caso, prevalece el motivo indicado allí. Quién lee ese mensaje depende del evento. En PreToolUse y Stop, el modelo lo ve como el motivo. En UserPromptSubmit y PreModelSwitch, se muestra al usuario y no se añade al contexto del modelo. En PostToolUse y PostToolUseFailure, que no admiten bloqueos, el bloqueo se ignora, aunque el error estándar sigue llegando al modelo como información de respuesta. En la mayoría de los demás eventos que no admiten bloqueos, el error estándar sólo se muestra al usuario o se ignora. En Stop, SubagentStop, TaskCompleted y el hook UserPromptSubmit de un plugin, un estado de salida 2 con salida estándar vacía y un error de archivo inexistente en el error estándar se trata como un error que no bloquea.
  • Cualquier otro código de salida con salida estándar en texto plano o vacía normalmente se trata como un error que no bloquea. La transcripción muestra un aviso de error del hook que incluye la primera línea del error estándar después del texto Failed with non-blocking status code:. El JSON válido todavía puede decidir el resultado en eventos como PreToolUse, salvo que el fallo del hook bloquee la acción. WorktreeCreate falla con cualquier salida distinta de cero, y WorktreeRemove falla con una salida distinta de cero si el directorio sigue existiendo después.

Para cualquier resultado distinto de bloquear o no hacer nada, use un estado de salida 0 y escriba un objeto JSON en la salida estándar. Un hook PreToolUse toma la decisión mediante permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" omite el aviso interactivo cuando las reglas de permisos y los requisitos de aprobación de la herramienta lo permiten, "deny" cancela la llamada y envía el motivo al modelo, y "ask" solicita confirmación. Elija un único estilo para cada hook. Combinar el estado de salida 2 con una decisión JSON en la salida estándar mantiene el bloqueo, aunque el JSON indique "allow".

Cuando varios hooks coinciden con un mismo evento, se ejecutan en paralelo, y los hooks de avisos y de agentes tienen un límite de doce ejecuciones simultáneas. Un deny de un hook no detiene a sus hooks hermanos, por lo que un hook de registro sigue escribiendo su línea mientras un hook de protección bloquea la misma llamada. Para PreToolUse, Claude Code combina entonces las respuestas y conserva la más restrictiva, en este orden: denegar, aplazar, preguntar, permitir.

Ejemplo 1: bloquear un comando destructivo antes de que se ejecute

Guarde esto como .claude/hooks/block-destructive.sh en su proyecto:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Hágalo ejecutable y regístrelo después en PreToolUse dentro de .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Pruebe el script manualmente antes de confiar en él, porque un hook que falla al procesar su propia entrada normalmente permite la operación cuando onFailure no está definido. En Windows sin Git Bash, un hook de comando con formato de shell PreToolUse o PermissionRequest que falla puede bloquear en su lugar la llamada a la herramienta:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Debería ver la línea Blocked by policy: en stderr y un código de salida 2. Introduzca un comando inocuo, como ls -la, y no debería ver ninguna salida. El código de salida debería ser 0. En una sesión, la llamada denegada aparece en la transcripción con su mensaje como motivo, y el modelo lee ese mensaje y adapta su comportamiento.

Una propiedad hace que esto sea útil: los hooks de PreToolUse se ejecutan antes de comprobar el modo de permisos, en todos los modos de permisos. Por tanto, una denegación se mantiene incluso con bypassPermissions. Esto hace que un hook sea útil junto con el modo automático y la configuración de permisos de Claude Code, donde se reducen las solicitudes de confirmación, pero el hook se sigue ejecutando.

Sea claro sobre lo que ofrece este mecanismo. La coincidencia de patrones en una cadena de comando es una medida de protección contra los descuidos de un agente. No constituye una barrera contra un agente que actúe de forma deliberada, porque el mismo comando puede escribirse de una forma que su grep no detecte. Las reglas estrictas deben definirse en el sistema de permisos y en la cuenta con la que se ejecuta el proceso.

Ejemplo 2: aplicar formato y lint después de cada edición

PostToolUse con un matcher Edit|Write se ejecuta después de que cualquiera de esas herramientas de edición de archivos termine correctamente. Guárdelo como .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Pida a Claude que añada una función con una indentación incorrecta a un archivo de Python y, después, abra el archivo. El archivo aparecerá con el formato corregido. Esa es la comprobación de que el hook se ejecutó, porque un hook correcto no muestra nada en la conversación.

El código de salida 2 no deshace nada. PostToolUse se ejecuta después de que la herramienta ya haya terminado, por lo que la edición queda guardada en el disco en cualquier caso. Lo que aporta el código de salida 2 es que la salida de ruff check llega al modelo como información de retorno. Así, corrige el error que acaba de introducir en lugar de continuar. Esta es la diferencia entre un fallo de lint que se detecta al hacer commit y uno que el agente corrige en el mismo turno.

Aquí importan dos limitaciones de los matchers. Edit|Write no detecta los archivos modificados por un comando de shell, y Claude escribe archivos mediante Bash con suficiente frecuencia como para que esa limitación sea relevante. Para cubrir cada llamada, haga que el matcher incluya también Bash y que el script enumere los archivos modificados mediante git status --porcelain. Para cubrir una vez por turno, coloque el análisis en un hook Stop.

Ejemplo 3: registrar cada llamada a una herramienta para auditoría

Un comparador vacío en PostToolUse se ejecuta en cada llamada correcta a una herramienta, excepto EndConversation. Enviar el registro al journal del sistema en lugar de a un archivo del directorio de inicio no impide que el propio shell del agente acceda a él: el acceso depende de los permisos de la cuenta. Los usuarios pueden leer sus journals privados por usuario, y root y los miembros de systemd-journal, adm o wheel pueden leer todos los archivos del journal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Léalo con journalctl -t claude-code -o cat | tail -n 5. Si tiene permiso para leer los registros, debería ver una línea JSON por cada llamada correcta a una herramienta distinta de EndConversation, con la más reciente al final. Si no aparece nada, compruebe tanto el acceso al journal como la ejecución del hook; la sección de solución de problemas siguiente explica cómo revisar el hook.

Añada el mismo bloque bajo PostToolUseFailure para capturar las llamadas que fallaron, porque PostToolUse sólo se ejecuta cuando la llamada termina correctamente y un comando fallido suele ser el más importante. La razón para usar logger en lugar de añadir datos a un archivo del directorio de inicio es la propiedad: un hook se ejecuta con el mismo usuario que el shell del agente, por lo que todo lo que ese usuario puede modificar mediante adición también puede truncarlo. systemd-journald escribe el journal; impedir que se elimine sigue dependiendo de los privilegios de la cuenta del agente.

Cuánto tiempo puede ejecutarse un hook

GráficoDefault hook timeout in seconds, by hook type and event
Los datos de este gráfico
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

De forma predeterminada, un hook de comandos dispone de 600 segundos, es decir, diez minutos. Algunos eventos reducen ese tiempo considerablemente. Los hooks SessionEnd comparten un presupuesto de 1.5 segundos entre todos, por lo que la limpieza al finalizar la sesión debe ser rápida. Sin embargo, si establece un timeout más largo para un hook en los archivos de configuración, el presupuesto compartido aumenta hasta ese valor, con un máximo de 60 segundos.

Un hook síncrono de comandos, HTTP o de una herramienta MCP que alcanza su tiempo de espera se cancela y normalmente no genera ninguna decisión. En PreModelSwitch, un tiempo de espera bloquea el cambio. Para una protección PreToolUse, un tiempo de espera normalmente permite que la llamada a la herramienta continúe por el flujo normal de permisos, con la excepción de Windows indicada anteriormente cuando onFailure no está establecido. Por ese motivo, los scripts de protección deben ser pequeños. Desde la versión 2.1.295, puede invertir ese comportamiento predeterminado en un hook command o http mediante "onFailure": "block". Así, un tiempo de espera, un fallo o un código de salida inesperado se convierten en un bloqueo. Esta opción no tiene efecto en Stop, SubagentStop, TaskCompleted, TeammateIdle ni en los hooks de comandos en segundo plano. Para trabajos lentos que no requieren esperar, como enviar un registro a otra ubicación, establezca "async": true. El hook se ejecutará en segundo plano sin retrasar la llamada a la herramienta.

Hooks, archivos de reglas, skills y servidores MCP

Cuatro elementos se confunden entre sí porque todos cambian lo que hace un agente. Sólo uno deja de ser una sugerencia.

Un archivo de reglas (CLAUDE.md o un archivo dentro de .claude/rules/) es texto que se carga en el contexto del modelo. Da forma al comportamiento, pero no impone nada. En una conversación larga, un diff grande y una solicitud nueva del usuario, una de sus líneas puede quedar relegada. Ese es el mecanismo habitual por el que ocurre que los agentes ignoran las instrucciones que escribió.

Una skill es una carpeta de instrucciones y scripts que el modelo carga cuando considera que la skill es relevante. Esa decisión es el objetivo de una skill y también su límite: el modelo sigue decidiendo. Puede ver ambos aspectos en una skill como Ponytail, que orienta al agente hacia el cambio más pequeño que funciona, porque determina cómo se aborda una tarea completa de una forma que ningún hook podría conseguir, y sólo mientras el modelo decide cargarla.

Un servidor MCP (model context protocol) proporciona al modelo nuevas herramientas que puede utilizar. Amplía el alcance del agente. No hace que el agente utilice ninguna herramienta, y es un proceso independiente que debe operar, lo que constituye una tarea propia: consulte cómo ejecutar servidores MCP en un VPS.

Un hook es el único de los cuatro que se ejecuta sin que el modelo lo elija. Use un archivo de reglas para una preferencia y una skill para un procedimiento que el modelo deba seguir cuando corresponda. Use un hook para el paso que debe ejecutarse siempre o para lo que nunca debe ocurrir. La comparación detallada, incluido cuándo una skill es mejor que un archivo de reglas, está en la comparación entre skills, MCP y archivos de reglas.

Un plugin es una forma de empaquetado, no un quinto mecanismo. Agrupa hooks y skills en una unidad instalable. Así un equipo puede distribuir la misma protección a todas las máquinas: consulte cómo funcionan los plugins de Claude Code.

La decisión de seguridad en un VPS compartido

Un hook es código que activa el agente y se ejecuta con el usuario que inició Claude Code. Hereda los permisos de archivos y el entorno de ese usuario. En un portátil, esto es una cuestión de flujo de trabajo. En un VPS donde un agente se ejecuta sin supervisión, es una cuestión de seguridad con cuatro aspectos prácticos.

Un hook de un repositorio es código que usted no ha escrito. .claude/settings.json está versionado, por lo que clonar un repositorio e iniciar una sesión dentro de él puede registrar hooks incluidos en el repositorio. En una sesión interactiva, Claude Code bloquea los hooks del proyecto mediante el cuadro de diálogo de confianza del espacio de trabajo para esa carpeta. Esto significa que aceptar la confianza es el momento en que decide ejecutarlos. Lea primero el bloque hooks. Una sesión claude -p o del SDK, que es la forma habitual de ejecutar un agente sin supervisión, nunca muestra ese cuadro de diálogo y considera que la carpeta es de confianza, por lo que los hooks del repositorio se ejecutan sin pedir confirmación. Revise sus archivos .claude/ antes de crear scripts que trabajen con él, o ejecute con --settings '{"disableAllHooks": true}'.

Un hook ve toda la entrada de la herramienta. Un hook de auditoría que registra tool_input escribe todos los argumentos de cada comando en un registro, incluido cualquier token que aparezca en una línea de comandos. Ese registro necesita la misma protección que el secreto, lo que forma parte del problema más amplio de mantener los secretos fuera del alcance de un agente de IA.

Un hook puede escribir en el contexto del modelo. La salida estándar en texto plano de un hook SessionStart o UserPromptSubmit correcto se añade a la conversación. Un hook que introduce texto externo, de un sistema de seguimiento de incidencias o de un archivo de registro, está entregando texto no confiable al modelo como si usted lo hubiera escrito. Un hook que reenvía una nota de otra sesión de Claude Code en el mismo VPS hace lo mismo, y la salida de un agente no merece más confianza que la del sistema de seguimiento de incidencias. Trate esa salida estándar como entrada, no como salida.

El privilegio es el control real. Ejecute el agente con un usuario dedicado sin privilegios y sólo con las reglas de sudo que necesite. Un bloqueo PreToolUse es útil, pero funciona como mecanismo de mejor esfuerzo por diseño: la referencia dice lo mismo sobre el filtro if y recomienda usar el sistema de permisos cuando necesite un bloqueo estricto. Las reglas de permisos y la cuenta con la que se ejecuta el proceso son las partes que siguen funcionando bajo presión.

Hay una propiedad que se mantiene en todos los modos de permisos. Los hooks PreToolUse se ejecutan antes de la comprobación del modo de permisos en todos los modos de permisos, por lo que un hook que devuelve deny bloquea la herramienta incluso con bypassPermissions. Los hooks pueden restringir lo que permiten las reglas de permisos. No pueden ampliarlo. La excepción es un mod. En una máquina sin configuración administrada ni archivo managed-mcp.json, en una sesión que no haya iniciado sesión mediante /login en un plan Team o Enterprise, un mod instalado que gestione tool.check puede aprobar una llamada que su hook PreToolUse haya bloqueado. Con una configuración administrada, un archivo managed-mcp.json o una credencial /login de Team o Enterprise para la sesión, una llamada bloqueada por un hook PreToolUse permanece bloqueada de forma predeterminada, independientemente del archivo de configuración del que proceda el hook. Una sesión que se ejecuta con una clave de API o un CLAUDE_CODE_OAUTH_TOKEN de larga duración, que es la forma en que se ejecuta en muchos servidores, cuenta como no autenticada aunque haya una sesión iniciada almacenada. Compruebe qué pueden cambiar los mods de Claude Code antes de instalar uno en un servidor.

¿Por qué no se ejecuta mi hook?

Siga estos pasos en orden. Cada paso indica el síntoma que verá.

  • Ejecute /hooks y compruebe que el hook aparezca en el evento esperado. Si el hook no aparece en el menú, normalmente significa que el archivo de configuración contiene un error de sintaxis JSON, porque no se permiten comas finales ni comentarios, o que el archivo no está en una de las seis ubicaciones anteriores.
  • Compare el matcher con el nombre de la herramienta exactamente. Los matchers distinguen entre mayúsculas y minúsculas, por lo que "bash" nunca coincide con la herramienta Bash.
  • Ejecute el script manualmente con una entrada de ejemplo, como en el ejemplo 1 anterior. Un código de salida inesperado indica un error en el script. Compruebe también su salida estándar, porque un JSON válido todavía puede proporcionar una decisión en eventos como PreToolUse.
  • Un aviso que muestra jq: command not found significa que falta jq en esa máquina. Un command not found para su propio script significa que la ruta no se resolvió, por lo que debe usar ${CLAUDE_PROJECT_DIR} o una ruta absoluta. Si el script no se ejecuta en ningún caso, probablemente no tiene permiso de ejecución.
  • El hook imprime un JSON válido y no ocurre nada. En macOS y Linux, un hook con formato de shell se ejecuta mediante sh -c en un shell no interactivo, pero algunas configuraciones siguen cargando el perfil, por ejemplo BASH_ENV que apunta a ~/.bashrc. Si ese perfil imprime un banner, el banner se antepone al JSON. La salida estándar ya no comienza por {, por lo que Claude Code interpreta todo como texto sin formato e ignora la decisión. Como el hook terminó con código 0, la transcripción no muestra ningún error. En la mayoría de los eventos, ese texto sólo se escribe en el registro de depuración. En UserPromptSubmit, UserPromptExpansion, SessionStart y PostModelSwitch, se añade al contexto del modelo, incluido el banner. Incluya cualquier echo del perfil en una condición para que sólo se ejecute en shells interactivos.
  • Si el problema continúa, inicie la sesión con claude --debug-file /tmp/claude.log y ejecute tail -f /tmp/claude.log en otra terminal. El registro de depuración indica qué hooks coincidieron, qué código de salida devolvió cada uno y todo lo que escribieron en stdout y stderr.

FAQ

¿Cuál es la diferencia entre un hook de Claude Code y una instrucción de CLAUDE.md?

Una instrucción CLAUDE.md es texto incluido en el contexto del modelo, por lo que compite por su atención con la conversación y con la petición actual. El modelo puede sopesarla frente a esos elementos. Un hook es un comando de shell que Claude Code ejecuta en un punto fijo de su ciclo de vida. Por tanto, se ejecuta cada vez que ocurre su evento, independientemente de lo que haya decidido el modelo. Use una instrucción para expresar una preferencia. Use un hook para un paso que siempre deba ejecutarse o una acción que nunca deba realizarse.

¿Cómo impido que Claude Code ejecute un comando de shell específico?

Registre un hook PreToolUse con un comparador Bash que lea el comando desde .tool_input.command, escriba el motivo en stderr y salga con el código 2. Claude Code cancela la llamada y muestra el motivo al modelo. Esto ocurre antes de comprobar el modo de permisos, por lo que la denegación se mantiene incluso en el modo bypassPermissions. La coincidencia sobre una cadena de comando es una medida de protección, no un límite de seguridad, porque el mismo comando puede escribirse de una forma que el patrón no detecte. Refuércela con reglas de permisos y con una cuenta sin privilegios.

Mi hook muestra JSON válido, pero no ocurre nada. ¿Por qué?

Revise si el perfil de shell imprime texto antes del JSON. En macOS y Linux, un hook sin un campo args se ejecuta mediante sh -c. En configuraciones que siguen cargando el perfil, como BASH_ENV que apunta a ~/.bashrc, un perfil que muestra un banner lo escribe en stdout antes del JSON. Como la salida ya no comienza por {, Claude Code la trata completa como texto sin formato e ignora la decisión. Como el hook terminó con código 0, la transcripción no muestra ningún error. Proteja cualquier echo del perfil con una comprobación de shell interactivo. Después, confirme la corrección leyendo el registro de depuración de claude --debug-file /tmp/claude.log.

¿Es seguro ejecutar hooks de Claude Code en un servidor compartido?

Los hooks se ejecutan con el usuario que inició Claude Code y con los permisos de archivos de ese usuario. Por tanto, un hook puede hacer todo lo que esa cuenta pueda hacer. Dos prácticas cubren la mayor parte del riesgo: ejecute el agente con una cuenta dedicada sin privilegios y con una política sudo restrictiva; además, lea el bloque hooks de cualquier repositorio antes de aceptar su cuadro de diálogo de confianza del espacio de trabajo o ejecutar claude -p en él. Los hooks del proyecto se incluyen en .claude/settings.json y el modo -p nunca muestra ese cuadro de diálogo. Establezca "disableAllHooks": true en el archivo de configuración para deshabilitar los hooks, excepto los hooks administrados que requieren este ajuste en el nivel administrado. Un ajuste de proyecto false puede anular un ajuste de usuario true.

¿Te resultó útil este artículo?