476| `async` | no | Si es `true`, se ejecuta en segundo plano sin bloquear. Consulta [Ejecutar hooks en segundo plano](#run-hooks-in-the-background) |476| `async` | no | Si es `true`, se ejecuta en segundo plano sin bloquear. Consulta [Ejecutar hooks en segundo plano](#run-hooks-in-the-background) |
477| `asyncRewake` | no | Si es `true`, se ejecuta en segundo plano y despierta a Claude en código de salida 2. El stderr del hook, o stdout si stderr está vacío, se muestra a Claude como un [recordatorio del sistema](/docs/es/glossary#system-reminder) para que pueda reaccionar a un fallo de fondo de larga duración |477| `asyncRewake` | no | Si es `true`, se ejecuta en segundo plano y despierta a Claude en código de salida 2. El stderr del hook, o stdout si stderr está vacío, se muestra a Claude como un [recordatorio del sistema](/docs/es/glossary#system-reminder) para que pueda reaccionar a un fallo de fondo de larga duración |
478| `shell` | no | Shell a usar para este hook. Acepta `"bash"` o `"powershell"`. Por defecto es `"bash"`, o `"powershell"` en Windows cuando Git Bash no está instalado. Establecer `"powershell"` ejecuta el comando a través de PowerShell en Windows. No requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL` ya que los hooks generan PowerShell directamente. Se ignora cuando `args` está establecido |478| `shell` | no | Shell a usar para este hook. Acepta `"bash"` o `"powershell"`. Por defecto es `"bash"`, o `"powershell"` en Windows cuando Git Bash no está instalado. Establecer `"powershell"` ejecuta el comando a través de PowerShell en Windows. No requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL` ya que los hooks generan PowerShell directamente. Se ignora cuando `args` está establecido |
479| `onFailure` | no | Qué le sucede a la acción cuando el hook falla: `"continue"`, el valor por defecto, o `"block"`. Consulta [Bloquear la acción cuando un hook falla](#block-the-action-when-a-hook-fails). Requiere Claude Code v2.1.295 o posterior |
479 480
480<a id="exec-form-and-shell-form" />481<a id="exec-form-and-shell-form" />
481 482
533| `url` | sí | URL a la que enviar la solicitud POST |534| `url` | sí | URL a la que enviar la solicitud POST |
534| `headers` | no | Encabezados HTTP adicionales como pares clave-valor. Los valores soportan interpolación de variables de entorno usando sintaxis `$VAR_NAME` o `${VAR_NAME}`. Solo se resuelven las variables listadas en `allowedEnvVars` |535| `headers` | no | Encabezados HTTP adicionales como pares clave-valor. Los valores soportan interpolación de variables de entorno usando sintaxis `$VAR_NAME` o `${VAR_NAME}`. Solo se resuelven las variables listadas en `allowedEnvVars` |
535| `allowedEnvVars` | no | Lista de nombres de variables de entorno que pueden interpolarse en valores de encabezado. Las referencias a variables no listadas se reemplazan con cadenas vacías. Requerido para que funcione cualquier interpolación de variable de entorno |536| `allowedEnvVars` | no | Lista de nombres de variables de entorno que pueden interpolarse en valores de encabezado. Las referencias a variables no listadas se reemplazan con cadenas vacías. Requerido para que funcione cualquier interpolación de variable de entorno |
537| `onFailure` | no | Qué le sucede a la acción cuando el hook falla: `"continue"`, el valor por defecto, o `"block"`. Consulta [Bloquear la acción cuando un hook falla](#block-the-action-when-a-hook-fails). Requiere Claude Code v2.1.295 o posterior |
536 538
537Claude Code envía la [entrada JSON](#hook-input-and-output) del hook como el cuerpo de la solicitud POST con `Content-Type: application/json`. El cuerpo de respuesta utiliza el mismo [formato de salida JSON](#json-output) que los hooks de comando.539Claude Code envía la [entrada JSON](#hook-input-and-output) del hook como el cuerpo de la solicitud POST con `Content-Type: application/json`. El cuerpo de respuesta utiliza el mismo [formato de salida JSON](#json-output) que los hooks de comando.
538 540
821 Salida por código de salida823 Salida por código de salida
822</h3>824</h3>
823 825
824El código de salida de tu comando de hook le dice a Claude Code si la acción debe continuar, ser bloqueada o ser ignorada. El código de salida no actúa solo. Claude Code lee los [campos de salida JSON](#json-output) desde stdout con cualquier código de salida, no solo con 0, y para los eventos que usan el modelo de decisión estándar, un objeto analizado que pasa la validación del esquema tiene efecto junto con el código. El bloqueo de exit 2 es el único resultado que JSON no puede sobrescribir.826El código de salida de tu hook le dice a Claude Code si debe continuar con la acción que activó el hook, como una llamada a herramienta o un prompt. Una ejecución que termina tiene uno de tres resultados:
825 827
826Dos tablas recogen las excepciones por evento: [Comportamiento del código de salida 2 por evento](#exit-code-2-behavior-per-event) indica qué hacen los códigos de salida para cada evento, y [Control de decisión](#decision-control) indica qué campos de decisión respeta cada evento. Los campos universales como `systemMessage` funcionan en la mayoría de los eventos y se enumeran en la tabla de [salida JSON](#json-output).828* **Éxito**: tu hook sale con 0. Claude Code aplica cualquier campo de [salida JSON](#json-output) que tu hook haya impreso, y la acción continúa a menos que esos campos la bloqueen o la denieguen.
829* **Error de bloqueo**: tu hook sale con 2. En los [eventos que pueden bloquear](#exit-code-2-behavior-per-event), Claude Code detiene la acción.
830* **Error sin bloqueo**: tu hook sale con cualquier otro código, o falla de alguna otra manera, como no iniciarse o imprimir JSON no válido. La acción continúa, y en eventos como `PreToolUse` ves un aviso `<hook name> hook error` en la transcripción. Si quieres que un hook fallido bloquee la acción, establece [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
831
832Lo que tu hook imprime en stdout puede cambiar el resultado. Por ejemplo, si un hook `PreToolUse` sale con 1 pero imprime JSON que pasa la validación, la ejecución es un éxito y los campos JSON deciden qué sucede. Para saber el resultado de tu hook en un evento como `PreToolUse`, busca lo que imprimió en stdout en la primera columna y su código de salida en la parte superior:
833
834| Stdout | Exit 0 | Exit 2 | Cualquier otro código de salida |
835| :- | :- | :- | :- |
836| Objeto JSON que pasa la [validación del esquema](#json-output) | Éxito. Los campos se aplican | Error de bloqueo. Claude Code sigue leyendo los campos, pero no pueden sobrescribir el bloqueo | Éxito. Claude Code ignora el código de salida, y solo los campos deciden. Con [`onFailure: "block"`](#block-the-action-when-a-hook-fails), esto cuenta como un fallo |
837| JSON que [no se puede analizar](#exit-code-0) o que falla la validación del esquema | Error sin bloqueo. El aviso incluye el mensaje de análisis o de validación | Error de bloqueo. Tu stderr es la razón | Error sin bloqueo. El aviso incluye el mensaje de análisis o de validación |
838| [Texto plano](#exit-code-0), o nada | Éxito | Error de bloqueo. Tu stderr es la razón | Error sin bloqueo. El aviso incluye la primera línea de tu stderr |
839
840Algunos eventos tienen sus propias reglas:
841
842* **`WorktreeCreate`**: cualquier código de salida distinto de cero hace que la creación del worktree falle, diga lo que diga tu JSON.
843* **`WorktreeRemove`**: cualquier código de salida distinto de cero hace que la eliminación del worktree falle si el directorio sigue existiendo después.
844* **`Stop`, `SubagentStop`, `TaskCompleted` y el hook `UserPromptSubmit` de un plugin**: cuando tu hook sale con 2 sin nada en stdout y su stderr indica que falta un archivo, como `No such file or directory`, Claude Code trata la ejecución como un error sin bloqueo.
845* **`Elicitation` y `ElicitationResult`**: Claude Code aplica tu `hookSpecificOutput` cuando tu hook sale con 0, y lo ignora con cualquier otro código de salida.
846* **Eventos que descartan la salida del hook, como `StopFailure`**: Claude Code ignora tu JSON con cualquier código de salida, aparte de los campos de efecto secundario como `terminalSequence`, que se siguen activando.
847
848Para comprobar qué hace el código de salida 2 en tu evento, consulta [Comportamiento del código de salida 2 por evento](#exit-code-2-behavior-per-event). Para comprobar qué campos de decisión respeta, consulta [Control de decisión](#decision-control).
827 849
828<h4 id="exit-code-0">850<h4 id="exit-code-0">
829 Exit code 0851 Exit code 0
835 857
836Que Claude Code lea tu stdout como [salida JSON](#json-output) o como texto plano depende de cómo comienza y termina, ignorando los espacios en blanco circundantes:858Que Claude Code lea tu stdout como [salida JSON](#json-output) o como texto plano depende de cómo comienza y termina, ignorando los espacios en blanco circundantes:
837 859
838* **Comienza con `{` y termina con `}`**: Claude Code lo analiza como JSON. Cuando la salida son dos o más líneas que se analizan como JSON cada una por su cuenta, y ninguna línea es un objeto de [salida JSON](#json-output) que establezca 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.860* **Comienza con `{` y termina con `}`**: Claude Code lo analiza como JSON. Cuando la salida son dos o más líneas que se analizan como JSON cada una por su cuenta, y ninguna línea es un objeto de [salida JSON](#json-output) que establezca 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.
839* **Comienza con `{` pero no termina con `}`**: Claude Code lo trata como texto plano.861* **Comienza con `{` pero no termina con `}`**: Claude Code lo trata como texto plano.
840* **Comienza con cualquier otra cosa**: Claude Code lo trata como texto plano, incluso si es un array JSON o una cadena JSON entrecomillada.862* **Comienza con cualquier otra cosa**: Claude Code lo trata como texto plano, incluso si es un array JSON o una cadena JSON entrecomillada.
841 863
842Para los eventos que usan el modelo de decisión estándar, exit 0 con un objeto analizado que falla la validación del esquema es un error sin bloqueo: la acción continúa, y la transcripción muestra un aviso `<hook name> hook error` con el mensaje de validación. Lo mismo sucede con cualquier código de salida distinto de 2, mientras que [exit 2 sigue bloqueando](#exit-code-2).864Cuando Claude Code intenta analizar tu stdout como JSON y no puede, o el objeto analizado falla la [validación del esquema](#json-output), la ejecución es un [error sin bloqueo](#exit-code-output). El aviso `<hook name> hook error` incluye el mensaje de análisis o de validación. En los eventos que agregan stdout de texto plano como contexto, Claude Code no agrega el stdout que no pudo analizar.
843
844Para los eventos que usan el modelo de decisión estándar, cuando Claude Code intenta analizar tu stdout como JSON y no puede, reporta un error sin bloqueo con cualquier código de salida distinto de 2. La transcripción muestra un aviso `<hook name> hook error` con el mensaje de análisis. En los eventos que agregan stdout de texto plano como contexto, Claude Code no agrega el texto. Antes de v2.1.248, Claude Code trataba ese stdout como texto plano.
845 865
846El stderr de un hook que sale con 0 va solo al registro de depuración, nunca a la transcripción, y Claude nunca lo ve. Para leerlo tú mismo, habilita el [registro de depuración](#debug-hooks). Para mostrarle una advertencia a Claude desde un hook `PostToolUse` o `PostToolUseFailure`, sal con 2 en su lugar para que [Claude vea el stderr](#exit-code-2-behavior-per-event) aunque la herramienta ya se haya ejecutado.866Claude nunca ve el stderr de un hook que sale con 0. Para leerlo tú mismo en eventos como `PreToolUse`, habilita el [registro de depuración](#debug-hooks). Para mostrarle una advertencia a Claude desde un hook `PostToolUse` o `PostToolUseFailure`, sal con 2 en su lugar para que [Claude vea el stderr](#exit-code-2-behavior-per-event) aunque la herramienta ya se haya ejecutado.
847 867
848<h4 id="exit-code-2">868<h4 id="exit-code-2">
849 Exit code 2869 Exit code 2
850</h4>870</h4>
851 871
852Exit 2 significa un error de bloqueo. En los [eventos que pueden bloquear](#exit-code-2-behavior-per-event), exit 2 bloquea independientemente de si imprimes JSON: ni siquiera un `permissionDecision` JSON de `"allow"` puede sobrescribirlo. Claude Code sigue leyendo cualquier [salida JSON](#json-output) válida en stdout. En `Elicitation` y `ElicitationResult`, el `hookSpecificOutput` de un hook que sale con 2 se ignora.872Sal con el código 2 para bloquear la acción. En los [eventos que pueden bloquear](#exit-code-2-behavior-per-event), Claude Code detiene la acción: un hook `PreToolUse` bloquea la llamada a herramienta, por ejemplo, y un hook `UserPromptSubmit` rechaza el prompt.
853 873
854El mensaje de bloqueo es la razón de la decisión de bloqueo de tu JSON cuando la incluye, y tu texto de stderr en caso contrario. Lo que hace el bloqueo varía según el evento: `PreToolUse` bloquea la llamada a herramienta, `UserPromptSubmit` rechaza el prompt, y así sucesivamente. [Comportamiento del código de salida 2 por evento](#exit-code-2-behavior-per-event) enumera el efecto para cada evento, y la sección de cada evento indica adónde va el mensaje.874El mensaje que acompaña al bloqueo es el stderr de tu hook. Si tu hook también imprimió JSON que toma una decisión de bloqueo, Claude Code usa la razón de esa decisión en su lugar.
855 875
856Un hook que sale con 2 mientras imprime JSON que falla la validación del esquema de [salida JSON](#json-output) sigue bloqueando: Claude Code usa stderr como la razón del bloqueo y registra el fallo de validación en el registro de depuración. Antes de v2.1.214, Claude Code trataba esa combinación como un error sin bloqueo y la acción continuaba.876Exit 2 bloquea incluso cuando tu hook imprime JSON:
877
878* **JSON que pasa la validación del esquema**: Claude Code sigue leyendo los campos de [salida JSON](#json-output), pero no pueden sobrescribir el bloqueo. Ni siquiera un `permissionDecision` de `"allow"` deja pasar la acción. En `Elicitation` y `ElicitationResult`, el `hookSpecificOutput` de un hook que sale con 2 se ignora.
879* **JSON que falla la validación del esquema**: el hook sigue bloqueando. Claude Code usa tu stderr como la razón del bloqueo y registra el fallo de validación en el registro de depuración.
857 880
858Este script bloquea los comandos `rm` saliendo con 2 y deja todos los demás comandos al flujo de permisos normal:881Este script bloquea los comandos `rm` saliendo con 2 y deja todos los demás comandos al flujo de permisos normal:
859 882
871exit 0 # No decision: the normal permission flow applies894exit 0 # No decision: the normal permission flow applies
872```895```
873 896
897Con este script registrado como un hook `PreToolUse` en `Bash`, un comando que comienza con `rm` se bloquea, y Claude recibe el stderr del hook como el error de la herramienta, con el prefijo del nombre del evento, el nombre de la herramienta y el comando del hook:
898
899```text theme={null}
900PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/no-rm.sh]: Blocked: rm commands are not allowed
901```
902
874<h4 id="other-exit-codes">903<h4 id="other-exit-codes">
875 Otros códigos de salida904 Otros códigos de salida
876</h4>905</h4>
877 906
878Cualquier otro código de salida no bloquea por sí solo en la mayoría de los eventos de hook. Lo que sucede depende de tu stdout:907Cuando tu hook sale con un código distinto de 0 o 2 e imprime texto plano o nada en stdout, la ejecución es un [error sin bloqueo](#exit-code-output). Ves un aviso `<hook name> hook error` en la transcripción con `Failed with non-blocking status code:` y la primera línea del stderr de tu hook. Por ejemplo, cuando un hook `PreToolUse` en `Bash` imprime `something broke` en stderr y sale con 1, el aviso `PreToolUse:Bash hook error` incluye esta línea:
879 908
880* Con un objeto analizado que pasa la validación del esquema, para los 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:909```text theme={null}
881 * Se respeta cada campo que el evento admite, incluidos `permissionDecision`, `additionalContext`, `updatedInput` y `systemMessage`, y el hook no se reporta como error.910Failed with non-blocking status code: something broke
882 * [Control de decisión](#decision-control) enumera los campos de decisión por evento; los campos universales como `systemMessage` siguen la tabla de [salida JSON](#json-output).911```
883* Con un objeto analizado que falla la validación del esquema, para los eventos que usan el modelo de decisión estándar, es el mismo error sin bloqueo que [con exit 0](#exit-code-0): la acción continúa, y el aviso `<hook name> hook error` incluye el mensaje de validación.
884* Con stdout que Claude Code [intenta analizar como JSON](#exit-code-0) y no puede, Claude Code reporta el mismo error sin bloqueo que con exit 0 para los eventos que usan el modelo de decisión estándar. La acción continúa, y el aviso incluye el mensaje de análisis.
885* Con stdout que Claude Code [trata como texto plano](#exit-code-0), o con stdout vacío, es un error sin bloqueo para la mayoría de los eventos de hook: la acción continúa, y la transcripción muestra un aviso `<hook name> hook error` seguido de la primera línea de stderr, con el prefijo `Failed with non-blocking status code:`. Para capturar el stderr completo, habilita el [registro de depuración](#debug-hooks).
886 912
887Los eventos fuera del modelo de decisión estándar mantienen sus propias filas en la [tabla por evento](#exit-code-2-behavior-per-event): `WorktreeCreate` hace fallar la creación con cualquier salida distinta de cero, diga lo que diga tu JSON, y los eventos que descartan por completo la salida del hook, como `StopFailure`, ignoran tu JSON con cualquier código de salida, aparte de los campos de efecto secundario como `terminalSequence`, que se siguen activando.913Para capturar el stderr completo en lugar de su primera línea, habilita el [registro de depuración](#debug-hooks).
888 914
889Un hook que no puede iniciarse cae en la misma categoría sin bloqueo. Cuando la ruta del script no existe o no es ejecutable, el shell sale con un código como 127 y ves el mismo aviso con el mensaje del intérprete, por ejemplo `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Para la mayoría de los eventos de hook, la acción continúa. Cuando configures un hook de política, fíjate en este aviso en su primera ejecución: una ruta mal escrita en `settings.json` deja el control deshabilitado en silencio.915Un hook que no puede iniciarse también es un error sin bloqueo. En la forma de shell, cuando la ruta del script no existe o no es ejecutable, el shell sale con un código como 127 y el aviso incluye el mensaje del intérprete, por ejemplo `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`. Cuando configures un hook de política, fíjate en este aviso en su primera ejecución, porque una ruta mal escrita en `settings.json` significa que el hook nunca se ejecuta. Para bloquear la acción en su lugar, establece [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
890 916
891<Warning>917<Warning>
892 Para la mayoría de los eventos de hook, el código de salida 2 es el único código de salida que bloquea solo con el código. Sin JSON válido en stdout, Claude Code trata el código de salida 1 como un error sin bloqueo y continúa con la acción, aunque 1 es el código de fallo convencional de Unix. Si tu hook está pensado para aplicar una política, usa `exit 2`. Los eventos de worktree son diferentes: cualquier código de salida distinto de cero de `WorktreeCreate` aborta la creación del worktree, y cualquier código de salida distinto de cero de `WorktreeRemove` hace que la eliminación del worktree falle si el directorio sigue existiendo después.918 Sin JSON válido en stdout, Claude Code trata el código de salida 1 como un error sin bloqueo, aunque 1 es el código de fallo convencional de Unix. Si tu hook está pensado para aplicar una política, usa `exit 2`.
893</Warning>919</Warning>
894 920
895<h4 id="timeouts">921<h4 id="timeouts">
900 926
901En [`PreModelSwitch`](#premodelswitch), un hook cancelado al agotarse su tiempo de espera bloquea el cambio de modelo. En `PreToolUse`, las dos familias de hooks difieren:927En [`PreModelSwitch`](#premodelswitch), un hook cancelado al agotarse su tiempo de espera bloquea el cambio de modelo. En `PreToolUse`, las dos familias de hooks difieren:
902 928
903* Un hook `command`, `http` o `mcp_tool` cuyo tiempo de espera se agota no bloquea la llamada a herramienta. La llamada continúa a través del [flujo de permisos](/docs/es/permissions) normal, así que no cuentes con que un hook bloqueado actúe como control.929* Un hook `command`, `http` o `mcp_tool` cuyo tiempo de espera se agota no bloquea la llamada a herramienta. La llamada continúa a través del [flujo de permisos](/docs/es/permissions) normal, así que no cuentes con que un hook bloqueado actúe como control. Para bloquear la llamada cuando se agota el tiempo de espera de un hook `command` o `http`, establece [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
904* Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) que excede su tiempo de espera [bloquea la llamada a herramienta](#pretooluse).930* Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) que excede su tiempo de espera [bloquea la llamada a herramienta](#pretooluse).
905 931
932<h4 id="block-the-action-when-a-hook-fails">
933 Bloquear la acción cuando un hook falla
934</h4>
935
936En la mayoría de los eventos, cuando un hook falla o se agota su tiempo de espera, Claude Code sigue llevando a cabo la acción, por lo que un hook de política con una ruta incorrecta o un script que se bloquea deja pasar todo. Para bloquear la acción en su lugar, establece `"onFailure": "block"` en un hook `command` o `http`. El valor predeterminado es `"continue"`. Requiere Claude Code v2.1.295 o posterior.
937
938Este hook `PreToolUse` en `.claude/settings.json` ejecuta un script del proyecto antes de cada comando Bash, y bloquea el comando si el script falla:
939
940```json theme={null}
941{
942 "hooks": {
943 "PreToolUse": [
944 {
945 "matcher": "Bash",
946 "hooks": [
947 {
948 "type": "command",
949 "command": "node",
950 "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
951 "onFailure": "block"
952 }
953 ]
954 }
955 ]
956 }
957}
958```
959
960Para probarlo, deja que falte `check-command.js` y pídele a Claude que ejecute un comando Bash como `ls`. Claude Code bloquea la llamada, y el error incluye `failed; blocking because onFailure is "block"` seguido de la salida de error propia de node, recortada aquí a una línea:
961
962```text theme={null}
963PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block"
964Error: Cannot find module '/path/to/project/.claude/hooks/check-command.js'
965```
966
967Después de que se agota el tiempo de espera, el mensaje dice `timed out` en lugar de `failed`. Sin `onFailure` establecido, el mismo script faltante es un error sin bloqueo y `ls` se ejecuta.
968
969Cada uno de estos cuenta como un fallo:
970
971* **No puede iniciarse**: un hook de comando no logra iniciarse, por ejemplo porque el script o el ejecutable no existe
972* **Código de salida distinto de 0 o 2**: cuenta para un hook de comando incluso si imprimió JSON que permite la acción, como `permissionDecision: "allow"`. Para devolver una decisión JSON, sal con 0
973* **Error HTTP**: la conexión de un hook HTTP falla, o el estado de la respuesta no es 2xx
974* **Tiempo de espera agotado**: el hook alcanza su [`timeout`](#common-fields)
975* **Salida no válida**: la salida JSON [no se puede analizar](#exit-code-0) o falla la [validación del esquema](#json-output). Para un hook HTTP, un cuerpo 2xx que no está vacío ni es un objeto JSON también cuenta. El stdout de texto plano de un hook de comando no es un fallo
976
977Con `"block"` establecido, un fallo hace lo que [el código de salida 2 hace en ese evento](#exit-code-2-behavior-per-event), excepto en `PermissionRequest`, donde deniega la solicitud. Por ejemplo, un fallo de `PreToolUse` bloquea la llamada a herramienta y un fallo de `UserPromptSubmit` bloquea el prompt.
978
979El campo no tiene efecto en estos hooks:
980
981* **Hooks `Stop`, `SubagentStop`, `TaskCompleted` y `TeammateIdle`**: el código de salida 2 en estos eventos hace que Claude siga trabajando, y Claude no puede reparar un hook que no se ejecuta
982* **Hooks de comando en segundo plano**: hooks de comando que establecen [`async` o `asyncRewake`](#run-hooks-in-the-background)
983
906<h4 id="exit-code-2-behavior-per-event">984<h4 id="exit-code-2-behavior-per-event">
907 Comportamiento del código de salida 2 por evento985 Comportamiento del código de salida 2 por evento
908</h4>986</h4>
960* **Fallo de conexión**: error sin bloqueo, la ejecución continúa1038* **Fallo de conexión**: error sin bloqueo, la ejecución continúa
961* **Tiempo de espera agotado**: el hook se cancela, como se describe en [Tiempos de espera](#timeouts)1039* **Tiempo de espera agotado**: el hook se cancela, como se describe en [Tiempos de espera](#timeouts)
962 1040
963A diferencia de los hooks de comando, los hooks HTTP no pueden señalar un error de bloqueo solo mediante códigos de estado. Para bloquear una llamada a herramienta o denegar un permiso, devuelve una respuesta 2xx con un cuerpo JSON que contenga los campos de decisión apropiados.1041Los hooks HTTP no pueden señalar un error de bloqueo solo mediante el código de estado: un estado que no es 2xx o una conexión fallida es un [error sin bloqueo](#exit-code-output). Para bloquear una llamada a herramienta o denegar un permiso, devuelve una respuesta 2xx con un cuerpo JSON que contenga los campos de decisión apropiados. Para bloquear la acción cuando la solicitud falla o devuelve un estado que no es 2xx, establece [`onFailure: "block"`](#block-the-action-when-a-hook-fails).
964 1042
965<h3 id="json-output">1043<h3 id="json-output">
966 Salida JSON1044 Salida JSON
1237 Control de decisiones de SessionStart1315 Control de decisiones de SessionStart
1238</h4>1316</h4>
1239 1317
1240Claude Code agrega al contexto de Claude la stdout que [trata como texto plano](#exit-code-0). Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puedes devolver estos campos específicos del evento:1318Un hook SessionStart puede agregar contexto para Claude, proporcionar el primer mensaje del usuario, establecer el título de la sesión, vigilar archivos y recargar skills. Devuelve el campo correspondiente a cada uno, además de los [campos de salida JSON](#json-output) disponibles para todos los hooks:
1241 1319
1242| Campo | Descripción |1320| Campo | Descripción |
1243| :- | :- |1321| :- | :- |
1244| `additionalContext` | Cadena agregada al contexto de Claude al inicio de la conversación, antes del primer prompt. Consulta [Agregar contexto para Claude](#add-context-for-claude) para saber cómo se entrega el texto y qué incluir en él |1322| `additionalContext` | Cadena agregada al contexto de Claude al inicio de la conversación, antes del primer prompt. Consulta [Agregar contexto para Claude](#add-context-for-claude) para saber cómo se entrega el texto y qué incluir en él |
1245| `initialUserMessage` | Cadena usada como el primer mensaje del usuario de la sesión. Se aplica en el [modo no interactivo](/docs/es/headless) con el flag `-p`, donde se convierte en el primer turno aunque no se proporcione ningún prompt. Si se proporciona un prompt, este sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, este crea el turno |1323| `initialUserMessage` | Cadena que se usa como primer mensaje del usuario de la sesión, en [modo no interactivo](/docs/es/headless) con el flag `-p`. Se convierte en el primer turno aunque no pases ningún prompt. Un prompt que sí pases va a continuación como el siguiente turno |
1246| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Úsalo para nombrar sesiones automáticamente a partir de la carpeta de inicio, la rama de git o el nombre del worktree. Se aplica cuando `source` es `"startup"`, `"resume"` o `"fork"`; se ignora en `"clear"` y `"compact"` |1324| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Se aplica cuando `source` es `"startup"`, `"resume"` o `"fork"` |
1247| `watchPaths` | Array de rutas absolutas que se vigilarán para eventos [FileChanged](#filechanged) durante esta sesión |1325| `watchPaths` | Array de rutas absolutas que se vigilarán para eventos [FileChanged](#filechanged) durante esta sesión |
1248| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a escanear los directorios de [skills](/docs/es/skills) y de comandos después de que terminan los hooks SessionStart, de modo que los skills que instaló el hook estén disponibles en la misma sesión, a partir del primer prompt |1326| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a examinar los directorios de [skills](/docs/es/skills) y comandos después de que terminan los hooks SessionStart. Consulta [Recargar los skills que instala un hook](#reload-skills-that-a-hook-installs) |
1327
1328Esta salida agrega contexto y le pone nombre a la sesión:
1249 1329
1250```json theme={null}1330```json theme={null}
1251{1331{
1257}1337}
1258```1338```
1259 1339
1260Como la stdout en texto plano ya llega a Claude en este evento, un hook que solo carga contexto puede imprimir directamente en stdout sin construir JSON. Usa el formato JSON cuando necesites combinar contexto con otros campos como `sessionTitle`.1340Un hook que solo agrega contexto puede imprimirlo sin construir JSON, porque Claude Code agrega al contexto de Claude la [stdout en texto plano](#exit-code-0) de un hook SessionStart.
1341
1342Si el hook SessionStart de tu plugin proporciona `initialUserMessage` o `sessionTitle`, instala el plugin antes de que se inicie la sesión. Claude Code ignora ambos campos de un plugin que termina de instalarse después de que se hayan ejecutado los hooks SessionStart.
1343
1344<h4 id="reload-skills-that-a-hook-installs">
1345 Recargar los skills que instala un hook
1346</h4>
1347
1348Para que los skills que instala un hook SessionStart estén disponibles en la misma sesión, devuelve `reloadSkills`. La detección de skills normalmente se ejecuta antes de que terminen los hooks SessionStart, así que, sin él, los archivos que un hook escribe en `~/.claude/skills/` o `.claude/skills/` pueden faltar cuando se ejecuta el primer prompt.
1261 1349
1262Usa `reloadSkills` cuando un hook SessionStart instala o actualiza skills. El descubrimiento de skills normalmente se ejecuta antes de que terminen los hooks SessionStart, así que los archivos que el hook escribe en `~/.claude/skills/` o `.claude/skills/` de otro modo solo aparecerían en la siguiente sesión. Este ejemplo sincroniza un repositorio compartido de skills y solicita el nuevo escaneo:1350Este ejemplo sincroniza un repositorio compartido de skills y solicita el nuevo examen:
1263 1351
1264```bash theme={null}1352```bash theme={null}
1265#!/bin/bash1353#!/bin/bash
1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1358echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1271```1359```
1272 1360
1273La URL del repositorio es un marcador de posición; reemplázala por tu propio repositorio de skills. Con el marcador de posición, la clonación falla e imprime un mensaje `fatal:` en stderr. La stderr de un hook SessionStart que termina con 0 es solo informativa, así que la solicitud `reloadSkills` se aplica de todos modos.1361La URL del repositorio es un marcador de posición. Reemplázala por tu propio repositorio de skills.
1274 1362
1275<h4 id="persist-environment-variables">1363<h4 id="persist-environment-variables">
1276 Persistir variables de entorno1364 Persistir variables de entorno
1419 1507
1420Los hooks `UserPromptSubmit` tienen un tiempo de espera predeterminado de 30 segundos para los tipos `command`, `http` y `mcp_tool`, más corto que el valor predeterminado de 600 segundos para esos tipos en la mayoría de los demás eventos. Como este hook se ejecuta antes de cada prompt y bloquea el procesamiento del modelo hasta que termina, un hook atascado detiene la sesión. Si tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.1508Los hooks `UserPromptSubmit` tienen un tiempo de espera predeterminado de 30 segundos para los tipos `command`, `http` y `mcp_tool`, más corto que el valor predeterminado de 600 segundos para esos tipos en la mayoría de los demás eventos. Como este hook se ejecuta antes de cada prompt y bloquea el procesamiento del modelo hasta que termina, un hook atascado detiene la sesión. Si tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.
1421 1509
1422Salvo un hook de comando que ejecutes con [`async: true`](#run-hooks-in-the-background), cuando a un hook de comando, HTTP o de herramienta MCP de `UserPromptSubmit` se le agota el tiempo de espera, se cancela y su salida, incluido cualquier `additionalContext`, se descarta. El prompt llega igualmente a Claude sin ese contexto. La transcripción muestra un aviso con el nombre del hook, el tiempo de espera que se agotó y que la salida se descartó.1510Salvo un hook de comando que ejecutes con [`async: true`](#run-hooks-in-the-background), cuando se agota el tiempo de espera de un hook de comando, HTTP o de herramienta MCP de `UserPromptSubmit`, se cancela y se descarta su salida, incluido cualquier `additionalContext`. El prompt sigue llegando a Claude sin ese contexto. Para bloquear el prompt en su lugar, establece [`onFailure: "block"`](#block-the-action-when-a-hook-fails) en un hook de comando o HTTP. La transcripción muestra un aviso que indica el hook, el tiempo de espera que se agotó y que se descartó la salida.
1423 1511
1424Cuando a un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `UserPromptSubmit` se le agota el tiempo de espera, bloquea el prompt con un mensaje que nombra el hook y el tiempo de espera, porque un callback ahí puede estar actuando como una barrera de políticas que no debe fallar de forma abierta. La sesión continúa. Antes de la v2.1.208, agotar el tiempo de espera de un callback en ese evento terminaba el turno con un error de ejecución.1512Cuando a un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `UserPromptSubmit` se le agota el tiempo de espera, bloquea el prompt con un mensaje que nombra el hook y el tiempo de espera, porque un callback ahí puede estar actuando como una barrera de políticas que no debe fallar de forma abierta. La sesión continúa. Antes de la v2.1.208, agotar el tiempo de espera de un callback en ese evento terminaba el turno con un error de ejecución.
1425 1513
1860| :- | :- | :- | :- |1948| :- | :- | :- | :- |
1861| `url` | string | `"https://example.com/api"` | URL de la que se obtendrá el contenido |1949| `url` | string | `"https://example.com/api"` | URL de la que se obtendrá el contenido |
1862| `prompt` | string | `"Extract the API endpoints"` | Prompt que se ejecutará sobre el contenido obtenido |1950| `prompt` | string | `"Extract the API endpoints"` | Prompt que se ejecutará sobre el contenido obtenido |
1951| `offset` | number | `100000` | Número opcional de caracteres que se omitirán desde el inicio de la página. Claude lo establece para seguir leyendo una página larga. Requiere Claude Code v2.1.290 o posterior |
1863 1952
1864<h5 id="websearch">1953<h5 id="websearch">
1865 WebSearch1954 WebSearch
2112| `message` | Solo para `"deny"`: le indica a Claude por qué se denegó el permiso |2201| `message` | Solo para `"deny"`: le indica a Claude por qué se denegó el permiso |
2113| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |2202| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |
2114 2203
2115Un hook que termina con 2 sin un objeto `decision` deja el flujo de permisos sin cambios, y su stderr se descarta. Solo el objeto `decision` puede conceder o denegar la solicitud.2204Un hook que sale con 2 sin un objeto `decision` deja el flujo de permisos sin cambios, y su stderr se descarta. Para conceder o denegar la solicitud, devuelve el objeto `decision`.
2116 2205
2117```json theme={null}2206```json theme={null}
2118{2207{
2678 Control de decisiones de TaskCreated2767 Control de decisiones de TaskCreated
2679</h4>2768</h4>
2680 2769
2681Un hook TaskCreated puede bloquear la creación de dos maneras. En ambos casos, Claude Code elimina la tarea y devuelve tu mensaje a Claude como el error de la herramienta. Claude Code ignora `continue: false` de este evento y Claude sigue trabajando.2770Un hook TaskCreated puede bloquear la creación con el código de salida 2 o con una decisión JSON. En cualquier caso, Claude Code elimina la tarea y devuelve tu mensaje a Claude como error de la herramienta. Claude Code ignora `continue: false` en este evento y Claude sigue trabajando.
2682 2771
2683* **Código de salida 2**: Claude Code devuelve el texto de stderr como mensaje.2772* **Código de salida 2**: Claude Code devuelve el texto de stderr como mensaje.
2684* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como mensaje.2773* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como mensaje.
3561 3650
3562Claude Code muestra al usuario cualquier `systemMessage` que devuelva tu hook, independientemente de la decisión, por lo que un hook que informa costos puede devolver `{"systemMessage": "..."}` y terminar con 0.3651Claude Code muestra al usuario cualquier `systemMessage` que devuelva tu hook, independientemente de la decisión, por lo que un hook que informa costos puede devolver `{"systemMessage": "..."}` y terminar con 0.
3563 3652
3564Un hook PreModelSwitch que no responde antes de su tiempo de espera bloquea el cambio. En [PreToolUse](#timeouts), en cambio, un hook de comando cuyo tiempo de espera se agota deja que la llamada a herramienta continúe. El tiempo de espera predeterminado para este evento es de 30 segundos. `PreModelSwitch` solo ejecuta hooks `command`, `http` y `mcp_tool`, por lo que los valores predeterminados de `prompt` y `agent` no se aplican.3653Un hook PreModelSwitch que no responde antes de que se agote su tiempo de espera bloquea el cambio. Para saber qué hace un tiempo de espera agotado en otros eventos, consulta [Tiempos de espera](#timeouts). El tiempo de espera predeterminado para este evento es de 30 segundos. `PreModelSwitch` solo ejecuta hooks `command`, `http` y `mcp_tool`, por lo que los valores predeterminados de `prompt` y `agent` no se aplican.
3565 3654
3566Un hook que termina con un código distinto de 0 o 2 y no imprime ninguna decisión JSON no bloquea: Claude Code muestra su stderr y aplica el cambio, como se describe en [Otros códigos de salida](#other-exit-codes).3655Un hook que termina con un código distinto de 0 o 2 y no imprime ninguna decisión JSON es un error no bloqueante, como se describe en [Otros códigos de salida](#other-exit-codes).
3567 3656
3568<h3 id="postmodelswitch">3657<h3 id="postmodelswitch">
3569 PostModelSwitch3658 PostModelSwitch
4279Los hooks asincronos tienen restricciones adicionales en comparación con los hooks sincronos:4368Los hooks asincronos tienen restricciones adicionales en comparación con los hooks sincronos:
4280 4369
4281* La salida del hook se entrega en el siguiente turno de conversación. Si la sesión está inactiva, la respuesta espera hasta la siguiente interacción del usuario. Excepción: un hook `asyncRewake` que sale con código 2 despierta a Claude inmediatamente incluso cuando la sesión está inactiva.4370* La salida del hook se entrega en el siguiente turno de conversación. Si la sesión está inactiva, la respuesta espera hasta la siguiente interacción del usuario. Excepción: un hook `asyncRewake` que sale con código 2 despierta a Claude inmediatamente incluso cuando la sesión está inactiva.
4282* Cada ejecución crea un proceso de fondo separado. No hay deduplicación en múltiples activaciones del mismo hook asincrónico.4371* Cada ejecución crea un proceso en segundo plano separado.
4283 4372
4284<h2 id="security-considerations">4373<h2 id="security-considerations">
4285 Consideraciones de seguridad4374 Consideraciones de seguridad
