70 70
71> [tab] macOS/Linux71> [tab] macOS/Linux
72>72>
73> El `matcher` se reduce a llamadas a herramientas Bash y la condición `if` se reduce aún más a subcomandos Bash que coinciden con `rm *`, por lo que `block-rm.sh` solo se genera cuando ambos filtros coinciden:73> El `matcher` se reduce a llamadas a la herramienta Bash y a [comandos de Monitor](#match-monitor-commands), y la condición `if` se reduce aún más a subcomandos Bash que coinciden con `rm *`, por lo que `block-rm.sh` solo se genera cuando ambos filtros coinciden:
74>74>
75> ```json theme={null}75> ```json theme={null}
76> {76> {
112> fi112> fi
113> ```113> ```
114>114>
115> Este script, como los otros ejemplos de Bash en esta página que analizan entrada JSON, utiliza `jq`, así que instale `jq` y asegúrese de que esté en su `PATH` antes de intentarlos.115> Este script, como los otros ejemplos de Bash en esta página que analizan entrada JSON, utiliza `jq`, así que instala `jq` y asegúrate de que esté en tu `PATH` antes de probarlos.
116 116
117> [tab] Windows (PowerShell)117> [tab] Windows (PowerShell)
118>118>
119> El matcher `Bash|PowerShell` cubre la [herramienta PowerShell](#powershell) así como Bash. Una única regla `if` coincide solo con las llamadas de una herramienta, por lo que cada herramienta obtiene su propio controlador: el primero se reduce a subcomandos Bash que coinciden con `rm *`, el segundo a comandos PowerShell que coinciden con `Remove-Item *`. Ambos ejecutan el mismo script a través de `powershell.exe`:119> El matcher `Bash|PowerShell` cubre la [herramienta PowerShell](#powershell) así como Bash. Una única regla `if` nombra una sola herramienta, por lo que cada herramienta obtiene su propio controlador: el primero se reduce a subcomandos Bash que coinciden con `rm *`, el segundo a comandos PowerShell que coinciden con `Remove-Item *`. Ambos ejecutan el mismo script a través de `powershell.exe`:
120>120>
121> ```json theme={null}121> ```json theme={null}
122> {122> {
225Los hooks se definen en archivos de configuración JSON. La configuración tiene tres niveles de anidamiento:225Los hooks se definen en archivos de configuración JSON. La configuración tiene tres niveles de anidamiento:
226 226
2271. Elige un [evento de hook](#hook-events) al que responder, como `PreToolUse` o `Stop`2271. Elige un [evento de hook](#hook-events) al que responder, como `PreToolUse` o `Stop`
2282. Añade un [grupo de matcher](#matcher-patterns) para filtrar cuándo se activa, como "solo para la herramienta Bash"2282. Agrega un [grupo de matcher](#matcher-patterns) para filtrar cuándo se activa, por ejemplo, "para la herramienta Bash"
2293. Define uno o más [manejadores de hook](#hook-handler-fields) para ejecutar cuando coincida2293. Define uno o más [manejadores de hook](#hook-handler-fields) para ejecutar cuando coincida
230 230
231Consulta [Cómo se resuelve un hook](#how-a-hook-resolves) arriba para un recorrido completo con un ejemplo anotado.231Consulta [Cómo se resuelve un hook](#how-a-hook-resolves) arriba para un recorrido completo con un ejemplo anotado.
277| Valor de matcher | Evaluado como | Ejemplo |277| Valor de matcher | Evaluado como | Ejemplo |
278| :- | :- | :- |278| :- | :- | :- |
279| `"*"`, `""` u omitido | Coincidir con todo | se activa en cada ocurrencia del evento |279| `"*"`, `""` u omitido | Coincidir con todo | se activa en cada ocurrencia del evento |
280| Solo letras, dígitos, `_`, `-`, espacios, `,` y `\|` | Cadena exacta, o lista de cadenas exactas separadas por `\|` o `,` con espacios en blanco opcionales alrededor | `Bash` coincide solo con la herramienta Bash; `Edit\|Write` y `Edit, Write` cada una coincide con cualquiera de las herramientas exactamente; `code-reviewer` coincide solo con ese tipo de agente |280| Solo letras, dígitos, `_`, `-`, espacios, `,` y `\|` | Cadena exacta, o lista de cadenas exactas separadas por `\|` o `,` con espacios en blanco opcionales alrededor | `Bash` coincide con la herramienta Bash y, en `PreToolUse` y `PermissionRequest`, también con [comandos de Monitor](#match-monitor-commands); `Edit\|Write` y `Edit, Write` cada una coincide con cualquiera de las herramientas exactamente; `code-reviewer` coincide solo con ese tipo de agente |
281| Contiene cualquier otro carácter | Expresión regular de JavaScript, sin anclar | `^Notebook` coincide con cualquier herramienta cuyo nombre comience con `Notebook`; `mcp__memory__.*` coincide con cada herramienta del servidor `memory` |281| Contiene cualquier otro carácter | Expresión regular de JavaScript, sin anclar | `^Notebook` coincide con cualquier herramienta cuyo nombre comience con `Notebook`; `mcp__memory__.*` coincide con cada herramienta del servidor `memory` |
282 282
283Un matcher en la ruta de expresión regular se prueba con `RegExp.prototype.test` de JavaScript, que tiene éxito en una coincidencia en cualquier lugar del valor. `Edit.*` coincide tanto con `Edit` como con `NotebookEdit`; envuelve el patrón en `^` y `$`, como en `^Edit$`, cuando necesites una coincidencia de cadena completa.283Un matcher en la ruta de expresión regular se prueba con `RegExp.prototype.test` de JavaScript, que tiene éxito en una coincidencia en cualquier lugar del valor. `Edit.*` coincide tanto con `Edit` como con `NotebookEdit`; envuelve el patrón en `^` y `$`, como en `^Edit$`, cuando necesites una coincidencia de cadena completa.
294| `SessionStart` | cómo comenzó la sesión | `startup`, `resume`, `clear`, `compact`, `fork` |294| `SessionStart` | cómo comenzó la sesión | `startup`, `resume`, `clear`, `compact`, `fork` |
295| `Setup` | qué bandera CLI activó la configuración | `init`, `maintenance` |295| `Setup` | qué bandera CLI activó la configuración | `init`, `maintenance` |
296| `SessionEnd` | por qué terminó la sesión | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |296| `SessionEnd` | por qué terminó la sesión | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` |
297| `Notification` | tipo de notificación | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |297| `Notification` | tipo de notificación | `permission_prompt`, `idle_prompt`, `auth_success`, `auth_storage_failure`, `elicitation_dialog`, `elicitation_url_dialog`, `elicitation_complete`, `elicitation_response`, `agent_needs_input`, `agent_completed`, `quota_auto_resume_fired`, `quota_auto_resume_stale`, `quota_auto_resume_disabled`, `plugin_notification` |
298| `SubagentStart` | tipo de agente | `general-purpose`, `Explore`, `Plan`, nombres de agentes personalizados, o nombres con alcance de plugin como `^my-plugin:reviewer$` |298| `SubagentStart` | tipo de agente | `general-purpose`, `Explore`, `Plan`, nombres de agentes personalizados, o nombres con alcance de plugin como `^my-plugin:reviewer$` |
299| `PreCompact`, `PostCompact` | qué activó la compactación | `manual`, `auto` |299| `PreCompact`, `PostCompact` | qué activó la compactación | `manual`, `auto` |
300| `PreModelSwitch`, `PostModelSwitch` | nombre canónico del modelo al que cambia la sesión, como se describe en [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |300| `PreModelSwitch`, `PostModelSwitch` | nombre canónico del modelo al que cambia la sesión, como se describe en [PreModelSwitch](#premodelswitch) | `claude-opus-5`, `claude-opus-4-6\|claude-opus-5`, `.*opus.*` |
385}385}
386```386```
387 387
388#### Coincidir comandos de Monitor
389
390Un hook [`PreToolUse`](#pretooluse) o [`PermissionRequest`](#permissionrequest) con un matcher `Bash` también se ejecuta en los comandos de shell que Claude inicia con la [herramienta Monitor](https://code.claude.com/docs/es/tools-reference.md#monitor-tool), pero su `allow` y su [`updatedInput`](#pretooluse-decision-control) no tienen efecto sobre ellos. Requiere Claude Code v2.1.314 o posterior. Los matchers como `Bash|PowerShell`, `^Bash$` y `Bash.*` también son matchers `Bash`. Un hook con un matcher `Bash` no se ejecuta para una [vigilancia de WebSocket](https://code.claude.com/docs/es/tools-reference.md#websocket-source), y un hook `PostToolUse` con uno no se ejecuta para Monitor.
391
392Un hook que se ejecuta para un comando de Monitor puede denegarlo o hacer que Claude Code te pregunte al respecto. Para permitir o reescribir el comando, cambia de un matcher `Bash` a uno que incluya Monitor:
393
394* **Matcher que incluye Monitor**: con un matcher como `Bash|Monitor` o `.*`, o sin matcher, el hook recibe la propia entrada de la llamada a Monitor, y `allow` y `updatedInput` se aplican. En [`if`](#common-fields), nombra Monitor, como en `Monitor(tail *)`, que coincide según [las reglas que sigue `Bash(tail *)`](#bash-if-matching). Si su `if` nombra Bash, el hook sigue recibiendo la entrada de la llamada a Monitor, pero `allow` y `updatedInput` no tienen efecto
395* **Matcher `Bash`**: el hook recibe una llamada a Bash. En `if`, nombra Bash, como en `Bash(tail *)`. El hook no se ejecuta si su `if` nombra Monitor
396
388### Campos de manejador de hook397### Campos de manejador de hook
389 398
390Cada objeto en el array `hooks` interno es un manejador de hook: el comando shell, punto final HTTP, herramienta MCP, prompt LLM o agente que se ejecuta cuando el matcher coincide. Hay cinco tipos:399Cada objeto en el array `hooks` interno es un manejador de hook: el comando shell, punto final HTTP, herramienta MCP, prompt LLM o agente que se ejecuta cuando el matcher coincide. Hay cinco tipos:
811* **Dos o más líneas que se analizan como JSON cada una por su cuenta, la primera comenzando con `{` y la última terminando con `}`**: texto plano cuando ninguna línea es un objeto de salida JSON que establezca un campo. Cuando alguna lo es, la salida es un fallo de análisis, así que imprime ese objeto sin nada más en stdout.820* **Dos o más líneas que se analizan como JSON cada una por su cuenta, la primera comenzando con `{` y la última terminando con `}`**: texto plano cuando ninguna línea es un objeto de salida JSON que establezca un campo. Cuando alguna lo es, la salida es un fallo de análisis, así que imprime ese objeto sin nada más en stdout.
812* **Cualquier otra cosa que comience con `{` y termine con `}` pero no sea JSON válido**: un fallo de análisis.821* **Cualquier otra cosa que comience con `{` y termine con `}` pero no sea JSON válido**: un fallo de análisis.
813 822
814Para la mayoría de los eventos, Claude Code escribe stdout en el registro de depuración y no lo muestra en la transcripción. Las excepciones son `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` y `PostModelSwitch`, donde Claude Code agrega el stdout de texto plano como contexto que Claude puede ver y sobre el que puede actuar. En esos eventos, Claude Code no agrega el stdout que no pudo analizar.823Para la mayoría de los eventos, Claude Code escribe stdout en el registro de depuración y no lo muestra en la transcripción. En estos eventos, tu stdout llega a Claude o al resumen de compactación:
824
825* **`UserPromptSubmit`, `UserPromptExpansion`, `SessionStart` y `PostModelSwitch`**: Claude Code agrega el stdout de texto plano como contexto que Claude puede ver y sobre el que puede actuar. No agrega el stdout que no pudo analizar.
826* **`PreCompact`**: tu stdout se convierte en [instrucciones para el resumen de compactación](#precompact-output)
815 827
816Claude 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.828Claude 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.
817 829
1050Las cadenas `additionalContext`, `systemMessage` e `initialUserMessage` de un hook, y su stdout plano, están limitadas a 10.000 caracteres:1062Las cadenas `additionalContext`, `systemMessage` e `initialUserMessage` de un hook, y su stdout plano, están limitadas a 10.000 caracteres:
1051 1063
1052* **Alcance**: Claude Code mide cada cadena por separado, incluso cuando varios hooks se ejecutan para el mismo evento. En la salida JSON, cada campo se mide por separado; el stdout plano se mide completo.1064* **Alcance**: Claude Code mide cada cadena por separado, incluso cuando varios hooks se ejecutan para el mismo evento. En la salida JSON, cada campo se mide por separado; el stdout plano se mide completo.
1053* **Por encima del límite**: Claude Code guarda la salida en un archivo en el directorio de la 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 y grande se maneja de la misma manera, como se describe en [Límites de salida](https://code.claude.com/docs/es/tools-reference.md#output-limits). A diferencia de ese tope de Bash, este límite no tiene ningún ajuste ni variable de entorno para aumentarlo.1065* **Por encima del límite**: excepto para el [stdout de PreCompact](#precompact-output), Claude Code guarda la salida en un archivo en el directorio de la sesión. Reemplaza la salida con la ruta del archivo y una vista previa de hasta los primeros 2.000 caracteres. Un resultado de Bash válido y grande se maneja de la misma manera, como se describe en [Límites de salida](https://code.claude.com/docs/es/tools-reference.md#output-limits). A diferencia de ese tope de Bash, este límite no tiene ningún ajuste ni variable de entorno para aumentarlo.
1054* **Lectura del archivo**: Claude Code no le pide a Claude que lea el archivo, así que mantén dentro del límite todo lo que Claude deba ver siempre.1066* **Lectura del archivo**: Claude Code no le pide a Claude que lea el archivo, así que mantén dentro del límite todo lo que Claude deba ver siempre.
1055 1067
1056El objeto JSON admite tres tipos de campos:1068El objeto JSON admite tres tipos de campos:
1954 1966
1955#### Control de decisiones de PreToolUse1967#### Control de decisiones de PreToolUse
1956 1968
1957Los hooks `PreToolUse` pueden controlar si una llamada a herramienta continúa. A diferencia de otros hooks que usan un campo `decision` de nivel superior, PreToolUse devuelve su decisión dentro de un objeto `hookSpecificOutput`. Esto le da un control más completo: cuatro resultados (permitir, denegar, preguntar o diferir) y la capacidad de modificar la entrada de la herramienta antes de la ejecución.1969Los hooks de `PreToolUse` pueden controlar si una llamada a herramienta continúa. A diferencia de otros hooks que usan un campo `decision` de nivel superior, PreToolUse devuelve su decisión dentro de un objeto `hookSpecificOutput`. Esto le da un control más rico: cuatro resultados (permitir, denegar, preguntar o diferir), además de la capacidad de modificar la entrada de la herramienta antes de la ejecución. Para permitir o reescribir un comando de Monitor, consulta [Hacer coincidir comandos de Monitor](#match-monitor-commands).
1958 1970
1959| Campo | Descripción |1971| Campo | Descripción |
1960| :- | :- |1972| :- | :- |
2051 2063
2052#### Diferir una llamada a herramienta para más tarde2064#### Diferir una llamada a herramienta para más tarde
2053 2065
2054`"defer"` está pensado para integraciones que ejecutan `claude -p` como subproceso y leen su salida JSON, como una aplicación del Agent SDK o una interfaz personalizada construida sobre Claude Code. Permite que ese proceso llamador pause a Claude en una llamada a herramienta, recopile la entrada mediante su propia interfaz y reanude donde se quedó. Claude Code respeta este valor solo en el [modo no interactivo](https://code.claude.com/docs/es/headless.md) con el flag `-p`. En las sesiones interactivas, registra una advertencia e ignora el resultado del hook.2066`"defer"` es para integraciones que ejecutan `claude -p` como subproceso y leen su salida JSON, como una app de Agent SDK o una UI personalizada creada sobre Claude Code. Permite que ese proceso que hace la llamada pause a Claude en una llamada a herramienta, recopile la entrada a través de su propia interfaz y reanude donde lo dejó.
2067
2068Claude Code respeta `"defer"` solo en [modo no interactivo](https://code.claude.com/docs/es/headless.md) con el flag `-p`, y solo cuando Claude hace una única llamada a herramienta en el turno:
2069
2070* **En sesiones interactivas**: registra una advertencia e ignora el resultado del hook
2071* **Varias llamadas a herramientas a la vez**: `"defer"` se ignora con una advertencia y la herramienta continúa por el flujo de permisos normal
2055 2072
2056La herramienta `AskUserQuestion` es el caso típico: Claude quiere preguntarle algo al usuario, pero no hay una terminal donde responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [host de permisos](https://code.claude.com/docs/es/headless.md#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasas con `--permission-prompt-tool`, así que inicia la ejecución con uno. El recorrido completo funciona así:2073La herramienta `AskUserQuestion` es el caso típico: Claude quiere preguntarle algo al usuario, pero no hay una terminal donde responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [host de permisos](https://code.claude.com/docs/es/headless.md#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasas con `--permission-prompt-tool`, así que inicia la ejecución con uno. El recorrido completo funciona así:
2057 2074
20614. El proceso llamador ejecuta `claude -p --resume <session-id>` con el mismo host de permisos. La misma llamada a herramienta vuelve a disparar `PreToolUse`.20784. El proceso llamador ejecuta `claude -p --resume <session-id>` con el mismo host de permisos. La misma llamada a herramienta vuelve a disparar `PreToolUse`.
20625. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.20795. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.
2063 2080
2064El campo `deferred_tool_use` contiene el `id`, el `name` y el `input` de la herramienta. El `input` son los parámetros que Claude generó para la llamada a herramienta, capturados antes de la ejecución:2081El campo `deferred_tool_use` lleva el `id`, el `name` y el `input` de la herramienta:
2065 2082
2066```json theme={null}2083```json theme={null}
2067{2084{
2077}2094}
2078```2095```
2079 2096
2080No hay tiempo de espera ni límite de reintentos. La sesión permanece en disco hasta que la reanudas, sujeta a la limpieza de retención de [`cleanupPeriodDays`](https://code.claude.com/docs/es/settings-reference#cleanupperioddays), que elimina los archivos de sesión después de 30 días de forma predeterminada, según las [reglas de limpieza de retención](https://code.claude.com/docs/es/claude-directory.md#cleaned-up-automatically).2097No hay tiempo de espera ni límite de reintentos. La sesión permanece en disco hasta que la [limpieza por retención](https://code.claude.com/docs/es/claude-directory.md#cleaned-up-automatically) de [`cleanupPeriodDays`](https://code.claude.com/docs/es/settings-reference#cleanupperioddays) la elimina, después de 30 días de forma predeterminada.
2081
2082Si la herramienta diferida ya no está disponible cuando reanudas, el primer resultado de la reanudación tiene `stop_reason: "tool_deferred_unavailable"` e `is_error: true`, y el hook no se dispara. Esto ocurre cuando un servidor MCP que proporcionaba la herramienta no está conectado en la sesión reanudada. El payload `deferred_tool_use` se sigue incluyendo para que puedas identificar qué herramienta falta.
2083
2084* **Si no enviaste ningún prompt, ni con la reanudación ni después**, la llamada sigue pendiente. Reanuda de nuevo con la herramienta disponible y se ejecutará primero.
2085* **Si enviaste un prompt, con la reanudación o después**, Claude Code lo responde sin el resultado de la herramienta y descarta la llamada diferida. Envía un nuevo prompt cuando la herramienta esté disponible si aún necesitas que se llame.
2086 2098
2087Si la respuesta que esperas no está lista cuando reanudas sin un prompt, el hook puede volver a devolver `"defer"`. Si enviaste un prompt y el hook vuelve a diferir, Claude Code trata el prompt de la misma manera: lo responde sin el resultado de la herramienta y descarta la llamada. Reanuda sin un prompt hasta que el hook devuelva `"allow"` o `"deny"`, que es como el proceso que hace la llamada rompe el bucle.2099Si la respuesta no está lista cuando reanudas, el hook puede devolver `"defer"` otra vez. Si enviaste un prompt con esa reanudación, Claude lo responde sin el resultado de la herramienta y no ejecuta la llamada. Reanuda sin un prompt hasta que el hook devuelva `"allow"` o `"deny"`.
2088
2089`"defer"` solo funciona cuando Claude hace una única llamada a herramienta en el turno. Si Claude hace varias llamadas a herramientas a la vez, `"defer"` se ignora con una advertencia y la herramienta continúa por el flujo de permisos normal. Esta restricción existe porque la reanudación solo puede volver a ejecutar una herramienta: no hay forma de diferir una llamada de un lote sin dejar las demás sin resolver.
2090 2100
2091> [!NOTE]2101> [!NOTE]
2092>2102>
2093> Para reanudar una sesión diferida en modo plan, pasa [`--permission-prompt-tool`](https://code.claude.com/docs/es/cli-reference#cli-flags) junto con `--resume` para que Claude Code pueda presentar el plan para su aprobación. Para las demás condiciones, consulta [Reanudar en modo plan con `-p`](https://code.claude.com/docs/es/sessions#resume-in-plan-mode-with-p). Requiere Claude Code v2.1.246 o posterior.2103> Para reanudar una sesión diferida en modo plan, pasa [`--permission-prompt-tool`](https://code.claude.com/docs/es/cli-reference#cli-flags) junto con `--resume` para que Claude Code pueda presentar el plan para su aprobación. Para las demás condiciones, consulta [Reanudar en modo plan con `-p`](https://code.claude.com/docs/es/sessions#resume-in-plan-mode-with-p). Requiere Claude Code v2.1.246 o posterior.
2094>2104>
2095> Cuando reanudas con `-p`, Claude Code no restaura ningún otro modo de permisos almacenado. Inicia la ejecución en el modo de permisos en el que se iniciaría una ejecución nueva de `claude -p`, así que vuelve a pasar `--permission-mode` o `--dangerously-skip-permissions` si la sesión diferida usaba alguno. Cuando reanudas con `claude --resume <session-id>` sin `-p`, Claude Code restaura el modo de permisos almacenado, con las excepciones que se indican en [modo de permisos al reanudar](https://code.claude.com/docs/es/sessions.md#permission-mode-on-resume).2105> Cuando reanudas con `-p`, Claude Code no restaura ningún otro modo de permisos almacenado. Inicia la ejecución en el modo de permisos en el que se iniciaría una nueva ejecución de `claude -p`, así que vuelve a pasar `--permission-mode` o `--dangerously-skip-permissions` si la sesión diferida usaba uno.
2106
2107##### Reanudar cuando una herramienta diferida no está disponible
2108
2109Un resultado con `stop_reason: "tool_deferred_unavailable"` significa que la herramienta de una llamada diferida no está disponible en la sesión reanudada, por ejemplo porque su servidor MCP no está conectado. Tu hook `PreToolUse` no se dispara, y el campo `deferred_tool_use` del resultado indica el nombre de la herramienta.
2110
2111Mientras la llamada está pendiente, cualquier prompt que envíes no llega a Claude y la ejecución termina con el código 1. El campo `result` comienza con `<tool> isn't available, so its deferred call didn't run.` Ejecuta la llamada o descártala para que no se ejecute:
2112
2113* **Para ejecutar la llamada**: haz que la herramienta esté disponible y reanuda de nuevo.
2114* **Para descartar la llamada**: reanuda con un prompt y con [`CLAUDE_CODE_DROP_UNAVAILABLE_DEFERRED_TOOL`](https://code.claude.com/docs/es/env-vars#variables) establecida en `1`. Claude recibe un error como resultado de la llamada y responde tu prompt. Cuando reanudes más tarde, no habrá ninguna llamada pendiente.
2115
2116Cuando descartas la llamada, la ejecución escribe el resultado `tool_deferred_unavailable` con un campo `result` vacío y, luego, la respuesta de Claude en un segundo resultado. Termina con el código 0 a menos que esa respuesta sea un error. Si estableces la variable y no envías ningún prompt, la ejecución igualmente descarta la llamada y termina con el código 1.
2117
2118Antes de v2.1.319, Claude Code respondía un prompt sin el resultado de la herramienta y descartaba la llamada. En esas versiones, envía un nuevo prompt una vez que la herramienta esté disponible.
2096 2119
2097### PermissionRequest2120### PermissionRequest
2098 2121
2148| `message` | Solo para `"deny"`: le indica a Claude por qué se denegó el permiso |2171| `message` | Solo para `"deny"`: le indica a Claude por qué se denegó el permiso |
2149| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |2172| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |
2150 2173
2174Para permitir o reescribir un comando de Monitor, consulta [Hacer coincidir comandos de Monitor](#match-monitor-commands).
2175
2151Un hook que sale con 2 sin un objeto `decision` deja sin cambios el flujo de permisos, y su stderr se descarta. Para conceder o denegar la solicitud, devuelve el objeto `decision`.2176Un hook que sale con 2 sin un objeto `decision` deja sin cambios el flujo de permisos, y su stderr se descarta. Para conceder o denegar la solicitud, devuelve el objeto `decision`.
2152 2177
2153```json theme={null}2178```json theme={null}
2205* Para ejecutar un hook después de que cualquier herramienta se complete correctamente, omite el `matcher` o establécelo en `"*"`. Así, tu hook puede descubrir por sí mismo qué cambió, por ejemplo ejecutando `git status --porcelain`, que también enumera los archivos sin seguimiento que `git diff` pasa por alto. Para las llamadas a herramientas que fallan, agrega el mismo hook en [PostToolUseFailure](#posttoolusefailure).2230* Para ejecutar un hook después de que cualquier herramienta se complete correctamente, omite el `matcher` o establécelo en `"*"`. Así, tu hook puede descubrir por sí mismo qué cambió, por ejemplo ejecutando `git status --porcelain`, que también enumera los archivos sin seguimiento que `git diff` pasa por alto. Para las llamadas a herramientas que fallan, agrega el mismo hook en [PostToolUseFailure](#posttoolusefailure).
2206* Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, usa [FileChanged](#filechanged). Claude Code no ejecuta un hook `PostToolUse` que coincida con `Edit|Write` cuando un comando `Bash` o un proceso externo a Claude Code reescribe el mismo archivo.2231* Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, usa [FileChanged](#filechanged). Claude Code no ejecuta un hook `PostToolUse` que coincida con `Edit|Write` cuando un comando `Bash` o un proceso externo a Claude Code reescribe el mismo archivo.
2207 2232
2233#### PostToolUse después de una interrupción
2234
2235Si un hook `PostToolUse` se detiene antes de tiempo después de que envías un mensaje o interrumpes durante una llamada a herramienta, verifica si presionaste `Ctrl+Enter`, `Enter` o `Esc`:
2236
2237* **`Ctrl+Enter`**: si presionarla [termina el turno](https://code.claude.com/docs/es/interactive-mode.md#when-claude-code-sends-what-you-queued) mientras una herramienta se está ejecutando y la herramienta termina, tus hooks `PostToolUse` se ejecutan sobre su resultado y tienen 10 segundos para terminar. La tecla actúa como `Esc` si pusiste en cola un comando `!` antes de tus mensajes o si las tareas en segundo plano están desactivadas, por ejemplo con [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/es/env-vars#variables).
2238* **`Enter`**: un mensaje que pones en cola con `Enter` no interrumpe el turno, así que los hooks conservan su `timeout` habitual.
2239* **`Esc`**: cancelas los hooks de inmediato, así que envía el mensaje con `Enter` o `Ctrl+Enter` cuando los hooks tengan que ejecutarse.
2240
2241Cuando se cumplen los 10 segundos, Claude Code finaliza un hook de comando que aún se esté ejecutando, sea cual sea su [`timeout`](#common-fields). Para permitir que un hook de comando más largo termine, ejecútalo con [`async: true`](#run-hooks-in-the-background), lo que significa que el hook no puede bloquear ni reescribir el resultado.
2242
2243Antes de v2.1.319, los hooks no se iniciaban después de que interrumpías el turno con un mensaje, y un hook en ejecución se detenía.
2244
2208#### Entrada de PostToolUse2245#### Entrada de PostToolUse
2209 2246
2210Los hooks `PostToolUse` se disparan después de que una herramienta ya se ejecutó correctamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto de ambos depende de la herramienta. Las rutas de `tool_input` de las herramientas de archivos llegan en el mismo formato que para [PreToolUse](#pretooluse-input): siempre absolutas, con los separadores nativos de la plataforma, es decir, barras invertidas en Windows. Para una herramienta MCP, la entrada también incluye el objeto [`mcp_server`](#pretooluse-input).2247Los hooks `PostToolUse` se disparan después de que una herramienta ya se ejecutó correctamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto de ambos depende de la herramienta. Las rutas de `tool_input` de las herramientas de archivos llegan en el mismo formato que para [PreToolUse](#pretooluse-input): siempre absolutas, con los separadores nativos de la plataforma, es decir, barras invertidas en Windows. Para una herramienta MCP, la entrada también incluye el objeto [`mcp_server`](#pretooluse-input).
2479| `permission_prompt` | Claude necesita que apruebes el uso de una herramienta o la [solicitud de red](https://code.claude.com/docs/es/sandboxing.md#network-isolation) de un comando en el sandbox, y la solicitud lleva esperando unos seis segundos |2516| `permission_prompt` | Claude necesita que apruebes el uso de una herramienta o la [solicitud de red](https://code.claude.com/docs/es/sandboxing.md#network-isolation) de un comando en el sandbox, y la solicitud lleva esperando unos seis segundos |
2480| `idle_prompt` | Claude terminó de responder hace unos 60 segundos y no has escrito nada desde entonces |2517| `idle_prompt` | Claude terminó de responder hace unos 60 segundos y no has escrito nada desde entonces |
2481| `auth_success` | Se completa la autenticación |2518| `auth_success` | Se completa la autenticación |
2519| `auth_storage_failure` | Tu inicio de sesión se completa, pero Claude Code no puede guardar las nuevas credenciales en su [almacenamiento de credenciales](https://code.claude.com/docs/es/authentication.md#credential-management). Se dispara en lugar de `auth_success` |
2482| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no has escrito nada durante unos seis segundos |2520| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no has escrito nada durante unos seis segundos |
2483| `elicitation_url_dialog` | Un servidor MCP te pide que abras una URL en el navegador y no has escrito nada durante unos seis segundos |2521| `elicitation_url_dialog` | Un servidor MCP te pide que abras una URL en el navegador y no has escrito nada durante unos seis segundos |
2484| `elicitation_complete` | Un servidor MCP informa que una [elicitación en modo URL](#elicitation-input) se completó |2522| `elicitation_complete` | Un servidor MCP informa que una [elicitación en modo URL](#elicitation-input) se completó |
2490| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar tu tarea: [`autoContinueAtUsageLimit`](https://code.claude.com/docs/es/settings-reference#autocontinueatusagelimit) se desactivó o el restablecimiento se movió a más de 24 horas durante una espera que Claude Code inició por su cuenta, la tarea continuada siguió alcanzando el límite, o la continuación se bloqueó antes de llegar al modelo. No se dispara cuando presionas `Esc` o `Ctrl+C`, o eliges **Don't continue automatically** |2528| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar tu tarea: [`autoContinueAtUsageLimit`](https://code.claude.com/docs/es/settings-reference#autocontinueatusagelimit) se desactivó o el restablecimiento se movió a más de 24 horas durante una espera que Claude Code inició por su cuenta, la tarea continuada siguió alcanzando el límite, o la continuación se bloqueó antes de llegar al modelo. No se dispara cuando presionas `Esc` o `Ctrl+C`, o eliges **Don't continue automatically** |
2491| `plugin_notification` | Un [mod](https://code.claude.com/docs/es/plugins/mods/api.md#show-something-without-starting-a-turn) genera una notificación con `$.ui.notify`. El `title` del hook es el nombre del mod, a menos que el mod haya establecido uno |2529| `plugin_notification` | Un [mod](https://code.claude.com/docs/es/plugins/mods/api.md#show-something-without-starting-a-turn) genera una notificación con `$.ui.notify`. El `title` del hook es el nombre del mod, a menos que el mod haya establecido uno |
2492 2530
2493Los tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` y `quota_auto_resume_disabled` requieren Claude Code v2.1.234 o posterior.2531Los tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` y `quota_auto_resume_disabled` requieren Claude Code v2.1.234 o posterior. El tipo `auth_storage_failure` requiere v2.1.288 o posterior.
2494 2532
2495En sesiones de terminal, `permission_prompt` para la solicitud de red de un comando en el sandbox requiere Claude Code v2.1.246 o posterior.2533En sesiones de terminal, `permission_prompt` para la solicitud de red de un comando en el sandbox requiere Claude Code v2.1.246 o posterior.
2496 2534
3326}3364}
3327```3365```
3328 3366
3367#### Salida de PreCompact
3368
3369Cuando un hook PreCompact termina con 0 y no bloquea, Claude Code usa su stdout como instrucciones para el resumen de la compactación. Mantén ese stdout por debajo de 10.000 caracteres por hook. Claude Code corta la salida más larga en el límite y agrega un marcador.
3370
3329### PostCompact3371### PostCompact
3330 3372
3331Se ejecuta después de que Claude Code completa una operación de compactación. Usa este evento para reaccionar al nuevo estado compactado, por ejemplo para registrar el resumen generado o actualizar un estado externo. Claude Code descarta los campos `systemMessage` y `continue` de un hook PostCompact.3373Se ejecuta después de que Claude Code completa una operación de compactación. Usa este evento para reaccionar al nuevo estado compactado, por ejemplo para registrar el resumen generado o actualizar un estado externo. Claude Code descarta los campos `systemMessage` y `continue` de un hook PostCompact.
