274 274
275Los hooks de archivos de configuración, configuración de política administrada y plugins también se ejecutan dentro de [subagentes](/docs/es/sub-agents). Cuando un subagente llama a una herramienta, eventos de herramienta como `PreToolUse` y `PostToolUse` activan los mismos hooks configurados que en la conversación principal, y la entrada lleva los campos de entrada comunes `agent_id` y `agent_type` [](#common-input-fields) que identifican al subagente.275Los hooks de archivos de configuración, configuración de política administrada y plugins también se ejecutan dentro de [subagentes](/docs/es/sub-agents). Cuando un subagente llama a una herramienta, eventos de herramienta como `PreToolUse` y `PostToolUse` activan los mismos hooks configurados que en la conversación principal, y la entrada lleva los campos de entrada comunes `agent_id` y `agent_type` [](#common-input-fields) que identifican al subagente.
276 276
277Los administradores empresariales pueden usar `allowManagedHooksOnly` para restringir qué hooks se ejecutan:277Los administradores pueden usar [`allowManagedHooksOnly`](/docs/es/settings-reference#allowmanagedhooksonly) en [configuración administrada](/docs/es/managed-settings) para restringir qué hooks se ejecutan:
278 278
279* Tus hooks de usuario, proyecto, local y plugin están bloqueados. Los hooks de plugins forzados a habilitarse en la configuración administrada `enabledPlugins` están exentos279* Tus hooks de usuario, proyecto, local y plugin están bloqueados. Los hooks de plugins forzados a habilitarse en la configuración administrada `enabledPlugins` están exentos
280* Claude Code también reduce tu configuración [`statusLine`](/docs/es/statusline), [`fileSuggestion`](/docs/es/settings-reference#filesuggestion) y [`subagentStatusLine`](/docs/es/statusline#subagent-status-lines) a la configuración administrada280* Claude Code también reduce tu configuración [`statusLine`](/docs/es/statusline), [`fileSuggestion`](/docs/es/settings-reference#filesuggestion) y [`subagentStatusLine`](/docs/es/statusline#subagent-status-lines) a la configuración administrada
304 304
305Un 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.305Un 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.
306 306
307Los guiones en el conjunto de coincidencia exacta requieren Claude Code v2.1.195 o posterior. En versiones anteriores, un nombre con guiones como `code-reviewer` se evalúa como una expresión regular sin anclar, por lo que también se activa para `senior-code-reviewer`; anclalo como `^code-reviewer$` en esas versiones para coincidir solo con ese nombre.
308
309`FileChanged` y `StopFailure` utilizan un conjunto de coincidencia exacta más estrecho de solo letras, dígitos, `_` y `|`. Un guión, espacio o coma en un matcher para esos dos eventos lo mantiene en la ruta de expresión regular, y solo `|` separa alternativas. Todos los demás eventos con soporte de matcher en la tabla que sigue aceptan `|` o `,`.307`FileChanged` y `StopFailure` utilizan un conjunto de coincidencia exacta más estrecho de solo letras, dígitos, `_` y `|`. Un guión, espacio o coma en un matcher para esos dos eventos lo mantiene en la ruta de expresión regular, y solo `|` separa alternativas. Todos los demás eventos con soporte de matcher en la tabla que sigue aceptan `|` o `,`.
310 308
311El evento `FileChanged` no sigue estas reglas al construir su lista de vigilancia. Consulta [FileChanged](#filechanged).309El evento `FileChanged` no sigue estas reglas al construir su lista de vigilancia. Consulta [FileChanged](#filechanged).
380* `mcp__brave-search__.*` coincide con todas las herramientas de un servidor cuyo nombre contiene un guión378* `mcp__brave-search__.*` coincide con todas las herramientas de un servidor cuyo nombre contiene un guión
381* `mcp__.*__write.*` coincide con cualquier herramienta cuyo nombre comienza con `write` de cualquier servidor379* `mcp__.*__write.*` coincide con cualquier herramienta cuyo nombre comienza con `write` de cualquier servidor
382 380
383Los guiones en el conjunto de coincidencia exacta requieren Claude Code v2.1.195 o posterior. En versiones anteriores, un prefijo con guiones desnudo como `mcp__brave-search` se evalúa como una expresión regular sin anclar y coincide con cada herramienta de ese servidor. La forma `mcp__brave-search__.*` funciona en cada versión.
384
385Las herramientas de un [servidor MCP incluido en plugin](/docs/es/mcp#plugin-provided-mcp-servers) utilizan un segmento de servidor con alcance que incluye el nombre del plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Un matcher escrito contra la clave del servidor desnuda nunca se activa para estas herramientas. Para un plugin llamado `my-plugin` que incluye un servidor bajo la clave `db`, una herramienta `query` aparece como `mcp__plugin_my-plugin_db__query`, por lo que el matcher para cada herramienta de ese servidor es `mcp__plugin_my-plugin_db__.*`. Utiliza el mismo nombre de herramienta con alcance en el campo [`if`](#common-fields) de un manejador. Consulta [Servidores MCP incluidos en plugin](/docs/es/mcp#plugin-provided-mcp-servers) para saber cómo se construye el nombre con alcance.381Las herramientas de un [servidor MCP incluido en plugin](/docs/es/mcp#plugin-provided-mcp-servers) utilizan un segmento de servidor con alcance que incluye el nombre del plugin: `mcp__plugin_<plugin-name>_<server-name>__<tool>`. Un matcher escrito contra la clave del servidor desnuda nunca se activa para estas herramientas. Para un plugin llamado `my-plugin` que incluye un servidor bajo la clave `db`, una herramienta `query` aparece como `mcp__plugin_my-plugin_db__query`, por lo que el matcher para cada herramienta de ese servidor es `mcp__plugin_my-plugin_db__.*`. Utiliza el mismo nombre de herramienta con alcance en el campo [`if`](#common-fields) de un manejador. Consulta [Servidores MCP incluidos en plugin](/docs/es/mcp#plugin-provided-mcp-servers) para saber cómo se construye el nombre con alcance.
386 382
387Este ejemplo registra todas las operaciones del servidor de memoria y valida operaciones de escritura de cualquier servidor MCP:383Este ejemplo registra todas las operaciones del servidor de memoria y valida operaciones de escritura de cualquier servidor MCP:
919| :- | :- | :- |915| :- | :- | :- |
920| `PreToolUse` | Sí | Bloquea la llamada a herramienta |916| `PreToolUse` | Sí | Bloquea la llamada a herramienta |
921| `PermissionRequest` | No | El código de salida 2 no se honra para este evento y el flujo de permiso procede sin cambios. Deniegue a través del objeto [`decision`](#permissionrequest-decision-control) en su lugar |917| `PermissionRequest` | No | El código de salida 2 no se honra para este evento y el flujo de permiso procede sin cambios. Deniegue a través del objeto [`decision`](#permissionrequest-decision-control) en su lugar |
922| `UserPromptSubmit` | Sí | Bloquea el procesamiento del prompt y borra el prompt |918| `UserPromptSubmit` | Sí | Bloquea el prompt, por lo que nunca llega a Claude. Consulte [What a blocked prompt leaves behind](#what-a-blocked-prompt-leaves-behind) |
923| `UserPromptExpansion` | Sí | Bloquea la expansión |919| `UserPromptExpansion` | Sí | Bloquea la expansión |
924| `Stop` | Sí | Evita que Claude se detenga, continúa la conversación |920| `Stop` | Sí | Evita que Claude se detenga, continúa la conversación |
925| `SubagentStop` | Sí | Evita que el subagente se detenga |921| `SubagentStop` | Sí | Evita que el subagente se detenga |
1187| `resume` | `--resume`, `--continue`, o `/resume` |1183| `resume` | `--resume`, `--continue`, o `/resume` |
1188| `clear` | `/clear` |1184| `clear` | `/clear` |
1189| `compact` | Compactación automática o manual |1185| `compact` | Compactación automática o manual |
1190| `fork` | Una nueva sesión bifurcada desde una existente: `--fork-session` con `--resume` o `--continue`, la copia de fondo `/fork`, o `/branch` |1186| `fork` | Una nueva sesión bifurcada desde una existente: `--fork-session` con `--resume` o `--continue`, la copia de fondo `/fork`, `/branch`, o una conversación que [mueve al fondo](/docs/es/agent-view#from-inside-a-session) |
1191 1187
1192Antes de v2.1.214, las sesiones bifurcadas reportaban origen `"resume"`.1188Antes de v2.1.214, las sesiones bifurcadas reportaban origen `"resume"`.
1193 1189
1194Cuando inicia una sesión interactiva, reanuda una conversación al iniciar con `--continue` o `--resume`, o ejecuta `/clear`, los hooks SessionStart se ejecutan en segundo plano. Puede escribir de inmediato, y una conversación que reanudó aparece sin esperar a los hooks. La primera respuesta de Claude aún espera a que los hooks terminen, por lo que su contexto llega a Claude.1190Cuando inicia una sesión interactiva, reanuda una conversación al iniciar con `--continue` o `--resume`, o ejecuta `/clear`, los hooks SessionStart se ejecutan en segundo plano. Puede escribir de inmediato, y una conversación que reanudó aparece sin esperar a que se completen los hooks. La primera respuesta de Claude aún espera a que se completen los hooks, por lo que su contexto llega a Claude.
1195 1191
1196Cuando cambia de conversaciones con `/resume` dentro de una sesión, el cambio espera a que los hooks terminen. Si ejecuta `/clear` o cambia a otra conversación mientras los hooks de fondo aún se están ejecutando, nada de lo que devuelven se aplica a la sesión.1192Cuando cambia de conversaciones con `/resume` dentro de una sesión, el cambio espera a que se completen los hooks. Si ejecuta `/clear` o cambia a otra conversación mientras los hooks de fondo aún se están ejecutando, nada de lo que devuelven se aplica a la sesión.
1197 1193
1198La misma espera se aplica al iniciar, incluida una sesión reanudada: un prompt que envía mientras los hooks SessionStart aún se están ejecutando no llega a Claude hasta que terminen.1194La misma espera se aplica al iniciar, incluida una sesión reanudada: un prompt que envía mientras los hooks SessionStart aún se están ejecutando no llega a Claude hasta que se completen.
1199 1195
1200Durante cualquiera de las esperas, presione `Esc` para recuperar el prompt en la entrada sin enviarlo. Los hooks siguen ejecutándose.1196Durante cualquiera de las esperas, presione `Esc` para recuperar el prompt en la entrada sin enviarlo. Los hooks siguen ejecutándose.
1201 1197
1208| Campo | Descripción |1204| Campo | Descripción |
1209| :- | :- |1205| :- | :- |
1210| `source` | Cómo se inició la sesión: `"startup"` para nuevas sesiones, `"resume"` para sesiones reanudadas, `"clear"` después de `/clear`, `"compact"` después de compactación, o `"fork"` para una nueva sesión bifurcada desde una existente |1206| `source` | Cómo se inició la sesión: `"startup"` para nuevas sesiones, `"resume"` para sesiones reanudadas, `"clear"` después de `/clear`, `"compact"` después de compactación, o `"fork"` para una nueva sesión bifurcada desde una existente |
1211| `model` | El identificador del modelo activo. Puede omitirse, por ejemplo después de `/clear` o cuando una sesión se restaura a través de recuperación de conversación, así que verifique el campo antes de leerlo |1207| `model` | El identificador del modelo activo. Puede omitirse, por ejemplo después de `/clear` o cuando se restaura una sesión a través de recuperación de conversación, así que verifique el campo antes de leerlo |
1212| `agent_type` | El nombre del agente, presente cuando inicia Claude Code con `claude --agent <name>` |1208| `agent_type` | El nombre del agente, presente cuando inicia Claude Code con `claude --agent <name>` |
1213| `session_title` | El título de sesión actual si ya está establecido, por ejemplo a través de `--name` o `/rename`. Un hook que emite `sessionTitle` puede verificar `session_title` primero para evitar sobrescribir un título que el usuario estableció explícitamente |1209| `session_title` | El título de sesión actual si ya está establecido, por ejemplo a través de `--name` o `/rename`. Un hook que emite `sessionTitle` puede verificar `session_title` primero para evitar sobrescribir un título que el usuario estableció explícitamente |
1214 1210
1218| :- | :- |1214| :- | :- |
1219| `seconds_since_last_response` | Segundos de reloj de pared desde la última respuesta en la transcripción reanudada |1215| `seconds_since_last_response` | Segundos de reloj de pared desde la última respuesta en la transcripción reanudada |
1220| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada reenvía como su prompt |1216| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada reenvía como su prompt |
1221| `prompt_cache_likely_expired` | `true` cuando la última respuesta es más antigua que la [duración del caché de prompt](/docs/es/prompt-caching#cache-lifetime) de la sesión o una compactación posterior reemplazó la conversación en caché |1217| `prompt_cache_likely_expired` | `true` cuando la última respuesta es más antigua que la [duración de vida del caché de prompt](/docs/es/prompt-caching#cache-lifetime) de la sesión o una compactación posterior reemplazó la conversación en caché |
1222| `estimated_cache_write_usd` | Costo estimado en dólares estadounidenses de escribir `context_tokens` en el caché de prompt en el modelo de la sesión, excluyendo la respuesta |1218| `estimated_cache_write_usd` | Costo estimado en dólares estadounidenses de escribir `context_tokens` en el caché de prompt en el modelo de la sesión, excluyendo la respuesta |
1223 1219
1224Este ejemplo muestra la entrada para una sesión reanudada 90 minutos después de su última respuesta:1220Este ejemplo muestra la entrada para una sesión reanudada 90 minutos después de su última respuesta:
1250| `initialUserMessage` | Cadena utilizada como el primer mensaje del usuario de la sesión. Se aplica en [modo no interactivo](/docs/es/headless) con la bandera `-p`, donde se convierte en el primer turno incluso si no se proporciona ningún prompt. Si se proporciona un prompt, lo sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, esto crea el turno |1246| `initialUserMessage` | Cadena utilizada como el primer mensaje del usuario de la sesión. Se aplica en [modo no interactivo](/docs/es/headless) con la bandera `-p`, donde se convierte en el primer turno incluso si no se proporciona ningún prompt. Si se proporciona un prompt, lo sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, esto crea el turno |
1251| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Úselo para nombrar sesiones automáticamente desde la carpeta de inicio, rama de git o nombre de worktree. Se aplica cuando `source` es `"startup"`, `"resume"`, o `"fork"`; se ignora en `"clear"` y `"compact"` |1247| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Úselo para nombrar sesiones automáticamente desde la carpeta de inicio, rama de git o nombre de worktree. Se aplica cuando `source` es `"startup"`, `"resume"`, o `"fork"`; se ignora en `"clear"` y `"compact"` |
1252| `watchPaths` | Matriz de rutas absolutas para observar eventos [FileChanged](#filechanged) durante esta sesión |1248| `watchPaths` | Matriz de rutas absolutas para observar eventos [FileChanged](#filechanged) durante esta sesión |
1253| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a escanear los directorios de [skill](/docs/es/skills) y comando después de que se completen los hooks SessionStart, por lo que las skills que instaló el hook están disponibles en la misma sesión, comenzando con el primer prompt |1249| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a escanear los directorios de [skill](/docs/es/skills) y comando después de que se completen los hooks SessionStart, por lo que los skills que instaló el hook están disponibles en la misma sesión, comenzando con el primer prompt |
1254 1250
1255```json theme={null}1251```json theme={null}
1256{1252{
1264 1260
1265Dado que stdout plano ya llega a Claude para este evento, un hook que solo carga contexto puede imprimir a stdout directamente sin construir JSON. Use la forma JSON cuando necesite combinar contexto con otros campos como `sessionTitle`.1261Dado que stdout plano ya llega a Claude para este evento, un hook que solo carga contexto puede imprimir a stdout directamente sin construir JSON. Use la forma JSON cuando necesite combinar contexto con otros campos como `sessionTitle`.
1266 1262
1267Use `reloadSkills` cuando un hook SessionStart instala o actualiza skills. El descubrimiento de skills normalmente se ejecuta antes de que terminen los hooks SessionStart, por lo 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 de skills compartido y solicita el re-escaneo:1263Use `reloadSkills` cuando un hook SessionStart instala o actualiza skills. El descubrimiento de skills normalmente se ejecuta antes de que se completen los hooks SessionStart, por lo 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 de skills compartido y solicita el re-escaneo:
1268 1264
1269```bash theme={null}1265```bash theme={null}
1270#!/bin/bash1266#!/bin/bash
1339 1335
1340En caso de éxito, `--init-only` no imprime nada en la terminal. Para confirmar que los hooks se ejecutaron, comience con `claude --debug-file <path> --init-only`, reemplazando `<path>` con una ubicación de archivo de registro, y verifique el registro para las entradas de hook Setup y SessionStart.1336En caso de éxito, `--init-only` no imprime nada en la terminal. Para confirmar que los hooks se ejecutaron, comience con `claude --debug-file <path> --init-only`, reemplazando `<path>` con una ubicación de archivo de registro, y verifique el registro para las entradas de hook Setup y SessionStart.
1341 1337
1342Debido a que Setup no se dispara en cada inicio, un plugin que necesita una dependencia instalada no puede confiar solo en Setup. El patrón práctico es verificar la dependencia en el primer uso e instalar si falta, por ejemplo un hook o skill que prueba `${CLAUDE_PLUGIN_DATA}/node_modules` y ejecuta `npm install` si está ausente. Consulte el [directorio de datos persistentes](/docs/es/plugins/components#path-variables-and-persistent-data) para saber dónde almacenar dependencias instaladas. Si distribuye su plugin a través de un marketplace, es posible que no necesite este patrón: Claude Code [instala automáticamente las dependencias de paquetes Node.js elegibles](/docs/es/plugins/loading#node-js-package-dependencies) cuando almacena en caché el plugin.1338Debido a que Setup no se dispara en cada inicio, un plugin que necesita una dependencia instalada no puede confiar solo en Setup. El patrón práctico es verificar la dependencia en el primer uso e instalar si falta, por ejemplo un hook o skill que prueba `${CLAUDE_PLUGIN_DATA}/node_modules` y ejecuta `npm install` si está ausente. Consulte el [directorio de datos persistentes](/docs/es/plugins/components#path-variables-and-persistent-data) para saber dónde almacenar las dependencias instaladas. Si distribuye su plugin a través de un marketplace, es posible que no necesite este patrón: Claude Code [instala automáticamente las dependencias del paquete Node.js elegibles](/docs/es/plugins/loading#node-js-package-dependencies) cuando almacena en caché el plugin.
1343 1339
1344<h4 id="setup-input">1340<h4 id="setup-input">
1345 Entrada de Setup1341 Entrada de Setup
1363 1359
1364Los hooks Setup no pueden bloquear; la ejecución continúa en cualquier código de salida. En cada código de salida, Claude Code descarta los [campos de salida JSON](#json-output) de un hook Setup, como `systemMessage`, `continue`, y `hookSpecificOutput.additionalContext`. Con `-p`, stdout, stderr y el código de salida de un hook Setup aparecen en la salida de la ejecución solo como [eventos `hook_response`](/docs/es/headless#read-session-metadata) cuando inicia con `--output-format stream-json --verbose`.1360Los hooks Setup no pueden bloquear; la ejecución continúa en cualquier código de salida. En cada código de salida, Claude Code descarta los [campos de salida JSON](#json-output) de un hook Setup, como `systemMessage`, `continue`, y `hookSpecificOutput.additionalContext`. Con `-p`, stdout, stderr y el código de salida de un hook Setup aparecen en la salida de la ejecución solo como [eventos `hook_response`](/docs/es/headless#read-session-metadata) cuando inicia con `--output-format stream-json --verbose`.
1365 1361
1366Los hooks Setup tienen acceso a `CLAUDE_ENV_FILE`. Las variables escritas en ese archivo persisten en comandos Bash posteriores para la sesión, tal como en [hooks SessionStart](#persist-environment-variables). Solo se ejecutan hooks `type: "command"` en `Setup`. Un hook `type: "mcp_tool"` en `Setup` siempre se omite, como se describe en [campos de hook de herramienta MCP](#mcp-tool-hook-fields).1362Los hooks Setup tienen acceso a `CLAUDE_ENV_FILE`. Las variables escritas en ese archivo persisten en comandos Bash posteriores para la sesión, al igual que en [hooks SessionStart](#persist-environment-variables). Solo se ejecutan hooks `type: "command"` en `Setup`. Un hook `type: "mcp_tool"` en `Setup` siempre se omite, como se describe en [campos de hook de herramienta MCP](#mcp-tool-hook-fields).
1367 1363
1368<h3 id="instructionsloaded">1364<h3 id="instructionsloaded">
1369 InstructionsLoaded1365 InstructionsLoaded
1406 Control de decisión de InstructionsLoaded1402 Control de decisión de InstructionsLoaded
1407</h4>1403</h4>
1408 1404
1409Los hooks InstructionsLoaded no tienen control de decisión. No pueden bloquear o modificar la carga de instrucciones. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage` y `continue`. Use este evento para auditoría de registros, seguimiento de cumplimiento u observabilidad.1405Los hooks InstructionsLoaded no tienen control de decisión. No pueden bloquear o modificar la carga de instrucciones. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage` y `continue`. Use este evento para auditoría de registro, seguimiento de cumplimiento u observabilidad.
1410 1406
1411<h3 id="userpromptsubmit">1407<h3 id="userpromptsubmit">
1412 UserPromptSubmit1408 UserPromptSubmit
1418 1414
1419Aparte de un hook de comando que ejecuta con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` de comando, HTTP o herramienta MCP que alcanza su tiempo de espera se cancela y su salida, incluido cualquier `additionalContext`, se descarta. El prompt aún llega a Claude sin ese contexto. La transcripción muestra un aviso que nombra el hook, el tiempo de espera que se disparó y que la salida se descartó.1415Aparte de un hook de comando que ejecuta con [`async: true`](#run-hooks-in-the-background), un hook `UserPromptSubmit` de comando, HTTP o herramienta MCP que alcanza su tiempo de espera se cancela y su salida, incluido cualquier `additionalContext`, se descarta. El prompt aún llega a Claude sin ese contexto. La transcripción muestra un aviso que nombra el hook, el tiempo de espera que se disparó y que la salida se descartó.
1420 1416
1421Un [hook de devolución de llamada del SDK del agente](/docs/es/agent-sdk/hooks) en `UserPromptSubmit` que alcanza su tiempo de espera bloquea el prompt con un mensaje que nombra el hook y el tiempo de espera, porque una devolución de llamada allí puede actuar como una puerta de política que no debe fallar abierta. La sesión continúa. Antes de v2.1.208, un tiempo de espera de devolución de llamada en ese evento terminaba el turno con un error de ejecución.1417Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `UserPromptSubmit` que alcanza su tiempo de espera bloquea el prompt con un mensaje que nombra el hook y el tiempo de espera, porque un callback allí puede estar actuando como una puerta de política que no debe fallar abierta. La sesión continúa. Antes de v2.1.208, un tiempo de espera de callback en ese evento terminaba el turno con un error de ejecución.
1422 1418
1423<h4 id="userpromptsubmit-input">1419<h4 id="userpromptsubmit-input">
1424 Entrada de UserPromptSubmit1420 Entrada de UserPromptSubmit
1425</h4>1421</h4>
1426 1422
1427Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptSubmit reciben el campo `prompt` que contiene el texto que el usuario envió. El contenido pegado que se redujo a un marcador de posición `[Pasted text #N]` llega expandido en su lugar. En sesiones donde Claude Code [marca texto pegado para Claude](/docs/es/terminal-config#how-claude-treats-pasted-text), ese contenido expandido se encuentra entre una línea `<pasted_content id="…">` y una línea `</pasted_content id="…">`, así que tenga en cuenta esas líneas si su hook analiza el prompt.1423Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptSubmit reciben el campo `prompt` que contiene el texto que envió el usuario. El contenido pegado que se redujo a un marcador de posición `[Pasted text #N]` llega expandido en su lugar. En sesiones donde Claude Code [marca texto pegado para Claude](/docs/es/terminal-config#how-claude-treats-pasted-text), ese contenido expandido se encuentra entre una línea `<pasted_content id="…">` y una línea `</pasted_content id="…">`, así que tenga en cuenta esas líneas si su hook analiza el prompt.
1428 1424
1429```json theme={null}1425```json theme={null}
1430{1426{
1454 1450
1455| Campo | Descripción |1451| Campo | Descripción |
1456| :- | :- |1452| :- | :- |
1457| `decision` | `"block"` evita que se procese el prompt y lo borra del contexto. Omita para permitir que el prompt continúe |1453| `decision` | `"block"` detiene el prompt antes de que llegue a Claude. Omita para permitir que el prompt continúe |
1458| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se agrega al contexto |1454| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se agrega al contexto |
1459| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1455| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |
1460| `sessionTitle` | Establece el título de la sesión. Úselo para nombrar sesiones automáticamente basándose en el contenido del prompt |1456| `sessionTitle` | Establece el título de la sesión. Úselo para nombrar sesiones automáticamente basándose en el contenido del prompt |
1461| `suppressOriginalPrompt` | Si es `true` cuando `decision` es `"block"`, omite el texto del prompt original del mensaje de bloqueo mostrado al usuario |1457| `suppressOriginalPrompt` | Si es `true` cuando el hook bloquea el prompt, deja el texto del prompt fuera del mensaje de bloqueo. Consulte [Lo que un prompt bloqueado deja atrás](#what-a-blocked-prompt-leaves-behind) |
1462 1458
1463Un hook que bloquea al salir con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario y no se agrega al contexto.1459Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario y no se agrega al contexto.
1464 1460
1465```json theme={null}1461```json theme={null}
1466{1462{
1469 "hookSpecificOutput": {1465 "hookSpecificOutput": {
1470 "hookEventName": "UserPromptSubmit",1466 "hookEventName": "UserPromptSubmit",
1471 "additionalContext": "My additional context here",1467 "additionalContext": "My additional context here",
1472 "sessionTitle": "My session title"1468 "sessionTitle": "My session title",
1469 "suppressOriginalPrompt": true
1473 }1470 }
1474}1471}
1475```1472```
1476 1473
1474<h4 id="what-a-blocked-prompt-leaves-behind">
1475 Lo que un prompt bloqueado deja atrás
1476</h4>
1477
1478Un prompt bloqueado nunca llega a Claude, pero su texto no se elimina en todas partes. De forma predeterminada, el mensaje de bloqueo mostrado al usuario termina con `Original prompt:` seguido del texto enviado, y Claude Code escribe ese mensaje en el archivo de transcripción de la sesión en el disco. Para dejar el texto fuera del mensaje, imprima JSON con `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Esto funciona si el hook bloquea con `decision: "block"` o saliendo con 2. Un hook de salida 2 que no imprime JSON siempre obtiene el texto del prompt en su mensaje de bloqueo.
1479
1480`suppressOriginalPrompt` cambia solo el mensaje de bloqueo. El texto enviado aún puede aparecer en archivos locales como la transcripción de la sesión y su historial de prompts, por lo que un hook de bloqueo no es una forma de mantener un secreto fuera del disco. Para limitar o eliminar esos archivos, consulte [Almacenamiento de texto plano](/docs/es/claude-directory#plaintext-storage) y [Borrar datos locales](/docs/es/claude-directory#clear-local-data).
1481
1477<h3 id="userpromptexpansion">1482<h3 id="userpromptexpansion">
1478 UserPromptExpansion1483 UserPromptExpansion
1479</h3>1484</h3>
1480 1485
1481Se ejecuta cuando un comando escrito por el usuario se expande en un prompt antes de llegar a Claude. Úselo para bloquear comandos específicos de invocación directa, inyectar contexto para una skill particular o registrar qué comandos invocan los usuarios. Por ejemplo, un hook que coincide con `deploy` puede bloquear `/deploy` a menos que esté presente un archivo de aprobación, o un hook que coincide con una skill de revisión puede agregar la lista de verificación de revisión del equipo como `additionalContext`.1486Se ejecuta cuando un comando escrito por el usuario se expande en un prompt antes de llegar a Claude. Úselo para bloquear comandos específicos de invocación directa, inyectar contexto para un skill particular o registrar qué comandos invocan los usuarios. Por ejemplo, un hook que coincide con `deploy` puede bloquear `/deploy` a menos que esté presente un archivo de aprobación, o un hook que coincide con un skill de revisión puede agregar la lista de verificación de revisión del equipo como `additionalContext`.
1482 1487
1483Este evento cubre la ruta que `PreToolUse` no cubre: un hook `PreToolUse` que coincide con la herramienta `Skill` se dispara solo cuando Claude llama a la herramienta, pero escribir `/skillname` directamente omite `PreToolUse`. `UserPromptExpansion` se dispara en esa ruta directa.1488Este evento cubre la ruta que `PreToolUse` no cubre: un hook `PreToolUse` que coincide con la herramienta `Skill` se dispara solo cuando Claude llama a la herramienta, pero escribir `/skillname` directamente omite `PreToolUse`. `UserPromptExpansion` se dispara en esa ruta directa.
1484 1489
1517| `reason` | Se muestra al usuario cuando `decision` es `"block"` |1522| `reason` | Se muestra al usuario cuando `decision` es `"block"` |
1518| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt expandido. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1523| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt expandido. Consulte [Agregar contexto para Claude](#add-context-for-claude) |
1519 1524
1520Un hook que bloquea al salir con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario.1525Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario.
1521 1526
1522```json theme={null}1527```json theme={null}
1523{1528{
1539Use MessageDisplay para:1544Use MessageDisplay para:
1540 1545
1541* eliminar markdown para una visualización mínima1546* eliminar markdown para una visualización mínima
1542* transformar el texto que una aplicación del SDK del agente muestra a sus usuarios1547* transformar el texto que una aplicación del Agent SDK muestra a sus usuarios
1543* redactar claves API o nombres de host internos de las respuestas de Claude1548* redactar claves API o nombres de host internos de las respuestas de Claude
1544 1549
1545Claude Code retiene cada lote hasta que su hook devuelve, así que mantenga el hook rápido. Si el hook falla o agota el tiempo de espera, Claude Code muestra el texto original. El tiempo de espera predeterminado para este evento es 10 segundos; si su hook necesita más tiempo, establezca el campo `timeout` en la entrada del hook.1550Claude Code retiene cada lote hasta que su hook devuelve, así que mantenga el hook rápido. Si el hook falla o agota el tiempo de espera, Claude Code muestra el texto original. El tiempo de espera predeterminado para este evento es 10 segundos; si su hook necesita más tiempo, establezca el campo `timeout` en la entrada del hook.
1548 1553
1549MessageDisplay no admite matchers y se dispara para cada mensaje del asistente que transmite texto; los mensajes sin texto, como respuestas de solo llamada de herramienta, no lo disparan.1554MessageDisplay no admite matchers y se dispara para cada mensaje del asistente que transmite texto; los mensajes sin texto, como respuestas de solo llamada de herramienta, no lo disparan.
1550 1555
1551En ejecuciones no interactivas, incluidas consultas del SDK del agente y `claude -p`, MessageDisplay se ejecuta una vez por mensaje del asistente en lugar de una vez por lote de líneas. La llamada única llega después de que se completa el mensaje y lleva el texto del mensaje completo: `index` es `0`, `final` es `true`, y `delta` contiene el mensaje completo. Un hook que recopila el texto `delta` para cada mensaje recibe el mismo texto total en ambos modos.1556En ejecuciones no interactivas, incluidas consultas del Agent SDK y `claude -p`, MessageDisplay se ejecuta una vez por mensaje del asistente en lugar de una vez por lote de líneas. La llamada única llega después de que se completa el mensaje y lleva el texto completo del mensaje: `index` es `0`, `final` es `true`, y `delta` contiene el mensaje completo. Un hook que recopila el texto `delta` para cada mensaje recibe el mismo texto total en ambos modos.
1552 1557
1553<h4 id="messagedisplay-input">1558<h4 id="messagedisplay-input">
1554 Entrada de MessageDisplay1559 Entrada de MessageDisplay
1562| `message_id` | UUID del mensaje del asistente que se muestra. Estable en cada lote del mismo mensaje. Este no es el ID `msg_…` de la API, por lo que no se puede correlacionar con IDs de mensajes de transcripción |1567| `message_id` | UUID del mensaje del asistente que se muestra. Estable en cada lote del mismo mensaje. Este no es el ID `msg_…` de la API, por lo que no se puede correlacionar con IDs de mensajes de transcripción |
1563| `index` | Índice basado en cero de este lote dentro del mensaje |1568| `index` | Índice basado en cero de este lote dentro del mensaje |
1564| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |1569| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |
1565| `delta` | Las líneas recién completadas desde el lote anterior, incluidas las saltos de línea finales. Siempre líneas completas, excepto el lote final que puede terminar a mitad de línea. En ejecuciones interactivas, el delta del lote final está vacío cuando el mensaje termina en un salto de línea, así que trate `final`, no un delta no vacío, como la señal de fin de mensaje. En ejecuciones del SDK del agente y `claude -p`, la llamada única lleva el mensaje completo |1570| `delta` | Las líneas recién completadas desde el lote anterior, incluidos los saltos de línea finales. Siempre líneas completas, excepto el lote final que puede terminar a mitad de línea. En ejecuciones interactivas, el delta del lote final está vacío cuando el mensaje termina en un salto de línea, así que trate `final`, no un delta no vacío, como la señal de fin de mensaje. En ejecuciones del Agent SDK y `claude -p`, la llamada única lleva el mensaje completo |
1566 1571
1567```json theme={null}1572```json theme={null}
1568{1573{
1590 1595
1591Los hooks MessageDisplay no tienen control de decisión. No pueden bloquear el mensaje o cambiar lo que se almacena en la transcripción o se envía a Claude. Claude Code actúa sobre `displayContent` de su salida JSON y descarta `systemMessage` y `continue`.1596Los hooks MessageDisplay no tienen control de decisión. No pueden bloquear el mensaje o cambiar lo que se almacena en la transcripción o se envía a Claude. Claude Code actúa sobre `displayContent` de su salida JSON y descarta `systemMessage` y `continue`.
1592 1597
1593Este ejemplo elimina el formato markdown de las respuestas de Claude para una visualización de texto plano. El script lee cada lote de stdin, elimina marcadores en negrita y comillas invertidas de código en línea de `delta`, y devuelve el resultado como `displayContent`.1598Este ejemplo elimina el formato markdown de las respuestas de Claude para una visualización de texto plano. El script lee cada lote de stdin, elimina marcadores en negrita y backticks de código en línea de `delta`, y devuelve el resultado como `displayContent`.
1594 1599
1595<Tabs>1600<Tabs>
1596 <Tab title="macOS/Linux">1601 <Tab title="macOS/Linux">
1649 }1654 }
1650 ```1655 ```
1651 1656
1652 La bandera `-NoProfile` omite cargar su perfil de PowerShell para que el hook se inicie rápido, y `-ExecutionPolicy Bypass` permite que PowerShell ejecute el archivo de script local.1657 La bandera `-NoProfile` omite la carga de su perfil de PowerShell para que el hook se inicie rápido, y `-ExecutionPolicy Bypass` permite que PowerShell ejecute el archivo de script local.
1653 1658
1654 Guarde este script en `.claude/hooks/plain-display.ps1` en su proyecto:1659 Guarde este script en `.claude/hooks/plain-display.ps1` en su proyecto:
1655 1660
1677Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, use [FileChanged](#filechanged) en lugar de hacer coincidir herramientas de edición de archivos por nombre. A diferencia de PreToolUse, Claude Code ejecuta hooks FileChanged después del cambio y no tienen control de decisión, por lo que no pueden bloquear la escritura.1682Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, use [FileChanged](#filechanged) en lugar de hacer coincidir herramientas de edición de archivos por nombre. A diferencia de PreToolUse, Claude Code ejecuta hooks FileChanged después del cambio y no tienen control de decisión, por lo que no pueden bloquear la escritura.
1678 1683
1679<Warning>1684<Warning>
1680 PreToolUse se ejecuta solo cuando Claude llama a una herramienta. Los archivos que [referencia con `@` en su prompt](/docs/es/common-workflows#reference-files-and-directories) se agregan sin ninguna llamada de herramienta: Claude Code inserta su contenido mientras construye el prompt, por lo que ningún hook PreToolUse se dispara para ellos, incluidos hooks que coinciden con `Read`. Para bloquear rutas específicas de referencias `@`, use una [regla de negación `Read`](/docs/es/permissions#read-and-edit) en su lugar.1685 PreToolUse se ejecuta solo cuando Claude llama a una herramienta. Los archivos que [referencia con `@` en su prompt](/docs/es/common-workflows#reference-files-and-directories) se agregan sin ninguna llamada de herramienta: Claude Code inserta su contenido mientras construye el prompt, por lo que ningún hook PreToolUse se dispara para ellos, incluidos los hooks que coinciden con `Read`. Para bloquear rutas específicas de referencias `@`, use una [regla de denegación `Read`](/docs/es/permissions#read-and-edit) en su lugar.
1681 1686
1682 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).1687 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).
1683</Warning>1688</Warning>
1684 1689
1685Use [control de decisión PreToolUse](#pretooluse-decision-control) para permitir, negar, preguntar o diferir la llamada de herramienta.1690Use [control de decisión PreToolUse](#pretooluse-decision-control) para permitir, denegar, preguntar o diferir la llamada de herramienta.
1686 1691
1687Un [hook de devolución de llamada del SDK del agente](/docs/es/agent-sdk/hooks) en `PreToolUse` que excede su tiempo de espera bloquea la llamada de herramienta, y Claude recibe un resultado de error que nombra el tiempo de espera. Una negación explícita devuelta por otro hook aún tiene prioridad.1692Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `PreToolUse` que excede su tiempo de espera bloquea la llamada de herramienta, y Claude recibe un resultado de error que nombra el tiempo de espera. Una denegación explícita devuelta por otro hook aún tiene prioridad.
1688 1693
1689<h4 id="pretooluse-input">1694<h4 id="pretooluse-input">
1690 Entrada de PreToolUse1695 Entrada de PreToolUse
1692 1697
1693Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input`, y `tool_use_id`.1698Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input`, y `tool_use_id`.
1694 1699
1695Para una [herramienta MCP](#match-mcp-tools), la entrada también lleva `mcp_server`, un objeto con el `name` del servidor y un `source` que dice de dónde vino la definición del servidor. Los valores `source` incluyen `plugin`, `sdk`, y alcances de configuración como `user` y `project`. [`McpServerProvenance`](/docs/es/agent-sdk/typescript#mcpserverprovenance) en la referencia del SDK del agente los enumera todos y dice cómo tratar uno que no reconoce. Base las decisiones de confianza en `source` en lugar de en `name` o el prefijo de nombre de herramienta `mcp__<server>__`. El campo `mcp_server` requiere Claude Code v2.1.274 o posterior.1700Para una [herramienta MCP](#match-mcp-tools), la entrada también lleva `mcp_server`, un objeto con el `name` del servidor y un `source` que dice de dónde vino la definición del servidor. Los valores `source` incluyen `plugin`, `sdk`, y alcances de configuración como `user` y `project`. [`McpServerProvenance`](/docs/es/agent-sdk/typescript#mcpserverprovenance) en la referencia del Agent SDK los enumera todos y dice cómo tratar uno que no reconoce. Base las decisiones de confianza en `source` en lugar de en `name` o en el prefijo de nombre de herramienta `mcp__<server>__`. El campo `mcp_server` requiere Claude Code v2.1.274 o posterior.
1696 1701
1697Para las herramientas de archivo `Write`, `Edit`, y `Read`, `tool_input.file_path` siempre es absoluto:1702Para las herramientas de archivo `Write`, `Edit`, y `Read`, `tool_input.file_path` siempre es absoluto:
1698 1703
1744 1749
1745| Campo | Tipo | Ejemplo | Descripción |1750| Campo | Tipo | Ejemplo | Descripción |
1746| :- | :- | :- | :- |1751| :- | :- | :- | :- |
1747| `changedFiles` | array | `["/path/to/src/app.ts"]` | Rutas absolutas de los archivos que el comando cambió, como máximo 200. Presente siempre que `files` contenga un diff o `moreFiles` esté por encima de cero |1752| `changedFiles` | array | `["/path/to/src/app.ts"]` | Rutas absolutas de los archivos que cambió el comando, como máximo 200. Presente siempre que `files` contenga un diff o `moreFiles` esté por encima de cero |
1748| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de hasta 5 archivos cambiados, para visualización. `created` o `deleted` es `true` para un archivo que el comando agregó o eliminó |1753| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de hasta 5 archivos cambiados, para visualización. `created` o `deleted` es `true` para un archivo que el comando agregó o eliminó |
1749| `moreFiles` | number | `2` | Recuento de archivos cambiados sin diff en `files` |1754| `moreFiles` | number | `2` | Recuento de archivos cambiados sin diff en `files` |
1750| `unavailable` | boolean | `true` | Se establece cuando el diff está incompleto o no se pudo tomar |1755| `unavailable` | boolean | `true` | Se establece cuando el diff está incompleto o no se pudo tomar |
1819| Campo | Tipo | Ejemplo | Descripción |1824| Campo | Tipo | Ejemplo | Descripción |
1820| :- | :- | :- | :- |1825| :- | :- | :- | :- |
1821| `pattern` | string | `"**/*.ts"` | Patrón glob para hacer coincidir archivos contra |1826| `pattern` | string | `"**/*.ts"` | Patrón glob para hacer coincidir archivos contra |
1822| `path` | string | `"/path/to/dir"` | Directorio opcional para buscar en. Por defecto es el directorio de trabajo actual |1827| `path` | string | `"/path/to/dir"` | Directorio opcional para buscar. Por defecto es el directorio de trabajo actual |
1823 1828
1824<h5 id="grep">1829<h5 id="grep">
1825 Grep1830 Grep
1876 1881
1877| Campo | Tipo | Ejemplo | Descripción |1882| Campo | Tipo | Ejemplo | Descripción |
1878| :- | :- | :- | :- |1883| :- | :- | :- | :- |
1879| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes en segundo plano. A partir de v2.1.198, los subagentes se ejecutan en segundo plano de forma predeterminada, por lo que un `run_in_background` omitido también produce `"async_launched"` |1884| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes de fondo. A partir de v2.1.198, los subagentes se ejecutan en segundo plano de forma predeterminada, por lo que un `run_in_background` omitido también produce `"async_launched"` |
1880| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para la ejecución del subagente |1885| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para la ejecución del subagente |
1881| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Los bloques de texto finales del subagente, o, para un subagente cuyo informe pasa a través de `SubagentHandback`, una nota breve sobre esa entrega en su lugar |1886| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Los bloques de texto finales del subagente, o, para un subagente cuyo informe pasa a través de `SubagentHandback`, una nota breve sobre esa entrega en su lugar |
1882| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo en el que comenzó el subagente, que puede diferir del modelo solicitado |1887| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo en el que comenzó el subagente, que puede diferir del modelo solicitado |
1883| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos utilizados en orden, con repeticiones consecutivas colapsadas; se establece solo cuando el modelo fue intercambiado a mitad de ejecución. Requiere Claude Code v2.1.212 o posterior |1888| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos utilizados en orden, con repeticiones consecutivas colapsadas; se establece solo cuando el modelo fue intercambiado a mitad de ejecución. Requiere Claude Code v2.1.212 o posterior |
1884| `totalTokens` | number | `12450` | Recuento de tokens de la solicitud final de la API del subagente: tokens de entrada, salida y caché combinados. Esto no es un total en toda la ejecución |1889| `totalTokens` | number | `12450` | Recuento de tokens de la solicitud final de la API del subagente: tokens de entrada, salida y caché combinados. Este no es un total en toda la ejecución |
1885| `totalDurationMs` | number | `48211` | Duración de reloj de pared de la ejecución del subagente |1890| `totalDurationMs` | number | `48211` | Duración de reloj de pared de la ejecución del subagente |
1886| `totalToolUseCount` | number | `7` | Recuento de llamadas de herramienta que hizo el subagente |1891| `totalToolUseCount` | number | `7` | Recuento de llamadas de herramienta que hizo el subagente |
1887| `usage` | object | `{"input_tokens": 8320, ...}` | Desglose de tokens por tipo de la solicitud final de la API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1892| `usage` | object | `{"input_tokens": 8320, ...}` | Desglose de tokens por tipo de la solicitud final de la API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1888 1893
1889En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference), que Claude Code proporciona en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), entrega su informe a través de esa herramienta en lugar de devolverlo como texto. El campo `content` de su resultado `completed` entonces lleva una nota breve sobre esa entrega en lugar del informe en sí. Para leer el informe, coincida un hook `PreToolUse` o `PostToolUse` en `SubagentHandback` y lea `tool_input.message`.1894En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference), que Claude Code proporciona en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), entrega su informe a través de esa herramienta en lugar de devolverlo como texto. El campo `content` de su resultado `completed` entonces lleva una nota breve sobre esa entrega en lugar del informe en sí. Para leer el informe, coincida un hook `PreToolUse` o `PostToolUse` en `SubagentHandback` y lea `tool_input.message`.
1890 1895
1891Para subagentes en segundo plano, la herramienta devuelve cuando la tarea se mueve al segundo plano, por lo que `tool_response` no lleva campos de uso: un lanzamiento en segundo plano devuelve inmediatamente, y una tarea en primer plano que Claude Code pone en segundo plano a mitad de ejecución devuelve en esa transición. Tiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, y `resolvedModel`.1896Para subagentes de fondo, la herramienta devuelve cuando la tarea se mueve al fondo, por lo que `tool_response` no lleva campos de uso: un lanzamiento de fondo devuelve inmediatamente, y una tarea en primer plano que Claude Code pone en segundo plano a mitad de ejecución devuelve en esa transición. Tiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, y `resolvedModel`.
1892 1897
1893En una respuesta `completed`, `resolvedModel` nombra el modelo en el que comenzó el subagente, que puede diferir del valor `model` en `tool_input`, como cuando `availableModels` u otra anulación se aplica. En una respuesta `async_launched`, `resolvedModel` nombra el modelo en uso cuando el agente se movió al segundo plano, por lo que un intercambio que ocurrió antes de pasar al segundo plano se refleja allí. El comportamiento de `modelsUsed` y `resolvedModel` en tiempo de fondo requiere Claude Code v2.1.212 o posterior.1898En una respuesta `completed`, `resolvedModel` nombra el modelo en el que comenzó el subagente, que puede diferir del valor `model` en `tool_input`, como cuando `availableModels` u otra anulación se aplica. En una respuesta `async_launched`, `resolvedModel` nombra el modelo en uso cuando el agente se movió al fondo, por lo que un intercambio que ocurrió antes de pasar al fondo se refleja allí. `modelsUsed` y el comportamiento de `resolvedModel` en el momento de pasar al fondo requieren Claude Code v2.1.212 o posterior.
1894 1899
1895<a id="askuserquestion" />1900<a id="askuserquestion" />
1896 1901
1909 ExitPlanMode1914 ExitPlanMode
1910</h5>1915</h5>
1911 1916
1912Presenta un plan y pide al usuario que lo apruebe antes de que Claude salga del [modo plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escribe el plan en un archivo en el disco antes de llamar a la herramienta, por lo que la entrada `tool_input` literal del modelo es típicamente vacía. Claude Code inyecta el contenido del plan y la ruta del archivo antes de pasar la entrada a los hooks.1917Presenta un plan y pide al usuario que lo apruebe antes de que Claude salga del [modo de plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escribe el plan en un archivo en el disco antes de llamar a la herramienta, por lo que la entrada literal `tool_input` del modelo es típicamente vacía. Claude Code inyecta el contenido del plan y la ruta del archivo antes de pasar la entrada a los hooks.
1913 1918
1914| Campo | Tipo | Ejemplo | Descripción |1919| Campo | Tipo | Ejemplo | Descripción |
1915| :- | :- | :- | :- |1920| :- | :- | :- | :- |
1916| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenido del plan en Markdown. Inyectado desde el archivo del plan en el disco |1921| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenido del plan en Markdown. Inyectado desde el archivo del plan en el disco |
1917| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Inyectado |1922| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Inyectado |
1918| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecado. Claude Code acepta el campo pero lo ignora. Antes de v2.1.205, llevaba permisos basados en prompts que Claude solicitó para implementar el plan |1923| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecado. Claude Code acepta el campo pero lo ignora. Antes de v2.1.205, llevaba permisos basados en prompts que Claude solicitó implementar el plan |
1919 1924
1920En `PostToolUse`, `tool_response` es un objeto con campos `plan` y `filePath` que contienen el plan aprobado, más banderas de estado internas. Lea `tool_response.plan` para el contenido del plan en lugar de releer el archivo del disco.1925En `PostToolUse`, `tool_response` es un objeto con campos `plan` y `filePath` que contienen el plan aprobado, más banderas de estado internas. Lea `tool_response.plan` para el contenido del plan en lugar de releer el archivo del disco.
1921 1926
1923 Control de decisión de PreToolUse1928 Control de decisión de PreToolUse
1924</h4>1929</h4>
1925 1930
1926Los hooks `PreToolUse` pueden controlar si procede una llamada de herramienta. 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, negar, preguntar o diferir) más la capacidad de modificar la entrada de herramienta antes de la ejecución.1931Los hooks `PreToolUse` pueden controlar si procede una llamada de herramienta. 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 control más rico: cuatro resultados (permitir, denegar, preguntar o diferir) más la capacidad de modificar la entrada de herramienta antes de la ejecución.
1927 1932
1928| Campo | Descripción |1933| Campo | Descripción |
1929| :- | :- |1934| :- | :- |
1930| `permissionDecision` | `"allow"` omite el aviso de permiso, excepto para las [acciones que ningún modo auto-aprueba](/docs/es/permission-modes#actions-no-mode-auto-approves) y para `AskUserQuestion` y `ExitPlanMode`, que necesitan [`updatedInput` emparejado con él](#allow-with-updatedinput). `"deny"` evita la llamada de herramienta. `"ask"` solicita al usuario que confirme. `"defer"` sale correctamente para que la herramienta pueda reanudarse más tarde. Las [reglas de negación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan independientemente de lo que devuelva el hook |1935| `permissionDecision` | `"allow"` omite el prompt de permiso, excepto para las [acciones que ningún modo auto-aprueba](/docs/es/permission-modes#actions-no-mode-auto-approves) y para `AskUserQuestion` y `ExitPlanMode`, que necesitan [`updatedInput` emparejado con él](#allow-with-updatedinput). `"deny"` evita la llamada de herramienta. `"ask"` solicita al usuario que confirme. `"defer"` sale correctamente para que la herramienta pueda reanudarse más tarde. Las [reglas de denegación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan independientemente de lo que devuelva el hook |
1931| `permissionDecisionReason` | Para `"ask"`, se muestra al usuario pero no a Claude. Para `"deny"`, se muestra a Claude. Para `"allow"` y `"defer"`, se escribe en el [registro de depuración](#debug-hooks) solo |1936| `permissionDecisionReason` | Para `"ask"`, se muestra al usuario pero no a Claude. Para `"deny"`, se muestra a Claude. Para `"allow"` y `"defer"`, se escribe en el [registro de depuración](#debug-hooks) solo |
1932| `updatedInput` | Modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluya campos sin cambios junto con los modificados. Claude Code evalúa reglas de permiso y la [elegibilidad de fondo automático](/docs/es/tools-reference#background-commands) de un comando Bash contra la entrada que devuelve su hook, no la entrada que envió Claude. Combine con `"allow"` para auto-aprobar, o `"ask"` para mostrar la entrada modificada al usuario. Para `"defer"`, se ignora |1937| `updatedInput` | Modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluya campos sin cambios junto con los modificados. Claude Code evalúa reglas de permiso y la [elegibilidad de ejecución en segundo plano](/docs/es/tools-reference#background-commands) de un comando Bash contra la entrada que devuelve su hook, no la entrada que envió Claude. Combine con `"allow"` para auto-aprobar, o `"ask"` para mostrar la entrada modificada al usuario. Para `"defer"`, se ignora |
1933| `additionalContext` | Cadena agregada al contexto de Claude junto con el resultado de la herramienta. Se ignora cuando `permissionDecision` es `"defer"`. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1938| `additionalContext` | Cadena agregada al contexto de Claude junto con el resultado de la herramienta. Se ignora cuando `permissionDecision` es `"defer"`. Consulte [Agregar contexto para Claude](#add-context-for-claude) |
1934 1939
1935Cuando múltiples hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.1940Cuando múltiples hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.
1936 1941
1937Un hook que bloquea al salir con 2 se enruta de la misma manera que `"deny"`: Claude ve el mensaje stderr como la razón de la negación.1942Un hook que bloquea saliendo con 2 se enruta de la misma manera que `"deny"`: Claude ve el mensaje stderr como la razón de la denegación.
1938 1943
1939Cuando un hook devuelve `"ask"`, el aviso de permiso mostrado al usuario incluye una etiqueta que identifica de dónde vino el hook: `[settings]` para un hook de cualquier archivo de configuración o del frontmatter del agente, `[plugin:<name>]` para el hook de un plugin, o `[skill]` para un hook del frontmatter de skill. Esto ayuda a los usuarios a entender qué fuente de configuración está solicitando confirmación.1944Cuando un hook devuelve `"ask"`, el prompt de permiso mostrado al usuario incluye una etiqueta que identifica de dónde vino el hook: `[settings]` para un hook de cualquier archivo de configuración o del frontmatter del agente, `[plugin:<name>]` para el hook de un plugin, o `[skill]` para un hook del frontmatter de skill. Esto ayuda a los usuarios a entender qué fuente de configuración está solicitando confirmación.
1940 1945
1941Un `"ask"` de un hook también fuerza un aviso de permiso en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): el clasificador aún puede negar la llamada de herramienta, pero no puede aprobar la llamada silenciosamente. Antes de v2.1.211, el clasificador podría aprobar un comando Bash ejecutándose fuera del [sandbox](/docs/es/sandboxing) sin mostrar el aviso que solicitó el hook; el clasificador aún aplicaba sus propias reglas de seguridad a ese comando, y una negación de hook `"deny"` siempre se honraba.1946Un `"ask"` de un hook también fuerza un prompt de permiso en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): el clasificador aún puede denegar la llamada de herramienta, pero no puede aprobar la llamada silenciosamente. Antes de v2.1.211, el clasificador podría aprobar un comando Bash ejecutándose fuera del [sandbox](/docs/es/sandboxing) sin mostrar el prompt que solicitó el hook; el clasificador aún aplicaba sus propias reglas de seguridad a ese comando, y una denegación de hook `"deny"` siempre se honraba.
1942 1947
1943```json theme={null}1948```json theme={null}
1944{1949{
1956 1961
1957<span id="allow-with-updatedinput" />1962<span id="allow-with-updatedinput" />
1958 1963
1959En [modo no interactivo](/docs/es/headless) con la bandera `-p`, Claude Code ofrece `AskUserQuestion` y `ExitPlanMode` solo cuando la ejecución tiene un [anfitrión de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs) para recibir el aviso, como una devolución de llamada `canUseTool` del SDK del agente. Estas herramientas requieren interacción del usuario. Devolver `permissionDecision: "allow"` junto con `updatedInput` satisface ese requisito: el hook lee la entrada de la herramienta de stdin, recopila la respuesta a través de su propia interfaz de usuario, y la devuelve en `updatedInput` para que la herramienta se ejecute sin solicitar. Devolver `"allow"` solo no es suficiente para estas herramientas. Para `AskUserQuestion`, devuelva la matriz `questions` original y agregue un objeto [`answers`](#askuserquestion) que asigne el texto de cada pregunta a la respuesta elegida.1964En [modo no interactivo](/docs/es/headless) con la bandera `-p`, Claude Code ofrece `AskUserQuestion` y `ExitPlanMode` solo cuando la ejecución tiene un [host de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs) para recibir el prompt, como un callback `canUseTool` del Agent SDK. Estas herramientas requieren interacción del usuario. Devolver `permissionDecision: "allow"` junto con `updatedInput` satisface ese requisito: el hook lee la entrada de la herramienta de stdin, recopila la respuesta a través de su propia interfaz de usuario, y la devuelve en `updatedInput` para que la herramienta se ejecute sin solicitar. Devolver `"allow"` solo no es suficiente para estas herramientas. Para `AskUserQuestion`, devuelva la matriz `questions` original y agregue un objeto [`answers`](#askuserquestion) que asigne el texto de cada pregunta a la respuesta elegida.
1960 1965
1961A partir de v2.1.199, una herramienta MCP cuyo servidor la marca con [`_meta["anthropic/requiresUserInteraction"]`](/docs/es/mcp#require-approval-for-a-specific-tool) es más estricta: un hook no puede omitir su aviso de aprobación con `"allow"`, con o sin `updatedInput`, porque Claude Code no puede confirmar que el hook recopiló la interacción que la herramienta necesita.1966A partir de v2.1.199, una herramienta MCP cuyo servidor la marca con [`_meta["anthropic/requiresUserInteraction"]`](/docs/es/mcp#require-approval-for-a-specific-tool) es más estricta: un hook no puede omitir su prompt de aprobación con `"allow"`, con o sin `updatedInput`, porque Claude Code no puede confirmar que el hook recopiló la interacción que la herramienta necesita.
1962 1967
1963<Note>1968<Note>
1964 PreToolUse anteriormente usaba campos `decision` y `reason` de nivel superior, pero estos están deprecados para este evento. Use `hookSpecificOutput.permissionDecision` y `hookSpecificOutput.permissionDecisionReason` en su lugar. Los valores deprecados `"approve"` y `"block"` se asignan a `"allow"` y `"deny"` respectivamente. Otros eventos como PostToolUse y Stop continúan usando `decision` y `reason` de nivel superior como su formato actual.1969 PreToolUse previamente usaba campos `decision` y `reason` de nivel superior, pero estos están deprecados para este evento. Use `hookSpecificOutput.permissionDecision` y `hookSpecificOutput.permissionDecisionReason` en su lugar. Los valores deprecados `"approve"` y `"block"` se asignan a `"allow"` y `"deny"` respectivamente. Otros eventos como PostToolUse y Stop continúan usando `decision` y `reason` de nivel superior como su formato actual.
1965</Note>1970</Note>
1966 1971
1967<h4 id="defer-a-tool-call-for-later">1972<h4 id="defer-a-tool-call-for-later">
1968 Diferir una llamada de herramienta para más tarde1973 Diferir una llamada de herramienta para más tarde
1969</h4>1974</h4>
1970 1975
1971`"defer"` es para integraciones que ejecutan `claude -p` como un subproceso y leen su salida JSON, como una aplicación del SDK del agente o una interfaz de usuario personalizada construida sobre Claude Code. Permite que ese proceso de llamada pause Claude en una llamada de herramienta, recopile entrada a través de su propia interfaz, y reanude donde se quedó. Claude Code honra este valor solo en [modo no interactivo](/docs/es/headless) con la bandera `-p`. En sesiones interactivas registra una advertencia e ignora el resultado del hook.1976`"defer"` es para integraciones que ejecutan `claude -p` como un subproceso y leen su salida JSON, como una aplicación del Agent SDK o una interfaz de usuario personalizada construida sobre Claude Code. Permite que ese proceso de llamada pause Claude en una llamada de herramienta, recopile entrada a través de su propia interfaz, y reanude donde se quedó. Claude Code honra este valor solo en [modo no interactivo](/docs/es/headless) con la bandera `-p`. En sesiones interactivas registra una advertencia e ignora el resultado del hook.
1972 1977
1973La herramienta `AskUserQuestion` es el caso típico: Claude quiere hacer una pregunta al usuario, pero no hay terminal para responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [anfitrión de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasa con `--permission-prompt-tool`, así que inicie la ejecución con una. El viaje de ida y vuelta funciona así:1978La herramienta `AskUserQuestion` es el caso típico: Claude quiere hacer una pregunta al usuario, pero no hay terminal para responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [host de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasa con `--permission-prompt-tool`, así que inicie la ejecución con una. El viaje de ida y vuelta funciona así:
1974 1979
19751. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.19801. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.
19762. El hook devuelve `permissionDecision: "defer"`. La herramienta no se ejecuta. El proceso sale con `stop_reason: "tool_deferred"` y la llamada de herramienta pendiente preservada en la transcripción.19812. El hook devuelve `permissionDecision: "defer"`. La herramienta no se ejecuta. El proceso sale con `stop_reason: "tool_deferred"` y la llamada de herramienta pendiente preservada en la transcripción.
19773. El proceso de llamada lee `deferred_tool_use` del resultado del SDK, muestra la pregunta en su propia interfaz de usuario, y espera una respuesta.19823. El proceso de llamada lee `deferred_tool_use` del resultado del SDK, muestra la pregunta en su propia interfaz de usuario, y espera una respuesta.
19784. El proceso de llamada ejecuta `claude -p --resume <session-id>` con el mismo anfitrión de permiso. Se dispara la misma llamada de herramienta `PreToolUse` nuevamente.19834. El proceso de llamada ejecuta `claude -p --resume <session-id>` con el mismo host de permiso. Se dispara la misma llamada de herramienta `PreToolUse` nuevamente.
19795. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.19845. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.
1980 1985
1981El campo `deferred_tool_use` lleva el `id`, `name`, e `input` de la herramienta. El `input` son los parámetros que Claude generó para la llamada de herramienta, capturados antes de la ejecución:1986El campo `deferred_tool_use` lleva el `id`, `name`, e `input` de la herramienta. El `input` son los parámetros que Claude generó para la llamada de herramienta, capturados antes de la ejecución:
2001Si la herramienta diferida ya no está disponible cuando reanuda, el proceso sale con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de que se dispare el hook. Esto sucede cuando un servidor MCP que proporcionó la herramienta no está conectado para la sesión reanudada. La carga `deferred_tool_use` aún se incluye para que pueda identificar qué herramienta desapareció.2006Si la herramienta diferida ya no está disponible cuando reanuda, el proceso sale con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de que se dispare el hook. Esto sucede cuando un servidor MCP que proporcionó la herramienta no está conectado para la sesión reanudada. La carga `deferred_tool_use` aún se incluye para que pueda identificar qué herramienta desapareció.
2002 2007
2003<Note>2008<Note>
2004 Para reanudar una sesión diferida en modo plan, pase [`--permission-prompt-tool`](/docs/es/cli-reference#cli-flags) junto con `--resume` para que Claude Code pueda presentar el plan para aprobación. Si pasa ciertos otros indicadores de inicio, la ejecución reanudada no vuelve al modo plan; consulte [Reanudar en modo plan con `-p`](/docs/es/sessions#resume-in-plan-mode-with-p). Requiere Claude Code v2.1.246 o posterior.2009 Para reanudar una sesión diferida en modo de plan, pase [`--permission-prompt-tool`](/docs/es/cli-reference#cli-flags) junto con `--resume` para que Claude Code pueda presentar el plan para aprobación. Si pasa ciertas otras banderas de inicio, la ejecución reanudada no vuelve al modo de plan; consulte [Reanudar en modo de plan con `-p`](/docs/es/sessions#resume-in-plan-mode-with-p). Requiere Claude Code v2.1.246 o posterior.
2005 2010
2006 Cuando reanuda con `-p`, Claude Code no restaura ningún otro modo de permiso almacenado. Inicia la ejecución en el modo de permiso que una nueva ejecución `claude -p` iniciaría, así que pase `--permission-mode` o `--dangerously-skip-permissions` nuevamente si la sesión diferida usó una. Cuando reanuda con `claude --resume <session-id>` sin `-p`, Claude Code restaura el modo de permiso almacenado, con las excepciones enumeradas en [modo de permiso en reanudar](/docs/es/sessions#permission-mode-on-resume).2011 Cuando reanuda con `-p`, Claude Code no restaura ningún otro modo de permiso almacenado. Inicia la ejecución en el modo de permiso que una nueva ejecución `claude -p` iniciaría, así que pase `--permission-mode` o `--dangerously-skip-permissions` nuevamente si la sesión diferida usó uno. Cuando reanuda con `claude --resume <session-id>` sin `-p`, Claude Code restaura el modo de permiso almacenado, con las excepciones enumeradas en [modo de permiso en reanudar](/docs/es/sessions#permission-mode-on-resume).
2007</Note>2012</Note>
2008 2013
2009<h3 id="permissionrequest">2014<h3 id="permissionrequest">
2010 PermissionRequest2015 PermissionRequest
2011</h3>2016</h3>
2012 2017
2013Se ejecuta cuando Claude Code está a punto de pedirle permiso para usar una herramienta. En sesiones que no pueden mostrar un aviso, como subagentes en segundo plano en [modo no interactivo](/docs/es/headless), Claude Code aún ejecuta estos hooks, y si ningún hook devuelve una decisión, niega la llamada de herramienta.2018Se ejecuta cuando Claude Code está a punto de pedirle permiso para usar una herramienta. En sesiones que no pueden mostrar un prompt, como subagentes de fondo en [modo no interactivo](/docs/es/headless), Claude Code aún ejecuta estos hooks, y si ningún hook devuelve una decisión, niega la llamada de herramienta.
2014Use [control de decisión PermissionRequest](#permissionrequest-decision-control) para permitir o negar en nombre del usuario.2019Use [control de decisión PermissionRequest](#permissionrequest-decision-control) para permitir o denegar en nombre del usuario.
2015 2020
2016Use este evento cuando necesite una señal en el momento en que Claude solicita permiso para usar una herramienta. Claude Code ejecuta un hook [Notification](#notification) con el tipo `permission_prompt` solo después de que el aviso ha esperado aproximadamente seis segundos.2021Use este evento cuando necesite una señal en el momento en que Claude solicita permiso para usar una herramienta. Claude Code ejecuta un hook [Notification](#notification) con el tipo `permission_prompt` solo después de que el prompt haya esperado aproximadamente seis segundos.
2017 2022
2018Claude Code no ejecuta hooks PermissionRequest para la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox. Para obtener una señal para ese aviso, use el tipo de notificación `permission_prompt`.2023Claude Code no ejecuta hooks PermissionRequest para la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox. Para obtener una señal para ese prompt, use el tipo de notificación `permission_prompt`.
2019 2024
2020Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2025Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.
2021 2026
2056 Control de decisión de PermissionRequest2061 Control de decisión de PermissionRequest
2057</h4>2062</h4>
2058 2063
2059Los hooks `PermissionRequest` pueden permitir o negar solicitudes de permiso. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver un objeto `decision` con estos campos específicos del evento:2064Los hooks `PermissionRequest` pueden permitir o denegar solicitudes de permiso. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver un objeto `decision` con estos campos específicos del evento:
2060 2065
2061| Campo | Descripción |2066| Campo | Descripción |
2062| :- | :- |2067| :- | :- |
2063| `behavior` | `"allow"` otorga el permiso, `"deny"` lo niega. Las [reglas de negación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan, por lo que un hook que devuelve `"allow"` no anula una regla de negación coincidente |2068| `behavior` | `"allow"` otorga el permiso, `"deny"` lo niega. Las [reglas de denegación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan, por lo que un hook que devuelve `"allow"` no anula una regla de denegación coincidente |
2064| `updatedInput` | Para `"allow"` solo: modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluya campos sin cambios junto con los modificados. La entrada modificada se re-evalúa contra reglas de negación y pregunta |2069| `updatedInput` | Para `"allow"` solo: modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluya campos sin cambios junto con los modificados. La entrada modificada se re-evalúa contra reglas de denegación y pregunta |
2065| `updatedPermissions` | Para `"allow"` solo: matriz de [entradas de actualización de permiso](#permission-update-entries) a aplicar, como agregar una regla de permiso o cambiar el modo de permiso de la sesión |2070| `updatedPermissions` | Para `"allow"` solo: matriz de [entradas de actualización de permiso](#permission-update-entries) a aplicar, como agregar una regla de permiso o cambiar el modo de permiso de la sesión |
2066| `message` | Para `"deny"` solo: dice a Claude por qué se negó el permiso |2071| `message` | Para `"deny"` solo: dice a Claude por qué se negó el permiso |
2067| `interrupt` | Para `"deny"` solo: si es `true`, detiene a Claude |2072| `interrupt` | Para `"deny"` solo: si es `true`, detiene a Claude |
2098| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |2103| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |
2099 2104
2100<Note>2105<Note>
2101 `setMode` con `bypassPermissions` solo tiene efecto si inició la sesión con modo de omisión ya disponible: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, o `permissions.defaultMode: "bypassPermissions"` en [configuración de usuario, `--settings`, o administrada](/docs/es/settings-reference#permissions-defaultmode). De lo contrario, la actualización es una no-op. La actualización también es una no-op cuando [`permissions.disableBypassPermissionsMode`](/docs/es/permissions#managed-settings) deshabilita el modo, o cuando la sesión comienza en [modo restringido](/docs/es/cli-reference#cli-flags).2106 `setMode` con `bypassPermissions` solo tiene efecto si inició la sesión con modo de bypass ya disponible: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions`, o `permissions.defaultMode: "bypassPermissions"` en [configuración de usuario, `--settings`, o configuración administrada](/docs/es/settings-reference#permissions-defaultmode). De lo contrario, la actualización es una no-op. La actualización también es una no-op cuando [`permissions.disableBypassPermissionsMode`](/docs/es/permissions#managed-settings) deshabilita el modo, o cuando la sesión comienza en [modo restringido](/docs/es/cli-reference#cli-flags).
2102 2107
2103 `bypassPermissions` nunca se persiste como `defaultMode` independientemente de `destination`.2108 `bypassPermissions` nunca se persiste como `defaultMode` independientemente de `destination`.
2104</Note>2109</Note>
2112| `projectSettings` | `.claude/settings.json` |2117| `projectSettings` | `.claude/settings.json` |
2113| `userSettings` | `~/.claude/settings.json` |2118| `userSettings` | `~/.claude/settings.json` |
2114 2119
2115Un hook puede devolver una de las `permission_suggestions` que recibió como su propia salida `updatedPermissions`.2120Un hook puede hacer eco de una de las `permission_suggestions` que recibió como su propia salida `updatedPermissions`.
2116 2121
2117<h3 id="posttooluse">2122<h3 id="posttooluse">
2118 PostToolUse2123 PostToolUse
2131 Entrada de PostToolUse2136 Entrada de PostToolUse
2132</h4>2137</h4>
2133 2138
2134Los hooks `PostToolUse` se disparan después de que una herramienta ya se ha ejecutado exitosamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto para ambos depende de la herramienta. Las rutas `tool_input` de herramientas de archivo llegan en el mismo formato que para [PreToolUse](#pretooluse-input): siempre absolutas, con los separadores nativos de la plataforma, así que barras invertidas en Windows. Para una herramienta MCP, la entrada también lleva el objeto [`mcp_server`](#pretooluse-input).2139Los hooks `PostToolUse` se disparan después de que una herramienta ya se ha ejecutado exitosamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto para ambos depende de la herramienta. Las rutas `tool_input` de herramientas de archivo llegan en el mismo formato que para [PreToolUse](#pretooluse-input): siempre absoluto, con los separadores nativos de la plataforma, así que barras invertidas en Windows. Para una herramienta MCP, la entrada también lleva el objeto [`mcp_server`](#pretooluse-input).
2135 2140
2136```json theme={null}2141```json theme={null}
2137{2142{
2156 2161
2157| Campo | Descripción |2162| Campo | Descripción |
2158| :- | :- |2163| :- | :- |
2159| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a avisos de permiso y hooks PreToolUse |2164| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a prompts de permiso y hooks PreToolUse |
2160 2165
2161<h4 id="posttooluse-decision-control">2166<h4 id="posttooluse-decision-control">
2162 Control de decisión de PostToolUse2167 Control de decisión de PostToolUse
2215 2220
2216Cuánto peso da el clasificador a la nota depende de dónde configuró el hook:2221Cuánto peso da el clasificador a la nota depende de dónde configuró el hook:
2217 2222
2218* **Hooks configurados en Claude Code**: para hooks de archivos de configuración, plugins, skills y frontmatter del agente, el clasificador trata la nota como contexto no verificado proporcionado por la aplicación. La nota nunca establece intención del usuario, y si afirma que aprobó o solicitó algo, el clasificador verifica esa afirmación contra sus propios mensajes en la conversación2223* **Hooks configurados en Claude Code**: para hooks de archivos de configuración, plugins, skills y frontmatter del agente, el clasificador trata la nota como contexto no verificado proporcionado por la aplicación. La nota nunca establece intención del usuario, y si afirma que usted aprobó o solicitó algo, el clasificador verifica esa afirmación contra sus propios mensajes en la conversación
2219* **Devoluciones de llamada del SDK del agente en proceso**: cuando una aplicación que integra Claude Code registra el hook como una [devolución de llamada del SDK de TypeScript](/docs/es/agent-sdk/hooks) y devuelve la nota durante la sesión en vivo, el clasificador puede pesar una declaración del usuario retransmitida en la nota como intención del usuario. Tal declaración puede satisfacer un requisito de consentimiento que el clasificador aceptaría de un mensaje que envía, pero nunca levanta un bloqueo que su propio mensaje tampoco podría levantar. Después de que se reanuda una sesión, Claude Code trata las notas restauradas como contexto no verificado. Cuando hooks de ambos grupos anotan la misma llamada, el clasificador trata la nota combinada como no verificada2224* **Callbacks del Agent SDK en proceso**: cuando una aplicación que integra Claude Code registra el hook como un [callback del SDK de TypeScript](/docs/es/agent-sdk/hooks) y devuelve la nota durante la sesión en vivo, el clasificador puede pesar una declaración del usuario retransmitida en la nota como intención del usuario. Tal declaración puede satisfacer un requisito de consentimiento que el clasificador aceptaría de un mensaje que envía, pero nunca levanta un bloqueo que su propio mensaje tampoco pudiera levantar. Después de que se reanuda una sesión, Claude Code trata las notas restauradas como contexto no verificado. Cuando hooks de ambos grupos anotan la misma llamada, el clasificador trata la nota combinada como no verificada
2220 2225
2221Claude Code aplica estos límites al entregar la nota:2226Claude Code aplica estos límites al entregar la nota:
2222 2227
2223* **Longitud**: Claude Code limita las notas para una llamada de herramienta a 2,000 caracteres y trunca el resto. El límite se comparte en cada hook que responde a esa llamada2228* **Longitud**: Claude Code limita las notas para una llamada de herramienta a 2,000 caracteres y trunca el resto. El límite se comparte en cada hook que responde a esa llamada
2224* **Solo respuestas sincrónicas**: Claude Code ignora el campo en la respuesta de un hook que [se ejecuta en segundo plano](#run-hooks-in-the-background), porque esa respuesta llega después de que Claude Code registra el resultado de la herramienta2229* **Solo respuestas sincrónicas**: Claude Code ignora el campo en la respuesta de un hook que [se ejecuta en segundo plano](#run-hooks-in-the-background), porque esa respuesta llega después de que Claude Code registra el resultado de la herramienta
2225* **Llamadas que el clasificador no registra**: la transcripción del clasificador omite búsquedas de solo lectura como lecturas de archivo y búsquedas. Claude Code descarta una nota adjunta a una de esas llamadas2230* **Llamadas que el clasificador no registra**: la transcripción del clasificador omite búsquedas de solo lectura como lecturas de archivo y búsquedas. Claude Code descarta una nota adjunta a una de esas llamadas
2226* **Interacción con reescrituras**: cuando la nota describe salida que está reemplazando con `updatedToolOutput`, devuelva ambos campos en la misma respuesta del hook. Claude Code descarta la nota si esa reescritura se rechaza u otra reescritura del hook la reemplaza. Claude Code entrega una nota que devuelve sin una reescritura incluso cuando otro hook reescribe la salida2231* **Interacción con reescrituras**: cuando la nota describe salida que está reemplazando con `updatedToolOutput`, devuelva ambos campos en la misma respuesta del hook. Claude Code descarta la nota si esa reescritura se rechaza u otro reemplazo del hook la reemplaza. Claude Code entrega una nota que devuelve sin una reescritura incluso cuando otro hook reescribe la salida
2227 2232
2228<Warning>2233<Warning>
2229 El clasificador lee contenido que coloca en `classifierContext` como información del anfitrión de la aplicación de la sesión, así que no copie salida de herramientas no confiables o texto de terceros en él. Mantenga la nota a una afirmación breve sobre esta única llamada, como un hecho sobre su origen o una declaración del usuario sobre ella; no use el campo para entregar mensajes no relacionados o un flujo de eventos.2234 El clasificador lee contenido que coloca en `classifierContext` como información del anfitrión de la aplicación que aloja la sesión, así que no copie salida de herramientas no confiables o texto de terceros en él. Mantenga la nota a una afirmación breve sobre esta única llamada, como un hecho sobre su origen o una declaración del usuario sobre ella; no use el campo para entregar mensajes no relacionados o un flujo de eventos.
2230</Warning>2235</Warning>
2231 2236
2232<h3 id="posttoolusefailure">2237<h3 id="posttoolusefailure">
2238Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2243Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.
2239 2244
2240<Note>2245<Note>
2241 Este evento no se dispara para llamadas de herramienta rechazadas antes de la ejecución: un nombre de herramienta desconocido, entrada que falla en validación de esquema o específica de herramienta, o una negación de permiso. Los rechazos de validación se devuelven como resultados `tool_use_error` y ocurren antes de que se ejecuten los hooks, por lo que no disparan ni `PreToolUse` ni `PostToolUseFailure`. Las negaciones de permiso disparan `PreToolUse` pero no este evento; consulte [PermissionDenied](#permissiondenied).2246 Este evento no se dispara para llamadas de herramienta rechazadas antes de la ejecución: un nombre de herramienta desconocido, entrada que falla en validación de esquema o específica de herramienta, o una denegación de permiso. Los rechazos de validación se devuelven como resultados `tool_use_error` y ocurren antes de que se ejecuten los hooks, por lo que no disparan ni `PreToolUse` ni `PostToolUseFailure`. Las denegaciones de permiso disparan `PreToolUse` pero no este evento; consulte [PermissionDenied](#permissiondenied).
2242</Note>2247</Note>
2243 2248
2244<h4 id="posttoolusefailure-input">2249<h4 id="posttoolusefailure-input">
2270| :- | :- |2275| :- | :- |
2271| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |2276| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |
2272| `is_interrupt` | Booleano opcional. Verdadero cuando el fallo llegó a Claude Code como una interrupción en lugar de como un error que reportó la herramienta. Cancelar una herramienta en ejecución no dispara este hook; el resultado de la herramienta lleva el mensaje de interrupción en su lugar |2277| `is_interrupt` | Booleano opcional. Verdadero cuando el fallo llegó a Claude Code como una interrupción en lugar de como un error que reportó la herramienta. Cancelar una herramienta en ejecución no dispara este hook; el resultado de la herramienta lleva el mensaje de interrupción en su lugar |
2273| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a avisos de permiso y hooks PreToolUse |2278| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a prompts de permiso y hooks PreToolUse |
2274 2279
2275La cadena `error` es generalmente el mismo texto que Claude recibe como resultado de la herramienta fallida. Su formato varía según la herramienta y el fallo. Clave su hook en `tool_name`, `is_interrupt`, y la primera línea `Exit code N`; trate el resto de la cadena como texto de visualización, no como un formato estable.2280La cadena `error` es generalmente el mismo texto que Claude recibe como resultado de la herramienta fallida. Su formato varía según la herramienta y el fallo. Clave su hook en `tool_name`, `is_interrupt`, y la primera línea `Exit code N`; trate el resto de la cadena como texto de visualización, no como un formato estable.
2276 2281
2277* Para Bash y PowerShell, un comando que se ejecutó y salió produce una primera línea `Exit code N`, luego cualquier salida que el comando produjo como un bloque con stdout y stderr intercalados2282* Para Bash y PowerShell, un comando que se ejecutó y salió produce una primera línea `Exit code N`, luego cualquier salida que el comando produjo como un bloque con stdout y stderr intercalados
2278* Una carga también puede llevar un mensaje de fallo desnudo sin línea de código de salida, cuando Claude Code no pudo iniciar el proceso de shell en sí2283* Una carga también puede llevar un mensaje de fallo desnudo sin línea de código de salida, cuando Claude Code no pudo iniciar el proceso de shell en sí
2279* Claude Code trunca a mitad de cadenas largas alrededor de un marcador `... [N characters truncated] ...`, e puede insertar líneas propias, como `Command timed out after 2m 0s`2284* Claude Code trunca en el medio cadenas largas alrededor de un marcador `... [N characters truncated] ...`, e puede insertar líneas propias, como `Command timed out after 2m 0s`
2280 2285
2281<h4 id="posttoolusefailure-decision-control">2286<h4 id="posttoolusefailure-decision-control">
2282 Control de decisión de PostToolUseFailure2287 Control de decisión de PostToolUseFailure
2301 PostToolBatch2306 PostToolBatch
2302</h3>2307</h3>
2303 2308
2304Se ejecuta una vez después de que cada llamada de herramienta en un lote se haya resuelto, antes de que Claude Code envíe la siguiente solicitud al modelo. `PostToolUse` se dispara una vez por herramienta, lo que significa que se dispara concurrentemente cuando Claude hace llamadas de herramienta paralelas. `PostToolBatch` se dispara exactamente una vez con el lote completo, por lo que es el lugar correcto para inyectar contexto que dependa del conjunto de herramientas que se ejecutaron en lugar de en cualquier herramienta única. No hay matcher para este evento.2309Se ejecuta una vez después de que cada llamada de herramienta en un lote se haya resuelto, antes de que Claude Code envíe la siguiente solicitud al modelo. `PostToolUse` se dispara una vez por herramienta, lo que significa que se dispara simultáneamente cuando Claude hace llamadas de herramienta paralelas. `PostToolBatch` se dispara exactamente una vez con el lote completo, por lo que es el lugar correcto para inyectar contexto que depende del conjunto de herramientas que se ejecutaron en lugar de en cualquier herramienta única. No hay matcher para este evento.
2305 2310
2306<h4 id="posttoolbatch-input">2311<h4 id="posttoolbatch-input">
2307 Entrada de PostToolBatch2312 Entrada de PostToolBatch
2333}2338}
2334```2339```
2335 2340
2336`tool_response` contiene el mismo contenido que el modelo recibe en el bloque `tool_result` correspondiente. El valor es una cadena serializada o matriz de bloques de contenido, exactamente como la herramienta la emitió. Para `Read`, eso significa texto con prefijo de número de línea en lugar de contenidos de archivo sin procesar. Las respuestas pueden ser grandes, así que analice solo los campos que necesita.2341`tool_response` contiene el mismo contenido que el modelo recibe en el bloque `tool_result` correspondiente. El valor es una cadena serializada o matriz de bloques de contenido, exactamente como lo emitió la herramienta. Para `Read`, eso significa texto con prefijo de número de línea en lugar de contenidos de archivo sin procesar. Las respuestas pueden ser grandes, así que analice solo los campos que necesita.
2337 2342
2338<Note>2343<Note>
2339 La forma `tool_response` difiere de la de `PostToolUse`. `PostToolUse` pasa el objeto `Output` estructurado de la herramienta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` pasa el contenido `tool_result` serializado que el modelo ve.2344 La forma `tool_response` difiere de la de `PostToolUse`. `PostToolUse` pasa el objeto `Output` estructurado de la herramienta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` pasa el contenido `tool_result` serializado que ve el modelo.
2340</Note>2345</Note>
2341 2346
2342<h4 id="posttoolbatch-decision-control">2347<h4 id="posttoolbatch-decision-control">
2364 PermissionDenied2369 PermissionDenied
2365</h3>2370</h3>
2366 2371
2367Se ejecuta cuando [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) niega una llamada de herramienta, incluido cuando niega sin un veredicto del clasificador porque [una verificación de seguridad separada del modo automático rechazó la solicitud del clasificador](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action) o su respuesta no se analizó. Este hook solo se dispara en modo automático: no se ejecuta cuando niega manualmente un diálogo de permiso, cuando un hook `PreToolUse` bloquea una llamada, o cuando una regla `deny` coincide. Úselo para registrar negaciones, ajustar configuración o decirle al modelo que puede reintentar la llamada de herramienta.2372Se ejecuta cuando [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) niega una llamada de herramienta, incluido cuando niega sin un veredicto del clasificador porque [una verificación de seguridad separada del modo automático rechazó la propia solicitud del clasificador](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action) o su respuesta no se analizó. Este hook solo se dispara en modo automático: no se ejecuta cuando niega manualmente un diálogo de permiso, cuando un hook `PreToolUse` bloquea una llamada, o cuando una regla `deny` coincide. Úselo para registrar denegaciones, ajustar configuración o decirle al modelo que puede reintentar la llamada de herramienta.
2368 2373
2369Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2374Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.
2370 2375
2393 2398
2394| Campo | Descripción |2399| Campo | Descripción |
2395| :- | :- |2400| :- | :- |
2396| `reason` | La razón de la negación. Para un veredicto del clasificador, en la mayoría de sesiones nombra la regla coincidente entre corchetes, como `[Data Exfiltration]`; consulte [Revisar negaciones](/docs/es/auto-mode-config#review-denials) para las otras formas. Para una [negación sin veredicto](#permissiondenied-decision-control), comienza con `Auto mode could not evaluate this action and is blocking it for safety`. Para una negación porque el modelo del clasificador no estaba disponible, es el texto fijo `Classifier unavailable` |2401| `reason` | La razón de la denegación. Para un veredicto del clasificador, en la mayoría de sesiones nombra la regla coincidente entre corchetes, como `[Data Exfiltration]`; consulte [Revisar denegaciones](/docs/es/auto-mode-config#review-denials) para las otras formas. Para una [denegación sin veredicto](#permissiondenied-decision-control), comienza con `Auto mode could not evaluate this action and is blocking it for safety`. Para una denegación porque el modelo del clasificador no estaba disponible, es el texto fijo `Classifier unavailable` |
2397 2402
2398<h4 id="permissiondenied-decision-control">2403<h4 id="permissiondenied-decision-control">
2399 Control de decisión de PermissionDenied2404 Control de decisión de PermissionDenied
2400</h4>2405</h4>
2401 2406
2402Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta negada. Devuelva un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:2407Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta denegada. Devuelva un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:
2403 2408
2404```json theme={null}2409```json theme={null}
2405{2410{
2410}2415}
2411```2416```
2412 2417
2413Cuando `retry` es `true`, Claude Code agrega un mensaje a la conversación diciéndole al modelo que puede reintentar la llamada de herramienta. Claude Code no revierte la negación en sí. Si su hook no devuelve JSON, o devuelve `retry: false`, la negación se mantiene y el modelo recibe el mensaje de rechazo original.2418Cuando `retry` es `true`, Claude Code agrega un mensaje a la conversación diciéndole al modelo que puede reintentar la llamada de herramienta. Claude Code no revierte la denegación en sí. Si su hook no devuelve JSON, o devuelve `retry: false`, la denegación se mantiene y el modelo recibe el mensaje de rechazo original.
2414 2419
2415Claude Code ignora `retry: true` cuando el clasificador produjo [sin veredicto en la acción](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action): su respuesta no se analizó, o una verificación de seguridad separada del modo automático rechazó la solicitud del clasificador. Para esas negaciones, Claude Code ya le dice al modelo en el mensaje de rechazo si debe reintentar más tarde o continuar.2420Claude Code ignora `retry: true` cuando el clasificador produjo [ningún veredicto sobre la acción](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action): su respuesta no se analizó, o una verificación de seguridad separada del modo automático rechazó la propia solicitud del clasificador. Para esas denegaciones, Claude Code ya le dice al modelo en el mensaje de rechazo si reintentar más tarde o continuar.
2416 2421
2417<h3 id="notification">2422<h3 id="notification">
2418 Notification2423 Notification
2424 2429
2425| Matcher | Cuándo se dispara |2430| Matcher | Cuándo se dispara |
2426| :- | :- |2431| :- | :- |
2427| `permission_prompt` | Claude necesita su permiso para usar una herramienta o una [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox, y el aviso ha esperado aproximadamente seis segundos |2432| `permission_prompt` | Claude necesita su permiso para usar una herramienta o una [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox, y el prompt ha esperado aproximadamente seis segundos |
2428| `idle_prompt` | Claude terminó de responder hace aproximadamente 60 segundos y no ha escrito desde entonces |2433| `idle_prompt` | Claude terminó de responder hace aproximadamente 60 segundos y no ha escrito desde entonces |
2429| `auth_success` | La autenticación se completa |2434| `auth_success` | La autenticación se completa |
2430| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no ha escrito durante aproximadamente seis segundos |2435| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no ha escrito durante aproximadamente seis segundos |
2431| `elicitation_url_dialog` | Un servidor MCP le pide que abra una URL de navegador y no ha escrito durante aproximadamente seis segundos |2436| `elicitation_url_dialog` | Un servidor MCP le pide que abra una URL de navegador y no ha escrito durante aproximadamente seis segundos |
2432| `elicitation_complete` | Un servidor MCP reporta que una [elicitación de modo URL](#elicitation-input) está completa |2437| `elicitation_complete` | Un servidor MCP reporta que una [elicitación de modo URL](#elicitation-input) está completa |
2433| `elicitation_response` | Se envía una respuesta de elicitación de MCP de vuelta al servidor |2438| `elicitation_response` | Se envía una respuesta de elicitación de MCP de vuelta al servidor |
2434| `agent_needs_input` | Una sesión en segundo plano comienza a esperar su entrada mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal, o la sesión actual le hace una pregunta de configuración de terminal de un [compañero de equipo del equipo del agente](/docs/es/agent-teams#choose-a-display-mode) y no ha escrito durante aproximadamente seis segundos |2439| `agent_needs_input` | Una sesión de fondo comienza a esperar su entrada mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal. También se dispara cuando una sesión de terminal le muestra una [pregunta de configuración de terminal de un compañero de equipo de agente](/docs/es/agent-teams#choose-a-display-mode) o el aviso del modo automático sobre [cargos de solicitud del clasificador](/docs/es/auto-mode-classifier-billing) y no ha escrito durante aproximadamente seis segundos |
2435| `agent_completed` | Una sesión en segundo plano termina o falla. Se dispara solo mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal |2440| `agent_completed` | Una sesión de fondo termina o falla. Se dispara solo mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal |
2436| `quota_auto_resume_fired` | Claude Code continúa su tarea después de que un límite de uso de claude.ai la pausó: en el reinicio, o antes cuando algo que hace en Claude Code durante la espera, como agregar créditos de uso, actualizar su plan o cambiar modelos, hace que el uso esté disponible nuevamente, con la [excepción de configuración de modelo](/docs/es/interactive-mode#wait-for-a-usage-limit-to-reset) |2441| `quota_auto_resume_fired` | Claude Code continúa su tarea después de que un límite de uso de claude.ai la pausó: en el reinicio, o antes cuando algo que hace en Claude Code durante la espera, como agregar créditos de uso, actualizar su plan o cambiar modelos, hace que el uso esté disponible nuevamente, con la [excepción de configuración de modelo](/docs/es/interactive-mode#wait-for-a-usage-limit-to-reset) |
2437| `quota_auto_resume_stale` | Un límite de uso de claude.ai se reinició mientras su computadora dormía durante más de aproximadamente 30 minutos. Claude Code espera a que presione `Enter` en lugar de continuar. Después de un sueño más corto continúa y dispara `quota_auto_resume_fired` en su lugar |2442| `quota_auto_resume_stale` | Un límite de uso de claude.ai se reinició mientras su computadora dormía más de aproximadamente 30 minutos. Claude Code espera a que presione `Enter` en lugar de continuar. Después de un sueño más corto continúa y se dispara `quota_auto_resume_fired` en su lugar |
2438| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar su tarea: [`autoContinueAtUsageLimit`](/docs/es/settings-reference#autocontinueatusagelimit) se desactivó o el reinicio se movió más de 24 horas durante una espera que Claude Code comenzó por sí solo, la tarea continuada siguió golpeando el límite, o la continuación fue bloqueada antes de llegar al modelo. No se dispara cuando presiona `Esc` o `Ctrl+C`, o elige **No continuar automáticamente** |2443| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar su tarea: [`autoContinueAtUsageLimit`](/docs/es/settings-reference#autocontinueatusagelimit) se desactivó o el reinicio se movió más de 24 horas en el futuro durante una espera que Claude Code comenzó por sí solo, la tarea continuada siguió golpeando el límite, o la continuación fue bloqueada antes de llegar al modelo. No se dispara cuando presiona `Esc` o `Ctrl+C`, o elige **No continuar automáticamente** |
2439 2444
2440Los tipos `agent_needs_input` y `agent_completed` requieren Claude Code v2.1.198 o posterior.2445Los tipos `agent_needs_input` y `agent_completed` requieren Claude Code v2.1.198 o posterior.
2441 2446
2448<Note>2453<Note>
2449 Los tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog`, y `elicitation_url_dialog` comparten su tiempo con notificaciones de escritorio, por lo que en sesiones de terminal solo los ve cuando parece que está lejos de la terminal:2454 Los tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog`, y `elicitation_url_dialog` comparten su tiempo con notificaciones de escritorio, por lo que en sesiones de terminal solo los ve cuando parece que está lejos de la terminal:
2450 2455
2451 * Espere `permission_prompt` una vez que no haya escrito durante aproximadamente seis segundos. El temporizador comienza cuando aparece el aviso de permiso, y cada pulsación de tecla lo difiere. Para ejecutar un hook inmediatamente cuando Claude solicita permiso para usar una herramienta, use [PermissionRequest](#permissionrequest) en su lugar.2456 * Espere `permission_prompt` una vez que no haya escrito durante aproximadamente seis segundos. El temporizador comienza cuando aparece el prompt de permiso, y cada pulsación de tecla lo difiere. Para ejecutar un hook inmediatamente cuando Claude solicita permiso para usar una herramienta, use [PermissionRequest](#permissionrequest) en su lugar.
2452 * Espere `idle_prompt` aproximadamente 60 segundos después de que Claude termine de responder, y solo si no ha escrito desde entonces. Claude Code no envía `idle_prompt` mientras espera a que se reinicie un límite de uso de claude.ai. Cuando la espera termina por sí sola, uno de los tipos `quota_auto_resume_*` se dispara en su lugar.2457 * Espere `idle_prompt` aproximadamente 60 segundos después de que Claude termine de responder, y solo si no ha escrito desde entonces. Claude Code no envía `idle_prompt` mientras espera a que se reinicie un límite de uso de claude.ai. Cuando la espera termina por sí sola, uno de los tipos `quota_auto_resume_*` se dispara en su lugar.
2453 * Espere `elicitation_dialog` para un formulario de elicitación, o `elicitation_url_dialog` para una solicitud de URL de navegador, una vez que no haya escrito durante aproximadamente seis segundos. Ambos comparten la misma puerta de seis segundos que `permission_prompt`: el temporizador comienza cuando aparece el diálogo, y cada pulsación de tecla lo difiere.2458 * Espere `elicitation_dialog` para un formulario de elicitación, o `elicitation_url_dialog` para una solicitud de URL de navegador, una vez que no haya escrito durante aproximadamente seis segundos. Ambos comparten la misma puerta de seis segundos que `permission_prompt`: el temporizador comienza cuando aparece el diálogo, y cada pulsación de tecla lo difiere.
2454 2459
2455 Una solicitud de permiso o elicitación que llega mientras otro diálogo está en pantalla mantiene la misma puerta de seis segundos, cronometrada desde cuando llega la solicitud. Su notificación puede llegar a usted mientras la solicitud aún espera detrás del diálogo abierto.2460 Una solicitud de permiso o elicitación que llega mientras otro diálogo está en pantalla mantiene la misma puerta de seis segundos, cronometrada desde cuando llega la solicitud. Su notificación puede llegar a usted mientras la solicitud aún espera detrás del diálogo abierto.
2456</Note>2461</Note>
2457 2462
2458Claude Code cronometra `permission_prompt` diferente en sesiones donde envía solicitudes de permiso a la devolución de llamada [`canUseTool`](/docs/es/agent-sdk/user-input) del SDK del agente, que es cómo Claude Desktop y la extensión VS Code alojan Claude Code:2463Claude Code cronometra `permission_prompt` diferente en sesiones donde envía solicitudes de permiso al callback [`canUseTool`](/docs/es/agent-sdk/user-input) del Agent SDK, que es cómo Claude Desktop y la extensión VS Code alojan Claude Code:
2459 2464
2460* Espere `permission_prompt` aproximadamente seis segundos después de que Claude solicite permiso. Claude Code no lo difiere mientras escribe.2465* Espere `permission_prompt` aproximadamente seis segundos después de que Claude solicita permiso. Claude Code no lo difiere mientras escribe.
2461* Si usted o un hook [PermissionRequest](#permissionrequest) responden antes, Claude Code no ejecuta `permission_prompt`.2466* Si usted o un hook [PermissionRequest](#permissionrequest) responden antes, Claude Code no ejecuta `permission_prompt`.
2462* Establezca [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.2467* Establezca [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.
2463 2468
2510}2515}
2511```2516```
2512 2517
2513Los hooks Notification no pueden bloquear o modificar notificaciones. Claude Code descarta sus campos `systemMessage` y `continue` pero aún emite [`terminalSequence`](#emit-terminal-notifications), que es en lo que se basa el ejemplo de notificación de escritorio. Los hooks Notification están destinados a efectos secundarios como reenviar la notificación a un servicio externo.2518Los hooks Notification no pueden bloquear o modificar notificaciones. Claude Code descarta sus campos `systemMessage` y `continue` pero aún emite [`terminalSequence`](#emit-terminal-notifications), en el que se basa el ejemplo de notificación de escritorio. Los hooks Notification están destinados a efectos secundarios como reenviar la notificación a un servicio externo.
2514 2519
2515<h3 id="subagentstart">2520<h3 id="subagentstart">
2516 SubagentStart2521 SubagentStart
2517</h3>2522</h3>
2518 2523
2519Se ejecuta cuando Claude genera un subagente con la herramienta Agent, cuando Claude [reanuda un subagente](/docs/es/sub-agents#resume-subagents), y cada vez que un [equipo del agente](/docs/es/agent-teams) compañero en proceso maneja un nuevo mensaje. Admite matchers para filtrar por nombre de tipo de agente. Para agentes integrados, este es el nombre del agente como `general-purpose`, `Explore`, o `Plan`. Para [subagentes personalizados](/docs/es/sub-agents), este es el campo `name` del frontmatter del agente, no el nombre del archivo.2524Se ejecuta cuando Claude genera un subagente con la herramienta Agent, cuando Claude [reanuda un subagente](/docs/es/sub-agents#resume-subagents), y cada vez que un compañero de [equipo de agente](/docs/es/agent-teams) en proceso maneja un nuevo mensaje. Admite matchers para filtrar por nombre de tipo de agente. Para agentes integrados, este es el nombre del agente como `general-purpose`, `Explore`, o `Plan`. Para [subagentes personalizados](/docs/es/sub-agents), este es el campo `name` del frontmatter del agente, no el nombre del archivo.
2520 2525
2521Para subagentes enviados por un [plugin](/docs/es/plugins/overview), el tipo de agente es el identificador con alcance de plugin como `my-plugin:reviewer`, no el nombre de frontmatter desnudo. Los dos puntos colocan un nombre con alcance de plugin en la ruta de expresión regular, así que ancle el matcher con `^` y `$` para una coincidencia exacta: `^my-plugin:reviewer$`.2526Para subagentes enviados por un [plugin](/docs/es/plugins/overview), el tipo de agente es el identificador con alcance de plugin como `my-plugin:reviewer`, no el nombre de frontmatter desnudo. Los dos puntos colocan un nombre con alcance de plugin en la ruta de expresión regular, así que ancle el matcher con `^` y `$` para una coincidencia exacta: `^my-plugin:reviewer$`.
2522 2527
2537}2542}
2538```2543```
2539 2544
2540Los hooks SubagentStart no pueden bloquear la creación del subagente, pero pueden inyectar contexto en el subagente. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puede devolver:2545Los hooks SubagentStart no pueden bloquear la creación de subagentes, pero pueden inyectar contexto en el subagente. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puede devolver:
2541 2546
2542| Campo | Descripción |2547| Campo | Descripción |
2543| :- | :- |2548| :- | :- |
2566 2571
2567Además de los [campos de entrada comunes](#common-input-fields), los hooks SubagentStop reciben `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, y `last_assistant_message`. El campo `agent_type` es el valor utilizado para filtrado de matcher. El `transcript_path` es la transcripción de la sesión principal, mientras que `agent_transcript_path` es la transcripción propia del subagente almacenada en una carpeta `subagents/` anidada. El campo `last_assistant_message` contiene el contenido de texto de la respuesta final del subagente, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción.2572Además de los [campos de entrada comunes](#common-input-fields), los hooks SubagentStop reciben `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, y `last_assistant_message`. El campo `agent_type` es el valor utilizado para filtrado de matcher. El `transcript_path` es la transcripción de la sesión principal, mientras que `agent_transcript_path` es la transcripción propia del subagente almacenada en una carpeta `subagents/` anidada. El campo `last_assistant_message` contiene el contenido de texto de la respuesta final del subagente, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción.
2568 2573
2569No todos los eventos SubagentStop provienen de un subagente que Claude generó. Claude Code también ejecuta agentes internos para algunas de sus propias características, como [sugerencias de prompt](/docs/es/interactive-mode#prompt-suggestions) y [preguntas secundarias `/btw`](/docs/es/interactive-mode#side-questions-with-%2Fbtw), y SubagentStop se dispara cuando uno de esos termina también. Para esos eventos, `agent_type` es el nombre del agente que la sesión en sí ejecuta, como uno establecido con [`--agent`](/docs/es/cli-reference#cli-flags) o la configuración [`agent`](/docs/es/settings-reference#agent), y una cadena vacía cuando la sesión se ejecuta sin uno.2574No cada evento SubagentStop proviene de un subagente que Claude generó. Claude Code también ejecuta agentes internos para algunas de sus propias características, como [sugerencias de prompt](/docs/es/interactive-mode#prompt-suggestions) y [preguntas secundarias `/btw`](/docs/es/interactive-mode#side-questions-with-%2Fbtw), y SubagentStop se dispara cuando uno de esos termina también. Para esos eventos, `agent_type` es el nombre del agente que la sesión en sí ejecuta, como uno establecido con [`--agent`](/docs/es/cli-reference#cli-flags) o la configuración [`agent`](/docs/es/settings-reference#agent), y una cadena vacía cuando la sesión se ejecuta sin uno.
2570 2575
2571Un `matcher` que nombra tipos de agente no coincide con un `agent_type` vacío. Un hook cuyo matcher está omitido, `""`, o `"*"`, o es una expresión regular que coincide con una cadena vacía, se ejecuta para eventos con un `agent_type` vacío también.2576Un `matcher` que nombra tipos de agentes no coincide con un `agent_type` vacío. Un hook cuyo matcher está omitido, `""`, o `"*"`, o es una expresión regular que coincide con una cadena vacía, se ejecuta para eventos con un `agent_type` vacío también.
2572 2577
2573En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference) entrega su informe a través de esa herramienta antes de que se detenga. El campo `last_assistant_message` entonces contiene el texto de cierre del subagente, si lo hay, que no es el informe entregado. El informe es la entrada `message` de esa llamada, que un hook `PreToolUse` o `PostToolUse` que coincide en `SubagentHandback` recibe como `tool_input.message`.2578En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference) entrega su informe a través de esa herramienta antes de que se detenga. El campo `last_assistant_message` entonces contiene el texto de cierre del subagente, si lo hay, que no es el informe entregado. El informe es la entrada `message` de esa llamada, que un hook `PreToolUse` o `PostToolUse` que coincide en `SubagentHandback` recibe como `tool_input.message`.
2574 2579
2575Los hooks SubagentStop también reciben las matrices `background_tasks` y `session_crons` descritas en [entrada de Stop](#stop-input). Ambas matrices tienen alcance a la sesión padre, no al subagente.2580Los hooks SubagentStop también reciben las matrices `background_tasks` y `session_crons` descritas en [entrada de Stop](#stop-input). Ambas matrices están limitadas a la sesión padre, no al subagente.
2576 2581
2577```json theme={null}2582```json theme={null}
2578{2583{
2591}2596}
2592```2597```
2593 2598
2594Los hooks SubagentStop usan el mismo formato de control de decisión que [hooks Stop](#stop-decision-control), incluido `hookSpecificOutput.additionalContext` con `hookEventName` establecido en `"SubagentStop"`, para retroalimentación sin error que mantiene el subagente ejecutándose. Devolver `decision: "block"` con un `reason` mantiene el subagente ejecutándose y entrega `reason` al subagente como su siguiente instrucción. Un hook que bloquea al salir con 2 entrega su mensaje stderr de la misma manera. Para inyectar contexto en la sesión padre después de que un subagente devuelve, use un hook [`PostToolUse`](#posttooluse) en la herramienta `Agent` en su lugar.2599Los hooks SubagentStop usan el mismo formato de control de decisión que [hooks Stop](#stop-decision-control), incluido `hookSpecificOutput.additionalContext` con `hookEventName` establecido en `"SubagentStop"`, para retroalimentación sin error que mantiene el subagente ejecutándose. Devolver `decision: "block"` con un `reason` mantiene el subagente ejecutándose y entrega `reason` al subagente como su siguiente instrucción. Un hook que bloquea saliendo con 2 entrega su mensaje stderr de la misma manera. Para inyectar contexto en la sesión padre después de que un subagente devuelve, use un hook [`PostToolUse`](#posttooluse) en la herramienta `Agent` en su lugar.
2595 2600
2596<h3 id="taskcreated">2601<h3 id="taskcreated">
2597 TaskCreated2602 TaskCreated
2626| `task_id` | Identificador de la tarea que se está creando |2631| `task_id` | Identificador de la tarea que se está creando |
2627| `task_subject` | Título de la tarea |2632| `task_subject` | Título de la tarea |
2628| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2633| `task_description` | Descripción detallada de la tarea. Puede estar ausente |
2629| `teammate_name` | Nombre del compañero que crea la tarea. Puede estar ausente |2634| `teammate_name` | Nombre del compañero que está creando la tarea. Puede estar ausente |
2630| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2635| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |
2631 2636
2632<h4 id="taskcreated-decision-control">2637<h4 id="taskcreated-decision-control">
2657 TaskCompleted2662 TaskCompleted
2658</h3>2663</h3>
2659 2664
2660Se ejecuta cuando una tarea se está marcando como completada. Esto se dispara en dos situaciones: cuando cualquier agente marca explícitamente una tarea como completada a través de la herramienta TaskUpdate, o cuando un [equipo del agente](/docs/es/agent-teams) compañero termina su turno con tareas en progreso. Úselo para hacer cumplir criterios de finalización como pasar pruebas o verificaciones de lint antes de que una tarea pueda cerrarse.2665Se ejecuta cuando se está marcando una tarea como completada. Esto se dispara en dos situaciones: cuando cualquier agente marca explícitamente una tarea como completada a través de la herramienta TaskUpdate, o cuando un compañero de [equipo de agente](/docs/es/agent-teams) termina su turno con tareas en progreso. Úselo para hacer cumplir criterios de finalización como pasar pruebas o verificaciones de lint antes de que una tarea pueda cerrarse.
2661 2666
2662Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.2667Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.
2663 2668
2687| `task_id` | Identificador de la tarea que se está completando |2692| `task_id` | Identificador de la tarea que se está completando |
2688| `task_subject` | Título de la tarea |2693| `task_subject` | Título de la tarea |
2689| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2694| `task_description` | Descripción detallada de la tarea. Puede estar ausente |
2690| `teammate_name` | Nombre del compañero que completa la tarea. Puede estar ausente |2695| `teammate_name` | Nombre del compañero que está completando la tarea. Puede estar ausente |
2691| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2696| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |
2692 2697
2693<h4 id="taskcompleted-decision-control">2698<h4 id="taskcompleted-decision-control">
2697Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:2702Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:
2698 2703
2699* **Código de salida 2**: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.2704* **Código de salida 2**: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.
2700* **JSON `{"continue": false, "stopReason": "..."}`**: cuando un compañero que termina su turno disparó el evento, detiene completamente al compañero, coincidiendo con el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario. Cuando la herramienta `TaskUpdate` disparó el evento, Claude Code ignora `continue: false`; el código de salida 2 aún bloquea la finalización.2705* **JSON `{"continue": false, "stopReason": "..."}`**: cuando un compañero que termina su turno disparó el evento, detiene completamente al compañero, coincidiendo con el comportamiento del hook Stop. El `stopReason` se muestra al usuario. Cuando la herramienta `TaskUpdate` disparó el evento, Claude Code ignora `continue: false`; el código de salida 2 aún bloquea la finalización.
2701 2706
2702Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:2707Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:
2703 2708
2731 2736
2732Además de los [campos de entrada comunes](#common-input-fields), los hooks Stop reciben `stop_hook_active`, `last_assistant_message`, `background_tasks`, y `session_crons`. El campo `stop_hook_active` es `true` cuando Claude Code ya está continuando como resultado de un hook de parada. Verifique este valor o procese la transcripción para evitar bloquear en una condición que nunca se resolverá. Claude Code aplica un límite de 8 continuaciones consecutivas: después de que los hooks de parada hayan continuado el turno ocho veces seguidas, Claude Code anula el siguiente bloqueo y termina el turno. Para aumentar el límite, establezca [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/es/env-vars).2737Además de los [campos de entrada comunes](#common-input-fields), los hooks Stop reciben `stop_hook_active`, `last_assistant_message`, `background_tasks`, y `session_crons`. El campo `stop_hook_active` es `true` cuando Claude Code ya está continuando como resultado de un hook de parada. Verifique este valor o procese la transcripción para evitar bloquear en una condición que nunca se resolverá. Claude Code aplica un límite de 8 continuaciones consecutivas: después de que los hooks de parada hayan continuado el turno ocho veces seguidas, Claude Code anula el siguiente bloqueo y termina el turno. Para aumentar el límite, establezca [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/es/env-vars).
2733 2738
2734El campo `last_assistant_message` contiene el contenido de texto de la respuesta final de Claude, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción. Para hooks que actúan en el turno recién completado, como hooks de lectura en voz alta o notificación, use este campo en lugar de leer `transcript_path`: el archivo de transcripción no se garantiza que incluya el mensaje final en el tiempo de Stop en todas las versiones.2739El campo `last_assistant_message` contiene el contenido de texto de la respuesta final de Claude, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción. Para hooks que actúan en el turno recién completado, como hooks de lectura en voz alta o notificación, use este campo en lugar de leer `transcript_path`: el archivo de transcripción no se garantiza que incluya el mensaje final en el momento de Stop en todas las versiones.
2735 2740
2736Las matrices `background_tasks` y `session_crons` permiten a los hooks distinguir "sesión terminada" de "sesión pausada esperando que el trabajo de fondo la despierte". Ambas matrices están presentes cuando el registro de tareas es alcanzable y están vacías cuando nada está en vuelo o programado.2741Las matrices `background_tasks` y `session_crons` permiten a los hooks distinguir "sesión terminada" de "sesión pausada esperando que el trabajo de fondo la despierte". Ambas matrices están presentes cuando el registro de tareas es alcanzable y están vacías cuando nada está en vuelo o programado.
2737 2742
2798| Campo | Descripción |2803| Campo | Descripción |
2799| :- | :- |2804| :- | :- |
2800| `decision` | `"block"` evita que Claude se detenga. Omita para permitir que Claude se detenga |2805| `decision` | `"block"` evita que Claude se detenga. Omita para permitir que Claude se detenga |
2801| `reason` | Requerido cuando `decision` es `"block"`. Le dice a Claude por qué debe continuar |2806| `reason` | Requerido cuando `decision` es `"block"`. Le dice a Claude por qué debería continuar |
2802| `hookSpecificOutput.additionalContext` | Retroalimentación sin error para Claude. La conversación continúa para que Claude pueda actuar sobre ella, pero a diferencia de `decision: "block"` se muestra en la transcripción como retroalimentación de hook en lugar de un error de hook |2807| `hookSpecificOutput.additionalContext` | Retroalimentación sin error para Claude. La conversación continúa para que Claude pueda actuar sobre ella, pero a diferencia de `decision: "block"` se muestra en la transcripción como retroalimentación de hook en lugar de un error de hook |
2803 2808
2804Un hook que bloquea al salir con 2 se enruta de la misma manera que `reason`: Claude recibe el mensaje stderr como la explicación de por qué debe continuar.2809Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: Claude recibe el mensaje stderr como la explicación de por qué debería continuar.
2805 2810
2806```json theme={null}2811```json theme={null}
2807{2812{
2810}2815}
2811```2816```
2812 2817
2813Use `additionalContext` cuando el hook está funcionando como se diseñó y dando orientación a Claude, como "ejecutar el conjunto de pruebas antes de terminar". Mantiene la conversación a través de las mismas protecciones de bucle que `decision: "block"`, es decir, la entrada `stop_hook_active` y el límite de 8 continuaciones consecutivas, pero la transcripción la etiqueta como `Stop hook feedback` y no se muestra ninguna notificación de error de hook:2818Use `additionalContext` cuando el hook está funcionando como se diseñó y dando orientación a Claude, como "ejecutar el conjunto de pruebas antes de terminar". Mantiene la conversación a través de las mismas protecciones de bucle que `decision: "block"`, a saber la entrada `stop_hook_active` y el límite de 8 continuaciones consecutivas, pero la transcripción la etiqueta como `Stop hook feedback` y no se muestra notificación de error de hook:
2814 2819
2815```json theme={null}2820```json theme={null}
2816{2821{
2831 Entrada de StopFailure2836 Entrada de StopFailure
2832</h4>2837</h4>
2833 2838
2834Además de los [campos de entrada comunes](#common-input-fields), los hooks StopFailure reciben `error`, `error_details` opcional, y `last_assistant_message` opcional. El campo `error` identifica el tipo de error y se utiliza para filtrado de matcher.2839Además de los [campos de entrada comunes](#common-input-fields), los hooks StopFailure reciben `error`, `error_details` opcional, y `last_assistant_message` opcional. El campo `error` identifica el tipo de error y se usa para filtrado de matcher.
2835 2840
2836| Campo | Descripción |2841| Campo | Descripción |
2837| :- | :- |2842| :- | :- |
2857 TeammateIdle2862 TeammateIdle
2858</h3>2863</h3>
2859 2864
2860Se ejecuta cuando un [equipo del agente](/docs/es/agent-teams) compañero está a punto de quedarse inactivo después de terminar su turno. Úselo para hacer cumplir puertas de calidad antes de que un compañero deje de trabajar, como requerir verificaciones de lint aprobadas o verificar que existan archivos de salida.2865Se ejecuta cuando un compañero de [equipo de agente](/docs/es/agent-teams) está a punto de quedarse inactivo después de terminar su turno. Úselo para hacer cumplir puertas de calidad antes de que un compañero deje de trabajar, como requerir verificaciones de lint aprobadas o verificar que existan archivos de salida.
2861 2866
2862Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.2867Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.
2863 2868
2891Los hooks TeammateIdle admiten dos formas de controlar el comportamiento del compañero:2896Los hooks TeammateIdle admiten dos formas de controlar el comportamiento del compañero:
2892 2897
2893* **Código de salida 2**: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.2898* **Código de salida 2**: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.
2894* **JSON `{"continue": false, "stopReason": "..."}`**: detiene completamente al compañero, coincidiendo con el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario.2899* **JSON `{"continue": false, "stopReason": "..."}`**: detiene completamente al compañero, coincidiendo con el comportamiento del hook Stop. El `stopReason` se muestra al usuario.
2895 2900
2896Este ejemplo verifica que exista un artefacto de compilación antes de permitir que un compañero se quede inactivo:2901Este ejemplo verifica que exista un artefacto de compilación antes de permitir que un compañero se quede inactivo:
2897 2902
2910 ConfigChange2915 ConfigChange
2911</h3>2916</h3>
2912 2917
2913Se ejecuta cuando un archivo de configuración cambia durante una sesión. Úselo para auditar cambios de configuración, hacer cumplir políticas de seguridad o bloquear modificaciones no autorizadas en archivos de configuración.2918Se ejecuta cuando un archivo de configuración cambia durante una sesión. Úselo para auditar cambios de configuración, hacer cumplir políticas de seguridad o bloquear modificaciones no autorizadas a archivos de configuración.
2914 2919
2915Claude Code ejecuta hooks ConfigChange cuando un archivo de configuración, un archivo de política administrada o un archivo de skill cambia. Para política administrada, solo los ejecuta cuando `managed-settings.json` o un archivo en `managed-settings.d/` cambia. Aplica [configuración administrada por servidor](/docs/es/server-managed-settings) y cambios en preferencias administradas de macOS o política de registro de Windows sin ejecutarlos. En WSL con [`wslInheritsWindowsSettings`](/docs/es/settings-reference#wslinheritswindowssettings), también aplica un archivo de configuración administrada de Windows modificado en su sondeo de política sin ejecutarlos.2920Claude Code ejecuta hooks ConfigChange cuando un archivo de configuración, un archivo de política administrada o un archivo de skill cambia. Para política administrada, solo los ejecuta cuando `managed-settings.json` o un archivo en `managed-settings.d/` cambia. Aplica [configuración administrada por servidor](/docs/es/server-managed-settings) y cambios a preferencias administradas de macOS o política de registro de Windows sin ejecutarlos. En WSL con [`wslInheritsWindowsSettings`](/docs/es/settings-reference#wslinheritswindowssettings), también aplica un archivo de configuración administrada de Windows modificado en su sondeo de política sin ejecutarlos.
2916 2921
2917El matcher filtra en la fuente de configuración:2922El matcher filtra en la fuente de configuración:
2918 2923
2965 Control de decisión de ConfigChange2970 Control de decisión de ConfigChange
2966</h4>2971</h4>
2967 2972
2968Los hooks ConfigChange pueden bloquear cambios de configuración para que no tengan efecto. Use código de salida 2 o un JSON `decision` para evitar el cambio. Cuando se bloquea, la nueva configuración no se aplica a la sesión en ejecución.2973Los hooks ConfigChange pueden bloquear cambios de configuración para que no surtan efecto. Use código de salida 2 o un JSON `decision` para evitar el cambio. Cuando se bloquea, la nueva configuración no se aplica a la sesión en ejecución.
2969 2974
2970| Campo | Descripción |2975| Campo | Descripción |
2971| :- | :- |2976| :- | :- |
2972| `decision` | `"block"` evita que se aplique el cambio de configuración. Omita para permitir el cambio |2977| `decision` | `"block"` evita que el cambio de configuración se aplique. Omita para permitir el cambio |
2973| `reason` | Aceptado pero nunca mostrado |2978| `reason` | Aceptado pero nunca mostrado |
2974 2979
2975```json theme={null}2980```json theme={null}
2979}2984}
2980```2985```
2981 2986
2982Los cambios `policy_settings` no se pueden bloquear. Los hooks aún se disparan para fuentes `policy_settings` cuando un archivo de configuración administrada en la máquina cambia, para que pueda registrar esas ediciones, pero cualquier decisión de bloqueo se ignora. Esto asegura que la configuración administrada por empresa siempre tenga efecto. Claude Code no ejecuta hooks `ConfigChange` cuando llegan o se actualizan [configuración administrada por servidor](/docs/es/server-managed-settings).2987Los cambios `policy_settings` no se pueden bloquear. Los hooks aún se disparan para fuentes `policy_settings` cuando un archivo de configuración administrada en la máquina cambia, por lo que puede usarlos para registrar esas ediciones, pero cualquier decisión de bloqueo se ignora. Esto asegura que la configuración administrada por la empresa siempre surta efecto. Claude Code no ejecuta hooks `ConfigChange` cuando llegan o se actualizan [configuración administrada por servidor](/docs/es/server-managed-settings).
2983 2988
2984Claude Code actúa sobre la decisión de bloqueo de la salida JSON de un hook ConfigChange y descarta `systemMessage` y `continue`. Un cambio bloqueado no muestra ningún mensaje a usted o a Claude, ya sea que bloquee con `reason` o con stderr en salida 2. Claude Code solo escribe una línea en el registro de depuración.2989Claude Code actúa sobre la decisión de bloqueo de la salida JSON de un hook ConfigChange y descarta `systemMessage` y `continue`. Un cambio bloqueado no muestra ningún mensaje a usted o a Claude, ya sea que bloquee con `reason` o con stderr en salida 2. Claude Code solo escribe una línea en el registro de depuración.
2985 2990
3028 DirectoryAdded3033 DirectoryAdded
3029</h3>3034</h3>
3030 3035
3031Se ejecuta después de agregar un directorio de trabajo a mitad de sesión con el comando `/add-dir`, o después de que un cliente SDK agregue uno con la solicitud de control `register_repo_root`. Úselo para preparar un repositorio recién agregado, por ejemplo instalando sus dependencias.3036Se ejecuta después de agregar un directorio de trabajo a mitad de sesión con el comando `/add-dir`, o después de que un cliente del SDK agregue uno con la solicitud de control `register_repo_root`. Úselo para preparar un repositorio recién agregado, por ejemplo instalando sus dependencias.
3032 3037
3033Claude Code no dispara este evento cuando:3038Claude Code no dispara este evento cuando:
3034 3039
3045| Matcher | Cuándo se dispara |3050| Matcher | Cuándo se dispara |
3046| :- | :- |3051| :- | :- |
3047| `slash_command` | Agrega un directorio con `/add-dir` |3052| `slash_command` | Agrega un directorio con `/add-dir` |
3048| `register_repo_root` | Un cliente SDK agrega un directorio con la solicitud de control `register_repo_root` |3053| `register_repo_root` | Un cliente del SDK agrega un directorio con la solicitud de control `register_repo_root` |
3049 3054
3050<h4 id="directoryadded-input">3055<h4 id="directoryadded-input">
3051 Entrada de DirectoryAdded3056 Entrada de DirectoryAdded
3078 FileChanged3083 FileChanged
3079</h3>3084</h3>
3080 3085
3081Se ejecuta cuando un archivo observado cambia en el disco. Claude Code detecta cambios con un observador del sistema de archivos, no inspeccionando llamadas de herramientas, por lo que ejecuta el hook sin importar qué cambió el archivo: una llamada de herramienta `Edit` o `Write`, un script que Claude ejecuta con `Bash`, o un proceso fuera de Claude Code completamente. Un uso común es recargar variables de entorno cuando cambian los archivos de configuración del proyecto.3086Se ejecuta cuando un archivo observado cambia en el disco. Claude Code detecta cambios con un observador del sistema de archivos, no inspeccionando llamadas de herramientas, por lo que ejecuta el hook sin importar qué cambió el archivo: una llamada de herramienta `Edit` o `Write`, un script que Claude ejecuta con `Bash`, o un proceso fuera de Claude Code completamente. Un uso común es recargar variables de entorno cuando cambian archivos de configuración del proyecto.
3082 3087
3083El `matcher` para este evento sirve dos roles:3088El `matcher` para este evento sirve dos roles:
3084 3089
3085* **Construir la lista de observación**: el valor se divide en `|` y cada segmento se registra como un nombre de archivo literal en el directorio de trabajo, por lo que `".envrc|.env"` observa exactamente esos dos archivos. Los patrones regex no son útiles aquí: un valor como `^\.env` observaría un archivo literalmente nombrado `^\.env`.3090* **Construir la lista de observación**: el valor se divide en `|` y cada segmento se registra como un nombre de archivo literal en el directorio de trabajo, por lo que `".envrc|.env"` observa exactamente esos dos archivos. Los patrones regex no son útiles aquí: un valor como `^\.env` observaría un archivo literalmente nombrado `^\.env`.
3086* **Filtrar qué hooks se ejecutan**: cuando un archivo observado cambia, el mismo valor filtra qué grupos de hooks se ejecutan usando las [reglas de matcher](#matcher-patterns) estándar contra el nombre base del archivo cambiado.3091* **Filtrar qué hooks se ejecutan**: cuando un archivo observado cambia, el mismo valor filtra qué grupos de hook se ejecutan usando las [reglas de matcher](#matcher-patterns) estándar contra el nombre base del archivo cambiado.
3087 3092
3088Este ejemplo normaliza terminaciones de línea en `data.csv` después de cualquier cambio, incluido un comando `Bash` o un script externo reescribiendo el archivo:3093Este ejemplo normaliza los finales de línea en `data.csv` después de cualquier cambio, incluido un comando `Bash` o un script externo reescribiendo el archivo:
3089 3094
3090```json theme={null}3095```json theme={null}
3091{3096{
3115fi3120fi
3116```3121```
3117 3122
3118Para confirmar que el hook funciona, pida a Claude que agregue una línea CRLF a `data.csv` con un comando `Bash`. Claude Code ejecuta el hook y el archivo termina con terminaciones LF.3123Para confirmar que el hook funciona, pida a Claude que agregue una línea CRLF a `data.csv` con un comando `Bash`. Claude Code ejecuta el hook y el archivo termina con finales LF.
3119 3124
3120Para observar archivos que no puede nombrar por adelantado, devuelva [`watchPaths`](#filechanged-output) de un hook para actualizar la lista de observación dinámicamente. Claude Code inicia el observador solo cuando algo nombra un archivo para observar, por lo que semilla la lista con un grupo FileChanged cuyo matcher nombra al menos un archivo, o con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) que devuelve `watchPaths`. El matcher aún filtra qué grupos de hooks se ejecutan cuando un archivo observado cambia, así que dé al grupo que maneja rutas dinámicas un matcher omitido, que coincide con cada archivo observado y no agrega nada a la lista de observación. Un matcher `"*"` también coincide con cada archivo, pero Claude Code lo registra en la lista de observación como cualquier otro valor, como un archivo literal nombrado `*`.3125Para observar archivos que no puede nombrar por adelantado, devuelva [`watchPaths`](#filechanged-output) de un hook para actualizar la lista de observación dinámicamente. Claude Code inicia el observador solo cuando algo nombra un archivo para observar, por lo que inicie la lista con un grupo FileChanged cuyo matcher nombre al menos un archivo, o con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) que devuelva `watchPaths`. El matcher aún filtra qué grupos de hook se ejecutan cuando un archivo observado cambia, así que dé al grupo que maneja rutas dinámicas un matcher omitido, que coincide con cada archivo observado y no agrega nada a la lista de observación. Un matcher `"*"` también coincide con cada archivo, pero Claude Code lo registra en la lista de observación como cualquier otro valor, como un archivo literal nombrado `*`.
3121 3126
3122Los hooks FileChanged tienen acceso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Las variables escritas en ese archivo persisten en comandos Bash posteriores hasta el siguiente evento [CwdChanged](#cwdchanged), cuando Claude Code las borra.3127Los hooks FileChanged tienen acceso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Las variables escritas en ese archivo persisten en comandos Bash posteriores hasta el siguiente evento [CwdChanged](#cwdchanged), cuando Claude Code las borra.
3123 3128
3161 WorktreeCreate3166 WorktreeCreate
3162</h3>3167</h3>
3163 3168
3164Se ejecuta cuando se está creando un worktree, ya sea desde `claude --worktree`, desde un [subagente usando `isolation: "worktree"`](/docs/es/sub-agents#choose-the-subagent-scope), o para una [sesión en segundo plano](/docs/es/agent-view#how-file-edits-are-isolated) que Claude Code aísla en su propio worktree. De forma predeterminada, Claude Code crea la copia de trabajo aislada con `git worktree`. Configurar un hook WorktreeCreate reemplaza ese comportamiento git predeterminado, permitiéndole usar un sistema de control de versiones diferente como SVN, Perforce o Mercurial.3169Se ejecuta cuando se está creando un worktree, ya sea desde `claude --worktree`, desde un [subagente usando `isolation: "worktree"`](/docs/es/sub-agents#choose-the-subagent-scope), o para una [sesión de fondo](/docs/es/agent-view#how-file-edits-are-isolated) que Claude Code aísla en su propio worktree. De forma predeterminada, Claude Code crea la copia de trabajo aislada con `git worktree`. Configurar un hook WorktreeCreate reemplaza ese comportamiento git predeterminado, permitiéndole usar un sistema de control de versiones diferente como SVN, Perforce o Mercurial.
3165 3170
3166Debido a que el hook reemplaza el comportamiento predeterminado completamente, [`.worktreeinclude`](/docs/es/worktrees#copy-gitignored-files-into-worktrees) no se procesa. Si necesita copiar archivos de configuración local como `.env` en el nuevo worktree, hágalo dentro de su script de hook.3171Debido a que el hook reemplaza el comportamiento predeterminado completamente, [`.worktreeinclude`](/docs/es/worktrees#copy-gitignored-files-into-worktrees) no se procesa. Si necesita copiar archivos de configuración local como `.env` en el nuevo worktree, hágalo dentro de su script de hook.
3167 3172
3188}3193}
3189```3194```
3190 3195
3191El hook lee el `name` del worktree de la entrada JSON en stdin, verifica una copia fresca en un nuevo directorio e imprime la ruta del directorio. El `echo` en la última línea es lo que Claude Code lee como la ruta del worktree. Redirija cualquier otra salida a stderr para que no interfiera con la ruta.3196El hook lee el `name` del worktree de la entrada JSON en stdin, verifica una copia fresca en un nuevo directorio, e imprime la ruta del directorio. El `echo` en la última línea es lo que Claude Code lee como la ruta del worktree. Redirija cualquier otra salida a stderr para que no interfiera con la ruta.
3192 3197
3193<h4 id="worktreecreate-input">3198<h4 id="worktreecreate-input">
3194 Entrada de WorktreeCreate3199 Entrada de WorktreeCreate
3210 Salida de WorktreeCreate3215 Salida de WorktreeCreate
3211</h4>3216</h4>
3212 3217
3213Los hooks WorktreeCreate no usan el modelo de decisión estándar permitir/bloquear. En su lugar, el éxito o fallo del hook determina el resultado. El hook debe devolver la ruta al directorio del worktree creado:3218Los hooks WorktreeCreate no usan el modelo de decisión de permitir/bloquear estándar. En su lugar, el éxito o fallo del hook determina el resultado. El hook debe devolver la ruta al directorio del worktree creado:
3214 3219
3215* **Hooks de comando** (`type: "command"`): imprima la ruta como la última línea no vacía de stdout. Claude Code elimina códigos de escape ANSI antes de leer esa línea, por lo que los banners de inicio de shell impresos antes de su `echo` se ignoran. Redirija cualquier otra salida del hook a stderr.3220* **Hooks de comando** (`type: "command"`): imprima la ruta como la última línea no vacía de stdout. Claude Code elimina códigos de escape ANSI antes de leer esa línea, por lo que los banners de inicio de shell impresos antes de su `echo` se ignoran. Redirija cualquier otra salida del hook a stderr.
3216* **Hooks HTTP** (`type: "http"`): devuelva `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.3221* **Hooks HTTP** (`type: "http"`): devuelva `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.
3229 3234
3230* sale de una sesión `--worktree` y elige eliminarla3235* sale de una sesión `--worktree` y elige eliminarla
3231* un subagente con `isolation: "worktree"` termina3236* un subagente con `isolation: "worktree"` termina
3232* elimina una [sesión en segundo plano](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook3237* elimina una [sesión de fondo](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook
3233 3238
3234Para worktrees basados en git, Claude Code maneja la limpieza automáticamente con `git worktree remove`. Si configuró un hook WorktreeCreate, emparéjelo con un hook WorktreeRemove para controlar la limpieza de los worktrees que crea:3239Para worktrees basados en git, Claude Code maneja la limpieza automáticamente con `git worktree remove`. Si configuró un hook WorktreeCreate, emparéjelo con un hook WorktreeRemove para controlar la limpieza de los worktrees que crea:
3235 3240
3236* **Sin hook WorktreeRemove**: cuando sale de una sesión `--worktree` y elige eliminación, Claude Code vuelve a `git worktree remove --force` en la ruta que devolvió su hook WorktreeCreate, por lo que se elimina un worktree que git reconoce. Un worktree que git no reconoce, por ejemplo uno que su hook creó con un sistema de control de versiones no git, permanece en el disco. Para lo que hace eliminar una [sesión en segundo plano](/docs/es/agent-view#what-deleting-a-session-removes) con un worktree creado por hook, consulte las reglas de eliminación de vista de agente.3241* **Sin hook WorktreeRemove**: cuando sale de una sesión `--worktree` y elige eliminación, Claude Code vuelve a `git worktree remove --force` en la ruta que devolvió su hook WorktreeCreate, por lo que se elimina un worktree que git reconoce. Un worktree que git no reconoce, por ejemplo uno que su hook creó con un sistema de control de versiones no git, permanece en el disco. Para lo que hace eliminar una [sesión de fondo](/docs/es/agent-view#what-deleting-a-session-removes) con un worktree creado por hook, consulte las reglas de eliminación de vista de agente.
3237* **El hook sale con 0**: el worktree se cuenta como eliminado. Claude Code no lee nada más del hook, así que asegúrese de que su hook eliminó el directorio.3242* **Hook sale con 0**: el worktree se cuenta como eliminado. Claude Code no lee nada más del hook, así que asegúrese de que su hook eliminó el directorio.
3238* **El hook sale con código no cero**: la eliminación falla si el directorio en `worktree_path` aún existe después, y el worktree permanece en el disco sin respaldo de git. Un hook que eliminó el directorio antes de salir con código no cero se cuenta como eliminado. Para cómo se reporta el fallo, consulte [entrada de WorktreeRemove](#worktreeremove-input).3243* **Hook sale con código no cero**: la eliminación falla si el directorio en `worktree_path` aún existe después, y el worktree permanece en el disco sin fallback de git. Un hook que eliminó el directorio antes de salir con código no cero se cuenta como eliminado. Para cómo se reporta el fallo, consulte [entrada de WorktreeRemove](#worktreeremove-input).
3239 3244
3240Claude Code nunca elimina una rama perteneciente a un worktree creado por hook, porque solo conoce la ruta que devolvió su hook WorktreeCreate. Si su hook WorktreeCreate crea una rama, elimínela en su hook WorktreeRemove.3245Claude Code nunca elimina una rama perteneciente a un worktree creado por hook, porque solo conoce la ruta que devolvió su hook WorktreeCreate. Si su hook WorktreeCreate crea una rama, elimínela en su hook WorktreeRemove.
3241 3246
3242Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.3247Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.
3243 3248
3244Para una eliminación de sesión en segundo plano, Claude Code verifica la ruta del worktree almacenada antes de ejecutar el hook y rechaza una ruta que es un enlace simbólico o pasa a través de uno por debajo de la raíz del repositorio. El hook se ejecuta para un worktree que aún contiene archivos solo cuando confirma la eliminación en [vista de agente](/docs/es/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/es/agent-view#manage-sessions-from-the-shell) mantiene la sesión y el worktree en su lugar. Antes de v2.1.216, el hook se ejecutaba en la ruta almacenada sin estas verificaciones.3249Para una eliminación de sesión de fondo, Claude Code verifica la ruta del worktree almacenada antes de ejecutar el hook y rechaza una ruta que es un enlace simbólico o pasa a través de uno por debajo de la raíz del repositorio. El hook se ejecuta para un worktree que aún contiene archivos solo cuando confirma la eliminación en [vista de agente](/docs/es/agent-view#what-deleting-a-session-removes); para tal worktree, [`claude rm`](/docs/es/agent-view#manage-sessions-from-the-shell) mantiene la sesión y el worktree en su lugar. Antes de v2.1.216, el hook se ejecutaba en la ruta almacenada sin estas verificaciones.
3245 3250
3246Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:3251Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:
3247 3252
3281El código de salida de un hook WorktreeRemove decide el resultado. Cuando un hook sale con código no cero y el directorio en `worktree_path` aún existe después, la eliminación falla:3286El código de salida de un hook WorktreeRemove decide el resultado. Cuando un hook sale con código no cero y el directorio en `worktree_path` aún existe después, la eliminación falla:
3282 3287
3283* El worktree permanece en el disco, y el comando del hook y stderr van al [registro de depuración](#debug-hooks).3288* El worktree permanece en el disco, y el comando del hook y stderr van al [registro de depuración](#debug-hooks).
3284* Si estaba eliminando una sesión en segundo plano, la sesión también permanece. El mensaje de rechazo en [vista de agente](/docs/es/agent-view#what-deleting-a-session-removes) reporta cómo terminó el hook, como `exited 1`, cita el inicio de su stderr, y dice si eliminar la sesión nuevamente elimina el directorio de todas formas.3289* Si estaba eliminando una sesión de fondo, la sesión también permanece. El mensaje de rechazo en [vista de agente](/docs/es/agent-view#what-deleting-a-session-removes) reporta cómo terminó el hook, como `exited 1`, cita el inicio de su stderr, y dice si eliminar la sesión nuevamente elimina el directorio de todas formas.
3285 3290
3286<h3 id="precompact">3291<h3 id="precompact">
3287 PreCompact3292 PreCompact
3298 3303
3299Salga con código 2 para bloquear la compactación. Para un `/compact` manual, el mensaje stderr se muestra al usuario. También puede bloquear devolviendo JSON con `"decision": "block"`.3304Salga con código 2 para bloquear la compactación. Para un `/compact` manual, el mensaje stderr se muestra al usuario. También puede bloquear devolviendo JSON con `"decision": "block"`.
3300 3305
3301Bloquear la compactación automática tiene diferentes efectos dependiendo de cuándo se dispare. Si la compactación fue disparada de forma proactiva antes del límite de contexto, Claude Code la omite y la conversación continúa sin compactar. Si la compactación fue disparada para recuperarse de un error de límite de contexto ya devuelto por la API, el error subyacente aparece y la solicitud actual falla.3306Bloquear la compactación automática tiene diferentes efectos dependiendo de cuándo se dispare. Si la compactación fue disparada de forma proactiva antes del límite de contexto, Claude Code la omite y la conversación continúa sin compactar. Si la compactación fue disparada para recuperarse de un error de límite de contexto ya devuelto por la API, el error subyacente surge y la solicitud actual falla.
3302 3307
3303Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.3308Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.
3304 3309
3325 3330
3326Se ejecuta después de que Claude Code completa una operación de compactación. Úselo para reaccionar al nuevo estado compactado, por ejemplo para registrar el resumen generado o actualizar el estado externo. Claude Code descarta los campos `systemMessage` y `continue` de un hook PostCompact.3331Se ejecuta después de que Claude Code completa una operación de compactación. Úselo para reaccionar al nuevo estado compactado, por ejemplo para registrar el resumen generado o actualizar el estado externo. Claude Code descarta los campos `systemMessage` y `continue` de un hook PostCompact.
3327 3332
3328Los mismos valores de matcher se aplican como para `PreCompact`:3333Los mismos valores de matcher se aplican que para `PreCompact`:
3329 3334
3330| Matcher | Cuándo se dispara |3335| Matcher | Cuándo se dispara |
3331| :- | :- |3336| :- | :- |
3355 PreModelSwitch3360 PreModelSwitch
3356</h3>3361</h3>
3357 3362
3358Se ejecuta antes de que Claude Code aplique un cambio de modelo que usted o un cliente solicitaron. Úselo para bloquear un cambio, requerir confirmación o mostrar qué costará el cambio antes de que suceda.3363Se ejecuta antes de que Claude Code aplique un cambio de modelo que usted o un cliente solicitó. Úselo para bloquear un cambio, requerir confirmación o mostrar cuál será el costo del cambio antes de que suceda.
3359 3364
3360PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:3365PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:
3361 3366
3363* El selector de modelo `Option+P` o `Alt+P`3368* El selector de modelo `Option+P` o `Alt+P`
3364* La configuración Model en `/config`3369* La configuración Model en `/config`
3365* Activar [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión3370* Activar [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión
3366* Una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un anfitrión [SDK del agente](/docs/es/agent-sdk/typescript#query-object) o [Control remoto](/docs/es/remote-control)3371* Una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un host [Agent SDK](/docs/es/agent-sdk/typescript#query-object) o [Control Remoto](/docs/es/remote-control)
3367 3372
3368Claude Code no ejecuta hooks PreModelSwitch para cambios que hace por sí solo, como un [respaldo de modelo automático](/docs/es/model-config#automatic-model-fallback) o restaurar el modelo cuando reanuda una sesión. Esos cambios llegan a [PostModelSwitch](#postmodelswitch) solo.3373Claude Code no ejecuta hooks PreModelSwitch para cambios que hace por sí solo, como un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback) o restaurar el modelo cuando reanuda una sesión. Esos cambios llegan a [PostModelSwitch](#postmodelswitch) solo.
3369 3374
3370Claude Code compara el matcher contra el nombre canónico del modelo al que la sesión está cambiando, ignorando cualquier sufijo `[1m]`. Un alias como `opus`, un ID de modelo fechado, y un ID específico del proveedor como un ID de modelo de Amazon Bedrock todos coinciden con el único nombre canónico al que se resuelven, por lo que `claude-opus-5` cubre cada deletreo de Opus 5.3375Claude Code compara el matcher contra el nombre canónico del modelo al que la sesión está cambiando, ignorando cualquier sufijo `[1m]`. Un alias como `opus`, un ID de modelo fechado, y un ID específico del proveedor como un ID de modelo de Amazon Bedrock todos coinciden con el único nombre canónico al que se resuelven, por lo que `claude-opus-5` cubre cada deletreo de Opus 5.
3371 3376
3372Cuando Claude Code no puede determinar un nombre canónico para el objetivo, por ejemplo un ID de modelo personalizado que solo su [puerta de enlace LLM](/docs/es/llm-gateway) conoce, ejecuta cada hook PreModelSwitch independientemente del matcher. Un hook que bloquea debe verificar `to_model` de su entrada en lugar de confiar solo en el matcher.3377Cuando Claude Code no puede determinar un nombre canónico para el objetivo, por ejemplo un ID de modelo personalizado que solo su [puerta de enlace LLM](/docs/es/llm-gateway) conoce, ejecuta cada hook PreModelSwitch independientemente del matcher. Un hook que bloquea debería por lo tanto verificar `to_model` de su entrada en lugar de confiar solo en el matcher.
3373 3378
3374Escriba el matcher como un nombre exacto, una lista separada por `|` como `claude-opus-4-6|claude-opus-5`, o una expresión regular como `.*opus.*`. Este ejemplo usa un matcher de nombre exacto y también verifica `to_model` de la entrada del hook, por lo que rechaza un cambio a Opus 4.6 al salir con código 2 y permite cualquier otro objetivo:3379Escriba el matcher como un nombre exacto, una lista separada por `|` como `claude-opus-4-6|claude-opus-5`, o una expresión regular como `.*opus.*`. Este ejemplo usa un matcher de nombre exacto y también verifica `to_model` de la entrada del hook, por lo que rechaza un cambio a Opus 4.6 saliendo con código 2 y permite cualquier otro objetivo:
3375 3380
3376<Tabs>3381<Tabs>
3377 <Tab title="macOS/Linux">3382 <Tab title="macOS/Linux">
3443 Entrada de PreModelSwitch3448 Entrada de PreModelSwitch
3444</h4>3449</h4>
3445 3450
3446Además de los [campos de entrada comunes](#common-input-fields), los hooks PreModelSwitch reciben los campos en esta tabla. Los últimos cinco describen qué cuesta reenviar la conversación al nuevo modelo, para que un hook pueda mostrar esa cifra antes de que suceda el cambio.3451Además de los [campos de entrada comunes](#common-input-fields), los hooks PreModelSwitch reciben los campos en esta tabla. Los últimos cinco describen cuál es el costo de reenviar la conversación al nuevo modelo, para que un hook pueda mostrar esa cifra antes de que suceda el cambio.
3447 3452
3448| Campo | Tipo | Descripción |3453| Campo | Tipo | Descripción |
3449| :- | :- | :- |3454| :- | :- | :- |
3450| `from_model` | string | ID de modelo del que cambia el cambio |3455| `from_model` | string | ID de modelo del que cambia el cambio |
3451| `to_model` | string | ID de modelo al que cambia el cambio. El matcher compara contra el nombre canónico de este modelo |3456| `to_model` | string | ID de modelo al que cambia el cambio. El matcher compara contra el nombre canónico de este modelo |
3452| `requested_model` | string o `null` | El modelo que la solicitud nombró: un alias como `opus`, un ID de modelo completo, o `null` cuando la solicitud fue para el modelo predeterminado |3457| `requested_model` | string o `null` | El modelo que la solicitud nombró: un alias como `opus`, un ID de modelo completo, o `null` cuando la solicitud fue para el modelo predeterminado |
3453| `source` | string | De dónde vino la solicitud: `"command"` para `/model <name>`, la configuración Model en `/config`, o activar modo rápido; `"picker"` para un selector de modelo; `"sdk"` para una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un anfitrión del SDK del agente o Control remoto |3458| `source` | string | De dónde vino la solicitud: `"command"` para `/model <name>`, la configuración Model en `/config`, o activar modo rápido; `"picker"` para un selector de modelo; `"sdk"` para una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un host Agent SDK o Control Remoto |
3454| `context_tokens` | number | Tokens que la siguiente solicitud reenvía como su prompt: los tokens de entrada, lectura de caché, creación de caché y salida de la última respuesta en la conversación principal, combinados. `0` antes de la primera respuesta |3459| `context_tokens` | number | Tokens que la siguiente solicitud reenvía como su prompt: los tokens de entrada, lectura de caché, creación de caché y salida de la última respuesta en la conversación principal, combinados. `0` antes de la primera respuesta |
3455| `prompt_cache_warm` | boolean | Si el caché de prompt del modelo actual probablemente aún esté caliente, lo que significa que el cambio lo pierde |3460| `prompt_cache_warm` | boolean | Si el caché de prompt del modelo actual probablemente aún esté caliente, lo que significa que el cambio lo pierde |
3456| `cache_ttl` | string | [Duración del caché de prompt](/docs/es/prompt-caching#cache-lifetime) que Claude Code solicita para esta sesión: `"5m"` o `"1h"` |3461| `cache_ttl` | string | [Duración de vida del caché de prompt](/docs/es/prompt-caching#cache-lifetime) que Claude Code solicita para esta sesión: `"5m"` o `"1h"` |
3457| `estimated_cache_write_usd` | number | Costo estimado en dólares estadounidenses de escribir `context_tokens` en el caché de prompt en `to_model` a la tasa `cache_ttl`, excluyendo la siguiente respuesta. El servidor puede no necesitar re-cachear todo el contexto, así que trátelo como una estimación |3462| `estimated_cache_write_usd` | number | Costo estimado en dólares estadounidenses de escribir `context_tokens` en el caché de prompt en `to_model` a la tasa `cache_ttl`, excluyendo la siguiente respuesta. El servidor puede no necesitar re-cachear todo el contexto, así que trátelo como una estimación |
3458| `pricing` | string | Cómo Claude Code fijó el precio de `estimated_cache_write_usd`: `"configured"` a sus propias tasas de la organización cuando las ha configurado, `"catalog"` a precio de lista, o `"default"` cuando `to_model` no tiene precio conocido y Claude Code asumió una tasa predeterminada |3463| `pricing` | string | Cómo Claude Code fijó el precio de `estimated_cache_write_usd`: `"configured"` a sus propias tasas de la organización cuando las ha configurado, `"catalog"` a precio de lista, o `"default"` cuando `to_model` no tiene precio conocido y Claude Code asumió una tasa predeterminada |
3459 3464
3483 3488
3484Los hooks `PreModelSwitch` pueden cancelar el cambio, pedir al usuario que lo confirme, o permitir que continúe. El código de salida 2 o un `decision: "block"` de nivel superior cancela el cambio.3489Los hooks `PreModelSwitch` pueden cancelar el cambio, pedir al usuario que lo confirme, o permitir que continúe. El código de salida 2 o un `decision: "block"` de nivel superior cancela el cambio.
3485 3490
3486Para un control más fino, devuelva `permissionDecision` y `permissionDecisionReason` en un objeto `hookSpecificOutput`, como en [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` acepta `"allow"`, `"deny"`, y `"ask"`. No acepta `"defer"`, `updatedInput`, o `additionalContext`. La tabla a continuación describe ambos campos:3491Para control más fino, devuelva `permissionDecision` y `permissionDecisionReason` en un objeto `hookSpecificOutput`, como en [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` acepta `"allow"`, `"deny"`, y `"ask"`. No acepta `"defer"`, `updatedInput`, o `additionalContext`. La tabla a continuación describe ambos campos:
3487 3492
3488| Campo | Descripción |3493| Campo | Descripción |
3489| :- | :- |3494| :- | :- |
3490| `permissionDecision` | `"allow"` continúa y omite la [confirmación que Claude Code muestra mientras el caché de prompt está caliente](/docs/es/prompt-caching#switching-models). `"deny"` cancela el cambio. `"ask"` solicita al usuario que lo confirme |3495| `permissionDecision` | `"allow"` continúa y omite la [confirmación que Claude Code muestra mientras el caché de prompt está caliente](/docs/es/prompt-caching#switching-models). `"deny"` cancela el cambio. `"ask"` solicita al usuario que lo confirme |
3491| `permissionDecisionReason` | Para `"deny"`, se muestra al usuario como la razón por la que se bloqueó el cambio, o se devuelve como el error para una solicitud `set_model`. Para `"ask"`, se muestra en el aviso de confirmación. Se ignora para `"allow"` |3496| `permissionDecisionReason` | Para `"deny"`, se muestra al usuario como la razón por la que se bloqueó el cambio, o se devuelve como el error para una solicitud `set_model`. Para `"ask"`, se muestra en el prompt de confirmación. Se ignora para `"allow"` |
3492 3497
3493Solo `/model` en una sesión interactiva puede mostrar el aviso `"ask"`. En todas las otras superficies, incluido modo no interactivo con la bandera `-p`, `/config`, y solicitudes `set_model`, Claude Code trata `"ask"` como un rechazo.3498Solo `/model` en una sesión interactiva puede mostrar el prompt `"ask"`. En todas las otras superficies, incluido modo no interactivo con la bandera `-p`, `/config`, y solicitudes `set_model`, Claude Code trata `"ask"` como un rechazo.
3494 3499
3495Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:3500Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:
3496 3501
3510 3515
3511Un hook PreModelSwitch que no responde antes de su tiempo de espera bloquea el cambio. En [PreToolUse](#timeouts), por el contrario, un hook de comando que agota el tiempo de espera permite que la llamada de herramienta continúe. El tiempo de espera predeterminado para este evento es 30 segundos. `PreModelSwitch` ejecuta solo hooks `command`, `http`, y `mcp_tool`, por lo que los valores predeterminados `prompt` y `agent` no se aplican.3516Un hook PreModelSwitch que no responde antes de su tiempo de espera bloquea el cambio. En [PreToolUse](#timeouts), por el contrario, un hook de comando que agota el tiempo de espera permite que la llamada de herramienta continúe. El tiempo de espera predeterminado para este evento es 30 segundos. `PreModelSwitch` ejecuta solo hooks `command`, `http`, y `mcp_tool`, por lo que los valores predeterminados `prompt` y `agent` no se aplican.
3512 3517
3513Un hook que sale 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).3518Un hook que sale con un código distinto de 0 o 2 e imprime sin 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).
3514 3519
3515<h3 id="postmodelswitch">3520<h3 id="postmodelswitch">
3516 PostModelSwitch3521 PostModelSwitch
3520 3525
3521PostModelSwitch requiere Claude Code v2.1.251 o posterior. No puede bloquear, porque el modelo ya ha cambiado. Claude Code ejecuta hooks PostModelSwitch después de cualquiera de estos cambios:3526PostModelSwitch requiere Claude Code v2.1.251 o posterior. No puede bloquear, porque el modelo ya ha cambiado. Claude Code ejecuta hooks PostModelSwitch después de cualquiera de estos cambios:
3522 3527
3523* Un cambio que usted o un cliente solicitaron3528* Un cambio que usted o un cliente solicitó
3524* Un [respaldo de modelo automático](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión3529* Un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión
3525* Una configuración como [`opusplan`](/docs/es/model-config#opusplan-model-setting) entrando o saliendo del modo plan3530* Una configuración como [`opusplan`](/docs/es/model-config#opusplan-model-setting) entrando o saliendo del modo de plan
3526* Claude Code restaurando el modelo cuando reanuda una sesión3531* Claude Code restaurando el modelo cuando reanuda una sesión
3527 3532
3528Claude Code no ejecuta hooks PostModelSwitch cuando un modelo de una [cadena de modelo de respaldo](/docs/es/model-config#fallback-model-chains) sirve un turno, porque esa sustitución dura un turno y deja el modelo de la sesión sin cambios.3533Claude Code no ejecuta hooks PostModelSwitch cuando un modelo de una [cadena de modelo de fallback](/docs/es/model-config#fallback-model-chains) sirve un turno, porque esa sustitución dura un turno y deja el modelo de la sesión sin cambios.
3529 3534
3530El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.3535El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.
3531 3536
3555 Entrada de PostModelSwitch3560 Entrada de PostModelSwitch
3556</h4>3561</h4>
3557 3562
3558Los hooks PostModelSwitch reciben los mismos campos que [PreModelSwitch](#premodelswitch-input), con `hook_event_name` establecido en `"PostModelSwitch"` y dos valores `source` más: `"auto"` para un respaldo automático u otro cambio que Claude Code hizo por sí solo, y `"resume"` para el modelo restaurado cuando reanuda una sesión.3563Los hooks PostModelSwitch reciben los mismos campos que [PreModelSwitch](#premodelswitch-input), con `hook_event_name` establecido en `"PostModelSwitch"` y dos valores `source` más: `"auto"` para un fallback automático u otro cambio que Claude Code hizo por sí solo, y `"resume"` para el modelo restaurado cuando reanuda una sesión.
3559 3564
3560`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es la configuración de modelo guardada que Claude Code restauró.3565`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es la configuración de modelo guardada que Claude Code restauró.
3561 3566
3569| :- | :- |3574| :- | :- |
3570| `additionalContext` | Cadena agregada al contexto de Claude con la siguiente solicitud. Consulte [Agregar contexto para Claude](#add-context-for-claude) |3575| `additionalContext` | Cadena agregada al contexto de Claude con la siguiente solicitud. Consulte [Agregar contexto para Claude](#add-context-for-claude) |
3571 3576
3572Si el hook no ha terminado dentro de cinco segundos después de que envía la siguiente solicitud, Claude Code envía esa solicitud sin la salida y la adjunta a la siguiente solicitud en su lugar. Si el modelo cambia varias veces antes de la siguiente solicitud, Claude Code entrega solo la salida para el modelo de destino del último cambio.3577Si el hook no se ha completado dentro de cinco segundos después de que envíe la siguiente solicitud, Claude Code envía esa solicitud sin la salida y la adjunta a la siguiente solicitud en su lugar. Si el modelo cambia varias veces antes de la siguiente solicitud, Claude Code entrega solo la salida para el cambio del modelo objetivo final.
3573 3578
3574<h3 id="sessionend">3579<h3 id="sessionend">
3575 SessionEnd3580 SessionEnd
3576</h3>3581</h3>
3577 3582
3578Se ejecuta cuando termina una sesión de Claude Code. Útil para tareas de limpieza, registrar estadísticas de sesión o guardar estado de sesión. Admite matchers para filtrar por razón de salida.3583Se ejecuta cuando termina una sesión de Claude Code. Útil para tareas de limpieza, registro de estadísticas de sesión o guardado del estado de la sesión. Admite matchers para filtrar por razón de salida.
3579 3584
3580El campo `reason` en la entrada del hook indica por qué terminó la sesión:3585El campo `reason` en la entrada del hook indica por qué terminó la sesión:
3581 3586
3586| `logout` | Usuario cerró sesión |3591| `logout` | Usuario cerró sesión |
3587| `prompt_input_exit` | Usuario salió mientras la entrada de prompt era visible |3592| `prompt_input_exit` | Usuario salió mientras la entrada de prompt era visible |
3588| `other` | Otras razones de salida |3593| `other` | Otras razones de salida |
3589| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Elimínelo de sus matchers `SessionEnd` |3594| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Elimine de sus matchers `SessionEnd` |
3590 3595
3591<h4 id="sessionend-input">3596<h4 id="sessionend-input">
3592 Entrada de SessionEnd3597 Entrada de SessionEnd
3604}3609}
3605```3610```
3606 3611
3607Los hooks SessionEnd no tienen control de decisión. No pueden bloquear la terminación de sesión pero pueden realizar tareas de limpieza. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage`.3612Los hooks SessionEnd no tienen control de decisión. No pueden bloquear la terminación de la sesión pero pueden realizar tareas de limpieza. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage`.
3608 3613
3609Los hooks SessionEnd tienen un tiempo de espera predeterminado de 1.5 segundos. Se aplica cuando sale, ejecuta `/clear`, o cambia sesiones con `/resume` interactivo. Puede dar a un hook más tiempo de dos formas:3614Los hooks SessionEnd tienen un tiempo de espera predeterminado de 1.5 segundos. Se aplica cuando sale, ejecuta `/clear`, o cambia de sesiones con `/resume` interactivo. Puede dar a un hook más tiempo de dos formas:
3610 3615
3611* **`timeout` por hook**: establezca `timeout` en la configuración de ese hook. El presupuesto general aumenta automáticamente para coincidir con el `timeout` por hook más alto en sus archivos de configuración, hasta 60 segundos. Si aumenta el presupuesto de esta forma, un hook sin su propio `timeout` aún mantiene el predeterminado. Los tiempos de espera establecidos en hooks proporcionados por plugins no aumentan el presupuesto.3616* **`timeout` por hook**: establezca `timeout` en la configuración de ese hook. El presupuesto general aumenta automáticamente para coincidir con el `timeout` por hook más alto en sus archivos de configuración, hasta 60 segundos. Si aumenta el presupuesto de esta forma, un hook sin su propio `timeout` aún mantiene el predeterminado. Los tiempos de espera establecidos en hooks proporcionados por plugins no aumentan el presupuesto.
3612* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: establezca esta variable de entorno en milisegundos para anular el presupuesto explícitamente. El valor que establezca también se convierte en el tiempo de espera para cada hook sin su propio `timeout`.3617* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: establezca esta variable de entorno en milisegundos para anular el presupuesto explícitamente. El valor que establezca también se convierte en el tiempo de espera para cada hook sin su propio `timeout`.
