40| :- | :- |40| :- | :- |
41| `SessionStart` | Cuando una sesión comienza o se reanuda |41| `SessionStart` | Cuando una sesión comienza o se reanuda |
42| `Setup` | Cuando inicia Claude Code con `--init-only`, o con `--init` o `--maintenance` en modo `-p`. Para preparación única en CI o scripts |42| `Setup` | Cuando inicia Claude Code con `--init-only`, o con `--init` o `--maintenance` en modo `-p`. Para preparación única en CI o scripts |
43| `UserPromptSubmit` | Cuando envía un prompt, antes de que Claude lo procese |43| `UserPromptSubmit` | Cuando se envía un prompt, antes de que Claude lo procese. También se dispara en [turnos que Claude Code inicia por su cuenta](/docs/es/hooks#userpromptsubmit) |
44| `UserPromptExpansion` | Cuando un comando escrito por el usuario se expande en un prompt, antes de que llegue a Claude. Puede bloquear la expansión |44| `UserPromptExpansion` | Cuando un comando escrito por el usuario se expande en un prompt, antes de que llegue a Claude. Puede bloquear la expansión |
45| `PreToolUse` | Antes de que se ejecute una llamada a herramienta. Puede bloquearlo |45| `PreToolUse` | Antes de que se ejecute una llamada a herramienta. Puede bloquearlo |
46| `PermissionRequest` | Cuando una llamada a herramienta necesita una decisión de permiso |46| `PermissionRequest` | Cuando una llamada a herramienta necesita una decisión de permiso |
1159 Eventos de hooks1159 Eventos de hooks
1160</h2>1160</h2>
1161 1161
1162Cada evento corresponde a un punto en el ciclo de vida de Claude Code donde los hooks pueden ejecutarse. Las secciones siguientes están ordenadas para coincidir con el ciclo de vida: desde la configuración de la sesión a través del bucle agéntico hasta el final de la sesión. Cada sección describe cuándo se dispara el evento, qué matchers admite, la entrada JSON que recibe y cómo controlar el comportamiento a través de la salida.1162Cada evento corresponde a un punto del ciclo de vida de Claude Code en el que pueden ejecutarse hooks. Las secciones siguientes están ordenadas según el ciclo de vida: desde la configuración de la sesión, pasando por el bucle agéntico, hasta el final de la sesión. Cada sección describe cuándo se dispara el evento, qué matchers admite, la entrada JSON que recibe y cómo controlar el comportamiento mediante la salida.
1163 1163
1164<h3 id="sessionstart">1164<h3 id="sessionstart">
1165 SessionStart1165 SessionStart
1166</h3>1166</h3>
1167 1167
1168Se ejecuta cuando Claude Code inicia una nueva sesión o reanuda una sesión existente. Útil para cargar contexto de desarrollo como problemas existentes o cambios recientes en su base de código, o configurar variables de entorno. Para contexto estático que no requiere un script, use [CLAUDE.md](/docs/es/memory) en su lugar.1168Se ejecuta cuando Claude Code inicia una sesión nueva o reanuda una sesión existente. Es útil para cargar contexto de desarrollo, como issues existentes o cambios recientes en tu base de código, o para configurar variables de entorno. Para contexto estático que no requiere un script, usa [CLAUDE.md](/docs/es/memory) en su lugar.
1169 1169
1170SessionStart se ejecuta en cada sesión, así que mantenga estos hooks rápidos. Solo se admiten hooks `type: "command"` y `type: "mcp_tool"`. Consulte [campos de hook de herramienta MCP](#mcp-tool-hook-fields) para saber cuándo se ejecutan los hooks `mcp_tool`.1170SessionStart se ejecuta en cada sesión, así que mantén estos hooks rápidos. Solo se admiten hooks `type: "command"` y `type: "mcp_tool"`. Consulta [Campos de hooks de herramientas MCP](#mcp-tool-hook-fields) para saber cuándo se ejecutan los hooks `mcp_tool`.
1171 1171
1172El valor del matcher corresponde a cómo se inició la sesión:1172El valor del matcher corresponde a cómo se inició la sesión:
1173 1173
1174| Matcher | Cuándo se dispara |1174| Matcher | Cuándo se dispara |
1175| :- | :- |1175| :- | :- |
1176| `startup` | Nueva sesión |1176| `startup` | Sesión nueva |
1177| `resume` | `--resume`, `--continue`, o `/resume` |1177| `resume` | `--resume`, `--continue` o `/resume` |
1178| `clear` | `/clear` |1178| `clear` | `/clear` |
1179| `compact` | Compactación automática o manual |1179| `compact` | Compactación automática o manual |
1180| `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) |1180| `fork` | Una sesión nueva bifurcada de una existente: `--fork-session` con `--resume` o `--continue`, la copia en segundo plano de `/fork`, `/branch` o una conversación que [mueves al segundo plano](/docs/es/agent-view#from-inside-a-session) |
1181 1181
1182Antes de v2.1.214, las sesiones bifurcadas reportaban origen `"resume"`.1182Antes de la v2.1.214, las sesiones bifurcadas informaban el origen `"resume"`.
1183 1183
1184Cuando 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.1184Cuando inicias una sesión interactiva, reanudas una conversación al arrancar con `--continue` o `--resume`, o ejecutas `/clear`, los hooks SessionStart se ejecutan en segundo plano. Puedes escribir de inmediato, y una conversación que reanudaste aparece sin esperar a los hooks. La primera respuesta de Claude sigue esperando a que los hooks terminen, para que su contexto llegue a Claude.
1185 1185
1186Cuando 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.1186Cuando cambias de conversación con `/resume` dentro de una sesión, el cambio espera a que los hooks terminen. Si ejecutas `/clear` o cambias a otra conversación mientras los hooks en segundo plano todavía se están ejecutando, nada de lo que devuelvan se aplica a la sesión.
1187 1187
1188La 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.1188La misma espera se aplica al arrancar, incluida una sesión reanudada: un prompt que envías mientras los hooks SessionStart todavía se están ejecutando no llega a Claude hasta que terminan.
1189 1189
1190Durante cualquiera de las esperas, presione `Esc` para recuperar el prompt en la entrada sin enviarlo. Los hooks siguen ejecutándose.1190Durante cualquiera de las dos esperas, presiona `Esc` para devolver el prompt a la entrada sin enviarlo. Los hooks siguen ejecutándose.
1191 1191
1192<h4 id="sessionstart-input">1192<h4 id="sessionstart-input">
1193 Entrada de SessionStart1193 Entrada de SessionStart
1194</h4>1194</h4>
1195 1195
1196Además de los [campos de entrada comunes](#common-input-fields), los hooks SessionStart reciben `source` y opcionalmente `model`, `agent_type`, y `session_title`:1196Además de los [campos de entrada comunes](#common-input-fields), los hooks SessionStart reciben `source` y, opcionalmente, `model`, `agent_type` y `session_title`:
1197 1197
1198| Campo | Descripción |1198| Campo | Descripción |
1199| :- | :- |1199| :- | :- |
1200| `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 |1200| `source` | Cómo se inició la sesión: `"startup"` para sesiones nuevas, `"resume"` para sesiones reanudadas, `"clear"` después de `/clear`, `"compact"` después de la compactación o `"fork"` para una sesión nueva bifurcada de una existente |
1201| `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 |1201| `model` | El identificador del modelo activo. Puede omitirse, por ejemplo después de `/clear` o cuando una sesión se restaura mediante la recuperación de conversaciones, así que comprueba que el campo exista antes de leerlo |
1202| `agent_type` | El nombre del agente, presente cuando inicia Claude Code con `claude --agent <name>` |1202| `agent_type` | El nombre del agente, presente cuando inicias Claude Code con `claude --agent <name>` |
1203| `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 |1203| `session_title` | El título personalizado de la sesión, presente cuando hay uno definido, por ejemplo con `--name`, `/rename`, la salida `sessionTitle` de un hook o `renameSession()` del Agent SDK. Un hook que emite `sessionTitle` puede comprobar primero este campo para evitar sobrescribir un título personalizado existente |
1204 1204
1205Una sesión que no ha nombrado aún puede tener un [título generado](/docs/es/sessions#name-your-sessions). Ese título no es un título personalizado y no aparece en `session_title`.1205Una sesión a la que no le has puesto nombre puede tener igualmente un [título generado](/docs/es/sessions#name-your-sessions). Ese título no es un título personalizado y no aparece en `session_title`.
1206 1206
1207Cuando `source` es `"resume"` o `"fork"` y la transcripción contiene al menos una respuesta de Claude, los hooks SessionStart también reciben los cuatro campos siguientes. Su hook puede usarlos para reportar qué cuesta reanudar una conversación obsoleta antes de la primera solicitud, por ejemplo en un [`systemMessage`](#json-output). Estos campos requieren Claude Code v2.1.251 o posterior.1207Cuando `source` es `"resume"` o `"fork"` y la transcripción contiene al menos una respuesta de Claude, los hooks SessionStart también reciben los cuatro campos siguientes. Tu hook puede usarlos para informar cuánto cuesta reanudar una conversación antigua antes de la primera solicitud, por ejemplo en un [`systemMessage`](#json-output). Estos campos requieren Claude Code v2.1.251 o posterior.
1208 1208
1209| Campo | Descripción |1209| Campo | Descripción |
1210| :- | :- |1210| :- | :- |
1211| `seconds_since_last_response` | Segundos de reloj de pared desde la última respuesta en la transcripción reanudada |1211| `seconds_since_last_response` | Segundos de tiempo real desde la última respuesta en la transcripción reanudada |
1212| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada reenvía como su prompt |1212| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada vuelve a enviar como su prompt |
1213| `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é |1213| `prompt_cache_likely_expired` | `true` cuando la última respuesta es más antigua que la [vida útil de la caché de prompts](/docs/es/prompt-caching#cache-lifetime) de la sesión o una compactación posterior reemplazó la conversación almacenada en caché |
1214| `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 |1214| `estimated_cache_write_usd` | Costo estimado en dólares estadounidenses de escribir `context_tokens` en la caché de prompts con el modelo de la sesión, sin incluir la respuesta |
1215 1215
1216Este ejemplo muestra la entrada para una sesión reanudada 90 minutos después de su última respuesta:1216Este ejemplo muestra la entrada de una sesión reanudada 90 minutos después de su última respuesta:
1217 1217
1218```json theme={null}1218```json theme={null}
1219{1219{
1231```1231```
1232 1232
1233<h4 id="sessionstart-decision-control">1233<h4 id="sessionstart-decision-control">
1234 Control de decisión de SessionStart1234 Control de decisiones de SessionStart
1235</h4>1235</h4>
1236 1236
1237Claude Code agrega stdout que [trata como texto plano](#exit-code-0) al contexto de Claude. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puede devolver estos campos específicos del evento:1237Claude Code agrega al contexto de Claude la stdout que [trata como texto plano](#exit-code-0). Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puedes devolver estos campos específicos del evento:
1238 1238
1239| Campo | Descripción |1239| Campo | Descripción |
1240| :- | :- |1240| :- | :- |
1241| `additionalContext` | Cadena agregada al contexto de Claude al inicio de la conversación, antes del primer prompt. Consulte [Agregar contexto para Claude](#add-context-for-claude) para saber cómo se entrega el texto y qué poner en él |1241| `additionalContext` | Cadena agregada al contexto de Claude al inicio de la conversación, antes del primer prompt. Consulta [Agregar contexto para Claude](#add-context-for-claude) para saber cómo se entrega el texto y qué poner en él |
1242| `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 |1242| `initialUserMessage` | Cadena usada como primer mensaje de usuario de la sesión. Se aplica en [modo no interactivo](/docs/es/headless) con el flag `-p`, donde se convierte en el primer turno incluso si no se proporciona ningún prompt. Si se proporciona un prompt, este sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, esto crea el turno |
1243| `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"` |1243| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Úsalo para nombrar sesiones automáticamente a partir de la carpeta de inicio, la rama de git o el nombre del worktree. Se aplica cuando `source` es `"startup"`, `"resume"` o `"fork"`; se ignora con `"clear"` y `"compact"` |
1244| `watchPaths` | Matriz de rutas absolutas para observar eventos [FileChanged](#filechanged) durante esta sesión |1244| `watchPaths` | Array de rutas absolutas que se vigilan para eventos [FileChanged](#filechanged) durante esta sesión |
1245| `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 |1245| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a examinar los directorios de [skills](/docs/es/skills) y comandos después de que terminan los hooks SessionStart, de modo que los skills que instaló el hook están disponibles en la misma sesión, a partir del primer prompt |
1246 1246
1247```json theme={null}1247```json theme={null}
1248{1248{
1254}1254}
1255```1255```
1256 1256
1257Dado 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`.1257Como la stdout en texto plano ya llega a Claude para este evento, un hook que solo carga contexto puede imprimir directamente en stdout sin construir JSON. Usa la forma JSON cuando necesites combinar contexto con otros campos, como `sessionTitle`.
1258 1258
1259Use `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:1259Usa `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/` solo aparecerían en la siguiente sesión. Este ejemplo sincroniza un repositorio compartido de skills y solicita el nuevo examen:
1260 1260
1261```bash theme={null}1261```bash theme={null}
1262#!/bin/bash1262#!/bin/bash
1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1267echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1268```1268```
1269 1269
1270La URL del repositorio es un marcador de posición; reemplácela con su propio repositorio de skills. Con el marcador de posición, el clon falla e imprime un mensaje `fatal:` a stderr. Stderr de un hook SessionStart que sale con 0 es solo informativo, por lo que la solicitud `reloadSkills` aún se aplica.1270La URL del repositorio es un marcador de posición; reemplázala por tu propio repositorio de skills. Con el marcador de posición, el clon falla e imprime un mensaje `fatal:` en stderr. La stderr de un hook SessionStart que sale con 0 es solo informativa, así que la solicitud `reloadSkills` se sigue aplicando.
1271 1271
1272<h4 id="persist-environment-variables">1272<h4 id="persist-environment-variables">
1273 Persistir variables de entorno1273 Persistir variables de entorno
1274</h4>1274</h4>
1275 1275
1276Los hooks SessionStart tienen acceso a la variable de entorno `CLAUDE_ENV_FILE`, que proporciona una ruta de archivo donde puede persistir variables de entorno para comandos Bash posteriores.1276Los hooks SessionStart tienen acceso a la variable de entorno `CLAUDE_ENV_FILE`, que proporciona una ruta de archivo donde puedes persistir variables de entorno para los comandos Bash posteriores.
1277 1277
1278Para establecer variables de entorno individuales, escriba declaraciones `export` en `CLAUDE_ENV_FILE`. Use append (`>>`) para preservar variables establecidas por otros hooks:1278Para establecer variables de entorno individuales, escribe instrucciones `export` en `CLAUDE_ENV_FILE`. Usa la anexión (`>>`) para conservar las variables establecidas por otros hooks:
1279 1279
1280```bash theme={null}1280```bash theme={null}
1281#!/bin/bash1281#!/bin/bash
1289exit 01289exit 0
1290```1290```
1291 1291
1292Para capturar todos los cambios de entorno de comandos de configuración, compare las variables exportadas antes y después:1292Para capturar todos los cambios del entorno de los comandos de configuración, compara las variables exportadas antes y después:
1293 1293
1294```bash theme={null}1294```bash theme={null}
1295#!/bin/bash1295#!/bin/bash
1309```1309```
1310 1310
1311<Note>1311<Note>
1312 `CLAUDE_ENV_FILE` está disponible para hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged), y [FileChanged](#filechanged). Otros tipos de hooks no tienen acceso a esta variable.1312 `CLAUDE_ENV_FILE` está disponible para los hooks SessionStart, [Setup](#setup), [CwdChanged](#cwdchanged) y [FileChanged](#filechanged). Los demás tipos de hooks no tienen acceso a esta variable.
1313</Note>1313</Note>
1314 1314
1315<h3 id="setup">1315<h3 id="setup">
1316 Setup1316 Setup
1317</h3>1317</h3>
1318 1318
1319Se dispara solo cuando inicia Claude Code con `--init-only`, o con `--init` o `--maintenance` en [modo no interactivo](/docs/es/headless) con la bandera `-p`. No se dispara en el inicio normal. Úselo para instalación de dependencias única o limpieza programada que dispara explícitamente desde CI o scripts, separado del inicio de sesión normal. Para inicialización por sesión, use [SessionStart](#sessionstart) en su lugar.1319Se dispara solo cuando inicias Claude Code con `--init-only`, o con `--init` o `--maintenance` en [modo no interactivo](/docs/es/headless) con el flag `-p`. No se dispara en un inicio normal. Úsalo para la instalación única de dependencias o para limpiezas programadas que activas explícitamente desde CI o scripts, de forma separada del inicio normal de la sesión. Para la inicialización por sesión, usa [SessionStart](#sessionstart) en su lugar.
1320 1320
1321El valor del matcher corresponde a la bandera CLI que disparó el hook:1321El valor del matcher corresponde al flag de la CLI que activó el hook:
1322 1322
1323| Matcher | Cuándo se dispara |1323| Matcher | Cuándo se dispara |
1324| :- | :- |1324| :- | :- |
1325| `init` | `claude --init-only` o `claude -p --init` |1325| `init` | `claude --init-only` o `claude -p --init` |
1326| `maintenance` | `claude -p --maintenance` |1326| `maintenance` | `claude -p --maintenance` |
1327 1327
1328Cuando ejecuta `claude --init-only`, Claude Code ejecuta hooks Setup y hooks `SessionStart` con el matcher `startup`, luego sale sin iniciar una conversación.1328Cuando ejecutas `claude --init-only`, Claude Code ejecuta los hooks Setup y los hooks `SessionStart` con el matcher `startup`, y luego sale sin iniciar una conversación.
1329 1329
1330Cuando inicia o continúa una conversación con `-p`, también necesita proporcionar un prompt, como argumento o canalizando en stdin. Puede omitir el prompt cuando un hook `SessionStart` proporciona [`initialUserMessage`](#sessionstart-decision-control) o cuando reanuda una sesión con una [llamada de herramienta diferida](#defer-a-tool-call-for-later).1330Cuando inicias o continúas una conversación con `-p`, también necesitas proporcionar un prompt, como argumento o mediante una canalización por stdin. Puedes omitir el prompt cuando un hook `SessionStart` proporciona [`initialUserMessage`](#sessionstart-decision-control) o cuando reanudas una sesión con una [llamada a herramienta diferida](#defer-a-tool-call-for-later).
1331 1331
1332En 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.1332Si tiene éxito, `--init-only` no imprime nada en la terminal. Para confirmar que los hooks se ejecutaron, inicia con `claude --debug-file <path> --init-only`, reemplazando `<path>` por la ubicación de un archivo de log, y revisa el registro en busca de las entradas de los hooks Setup y SessionStart.
1333 1333
1334Debido 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.1334Como Setup no se dispara en cada inicio, un plugin que necesita una dependencia instalada no puede depender solo de Setup. El patrón práctico es comprobar la dependencia en el primer uso e instalarla si falta, por ejemplo con un hook o skill que compruebe `${CLAUDE_PLUGIN_DATA}/node_modules` y ejecute `npm install` si no existe. Consulta el [directorio de datos persistentes](/docs/es/plugins/components#path-variables-and-persistent-data) para saber dónde almacenar las dependencias instaladas. Si distribuyes tu plugin a través de un marketplace, es posible que no necesites este patrón: Claude Code [instala automáticamente las dependencias de paquetes de Node.js aptas](/docs/es/plugins/loading#node-js-package-dependencies) cuando almacena el plugin en caché.
1335 1335
1336<h4 id="setup-input">1336<h4 id="setup-input">
1337 Entrada de Setup1337 Entrada de Setup
1338</h4>1338</h4>
1339 1339
1340Además de los [campos de entrada comunes](#common-input-fields), los hooks Setup reciben un campo `trigger` establecido en `"init"` o `"maintenance"`:1340Además de los [campos de entrada comunes](#common-input-fields), los hooks Setup reciben un campo `trigger` con el valor `"init"` o `"maintenance"`:
1341 1341
1342```json theme={null}1342```json theme={null}
1343{1343{
1350```1350```
1351 1351
1352<h4 id="setup-decision-control">1352<h4 id="setup-decision-control">
1353 Control de decisión de Setup1353 Control de decisiones de Setup
1354</h4>1354</h4>
1355 1355
1356Los 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`.1356Los hooks Setup no pueden bloquear; la ejecución continúa con cualquier código de salida. Con cualquier 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`, la stdout, la 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 inicias con `--output-format stream-json --verbose`.
1357 1357
1358Los 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).1358Los hooks Setup tienen acceso a `CLAUDE_ENV_FILE`. Las variables escritas en ese archivo persisten en los comandos Bash posteriores de la sesión, igual que en los [hooks SessionStart](#persist-environment-variables). Solo los hooks `type: "command"` se ejecutan en `Setup`. Un hook `type: "mcp_tool"` en `Setup` siempre se omite, como se describe en [Campos de hooks de herramientas MCP](#mcp-tool-hook-fields).
1359 1359
1360<h3 id="instructionsloaded">1360<h3 id="instructionsloaded">
1361 InstructionsLoaded1361 InstructionsLoaded
1362</h3>1362</h3>
1363 1363
1364Se dispara cuando se carga un archivo `CLAUDE.md` o `.claude/rules/*.md` en el contexto. Este evento se dispara al inicio de la sesión para archivos cargados con entusiasmo y nuevamente más tarde cuando se cargan archivos de forma perezosa, por ejemplo cuando Claude accede a un subdirectorio que contiene un `CLAUDE.md` anidado o cuando las reglas condicionales con frontmatter `paths:` coinciden. El hook no admite bloqueo o control de decisión. Se ejecuta de forma asincrónica con fines de observabilidad.1364Se dispara cuando un archivo `CLAUDE.md` o `.claude/rules/*.md` se carga en el contexto. Este evento se dispara al inicio de la sesión para los archivos cargados de forma anticipada y de nuevo más tarde cuando los archivos se cargan de forma diferida, por ejemplo cuando Claude accede a un subdirectorio que contiene un `CLAUDE.md` anidado o cuando coinciden reglas condicionales con frontmatter `paths:`. El hook no admite bloqueo ni control de decisiones. Se ejecuta de forma asíncrona con fines de observabilidad.
1365 1365
1366Este evento no se dispara cuando Claude [lee `AGENTS.md` directamente](/docs/es/memory#agents-md) a través de la configuración **Instrucciones del proyecto**. Se dispara cuando un `CLAUDE.md` importa su `AGENTS.md`, con `load_reason` establecido en `include` como para cualquier otro archivo importado, y cuando `CLAUDE.md` es un enlace simbólico a él, como una carga normal de `CLAUDE.md`.1366Este evento no se dispara cuando Claude [lee `AGENTS.md` directamente](/docs/es/memory#agents-md) mediante el ajuste **Project instructions**. Sí se dispara cuando un `CLAUDE.md` importa tu `AGENTS.md`, con `load_reason` establecido en `include` como para cualquier otro archivo importado, y cuando `CLAUDE.md` es un enlace simbólico a él, como una carga normal de `CLAUDE.md`.
1367 1367
1368El matcher se ejecuta contra `load_reason`. Por ejemplo, use `"matcher": "session_start"` para dispararse solo para archivos cargados al inicio de la sesión, o `"matcher": "path_glob_match|nested_traversal"` para dispararse solo para cargas perezosas.1368El matcher se evalúa contra `load_reason`. Por ejemplo, usa `"matcher": "session_start"` para dispararse solo con los archivos cargados al inicio de la sesión, o `"matcher": "path_glob_match|nested_traversal"` para dispararse solo con las cargas diferidas.
1369 1369
1370<h4 id="instructionsloaded-input">1370<h4 id="instructionsloaded-input">
1371 Entrada de InstructionsLoaded1371 Entrada de InstructionsLoaded
1376| Campo | Descripción |1376| Campo | Descripción |
1377| :- | :- |1377| :- | :- |
1378| `file_path` | Ruta absoluta al archivo de instrucciones que se cargó |1378| `file_path` | Ruta absoluta al archivo de instrucciones que se cargó |
1379| `memory_type` | Alcance del archivo: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |1379| `memory_type` | Alcance del archivo: `"User"`, `"Project"`, `"Local"` o `"Managed"` |
1380| `load_reason` | Por qué se cargó el archivo: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"`, o `"compact"`. El valor `"compact"` se dispara cuando los archivos de instrucciones se recargan después de un evento de compactación |1380| `load_reason` | Por qué se cargó el archivo: `"session_start"`, `"nested_traversal"`, `"path_glob_match"`, `"include"` o `"compact"`. El valor `"compact"` se dispara cuando los archivos de instrucciones se vuelven a cargar después de un evento de compactación |
1381| `globs` | Patrones de glob de ruta del frontmatter `paths:` del archivo, si los hay. Presente solo para cargas `path_glob_match` |1381| `globs` | Patrones glob de rutas del frontmatter `paths:` del archivo, si los hay. Presente solo en las cargas `path_glob_match` |
1382| `trigger_file_path` | Ruta al archivo cuyo acceso disparó esta carga, para cargas perezosas |1382| `trigger_file_path` | Ruta al archivo cuyo acceso activó esta carga, en las cargas diferidas |
1383| `parent_file_path` | Ruta al archivo de instrucciones padre que incluyó este, para cargas `include` |1383| `parent_file_path` | Ruta al archivo de instrucciones padre que incluyó este, en las cargas `include` |
1384 1384
1385```json theme={null}1385```json theme={null}
1386{1386{
1395```1395```
1396 1396
1397<h4 id="instructionsloaded-decision-control">1397<h4 id="instructionsloaded-decision-control">
1398 Control de decisión de InstructionsLoaded1398 Control de decisiones de InstructionsLoaded
1399</h4>1399</h4>
1400 1400
1401Los 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.1401Los hooks InstructionsLoaded no tienen control de decisiones. No pueden bloquear ni modificar la carga de instrucciones. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage` y `continue`. Usa este evento para registros de auditoría, seguimiento de cumplimiento u observabilidad.
1402 1402
1403<h3 id="userpromptsubmit">1403<h3 id="userpromptsubmit">
1404 UserPromptSubmit1404 UserPromptSubmit
1405</h3>1405</h3>
1406 1406
1407Se ejecuta cuando el usuario envía un prompt, antes de que Claude lo procese. Esto le permite agregar contexto adicional basado en el prompt/conversación, validar prompts o bloquear ciertos tipos de prompts.1407Se ejecuta cuando se envía un prompt, antes de que Claude lo procese. Esto te permite
1408agregar contexto adicional según el prompt o la conversación, validar prompts o
1409bloquear ciertos tipos de prompts.
1408 1410
1409Los hooks `UserPromptSubmit` tienen un tiempo de espera predeterminado de 30 segundos para tipos `command`, `http` y `mcp_tool`, más corto que el predeterminado de 600 segundos para esos tipos en la mayoría de otros eventos. Debido a que este hook se ejecuta antes de cada prompt y bloquea el procesamiento del modelo hasta que se completa, un hook atascado detiene la sesión. Si su hook necesita más tiempo, establezca el campo `timeout` en la entrada del hook.1411Los hooks `UserPromptSubmit` no se disparan solo con los prompts que escribes. Claude Code también los ejecuta cuando:
1410 1412
1411Aparte 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ó.1413* Se dispara una [tarea programada](/docs/es/scheduled-tasks), incluida una iteración de `/loop`
1414* Un [subagente en segundo plano](/docs/es/sub-agents#run-subagents-in-foreground-or-background) informa a la sesión que lo inició
1415* Llega a tu conversación principal un [mensaje que envía otra sesión](/docs/es/cross-session-messaging)
1412 1416
1413Un [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.1417Los hooks `UserPromptSubmit` tienen un tiempo de espera predeterminado de 30 segundos para los tipos `command`, `http` y `mcp_tool`, más corto que el predeterminado de 600 segundos para esos tipos en la mayoría de los demás eventos. Como este hook se ejecuta antes de cada prompt y bloquea el procesamiento del modelo hasta que termina, un hook atascado detiene la sesión. Si tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.
1418
1419Salvo un hook de comando que ejecutas con [`async: true`](#run-hooks-in-the-background), un hook de comando, HTTP o de herramienta MCP de `UserPromptSubmit` que agota su tiempo de espera se cancela y su salida, incluido cualquier `additionalContext`, se descarta. El prompt sigue llegando a Claude sin ese contexto. La transcripción muestra un aviso que nombra el hook, el tiempo de espera que se agotó y que la salida se descartó.
1420
1421Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `UserPromptSubmit` que agota su tiempo de espera bloquea el prompt con un mensaje que nombra el hook y el tiempo de espera, porque un callback ahí puede actuar como una barrera de políticas que no debe fallar en abierto. La sesión continúa. Antes de la v2.1.208, un tiempo de espera agotado de un callback en ese evento terminaba el turno con un error de ejecución.
1414 1422
1415<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">
1416 Entrada de UserPromptSubmit1424 Entrada de UserPromptSubmit
1417</h4>1425</h4>
1418 1426
1419Ademá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.1427Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptSubmit reciben el campo `prompt` con el texto enviado. El contenido pegado que se contrajo en un marcador de posición `[Pasted text #N]` llega expandido en su lugar. En las sesiones en las que Claude Code [marca el texto pegado para Claude](/docs/es/terminal-config#how-claude-treats-pasted-text), ese contenido expandido se sitúa entre una línea `<pasted_content id="…">` y una línea `</pasted_content id="…">`, así que ten en cuenta esas líneas si tu hook analiza el prompt.
1420 1428
1421Los hooks UserPromptSubmit también reciben `session_title` cuando la sesión tiene un título personalizado, con el mismo significado que el [campo `session_title` de SessionStart](#sessionstart-input).1429Los hooks UserPromptSubmit también reciben `session_title` cuando la sesión tiene un título personalizado, con el mismo significado que el [campo `session_title` de SessionStart](#sessionstart-input).
1422 1430
1432```1440```
1433 1441
1434<h4 id="userpromptsubmit-decision-control">1442<h4 id="userpromptsubmit-decision-control">
1435 Control de decisión de UserPromptSubmit1443 Control de decisiones de UserPromptSubmit
1436</h4>1444</h4>
1437 1445
1438Los hooks `UserPromptSubmit` pueden controlar si se procesa un prompt de usuario y agregar contexto. Todos los [campos de salida JSON](#json-output) están disponibles.1446Los hooks `UserPromptSubmit` pueden controlar si se procesa un prompt enviado y agregar contexto. Todos los [campos de salida JSON](#json-output) están disponibles.
1439 1447
1440Hay dos formas de agregar contexto a la conversación en código de salida 0:1448Hay dos formas de agregar contexto a la conversación con el código de salida 0:
1441 1449
1442* **Stdout de texto plano**: Claude Code agrega stdout que [trata como texto plano](#exit-code-0) al contexto de Claude1450* **Stdout en texto plano**: Claude Code agrega al contexto de Claude la stdout que [trata como texto plano](#exit-code-0)
1443* **JSON con `additionalContext`**: use el formato JSON a continuación para más control. El campo `additionalContext` se agrega como contexto1451* **JSON con `additionalContext`**: usa el formato JSON siguiente para tener más control. El campo `additionalContext` se agrega como contexto
1444 1452
1445Ningún canal produce una entrada de transcripción visible. El stdout plano y el valor `additionalContext` se inyectan cada uno como un recordatorio del sistema que comienza con el nombre del hook; Claude lee ambos. Para confirmar la entrega, verifique el [registro de depuración](#debug-hooks).1453Ninguno de los dos canales produce una entrada visible en la transcripción. La stdout en texto plano y el valor de `additionalContext` se inyectan cada uno como un recordatorio del sistema que comienza con el nombre del hook; Claude lee ambos. Para confirmar la entrega, revisa el [registro de depuración](#debug-hooks).
1446 1454
1447Para bloquear un prompt, devuelva un objeto JSON con `decision` establecido en `"block"`:1455Para bloquear un prompt, devuelve un objeto JSON con `decision` establecido en `"block"`:
1448 1456
1449| Campo | Descripción |1457| Campo | Descripción |
1450| :- | :- |1458| :- | :- |
1451| `decision` | `"block"` detiene el prompt antes de que llegue a Claude. Omita para permitir que el prompt continúe |1459| `decision` | `"block"` detiene el prompt antes de que llegue a Claude. Omítelo para permitir que el prompt continúe |
1452| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se agrega al contexto |1460| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se agrega al contexto |
1453| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1461| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
1454| `sessionTitle` | Establece el título de la sesión. Úselo para nombrar sesiones automáticamente basándose en el contenido del prompt |1462| `sessionTitle` | Establece el título de la sesión. Úsalo para nombrar sesiones automáticamente según el contenido del prompt |
1455| `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) |1463| `suppressOriginalPrompt` | Si es `true` cuando el hook bloquea el prompt, deja el texto del prompt fuera del mensaje de bloqueo. Consulta [Lo que deja un prompt bloqueado](#what-a-blocked-prompt-leaves-behind) |
1456 1464
1457Un 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.1465Un hook que bloquea saliendo con 2 se encamina igual que `reason`: el mensaje de bloqueo muestra el texto de stderr al usuario y no se agrega al contexto.
1458 1466
1459```json theme={null}1467```json theme={null}
1460{1468{
1470```1478```
1471 1479
1472<h4 id="what-a-blocked-prompt-leaves-behind">1480<h4 id="what-a-blocked-prompt-leaves-behind">
1473 Lo que un prompt bloqueado deja atrás1481 Lo que deja un prompt bloqueado
1474</h4>1482</h4>
1475 1483
1476Un 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.1484Un prompt bloqueado nunca llega a Claude, pero su texto no se elimina de todas partes. De forma predeterminada, el mensaje de bloqueo que se muestra 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 disco. Para dejar el texto fuera del mensaje, imprime JSON con `"suppressOriginalPrompt": true` dentro de `hookSpecificOutput`. Esto funciona tanto si el hook bloquea con `decision: "block"` como si lo hace saliendo con 2. Un hook que sale con 2 y no imprime JSON siempre incluye el texto del prompt en su mensaje de bloqueo.
1477 1485
1478`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).1486`suppressOriginalPrompt` solo cambia el mensaje de bloqueo. El texto enviado puede seguir apareciendo en archivos locales, como la transcripción de la sesión y tu historial de prompts, así que un hook de bloqueo no es una forma de mantener un secreto fuera del disco. Para limitar o eliminar esos archivos, consulta [Almacenamiento en texto plano](/docs/es/claude-directory#plaintext-storage) y [Borrar datos locales](/docs/es/claude-directory#clear-local-data).
1479 1487
1480<h3 id="userpromptexpansion">1488<h3 id="userpromptexpansion">
1481 UserPromptExpansion1489 UserPromptExpansion
1482</h3>1490</h3>
1483 1491
1484Se 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`.1492Se ejecuta cuando un comando escrito por el usuario se expande en un prompt antes de llegar a Claude. Úsalo para impedir la invocación directa de comandos específicos, inyectar contexto para un skill en particular o registrar qué comandos invocan los usuarios. Por ejemplo, un hook que coincide con `deploy` puede bloquear `/deploy` a menos que exista un archivo de aprobación, o un hook que coincide con un skill de revisión puede anexar la lista de verificación de revisión del equipo como `additionalContext`.
1485 1493
1486Este 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.1494Este 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 evita `PreToolUse`. `UserPromptExpansion` se dispara en esa ruta directa.
1487 1495
1488Coincide en `command_name`. Deje el matcher vacío para dispararse en cada comando de tipo prompt.1496Coincide con `command_name`. Deja el matcher vacío para dispararse con cada comando de tipo prompt.
1489 1497
1490<h4 id="userpromptexpansion-input">1498<h4 id="userpromptexpansion-input">
1491 Entrada de UserPromptExpansion1499 Entrada de UserPromptExpansion
1492</h4>1500</h4>
1493 1501
1494Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptExpansion reciben `expansion_type`, `command_name`, `command_args`, `command_source` y la cadena `prompt` original. El campo `expansion_type` es `slash_command` para skills y comandos personalizados, o `mcp_prompt` para prompts del servidor MCP.1502Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptExpansion reciben `expansion_type`, `command_name`, `command_args`, `command_source` y la cadena `prompt` original. El campo `expansion_type` es `slash_command` para skills y comandos personalizados, o `mcp_prompt` para los prompts de servidores MCP.
1495 1503
1496```json theme={null}1504```json theme={null}
1497{1505{
1509```1517```
1510 1518
1511<h4 id="userpromptexpansion-decision-control">1519<h4 id="userpromptexpansion-decision-control">
1512 Control de decisión de UserPromptExpansion1520 Control de decisiones de UserPromptExpansion
1513</h4>1521</h4>
1514 1522
1515Los hooks `UserPromptExpansion` pueden bloquear la expansión o agregar contexto. Todos los [campos de salida JSON](#json-output) están disponibles.1523Los hooks `UserPromptExpansion` pueden bloquear la expansión o agregar contexto. Todos los [campos de salida JSON](#json-output) están disponibles.
1516 1524
1517| Campo | Descripción |1525| Campo | Descripción |
1518| :- | :- |1526| :- | :- |
1519| `decision` | `"block"` evita que el comando se expanda. Omita para permitir que continúe |1527| `decision` | `"block"` impide que el comando se expanda. Omítelo para permitir que continúe |
1520| `reason` | Se muestra al usuario cuando `decision` es `"block"` |1528| `reason` | Se muestra al usuario cuando `decision` es `"block"` |
1521| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt expandido. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1529| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt expandido. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
1522 1530
1523Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario.1531Un hook que bloquea saliendo con 2 se encamina igual que `reason`: el mensaje de bloqueo muestra el texto de stderr al usuario.
1524 1532
1525```json theme={null}1533```json theme={null}
1526{1534{
1537 MessageDisplay1545 MessageDisplay
1538</h3>1546</h3>
1539 1547
1540Se ejecuta mientras un mensaje del asistente se transmite a la pantalla. Claude Code muestra el mensaje en incrementos: cada vez que un lote de líneas recién completadas está listo para renderizar, el hook se ejecuta una vez con esas líneas y Claude Code renderiza el texto de reemplazo del hook en su lugar. Un mensaje largo produce varias llamadas; un mensaje corto puede producir solo una.1548Se ejecuta mientras un mensaje del asistente se transmite a la pantalla. Claude Code muestra el mensaje en incrementos: cada vez que un lote de líneas recién completadas está listo para renderizarse, el hook se ejecuta una vez con esas líneas y Claude Code renderiza el texto de reemplazo del hook en su lugar. Un mensaje largo produce varias llamadas; un mensaje corto puede producir solo una.
1541 1549
1542Use MessageDisplay para:1550Usa MessageDisplay para:
1543 1551
1544* eliminar markdown para una visualización mínima1552* quitar el markdown para una visualización mínima
1545* transformar el texto que una aplicación del Agent SDK muestra a sus usuarios1553* transformar el texto que una aplicación del Agent SDK muestra a sus usuarios
1546* redactar claves API o nombres de host internos de las respuestas de Claude1554* ocultar claves de API o nombres de host internos de las respuestas de Claude
1547 1555
1548Claude 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.1556Claude Code retiene cada lote hasta que tu hook devuelve, así que mantén el hook rápido. Si el hook falla o se agota su tiempo de espera, Claude Code muestra el texto original. El tiempo de espera predeterminado de este evento es de 10 segundos; si tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.
1549 1557
1550MessageDisplay es solo para visualización: el texto de reemplazo cambia solo lo que se renderiza en pantalla. La transcripción y lo que Claude ve mantienen el texto original, por lo que Claude nunca ve el reemplazo, y el modo detallado muestra el original. El hook recibe solo texto de mensaje del asistente, por lo que los resultados de herramientas y el texto que escribe se renderiza sin cambios.1558MessageDisplay es solo de visualización: el texto de reemplazo cambia solo lo que se renderiza en pantalla. La transcripción y lo que ve Claude conservan el texto original, así que Claude nunca ve el reemplazo, y el modo detallado muestra el original. El hook recibe solo el texto de los mensajes del asistente, por lo que los resultados de herramientas y el texto que escribes se renderizan sin cambios.
1551 1559
1552MessageDisplay 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.1560MessageDisplay no admite matchers y se dispara con cada mensaje del asistente que transmite texto; los mensajes sin texto, como las respuestas que solo contienen llamadas a herramientas, no lo activan.
1553 1561
1554En 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.1562En las ejecuciones no interactivas, incluidas las 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 única llamada llega después de que el mensaje se completa y lleva el texto completo del mensaje: `index` es `0`, `final` es `true` y `delta` contiene el mensaje entero. Un hook que recopila el texto de `delta` de cada mensaje recibe el mismo texto total en ambos modos.
1555 1563
1556<h4 id="messagedisplay-input">1564<h4 id="messagedisplay-input">
1557 Entrada de MessageDisplay1565 Entrada de MessageDisplay
1558</h4>1566</h4>
1559 1567
1560Además de los [campos de entrada comunes](#common-input-fields), los hooks MessageDisplay reciben identificadores para el turno y el mensaje, la posición de esta llamada dentro del mensaje y el nuevo texto en `delta`. Los límites de lotes dependen de cómo se transmite el texto, así que use `index` y `final` para rastrear el progreso a través de un mensaje en lugar de esperar que las líneas se agrupen de una manera particular.1568Además de los [campos de entrada comunes](#common-input-fields), los hooks MessageDisplay reciben identificadores del turno y del mensaje, la posición de esta llamada dentro del mensaje y el texto nuevo en `delta`. Los límites de los lotes dependen de cómo se transmite el texto, así que usa `index` y `final` para seguir el progreso a lo largo de un mensaje en lugar de esperar que las líneas se agrupen de una forma particular.
1561 1569
1562| Campo | Descripción |1570| Campo | Descripción |
1563| :- | :- |1571| :- | :- |
1564| `turn_id` | UUID del turno actual |1572| `turn_id` | UUID del turno actual |
1565| `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 |1573| `message_id` | UUID del mensaje del asistente que se está mostrando. Es estable en todos los lotes del mismo mensaje. No es el id `msg_…` de la API, así que no se puede correlacionar con los ids de los mensajes de la transcripción |
1566| `index` | Índice basado en cero de este lote dentro del mensaje |1574| `index` | Índice, con base cero, de este lote dentro del mensaje |
1567| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |1575| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |
1568| `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 |1576| `delta` | Las líneas recién completadas desde el lote anterior, incluidos los saltos de línea finales. Siempre son líneas completas, excepto el lote final, que puede terminar a mitad de línea. En las ejecuciones interactivas, el delta del lote final está vacío cuando el mensaje termina en un salto de línea, así que trata `final`, y no un delta no vacío, como la señal de fin de mensaje. En las ejecuciones del Agent SDK y de `claude -p`, la única llamada lleva el mensaje completo |
1569 1577
1570```json theme={null}1578```json theme={null}
1571{1579{
1589 1597
1590| Campo | Descripción |1598| Campo | Descripción |
1591| :- | :- |1599| :- | :- |
1592| `displayContent` | Texto mostrado en lugar del delta. Omítalo para mostrar el original |1600| `displayContent` | Texto que se muestra en lugar del delta. Omítelo para mostrar el original |
1593 1601
1594Los 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`.1602Los hooks MessageDisplay no tienen control de decisiones. No pueden bloquear el mensaje ni 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`.
1595 1603
1596Este 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`.1604Este ejemplo quita el formato markdown de las respuestas de Claude para una visualización en texto plano. El script lee cada lote desde stdin, elimina los marcadores de negrita y las comillas invertidas del código en línea de `delta`, y devuelve el resultado como `displayContent`.
1597 1605
1598<Tabs>1606<Tabs>
1599 <Tab title="macOS/Linux">1607 <Tab title="macOS/Linux">
1600 Registre un hook de comando para el evento en su archivo de configuración:1608 Registra un hook de comando para el evento en tu archivo de configuración:
1601 1609
1602 ```json theme={null}1610 ```json theme={null}
1603 {1611 {
1617 }1625 }
1618 ```1626 ```
1619 1627
1620 Guarde este script en `.claude/hooks/plain-display.sh` en su proyecto y hágalo ejecutable con `chmod +x`:1628 Guarda este script en `.claude/hooks/plain-display.sh` en tu proyecto y hazlo ejecutable con `chmod +x`:
1621 1629
1622 ```bash theme={null}1630 ```bash theme={null}
1623 #!/bin/bash1631 #!/bin/bash
1626 </Tab>1634 </Tab>
1627 1635
1628 <Tab title="Windows (PowerShell)">1636 <Tab title="Windows (PowerShell)">
1629 Registre un hook de comando que ejecute el script a través de PowerShell:1637 Registra un hook de comando que ejecute el script mediante PowerShell:
1630 1638
1631 ```json theme={null}1639 ```json theme={null}
1632 {1640 {
1652 }1660 }
1653 ```1661 ```
1654 1662
1655 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.1663 El flag `-NoProfile` omite la carga de tu perfil de PowerShell para que el hook arranque rápido, y `-ExecutionPolicy Bypass` permite que PowerShell ejecute el archivo de script local.
1656 1664
1657 Guarde este script en `.claude/hooks/plain-display.ps1` en su proyecto:1665 Guarda este script en `.claude/hooks/plain-display.ps1` en tu proyecto:
1658 1666
1659 ```powershell theme={null}1667 ```powershell theme={null}
1660 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1668 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1669 </Tab>1677 </Tab>
1670</Tabs>1678</Tabs>
1671 1679
1672Los lotes sin markdown pasan sin cambios. Si el script falla, por ejemplo porque falta `jq`, Claude Code muestra el texto original y solo nota el fallo en [salida de depuración](#debug-hooks), no en la sesión.1680Los lotes sin markdown pasan sin cambios. Si el script falla, por ejemplo porque falta `jq`, Claude Code muestra el texto original y anota el fallo solo en la [salida de depuración](#debug-hooks), no en la sesión.
1673 1681
1674<h3 id="pretooluse">1682<h3 id="pretooluse">
1675 PreToolUse1683 PreToolUse
1676</h3>1684</h3>
1677 1685
1678Se ejecuta después de que Claude crea parámetros de herramienta y antes de procesar la llamada de herramienta. Coincide en cualquier nombre de herramienta excepto `EndConversation`: herramientas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion`, y `ExitPlanMode`, y cualquier [nombre de herramienta MCP](#match-mcp-tools).1686Se ejecuta después de que Claude crea los parámetros de la herramienta y antes de procesar la llamada a herramienta. Coincide con cualquier nombre de herramienta excepto `EndConversation`: herramientas integradas como `Bash`, `PowerShell`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, `Agent`, `Workflow`, `WebFetch`, `WebSearch`, `AskUserQuestion` y `ExitPlanMode`, y cualquier [nombre de herramienta MCP](#match-mcp-tools).
1679 1687
1680Para 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.1688Para ejecutar un hook cuando un archivo específico cambia en disco, sin importar qué lo escribió, usa [FileChanged](#filechanged) en lugar de hacer coincidir por nombre las herramientas de edición de archivos. A diferencia de PreToolUse, Claude Code ejecuta los hooks FileChanged después del cambio, y no tienen control de decisiones, así que no pueden bloquear la escritura.
1681 1689
1682<Warning>1690<Warning>
1683 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.1691 PreToolUse solo se ejecuta cuando Claude llama a una herramienta. Los archivos que [referencias con `@` en tu prompt](/docs/es/common-workflows#reference-files-and-directories) se agregan sin ninguna llamada a herramienta: Claude Code inserta su contenido mientras construye el prompt, así que no se dispara ningún hook PreToolUse para ellos, incluidos los hooks que coinciden con `Read`. Para bloquear rutas específicas de las referencias con `@`, usa una [regla de denegación de `Read`](/docs/es/permissions#read-and-edit) en su lugar.
1684 1692
1685 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).1693 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).
1686</Warning>1694</Warning>
1687 1695
1688Use [control de decisión PreToolUse](#pretooluse-decision-control) para permitir, denegar, preguntar o diferir la llamada de herramienta.1696Usa el [control de decisiones de PreToolUse](#pretooluse-decision-control) para permitir, denegar, preguntar o diferir la llamada a herramienta.
1689 1697
1690Un [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.1698Un [hook de callback del Agent SDK](/docs/es/agent-sdk/hooks) en `PreToolUse` que supera su tiempo de espera bloquea la llamada a herramienta, y Claude recibe un resultado de error que nombra el tiempo de espera. Una denegación explícita devuelta por otro hook sigue teniendo precedencia.
1691 1699
1692<h4 id="pretooluse-input">1700<h4 id="pretooluse-input">
1693 Entrada de PreToolUse1701 Entrada de PreToolUse
1694</h4>1702</h4>
1695 1703
1696Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input`, y `tool_use_id`.1704Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input` y `tool_use_id`.
1697 1705
1698Para 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.1706Para una [herramienta MCP](#match-mcp-tools), la entrada también lleva `mcp_server`, un objeto con el `name` del servidor y un `source` que indica de dónde proviene la definición del servidor. Los valores de `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 e indica cómo tratar uno que no reconozcas. Basa 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.
1699 1707
1700Para las herramientas de archivo `Write`, `Edit`, y `Read`, `tool_input.file_path` siempre es absoluto:1708Para las herramientas de archivos `Write`, `Edit` y `Read`, `tool_input.file_path` siempre es absoluta:
1701 1709
1702* Claude Code expande `~` y rutas relativas antes de que se ejecuten los hooks, por lo que un hook que coincide en rutas no puede ser eludido a través de `~` o un deletreo relativo de la misma ruta1710* Claude Code expande `~` y las rutas relativas antes de que se ejecuten los hooks, así que un hook que coincide con rutas no se puede eludir mediante `~` o una forma relativa de escribir la misma ruta
1703* En Windows, la ruta llega con separadores de barra invertida, incluso cuando su hook se ejecuta bajo Git Bash donde `$PWD` se ve como `/c/project`1711* En Windows, la ruta llega con separadores de barra invertida, incluso cuando tu hook se ejecuta en Git Bash, donde `$PWD` se ve como `/c/project`
1704* Una comparación escrita con barras diagonales, como una verificación `/src/`, nunca coincide con una ruta de barra invertida, y la llamada de herramienta continúa como si el hook no tuviera nada que bloquear1712* Una comparación escrita con barras diagonales, como una comprobación de `/src/`, nunca coincide con una ruta con barras invertidas, y la llamada a herramienta continúa como si el hook no tuviera nada que bloquear
1705* Normalice separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` en Bash, o `file_path.replace("\\", "/")` en Python, luego coincida con un segmento de ruta como `/src/` en lugar de anclar con `^`, ya que la ruta es absoluta1713* Normaliza los separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` en Bash, o `file_path.replace("\\", "/")` en Python, y luego haz coincidir un segmento de ruta como `/src/` en lugar de anclar con `^`, ya que la ruta es absoluta
1706 1714
1707Una llamada `Write` en Windows entrega:1715Una llamada a `Write` en Windows entrega:
1708 1716
1709```json theme={null}1717```json theme={null}
1710{1718{
1718}1726}
1719```1727```
1720 1728
1721Los campos `tool_input` dependen de la herramienta:1729Los campos de `tool_input` dependen de la herramienta:
1722 1730
1723<a id="bash" />1731<a id="bash" />
1724 1732
1726 Bash1734 Bash
1727</h5>1735</h5>
1728 1736
1729Ejecuta comandos de shell.1737Ejecuta comandos del shell.
1730 1738
1731| Campo | Tipo | Ejemplo | Descripción |1739| Campo | Tipo | Ejemplo | Descripción |
1732| :- | :- | :- | :- |1740| :- | :- | :- | :- |
1733| `command` | string | `"npm test"` | El comando de shell a ejecutar |1741| `command` | string | `"npm test"` | El comando del shell que se ejecutará |
1734| `description` | string | `"Run test suite"` | Descripción opcional de lo que hace el comando |1742| `description` | string | `"Run test suite"` | Descripción opcional de lo que hace el comando |
1735| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos. Los valores por encima del [máximo](/docs/es/tools-reference#bash-tool-behavior) se reducen al máximo en lugar de ser rechazados |1743| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos. Los valores por encima del [máximo](/docs/es/tools-reference#bash-tool-behavior) se reducen al máximo en lugar de rechazarse |
1736| `run_in_background` | boolean | `false` | Si se ejecuta el comando en segundo plano |1744| `run_in_background` | boolean | `false` | Si el comando se ejecuta en segundo plano |
1737 1745
1738Cuando un comando Bash cambia archivos en un repositorio Git, Claude Code puede registrar qué cambió. Registra los cambios en cada modo de permiso cuando la configuración [`bashEditDiffEnabled`](/docs/es/settings-reference#basheditdiffenabled) activa el registro; la entrada de esa configuración dice qué archivos pueden establecerla. De lo contrario, solo los registra en modo automático y modo `bypassPermissions`, y solo cuando Claude Code dirige a Claude a editar archivos a través de Bash. Establezca `bashEditDiffEnabled` en `false` para desactivar el registro. Los comandos de fondo y los comandos de solo lectura no llevan diff.1746Cuando un comando Bash cambia archivos en un repositorio Git, Claude Code puede registrar lo que cambió. Registra los cambios en todos los modos de permisos cuando el ajuste [`bashEditDiffEnabled`](/docs/es/settings-reference#basheditdiffenabled) activa el registro; la entrada de ese ajuste indica qué archivos pueden establecerlo. De lo contrario, solo los registra en modo automático y en modo `bypassPermissions`, y solo cuando Claude Code indica a Claude que edite archivos mediante Bash. Establece `bashEditDiffEnabled` en `false` para desactivar el registro. Los comandos en segundo plano y los comandos de solo lectura no llevan diff.
1739 1747
1740Su [hook PostToolUse](#posttooluse) luego recibe los archivos cambiados en `tool_response.bashEditDiff`. La lista cubre qué cambió bajo el repositorio mientras se ejecutaba el comando. Los archivos que Git ignora y los archivos en submódulos no se enumeran. Requiere Claude Code v2.1.269 o posterior.1748Tu [hook PostToolUse](#posttooluse) recibe entonces los archivos modificados en `tool_response.bashEditDiff`. La lista cubre lo que cambió dentro del repositorio mientras se ejecutaba el comando. Los archivos que Git ignora y los archivos de los submódulos no se incluyen. Requiere Claude Code v2.1.269 o posterior.
1741 1749
1742<Note>1750<Note>
1743 La lista es mejor esfuerzo y en beta pública. Claude Code puede perder un cambio, incluir un archivo que otro proceso cambió al mismo tiempo, o detenerse en sus límites de tamaño. La forma del campo puede cambiar. Use la lista para encontrar qué revisar, no para hacer cumplir una política.1751 La lista es de mejor esfuerzo y está en beta pública. Claude Code puede pasar por alto un cambio, incluir un archivo que otro proceso cambió al mismo tiempo o detenerse en sus límites de tamaño. La forma del campo puede cambiar. Usa la lista para encontrar qué revisar, no para aplicar una política.
1744</Note>1752</Note>
1745 1753
1746`changedFiles` y `files` enumeran qué cambió el comando; los campos restantes dicen qué tan completa y confiable es esa lista.1754`changedFiles` y `files` enumeran lo que cambió el comando; los campos restantes indican qué tan completa y qué tan fiable es esa lista.
1747 1755
1748| Campo | Tipo | Ejemplo | Descripción |1756| Campo | Tipo | Ejemplo | Descripción |
1749| :- | :- | :- | :- |1757| :- | :- | :- | :- |
1750| `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 |1758| `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` sea mayor que cero |
1751| `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ó |1759| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de hasta 5 archivos modificados, para mostrar. `created` o `deleted` es `true` para un archivo que el comando agregó o eliminó |
1752| `moreFiles` | number | `2` | Recuento de archivos cambiados sin diff en `files` |1760| `moreFiles` | number | `2` | Cantidad de archivos modificados sin diff en `files` |
1753| `unavailable` | boolean | `true` | Se establece cuando el diff está incompleto o no se pudo tomar |1761| `unavailable` | boolean | `true` | Se establece cuando el diff está incompleto o no se pudo obtener |
1754| `skipped` | boolean | `true` | Se establece para un comando Git que mueve el árbol de trabajo, como `git checkout` o `git stash`, por lo que Claude Code no toma diff |1762| `skipped` | boolean | `true` | Se establece para un comando de Git que mueve el árbol de trabajo, como `git checkout` o `git stash`, de modo que Claude Code no obtiene ningún diff |
1755| `shared` | boolean | `true` | Se establece cuando otra llamada de herramienta Bash, como la de un subagente, se ejecutó en el mismo repositorio al mismo tiempo, por lo que algunos cambios enumerados pueden ser de ese comando |1763| `shared` | boolean | `true` | Se establece cuando otra llamada a la herramienta Bash, como la de un subagente, se ejecutó en el mismo repositorio al mismo tiempo, por lo que algunos cambios enumerados pueden ser de ese comando |
1756 1764
1757<a id="powershell" />1765<a id="powershell" />
1758 1766
1760 PowerShell1768 PowerShell
1761</h5>1769</h5>
1762 1770
1763Ejecuta comandos de PowerShell. Consulte la [herramienta PowerShell](/docs/es/tools-reference#powershell-tool) para disponibilidad por plataforma.1771Ejecuta comandos de PowerShell. Consulta la [herramienta PowerShell](/docs/es/tools-reference#powershell-tool) para conocer la disponibilidad por plataforma.
1764 1772
1765Los campos coinciden con la herramienta Bash, con la cadena de comando en `command`:1773Los campos coinciden con los de la herramienta Bash, con la cadena del comando en `command`:
1766 1774
1767| Campo | Tipo | Ejemplo | Descripción |1775| Campo | Tipo | Ejemplo | Descripción |
1768| :- | :- | :- | :- |1776| :- | :- | :- | :- |
1769| `command` | string | `"Get-ChildItem -Recurse"` | El comando de PowerShell a ejecutar |1777| `command` | string | `"Get-ChildItem -Recurse"` | El comando de PowerShell que se ejecutará |
1770| `description` | string | `"List files recursively"` | Descripción opcional de lo que hace el comando |1778| `description` | string | `"List files recursively"` | Descripción opcional de lo que hace el comando |
1771| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos |1779| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos |
1772| `run_in_background` | boolean | `false` | Si se ejecuta el comando en segundo plano |1780| `run_in_background` | boolean | `false` | Si el comando se ejecuta en segundo plano |
1773 1781
1774Coincida con `Bash|PowerShell` en hooks que inspeccionan comandos de shell, para que cubran ambas herramientas:1782Haz coincidir `Bash|PowerShell` en los hooks que inspeccionan comandos del shell, para que cubran ambas herramientas:
1775 1783
1776* En Windows, dondequiera que la herramienta PowerShell esté habilitada, Claude trata PowerShell como el shell principal y enruta comandos de shell a través de él.1784* En Windows, dondequiera que la herramienta PowerShell esté habilitada, Claude trata PowerShell como el shell principal y encamina los comandos del shell a través de él.
1777* En Windows sin Git Bash, la herramienta se habilita automáticamente y Claude Code no registra la herramienta Bash en absoluto.1785* En Windows sin Git Bash, la herramienta se habilita automáticamente y Claude Code no registra la herramienta Bash en absoluto.
1778* Un hook que coincide solo con `Bash` nunca se dispara allí.1786* Un hook que solo coincide con `Bash` nunca se dispara ahí.
1779 1787
1780<h5 id="write">1788<h5 id="write">
1781 Write1789 Write
1785 1793
1786| Campo | Tipo | Ejemplo | Descripción |1794| Campo | Tipo | Ejemplo | Descripción |
1787| :- | :- | :- | :- |1795| :- | :- | :- | :- |
1788| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo a escribir |1796| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo que se escribirá |
1789| `content` | string | `"file content"` | Contenido a escribir en el archivo |1797| `content` | string | `"file content"` | Contenido que se escribirá en el archivo |
1790 1798
1791<h5 id="edit">1799<h5 id="edit">
1792 Edit1800 Edit
1796 1804
1797| Campo | Tipo | Ejemplo | Descripción |1805| Campo | Tipo | Ejemplo | Descripción |
1798| :- | :- | :- | :- |1806| :- | :- | :- | :- |
1799| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo a editar |1807| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo que se editará |
1800| `old_string` | string | `"original text"` | Texto a encontrar y reemplazar |1808| `old_string` | string | `"original text"` | Texto que se buscará y reemplazará |
1801| `new_string` | string | `"replacement text"` | Texto de reemplazo |1809| `new_string` | string | `"replacement text"` | Texto de reemplazo |
1802| `replace_all` | boolean | `false` | Si se reemplazan todas las ocurrencias |1810| `replace_all` | boolean | `false` | Si se reemplazan todas las apariciones |
1803 1811
1804<h5 id="read">1812<h5 id="read">
1805 Read1813 Read
1806</h5>1814</h5>
1807 1815
1808Lee contenidos de archivo.1816Lee el contenido de archivos.
1809 1817
1810| Campo | Tipo | Ejemplo | Descripción |1818| Campo | Tipo | Ejemplo | Descripción |
1811| :- | :- | :- | :- |1819| :- | :- | :- | :- |
1812| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo a leer |1820| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo que se leerá |
1813| `offset` | number | `10` | Número de línea opcional para comenzar a leer desde |1821| `offset` | number | `10` | Número de línea opcional desde el que empezar a leer |
1814| `limit` | number | `50` | Número opcional de líneas a leer |1822| `limit` | number | `50` | Número opcional de líneas que se leerán |
1815 1823
1816<h5 id="glob">1824<h5 id="glob">
1817 Glob1825 Glob
1818</h5>1826</h5>
1819 1827
1820Encuentra archivos que coinciden con un patrón glob.1828Busca archivos que coinciden con un patrón glob.
1821 1829
1822| Campo | Tipo | Ejemplo | Descripción |1830| Campo | Tipo | Ejemplo | Descripción |
1823| :- | :- | :- | :- |1831| :- | :- | :- | :- |
1824| `pattern` | string | `"**/*.ts"` | Patrón glob para hacer coincidir archivos contra |1832| `pattern` | string | `"**/*.ts"` | Patrón glob con el que comparar los archivos |
1825| `path` | string | `"/path/to/dir"` | Directorio opcional para buscar. Por defecto es el directorio de trabajo actual |1833| `path` | string | `"/path/to/dir"` | Directorio opcional en el que buscar. De forma predeterminada, el directorio de trabajo actual |
1826 1834
1827<h5 id="grep">1835<h5 id="grep">
1828 Grep1836 Grep
1829</h5>1837</h5>
1830 1838
1831Busca contenidos de archivo con expresiones regulares.1839Busca en el contenido de archivos con expresiones regulares.
1832 1840
1833| Campo | Tipo | Ejemplo | Descripción |1841| Campo | Tipo | Ejemplo | Descripción |
1834| :- | :- | :- | :- |1842| :- | :- | :- | :- |
1835| `pattern` | string | `"TODO.*fix"` | Patrón de expresión regular a buscar |1843| `pattern` | string | `"TODO.*fix"` | Patrón de expresión regular que se buscará |
1836| `path` | string | `"/path/to/dir"` | Archivo o directorio opcional para buscar en |1844| `path` | string | `"/path/to/dir"` | Archivo o directorio opcional en el que buscar |
1837| `glob` | string | `"*.ts"` | Patrón glob opcional para filtrar archivos |1845| `glob` | string | `"*.ts"` | Patrón glob opcional para filtrar archivos |
1838| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Por defecto es `"files_with_matches"` |1846| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"` o `"count"`. De forma predeterminada, `"files_with_matches"` |
1839| `-i` | boolean | `true` | Búsqueda insensible a mayúsculas y minúsculas |1847| `-i` | boolean | `true` | Búsqueda sin distinguir mayúsculas de minúsculas |
1840| `multiline` | boolean | `false` | Habilitar coincidencia multilínea |1848| `multiline` | boolean | `false` | Habilita la coincidencia multilínea |
1841 1849
1842<h5 id="webfetch">1850<h5 id="webfetch">
1843 WebFetch1851 WebFetch
1847 1855
1848| Campo | Tipo | Ejemplo | Descripción |1856| Campo | Tipo | Ejemplo | Descripción |
1849| :- | :- | :- | :- |1857| :- | :- | :- | :- |
1850| `url` | string | `"https://example.com/api"` | URL para obtener contenido de |1858| `url` | string | `"https://example.com/api"` | URL de la que obtener el contenido |
1851| `prompt` | string | `"Extract the API endpoints"` | Prompt a ejecutar en el contenido obtenido |1859| `prompt` | string | `"Extract the API endpoints"` | Prompt que se ejecutará sobre el contenido obtenido |
1852 1860
1853<h5 id="websearch">1861<h5 id="websearch">
1854 WebSearch1862 WebSearch
1859| Campo | Tipo | Ejemplo | Descripción |1867| Campo | Tipo | Ejemplo | Descripción |
1860| :- | :- | :- | :- |1868| :- | :- | :- | :- |
1861| `query` | string | `"react hooks best practices"` | Consulta de búsqueda |1869| `query` | string | `"react hooks best practices"` | Consulta de búsqueda |
1862| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluir solo resultados de estos dominios |1870| `allowed_domains` | array | `["docs.example.com"]` | Opcional: incluye solo resultados de estos dominios |
1863| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluir resultados de estos dominios |1871| `blocked_domains` | array | `["spam.example.com"]` | Opcional: excluye resultados de estos dominios |
1864 1872
1865<h5 id="agent">1873<h5 id="agent">
1866 Agent1874 Agent
1870 1878
1871| Campo | Tipo | Ejemplo | Descripción |1879| Campo | Tipo | Ejemplo | Descripción |
1872| :- | :- | :- | :- |1880| :- | :- | :- | :- |
1873| `prompt` | string | `"Find all API endpoints"` | La tarea para que el agente realice |1881| `prompt` | string | `"Find all API endpoints"` | La tarea que realizará el agente |
1874| `description` | string | `"Find API endpoints"` | Descripción breve de la tarea |1882| `description` | string | `"Find API endpoints"` | Descripción breve de la tarea |
1875| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1883| `subagent_type` | string | `"Explore"` | Tipo de agente especializado que se usará |
1876| `model` | string | `"sonnet"` | Alias de modelo opcional para anular el predeterminado |1884| `model` | string | `"sonnet"` | Alias de modelo opcional para sobrescribir el predeterminado |
1877 1885
1878Cuando una llamada Agent en primer plano se completa, su [hook PostToolUse](#posttooluse) recibe el resultado del subagente y la telemetría de ejecución en `tool_response`. Lea estos campos para inspeccionar la ejecución; para resúmenes de tokens y costos en subagentes, use los [contadores de tokens y costos](/docs/es/monitoring-usage#token-counter) filtrados a `query_source` `"subagent"`, ya que `totalTokens` y `usage` cubren solo la solicitud final:1886Cuando una llamada a Agent en primer plano termina, tu [hook PostToolUse](#posttooluse) recibe el resultado del subagente y la telemetría de la ejecución en `tool_response`. Lee estos campos para inspeccionar la ejecución; para totales de tokens y costos entre subagentes, usa los [contadores de tokens y costos](/docs/es/monitoring-usage#token-counter) filtrados por `query_source` `"subagent"`, ya que `totalTokens` y `usage` cubren solo la solicitud final:
1879 1887
1880| Campo | Tipo | Ejemplo | Descripción |1888| Campo | Tipo | Ejemplo | Descripción |
1881| :- | :- | :- | :- |1889| :- | :- | :- | :- |
1882| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes en segundo plano. Los subagentes se ejecutan en segundo plano de forma predeterminada, por lo que una llamada a Agent que omite `run_in_background` también produce `"async_launched"` |1890| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes en segundo plano. Los subagentes se ejecutan en segundo plano de forma predeterminada, así que una llamada a Agent que omite `run_in_background` también produce `"async_launched"` |
1883| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para la ejecución del subagente |1891| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador de la ejecución del subagente |
1884| `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 |1892| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Los bloques de texto finales del subagente o, para un subagente cuyo informe pasa por `SubagentHandback`, una nota breve sobre esa entrega en su lugar |
1885| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo en el que comenzó el subagente, que puede diferir del modelo solicitado |1893| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo con el que empezó el subagente, que puede diferir del modelo solicitado |
1886| `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 |1894| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados en orden, con las repeticiones consecutivas contraídas; se establece solo cuando el modelo se cambió a mitad de la ejecución. Requiere Claude Code v2.1.212 o posterior |
1887| `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 |1895| `totalTokens` | number | `12450` | Cantidad de tokens de la solicitud final a la API del subagente: tokens de entrada, de salida y de caché combinados. No es un total de toda la ejecución |
1888| `totalDurationMs` | number | `48211` | Duración de reloj de pared de la ejecución del subagente |1896| `totalDurationMs` | number | `48211` | Duración en tiempo real de la ejecución del subagente |
1889| `totalToolUseCount` | number | `7` | Recuento de llamadas de herramienta que hizo el subagente |1897| `totalToolUseCount` | number | `7` | Cantidad de llamadas a herramientas que hizo el subagente |
1890| `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` |1898| `usage` | object | `{"input_tokens": 8320, ...}` | Desglose de tokens por tipo de la solicitud final a la API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1891 1899
1892En 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`.1900En 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 mediante esa herramienta en lugar de devolverlo como texto. El campo `content` de su resultado `completed` lleva entonces una nota breve sobre esa entrega en lugar del informe en sí. Para leer el informe, haz coincidir un hook `PreToolUse` o `PostToolUse` con `SubagentHandback` y lee `tool_input.message`.
1893 1901
1894Para 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`.1902Para los subagentes en segundo plano, la herramienta devuelve cuando la tarea pasa a segundo plano, así que `tool_response` no lleva campos de uso: un inicio en segundo plano devuelve de inmediato, y una tarea en primer plano que Claude Code pasa a segundo plano a mitad de la ejecución devuelve en esa transición. Tiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile` y `resolvedModel`.
1895 1903
1896En 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.1904En una respuesta `completed`, `resolvedModel` nombra el modelo con el que empezó el subagente, que puede diferir del valor de `model` en `tool_input`, por ejemplo cuando se aplica `availableModels` u otra sobrescritura. En una respuesta `async_launched`, `resolvedModel` nombra el modelo en uso cuando el agente pasó a segundo plano, de modo que un cambio ocurrido antes de pasar a segundo plano se refleja ahí. `modelsUsed` y el comportamiento de `resolvedModel` en el momento de pasar a segundo plano requieren Claude Code v2.1.212 o posterior.
1897 1905
1898<a id="askuserquestion" />1906<a id="askuserquestion" />
1899 1907
1901 AskUserQuestion1909 AskUserQuestion
1902</h5>1910</h5>
1903 1911
1904Hace al usuario una a cuatro preguntas de opción múltiple.1912Hace al usuario de una a cuatro preguntas de opción múltiple.
1905 1913
1906| Campo | Tipo | Ejemplo | Descripción |1914| Campo | Tipo | Ejemplo | Descripción |
1907| :- | :- | :- | :- |1915| :- | :- | :- | :- |
1908| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Preguntas a presentar, cada una con una cadena `question`, `header` corto, matriz `options`, y bandera `multiSelect` opcional |1916| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Preguntas que se presentarán, cada una con una cadena `question`, un `header` breve, un array `options` y un flag `multiSelect` opcional |
1909| `answers` | object | `{"Which framework?": "React"}` | Opcional. Asigna texto de pregunta a la etiqueta de opción seleccionada. Las respuestas de selección múltiple unen etiquetas con comas. Claude no establece este campo; suministrarlo a través de `updatedInput` para responder programáticamente |1917| `answers` | object | `{"Which framework?": "React"}` | Opcional. Asigna el texto de la pregunta a la etiqueta de la opción seleccionada. Las respuestas de selección múltiple unen las etiquetas con comas. Claude no establece este campo; proporciónalo mediante `updatedInput` para responder de forma programática |
1910 1918
1911<h5 id="exitplanmode">1919<h5 id="exitplanmode">
1912 ExitPlanMode1920 ExitPlanMode
1913</h5>1921</h5>
1914 1922
1915Presenta 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.1923Presenta 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 disco antes de llamar a la herramienta, así que el `tool_input` literal del modelo suele estar vacío. Claude Code inyecta el contenido del plan y la ruta del archivo antes de pasar la entrada a los hooks.
1916 1924
1917| Campo | Tipo | Ejemplo | Descripción |1925| Campo | Tipo | Ejemplo | Descripción |
1918| :- | :- | :- | :- |1926| :- | :- | :- | :- |
1919| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenido del plan en Markdown. Inyectado desde el archivo del plan en el disco |1927| `plan` | string | `"## Refactor auth\n1. Extract..."` | Contenido del plan en Markdown. Se inyecta desde el archivo del plan en disco |
1920| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Inyectado |1928| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Se inyecta |
1921| `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 |1929| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Obsoleto. Claude Code acepta el campo pero lo ignora. Antes de la v2.1.205, llevaba los permisos basados en prompts que Claude solicitaba para implementar el plan |
1922 1930
1923En `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.1931En `PostToolUse`, `tool_response` es un objeto con los campos `plan` y `filePath`, que contienen el plan aprobado, además de flags de estado internos. Lee `tool_response.plan` para obtener el contenido del plan en lugar de volver a leer el archivo desde el disco.
1924 1932
1925<h4 id="pretooluse-decision-control">1933<h4 id="pretooluse-decision-control">
1926 Control de decisión de PreToolUse1934 Control de decisiones de PreToolUse
1927</h4>1935</h4>
1928 1936
1929Los 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.1937Los hooks `PreToolUse` pueden controlar si una llamada a herramienta continúa. A diferencia de otros hooks que usan un campo `decision` de nivel superior, PreToolUse devuelve su decisión dentro de un objeto `hookSpecificOutput`. Esto le da un control más rico: cuatro resultados (permitir, denegar, preguntar o diferir) además de la capacidad de modificar la entrada de la herramienta antes de la ejecución.
1930 1938
1931| Campo | Descripción |1939| Campo | Descripción |
1932| :- | :- |1940| :- | :- |
1933| `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 |1941| `permissionDecision` | `"allow"` omite la solicitud de permiso, excepto para las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves) y para `AskUserQuestion` y `ExitPlanMode`, que necesitan [`updatedInput` emparejado con él](#allow-with-updatedinput). `"deny"` impide la llamada a herramienta. `"ask"` pide al usuario que confirme. `"defer"` sale de forma controlada para que la herramienta pueda reanudarse más tarde. Las [reglas de denegación y de pregunta](/docs/es/permissions#manage-permissions) se siguen evaluando independientemente de lo que devuelva el hook |
1934| `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 |1942| `permissionDecisionReason` | Para `"ask"`, se muestra al usuario en la solicitud de permiso. Cuando Claude Code [deniega la llamada](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs) en una ejecución `-p` en la que nadie puede responder a esa solicitud, Claude lee el motivo en el resultado de la herramienta. Para `"deny"`, se muestra a Claude. Para `"allow"` y `"defer"`, se escribe solo en el [registro de depuración](#debug-hooks) |
1935| `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#foreground-commands-that-move-to-the-background) 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 |1943| `updatedInput` | Modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza todo el objeto de entrada, así que incluye los campos sin cambios junto con los modificados. Claude Code evalúa las reglas de permisos y la [aptitud para pasar automáticamente a segundo plano](/docs/es/tools-reference#foreground-commands-that-move-to-the-background) de un comando Bash contra la entrada que devuelve tu hook, no contra la entrada que envió Claude. Combínalo con `"allow"` para aprobar automáticamente, o con `"ask"` para mostrar la entrada modificada al usuario. Para `"defer"`, se ignora |
1936| `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) |1944| `additionalContext` | Cadena agregada al contexto de Claude junto con el resultado de la herramienta. Se ignora cuando `permissionDecision` es `"defer"`. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
1937 1945
1938Cuando múltiples hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.1946Cuando varios hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.
1939 1947
1940Un 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.1948Un hook que bloquea saliendo con 2 se encamina igual que `"deny"`: Claude ve el mensaje de stderr como el motivo de la denegación.
1941 1949
1942Cuando 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.1950Cuando un hook devuelve `"ask"`, la solicitud de permiso que se muestra al usuario incluye una etiqueta que identifica de dónde proviene el hook: `[settings]` para un hook de cualquier archivo de configuración o del frontmatter de un agente, `[plugin:<name>]` para el hook de un plugin, o `[skill]` para un hook del frontmatter de un skill. Esto ayuda a los usuarios a entender qué fuente de configuración está solicitando la confirmación.
1943 1951
1944Un `"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.1952El `"ask"` de un hook también fuerza una solicitud de permiso en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): el clasificador todavía puede denegar la llamada a herramienta, pero no puede aprobarla en silencio. Antes de la v2.1.211, el clasificador podía aprobar un comando Bash que se ejecutaba fuera del [sandbox](/docs/es/sandboxing) sin mostrar la solicitud que pedía el hook; el clasificador seguía aplicando sus propias reglas de seguridad a ese comando, y un `"deny"` de un hook siempre se respetaba.
1945 1953
1946```json theme={null}1954```json theme={null}
1947{1955{
1959 1967
1960<span id="allow-with-updatedinput" />1968<span id="allow-with-updatedinput" />
1961 1969
1962En [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.1970En [modo no interactivo](/docs/es/headless) con el flag `-p`, Claude Code ofrece `AskUserQuestion` y `ExitPlanMode` solo cuando la ejecución tiene un [host de permisos](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs) que reciba la solicitud, 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 desde stdin, recopila la respuesta mediante tu propia interfaz y la devuelve en `updatedInput` para que la herramienta se ejecute sin pedir nada. Devolver solo `"allow"` no es suficiente para estas herramientas. Para `AskUserQuestion`, devuelve el array `questions` original y agrega un objeto [`answers`](#askuserquestion) que asigne el texto de cada pregunta a la respuesta elegida.
1963 1971
1964A 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.1972Una 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 solicitud 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.
1965 1973
1966<Note>1974<Note>
1967 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.1975 PreToolUse usaba anteriormente los campos de nivel superior `decision` y `reason`, pero están obsoletos para este evento. Usa `hookSpecificOutput.permissionDecision` y `hookSpecificOutput.permissionDecisionReason` en su lugar. Los valores obsoletos `"approve"` y `"block"` se asignan a `"allow"` y `"deny"`, respectivamente. Otros eventos como PostToolUse y Stop siguen usando `decision` y `reason` de nivel superior como su formato actual.
1968</Note>1976</Note>
1969 1977
1970<h4 id="defer-a-tool-call-for-later">1978<h4 id="defer-a-tool-call-for-later">
1971 Diferir una llamada de herramienta para más tarde1979 Diferir una llamada a herramienta para más tarde
1972</h4>1980</h4>
1973 1981
1974`"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.1982`"defer"` está pensado para integraciones que ejecutan `claude -p` como subproceso y leen su salida JSON, como una aplicación del Agent SDK o una interfaz personalizada construida sobre Claude Code. Permite que ese proceso que llama pause a Claude en una llamada a herramienta, recopile la entrada mediante su propia interfaz y reanude donde lo dejó. Claude Code respeta este valor solo en [modo no interactivo](/docs/es/headless) con el flag `-p`. En las sesiones interactivas, registra una advertencia e ignora el resultado del hook.
1975 1983
1976La 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í:1984La herramienta `AskUserQuestion` es el caso típico: Claude quiere preguntarle algo al usuario, pero no hay ninguna terminal en la que responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [host de permisos](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasas con `--permission-prompt-tool`, así que inicia la ejecución con uno. El recorrido completo funciona así:
1977 1985
19781. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.19861. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.
19792. 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.19872. El hook devuelve `permissionDecision: "defer"`. La herramienta no se ejecuta. El proceso sale con `stop_reason: "tool_deferred"` y la llamada a herramienta pendiente queda conservada en la transcripción.
19803. 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.19883. El proceso que llama lee `deferred_tool_use` del resultado del SDK, muestra la pregunta en su propia interfaz y espera una respuesta.
19814. 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.19894. El proceso que llama ejecuta `claude -p --resume <session-id>` con el mismo host de permisos. La misma llamada a herramienta vuelve a disparar `PreToolUse`.
19825. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.19905. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.
1983 1991
1984El 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:1992El campo `deferred_tool_use` lleva el `id`, el `name` y el `input` de la herramienta. El `input` son los parámetros que Claude generó para la llamada a herramienta, capturados antes de la ejecución:
1985 1993
1986```json theme={null}1994```json theme={null}
1987{1995{
1997}2005}
1998```2006```
1999 2007
2000No hay límite de tiempo de espera o reintento. La sesión permanece en el disco hasta que la reanude, sujeta al barrido de retención [`cleanupPeriodDays`](/docs/es/settings-reference#cleanupperioddays), que elimina archivos de sesión después de 30 días de forma predeterminada, siguiendo las [reglas de barrido de retención](/docs/es/claude-directory#cleaned-up-automatically). Si la respuesta no está lista cuando reanuda, el hook puede devolver `"defer"` nuevamente y el proceso sale de la misma manera. El proceso de llamada controla cuándo romper el bucle devolviendo finalmente `"allow"` o `"deny"` del hook.2008No hay tiempo de espera ni límite de reintentos. La sesión permanece en disco hasta que la reanudas, sujeta a la limpieza de retención de [`cleanupPeriodDays`](/docs/es/settings-reference#cleanupperioddays), que elimina los archivos de sesión después de 30 días de forma predeterminada, según las [reglas de limpieza de retención](/docs/es/claude-directory#cleaned-up-automatically). Si la respuesta no está lista cuando reanudas, el hook puede devolver `"defer"` de nuevo y el proceso sale de la misma forma. El proceso que llama controla cuándo romper el bucle devolviendo finalmente `"allow"` o `"deny"` desde el hook.
2001 2009
2002`"defer"` solo funciona cuando Claude hace una única llamada de herramienta en el turno. Si Claude hace varias llamadas de herramienta a la vez, `"defer"` se ignora con una advertencia y la herramienta procede a través del flujo de permiso normal. La restricción existe porque reanudar solo puede re-ejecutar una herramienta: no hay forma de diferir una llamada de un lote sin dejar las otras sin resolver.2010`"defer"` solo funciona cuando Claude hace una única llamada a herramienta en el turno. Si Claude hace varias llamadas a herramientas a la vez, `"defer"` se ignora con una advertencia y la herramienta continúa por el flujo de permisos normal. La restricción existe porque la reanudación solo puede volver a ejecutar una herramienta: no hay forma de diferir una llamada de un lote sin dejar las demás sin resolver.
2003 2011
2004Si 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ó.2012Si la herramienta diferida ya no está disponible cuando reanudas, el proceso sale con `stop_reason: "tool_deferred_unavailable"` e `is_error: true` antes de que se dispare el hook. Esto ocurre cuando un servidor MCP que proporcionaba la herramienta no está conectado en la sesión reanudada. El payload `deferred_tool_use` se sigue incluyendo para que puedas identificar qué herramienta desapareció.
2005 2013
2006<Note>2014<Note>
2007 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.2015 Para reanudar una sesión diferida en modo plan, pasa [`--permission-prompt-tool`](/docs/es/cli-reference#cli-flags) junto con `--resume` para que Claude Code pueda presentar el plan para su aprobación. Si pasas ciertos otros flags de inicio, la ejecución reanudada no vuelve al modo plan; consulta [Reanudar en modo plan con `-p`](/docs/es/sessions#resume-in-plan-mode-with-p). Requiere Claude Code v2.1.246 o posterior.
2008 2016
2009 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).2017 Cuando reanudas con `-p`, Claude Code no restaura ningún otro modo de permisos almacenado. Inicia la ejecución en el modo de permisos en el que se iniciaría una nueva ejecución `claude -p`, así que vuelve a pasar `--permission-mode` o `--dangerously-skip-permissions` si la sesión diferida usaba alguno. Cuando reanudas con `claude --resume <session-id>` sin `-p`, Claude Code restaura el modo de permisos almacenado, con las excepciones enumeradas en [modo de permisos al reanudar](/docs/es/sessions#permission-mode-on-resume).
2010</Note>2018</Note>
2011 2019
2012<h3 id="permissionrequest">2020<h3 id="permissionrequest">
2013 PermissionRequest2021 PermissionRequest
2014</h3>2022</h3>
2015 2023
2016Se ejecuta cuando Claude Code está a punto de pedirte permiso para usar una herramienta. En las sesiones que no pueden mostrar una solicitud, como los subagentes en segundo plano en el [modo no interactivo](/docs/es/headless), Claude Code ejecuta igualmente estos hooks, y si ningún hook devuelve una decisión, deniega la llamada a herramienta. Para una llamada que llega a un `--permission-prompt-tool` o al [callback `canUseTool`](/docs/es/agent-sdk/permissions) del Agent SDK, los hooks se ejecutan junto con tu host, y se aplica el que decida primero.2024Se ejecuta cuando Claude Code está a punto de pedirte permiso para usar una herramienta. En las sesiones que no pueden mostrar una solicitud, como los subagentes en segundo plano en [modo no interactivo](/docs/es/headless), Claude Code sigue ejecutando estos hooks y, si ningún hook devuelve una decisión, deniega la llamada a herramienta. Para una llamada que llega a un `--permission-prompt-tool` o al [callback `canUseTool`](/docs/es/agent-sdk/permissions) del Agent SDK, los hooks se ejecutan junto con tu host, y se aplica la decisión del que decida primero.
2017Usa el [control de decisiones de PermissionRequest](#permissionrequest-decision-control) para permitir o denegar en nombre del usuario.2025Usa el [control de decisiones de PermissionRequest](#permissionrequest-decision-control) para permitir o denegar en nombre del usuario.
2018 2026
2019Use 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.2027Usa este evento cuando necesites una señal en el momento en que Claude pide permiso para usar una herramienta. Claude Code ejecuta un hook [Notification](#notification) con el tipo `permission_prompt` solo después de que la solicitud ha esperado unos seis segundos.
2020 2028
2021Claude 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`.2029Claude Code no ejecuta hooks PermissionRequest para la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en el sandbox. Para obtener una señal de esa solicitud, usa el tipo de notificación `permission_prompt`.
2022 2030
2023Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2031Coincide con el nombre de la herramienta, con los mismos valores que PreToolUse.
2024 2032
2025<h4 id="permissionrequest-input">2033<h4 id="permissionrequest-input">
2026 Entrada de PermissionRequest2034 Entrada de PermissionRequest
2027</h4>2035</h4>
2028 2036
2029Los hooks PermissionRequest reciben campos `tool_name` e `tool_input` como los hooks PreToolUse, pero sin `tool_use_id`. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input). Una matriz `permission_suggestions` opcional contiene las [actualizaciones de permiso](#permission-update-entries) que Claude Code sugiere para esta solicitud, como agregar una regla de permiso o cambiar el modo de permiso.2037Los hooks PermissionRequest reciben los campos `tool_name` y `tool_input` como los hooks PreToolUse, pero sin `tool_use_id`. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input). Un array opcional `permission_suggestions` contiene las [actualizaciones de permisos](#permission-update-entries) que Claude Code sugiere para esta solicitud, como agregar una regla de permiso o cambiar el modo de permisos.
2030 2038
2031La matriz `permission_suggestions` no es una lista exacta de las opciones que ve, porque cada diálogo de permiso construye sus propias opciones. Algunos diálogos, como el de ediciones de archivo, no leen la matriz en absoluto y derivan sus opciones de la solicitud en sí. Un diálogo que sí la lee aún puede retener una opción cuya sugerencia permanece en la matriz, por ejemplo cuando [`allowManagedPermissionRulesOnly`](/docs/es/settings-reference#allowmanagedpermissionrulesonly) oculta opciones de guardado de reglas. También puede ofrecer opciones que no tienen entrada de sugerencia, como [**Sí, y cambiar a modo automático**](/docs/es/permission-modes#switch-permission-modes), que cambia el modo de permiso directamente en lugar de a través de una actualización de permiso.2039El array `permission_suggestions` no es una lista exacta de las opciones que ves, porque cada diálogo de permisos construye sus propias opciones. Algunos diálogos, como el de las ediciones de archivos, no leen el array en absoluto y derivan sus opciones de la propia solicitud. Un diálogo que sí lo lee puede seguir ocultando una opción cuya sugerencia permanece en el array, por ejemplo cuando [`allowManagedPermissionRulesOnly`](/docs/es/settings-reference#allowmanagedpermissionrulesonly) oculta las opciones para guardar reglas. También puede ofrecer opciones que no tienen ninguna entrada de sugerencia, como [**Yes, and switch to auto mode**](/docs/es/permission-modes#switch-permission-modes), que cambia el modo de permisos directamente en lugar de hacerlo mediante una actualización de permisos.
2032 2040
2033Los hooks PreToolUse se ejecutan antes de cada llamada de herramienta, independientemente de si necesita permiso. Los hooks PermissionRequest se ejecutan solo cuando Claude Code está a punto de pedirle permiso, o cuando de otro modo auto-negaría una llamada que no puede solicitar. Ninguno de los dos eventos se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).2041Los hooks PreToolUse se ejecutan antes de cada llamada a herramienta, necesite o no permiso. Los hooks PermissionRequest se ejecutan solo cuando Claude Code está a punto de pedirte permiso, o cuando de otro modo denegaría automáticamente una llamada que no puede mostrar una solicitud. Ninguno de los dos eventos se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).
2034 2042
2035```json theme={null}2043```json theme={null}
2036{2044{
2056```2064```
2057 2065
2058<h4 id="permissionrequest-decision-control">2066<h4 id="permissionrequest-decision-control">
2059 Control de decisión de PermissionRequest2067 Control de decisiones de PermissionRequest
2060</h4>2068</h4>
2061 2069
2062Los 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:2070Los hooks `PermissionRequest` pueden permitir o denegar solicitudes de permiso. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver un objeto `decision` con estos campos específicos del evento:
2063 2071
2064| Campo | Descripción |2072| Campo | Descripción |
2065| :- | :- |2073| :- | :- |
2066| `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 |2074| `behavior` | `"allow"` concede el permiso, `"deny"` lo deniega. Las [reglas de denegación y de pregunta](/docs/es/permissions#manage-permissions) se siguen evaluando, así que un hook que devuelve `"allow"` no sobrescribe una regla de denegación que coincida |
2067| `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 |2075| `updatedInput` | Solo para `"allow"`: modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza todo el objeto de entrada, así que incluye los campos sin cambios junto con los modificados. La entrada modificada se vuelve a evaluar contra las reglas de denegación y de pregunta |
2068| `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 |2076| `updatedPermissions` | Solo para `"allow"`: array de [entradas de actualización de permisos](#permission-update-entries) que se aplicarán, como agregar una regla de permiso o cambiar el modo de permisos de la sesión |
2069| `message` | Para `"deny"` solo: dice a Claude por qué se negó el permiso |2077| `message` | Solo para `"deny"`: le dice a Claude por qué se denegó el permiso |
2070| `interrupt` | Para `"deny"` solo: si es `true`, detiene a Claude |2078| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |
2071 2079
2072Un hook que sale con 2 sin un objeto `decision` deja el flujo de permiso sin cambios, y su stderr se descarta. Solo el objeto `decision` puede otorgar o negar la solicitud.2080Un hook que sale con 2 sin un objeto `decision` deja el flujo de permisos sin cambios, y su stderr se descarta. Solo el objeto `decision` puede conceder o denegar la solicitud.
2073 2081
2074```json theme={null}2082```json theme={null}
2075{2083{
2086```2094```
2087 2095
2088<h4 id="permission-update-entries">2096<h4 id="permission-update-entries">
2089 Entradas de actualización de permiso2097 Entradas de actualización de permisos
2090</h4>2098</h4>
2091 2099
2092El campo de salida `updatedPermissions` y el campo de entrada [`permission_suggestions`](#permissionrequest-input) ambos usan la misma matriz de objetos de entrada. Cada entrada tiene un `type` que determina sus otros campos, y un `destination` que controla dónde se escribe el cambio.2100El campo de salida `updatedPermissions` y el [campo de entrada `permission_suggestions`](#permissionrequest-input) usan el mismo array de objetos de entrada. Cada entrada tiene un `type` que determina sus demás campos, y un `destination` que controla dónde se escribe el cambio.
2093 2101
2094| `type` | Campos | Efecto |2102| `type` | Campos | Efecto |
2095| :- | :- | :- |2103| :- | :- | :- |
2096| `addRules` | `rules`, `behavior`, `destination` | Agrega reglas de permiso. `rules` es una matriz de objetos `{toolName, ruleContent?}`. Omita `ruleContent` para hacer coincidir toda la herramienta. `behavior` es `"allow"`, `"deny"`, o `"ask"` |2104| `addRules` | `rules`, `behavior`, `destination` | Agrega reglas de permisos. `rules` es un array de objetos `{toolName, ruleContent?}`. Omite `ruleContent` para coincidir con toda la herramienta. `behavior` es `"allow"`, `"deny"` o `"ask"` |
2097| `replaceRules` | `rules`, `behavior`, `destination` | Reemplaza todas las reglas del `behavior` dado en el `destination` con las `rules` proporcionadas |2105| `replaceRules` | `rules`, `behavior`, `destination` | Reemplaza todas las reglas del `behavior` indicado en el `destination` con las `rules` proporcionadas |
2098| `removeRules` | `rules`, `behavior`, `destination` | Elimina reglas coincidentes del `behavior` dado |2106| `removeRules` | `rules`, `behavior`, `destination` | Elimina las reglas que coinciden del `behavior` indicado |
2099| `setMode` | `mode`, `destination` | Cambia el modo de permiso. Los modos válidos son `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan`, y `manual` como alias para `default`. El alias `manual` requiere Claude Code v2.1.200 o posterior |2107| `setMode` | `mode`, `destination` | Cambia el modo de permisos. Los modos válidos son `default`, `auto`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` y `manual` como alias de `default`. El alias `manual` requiere Claude Code v2.1.200 o posterior |
2100| `addDirectories` | `directories`, `destination` | Agrega directorios de trabajo. `directories` es una matriz de cadenas de ruta |2108| `addDirectories` | `directories`, `destination` | Agrega directorios de trabajo. `directories` es un array de cadenas de rutas |
2101| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |2109| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |
2102 2110
2103<Note>2111<Note>
2104 `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).2112 `setMode` con `bypassPermissions` solo surte efecto si iniciaste la sesión con el modo bypass ya disponible: `--dangerously-skip-permissions`, `--permission-mode bypassPermissions`, `--allow-dangerously-skip-permissions` o `permissions.defaultMode: "bypassPermissions"` en la [configuración de usuario, de `--settings` o administrada](/docs/es/settings-reference#permissions-defaultmode). De lo contrario, la actualización no tiene efecto. La actualización tampoco tiene efecto cuando [`permissions.disableBypassPermissionsMode`](/docs/es/permissions#managed-settings) deshabilita el modo, o cuando la sesión se inicia en [modo restringido](/docs/es/cli-reference#cli-flags).
2105 2113
2106 `bypassPermissions` nunca se persiste como `defaultMode` independientemente de `destination`.2114 `bypassPermissions` nunca se persiste como `defaultMode`, independientemente de `destination`.
2107</Note>2115</Note>
2108 2116
2109El campo `destination` en cada entrada determina si el cambio permanece en memoria o persiste en un archivo de configuración.2117El campo `destination` de cada entrada determina si el cambio permanece en memoria o se persiste en un archivo de configuración.
2110 2118
2111| `destination` | Escribe en |2119| `destination` | Escribe en |
2112| :- | :- |2120| :- | :- |
2113| `session` | solo en memoria, descartado cuando termina la sesión |2121| `session` | solo en memoria, se descarta cuando termina la sesión |
2114| `localSettings` | `.claude/settings.local.json` |2122| `localSettings` | `.claude/settings.local.json` |
2115| `projectSettings` | `.claude/settings.json` |2123| `projectSettings` | `.claude/settings.json` |
2116| `userSettings` | `~/.claude/settings.json` |2124| `userSettings` | `~/.claude/settings.json` |
2117 2125
2118Un hook puede hacer eco de una de las `permission_suggestions` que recibió como su propia salida `updatedPermissions`.2126Un hook puede devolver una de las `permission_suggestions` que recibió como su propia salida `updatedPermissions`.
2119 2127
2120<h3 id="posttooluse">2128<h3 id="posttooluse">
2121 PostToolUse2129 PostToolUse
2122</h3>2130</h3>
2123 2131
2124Se ejecuta inmediatamente después de que una herramienta se completa exitosamente.2132Se ejecuta inmediatamente después de que una herramienta se completa correctamente.
2125 2133
2126Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2134Coincide con el nombre de la herramienta, con los mismos valores que PreToolUse.
2127 2135
2128Coincida más ampliamente cuando el nombre de la herramienta no es el filtro correcto:2136Usa una coincidencia más amplia cuando el nombre de la herramienta no sea el filtro adecuado:
2129 2137
2130* Para ejecutar un hook después de que cualquier herramienta se complete exitosamente, omita el `matcher` o establézcalo en `"*"`. Su hook puede entonces descubrir qué cambió por sí mismo, por ejemplo ejecutando `git status --porcelain`, que también enumera archivos sin seguimiento que `git diff` pierde. Para llamadas de herramienta que fallan, agregue el mismo hook bajo [PostToolUseFailure](#posttoolusefailure).2138* Para ejecutar un hook después de que cualquier herramienta se complete correctamente, omite el `matcher` o establécelo en `"*"`. Tu hook puede entonces descubrir por sí mismo qué cambió, por ejemplo ejecutando `git status --porcelain`, que también lista los archivos sin seguimiento que `git diff` no muestra. Para las llamadas a herramientas que fallan, agrega el mismo hook en [PostToolUseFailure](#posttoolusefailure).
2131* Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, use [FileChanged](#filechanged). Claude Code no ejecuta un hook `PostToolUse` que coincida con `Edit|Write` cuando un comando `Bash` o un proceso fuera de Claude Code reescribe el mismo archivo.2139* Para ejecutar un hook cuando un archivo específico cambia en disco, sin importar qué lo escribió, usa [FileChanged](#filechanged). Claude Code no ejecuta un hook `PostToolUse` que coincide con `Edit|Write` cuando un comando `Bash` o un proceso fuera de Claude Code reescribe el mismo archivo.
2132 2140
2133<h4 id="posttooluse-input">2141<h4 id="posttooluse-input">
2134 Entrada de PostToolUse2142 Entrada de PostToolUse
2135</h4>2143</h4>
2136 2144
2137Los 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).2145Los hooks `PostToolUse` se activan después de que una herramienta ya se ejecutó correctamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto de ambos depende de la herramienta. Las rutas de `tool_input` de las herramientas de archivos llegan en el mismo formato que para [PreToolUse](#pretooluse-input): siempre absolutas, con los separadores nativos de la plataforma, es decir, barras invertidas en Windows. Para una herramienta MCP, la entrada también incluye el objeto [`mcp_server`](#pretooluse-input).
2138 2146
2139```json theme={null}2147```json theme={null}
2140{2148{
2159 2167
2160| Campo | Descripción |2168| Campo | Descripción |
2161| :- | :- |2169| :- | :- |
2162| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a prompts de permiso y hooks PreToolUse |2170| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a solicitudes de permiso y a hooks PreToolUse |
2163 2171
2164<h4 id="posttooluse-decision-control">2172<h4 id="posttooluse-decision-control">
2165 Control de decisión de PostToolUse2173 Control de decisiones de PostToolUse
2166</h4>2174</h4>
2167 2175
2168Los hooks `PostToolUse` pueden proporcionar retroalimentación a Claude después de la ejecución de la herramienta. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:2176Los hooks `PostToolUse` pueden proporcionar retroalimentación a Claude después de la ejecución de la herramienta. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver estos campos específicos del evento:
2169 2177
2170| Campo | Descripción |2178| Campo | Descripción |
2171| :- | :- |2179| :- | :- |
2172| `decision` | `"block"` agrega el `reason` junto al resultado de la herramienta. Claude aún ve la salida original; para reemplazarla, use `updatedToolOutput` |2180| `decision` | `"block"` agrega el `reason` junto al resultado de la herramienta. Claude sigue viendo la salida original; para reemplazarla, usa `updatedToolOutput` |
2173| `reason` | Explicación mostrada a Claude cuando `decision` es `"block"` |2181| `reason` | Explicación que se muestra a Claude cuando `decision` es `"block"` |
2174| `additionalContext` | Cadena agregada al contexto de Claude junto con el resultado de la herramienta. Consulte [Agregar contexto para Claude](#add-context-for-claude) |2182| `additionalContext` | Cadena que se agrega al contexto de Claude junto con el resultado de la herramienta. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
2175| `classifierContext` | Nota breve sobre el resultado de esta llamada para el clasificador de [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) en lugar de para Claude. Consulte [Anotar un resultado para el clasificador de modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requiere Claude Code v2.1.236 o posterior |2183| `classifierContext` | Nota breve sobre el resultado de esta llamada destinada al clasificador del [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) en lugar de a Claude. Consulta [Anotar un resultado para el clasificador del modo automático](#annotate-a-result-for-the-auto-mode-classifier). Requiere Claude Code v2.1.236 o posterior |
2176| `updatedToolOutput` | Reemplaza la salida de la herramienta con el valor proporcionado antes de que se envíe a Claude. El valor debe coincidir con la forma de salida de la herramienta |2184| `updatedToolOutput` | Reemplaza la salida de la herramienta con el valor proporcionado antes de enviarla a Claude. El valor debe coincidir con la forma de salida de la herramienta |
2177| `updatedMCPToolOutput` | Reemplaza la salida para [herramientas MCP](#match-mcp-tools) solo. Prefiera `updatedToolOutput`, que funciona para todas las herramientas |2185| `updatedMCPToolOutput` | Reemplaza la salida solo para [herramientas MCP](#match-mcp-tools). Es preferible `updatedToolOutput`, que funciona para todas las herramientas |
2178 2186
2179El ejemplo a continuación reemplaza la salida de una llamada `Bash`. El valor de reemplazo coincide con la forma de salida de la herramienta `Bash`:2187El siguiente ejemplo reemplaza la salida de una llamada a `Bash`. El valor de reemplazo coincide con la forma de salida de la herramienta `Bash`:
2180 2188
2181```json theme={null}2189```json theme={null}
2182{2190{
2194```2202```
2195 2203
2196<Warning>2204<Warning>
2197 `updatedToolOutput` solo cambia lo que Claude ve. La herramienta ya se ha ejecutado en el momento en que se dispara el hook, por lo que cualquier archivo escrito, comando ejecutado o solicitud de red enviada ya ha tenido efecto. La telemetría como tramos de herramientas OpenTelemetry y eventos de análisis también captura la salida original antes de que se ejecute el hook. Para evitar o modificar una llamada de herramienta antes de que se ejecute, use un hook [PreToolUse](#pretooluse) en su lugar.2205 `updatedToolOutput` solo cambia lo que ve Claude. La herramienta ya se ejecutó cuando se activa el hook, por lo que cualquier archivo escrito, comando ejecutado o solicitud de red enviada ya surtió efecto. La telemetría, como los spans de herramientas de OpenTelemetry y los eventos de análisis, también captura la salida original antes de que se ejecute el hook. Para impedir o modificar una llamada a herramienta antes de que se ejecute, usa en su lugar un hook [PreToolUse](#pretooluse).
2198 2206
2199 El valor de reemplazo debe coincidir con la forma de salida de la herramienta. Las herramientas integradas devuelven objetos estructurados en lugar de cadenas simples. Por ejemplo, `Bash` devuelve un objeto con campos `stdout`, `stderr`, `interrupted`, e `isImage`. Para herramientas integradas, un valor que no coincida con el esquema de salida de la herramienta se ignora y se usa la salida original. La salida de herramientas MCP se pasa sin validación de esquema. Eliminar detalles de error que Claude necesita puede hacer que continúe con una suposición falsa.2207 El valor de reemplazo debe coincidir con la forma de salida de la herramienta. Las herramientas integradas devuelven objetos estructurados en lugar de cadenas simples. Por ejemplo, `Bash` devuelve un objeto con los campos `stdout`, `stderr`, `interrupted` e `isImage`. Para las herramientas integradas, un valor que no coincide con el esquema de salida de la herramienta se ignora y se usa la salida original. La salida de las herramientas MCP se pasa sin validación de esquema. Eliminar detalles de errores que Claude necesita puede hacer que proceda con una suposición falsa.
2200</Warning>2208</Warning>
2201 2209
2202<h4 id="annotate-a-result-for-the-auto-mode-classifier">2210<h4 id="annotate-a-result-for-the-auto-mode-classifier">
2203 Anotar un resultado para el clasificador de modo automático2211 Anotar un resultado para el clasificador del modo automático
2204</h4>2212</h4>
2205 2213
2206Devuelva `classifierContext` para enviar una nota breve sobre el resultado de la llamada de herramienta al clasificador de [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) en lugar de a Claude. El clasificador [nunca recibe resultados de herramientas en sí](/docs/es/permission-modes#how-the-classifier-evaluates-actions), por lo que este campo es la forma admitida de decirle algo sobre lo que devolvió una llamada antes de que revise acciones posteriores. El campo requiere Claude Code v2.1.236 o posterior.2214Devuelve `classifierContext` para enviar una nota breve sobre el resultado de la llamada a herramienta al clasificador del [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) en lugar de a Claude. El clasificador [nunca recibe los resultados de las herramientas en sí](/docs/es/permission-modes#how-the-classifier-evaluates-actions), por lo que este campo es la forma admitida de comunicarle algo sobre lo que devolvió una llamada antes de que revise acciones posteriores. El campo requiere Claude Code v2.1.236 o posterior.
2207 2215
2208El ejemplo a continuación dice al clasificador de dónde vino la salida de una consulta:2216El siguiente ejemplo le indica al clasificador de dónde provino la salida de una consulta:
2209 2217
2210```json theme={null}2218```json theme={null}
2211{2219{
2216}2224}
2217```2225```
2218 2226
2219Cuánto peso da el clasificador a la nota depende de dónde configuró el hook:2227El peso que el clasificador le da a la nota depende de dónde configuraste el hook:
2220 2228
2221* **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ón2229* **Hooks configurados en Claude Code**: para los hooks de archivos de configuración, plugins, skills y frontmatter de agentes, el clasificador trata la nota como contexto no verificado proporcionado por la aplicación. La nota nunca establece la intención del usuario y, si afirma que aprobaste o solicitaste algo, el clasificador contrasta esa afirmación con tus propios mensajes en la conversación
2222* **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 verificada2230* **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 considerar como intención del usuario una declaración del usuario transmitida en la nota. Esa declaración puede satisfacer un requisito de consentimiento que el clasificador aceptaría de un mensaje que envíes, pero nunca levanta un bloqueo que tu propio mensaje tampoco 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 verificada
2223 2231
2224Claude Code aplica estos límites al entregar la nota:2232Claude Code aplica estos límites al entregar la nota:
2225 2233
2226* **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 llamada2234* **Longitud**: Claude Code limita las notas de una llamada a herramienta a 2000 caracteres y trunca el resto. El límite se comparte entre todos los hooks que responden a esa llamada
2227* **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 herramienta2235* **Solo respuestas síncronas**: 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
2228* **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 llamadas2236* **Llamadas que el clasificador no registra**: la transcripción del clasificador omite las consultas de solo lectura, como las lecturas de archivos y las búsquedas. Claude Code descarta una nota adjunta a una de esas llamadas
2229* **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 salida2237* **Interacción con reescrituras**: cuando la nota describe una salida que estás reemplazando con `updatedToolOutput`, devuelve ambos campos en la misma respuesta del hook. Claude Code descarta la nota si esa reescritura se rechaza o si la reescritura de otro hook la reemplaza. Claude Code entrega una nota que devuelves sin reescritura incluso cuando otro hook reescribe la salida
2230 2238
2231<Warning>2239<Warning>
2232 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.2240 El clasificador lee el contenido que colocas en `classifierContext` como información de la aplicación que aloja la sesión, así que no copies en él salida de herramientas no confiable ni texto de terceros. Limita la nota a una afirmación breve sobre esta única llamada, como un dato sobre su origen o una declaración del usuario al respecto; no uses el campo para entregar mensajes no relacionados ni un flujo de eventos.
2233</Warning>2241</Warning>
2234 2242
2235<h3 id="posttoolusefailure">2243<h3 id="posttoolusefailure">
2236 PostToolUseFailure2244 PostToolUseFailure
2237</h3>2245</h3>
2238 2246
2239Se ejecuta cuando una herramienta que comenzó a ejecutarse falla: la herramienta lanzó un error, o una herramienta MCP devolvió un resultado de error. Úselo para registrar fallos, enviar alertas o proporcionar retroalimentación correctiva a Claude.2247Se ejecuta cuando falla una herramienta que comenzó a ejecutarse: la herramienta lanzó un error o una herramienta MCP devolvió un resultado de error. Úsalo para registrar fallas, enviar alertas o proporcionar retroalimentación correctiva a Claude.
2240 2248
2241Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2249Coincide con el nombre de la herramienta, con los mismos valores que PreToolUse.
2242 2250
2243<Note>2251<Note>
2244 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).2252 Este evento no se activa para llamadas a herramientas rechazadas antes de la ejecución: un nombre de herramienta desconocido, una entrada que no supera la validación de esquema o la validación específica de la 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 activan ni `PreToolUse` ni `PostToolUseFailure`. Las denegaciones de permiso activan `PreToolUse` pero no este evento; consulta [PermissionDenied](#permissiondenied).
2245</Note>2253</Note>
2246 2254
2247<h4 id="posttoolusefailure-input">2255<h4 id="posttoolusefailure-input">
2248 Entrada de PostToolUseFailure2256 Entrada de PostToolUseFailure
2249</h4>2257</h4>
2250 2258
2251Los hooks PostToolUseFailure reciben los mismos campos `tool_name` e `tool_input` que PostToolUse, junto con información de error como campos de nivel superior. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input). Por ejemplo, un comando `npm test` fallido podría entregar:2259Los hooks PostToolUseFailure reciben los mismos campos `tool_name` y `tool_input` que PostToolUse, junto con información del error como campos de nivel superior. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input). Por ejemplo, un comando `npm test` fallido podría entregar:
2252 2260
2253```json theme={null}2261```json theme={null}
2254{2262{
2272| Campo | Descripción |2280| Campo | Descripción |
2273| :- | :- |2281| :- | :- |
2274| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |2282| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |
2275| `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 |2283| `is_interrupt` | Booleano opcional. Es verdadero cuando la falla llegó a Claude Code como una cancelación en lugar de como un error informado por la herramienta. Cancelar una herramienta en ejecución no activa este hook; en su lugar, el resultado de la herramienta contiene el mensaje de interrupción |
2276| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a prompts de permiso y hooks PreToolUse |2284| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a solicitudes de permiso y a hooks PreToolUse |
2277 2285
2278La 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.2286La 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 la falla. Basa tu hook en `tool_name`, `is_interrupt` y la primera línea `Exit code N`; trata el resto de la cadena como texto para mostrar, no como un formato estable.
2279 2287
2280* 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 intercalados2288* Para Bash y PowerShell, un comando que se ejecutó y terminó produce una primera línea `Exit code N`, seguida de cualquier salida que haya producido el comando como un solo bloque con stdout y stderr intercalados
2281* 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í2289* Un payload también puede contener un mensaje de falla simple sin línea de código de salida, cuando Claude Code no pudo iniciar el proceso del shell
2282* 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`2290* Claude Code trunca por el medio las cadenas largas alrededor de un marcador `... [N characters truncated] ...` y puede insertar líneas propias, como `Command timed out after 2m 0s`
2283 2291
2284<h4 id="posttoolusefailure-decision-control">2292<h4 id="posttoolusefailure-decision-control">
2285 Control de decisión de PostToolUseFailure2293 Control de decisiones de PostToolUseFailure
2286</h4>2294</h4>
2287 2295
2288Los hooks `PostToolUseFailure` pueden proporcionar contexto a Claude después de un fallo de herramienta. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:2296Los hooks `PostToolUseFailure` pueden proporcionar contexto a Claude después de una falla de herramienta. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver estos campos específicos del evento:
2289 2297
2290| Campo | Descripción |2298| Campo | Descripción |
2291| :- | :- |2299| :- | :- |
2292| `additionalContext` | Cadena agregada al contexto de Claude junto con el error. Consulte [Agregar contexto para Claude](#add-context-for-claude) |2300| `additionalContext` | Cadena que se agrega al contexto de Claude junto con el error. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
2293 2301
2294```json theme={null}2302```json theme={null}
2295{2303{
2304 PostToolBatch2312 PostToolBatch
2305</h3>2313</h3>
2306 2314
2307Se 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.2315Se ejecuta una vez después de que se haya resuelto cada llamada a herramienta de un lote, antes de que Claude Code envíe la siguiente solicitud al modelo. `PostToolUse` se activa una vez por herramienta, lo que significa que se activa de forma concurrente cuando Claude hace llamadas a herramientas en paralelo. `PostToolBatch` se activa exactamente una vez con el lote completo, por lo que es el lugar adecuado para inyectar contexto que depende del conjunto de herramientas que se ejecutaron en lugar de una sola herramienta. No hay matcher para este evento.
2308 2316
2309<h4 id="posttoolbatch-input">2317<h4 id="posttoolbatch-input">
2310 Entrada de PostToolBatch2318 Entrada de PostToolBatch
2311</h4>2319</h4>
2312 2320
2313Además de los [campos de entrada comunes](#common-input-fields), los hooks PostToolBatch reciben `tool_calls`, una matriz que describe cada llamada de herramienta en el lote:2321Además de los [campos de entrada comunes](#common-input-fields), los hooks PostToolBatch reciben `tool_calls`, un arreglo que describe cada llamada a herramienta del lote:
2314 2322
2315```json theme={null}2323```json theme={null}
2316{2324{
2336}2344}
2337```2345```
2338 2346
2339`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.2347`tool_response` contiene el mismo contenido que el modelo recibe en el bloque `tool_result` correspondiente. El valor es una cadena serializada o un arreglo 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 del contenido sin procesar del archivo. Las respuestas pueden ser grandes, así que analiza solo los campos que necesitas.
2340 2348
2341<Note>2349<Note>
2342 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.2350 La forma de `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 serializado de `tool_result` que ve el modelo.
2343</Note>2351</Note>
2344 2352
2345<h4 id="posttoolbatch-decision-control">2353<h4 id="posttoolbatch-decision-control">
2346 Control de decisión de PostToolBatch2354 Control de decisiones de PostToolBatch
2347</h4>2355</h4>
2348 2356
2349Los hooks `PostToolBatch` pueden inyectar contexto para Claude. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:2357Los hooks `PostToolBatch` pueden inyectar contexto para Claude. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver estos campos específicos del evento:
2350 2358
2351| Campo | Descripción |2359| Campo | Descripción |
2352| :- | :- |2360| :- | :- |
2353| `additionalContext` | Cadena de contexto inyectada una vez antes de la siguiente llamada del modelo. Consulte [Agregar contexto para Claude](#add-context-for-claude) para detalles de entrega, qué poner en él y cómo las sesiones reanudadas manejan valores pasados |2361| `additionalContext` | Cadena de contexto inyectada una vez antes de la siguiente llamada al modelo. Consulta [Agregar contexto para Claude](#add-context-for-claude) para conocer los detalles de entrega, qué incluir y cómo las sesiones reanudadas manejan los valores anteriores |
2354 2362
2355```json theme={null}2363```json theme={null}
2356{2364{
2361}2369}
2362```2370```
2363 2371
2364Devolver `decision: "block"` o `continue: false` detiene el bucle agéntico antes de la siguiente llamada del modelo. El mensaje de bloqueo viene del JSON `reason` o `stopReason`, o de stderr en salida 2. Lo ve como una advertencia en la transcripción, y permanece en la conversación, por lo que Claude lo ve cuando la conversación continúa.2372Devolver `decision: "block"` o `continue: false` detiene el bucle agéntico antes de la siguiente llamada al modelo. El mensaje de bloqueo proviene del `reason` o `stopReason` del JSON, o de stderr con el código de salida 2. Lo ves como una advertencia en la transcripción y permanece en la conversación, por lo que Claude lo ve cuando la conversación continúa.
2365 2373
2366<h3 id="permissiondenied">2374<h3 id="permissiondenied">
2367 PermissionDenied2375 PermissionDenied
2368</h3>2376</h3>
2369 2377
2370Se 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.2378Se ejecuta cuando el [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) deniega una llamada a herramienta, incluso cuando la deniega sin un veredicto del clasificador porque [una verificación de seguridad independiente 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 pudo analizar. Este hook solo se activa en modo automático: no se ejecuta cuando deniegas manualmente un cuadro de diálogo de permisos, cuando un hook `PreToolUse` bloquea una llamada ni cuando coincide una regla `deny`. Úsalo para registrar denegaciones, ajustar la configuración o indicarle al modelo que puede reintentar la llamada a herramienta.
2371 2379
2372Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2380Coincide con el nombre de la herramienta, con los mismos valores que PreToolUse.
2373 2381
2374<h4 id="permissiondenied-input">2382<h4 id="permissiondenied-input">
2375 Entrada de PermissionDenied2383 Entrada de PermissionDenied
2376</h4>2384</h4>
2377 2385
2378Además de los [campos de entrada comunes](#common-input-fields), los hooks PermissionDenied reciben `tool_name`, `tool_input`, `tool_use_id`, y `reason`. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input).2386Además de los [campos de entrada comunes](#common-input-fields), los hooks PermissionDenied reciben `tool_name`, `tool_input`, `tool_use_id` y `reason`. Para una herramienta MCP, también reciben el objeto [`mcp_server`](#pretooluse-input).
2379 2387
2380```json theme={null}2388```json theme={null}
2381{2389{
2396 2404
2397| Campo | Descripción |2405| Campo | Descripción |
2398| :- | :- |2406| :- | :- |
2399| `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` |2407| `reason` | El motivo de la denegación. Para un veredicto del clasificador, en la mayoría de las sesiones nombra la regla que coincidió entre corchetes, como `[Data Exfiltration]`; consulta [Revisar denegaciones](/docs/es/auto-mode-config#review-denials) para ver 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 clasificador no estaba disponible, es el texto fijo `Classifier unavailable` |
2400 2408
2401<h4 id="permissiondenied-decision-control">2409<h4 id="permissiondenied-decision-control">
2402 Control de decisión de PermissionDenied2410 Control de decisiones de PermissionDenied
2403</h4>2411</h4>
2404 2412
2405Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta denegada. Devuelva un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:2413Los hooks PermissionDenied pueden indicarle al modelo que puede reintentar la llamada a herramienta denegada. Devuelve un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:
2406 2414
2407```json theme={null}2415```json theme={null}
2408{2416{
2413}2421}
2414```2422```
2415 2423
2416Cuando `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.2424Cuando `retry` es `true`, Claude Code agrega un mensaje a la conversación que le indica al modelo que puede reintentar la llamada a herramienta. Claude Code no revierte la denegación en sí. Si tu hook no devuelve JSON, o devuelve `retry: false`, la denegación se mantiene y el modelo recibe el mensaje de rechazo original.
2417 2425
2418Claude 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.2426Claude Code ignora `retry: true` cuando el clasificador no produjo [ningún veredicto sobre la acción](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action): su respuesta no se pudo analizar, o una verificación de seguridad independiente del modo automático rechazó la propia solicitud del clasificador. Para esas denegaciones, Claude Code ya le indica al modelo en el mensaje de rechazo si debe reintentar más tarde o continuar.
2419 2427
2420<h3 id="notification">2428<h3 id="notification">
2421 Notification2429 Notification
2422</h3>2430</h3>
2423 2431
2424Se ejecuta cuando Claude Code envía notificaciones. Coincide en el tipo de notificación. Omita el matcher para ejecutar hooks para todos los tipos de notificación.2432Se ejecuta cuando Claude Code envía notificaciones. Coincide con el tipo de notificación. Omite el matcher para ejecutar hooks para todos los tipos de notificación.
2425 2433
2426Recibe estos eventos de hook incluso con notificaciones de escritorio desactivadas: la configuración `preferredNotifChannel`, incluida `notifications_disabled`, cambia solo cómo se le alerta, no si su hook se ejecuta.2434Recibes estos eventos de hook incluso con las notificaciones de escritorio desactivadas: el ajuste `preferredNotifChannel`, incluido `notifications_disabled`, solo cambia cómo se te alerta, no si tu hook se ejecuta.
2427 2435
2428| Matcher | Cuándo se dispara |2436| Matcher | Cuándo se activa |
2429| :- | :- |2437| :- | :- |
2430| `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 |2438| `permission_prompt` | Claude necesita que apruebes el uso de una herramienta o la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en el sandbox, y la solicitud lleva esperando unos seis segundos |
2431| `idle_prompt` | Claude terminó de responder hace aproximadamente 60 segundos y no ha escrito desde entonces |2439| `idle_prompt` | Claude terminó de responder hace unos 60 segundos y no has escrito nada desde entonces |
2432| `auth_success` | La autenticación se completa |2440| `auth_success` | Se completa la autenticación |
2433| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no ha escrito durante aproximadamente seis segundos |2441| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no has escrito nada durante unos seis segundos |
2434| `elicitation_url_dialog` | Un servidor MCP le pide que abra una URL de navegador y no ha escrito durante aproximadamente seis segundos |2442| `elicitation_url_dialog` | Un servidor MCP te pide abrir una URL en el navegador y no has escrito nada durante unos seis segundos |
2435| `elicitation_complete` | Un servidor MCP reporta que una [elicitación de modo URL](#elicitation-input) está completa |2443| `elicitation_complete` | Un servidor MCP informa que una [elicitación en modo URL](#elicitation-input) está completa |
2436| `elicitation_response` | Se envía una respuesta de elicitación de MCP de vuelta al servidor |2444| `elicitation_response` | Se envía una respuesta de elicitación MCP de vuelta al servidor |
2437| `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 |2445| `agent_needs_input` | Una sesión en segundo plano comienza a esperar tu entrada mientras la [vista de agentes](/docs/es/agent-view) está abierta en una terminal. También se activa cuando una sesión de terminal te muestra una [pregunta de configuración de terminal de un compañero de un equipo de agentes](/docs/es/agent-teams#choose-a-display-mode) o el aviso del modo automático sobre [cargos por solicitudes del clasificador](/docs/es/auto-mode-classifier-billing) y no has escrito nada durante unos seis segundos |
2438| `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 |2446| `agent_completed` | Una sesión en segundo plano termina o falla. Se activa solo mientras la [vista de agentes](/docs/es/agent-view) está abierta en una terminal |
2439| `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) |2447| `quota_auto_resume_fired` | Claude Code continúa tu tarea después de que un límite de uso de claude.ai la pausó: en el restablecimiento, o antes cuando algo que haces en Claude Code durante la espera, como agregar créditos de uso, mejorar tu plan o cambiar de modelo, vuelve a habilitar el uso, con la [excepción del ajuste de modelo](/docs/es/interactive-mode#wait-for-a-usage-limit-to-reset) |
2440| `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 |2448| `quota_auto_resume_stale` | Un límite de uso de claude.ai se restableció mientras tu computadora estuvo suspendida durante más de unos 30 minutos. Claude Code espera a que presiones `Enter` en lugar de continuar. Después de una suspensión más corta, continúa y activa `quota_auto_resume_fired` en su lugar |
2441| `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** |2449| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar tu tarea: se desactivó [`autoContinueAtUsageLimit`](/docs/es/settings-reference#autocontinueatusagelimit) o el restablecimiento se alejó más de 24 horas durante una espera que Claude Code inició por su cuenta, la tarea continuada siguió alcanzando el límite, o la continuación se bloqueó antes de llegar al modelo. No se activa cuando presionas `Esc` o `Ctrl+C`, ni cuando eliges **Don't continue automatically** |
2442 2450
2443Los tipos `quota_auto_resume_fired`, `quota_auto_resume_stale`, y `quota_auto_resume_disabled` requieren Claude Code v2.1.234 o posterior.2451Los tipos `quota_auto_resume_fired`, `quota_auto_resume_stale` y `quota_auto_resume_disabled` requieren Claude Code v2.1.234 o posterior.
2444 2452
2445En sesiones de terminal, `permission_prompt` para una solicitud de red de un comando en sandbox requiere Claude Code v2.1.246 o posterior.2453En sesiones de terminal, `permission_prompt` para la solicitud de red de un comando en el sandbox requiere Claude Code v2.1.246 o posterior.
2446 2454
2447`agent_needs_input` para una pregunta de configuración de terminal de un compañero requiere Claude Code v2.1.248 o posterior.2455`agent_needs_input` para la pregunta de configuración de terminal de un compañero requiere Claude Code v2.1.248 o posterior.
2448 2456
2449<Note>2457<Note>
2450 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:2458 Los tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog` y `elicitation_url_dialog` comparten su temporización con las notificaciones de escritorio, por lo que en las sesiones de terminal solo los ves cuando parece que estás lejos de la terminal:
2451 2459
2452 * 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.2460 * Espera `permission_prompt` una vez que no hayas escrito nada durante unos seis segundos. El temporizador comienza cuando aparece la solicitud de permiso, y cada pulsación de tecla lo aplaza. Para ejecutar un hook inmediatamente cuando Claude pide permiso para usar una herramienta, usa [PermissionRequest](#permissionrequest) en su lugar.
2453 * 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.2461 * Espera `idle_prompt` unos 60 segundos después de que Claude termine de responder, y solo si no has escrito nada desde entonces y ningún agente en segundo plano, como un [subagente](/docs/es/sub-agents) en segundo plano, sigue en ejecución. Claude Code no envía `idle_prompt` mientras espera a que se restablezca un límite de uso de claude.ai. Cuando la espera termina por sí sola, se activa en su lugar uno de los tipos `quota_auto_resume_*`.
2454 * 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.2462 * Espera `elicitation_dialog` para un formulario de elicitación, o `elicitation_url_dialog` para una solicitud de URL del navegador, una vez que no hayas escrito nada durante unos seis segundos. Ambos comparten el mismo umbral de seis segundos que `permission_prompt`: el temporizador comienza cuando aparece el cuadro de diálogo, y cada pulsación de tecla lo aplaza.
2455 2463
2456 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.2464 Una solicitud de permiso o elicitación que llega mientras otro cuadro de diálogo está en pantalla mantiene el mismo umbral de seis segundos, contado desde que llega la solicitud. Su notificación puede llegarte mientras la solicitud sigue esperando detrás del cuadro de diálogo abierto.
2457</Note>2465</Note>
2458 2466
2459Claude 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:2467Claude Code temporiza `permission_prompt` de forma diferente en las sesiones en las que envía solicitudes de permiso al [callback `canUseTool`](/docs/es/agent-sdk/user-input) del Agent SDK, que es como Claude Desktop y la extensión de VS Code alojan Claude Code:
2460 2468
2461* Espere `permission_prompt` aproximadamente seis segundos después de que Claude solicita permiso. Claude Code no lo difiere mientras escribe.2469* Espera `permission_prompt` unos seis segundos después de que Claude pida permiso. Claude Code no lo aplaza mientras escribes.
2462* Si usted o un hook [PermissionRequest](#permissionrequest) responden antes, Claude Code no ejecuta `permission_prompt`.2470* Si tú o un hook [PermissionRequest](#permissionrequest) responden antes, Claude Code no ejecuta `permission_prompt`.
2463* Establezca [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.2471* Establece [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.
2464 2472
2465Antes de v2.1.233, `permission_prompt` no se disparaba en estas sesiones.2473Antes de v2.1.233, `permission_prompt` no se activaba en estas sesiones.
2466 2474
2467Use matchers separados para ejecutar diferentes manejadores dependiendo del tipo de notificación. Esta configuración dispara un script de alerta específico de permiso cuando Claude necesita aprobación de permiso y una notificación diferente cuando Claude ha estado inactivo:2475Usa matchers separados para ejecutar distintos manejadores según el tipo de notificación. Esta configuración activa un script de alerta específico de permisos cuando Claude necesita aprobación de permisos y una notificación diferente cuando Claude ha estado inactivo:
2468 2476
2469```json theme={null}2477```json theme={null}
2470{2478{
2497 Entrada de Notification2505 Entrada de Notification
2498</h4>2506</h4>
2499 2507
2500Además de los [campos de entrada comunes](#common-input-fields), los hooks Notification reciben `message` con el texto de notificación, un `title` opcional, y `notification_type` que indica qué tipo se disparó.2508Además de los [campos de entrada comunes](#common-input-fields), los hooks Notification reciben `message` con el texto de la notificación, un `title` opcional y `notification_type`, que indica qué tipo se activó.
2501 2509
2502```json theme={null}2510```json theme={null}
2503{2511{
2511}2519}
2512```2520```
2513 2521
2514Los 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.2522Los hooks Notification no pueden bloquear ni modificar notificaciones. Claude Code descarta sus campos `systemMessage` y `continue`, pero sigue emitiendo [`terminalSequence`](#emit-terminal-notifications), que es en lo que se basa el ejemplo de notificación de escritorio. Los hooks Notification están pensados para efectos secundarios, como reenviar la notificación a un servicio externo.
2515 2523
2516<h3 id="subagentstart">2524<h3 id="subagentstart">
2517 SubagentStart2525 SubagentStart
2518</h3>2526</h3>
2519 2527
2520Se 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.2528Se 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 en proceso de un [equipo de agentes](/docs/es/agent-teams) maneja un mensaje nuevo. Admite matchers para filtrar por nombre de tipo de agente. Para los agentes integrados, es el nombre del agente, como `general-purpose`, `Explore` o `Plan`. Para los [subagentes personalizados](/docs/es/sub-agents), es el campo `name` del frontmatter del agente, no el nombre del archivo.
2521 2529
2522Para 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$`.2530Para los subagentes incluidos en un [plugin](/docs/es/plugins/overview), el tipo de agente es el identificador con ámbito del plugin, como `my-plugin:reviewer`, no el nombre simple del frontmatter. Los dos puntos colocan un nombre con ámbito de plugin en la ruta de expresión regular, así que ancla el matcher con `^` y `$` para una coincidencia exacta: `^my-plugin:reviewer$`.
2523 2531
2524<h4 id="subagentstart-input">2532<h4 id="subagentstart-input">
2525 Entrada de SubagentStart2533 Entrada de SubagentStart
2526</h4>2534</h4>
2527 2535
2528Además de los [campos de entrada comunes](#common-input-fields), los hooks SubagentStart reciben `agent_id` con el identificador único para el subagente y `agent_type` con el nombre del agente que el matcher filtra.2536Además de los [campos de entrada comunes](#common-input-fields), los hooks SubagentStart reciben `agent_id` con el identificador único del subagente y `agent_type` con el nombre del agente sobre el que filtra el matcher.
2529 2537
2530```json theme={null}2538```json theme={null}
2531{2539{
2538}2546}
2539```2547```
2540 2548
2541Los 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:2549Los 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, puedes devolver:
2542 2550
2543| Campo | Descripción |2551| Campo | Descripción |
2544| :- | :- |2552| :- | :- |
2545| `additionalContext` | Cadena agregada al contexto del subagente al inicio de su conversación, antes de su primer prompt. Consulte [Agregar contexto para Claude](#add-context-for-claude) |2553| `additionalContext` | Cadena que se agrega al contexto del subagente al comienzo de su conversación, antes de su primer prompt. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
2546 2554
2547```json theme={null}2555```json theme={null}
2548{2556{
2553}2561}
2554```2562```
2555 2563
2556Cuando el hook se ejecuta nuevamente para el mismo subagente, Claude Code inyecta el contexto devuelto solo cuando el contexto del subagente no contiene ya la copia de una ejecución anterior. La copia inyectada al inicio permanece en su lugar, dejando el [caché de prompt](/docs/es/prompt-caching#subagents-and-the-cache) del subagente intacto. Después de que la [compactación automática](/docs/es/sub-agents#auto-compaction) descarta esa copia, Claude Code inyecta el contexto de la siguiente ejecución nuevamente.2564Cuando el hook se vuelve a ejecutar para el mismo subagente, Claude Code inyecta el contexto devuelto solo cuando el contexto del subagente aún no contiene la copia de una ejecución anterior. La copia inyectada al inicio permanece en su lugar, lo que mantiene intacta la [caché de prompts](/docs/es/prompt-caching#subagents-and-the-cache) del subagente. Después de que la [compactación automática](/docs/es/sub-agents#auto-compaction) descarta esa copia, Claude Code vuelve a inyectar el contexto de la siguiente ejecución.
2557 2565
2558<h3 id="subagentstop">2566<h3 id="subagentstop">
2559 SubagentStop2567 SubagentStop
2560</h3>2568</h3>
2561 2569
2562Se ejecuta cuando un subagente de Claude Code ha terminado de responder. Coincide en el tipo de agente, los mismos valores que SubagentStart.2570Se ejecuta cuando un subagente de Claude Code terminó de responder. Coincide con el tipo de agente, con los mismos valores que SubagentStart.
2563 2571
2564<h4 id="subagentstop-input">2572<h4 id="subagentstop-input">
2565 Entrada de SubagentStop2573 Entrada de SubagentStop
2566</h4>2574</h4>
2567 2575
2568Ademá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.2576Ademá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 que se usa para el filtrado del matcher. `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 anidada `subagents/`. El campo `last_assistant_message` contiene el contenido de texto de la respuesta final del subagente, para que los hooks puedan acceder a él sin analizar el archivo de transcripción.
2569 2577
2570No 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.2578No todos los eventos SubagentStop provienen de un subagente que Claude generó. Claude Code también ejecuta agentes internos para algunas de sus propias funciones, como las [sugerencias de prompts](/docs/es/interactive-mode#prompt-suggestions) y las [preguntas laterales con `/btw`](/docs/es/interactive-mode#side-questions-with-%2Fbtw), y SubagentStop también se activa cuando uno de ellos termina. Para esos eventos, `agent_type` es el nombre del agente con el que se ejecuta la propia sesión, como uno establecido con [`--agent`](/docs/es/cli-reference#cli-flags) o con el [ajuste `agent`](/docs/es/settings-reference#agent), y una cadena vacía cuando la sesión se ejecuta sin uno.
2571 2579
2572Un `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.2580Un `matcher` que nombra tipos de agente no coincide con un `agent_type` vacío. Un hook cuyo matcher se omite, es `""` o `"*"`, o es una expresión regular que coincide con una cadena vacía, también se ejecuta para eventos con un `agent_type` vacío.
2573 2581
2574En 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`.2582En 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 detenerse. El campo `last_assistant_message` contiene entonces 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 con `SubagentHandback` recibe como `tool_input.message`.
2575 2583
2576Los 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.2584Los hooks SubagentStop también reciben los arreglos `background_tasks` y `session_crons` descritos en [Entrada de Stop](#stop-input). Ambos arreglos tienen como ámbito la sesión principal, no el subagente.
2577 2585
2578```json theme={null}2586```json theme={null}
2579{2587{
2592}2600}
2593```2601```
2594 2602
2595Los 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.2603Los hooks SubagentStop usan el mismo formato de control de decisiones que los [hooks Stop](#stop-decision-control), incluido `hookSpecificOutput.additionalContext` con `hookEventName` establecido en `"SubagentStop"`, para retroalimentación que no es de error y que mantiene al subagente en ejecución. Devolver `decision: "block"` con un `reason` mantiene al subagente en ejecución y le entrega `reason` como su siguiente instrucción. Un hook que bloquea al terminar con código 2 entrega su mensaje de stderr de la misma manera. Para inyectar contexto en la sesión principal después de que un subagente regresa, usa en su lugar un hook [`PostToolUse`](#posttooluse) sobre la herramienta `Agent`.
2596 2604
2597<h3 id="taskcreated">2605<h3 id="taskcreated">
2598 TaskCreated2606 TaskCreated
2599</h3>2607</h3>
2600 2608
2601Se ejecuta cuando se está creando una tarea a través de la herramienta `TaskCreate`. Úselo para hacer cumplir convenciones de nomenclatura, requerir descripciones de tareas o evitar que se creen ciertas tareas. En una [sesión sin las herramientas Task](/docs/es/tools-reference#task-tool-availability), este evento no se dispara.2609Se ejecuta cuando se está creando una tarea mediante la herramienta `TaskCreate`. Úsalo para aplicar convenciones de nomenclatura, exigir descripciones de tareas o impedir que se creen ciertas tareas. En una [sesión sin las herramientas Task](/docs/es/tools-reference#task-tool-availability), este evento no se activa.
2602 2610
2603Los hooks TaskCreated no admiten matchers y se disparan en cada ocurrencia.2611Los hooks TaskCreated no admiten matchers y se activan en cada ocurrencia.
2604 2612
2605<h4 id="taskcreated-input">2613<h4 id="taskcreated-input">
2606 Entrada de TaskCreated2614 Entrada de TaskCreated
2607</h4>2615</h4>
2608 2616
2609Además de los [campos de entrada comunes](#common-input-fields), los hooks TaskCreated reciben `task_id`, `task_subject`, y opcionalmente `task_description`, `teammate_name`, y `team_name`.2617Además de los [campos de entrada comunes](#common-input-fields), los hooks TaskCreated reciben `task_id`, `task_subject` y, opcionalmente, `task_description`, `teammate_name` y `team_name`.
2610 2618
2611```json theme={null}2619```json theme={null}
2612{2620{
2626| :- | :- |2634| :- | :- |
2627| `task_id` | Identificador de la tarea que se está creando |2635| `task_id` | Identificador de la tarea que se está creando |
2628| `task_subject` | Título de la tarea |2636| `task_subject` | Título de la tarea |
2629| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2637| `task_description` | Descripción detallada de la tarea. Puede no estar presente |
2630| `teammate_name` | Nombre del compañero que está creando la tarea. Puede estar ausente |2638| `teammate_name` | Nombre del compañero que crea la tarea. Puede no estar presente |
2631| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2639| `team_name` | Obsoleto. Nombre del equipo derivado de la sesión; se eliminará en una versión futura |
2632 2640
2633<h4 id="taskcreated-decision-control">2641<h4 id="taskcreated-decision-control">
2634 Control de decisión de TaskCreated2642 Control de decisiones de TaskCreated
2635</h4>2643</h4>
2636 2644
2637Un hook TaskCreated puede bloquear la creación de dos formas. De cualquier forma, Claude Code elimina la tarea y devuelve su mensaje a Claude como el error de la herramienta. Claude Code ignora `continue: false` de este evento y Claude sigue trabajando.2645Un hook TaskCreated puede bloquear la creación de dos maneras. En cualquier caso, Claude Code elimina la tarea y devuelve tu mensaje a Claude como el error de la herramienta. Claude Code ignora `continue: false` de este evento y Claude sigue trabajando.
2638 2646
2639* **Código de salida 2**: Claude Code devuelve el texto stderr como el mensaje.2647* **Código de salida 2**: Claude Code devuelve el texto de stderr como mensaje.
2640* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como el mensaje.2648* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como mensaje.
2641 2649
2642Este ejemplo bloquea tareas cuyos asuntos no siguen el formato requerido:2650Este ejemplo bloquea las tareas cuyos asuntos no siguen el formato requerido:
2643 2651
2644```bash theme={null}2652```bash theme={null}
2645#!/bin/bash2653#!/bin/bash
2658 TaskCompleted2666 TaskCompleted
2659</h3>2667</h3>
2660 2668
2661Se 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.2669Se ejecuta cuando una tarea se está marcando como completada. Se activa en dos situaciones: cuando cualquier agente marca explícitamente una tarea como completada mediante la herramienta TaskUpdate, o cuando un compañero de un [equipo de agentes](/docs/es/agent-teams) termina su turno con tareas en curso. Úsalo para aplicar criterios de finalización, como exigir que pasen las pruebas o las verificaciones de lint antes de que una tarea pueda cerrarse.
2662 2670
2663Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.2671Los hooks TaskCompleted no admiten matchers y se activan en cada ocurrencia.
2664 2672
2665<h4 id="taskcompleted-input">2673<h4 id="taskcompleted-input">
2666 Entrada de TaskCompleted2674 Entrada de TaskCompleted
2667</h4>2675</h4>
2668 2676
2669Además de los [campos de entrada comunes](#common-input-fields), los hooks TaskCompleted reciben `task_id`, `task_subject`, y opcionalmente `task_description`, `teammate_name`, y `team_name`.2677Además de los [campos de entrada comunes](#common-input-fields), los hooks TaskCompleted reciben `task_id`, `task_subject` y, opcionalmente, `task_description`, `teammate_name` y `team_name`.
2670 2678
2671```json theme={null}2679```json theme={null}
2672{2680{
2687| :- | :- |2695| :- | :- |
2688| `task_id` | Identificador de la tarea que se está completando |2696| `task_id` | Identificador de la tarea que se está completando |
2689| `task_subject` | Título de la tarea |2697| `task_subject` | Título de la tarea |
2690| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2698| `task_description` | Descripción detallada de la tarea. Puede no estar presente |
2691| `teammate_name` | Nombre del compañero que está completando la tarea. Puede estar ausente |2699| `teammate_name` | Nombre del compañero que completa la tarea. Puede no estar presente |
2692| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2700| `team_name` | Obsoleto. Nombre del equipo derivado de la sesión; se eliminará en una versión futura |
2693 2701
2694<h4 id="taskcompleted-decision-control">2702<h4 id="taskcompleted-decision-control">
2695 Control de decisión de TaskCompleted2703 Control de decisiones de TaskCompleted
2696</h4>2704</h4>
2697 2705
2698Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:2706Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:
2699 2707
2700* **Código de salida 2**: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.2708* **Código de salida 2**: la tarea no se marca como completada y el mensaje de stderr se devuelve al modelo como retroalimentación.
2701* **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.2709* **JSON `{"continue": false, "stopReason": "..."}`**: cuando el evento lo activó un compañero que terminaba su turno, detiene al compañero por completo, igual que el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario. Cuando el evento lo activó la herramienta `TaskUpdate`, Claude Code ignora `continue: false`; el código de salida 2 sigue bloqueando la finalización.
2702 2710
2703Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:2711Este ejemplo ejecuta pruebas y bloquea la finalización de la tarea si fallan:
2704 2712
2705```bash theme={null}2713```bash theme={null}
2706#!/bin/bash2714#!/bin/bash
2720 Stop2728 Stop
2721</h3>2729</h3>
2722 2730
2723Se ejecuta cuando el agente principal de Claude Code ha terminado de responder. No se ejecuta si la detención ocurrió debido a una interrupción del usuario. Los errores de API disparan [StopFailure](#stopfailure) en su lugar.2731Se ejecuta cuando el agente principal de Claude Code terminó de responder. No se ejecuta si
2732la detención se produjo por una interrupción del usuario. Los errores de la API activan
2733[StopFailure](#stopfailure) en su lugar.
2724 2734
2725<Tip>2735<Tip>
2726 El comando [`/goal`](/docs/es/goal) es un atajo integrado para un hook Stop con alcance de sesión basado en prompt. Úselo cuando quiera que Claude siga trabajando hacia una condición sin escribir configuración de hook.2736 El comando [`/goal`](/docs/es/goal) es un atajo integrado para un hook Stop basado en prompts con ámbito de sesión. Úsalo cuando quieras que Claude siga trabajando hacia una condición sin escribir configuración de hooks.
2727</Tip>2737</Tip>
2728 2738
2729<h4 id="stop-input">2739<h4 id="stop-input">
2730 Entrada de Stop2740 Entrada de Stop
2731</h4>2741</h4>
2732 2742
2733Ademá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).2743Ademá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 stop. Verifica este valor o procesa la transcripción para evitar bloquear por una condición que nunca se resolverá. Claude Code aplica un límite de 8 continuaciones consecutivas: después de que los hooks stop continuaron el turno ocho veces seguidas, Claude Code sobrescribe el siguiente bloqueo y termina el turno. Para aumentar el límite, establece [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/es/env-vars).
2734 2744
2735El 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.2745El campo `last_assistant_message` contiene el contenido de texto de la respuesta final de Claude, para que los hooks puedan acceder a él sin analizar el archivo de transcripción. Para los hooks que actúan sobre el turno recién completado, como los hooks de lectura en voz alta o de notificación, usa este campo en lugar de leer `transcript_path`: no se garantiza que el archivo de transcripción incluya el mensaje final en el momento de Stop en todas las versiones.
2736 2746
2737Las 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.2747Los arreglos `background_tasks` y `session_crons` permiten a los hooks distinguir entre "la sesión terminó" y "la sesión está en pausa esperando que un trabajo en segundo plano la reactive". Ambos arreglos están presentes cuando el registro de tareas es accesible y están vacíos cuando no hay nada en curso ni programado.
2738 2748
2739Cada entrada en `background_tasks` describe una tarea en vuelo y usa estos campos:2749Cada entrada de `background_tasks` describe una tarea en curso y usa estos campos:
2740 2750
2741| Campo | Descripción |2751| Campo | Descripción |
2742| :- | :- |2752| :- | :- |
2743| `id` | Identificador de tarea |2753| `id` | Identificador de la tarea |
2744| `type` | Etiqueta de tipo de tarea amigable como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session`, o `MCP task`. Cada etiqueta identifica qué característica de Claude Code creó la tarea. Vuelve al discriminante sin procesar para tipos no reconocidos |2754| `type` | Etiqueta legible del tipo de tarea, como `shell`, `subagent`, `monitor`, `workflow`, `teammate`, `cloud session` o `MCP task`. Cada etiqueta identifica qué función de Claude Code creó la tarea. Recurre al discriminante sin procesar para tipos no reconocidos |
2745| `status` | Estado actual de la tarea |2755| `status` | Estado actual de la tarea |
2746| `description` | Descripción de texto libre, limitada a 1000 caracteres con un marcador `… [+N chars]` en cadena cuando se recorta |2756| `description` | Descripción de texto libre, limitada a 1000 caracteres con un marcador `… [+N chars]` dentro de la cadena cuando se recorta |
2747| `command` | Línea de comando de shell, limitada a 1000 caracteres. Presente solo para tareas `shell` |2757| `command` | Línea de comando del shell, limitada a 1000 caracteres. Presente solo para tareas `shell` |
2748| `agent_type` | Nombre de tipo de subagente. Presente solo para tareas `subagent` |2758| `agent_type` | Nombre del tipo de subagente. Presente solo para tareas `subagent` |
2749| `server` | Nombre del servidor MCP. Presente solo para tareas `monitor` y `MCP task` |2759| `server` | Nombre del servidor MCP. Presente solo para tareas `monitor` y `MCP task` |
2750| `tool` | Nombre de herramienta MCP. Presente solo para tareas `monitor` y `MCP task` |2760| `tool` | Nombre de la herramienta MCP. Presente solo para tareas `monitor` y `MCP task` |
2751| `name` | Nombre del flujo de trabajo. Presente solo para tareas `workflow` |2761| `name` | Nombre del workflow. Presente solo para tareas `workflow` |
2752 2762
2753Cada entrada en `session_crons` describe un despertar programado con alcance de sesión, originario de `CronCreate`, `ScheduleWakeup`, y `/loop`:2763Cada entrada de `session_crons` describe una reactivación programada con ámbito de sesión, procedente de `CronCreate`, `ScheduleWakeup` y `/loop`:
2754 2764
2755| Campo | Descripción |2765| Campo | Descripción |
2756| :- | :- |2766| :- | :- |
2757| `id` | Identificador de tarea cron |2767| `id` | Identificador de la tarea cron |
2758| `schedule` | Expresión cron, por ejemplo `0 9 * * 1-5` |2768| `schedule` | Expresión cron, por ejemplo `0 9 * * 1-5` |
2759| `recurring` | `false` para despertares únicos cuya programación codifica un único tiempo de disparo, `true` para tareas que se disparan nuevamente en cada coincidencia |2769| `recurring` | `false` para reactivaciones únicas cuya programación codifica un solo momento de activación, `true` para tareas que se vuelven a activar en cada coincidencia |
2760| `prompt` | Prompt enviado cuando se dispara el cron, limitado a 1000 caracteres con el mismo marcador `… [+N chars]` |2770| `prompt` | Prompt enviado cuando se activa el cron, limitado a 1000 caracteres con el mismo marcador `… [+N chars]` |
2761 2771
2762Este ejemplo muestra una entrada de Stop con una tarea de shell en vuelo y un cron recurrente:2772Este ejemplo muestra una entrada de Stop con una tarea de shell en curso y un cron recurrente:
2763 2773
2764```json theme={null}2774```json theme={null}
2765{2775{
2791```2801```
2792 2802
2793<h4 id="stop-decision-control">2803<h4 id="stop-decision-control">
2794 Control de decisión de Stop2804 Control de decisiones de Stop
2795</h4>2805</h4>
2796 2806
2797Los hooks `Stop` y `SubagentStop` pueden controlar si Claude continúa. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:2807Los hooks `Stop` y `SubagentStop` pueden controlar si Claude continúa. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver estos campos específicos del evento:
2798 2808
2799| Campo | Descripción |2809| Campo | Descripción |
2800| :- | :- |2810| :- | :- |
2801| `decision` | `"block"` evita que Claude se detenga. Omita para permitir que Claude se detenga |2811| `decision` | `"block"` impide que Claude se detenga. Omítelo para permitir que Claude se detenga |
2802| `reason` | Requerido cuando `decision` es `"block"`. Le dice a Claude por qué debería continuar |2812| `reason` | Obligatorio cuando `decision` es `"block"`. Le indica a Claude por qué debe continuar |
2803| `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 |2813| `hookSpecificOutput.additionalContext` | Retroalimentación para Claude que no es de error. La conversación continúa para que Claude pueda actuar en consecuencia, pero a diferencia de `decision: "block"` se muestra en la transcripción como retroalimentación del hook en lugar de como un error del hook |
2804 2814
2805Un 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.2815Un hook que bloquea al terminar con código 2 se enruta igual que `reason`: Claude recibe el mensaje de stderr como la explicación de por qué debe continuar.
2806 2816
2807```json theme={null}2817```json theme={null}
2808{2818{
2811}2821}
2812```2822```
2813 2823
2814Use `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:2824Usa `additionalContext` cuando el hook funciona según lo previsto y le da orientación a Claude, como "ejecuta el conjunto de pruebas antes de terminar". Mantiene la conversación en marcha a través de las mismas protecciones contra bucles que `decision: "block"`, es decir, la entrada `stop_hook_active` y el límite de 8 continuaciones consecutivas, pero la transcripción lo etiqueta como `Stop hook feedback` y no se muestra ninguna notificación de error del hook:
2815 2825
2816```json theme={null}2826```json theme={null}
2817{2827{
2826 StopFailure2836 StopFailure
2827</h3>2837</h3>
2828 2838
2829Se ejecuta en lugar de [Stop](#stop) cuando el turno termina debido a un error de API. Claude Code ignora la salida y el código de salida del hook, aparte de [`terminalSequence`](#emit-terminal-notifications). Úselo para registrar fallos, enviar alertas o tomar acciones de recuperación cuando Claude no puede completar una respuesta debido a límites de velocidad, problemas de autenticación u otros errores de API.2839Se ejecuta en lugar de [Stop](#stop) cuando el turno termina debido a un error de la API. Claude Code ignora la salida y el código de salida del hook, excepto [`terminalSequence`](#emit-terminal-notifications). Úsalo para registrar fallas, enviar alertas o tomar medidas de recuperación cuando Claude no puede completar una respuesta debido a rate limits, problemas de autenticación u otros errores de la API.
2830 2840
2831<h4 id="stopfailure-input">2841<h4 id="stopfailure-input">
2832 Entrada de StopFailure2842 Entrada de StopFailure
2833</h4>2843</h4>
2834 2844
2835Ademá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.2845Ademá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 el filtrado del matcher.
2836 2846
2837| Campo | Descripción |2847| Campo | Descripción |
2838| :- | :- |2848| :- | :- |
2839| `error` | Tipo de error: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, o `unknown` |2849| `error` | Tipo de error: `rate_limit`, `overloaded`, `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error` o `unknown` |
2840| `error_details` | Detalles adicionales sobre el error, cuando esté disponible |2850| `error_details` | Detalles adicionales sobre el error, cuando están disponibles |
2841| `last_assistant_message` | El texto de error renderizado mostrado en la conversación. A diferencia de `Stop` y `SubagentStop`, donde este campo contiene la salida conversacional de Claude, para `StopFailure` contiene la cadena de error de la API en sí, como `"API Error: Rate limit reached"` |2851| `last_assistant_message` | El texto de error renderizado que se muestra en la conversación. A diferencia de `Stop` y `SubagentStop`, donde este campo contiene la salida conversacional de Claude, para `StopFailure` contiene la propia cadena de error de la API, como `"API Error: Rate limit reached"` |
2842 2852
2843```json theme={null}2853```json theme={null}
2844{2854{
2852}2862}
2853```2863```
2854 2864
2855Los hooks StopFailure no tienen control de decisión. Se ejecutan solo para propósitos de notificación y registro.2865Los hooks StopFailure no tienen control de decisiones. Se ejecutan solo con fines de notificación y registro.
2856 2866
2857<h3 id="teammateidle">2867<h3 id="teammateidle">
2858 TeammateIdle2868 TeammateIdle
2859</h3>2869</h3>
2860 2870
2861Se 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.2871Se ejecuta cuando un compañero de un [equipo de agentes](/docs/es/agent-teams) está a punto de quedar inactivo después de terminar su turno. Úsalo para aplicar controles de calidad antes de que un compañero deje de trabajar, como exigir que pasen las verificaciones de lint o verificar que existan los archivos de salida.
2862 2872
2863Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.2873Los hooks TeammateIdle no admiten matchers y se activan en cada ocurrencia.
2864 2874
2865<h4 id="teammateidle-input">2875<h4 id="teammateidle-input">
2866 Entrada de TeammateIdle2876 Entrada de TeammateIdle
2882 2892
2883| Campo | Descripción |2893| Campo | Descripción |
2884| :- | :- |2894| :- | :- |
2885| `teammate_name` | Nombre del compañero que está a punto de quedarse inactivo |2895| `teammate_name` | Nombre del compañero que está a punto de quedar inactivo |
2886| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2896| `team_name` | Obsoleto. Nombre del equipo derivado de la sesión; se eliminará en una versión futura |
2887 2897
2888<h4 id="teammateidle-decision-control">2898<h4 id="teammateidle-decision-control">
2889 Control de decisión de TeammateIdle2899 Control de decisiones de TeammateIdle
2890</h4>2900</h4>
2891 2901
2892Los hooks TeammateIdle admiten dos formas de controlar el comportamiento del compañero:2902Los hooks TeammateIdle admiten dos formas de controlar el comportamiento del compañero:
2893 2903
2894* **Código de salida 2**: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.2904* **Código de salida 2**: el compañero recibe el mensaje de stderr como retroalimentación y sigue trabajando en lugar de quedar inactivo.
2895* **JSON `{"continue": false, "stopReason": "..."}`**: detiene completamente al compañero, coincidiendo con el comportamiento del hook Stop. El `stopReason` se muestra al usuario.2905* **JSON `{"continue": false, "stopReason": "..."}`**: detiene al compañero por completo, igual que el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario.
2896 2906
2897Este ejemplo verifica que exista un artefacto de compilación antes de permitir que un compañero se quede inactivo:2907Este ejemplo verifica que exista un artefacto de compilación antes de permitir que un compañero quede inactivo:
2898 2908
2899```bash theme={null}2909```bash theme={null}
2900#!/bin/bash2910#!/bin/bash
2911 ConfigChange2921 ConfigChange
2912</h3>2922</h3>
2913 2923
2914Se 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.2924Se ejecuta cuando un archivo de configuración cambia durante una sesión. Úsalo para auditar cambios de configuración, aplicar políticas de seguridad o bloquear modificaciones no autorizadas a los archivos de configuración.
2915 2925
2916Claude 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.2926Claude Code ejecuta los hooks ConfigChange cuando cambia un archivo de configuración, un archivo de política administrada o un archivo de skill. Para la política administrada, solo los ejecuta cuando cambia `managed-settings.json` o un archivo en `managed-settings.d/`. Aplica la [configuración administrada por el servidor](/docs/es/server-managed-settings) y los cambios en las preferencias administradas de macOS o en la política del registro de Windows sin ejecutarlos. En WSL con [`wslInheritsWindowsSettings`](/docs/es/settings-reference#wslinheritswindowssettings), también aplica un archivo de configuración administrada del lado de Windows que cambió en su sondeo de políticas sin ejecutarlos.
2917 2927
2918El matcher filtra en la fuente de configuración:2928El matcher filtra según el origen de la configuración:
2919 2929
2920| Matcher | Cuándo se dispara |2930| Matcher | Cuándo se activa |
2921| :- | :- |2931| :- | :- |
2922| `user_settings` | `~/.claude/settings.json` cambia |2932| `user_settings` | Cambia `~/.claude/settings.json` |
2923| `project_settings` | `.claude/settings.json` cambia |2933| `project_settings` | Cambia `.claude/settings.json` |
2924| `local_settings` | `.claude/settings.local.json` cambia |2934| `local_settings` | Cambia `.claude/settings.local.json` |
2925| `policy_settings` | `managed-settings.json` o un archivo en `managed-settings.d/` cambia |2935| `policy_settings` | Cambia `managed-settings.json` o un archivo en `managed-settings.d/` |
2926| `skills` | Un archivo de skill en `.claude/skills/` cambia |2936| `skills` | Cambia un archivo de skill en `.claude/skills/` |
2927 2937
2928Este ejemplo registra todos los cambios de configuración para auditoría de seguridad:2938Este ejemplo registra todos los cambios de configuración para auditorías de seguridad:
2929 2939
2930```json theme={null}2940```json theme={null}
2931{2941{
2949 Entrada de ConfigChange2959 Entrada de ConfigChange
2950</h4>2960</h4>
2951 2961
2952Además de los [campos de entrada comunes](#common-input-fields), los hooks ConfigChange reciben `source` y opcionalmente `file_path`. El campo `source` indica qué tipo de configuración cambió, y `file_path` proporciona la ruta al archivo específico que se modificó.2962Además de los [campos de entrada comunes](#common-input-fields), los hooks ConfigChange reciben `source` y, opcionalmente, `file_path`. El campo `source` indica qué tipo de configuración cambió, y `file_path` proporciona la ruta del archivo específico que se modificó.
2953 2963
2954```json theme={null}2964```json theme={null}
2955{2965{
2963```2973```
2964 2974
2965<h4 id="configchange-decision-control">2975<h4 id="configchange-decision-control">
2966 Control de decisión de ConfigChange2976 Control de decisiones de ConfigChange
2967</h4>2977</h4>
2968 2978
2969Los 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.2979Los hooks ConfigChange pueden impedir que los cambios de configuración surtan efecto. Usa el código de salida 2 o un `decision` en JSON para impedir el cambio. Cuando se bloquea, la nueva configuración no se aplica a la sesión en ejecución.
2970 2980
2971| Campo | Descripción |2981| Campo | Descripción |
2972| :- | :- |2982| :- | :- |
2973| `decision` | `"block"` evita que el cambio de configuración se aplique. Omita para permitir el cambio |2983| `decision` | `"block"` impide que se aplique el cambio de configuración. Omítelo para permitir el cambio |
2974| `reason` | Aceptado pero nunca mostrado |2984| `reason` | Se acepta, pero nunca se muestra |
2975 2985
2976```json theme={null}2986```json theme={null}
2977{2987{
2980}2990}
2981```2991```
2982 2992
2983Los 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).2993Los cambios de `policy_settings` no se pueden bloquear. Los hooks siguen activándose para los orígenes `policy_settings` cuando cambia un archivo de configuración administrada en la máquina, así que puedes usarlos para registrar esas ediciones, pero cualquier decisión de bloqueo se ignora. Esto garantiza que la configuración administrada por la empresa siempre surta efecto. Claude Code no ejecuta hooks `ConfigChange` cuando llega o se actualiza la [configuración administrada por el servidor](/docs/es/server-managed-settings).
2984 2994
2985Claude 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.2995Claude Code actúa según 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 ni a ti ni a Claude, ya sea que bloquees con `reason` o con stderr y código de salida 2. Claude Code solo escribe una línea en el registro de depuración.
2986 2996
2987<h3 id="cwdchanged">2997<h3 id="cwdchanged">
2988 CwdChanged2998 CwdChanged
2989</h3>2999</h3>
2990 3000
2991Se ejecuta cuando un comando de shell en la conversación principal cambia el directorio de trabajo, por ejemplo cuando Claude ejecuta un comando `cd`. Úselo para reaccionar a cambios de directorio: recargar variables de entorno, activar cadenas de herramientas específicas del proyecto o ejecutar scripts de configuración automáticamente. Se empareja con [FileChanged](#filechanged) para herramientas como [direnv](https://direnv.net/) que administran el entorno por directorio.3001Se ejecuta cuando un comando de shell en la conversación principal cambia el directorio de trabajo, por ejemplo cuando Claude ejecuta un comando `cd`. Úsalo para reaccionar a los cambios de directorio: recargar variables de entorno, activar cadenas de herramientas específicas del proyecto o ejecutar scripts de configuración automáticamente. Se combina con [FileChanged](#filechanged) para herramientas como [direnv](https://direnv.net/) que administran el entorno por directorio.
2992 3002
2993Los hooks CwdChanged 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, cuando Claude Code las borra.3003Los hooks CwdChanged tienen acceso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Las variables escritas en ese archivo persisten en los comandos Bash posteriores hasta el siguiente evento CwdChanged, cuando Claude Code las borra.
2994 3004
2995CwdChanged no admite matchers y se dispara en cada ocurrencia.3005CwdChanged no admite matchers y se activa en cada ocurrencia.
2996 3006
2997<h4 id="cwdchanged-input">3007<h4 id="cwdchanged-input">
2998 Entrada de CwdChanged3008 Entrada de CwdChanged
3015 Salida de CwdChanged3025 Salida de CwdChanged
3016</h4>3026</h4>
3017 3027
3018Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, los hooks CwdChanged pueden devolver `watchPaths` para establecer dinámicamente qué rutas de archivo [FileChanged](#filechanged) observa:3028Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, los hooks CwdChanged pueden devolver `watchPaths` para establecer dinámicamente qué rutas de archivo vigila [FileChanged](#filechanged):
3019 3029
3020| Campo | Descripción |3030| Campo | Descripción |
3021| :- | :- |3031| :- | :- |
3022| `watchPaths` | Matriz de rutas absolutas. Reemplaza la lista de observación dinámica actual. Las rutas de su configuración `matcher` siempre se observan. Devolver una matriz vacía borra la lista dinámica, que es típico al entrar en un nuevo directorio |3032| `watchPaths` | Arreglo de rutas absolutas. Reemplaza la lista de vigilancia dinámica actual. Las rutas de tu configuración de `matcher` siempre se vigilan. Devolver un arreglo vacío borra la lista dinámica, lo cual es habitual al entrar en un directorio nuevo |
3023 3033
3024Los hooks CwdChanged no tienen control de decisión. No pueden bloquear el cambio de directorio.3034Los hooks CwdChanged no tienen control de decisiones. No pueden bloquear el cambio de directorio.
3025 3035
3026Claude Code lee `watchPaths` y `systemMessage` de su salida JSON y descarta `continue`. En sesiones interactivas, muestra el `systemMessage` como una breve notificación de terminal. El mensaje no llega al flujo de mensajes del SDK.3036Claude Code lee `watchPaths` y `systemMessage` de su salida JSON y descarta `continue`. En las sesiones interactivas, muestra el `systemMessage` como una breve notificación en la terminal. El mensaje no llega al flujo de mensajes del SDK.
3027 3037
3028<h3 id="directoryadded">3038<h3 id="directoryadded">
3029 DirectoryAdded3039 DirectoryAdded
3030</h3>3040</h3>
3031 3041
3032Se 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.3042Se ejecuta después de que agregas un directorio de trabajo a mitad de sesión con el comando `/add-dir`, o después de que un cliente del SDK agrega uno con la solicitud de control `register_repo_root`. Úsalo para preparar un repositorio recién agregado, por ejemplo instalando sus dependencias.
3033 3043
3034Claude Code no dispara este evento cuando:3044Claude Code no activa este evento cuando:
3035 3045
3036* Pasa un directorio con la bandera de inicio `--add-dir`; [SessionStart](#sessionstart) cubre esos directorios3046* Pasas un directorio con el flag de inicio `--add-dir`; [SessionStart](#sessionstart) cubre esos directorios
3037* Agrega un directorio en la pestaña Workspace `/permissions`3047* Agregas un directorio en la pestaña Workspace de `/permissions`
3038* Agrega un directorio que ya es un directorio de trabajo o está dentro de uno3048* Agregas un directorio que ya es un directorio de trabajo o que está dentro de uno
3039 3049
3040Claude Code se dispara DirectoryAdded después de actualizar el estado de sandbox y permiso, por lo que las herramientas en sandbox ya ven el nuevo directorio cuando se ejecuta su hook. Los comandos del hook en sí se ejecutan sin sandbox.3050Claude Code activa DirectoryAdded después de actualizar el estado del sandbox y de los permisos, por lo que las herramientas en el sandbox ya ven el nuevo directorio cuando se ejecuta tu hook. Los comandos de los hooks en sí se ejecutan fuera del sandbox.
3041 3051
3042Claude Code no espera el hook: la adición se completa inmediatamente, y el hook se ejecuta en segundo plano con el tiempo de espera predeterminado de 600 segundos.3052Claude Code no espera al hook: la adición se completa inmediatamente y el hook se ejecuta en segundo plano con el tiempo de espera predeterminado de 600 segundos.
3043 3053
3044El matcher filtra en cómo se agregó el directorio:3054El matcher filtra según cómo se agregó el directorio:
3045 3055
3046| Matcher | Cuándo se dispara |3056| Matcher | Cuándo se activa |
3047| :- | :- |3057| :- | :- |
3048| `slash_command` | Agrega un directorio con `/add-dir` |3058| `slash_command` | Agregas un directorio con `/add-dir` |
3049| `register_repo_root` | Un cliente del SDK agrega un directorio con la solicitud de control `register_repo_root` |3059| `register_repo_root` | Un cliente del SDK agrega un directorio con la solicitud de control `register_repo_root` |
3050 3060
3051<h4 id="directoryadded-input">3061<h4 id="directoryadded-input">
3057| Campo | Descripción |3067| Campo | Descripción |
3058| :- | :- |3068| :- | :- |
3059| `directory` | Ruta absoluta del directorio que se agregó |3069| `directory` | Ruta absoluta del directorio que se agregó |
3060| `source` | Cómo se agregó el directorio, `"slash_command"` para `/add-dir` o `"register_repo_root"` para la solicitud de control del SDK |3070| `source` | Cómo se agregó el directorio: `"slash_command"` para `/add-dir` o `"register_repo_root"` para la solicitud de control del SDK |
3061 3071
3062```json theme={null}3072```json theme={null}
3063{3073{
3070}3080}
3071```3081```
3072 3082
3073Los hooks DirectoryAdded no tienen control de decisión. No pueden bloquear la adición, que ya se ha completado cuando se ejecuta el hook. Claude Code descarta el campo `continue` de su salida JSON y muestra el resto diferente por fuente:3083Los hooks DirectoryAdded no tienen control de decisiones. No pueden bloquear la adición, que ya se completó cuando se ejecuta el hook. Claude Code descarta el campo `continue` de su salida JSON y presenta el resto de forma diferente según el origen:
3074 3084
3075* `slash_command`: Claude Code entrega el `systemMessage` del hook a Claude como contexto en el siguiente turno de conversación, en lugar de mostrárselo. Un recuento de hooks fallidos aparece en la transcripción. La salida de fallo completo va al registro de depuración3085* `slash_command`: Claude Code entrega el `systemMessage` del hook a Claude como contexto en el siguiente turno de la conversación, en lugar de mostrártelo a ti. En la transcripción aparece un recuento de hooks fallidos. La salida completa de las fallas va al registro de depuración
3076* `register_repo_root`: Claude Code escribe la salida `systemMessage` y la salida de fallo solo en el registro de depuración3086* `register_repo_root`: Claude Code escribe la salida de `systemMessage` y la salida de las fallas solo en el registro de depuración
3077 3087
3078<h3 id="filechanged">3088<h3 id="filechanged">
3079 FileChanged3089 FileChanged
3080</h3>3090</h3>
3081 3091
3082Se 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.3092Se ejecuta cuando un archivo vigilado cambia en disco. Claude Code detecta los cambios con un observador del sistema de archivos, no inspeccionando las llamadas a herramientas, por lo que ejecuta el hook sin importar qué cambió el archivo: una llamada a la herramienta `Edit` o `Write`, un script que Claude ejecuta con `Bash` o un proceso completamente ajeno a Claude Code. Un uso común es recargar variables de entorno cuando cambian los archivos de configuración del proyecto.
3083 3093
3084El `matcher` para este evento sirve dos roles:3094El `matcher` de este evento cumple dos funciones:
3085 3095
3086* **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`.3096* **Construir la lista de vigilancia**: el valor se divide por `|` y cada segmento se registra como un nombre de archivo literal en el directorio de trabajo, así que `".envrc|.env"` vigila exactamente esos dos archivos. Los patrones de expresiones regulares no sirven aquí: un valor como `^\.env` vigilaría un archivo llamado literalmente `^\.env`.
3087* **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.3097* **Filtrar qué hooks se ejecutan**: cuando cambia un archivo vigilado, 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 que cambió.
3088 3098
3089Este 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:3099Este ejemplo normaliza los finales de línea en `data.csv` después de cualquier cambio, incluido un comando `Bash` o un script externo que reescribe el archivo:
3090 3100
3091```json theme={null}3101```json theme={null}
3092{3102{
3106}3116}
3107```3117```
3108 3118
3109El hook lee la ruta absoluta del archivo cambiado del campo `file_path` de la [entrada JSON](#filechanged-input) en stdin. Su guardia `grep` prueba lo mismo que `perl` elimina, un CR al final de una línea, por lo que la ejecución después de una normalización sale sin tocar el archivo. Una guardia más suelta se repite para siempre, porque `perl -i` reescribe el archivo incluso cuando no sustituye nada y Claude Code ejecuta el hook nuevamente después de cada reescritura. Guarde este script en `/path/to/normalize-line-endings.sh` y hágalo ejecutable:3119El hook lee la ruta absoluta del archivo que cambió del campo `file_path` de la [entrada JSON](#filechanged-input) en stdin. Su verificación con `grep` comprueba lo mismo que elimina `perl`, un CR al final de una línea, así que la ejecución posterior a una normalización termina sin tocar el archivo. Una verificación más laxa entra en un bucle infinito, porque `perl -i` reescribe el archivo incluso cuando no sustituye nada y Claude Code vuelve a ejecutar el hook después de cada reescritura. Guarda este script en `/path/to/normalize-line-endings.sh` y hazlo ejecutable:
3110 3120
3111```bash theme={null}3121```bash theme={null}
3112#!/bin/bash3122#!/bin/bash
3116fi3126fi
3117```3127```
3118 3128
3119Para 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.3129Para confirmar que el hook funciona, pídele 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 de línea LF.
3120 3130
3121Para 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 `*`.3131Para vigilar archivos que no puedes nombrar de antemano, devuelve [`watchPaths`](#filechanged-output) desde un hook para actualizar la lista de vigilancia dinámicamente. Claude Code inicia el observador solo cuando algo nombra un archivo que vigilar, así que inicializa 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 sigue filtrando qué grupos de hooks se ejecutan cuando cambia un archivo vigilado, así que deja sin matcher el grupo que maneja las rutas dinámicas: así coincide con todos los archivos vigilados y no agrega nada a la lista de vigilancia. Un matcher `"*"` también coincide con todos los archivos, pero Claude Code lo registra en la lista de vigilancia como cualquier otro valor, como un archivo literal llamado `*`.
3122 3132
3123Los 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.3133Los hooks FileChanged tienen acceso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Las variables escritas en ese archivo persisten en los comandos Bash posteriores hasta el siguiente evento [CwdChanged](#cwdchanged), cuando Claude Code las borra.
3124 3134
3125<h4 id="filechanged-input">3135<h4 id="filechanged-input">
3126 Entrada de FileChanged3136 Entrada de FileChanged
3130 3140
3131| Campo | Descripción |3141| Campo | Descripción |
3132| :- | :- |3142| :- | :- |
3133| `file_path` | Ruta absoluta al archivo que cambió |3143| `file_path` | Ruta absoluta del archivo que cambió |
3134| `event` | Qué sucedió: `"change"` para un archivo modificado, `"add"` para un archivo creado, o `"unlink"` para un archivo eliminado |3144| `event` | Qué ocurrió: `"change"` para un archivo modificado, `"add"` para un archivo creado o `"unlink"` para un archivo eliminado |
3135 3145
3136```json theme={null}3146```json theme={null}
3137{3147{
3148 Salida de FileChanged3158 Salida de FileChanged
3149</h4>3159</h4>
3150 3160
3151Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, los hooks FileChanged pueden devolver `watchPaths` para actualizar dinámicamente qué rutas de archivo se observan:3161Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, los hooks FileChanged pueden devolver `watchPaths` para actualizar dinámicamente qué rutas de archivo se vigilan:
3152 3162
3153| Campo | Descripción |3163| Campo | Descripción |
3154| :- | :- |3164| :- | :- |
3155| `watchPaths` | Matriz de rutas absolutas. Reemplaza la lista de observación dinámica actual. Las rutas de su configuración `matcher` siempre se observan. Úselo cuando su script de hook descubra archivos adicionales para observar basándose en el archivo cambiado |3165| `watchPaths` | Arreglo de rutas absolutas. Reemplaza la lista de vigilancia dinámica actual. Las rutas de tu configuración de `matcher` siempre se vigilan. Úsalo cuando tu script de hook descubra archivos adicionales que vigilar en función del archivo que cambió |
3156 3166
3157Los hooks FileChanged no tienen control de decisión. No pueden bloquear el cambio de archivo que ocurre.3167Los hooks FileChanged no tienen control de decisiones. No pueden impedir que se produzca el cambio del archivo.
3158 3168
3159Claude Code lee `watchPaths` y `systemMessage` de su salida JSON y descarta `continue`. En sesiones interactivas, muestra el `systemMessage` como una breve notificación de terminal. El mensaje no llega al flujo de mensajes del SDK.3169Claude Code lee `watchPaths` y `systemMessage` de su salida JSON y descarta `continue`. En las sesiones interactivas, muestra el `systemMessage` como una breve notificación en la terminal. El mensaje no llega al flujo de mensajes del SDK.
3160 3170
3161<h3 id="worktreecreate">3171<h3 id="worktreecreate">
3162 WorktreeCreate3172 WorktreeCreate
3163</h3>3173</h3>
3164 3174
3165Se 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.3175Se ejecuta cuando se está creando un worktree, ya sea desde `claude --worktree`, desde un [subagente que usa `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 predeterminado de git, lo que te permite usar un sistema de control de versiones diferente, como SVN, Perforce o Mercurial.
3166 3176
3167Debido 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.3177Como el hook reemplaza por completo el comportamiento predeterminado, [`.worktreeinclude`](/docs/es/worktrees#copy-gitignored-files-into-worktrees) no se procesa. Si necesitas copiar archivos de configuración locales como `.env` en el nuevo worktree, hazlo dentro de tu script de hook.
3168 3178
3169El hook debe devolver la ruta al directorio del worktree creado. Claude Code usa esta ruta como el directorio de trabajo para la sesión aislada. Consulte [salida de WorktreeCreate](#worktreecreate-output) para saber cómo cada tipo de hook devuelve la ruta.3179El hook debe devolver la ruta del directorio del worktree creado. Claude Code usa esta ruta como directorio de trabajo para la sesión aislada. Consulta [Salida de WorktreeCreate](#worktreecreate-output) para ver cómo devuelve la ruta cada tipo de hook.
3170 3180
3171Claude Code actúa sobre el éxito del hook y la ruta devuelta, y descarta `systemMessage` y `continue`.3181Claude Code actúa según el éxito del hook y la ruta devuelta, y descarta `systemMessage` y `continue`.
3172 3182
3173Este ejemplo crea una copia de trabajo SVN e imprime la ruta para que Claude Code la use. Reemplace la URL del repositorio con la suya:3183Este ejemplo crea una copia de trabajo de SVN e imprime la ruta para que Claude Code la use. Reemplaza la URL del repositorio por la tuya:
3174 3184
3175```json theme={null}3185```json theme={null}
3176{3186{
3189}3199}
3190```3200```
3191 3201
3192El 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.3202El hook lee el `name` del worktree de la entrada JSON en stdin, extrae una copia nueva en un directorio nuevo e imprime la ruta del directorio. El `echo` de la última línea es lo que Claude Code lee como la ruta del worktree. Redirige cualquier otra salida a stderr para que no interfiera con la ruta.
3193 3203
3194<h4 id="worktreecreate-input">3204<h4 id="worktreecreate-input">
3195 Entrada de WorktreeCreate3205 Entrada de WorktreeCreate
3196</h4>3206</h4>
3197 3207
3198Además de los [campos de entrada comunes](#common-input-fields), los hooks WorktreeCreate reciben el campo `name`. Este es un identificador slug para el nuevo worktree, ya sea especificado por el usuario o generado automáticamente, por ejemplo `bold-oak-a3f2`.3208Además de los [campos de entrada comunes](#common-input-fields), los hooks WorktreeCreate reciben el campo `name`. Es un identificador tipo slug para el nuevo worktree, especificado por el usuario o generado automáticamente, por ejemplo `bold-oak-a3f2`.
3199 3209
3200```json theme={null}3210```json theme={null}
3201{3211{
3211 Salida de WorktreeCreate3221 Salida de WorktreeCreate
3212</h4>3222</h4>
3213 3223
3214Los 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:3224Los hooks WorktreeCreate no usan el modelo estándar de decisión de permitir/bloquear. En su lugar, el éxito o el fallo del hook determina el resultado. El hook debe devolver la ruta al directorio del worktree creado:
3215 3225
3216* **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.3226* **Hooks de comando** (`type: "command"`): imprime la ruta como la última línea no vacía de stdout. Claude Code elimina los códigos de escape ANSI antes de leer esa línea, por lo que se ignoran los banners de inicio del shell impresos antes de tu `echo`. Redirige cualquier otra salida del hook a stderr.
3217* **Hooks HTTP** (`type: "http"`): devuelva `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.3227* **Hooks HTTP** (`type: "http"`): devuelve `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.
3218 3228
3219Si el hook falla o no produce una ruta, la creación del worktree falla con un error.3229Si el hook falla o no produce ninguna ruta, la creación del worktree falla con un error.
3220 3230
3221Claude Code resuelve una ruta relativa contra el directorio en el que se ejecutó el hook, colapsando cualquier segmento `.` o `..` en él. Si la ruta resultante no es un directorio en el que Claude Code pueda entrar, la sesión imprime un error que nombra la ruta y sale con código 1.3231Claude Code resuelve una ruta relativa respecto al directorio en el que se ejecutó el hook, colapsando cualquier segmento `.` o `..` que contenga. Si la ruta resultante no es un directorio al que Claude Code pueda entrar, la sesión imprime un error que indica la ruta y termina con el código 1.
3222 3232
3223Claude Code rechaza una ruta absoluta que contiene segmentos `.` o `..`, y cualquier ruta que pase a través de un enlace simbólico por debajo de la raíz del repositorio, porque un enlace simbólico comprometido en el repositorio podría redirigir el worktree fuera de él. El error nombra el componente rechazado. Devuelva una ruta normalizada que no pase a través de un enlace simbólico dentro del repositorio. Antes de v2.1.216, la creación del worktree seguía la ruta del hook sin este cribado.3233Claude Code rechaza una ruta absoluta que contenga segmentos `.` o `..`, y cualquier ruta que pase por un enlace simbólico debajo de la raíz del repositorio, porque un enlace simbólico confirmado en el repositorio podría redirigir el worktree fuera de él. El error indica el componente rechazado. Devuelve una ruta normalizada que no pase por un enlace simbólico dentro del repositorio. Antes de v2.1.216, la creación del worktree seguía la ruta del hook sin esta verificación.
3224 3234
3225<h3 id="worktreeremove">3235<h3 id="worktreeremove">
3226 WorktreeRemove3236 WorktreeRemove
3227</h3>3237</h3>
3228 3238
3229Se ejecuta cuando se está eliminando un worktree. Este es el homólogo de limpieza de [WorktreeCreate](#worktreecreate). El evento se dispara cuando:3239Se ejecuta cuando se está eliminando un worktree. Es la contraparte de limpieza de [WorktreeCreate](#worktreecreate). El evento se dispara cuando:
3230 3240
3231* sale de una sesión `--worktree` y elige eliminarla3241* sales de una sesión `--worktree` y eliges eliminarlo
3232* un subagente con `isolation: "worktree"` termina3242* un subagente con `isolation: "worktree"` termina
3233* elimina una [sesión de fondo](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook3243* eliminas una [sesión en segundo plano](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook
3234 3244
3235Para 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:3245Para los worktrees basados en git, Claude Code se encarga de la limpieza automáticamente con `git worktree remove`. Si configuraste un hook WorktreeCreate, combínalo con un hook WorktreeRemove para controlar la limpieza de los worktrees que crea:
3236 3246
3237* **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.3247* **Sin hook WorktreeRemove**: cuando sales de una sesión `--worktree` y eliges eliminarlo, Claude Code recurre a `git worktree remove --force` sobre la ruta que devolvió tu hook WorktreeCreate, de modo que se elimina un worktree que git reconoce. Un worktree que git no reconoce, por ejemplo uno que tu hook creó con un sistema de control de versiones distinto de git, permanece en el disco. Para saber qué hace la eliminación de una [sesión en segundo plano](/docs/es/agent-view#what-deleting-a-session-removes) con un worktree creado por un hook, consulta las reglas de eliminación de agent view.
3238* **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.3248* **El hook termina con 0**: el worktree se considera eliminado. Claude Code no lee nada más del hook, así que asegúrate de que tu hook haya eliminado el directorio.
3239* **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).3249* **El hook termina con un código distinto de cero**: la eliminación falla si el directorio en `worktree_path` sigue existiendo después, y el worktree permanece en el disco sin recurrir a git. Un hook que eliminó el directorio antes de terminar con un código distinto de cero se considera eliminado. Para saber cómo se informa el fallo, consulta [Entrada de WorktreeRemove](#worktreeremove-input).
3240 3250
3241Claude 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.3251Claude Code nunca elimina una rama que pertenezca a un worktree creado por un hook, porque solo conoce la ruta que devolvió tu hook WorktreeCreate. Si tu hook WorktreeCreate crea una rama, elimínala en tu hook WorktreeRemove.
3242 3252
3243Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.3253Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.
3244 3254
3245Para 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.3255Al eliminar una sesión en segundo plano, Claude Code verifica la ruta del worktree almacenada antes de ejecutar el hook y rechaza una ruta que sea un enlace simbólico o que pase por uno debajo de la raíz del repositorio. El hook se ejecuta para un worktree que todavía contiene archivos solo cuando confirmas la eliminación en [agent view](/docs/es/agent-view#what-deleting-a-session-removes); para ese tipo de worktree, [`claude rm`](/docs/es/agent-view#manage-sessions-from-the-shell) conserva la sesión y el worktree. Antes de v2.1.216, el hook se ejecutaba sobre la ruta almacenada sin estas comprobaciones.
3246 3256
3247Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:3257Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:
3248 3258
3279}3289}
3280```3290```
3281 3291
3282El 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:3292El código de salida de un hook WorktreeRemove decide el resultado. Cuando un hook termina con un código distinto de cero y el directorio en `worktree_path` sigue existiendo después, la eliminación falla:
3283 3293
3284* El worktree permanece en el disco, y el comando del hook y stderr van al [registro de depuración](#debug-hooks).3294* El worktree permanece en el disco, y el comando del hook y su stderr van al [registro de depuración](#debug-hooks).
3285* 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.3295* Si estabas eliminando una sesión en segundo plano, la sesión también permanece. El mensaje de rechazo en [agent view](/docs/es/agent-view#what-deleting-a-session-removes) informa cómo terminó el hook, como `exited 1`, cita el inicio de su stderr e indica si volver a eliminar la sesión elimina el directorio de todos modos.
3286 3296
3287<h3 id="precompact">3297<h3 id="precompact">
3288 PreCompact3298 PreCompact
3290 3300
3291Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.3301Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.
3292 3302
3293El valor del matcher indica si la compactación fue disparada manualmente o automáticamente:3303El valor del matcher indica si la compactación se activó de forma manual o automática:
3294 3304
3295| Matcher | Cuándo se dispara |3305| Matcher | Cuándo se dispara |
3296| :- | :- |3306| :- | :- |
3297| `manual` | `/compact` |3307| `manual` | `/compact` |
3298| `auto` | Compactación automática cuando la conversación alcanza la [ventana de compactación automática](/docs/es/model-config#set-the-auto-compact-window) |3308| `auto` | Compactación automática cuando la conversación alcanza la [ventana de compactación automática](/docs/es/model-config#set-the-auto-compact-window) |
3299 3309
3300Salga 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"`.3310Termina con el código 2 para bloquear la compactación. Para un `/compact` manual, el mensaje de stderr se muestra al usuario. También puedes bloquear devolviendo JSON con `"decision": "block"`.
3301 3311
3302Bloquear 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.3312Bloquear la compactación automática tiene efectos distintos según cuándo se dispare. Si la compactación se activó 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 se activó para recuperarse de un error de límite de contexto ya devuelto por la API, el error subyacente aparece y la solicitud actual falla.
3303 3313
3304Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.3314Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.
3305 3315
3324 PostCompact3334 PostCompact
3325</h3>3335</h3>
3326 3336
3327Se 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.3337Se ejecuta después de que Claude Code completa una operación de compactación. Usa este evento para reaccionar al nuevo estado compactado, por ejemplo para registrar el resumen generado o actualizar un estado externo. Claude Code descarta los campos `systemMessage` y `continue` de un hook PostCompact.
3328 3338
3329Los mismos valores de matcher se aplican que para `PreCompact`:3339Se aplican los mismos valores de matcher que para `PreCompact`:
3330 3340
3331| Matcher | Cuándo se dispara |3341| Matcher | Cuándo se dispara |
3332| :- | :- |3342| :- | :- |
3333| `manual` | Después de `/compact` |3343| `manual` | Después de `/compact` |
3334| `auto` | Después de compactación automática cuando la conversación alcanza la [ventana de compactación automática](/docs/es/model-config#set-the-auto-compact-window) |3344| `auto` | Después de la compactación automática cuando la conversación alcanza la [ventana de compactación automática](/docs/es/model-config#set-the-auto-compact-window) |
3335 3345
3336<h4 id="postcompact-input">3346<h4 id="postcompact-input">
3337 Entrada de PostCompact3347 Entrada de PostCompact
3338</h4>3348</h4>
3339 3349
3340Además de los [campos de entrada comunes](#common-input-fields), los hooks PostCompact reciben `trigger` y `compact_summary`. El campo `compact_summary` contiene el resumen de conversación generado por la operación de compactación.3350Además de los [campos de entrada comunes](#common-input-fields), los hooks PostCompact reciben `trigger` y `compact_summary`. El campo `compact_summary` contiene el resumen de la conversación generado por la operación de compactación.
3341 3351
3342```json theme={null}3352```json theme={null}
3343{3353{
3350}3360}
3351```3361```
3352 3362
3353Los hooks PostCompact no tienen control de decisión. No pueden afectar el resultado de la compactación pero pueden realizar tareas de seguimiento.3363Los hooks PostCompact no tienen control de decisión. No pueden afectar el resultado de la compactación, pero pueden realizar tareas posteriores.
3354 3364
3355<h3 id="premodelswitch">3365<h3 id="premodelswitch">
3356 PreModelSwitch3366 PreModelSwitch
3357</h3>3367</h3>
3358 3368
3359Se 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.3369Se ejecuta antes de que Claude Code aplique un cambio de modelo que tú o un cliente solicitaron. Úsalo para bloquear un cambio, requerir confirmación o mostrar lo que costará el cambio antes de que ocurra.
3360 3370
3361PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:3371PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:
3362 3372
3363* `/model <name>` y el selector `/model`3373* `/model <name>` y el selector de `/model`
3364* El selector de modelo `Option+P` o `Alt+P`3374* El selector de modelo de `Option+P` o `Alt+P`
3365* La configuración Model en `/config`3375* El ajuste Model en `/config`
3366* Activar [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión3376* Activar el [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión
3367* 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)3377* Una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un host del [Agent SDK](/docs/es/agent-sdk/typescript#query-object) o desde [Remote Control](/docs/es/remote-control)
3368 3378
3369Claude 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.3379Claude Code no ejecuta los hooks PreModelSwitch para los cambios que hace por su cuenta, como un [respaldo automático de modelo](/docs/es/model-config#automatic-model-fallback) o la restauración del modelo cuando reanudas una sesión. Esos cambios solo llegan a [PostModelSwitch](#postmodelswitch).
3370 3380
3371Claude 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.3381Claude Code compara el matcher con el nombre canónico del modelo al que cambia la sesión, ignorando cualquier sufijo `[1m]`. Un alias como `opus`, un ID de modelo con fecha y un ID específico de un proveedor, como un ID de modelo de Amazon Bedrock, coinciden todos con el único nombre canónico al que se resuelven, por lo que `claude-opus-5` cubre todas las formas de escribir Opus 5.
3372 3382
3373Cuando 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.3383Cuando Claude Code no puede determinar un nombre canónico para el destino, por ejemplo un ID de modelo personalizado que solo conoce tu [gateway de LLM](/docs/es/llm-gateway), ejecuta todos los hooks PreModelSwitch sin importar el matcher. Por lo tanto, un hook que bloquea debe comprobar `to_model` en su entrada en lugar de depender solo del matcher.
3374 3384
3375Escriba 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:3385Escribe 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 además comprueba `to_model` en la entrada del hook, de modo que rechaza un cambio a Opus 4.6 terminando con el código 2 y deja pasar cualquier otro destino:
3376 3386
3377<Tabs>3387<Tabs>
3378 <Tab title="macOS/Linux">3388 <Tab title="macOS/Linux">
3379 El comando verifica `to_model` con `jq`:3389 El comando comprueba `to_model` con `jq`:
3380 3390
3381 ```json theme={null}3391 ```json theme={null}
3382 {3392 {
3398 </Tab>3408 </Tab>
3399 3409
3400 <Tab title="Windows (PowerShell)">3410 <Tab title="Windows (PowerShell)">
3401 Registre un hook de comando que ejecute un script a través de PowerShell:3411 Registra un hook de comando que ejecute un script mediante PowerShell:
3402 3412
3403 ```json theme={null}3413 ```json theme={null}
3404 {3414 {
3425 }3435 }
3426 ```3436 ```
3427 3437
3428 Guarde este script en `.claude/hooks/block-opus-46.ps1` en su proyecto:3438 Guarda este script en `.claude/hooks/block-opus-46.ps1` en tu proyecto:
3429 3439
3430 ```powershell theme={null}3440 ```powershell theme={null}
3431 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3441 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3438 </Tab>3448 </Tab>
3439</Tabs>3449</Tabs>
3440 3450
3441Para confirmar que el hook funciona, ejecute `/model claude-opus-4-6` desde una sesión que ejecuta un modelo diferente. Claude Code mantiene el modelo actual e informa que un hook PreModelSwitch bloqueó el cambio, con su mensaje como la razón.3451Para confirmar que el hook funciona, ejecuta `/model claude-opus-4-6` desde una sesión que use un modelo diferente. Claude Code mantiene el modelo actual e informa que un hook PreModelSwitch bloqueó el cambio, con tu mensaje como motivo.
3442 3452
3443<h4 id="premodelswitch-input">3453<h4 id="premodelswitch-input">
3444 Entrada de PreModelSwitch3454 Entrada de PreModelSwitch
3445</h4>3455</h4>
3446 3456
3447Ademá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.3457Además de los [campos de entrada comunes](#common-input-fields), los hooks PreModelSwitch reciben los campos de esta tabla. Los últimos cinco describen lo que cuesta volver a enviar la conversación al nuevo modelo, de modo que un hook puede mostrar esa cifra antes de que ocurra el cambio.
3448 3458
3449| Campo | Tipo | Descripción |3459| Campo | Tipo | Descripción |
3450| :- | :- | :- |3460| :- | :- | :- |
3451| `from_model` | string | ID de modelo del que cambia el cambio |3461| `from_model` | string | ID del modelo desde el que se cambia |
3452| `to_model` | string | ID de modelo al que cambia el cambio. El matcher compara contra el nombre canónico de este modelo |3462| `to_model` | string | ID del modelo al que se cambia. El matcher se compara con el nombre canónico de este modelo |
3453| `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 |3463| `requested_model` | string o `null` | El modelo que indicó la solicitud: un alias como `opus`, un ID de modelo completo, o `null` cuando la solicitud era para el modelo predeterminado |
3454| `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 |3464| `source` | string | De dónde vino la solicitud: `"command"` para `/model <name>`, el ajuste Model en `/config` o la activación del 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 del Agent SDK o desde Remote Control |
3455| `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 |3465| `context_tokens` | number | Tokens que la siguiente solicitud vuelve a enviar como su prompt: los tokens de entrada, de lectura de caché, de creación de caché y de salida de la última respuesta en la conversación principal, combinados. `0` antes de la primera respuesta |
3456| `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 |3466| `prompt_cache_warm` | boolean | Si la caché de prompts del modelo actual probablemente sigue caliente, lo que significa que el cambio la pierde |
3457| `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"` |3467| `cache_ttl` | string | [Duración de la caché de prompts](/docs/es/prompt-caching#cache-lifetime) que Claude Code solicita para esta sesión: `"5m"` o `"1h"` |
3458| `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 |3468| `estimated_cache_write_usd` | number | Costo estimado en dólares estadounidenses de escribir `context_tokens` en la caché de prompts de `to_model` a la tarifa de `cache_ttl`, sin incluir la siguiente respuesta. Es posible que el servidor no necesite volver a almacenar en caché todo el contexto, así que trátalo como una estimación |
3459| `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 |3469| `pricing` | string | Cómo calculó Claude Code el precio de `estimated_cache_write_usd`: `"configured"` con las tarifas propias de tu organización cuando las ha configurado, `"catalog"` con el precio de lista, o `"default"` cuando `to_model` no tiene un precio conocido y Claude Code asumió una tarifa predeterminada |
3460 3470
3461Este ejemplo muestra la entrada para `/model opus` en una sesión que ejecuta Sonnet 5:3471Este ejemplo muestra la entrada para `/model opus` en una sesión que usa Sonnet 5:
3462 3472
3463```json theme={null}3473```json theme={null}
3464{3474{
3482 Control de decisión de PreModelSwitch3492 Control de decisión de PreModelSwitch
3483</h4>3493</h4>
3484 3494
3485Los 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.3495Los hooks `PreModelSwitch` pueden cancelar el cambio, pedir al usuario que lo confirme o dejar que continúe. El código de salida 2 o un `decision: "block"` de nivel superior cancela el cambio.
3486 3496
3487Para 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:3497Para un control más preciso, devuelve `permissionDecision` y `permissionDecisionReason` en un objeto `hookSpecificOutput`, como en [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` acepta `"allow"`, `"deny"` y `"ask"`. No acepta `"defer"`, `updatedInput` ni `additionalContext`. La siguiente tabla describe ambos campos:
3488 3498
3489| Campo | Descripción |3499| Campo | Descripción |
3490| :- | :- |3500| :- | :- |
3491| `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 |3501| `permissionDecision` | `"allow"` continúa y omite la [confirmación que Claude Code muestra mientras la caché de prompts está caliente](/docs/es/prompt-caching#switching-models). `"deny"` cancela el cambio. `"ask"` pide al usuario que lo confirme |
3492| `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"` |3502| `permissionDecisionReason` | Para `"deny"`, se muestra al usuario como el motivo por el que se bloqueó el cambio, o se devuelve como el error de una solicitud `set_model`. Para `"ask"`, se muestra en la solicitud de confirmación. Se ignora para `"allow"` |
3493 3503
3494Solo `/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.3504Solo `/model` en una sesión interactiva puede mostrar la solicitud de `"ask"`. En todas las demás superficies, incluido el modo no interactivo con el flag `-p`, `/config` y las solicitudes `set_model`, Claude Code trata `"ask"` como un rechazo.
3495 3505
3496Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:3506Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:
3497 3507
3505}3515}
3506```3516```
3507 3517
3508Cuando múltiples hooks PreModelSwitch devuelven decisiones diferentes, la precedencia es `deny` > `ask` > `allow`.3518Cuando varios hooks PreModelSwitch devuelven decisiones diferentes, la precedencia es `deny` > `ask` > `allow`.
3509 3519
3510Claude Code muestra al usuario cualquier `systemMessage` que devuelva su hook independientemente de la decisión, por lo que un hook de informe de costo puede devolver `{"systemMessage": "..."}` y salir con 0.3520Claude Code muestra al usuario cualquier `systemMessage` que devuelva tu hook, independientemente de la decisión, por lo que un hook que informe del costo puede devolver `{"systemMessage": "..."}` y terminar con 0.
3511 3521
3512Un 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.3522Un hook PreModelSwitch que no responde antes de su tiempo de espera bloquea el cambio. En [PreToolUse](#timeouts), en cambio, un hook de comando cuyo tiempo de espera se agota deja que la llamada a herramienta continúe. El tiempo de espera predeterminado para este evento es de 30 segundos. `PreModelSwitch` solo ejecuta hooks `command`, `http` y `mcp_tool`, por lo que los valores predeterminados de `prompt` y `agent` no se aplican.
3513 3523
3514Un 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).3524Un hook que termina con un código distinto de 0 o 2 y no imprime ninguna decisión JSON no bloquea: Claude Code muestra su stderr y aplica el cambio, como se describe en [Otros códigos de salida](#other-exit-codes).
3515 3525
3516<h3 id="postmodelswitch">3526<h3 id="postmodelswitch">
3517 PostModelSwitch3527 PostModelSwitch
3518</h3>3528</h3>
3519 3529
3520Se ejecuta después de que el modelo de la sesión cambia. Úselo para dar orientación específica del modelo a Claude sin editar cada CLAUDE.md, por ejemplo una instrucción de toda la organización que se aplica en ciertos modelos.3530Se ejecuta después de que cambia el modelo de la sesión. Úsalo para dar a Claude indicaciones específicas del modelo sin editar cada CLAUDE.md, por ejemplo una instrucción para toda la organización que se aplique en ciertos modelos.
3521 3531
3522PostModelSwitch 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:3532PostModelSwitch requiere Claude Code v2.1.251 o posterior. No puede bloquear, porque el modelo ya cambió. Claude Code ejecuta los hooks PostModelSwitch después de cualquiera de estos cambios:
3523 3533
3524* Un cambio que usted o un cliente solicitó3534* Un cambio que tú o un cliente solicitaron
3525* Un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión3535* Un [respaldo automático de modelo](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión
3526* Una configuración como [`opusplan`](/docs/es/model-config#opusplan-model-setting) entrando o saliendo del modo de plan3536* Un ajuste como [`opusplan`](/docs/es/model-config#opusplan-model-setting) al entrar o salir del modo plan
3527* Claude Code restaurando el modelo cuando reanuda una sesión3537* Claude Code restaurando el modelo cuando reanudas una sesión
3528 3538
3529Claude 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.3539Claude Code no ejecuta los hooks PostModelSwitch cuando un modelo de una [cadena de modelos de respaldo](/docs/es/model-config#fallback-model-chains) atiende un turno, porque esa sustitución dura un turno y deja sin cambios el modelo de la sesión.
3530 3540
3531El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.3541El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code lo compara con el nombre canónico del modelo al que cambió la sesión.
3532 3542
3533Este ejemplo agrega orientación siempre que el modelo de la sesión cambia a cualquier modelo Opus:3543Este ejemplo agrega indicaciones siempre que el modelo de la sesión cambia a cualquier modelo Opus:
3534 3544
3535```json theme={null}3545```json theme={null}
3536{3546{
3550}3560}
3551```3561```
3552 3562
3553Para confirmar que el hook funciona, cambie a un modelo Opus desde una sesión que ejecuta un modelo diferente, por ejemplo ejecute `/model opus` desde una sesión Sonnet, luego pregunte a Claude qué orientación tiene sobre el modelo actual.3563Para confirmar que el hook funciona, cambia a un modelo Opus desde una sesión que use un modelo diferente, por ejemplo ejecuta `/model opus` desde una sesión de Sonnet, y luego pregúntale a Claude qué indicaciones tiene sobre el modelo actual.
3554 3564
3555<h4 id="postmodelswitch-input">3565<h4 id="postmodelswitch-input">
3556 Entrada de PostModelSwitch3566 Entrada de PostModelSwitch
3557</h4>3567</h4>
3558 3568
3559Los 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.3569Los hooks PostModelSwitch reciben los mismos campos que [PreModelSwitch](#premodelswitch-input), con `hook_event_name` establecido en `"PostModelSwitch"` y dos valores más de `source`: `"auto"` para un respaldo automático u otro cambio que Claude Code hizo por su cuenta, y `"resume"` para el modelo restaurado cuando reanudas una sesión.
3560 3570
3561`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es la configuración de modelo guardada que Claude Code restauró.3571`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es el ajuste de modelo guardado que restauró Claude Code.
3562 3572
3563<h4 id="postmodelswitch-decision-control">3573<h4 id="postmodelswitch-decision-control">
3564 Control de decisión de PostModelSwitch3574 Control de decisión de PostModelSwitch
3565</h4>3575</h4>
3566 3576
3567Claude Code toma su [stdout de texto plano](#exit-code-0) del hook en salida 0, o `additionalContext` de salida JSON, y lo entrega a Claude con la siguiente solicitud después del cambio. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puede devolver:3577Claude Code toma la [salida stdout en texto plano](#exit-code-0) de tu hook al terminar con 0, o `additionalContext` de la salida JSON, y la entrega a Claude con la siguiente solicitud después del cambio. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puedes devolver:
3568 3578
3569| Campo | Descripción |3579| Campo | Descripción |
3570| :- | :- |3580| :- | :- |
3571| `additionalContext` | Cadena agregada al contexto de Claude con la siguiente solicitud. Consulte [Agregar contexto para Claude](#add-context-for-claude) |3581| `additionalContext` | Cadena agregada al contexto de Claude con la siguiente solicitud. Consulta [Agregar contexto para Claude](#add-context-for-claude) |
3572 3582
3573Si 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.3583Si el hook no ha terminado en los cinco segundos posteriores a que envíes el siguiente prompt, Claude Code envía esa solicitud sin la salida y la adjunta a la solicitud siguiente. Si el modelo cambia varias veces antes de la siguiente solicitud, Claude Code entrega solo la salida correspondiente al modelo de destino del último cambio.
3574 3584
3575<h3 id="sessionend">3585<h3 id="sessionend">
3576 SessionEnd3586 SessionEnd
3577</h3>3587</h3>
3578 3588
3579Se 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.3589Se ejecuta cuando termina una sesión de Claude Code. Es útil para tareas de limpieza, registrar estadísticas
3590de la sesión o guardar el estado de la sesión. Admite matchers para filtrar por motivo de salida.
3580 3591
3581El campo `reason` en la entrada del hook indica por qué terminó la sesión:3592El campo `reason` en la entrada del hook indica por qué terminó la sesión:
3582 3593
3583| Razón | Descripción |3594| Motivo | Descripción |
3584| :- | :- |3595| :- | :- |
3585| `clear` | Sesión borrada con comando `/clear` |3596| `clear` | Sesión borrada con el comando `/clear` |
3586| `resume` | Sesión cambiada a través de `/resume` interactivo |3597| `resume` | Sesión cambiada mediante `/resume` interactivo |
3587| `logout` | Usuario cerró sesión |3598| `logout` | El usuario cerró sesión |
3588| `prompt_input_exit` | Usuario salió mientras la entrada de prompt era visible |3599| `prompt_input_exit` | El usuario salió mientras la entrada del prompt estaba visible |
3589| `other` | Otras razones de salida |3600| `other` | Otros motivos de salida |
3590| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Elimine de sus matchers `SessionEnd` |3601| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Quítalo de tus matchers de `SessionEnd` |
3591 3602
3592<h4 id="sessionend-input">3603<h4 id="sessionend-input">
3593 Entrada de SessionEnd3604 Entrada de SessionEnd
3594</h4>3605</h4>
3595 3606
3596Además de los [campos de entrada comunes](#common-input-fields), los hooks SessionEnd reciben un campo `reason` que indica por qué terminó la sesión. Consulte la [tabla de razones](#sessionend) anterior para todos los valores.3607Además de los [campos de entrada comunes](#common-input-fields), los hooks SessionEnd reciben un campo `reason` que indica por qué terminó la sesión. Consulta la [tabla de motivos](#sessionend) anterior para ver todos los valores.
3597 3608
3598```json theme={null}3609```json theme={null}
3599{3610{
3605}3616}
3606```3617```
3607 3618
3608Los 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`.3619Los hooks SessionEnd no tienen control de decisión. No pueden bloquear la finalización de la sesión, pero pueden realizar tareas de limpieza. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage`.
3609 3620
3610Los 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:3621Los hooks SessionEnd tienen un tiempo de espera predeterminado de 1.5 segundos. Se aplica cuando sales, ejecutas `/clear` o cambias de sesión con `/resume` interactivo. Puedes darle más tiempo a un hook de dos maneras:
3611 3622
3612* **`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.3623* **`timeout` por hook**: establece `timeout` en la configuración de ese hook. El presupuesto total aumenta automáticamente hasta igualar el `timeout` por hook más alto de tus archivos de configuración, hasta 60 segundos. Si aumentas el presupuesto de esta manera, un hook sin su propio `timeout` sigue conservando el valor predeterminado. Los tiempos de espera establecidos en hooks proporcionados por plugins no aumentan el presupuesto.
3613* **`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`.3624* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: establece esta variable de entorno en milisegundos para sobrescribir el presupuesto explícitamente. El valor que establezcas también se convierte en el tiempo de espera de cada hook sin su propio `timeout`.
3614 3625
3615Este ejemplo establece el presupuesto en 5 segundos:3626Este ejemplo establece el presupuesto en 5 segundos:
3616 3627
3618CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3629CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3619```3630```
3620 3631
3621Antes de v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` solo aumentaba el presupuesto general, y un hook sin su propio `timeout` aún se cancelaba después de 1.5 segundos.3632Antes de v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` solo aumentaba el presupuesto total, y un hook sin su propio `timeout` se seguía cancelando después de 1.5 segundos.
3622 3633
3623<h3 id="elicitation">3634<h3 id="elicitation">
3624 Elicitation3635 Elicitation
3625</h3>3636</h3>
3626 3637
3627Se ejecuta cuando un servidor MCP solicita entrada del usuario a mitad de tarea. De forma predeterminada, Claude Code muestra un diálogo interactivo para que el usuario responda. Los hooks pueden interceptar esta solicitud y responder programáticamente, omitiendo completamente el diálogo.3638Se ejecuta cuando un servidor MCP solicita información al usuario en mitad de una tarea. De forma predeterminada, Claude Code muestra un cuadro de diálogo interactivo para que el usuario responda. Los hooks pueden interceptar esta solicitud y responder de forma programática, omitiendo el cuadro de diálogo por completo.
3628 3639
3629El campo matcher coincide contra el nombre del servidor MCP.3640El campo matcher se compara con el nombre del servidor MCP.
3630 3641
3631<h4 id="elicitation-input">3642<h4 id="elicitation-input">
3632 Entrada de Elicitation3643 Entrada de Elicitation
3633</h4>3644</h4>
3634 3645
3635Además de los [campos de entrada comunes](#common-input-fields), los hooks Elicitation reciben `mcp_server_name`, `message`, y campos opcionales `mode`, `url`, `elicitation_id`, y `requested_schema`.3646Además de los [campos de entrada comunes](#common-input-fields), los hooks Elicitation reciben `mcp_server_name`, `message` y los campos opcionales `mode`, `url`, `elicitation_id` y `requested_schema`.
3636 3647
3637Para elicitación de modo formulario, el caso más común:3648Para la elicitación en modo formulario, el caso más común:
3638 3649
3639```json theme={null}3650```json theme={null}
3640{3651{
3654}3665}
3655```3666```
3656 3667
3657Para elicitación de modo URL, utilizada para autenticación basada en navegador:3668Para la elicitación en modo URL, usada para la autenticación basada en el navegador:
3658 3669
3659```json theme={null}3670```json theme={null}
3660{3671{
3673 Salida de Elicitation3684 Salida de Elicitation
3674</h4>3685</h4>
3675 3686
3676Para responder programáticamente sin mostrar el diálogo, devuelva un objeto JSON con `hookSpecificOutput`:3687Para responder de forma programática sin mostrar el cuadro de diálogo, devuelve un objeto JSON con `hookSpecificOutput`:
3677 3688
3678```json theme={null}3689```json theme={null}
3679{3690{
3689 3700
3690| Campo | Valores | Descripción |3701| Campo | Valores | Descripción |
3691| :- | :- | :- |3702| :- | :- | :- |
3692| `action` | `accept`, `decline`, `cancel` | Si aceptar, rechazar o cancelar la solicitud |3703| `action` | `accept`, `decline`, `cancel` | Si se acepta, rechaza o cancela la solicitud |
3693| `content` | object | Valores de campo de formulario a enviar. Solo se usa cuando `action` es `accept` |3704| `content` | object | Valores de los campos del formulario que se envían. Solo se usa cuando `action` es `accept` |
3694 3705
3695El código de salida 2 niega la elicitación. Claude Code no muestra su mensaje stderr en ningún lugar.3706El código de salida 2 deniega la elicitación. Claude Code no muestra tu mensaje de stderr en ningún lugar.
3696 3707
3697Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook Elicitation y descarta `systemMessage` y `continue`.3708Claude Code actúa según `hookSpecificOutput` de la salida JSON de un hook Elicitation y descarta `systemMessage` y `continue`.
3698 3709
3699<h3 id="elicitationresult">3710<h3 id="elicitationresult">
3700 ElicitationResult3711 ElicitationResult
3701</h3>3712</h3>
3702 3713
3703Se ejecuta después de que un usuario responde a una elicitación de MCP. Los hooks pueden observar, modificar o bloquear la respuesta antes de que se devuelva al servidor MCP.3714Se ejecuta después de que un usuario responde a una elicitación de MCP. Los hooks pueden observar, modificar o bloquear la respuesta antes de que se envíe de vuelta al servidor MCP.
3704 3715
3705El campo matcher coincide contra el nombre del servidor MCP.3716El campo matcher se compara con el nombre del servidor MCP.
3706 3717
3707<h4 id="elicitationresult-input">3718<h4 id="elicitationresult-input">
3708 Entrada de ElicitationResult3719 Entrada de ElicitationResult
3709</h4>3720</h4>
3710 3721
3711Además de los [campos de entrada comunes](#common-input-fields), los hooks ElicitationResult reciben `mcp_server_name`, `action`, y campos opcionales `mode`, `elicitation_id`, y `content`.3722Además de los [campos de entrada comunes](#common-input-fields), los hooks ElicitationResult reciben `mcp_server_name`, `action` y los campos opcionales `mode`, `elicitation_id` y `content`.
3712 3723
3713```json theme={null}3724```json theme={null}
3714{3725{
3728 Salida de ElicitationResult3739 Salida de ElicitationResult
3729</h4>3740</h4>
3730 3741
3731Para anular la respuesta del usuario, devuelva un objeto JSON con `hookSpecificOutput`:3742Para sobrescribir la respuesta del usuario, devuelve un objeto JSON con `hookSpecificOutput`:
3732 3743
3733```json theme={null}3744```json theme={null}
3734{3745{
3742 3753
3743| Campo | Valores | Descripción |3754| Campo | Valores | Descripción |
3744| :- | :- | :- |3755| :- | :- | :- |
3745| `action` | `accept`, `decline`, `cancel` | Anula la acción del usuario |3756| `action` | `accept`, `decline`, `cancel` | Sobrescribe la acción del usuario |
3746| `content` | object | Anula los valores del campo de formulario. Solo significativo cuando `action` es `accept` |3757| `content` | object | Sobrescribe los valores de los campos del formulario. Solo tiene sentido cuando `action` es `accept` |
3747 3758
3748El código de salida 2 bloquea la respuesta, cambiando la acción efectiva a `decline`. Claude Code no muestra su mensaje stderr en ningún lugar.3759El código de salida 2 bloquea la respuesta y cambia la acción efectiva a `decline`. Claude Code no muestra tu mensaje de stderr en ningún lugar.
3749 3760
3750Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook ElicitationResult y descarta `systemMessage` y `continue`.3761Claude Code actúa según `hookSpecificOutput` de la salida JSON de un hook ElicitationResult y descarta `systemMessage` y `continue`.
3751 3762
3752<h2 id="prompt-based-hooks">3763<h2 id="prompt-based-hooks">
3753 Hooks basados en prompts3764 Hooks basados en prompts
