421 421
422* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): ejecutan un comando de shell. Tu script recibe la [entrada JSON](#hook-input-and-output) del evento en stdin y comunica resultados de vuelta a través de códigos de salida y stdout.422* **[Hooks de comando](#command-hook-fields)** (`type: "command"`): ejecutan un comando de shell. Tu script recibe la [entrada JSON](#hook-input-and-output) del evento en stdin y comunica resultados de vuelta a través de códigos de salida y stdout.
423* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): envían la entrada JSON del evento como una solicitud HTTP POST a una URL. El punto final comunica resultados de vuelta a través del cuerpo de respuesta utilizando el mismo [formato de salida JSON](#json-output) que los hooks de comando.423* **[Hooks HTTP](#http-hook-fields)** (`type: "http"`): envían la entrada JSON del evento como una solicitud HTTP POST a una URL. El punto final comunica resultados de vuelta a través del cuerpo de respuesta utilizando el mismo [formato de salida JSON](#json-output) que los hooks de comando.
424* **[Hooks de herramienta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): llaman a una herramienta en un [servidor MCP](/docs/es/mcp) ya conectado. La salida de texto de la herramienta se trata como stdout de hook de comando.424* **[Hooks de herramienta MCP](#mcp-tool-hook-fields)** (`type: "mcp_tool"`): llaman a una herramienta en un [servidor MCP](/docs/es/mcp) configurado. La salida de texto de la herramienta se trata como stdout de hook de comando.
425* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): envían un prompt a un modelo Claude para evaluación de un solo turno. El modelo devuelve su decisión como JSON. Consulta [Hooks basados en prompt](#prompt-based-hooks).425* **[Hooks de prompt](#prompt-and-agent-hook-fields)** (`type: "prompt"`): envían un prompt a un modelo Claude para evaluación de un solo turno. El modelo devuelve su decisión como JSON. Consulta [Hooks basados en prompt](#prompt-based-hooks).
426* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): generan un subagente que puede usar herramientas como Read, Grep y Glob para verificar condiciones antes de devolver una decisión. Los hooks de agente son experimentales y pueden cambiar. Consulta [Hooks basados en agente](#agent-based-hooks).426* **[Hooks de agente](#prompt-and-agent-hook-fields)** (`type: "agent"`): generan un subagente que puede usar herramientas como Read, Grep y Glob para verificar condiciones antes de devolver una decisión. Los hooks de agente son experimentales y pueden cambiar. Consulta [Hooks basados en agente](#agent-based-hooks).
427 427
474| `command` | sí | Comando de shell a ejecutar. Con `args`, el ejecutable a generar directamente. Consulta [Forma exec y forma shell](#exec-form-and-shell-form) |474| `command` | sí | Comando de shell a ejecutar. Con `args`, el ejecutable a generar directamente. Consulta [Forma exec y forma shell](#exec-form-and-shell-form) |
475| `args` | no | Lista de argumentos. Cuando está presente, `command` se resuelve como un ejecutable y se genera directamente con `args` como el vector de argumentos, sin shell involucrado. Consulta [Forma exec y forma shell](#exec-form-and-shell-form) |475| `args` | no | Lista de argumentos. Cuando está presente, `command` se resuelve como un ejecutable y se genera directamente con `args` como el vector de argumentos, sin shell involucrado. Consulta [Forma exec y forma shell](#exec-form-and-shell-form) |
476| `async` | no | Si es `true`, se ejecuta en segundo plano sin bloquear. Consulta [Ejecutar hooks en segundo plano](#run-hooks-in-the-background) |476| `async` | no | Si es `true`, se ejecuta en segundo plano sin bloquear. Consulta [Ejecutar hooks en segundo plano](#run-hooks-in-the-background) |
477| `asyncRewake` | no | Si es `true`, se ejecuta en segundo plano y despierta a Claude en código de salida 2. El stderr del hook, o stdout si stderr está vacío, se muestra a Claude como un recordatorio del sistema para que pueda reaccionar a un fallo de fondo de larga duración |477| `asyncRewake` | no | Si es `true`, se ejecuta en segundo plano y despierta a Claude en código de salida 2. El stderr del hook, o stdout si stderr está vacío, se muestra a Claude como un [recordatorio del sistema](/docs/es/glossary#system-reminder) para que pueda reaccionar a un fallo de fondo de larga duración |
478| `shell` | no | Shell a usar para este hook. Acepta `"bash"` o `"powershell"`. Por defecto es `"bash"`, o `"powershell"` en Windows cuando Git Bash no está instalado. Establecer `"powershell"` ejecuta el comando a través de PowerShell en Windows. No requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL` ya que los hooks generan PowerShell directamente. Se ignora cuando `args` está establecido |478| `shell` | no | Shell a usar para este hook. Acepta `"bash"` o `"powershell"`. Por defecto es `"bash"`, o `"powershell"` en Windows cuando Git Bash no está instalado. Establecer `"powershell"` ejecuta el comando a través de PowerShell en Windows. No requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL` ya que los hooks generan PowerShell directamente. Se ignora cuando `args` está establecido |
479 479
480<a id="exec-form-and-shell-form" />480<a id="exec-form-and-shell-form" />
571 571
572| Campo | Requerido | Descripción |572| Campo | Requerido | Descripción |
573| :- | :- | :- |573| :- | :- | :- |
574| `server` | sí | Nombre de un servidor MCP configurado. Para un [servidor incluido en plugin](/docs/es/mcp#plugin-provided-mcp-servers), este es el nombre con alcance `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:db`, no la clave del servidor desnuda. El servidor debe estar ya conectado; el hook nunca activa un flujo OAuth o de conexión |574| `server` | sí | Nombre de un servidor MCP configurado. Para un [servidor incluido en plugin](/docs/es/mcp#plugin-provided-mcp-servers), este es el nombre con alcance `plugin:<plugin-name>:<server-name>`, como `plugin:my-plugin:db`, no la clave del servidor desnuda |
575| `tool` | sí | Nombre de la herramienta a llamar en ese servidor |575| `tool` | sí | Nombre de la herramienta a llamar en ese servidor |
576| `input` | no | Argumentos pasados a la herramienta. Los valores de cadena soportan sustitución de `${path}` de la [entrada JSON](#hook-input-and-output) del hook, como `"${tool_input.file_path}"` |576| `input` | no | Argumentos pasados a la herramienta. Los valores de cadena soportan sustitución de `${path}` de la [entrada JSON](#hook-input-and-output) del hook, como `"${tool_input.file_path}"` |
577 577
578Claude Code lee el contenido de texto de la herramienta de la misma manera que lee stdout de hook de comando, siguiendo la [regla de análisis bajo código de salida 0](#exit-code-0). Si el servidor nombrado no está conectado, o la herramienta devuelve `isError: true`, el hook produce un error sin bloqueo y la ejecución continúa.
579
580Este ejemplo llama a la herramienta `security_scan` en el servidor MCP `my_server` después de cada `Write` o `Edit`, pasando la ruta del archivo editado:578Este ejemplo llama a la herramienta `security_scan` en el servidor MCP `my_server` después de cada `Write` o `Edit`, pasando la ruta del archivo editado:
581 579
582```json theme={null}580```json theme={null}
599}597}
600```598```
601 599
602Un hook `mcp_tool` puede ejecutarse solo después de que Claude Code haya puesto los servidores MCP de la sesión disponibles para los hooks. `SessionStart` y `Setup` pueden activarse antes de ese punto:600<h5 id="how-the-tool’s-result-is-read">
601 Cómo se lee el resultado de la herramienta
602</h5>
603 603
604* **Al lanzar**: `SessionStart` se activa antes de que los servidores estén disponibles, incluso cuando lanzas con `--continue` o `--resume`. Claude Code omite los hooks `mcp_tool` del evento sin llamar a sus herramientas, y el [registro de depuración](#debug-hooks) registra `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`.604Claude Code lee el contenido de texto de la herramienta de la misma manera que lee stdout de hook de comando, siguiendo la [regla de análisis bajo código de salida 0](#exit-code-0). Si la herramienta devuelve `isError: true`, el hook produce un error sin bloqueo y la ejecución continúa.
605* **Más tarde en una sesión en ejecución**: después de `/clear` o una compactación, `SessionStart` se activa de nuevo con los servidores ya disponibles, y sus hooks `mcp_tool` se ejecutan.
606* **En `Setup`**: `Setup` siempre se activa antes de que los servidores estén disponibles, por lo que Claude Code omite sus hooks `mcp_tool` cada vez y registra el mismo mensaje nombrando `Setup`.
607 605
608Por ejemplo, esta configuración llama a la herramienta `load_context` en el servidor MCP `my_server` desde un hook `SessionStart` sin matcher, por lo que se aplica a cada fuente de `SessionStart`:606<h5 id="when-the-server-is-still-connecting">
607 Cuando el servidor aún se está conectando
608</h5>
609 609
610```json theme={null}610En eventos donde un hook puede bloquear o cambiar el resultado, como `PreToolUse` o `Stop`, Claude Code espera a que se conecte un servidor antes de llamar a la herramienta, durante como máximo [`MCP_TIMEOUT`](/docs/es/env-vars) y dentro del propio [`timeout`](#common-fields) del hook. En eventos observacionales, como `Notification` o `SessionEnd`, no espera.
611{611
612 "hooks": {612Un servidor que muestra el estado [`cached`](/docs/es/mcp#server-status-detail) se conecta cuando el hook llama a su herramienta. Si el servidor no está conectado en ese punto, el hook produce un error sin bloqueo y la ejecución continúa. El hook nunca inicia un flujo OAuth, por lo que [autentica el servidor desde `/mcp`](/docs/es/mcp#authenticate-with-remote-mcp-servers) primero.
613 "SessionStart": [613
614 {614<h5 id="events-that-fire-before-mcp-servers-are-available">
615 "hooks": [615 Eventos que se activan antes de que los servidores MCP estén disponibles
616 {616</h5>
617 "type": "mcp_tool",
618 "server": "my_server",
619 "tool": "load_context"
620 }
621 ]
622 }
623 ]
624 }
625}
626```
627 617
628Cuando ejecutas `claude`, Claude Code omite este hook, nunca llama a `load_context` y escribe el mensaje `no MCP client context` en el registro de depuración. Ejecuta `/clear` en esa misma sesión y el hook se ejecuta y llama a `load_context`. Un hook `type: "command"` en `SessionStart` se ejecuta al lanzar, por lo que usa uno para cualquier cosa que la sesión necesite desde su primer turno.618`SessionStart` al lanzar, incluso con `--continue` o `--resume`, y cada evento `Setup` se activan antes de que los servidores MCP de la sesión estén disponibles para los hooks. Claude Code omite sus hooks `mcp_tool` sin llamar a la herramienta, y el [registro de depuración](#debug-hooks) registra `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`, o el mismo mensaje nombrando `Setup`. Cuando `SessionStart` se activa de nuevo más tarde en la sesión, después de `/clear` o una compactación, sus hooks `mcp_tool` se ejecutan. Para cualquier cosa que la sesión necesite al lanzar, usa un hook `type: "command"` en `SessionStart` en su lugar.
629 619
630<h4 id="prompt-and-agent-hook-fields">620<h4 id="prompt-and-agent-hook-fields">
631 Campos de hook de prompt y agente621 Campos de hook de prompt y agente
636| Campo | Requerido | Descripción |626| Campo | Requerido | Descripción |
637| :- | :- | :- |627| :- | :- | :- |
638| `prompt` | sí | Texto de prompt a enviar al modelo. Usa `$ARGUMENTS` como marcador de posición para la entrada JSON del hook. Escapa con una barra invertida para incluir texto literal: `\$1.00` se renderiza como `$1.00` |628| `prompt` | sí | Texto de prompt a enviar al modelo. Usa `$ARGUMENTS` como marcador de posición para la entrada JSON del hook. Escapa con una barra invertida para incluir texto literal: `\$1.00` se renderiza como `$1.00` |
639| `model` | no | Modelo a usar para evaluación. Por defecto es un modelo rápido |629| `model` | no | Modelo a usar para evaluación. Por defecto es el modelo que Claude Code usa para [funcionalidad de fondo](/docs/es/costs#background-token-usage) |
640 630
641<h3 id="reference-scripts-by-path">631<h3 id="reference-scripts-by-path">
642 Referencia de scripts por ruta632 Referencia de scripts por ruta
791| `prompt_id` | UUID que identifica el prompt del usuario que se está procesando actualmente. Coincide con el [atributo `prompt.id` en eventos de OpenTelemetry](/docs/es/monitoring-usage#event-correlation-attributes), para que pueda correlacionar la salida del hook con la telemetría de un único prompt. Ausente hasta la primera entrada del usuario. Requiere Claude Code v2.1.196 o posterior |781| `prompt_id` | UUID que identifica el prompt del usuario que se está procesando actualmente. Coincide con el [atributo `prompt.id` en eventos de OpenTelemetry](/docs/es/monitoring-usage#event-correlation-attributes), para que pueda correlacionar la salida del hook con la telemetría de un único prompt. Ausente hasta la primera entrada del usuario. Requiere Claude Code v2.1.196 o posterior |
792| `transcript_path` | Ruta al JSON de conversación. El archivo de transcripción se escribe de forma asincrónica y puede rezagarse con respecto a la conversación en memoria, por lo que es posible que aún no incluya los mensajes más recientes del turno actual cuando se activa un hook. Los hooks que necesitan el texto del asistente final del turno actual deben usar `last_assistant_message` en [Stop](#stop) y [SubagentStop](#subagentstop) en lugar de leer la transcripción |782| `transcript_path` | Ruta al JSON de conversación. El archivo de transcripción se escribe de forma asincrónica y puede rezagarse con respecto a la conversación en memoria, por lo que es posible que aún no incluya los mensajes más recientes del turno actual cuando se activa un hook. Los hooks que necesitan el texto del asistente final del turno actual deben usar `last_assistant_message` en [Stop](#stop) y [SubagentStop](#subagentstop) en lugar de leer la transcripción |
793| `cwd` | Directorio de trabajo actual cuando se invoca el hook |783| `cwd` | Directorio de trabajo actual cuando se invoca el hook |
794| `scratchpad_dir` | Ruta al directorio de scratchpad de la sesión, donde Claude mantiene archivos de trabajo temporales. Ausente cuando la sesión no tiene scratchpad o el directorio temporal no está disponible. Requiere Claude Code v2.1.257 o posterior |784| `scratchpad_dir` | Ruta al [directorio de scratchpad de la sesión](/docs/es/claude-directory#session-scratchpad-directory), donde Claude mantiene archivos de trabajo temporales. Ausente cuando la sesión no tiene scratchpad o el directorio temporal no está disponible. Requiere Claude Code v2.1.257 o posterior |
795| `permission_mode` | [Modo de permiso](/docs/es/permissions#permission-modes) actual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` o `"bypassPermissions"`. El modo etiquetado como **Manual** llega como `"default"`, nunca como `"manual"`, por lo que los scripts que coinciden con `"default"` siguen funcionando. No todos los eventos reciben este campo. Consulte el ejemplo JSON en cada sección [hook event](#hook-events) |785| `permission_mode` | [Modo de permiso](/docs/es/permissions#permission-modes) actual: `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, `"dontAsk"` o `"bypassPermissions"`. El modo etiquetado como **Manual** llega como `"default"`, nunca como `"manual"`, por lo que los scripts que coinciden con `"default"` siguen funcionando. No todos los eventos reciben este campo. Consulte el ejemplo JSON en cada sección [hook event](#hook-events) |
796| `effort` | Objeto con un campo `level` que contiene el [nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) en vigor cuando se ejecuta el hook: `"low"`, `"medium"`, `"high"`, `"xhigh"` o `"max"`. Si establece un nivel que el modelo activo no admite, `level` reporta el nivel que Claude Code ejecutó en su lugar; [Adjust effort level](/docs/es/model-config#adjust-effort-level) dice cómo lo elige. Ultracode no es un nivel distinto y se reporta como `"xhigh"`. El objeto coincide con el campo `effort` de la [línea de estado](/docs/es/statusline#available-data). Presente para eventos que se activan dentro de un contexto de uso de herramienta, como `PreToolUse`, `PostToolUse`, `Stop` y `SubagentStop`, cuando el modelo actual admite el parámetro de esfuerzo. El nivel también está disponible para comandos de hook y la herramienta Bash como la variable de entorno `$CLAUDE_EFFORT`. |786| `effort` | Objeto con un campo `level` que contiene el [nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) en vigor cuando se ejecuta el hook: `"low"`, `"medium"`, `"high"`, `"xhigh"` o `"max"`. Si establece un nivel que el modelo activo no admite, `level` reporta el nivel que Claude Code ejecutó en su lugar; [Adjust effort level](/docs/es/model-config#adjust-effort-level) dice cómo lo elige. El objeto coincide con el campo `effort` de la [línea de estado](/docs/es/statusline#available-data). Presente para eventos que se activan dentro de un contexto de uso de herramienta, como `PreToolUse`, `PostToolUse`, `Stop` y `SubagentStop`, cuando el modelo actual admite el parámetro de esfuerzo. El nivel también está disponible para comandos de hook y la herramienta Bash como la variable de entorno `$CLAUDE_EFFORT`. |
797| `hook_event_name` | Nombre del evento que se activó |787| `hook_event_name` | Nombre del evento que se activó |
798 788
799Cuando se ejecuta con `--agent` o dentro de un subagente, se incluyen dos campos adicionales:789Cuando se ejecuta con `--agent` o dentro de un subagente, se incluyen dos campos adicionales:
1057 Agregar contexto para Claude1047 Agregar contexto para Claude
1058</h4>1048</h4>
1059 1049
1060El campo `additionalContext` pasa una cadena de su hook a la ventana de contexto de Claude. Claude Code envuelve la cadena en un recordatorio del sistema e la inserta en la conversación en el punto donde se activó el hook. Claude lee el recordatorio en la siguiente solicitud del modelo, pero no aparece como un mensaje de chat en la interfaz.1050El campo `additionalContext` pasa una cadena de su hook a la ventana de contexto de Claude. Claude Code envuelve la cadena en un [recordatorio del sistema](/docs/es/glossary#system-reminder) e la inserta en la conversación en el punto donde se activó el hook. Claude lee el recordatorio en la siguiente solicitud del modelo, pero no aparece como un mensaje de chat en la interfaz.
1061 1051
1062Devuelva `additionalContext` dentro de `hookSpecificOutput` junto al nombre del evento:1052Devuelva `additionalContext` dentro de `hookSpecificOutput` junto al nombre del evento:
1063 1053
1179 Eventos de hooks1169 Eventos de hooks
1180</h2>1170</h2>
1181 1171
1182Cada 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.1172Cada evento corresponde a un punto en el ciclo de vida de Claude Code donde los hooks pueden ejecutarse. Las secciones a continuación 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.
1183 1173
1184<h3 id="sessionstart">1174<h3 id="sessionstart">
1185 SessionStart1175 SessionStart
1186</h3>1176</h3>
1187 1177
1188Se 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.1178Se 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 tu base de código, o configurar variables de entorno. Para contexto estático que no requiere un script, usa [CLAUDE.md](/docs/es/memory) en su lugar.
1189 1179
1190SessionStart 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`.1180SessionStart 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 hook de herramienta MCP](#mcp-tool-hook-fields) para saber cuándo se ejecutan los hooks `mcp_tool`.
1191 1181
1192El valor del matcher corresponde a cómo se inició la sesión:1182El valor del matcher corresponde a cómo se inició la sesión:
1193 1183
1199| `compact` | Compactación automática o manual |1189| `compact` | Compactación automática o manual |
1200| `fork` | Una nueva sesión bifurcada desde una existente: `--fork-session` con `--resume` o `--continue`, la copia de fondo `/fork`, o `/branch` |1190| `fork` | Una nueva sesión bifurcada desde una existente: `--fork-session` con `--resume` o `--continue`, la copia de fondo `/fork`, o `/branch` |
1201 1191
1202Antes de v2.1.214, las sesiones bifurcadas reportaban la fuente `"resume"`.1192Antes de v2.1.214, las sesiones bifurcadas reportaban origen `"resume"`.
1203 1193
1204Cuando 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.1194Cuando inicias una sesión interactiva, reanudas una conversación al iniciar 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 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.
1205 1195
1206Cuando cambia de conversación 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.1196Cuando cambias de conversación con `/resume` dentro de una sesión, el cambio espera a que se completen los hooks. Si ejecutas `/clear` o cambias 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.
1207 1197
1208La 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.1198La misma espera se aplica al iniciar, incluyendo una sesión reanudada: un prompt que envíes mientras los hooks SessionStart aún se están ejecutando no llega a Claude hasta que se completen.
1209 1199
1210Durante cualquiera de estas esperas, presione `Esc` para recuperar el prompt en la entrada sin enviarlo. Los hooks continúan ejecutándose.1200Durante cualquiera de estas esperas, presiona `Esc` para recuperar el prompt en la entrada sin enviarlo. Los hooks siguen ejecutándose.
1211 1201
1212<h4 id="sessionstart-input">1202<h4 id="sessionstart-input">
1213 Entrada de SessionStart1203 Entrada de SessionStart
1218| Campo | Descripción |1208| Campo | Descripción |
1219| :- | :- |1209| :- | :- |
1220| `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 |1210| `source` | Cómo se inició la sesión: `"startup"` para nuevas sesiones, `"resume"` para sesiones reanudadas, `"clear"` después de `/clear`, `"compact"` después de compactación, o `"fork"` para una nueva sesión bifurcada desde una existente |
1221| `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 |1211| `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 verifica el campo antes de leerlo |
1222| `agent_type` | El nombre del agente, presente cuando inicia Claude Code con `claude --agent <name>` |1212| `agent_type` | El nombre del agente, presente cuando inicias Claude Code con `claude --agent <name>` |
1223| `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 |1213| `session_title` | El título de la 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 |
1224 1214
1225Cuando `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.1215Cuando `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 a continuación. Tu 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.
1226 1216
1227| Campo | Descripción |1217| Campo | Descripción |
1228| :- | :- |1218| :- | :- |
1229| `seconds_since_last_response` | Segundos de reloj de pared desde la última respuesta en la transcripción reanudada |1219| `seconds_since_last_response` | Segundos de reloj de pared desde la última respuesta en la transcripción reanudada |
1230| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada reenvía como su prompt |1220| `context_tokens` | Tokens que la primera solicitud de la sesión reanudada reenvía como su prompt |
1231| `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é |1221| `prompt_cache_likely_expired` | `true` cuando la última respuesta es más antigua que la [duración del caché de prompt](/docs/es/prompt-caching#cache-lifetime) de la sesión o una compactación posterior reemplazó la conversación en caché |
1232| `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 |1222| `estimated_cache_write_usd` | Costo estimado en dólares estadounidenses de escribir `context_tokens` en el caché de prompt en el modelo de la sesión, excluyendo la respuesta |
1233 1223
1234Este ejemplo muestra la entrada para una sesión reanudada 90 minutos después de su última respuesta:1224Este ejemplo muestra la entrada para una sesión reanudada 90 minutos después de su última respuesta:
1252 Control de decisión de SessionStart1242 Control de decisión de SessionStart
1253</h4>1243</h4>
1254 1244
1255Claude 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:1245Claude Code añade 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, puedes devolver estos campos específicos del evento:
1256 1246
1257| Campo | Descripción |1247| Campo | Descripción |
1258| :- | :- |1248| :- | :- |
1259| `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 |1249| `additionalContext` | Cadena añadida al contexto de Claude al inicio de la conversación, antes del primer prompt. Consulta [Añadir contexto para Claude](#add-context-for-claude) para saber cómo se entrega el texto y qué poner en él |
1260| `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, sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, esto crea el turno |1250| `initialUserMessage` | Cadena utilizada como el primer mensaje del usuario de la sesión. Se aplica en [modo no interactivo](/docs/es/headless) con la bandera `-p`, donde se convierte en el primer turno incluso si no se proporciona ningún prompt. Si se proporciona un prompt, lo sigue como el siguiente turno. A diferencia de `additionalContext`, que se adjunta a un turno existente, esto crea el turno |
1261| `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"` |1251| `sessionTitle` | Establece el título de la sesión, con el mismo efecto que `/rename`. Úsalo 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"` |
1262| `watchPaths` | Matriz de rutas absolutas para observar eventos [FileChanged](#filechanged) durante esta sesión |1252| `watchPaths` | Array de rutas absolutas para observar eventos [FileChanged](#filechanged) durante esta sesión |
1263| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a escanear los directorios de [skill](/docs/es/skills) y comando después de que se completen los hooks SessionStart, por lo que las skills que instaló el hook están disponibles en la misma sesión, comenzando con el primer prompt |1253| `reloadSkills` | Booleano. Cuando es `true`, Claude Code vuelve a escanear los directorios de [skill](/docs/es/skills) y comando después de que se completen los hooks SessionStart, por lo que las skills que instaló el hook están disponibles en la misma sesión, comenzando con el primer prompt |
1264 1254
1265```json theme={null}1255```json theme={null}
1272}1262}
1273```1263```
1274 1264
1275Dado 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`.1265Dado que stdout plano ya llega a Claude para este evento, un hook que solo carga contexto puede imprimir a stdout directamente sin construir JSON. Usa la forma JSON cuando necesites combinar contexto con otros campos como `sessionTitle`.
1276 1266
1277Use `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:1267Usa `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:
1278 1268
1279```bash theme={null}1269```bash theme={null}
1280#!/bin/bash1270#!/bin/bash
1285echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1275echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'
1286```1276```
1287 1277
1288La 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.1278La URL del repositorio es un marcador de posición; reemplázala con tu 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.
1289 1279
1290<h4 id="persist-environment-variables">1280<h4 id="persist-environment-variables">
1291 Persistir variables de entorno1281 Persistir variables de entorno
1292</h4>1282</h4>
1293 1283
1294Los 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.1284Los 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 comandos Bash posteriores.
1295 1285
1296Para establecer variables de entorno individuales, escriba declaraciones `export` en `CLAUDE_ENV_FILE`. Use append (`>>`) para preservar variables establecidas por otros hooks:1286Para establecer variables de entorno individuales, escribe declaraciones `export` en `CLAUDE_ENV_FILE`. Usa append (`>>`) para preservar variables establecidas por otros hooks:
1297 1287
1298```bash theme={null}1288```bash theme={null}
1299#!/bin/bash1289#!/bin/bash
1307exit 01297exit 0
1308```1298```
1309 1299
1310Para capturar todos los cambios de entorno de comandos de configuración, compare las variables exportadas antes y después:1300Para capturar todos los cambios de entorno de comandos de configuración, compara las variables exportadas antes y después:
1311 1301
1312```bash theme={null}1302```bash theme={null}
1313#!/bin/bash1303#!/bin/bash
1334 Setup1324 Setup
1335</h3>1325</h3>
1336 1326
1337Se 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 al iniciar normalmente. Ú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.1327Se dispara solo cuando inicias 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. Úsalo para instalación de dependencias única o limpieza programada que actives explícitamente desde CI o scripts, separado del inicio normal de sesión. Para inicialización por sesión, usa [SessionStart](#sessionstart) en su lugar.
1338 1328
1339El valor del matcher corresponde a la bandera CLI que disparó el hook:1329El valor del matcher corresponde a la bandera CLI que activó el hook:
1340 1330
1341| Matcher | Cuándo se dispara |1331| Matcher | Cuándo se dispara |
1342| :- | :- |1332| :- | :- |
1343| `init` | `claude --init-only` o `claude -p --init` |1333| `init` | `claude --init-only` o `claude -p --init` |
1344| `maintenance` | `claude -p --maintenance` |1334| `maintenance` | `claude -p --maintenance` |
1345 1335
1346Cuando ejecuta `claude --init-only`, Claude Code ejecuta hooks Setup y hooks `SessionStart` con el matcher `startup`, luego sale sin iniciar una conversación.1336Cuando ejecutas `claude --init-only`, Claude Code ejecuta hooks Setup y hooks `SessionStart` con el matcher `startup`, luego sale sin iniciar una conversación.
1347 1337
1348Cuando 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).1338Cuando inicias o continúas una conversación con `-p`, también necesitas proporcionar un prompt, como argumento o canalizando en stdin. Puedes omitir el prompt cuando un hook `SessionStart` proporciona [`initialUserMessage`](#sessionstart-decision-control) o cuando reanudas una sesión con una [llamada de herramienta diferida](#defer-a-tool-call-for-later).
1349 1339
1350En 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.1340En caso de éxito, `--init-only` no imprime nada en la terminal. Para confirmar que los hooks se ejecutaron, comienza con `claude --debug-file <path> --init-only`, reemplazando `<path>` con una ubicación de archivo de registro, y verifica el registro para las entradas de hook Setup y SessionStart.
1351 1341
1352Debido 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.1342Debido a que Setup no se dispara en cada inicio, un plugin que necesita una dependencia instalada no puede confiar solo en Setup. El patrón práctico es verificar la dependencia en el primer uso e instalar si falta, por ejemplo un hook o skill que prueba `${CLAUDE_PLUGIN_DATA}/node_modules` y ejecuta `npm install` si está ausente. Consulta el [directorio de datos persistentes](/docs/es/plugins/components#path-variables-and-persistent-data) para saber dónde almacenar 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 Node.js elegibles](/docs/es/plugins/loading#node-js-package-dependencies) cuando almacena en caché el plugin.
1353 1343
1354<h4 id="setup-input">1344<h4 id="setup-input">
1355 Entrada de Setup1345 Entrada de Setup
1371 Control de decisión de Setup1361 Control de decisión de Setup
1372</h4>1362</h4>
1373 1363
1374Los 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`, la salida stdout, stderr y 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`.1364Los hooks Setup no pueden bloquear; la ejecución continúa en cualquier código de salida. En cada código de salida, Claude Code descarta los [campos de salida JSON](#json-output) de un hook Setup, como `systemMessage`, `continue`, y `hookSpecificOutput.additionalContext`. Con `-p`, la salida estándar, error estándar y 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`.
1375 1365
1376Los 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).1366Los hooks Setup tienen acceso a `CLAUDE_ENV_FILE`. Las variables escritas en ese archivo persisten en comandos Bash posteriores para la sesión, tal como en [hooks SessionStart](#persist-environment-variables). Solo se ejecutan hooks `type: "command"` en `Setup`. Un hook `type: "mcp_tool"` en `Setup` siempre se omite, como se describe en [Campos de hook de herramienta MCP](#mcp-tool-hook-fields).
1377 1367
1378<h3 id="instructionsloaded">1368<h3 id="instructionsloaded">
1379 InstructionsLoaded1369 InstructionsLoaded
1381 1371
1382Se 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.1372Se 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.
1383 1373
1384Este evento no se dispara cuando Claude [lee `AGENTS.md` directamente](/docs/es/memory#agents-md) a través de la configuración **Project instructions**. 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 symlink a él, como una carga normal de `CLAUDE.md`.1374Este 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 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`.
1385 1375
1386El 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.1376El matcher se ejecuta contra `load_reason`. Por ejemplo, usa `"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.
1387 1377
1388<h4 id="instructionsloaded-input">1378<h4 id="instructionsloaded-input">
1389 Entrada de InstructionsLoaded1379 Entrada de InstructionsLoaded
1397| `memory_type` | Alcance del archivo: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |1387| `memory_type` | Alcance del archivo: `"User"`, `"Project"`, `"Local"`, o `"Managed"` |
1398| `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 |1388| `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 |
1399| `globs` | Patrones de glob de ruta del frontmatter `paths:` del archivo, si los hay. Presente solo para cargas `path_glob_match` |1389| `globs` | Patrones de glob de ruta del frontmatter `paths:` del archivo, si los hay. Presente solo para cargas `path_glob_match` |
1400| `trigger_file_path` | Ruta al archivo cuyo acceso disparó esta carga, para cargas perezosas |1390| `trigger_file_path` | Ruta al archivo cuyo acceso activó esta carga, para cargas perezosas |
1401| `parent_file_path` | Ruta al archivo de instrucciones padre que incluyó este, para cargas `include` |1391| `parent_file_path` | Ruta al archivo de instrucciones padre que incluyó este, para cargas `include` |
1402 1392
1403```json theme={null}1393```json theme={null}
1416 Control de decisión de InstructionsLoaded1406 Control de decisión de InstructionsLoaded
1417</h4>1407</h4>
1418 1408
1419Los hooks InstructionsLoaded no tienen control de decisión. No pueden bloquear o modificar la carga de instrucciones. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage` y `continue`. Use este evento para auditoría de registros, seguimiento de cumplimiento u observabilidad.1409Los hooks InstructionsLoaded no tienen control de decisión. No pueden bloquear o modificar la carga de instrucciones. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage` y `continue`. Usa este evento para auditoría de registros, seguimiento de cumplimiento u observabilidad.
1420 1410
1421<h3 id="userpromptsubmit">1411<h3 id="userpromptsubmit">
1422 UserPromptSubmit1412 UserPromptSubmit
1423</h3>1413</h3>
1424 1414
1425Se 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.1415Se ejecuta cuando el usuario envía un prompt, antes de que Claude lo procese. Esto te permite añadir contexto adicional basado en el prompt/conversación, validar prompts o bloquear ciertos tipos de prompts.
1426 1416
1427Los 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.1417Los 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 paraliza la sesión. Si tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.
1428 1418
1429Aparte de un hook de comando que ejecuta con [`async: true`](#run-hooks-in-the-background), un hook de comando, HTTP o herramienta MCP `UserPromptSubmit` 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ó.1419Aparte de un hook de comando que ejecutas 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, incluyendo 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ó.
1430 1420
1431Un hook de devolución de llamada [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 una devolución de llamada allí puede actuar como una puerta de política que no debe fallar abierta. La sesión continúa. Antes de v2.1.208, un tiempo de espera de devolución de llamada en ese evento terminaba el turno con un error de ejecución.1421Un [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.
1432 1422
1433<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">
1434 Entrada de UserPromptSubmit1424 Entrada de UserPromptSubmit
1435</h4>1425</h4>
1436 1426
1437Además de los [campos de entrada comunes](#common-input-fields), los hooks UserPromptSubmit reciben el campo `prompt` que contiene el texto que el usuario envió. El contenido pegado que se colapsó en un marcador de posición `[Pasted text #N]` llega expandido en su lugar. En sesiones donde Claude Code [marca el 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` que contiene el texto que el usuario envió. El contenido pegado que se redujo a un marcador de posición `[Pasted text #N]` llega expandido en su lugar. En sesiones donde Claude Code [marca el 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 ten en cuenta esas líneas si tu hook analiza el prompt.
1438 1428
1439```json theme={null}1429```json theme={null}
1440{1430{
1451 Control de decisión de UserPromptSubmit1441 Control de decisión de UserPromptSubmit
1452</h4>1442</h4>
1453 1443
1454Los 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.1444Los hooks `UserPromptSubmit` pueden controlar si se procesa un prompt de usuario y añadir contexto. Todos los [campos de salida JSON](#json-output) están disponibles.
1455 1445
1456Hay dos formas de agregar contexto a la conversación en código de salida 0:1446Hay dos formas de añadir contexto a la conversación en código de salida 0:
1457 1447
1458* **Stdout de texto plano**: Claude Code agrega stdout que [trata como texto plano](#exit-code-0) al contexto de Claude1448* **Stdout de texto plano**: Claude Code añade stdout que [trata como texto plano](#exit-code-0) al contexto de Claude
1459* **JSON con `additionalContext`**: use el formato JSON a continuación para más control. El campo `additionalContext` se agrega como contexto1449* **JSON con `additionalContext`**: usa el formato JSON a continuación para más control. El campo `additionalContext` se añade como contexto
1460 1450
1461Ningú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).1451Ningú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, verifica el [registro de depuración](#debug-hooks).
1462 1452
1463Para bloquear un prompt, devuelva un objeto JSON con `decision` establecido en `"block"`:1453Para bloquear un prompt, devuelve un objeto JSON con `decision` establecido en `"block"`:
1464 1454
1465| Campo | Descripción |1455| Campo | Descripción |
1466| :- | :- |1456| :- | :- |
1467| `decision` | `"block"` evita que se procese el prompt y lo borra del contexto. Omita para permitir que el prompt continúe |1457| `decision` | `"block"` evita que se procese el prompt y lo borra del contexto. Omite para permitir que el prompt continúe |
1468| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se agrega al contexto |1458| `reason` | Se muestra al usuario cuando `decision` es `"block"`. No se añade al contexto |
1469| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1459| `additionalContext` | Cadena añadida al contexto de Claude junto con el prompt enviado. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
1470| `sessionTitle` | Establece el título de la sesión. Úselo para nombrar sesiones automáticamente basándose en el contenido del prompt |1460| `sessionTitle` | Establece el título de la sesión. Úsalo para nombrar sesiones automáticamente basándote en el contenido del prompt |
1471| `suppressOriginalPrompt` | Si es `true` cuando `decision` es `"block"`, omite el texto del prompt original del mensaje de bloqueo mostrado al usuario |1461| `suppressOriginalPrompt` | Si es `true` cuando `decision` es `"block"`, omite el texto del prompt original del mensaje de bloqueo mostrado al usuario |
1472 1462
1473Un 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.1463Un 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 añade al contexto.
1474 1464
1475```json theme={null}1465```json theme={null}
1476{1466{
1488 UserPromptExpansion1478 UserPromptExpansion
1489</h3>1479</h3>
1490 1480
1491Se ejecuta cuando un comando escrito por el usuario se expande en un prompt antes de llegar a Claude. Úselo para bloquear comandos específicos de invocación directa, inyectar contexto para una skill particular o registrar qué comandos invocan los usuarios. Por ejemplo, un hook que coincide con `deploy` puede bloquear `/deploy` a menos que esté presente un archivo de aprobación, o un hook que coincide con una skill de revisión puede agregar la lista de verificación de revisión del equipo como `additionalContext`.1481Se ejecuta cuando un comando escrito por el usuario se expande en un prompt antes de llegar a Claude. Úsalo para bloquear comandos específicos de invocación directa, inyectar contexto para una skill particular o registrar qué comandos invocan los usuarios. Por ejemplo, un hook que coincide con `deploy` puede bloquear `/deploy` a menos que esté presente un archivo de aprobación, o un hook que coincide con una skill de revisión puede añadir la lista de verificación de revisión del equipo como `additionalContext`.
1492 1482
1493Este 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.1483Este evento cubre la ruta que `PreToolUse` no cubre: un hook `PreToolUse` que coincide con la herramienta `Skill` se dispara solo cuando Claude llama a la herramienta, pero escribir `/skillname` directamente omite `PreToolUse`. `UserPromptExpansion` se dispara en esa ruta directa.
1494 1484
1495Coincide en `command_name`. Deje el matcher vacío para dispararse en cada comando de tipo prompt.1485Coincide en `command_name`. Deja el matcher vacío para dispararse en cada comando de tipo prompt.
1496 1486
1497<h4 id="userpromptexpansion-input">1487<h4 id="userpromptexpansion-input">
1498 Entrada de UserPromptExpansion1488 Entrada de UserPromptExpansion
1499</h4>1489</h4>
1500 1490
1501Ademá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.1491Ademá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.
1502 1492
1503```json theme={null}1493```json theme={null}
1504{1494{
1519 Control de decisión de UserPromptExpansion1509 Control de decisión de UserPromptExpansion
1520</h4>1510</h4>
1521 1511
1522Los hooks `UserPromptExpansion` pueden bloquear la expansión o agregar contexto. Todos los [campos de salida JSON](#json-output) están disponibles.1512Los hooks `UserPromptExpansion` pueden bloquear la expansión o añadir contexto. Todos los [campos de salida JSON](#json-output) están disponibles.
1523 1513
1524| Campo | Descripción |1514| Campo | Descripción |
1525| :- | :- |1515| :- | :- |
1526| `decision` | `"block"` evita que el comando se expanda. Omita para permitir que continúe |1516| `decision` | `"block"` evita que el comando se expanda. Omite para permitir que continúe |
1527| `reason` | Se muestra al usuario cuando `decision` es `"block"` |1517| `reason` | Se muestra al usuario cuando `decision` es `"block"` |
1528| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt expandido. Consulte [Agregar contexto para Claude](#add-context-for-claude) |1518| `additionalContext` | Cadena añadida al contexto de Claude junto con el prompt expandido. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
1529 1519
1530Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario.1520Un hook que bloquea saliendo con 2 se enruta de la misma manera que `reason`: el mensaje de bloqueo muestra el texto stderr al usuario.
1531 1521
1546 1536
1547Se 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.1537Se 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.
1548 1538
1549Use MessageDisplay para:1539Usa MessageDisplay para:
1550 1540
1551* eliminar markdown para una visualización mínima1541* eliminar markdown para una visualización mínima
1552* transformar el texto que una aplicación Agent SDK muestra a sus usuarios1542* transformar el texto que una aplicación del Agent SDK muestra a sus usuarios
1553* redactar claves API o nombres de host internos de las respuestas de Claude1543* redactar claves API o nombres de host internos de las respuestas de Claude
1554 1544
1555Claude 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.1545Claude Code retiene cada lote hasta que tu hook devuelve, así que mantén 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 tu hook necesita más tiempo, establece el campo `timeout` en la entrada del hook.
1556 1546
1557MessageDisplay 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.1547MessageDisplay 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 escribes se renderiza sin cambios.
1558 1548
1559MessageDisplay 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.1549MessageDisplay no admite matchers y se dispara para cada mensaje del asistente que transmite texto; los mensajes sin texto, como respuestas de solo llamada de herramienta, no lo activan.
1560 1550
1561En ejecuciones no interactivas, incluidas consultas de 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 del mensaje completo: `index` es `0`, `final` es `true`, y `delta` contiene el mensaje completo. Un hook que recopila el texto `delta` para cada mensaje recibe el mismo texto total en ambos modos.1551En ejecuciones no interactivas, incluyendo 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.
1562 1552
1563<h4 id="messagedisplay-input">1553<h4 id="messagedisplay-input">
1564 Entrada de MessageDisplay1554 Entrada de MessageDisplay
1565</h4>1555</h4>
1566 1556
1567Ademá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.1557Ademá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 transmita el texto, así que usa `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.
1568 1558
1569| Campo | Descripción |1559| Campo | Descripción |
1570| :- | :- |1560| :- | :- |
1571| `turn_id` | UUID del turno actual |1561| `turn_id` | UUID del turno actual |
1572| `message_id` | UUID del mensaje del asistente que se muestra. Estable en cada lote del mismo mensaje. Este no es el ID de API `msg_…`, por lo que no se puede correlacionar con IDs de mensaje de transcripción |1562| `message_id` | UUID del mensaje del asistente que se está mostrando. Estable en cada lote del mismo mensaje. Este no es el `msg_…` id de la API, por lo que no se puede correlacionar con ids de mensajes de transcripción |
1573| `index` | Índice basado en cero de este lote dentro del mensaje |1563| `index` | Índice basado en cero de este lote dentro del mensaje |
1574| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |1564| `final` | `true` en el último lote del mensaje. Cada mensaje tiene exactamente un lote final |
1575| `delta` | Las líneas recién completadas desde el lote anterior, incluidas las saltos de línea finales. Siempre líneas completas, excepto el lote final que puede terminar a mitad de línea. En ejecuciones interactivas, el delta del lote final está vacío cuando el mensaje termina en un salto de línea, así que trate `final`, no un delta no vacío, como la señal de fin de mensaje. En ejecuciones de Agent SDK y `claude -p`, la llamada única lleva el mensaje completo |1565| `delta` | Las líneas recién completadas desde el lote anterior, incluyendo 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 trata `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 1566
1577```json theme={null}1567```json theme={null}
1578{1568{
1596 1586
1597| Campo | Descripción |1587| Campo | Descripción |
1598| :- | :- |1588| :- | :- |
1599| `displayContent` | Texto mostrado en lugar del delta. Omítalo para mostrar el original |1589| `displayContent` | Texto mostrado en lugar del delta. Omítelo para mostrar el original |
1600 1590
1601Los 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`.1591Los hooks MessageDisplay no tienen control de decisión. No pueden bloquear el mensaje o cambiar lo que se almacena en la transcripción o se envía a Claude. Claude Code actúa sobre `displayContent` de su salida JSON y descarta `systemMessage` y `continue`.
1602 1592
1603Este ejemplo elimina el formato markdown de las respuestas de Claude para una visualización de texto plano. El script lee cada lote de stdin, elimina marcadores en negrita y comillas invertidas de código en línea de `delta`, y devuelve el resultado como `displayContent`.1593Este ejemplo elimina el formato markdown de las respuestas de Claude para una visualización de texto plano. El script lee cada lote de stdin, elimina marcadores en negrita y backticks de código en línea de `delta`, y devuelve el resultado como `displayContent`.
1604 1594
1605<Tabs>1595<Tabs>
1606 <Tab title="macOS/Linux">1596 <Tab title="macOS/Linux">
1607 Registre un hook de comando para el evento en su archivo de configuración:1597 Registra un hook de comando para el evento en tu archivo de configuración:
1608 1598
1609 ```json theme={null}1599 ```json theme={null}
1610 {1600 {
1624 }1614 }
1625 ```1615 ```
1626 1616
1627 Guarde este script en `.claude/hooks/plain-display.sh` en su proyecto y hágalo ejecutable con `chmod +x`:1617 Guarda este script en `.claude/hooks/plain-display.sh` en tu proyecto y hazlo ejecutable con `chmod +x`:
1628 1618
1629 ```bash theme={null}1619 ```bash theme={null}
1630 #!/bin/bash1620 #!/bin/bash
1633 </Tab>1623 </Tab>
1634 1624
1635 <Tab title="Windows (PowerShell)">1625 <Tab title="Windows (PowerShell)">
1636 Registre un hook de comando que ejecute el script a través de PowerShell:1626 Registra un hook de comando que ejecute el script a través de PowerShell:
1637 1627
1638 ```json theme={null}1628 ```json theme={null}
1639 {1629 {
1659 }1649 }
1660 ```1650 ```
1661 1651
1662 La bandera `-NoProfile` omite cargar su perfil de PowerShell para que el hook se inicie rápido, y `-ExecutionPolicy Bypass` permite que PowerShell ejecute el archivo de script local.1652 La bandera `-NoProfile` omite cargar tu perfil de PowerShell para que el hook se inicie rápido, y `-ExecutionPolicy Bypass` permite que PowerShell ejecute el archivo de script local.
1663 1653
1664 Guarde este script en `.claude/hooks/plain-display.ps1` en su proyecto:1654 Guarda este script en `.claude/hooks/plain-display.ps1` en tu proyecto:
1665 1655
1666 ```powershell theme={null}1656 ```powershell theme={null}
1667 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json1657 $batch = [Console]::In.ReadToEnd() | ConvertFrom-Json
1676 </Tab>1666 </Tab>
1677</Tabs>1667</Tabs>
1678 1668
1679Los 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.1669Los lotes sin markdown pasan sin cambios. Si el script falla, por ejemplo porque `jq` falta, Claude Code muestra el texto original y nota el fallo solo en [salida de depuración](#debug-hooks), no en la sesión.
1680 1670
1681<h3 id="pretooluse">1671<h3 id="pretooluse">
1682 PreToolUse1672 PreToolUse
1683</h3>1673</h3>
1684 1674
1685Se ejecuta después de que Claude crea parámetros de herramienta y antes de procesar la llamada de 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).1675Se 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).
1686 1676
1687Para 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.1677Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, usa [FileChanged](#filechanged) en lugar de coincidir con 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.
1688 1678
1689<Warning>1679<Warning>
1690 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.1680 PreToolUse se ejecuta solo cuando Claude llama a una herramienta. Los archivos que [referencias con `@` en tu prompt](/docs/es/common-workflows#reference-files-and-directories) se añaden sin ninguna llamada de herramienta: Claude Code inserta sus contenidos mientras construye el prompt, por lo que ningún hook PreToolUse se dispara para ellos, incluyendo hooks que coinciden con `Read`. Para bloquear rutas específicas de referencias `@`, usa una [regla de negación `Read`](/docs/es/permissions#read-and-edit) en su lugar.
1691 1681
1692 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).1682 PreToolUse tampoco se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).
1693</Warning>1683</Warning>
1694 1684
1695Use [control de decisión PreToolUse](#pretooluse-decision-control) para permitir, denegar, preguntar o diferir la llamada de herramienta.1685Usa [control de decisión PreToolUse](#pretooluse-decision-control) para permitir, negar, preguntar o diferir la llamada de herramienta.
1696 1686
1697Un hook de devolución de llamada [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.1687Un [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 negación explícita devuelta por otro hook aún tiene precedencia.
1698 1688
1699<h4 id="pretooluse-input">1689<h4 id="pretooluse-input">
1700 Entrada de PreToolUse1690 Entrada de PreToolUse
1702 1692
1703Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input`, y `tool_use_id`.1693Además de los [campos de entrada comunes](#common-input-fields), los hooks PreToolUse reciben `tool_name`, `tool_input`, y `tool_use_id`.
1704 1694
1705Para 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 de Agent SDK los enumera todos y dice cómo tratar uno que no reconozca. Base las decisiones de confianza en `source` en lugar de en `name` o el prefijo de nombre de herramienta `mcp__<server>__`. El campo `mcp_server` requiere Claude Code v2.1.274 o posterior.1695Para una [herramienta MCP](#match-mcp-tools), la entrada también lleva `mcp_server`, un objeto con el `name` del servidor y un `source` que dice de dónde vino la definición del servidor. Los valores `source` incluyen `plugin`, `sdk`, y alcances de configuración como `user` y `project`. [`McpServerProvenance`](/docs/es/agent-sdk/typescript#mcpserverprovenance) en la referencia del Agent SDK los enumera todos y dice cómo tratar uno que no reconozcas. Basa las decisiones de confianza en `source` en lugar de en `name` o el prefijo de nombre de herramienta `mcp__<server>__`. El campo `mcp_server` requiere Claude Code v2.1.274 o posterior.
1706 1696
1707Para las herramientas de archivo `Write`, `Edit`, y `Read`, `tool_input.file_path` siempre es absoluto:1697Para las herramientas de archivo `Write`, `Edit`, y `Read`, `tool_input.file_path` siempre es absoluto:
1708 1698
1709* Claude Code expande `~` y rutas relativas antes de que se ejecuten los hooks, por lo que un hook que coincide con rutas no puede ser eludido a través de `~` o un deletreo relativo de la misma ruta1699* Claude Code expande `~` y rutas relativas antes de que se ejecuten los hooks, por lo que un hook que coincida en rutas no puede ser eludido a través de `~` o un deletreo relativo de la misma ruta
1710* 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`1700* En Windows, la ruta llega con separadores de barra invertida, incluso cuando tu hook se ejecuta bajo Git Bash donde `$PWD` se ve como `/c/project`
1711* 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 bloquear1701* 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 bloquear
1712* 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 absoluta1702* Normaliza separadores antes de comparar: `FILE_PATH="${FILE_PATH//\\//}"` en Bash, o `file_path.replace("\\", "/")` en Python, luego coincide con un segmento de ruta como `/src/` en lugar de anclar con `^`, ya que la ruta es absoluta
1713 1703
1714Una llamada `Write` en Windows entrega:1704Una llamada `Write` en Windows entrega:
1715 1705
1740| `command` | string | `"npm test"` | El comando de shell a ejecutar |1730| `command` | string | `"npm test"` | El comando de shell a ejecutar |
1741| `description` | string | `"Run test suite"` | Descripción opcional de lo que hace el comando |1731| `description` | string | `"Run test suite"` | Descripción opcional de lo que hace el comando |
1742| `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 |1732| `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| `run_in_background` | boolean | `false` | Si ejecutar el comando en segundo plano |1733| `run_in_background` | boolean | `false` | Si se ejecuta el comando en segundo plano |
1744 1734
1745Cuando 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.1735Cuando 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, los registra solo en modo automático y modo `bypassPermissions`, y solo cuando Claude Code dirige a Claude a editar archivos a través de Bash. Establece `bashEditDiffEnabled` en `false` para desactivar el registro. Los comandos de fondo y los comandos de solo lectura no llevan diff.
1746 1736
1747Su 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.1737Tu [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.
1748 1738
1749<Note>1739<Note>
1750 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.1740 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. Usa la lista para encontrar qué revisar, no para aplicar una política.
1751</Note>1741</Note>
1752 1742
1753`changedFiles` y `files` enumeran qué cambió el comando; los campos restantes dicen qué tan completa y confiable es esa lista.1743`changedFiles` y `files` enumeran qué cambió el comando; los campos restantes dicen qué tan completa y confiable es esa lista.
1755| Campo | Tipo | Ejemplo | Descripción |1745| Campo | Tipo | Ejemplo | Descripción |
1756| :- | :- | :- | :- |1746| :- | :- | :- | :- |
1757| `changedFiles` | array | `["/path/to/src/app.ts"]` | Rutas absolutas de los archivos que el comando cambió, como máximo 200. Presente siempre que `files` contenga un diff o `moreFiles` esté por encima de cero |1747| `changedFiles` | array | `["/path/to/src/app.ts"]` | Rutas absolutas de los archivos que el comando cambió, como máximo 200. Presente siempre que `files` contenga un diff o `moreFiles` esté por encima de cero |
1758| `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ó |1748| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | Diffs de hasta 5 archivos cambiados, para visualización. `created` o `deleted` es `true` para un archivo que el comando añadió o eliminó |
1759| `moreFiles` | number | `2` | Recuento de archivos cambiados sin diff en `files` |1749| `moreFiles` | number | `2` | Recuento de archivos cambiados sin diff en `files` |
1760| `unavailable` | boolean | `true` | Se establece cuando el diff está incompleto o no se pudo tomar |1750| `unavailable` | boolean | `true` | Establecido cuando el diff está incompleto o no se pudo tomar |
1761| `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 |1751| `skipped` | boolean | `true` | Establecido 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| `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 |1752| `shared` | boolean | `true` | Establecido 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 1753
1764<a id="powershell" />1754<a id="powershell" />
1765 1755
1767 PowerShell1757 PowerShell
1768</h5>1758</h5>
1769 1759
1770Ejecuta comandos de PowerShell. Consulte la [herramienta PowerShell](/docs/es/tools-reference#powershell-tool) para disponibilidad por plataforma.1760Ejecuta comandos de PowerShell. Consulta la [herramienta PowerShell](/docs/es/tools-reference#powershell-tool) para disponibilidad por plataforma.
1771 1761
1772Los campos coinciden con la herramienta Bash, con la cadena de comando en `command`:1762Los campos coinciden con la herramienta Bash, con la cadena de comando en `command`:
1773 1763
1776| `command` | string | `"Get-ChildItem -Recurse"` | El comando de PowerShell a ejecutar |1766| `command` | string | `"Get-ChildItem -Recurse"` | El comando de PowerShell a ejecutar |
1777| `description` | string | `"List files recursively"` | Descripción opcional de lo que hace el comando |1767| `description` | string | `"List files recursively"` | Descripción opcional de lo que hace el comando |
1778| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos |1768| `timeout` | number | `120000` | Tiempo de espera opcional en milisegundos |
1779| `run_in_background` | boolean | `false` | Si ejecutar el comando en segundo plano |1769| `run_in_background` | boolean | `false` | Si se ejecuta el comando en segundo plano |
1780 1770
1781Coincida con `Bash|PowerShell` en hooks que inspeccionen comandos de shell, para que cubran ambas herramientas:1771Coincide en `Bash|PowerShell` en hooks que inspeccionan comandos de shell, para que cubran ambas herramientas:
1782 1772
1783* 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.1773* 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 sin Git Bash, la herramienta se habilita automáticamente y Claude Code no registra la herramienta Bash en absoluto.1774* En Windows sin Git Bash, la herramienta se habilita automáticamente y Claude Code no registra la herramienta Bash en absoluto.
1806| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo a editar |1796| `file_path` | string | `"/path/to/file.txt"` | Ruta absoluta al archivo a editar |
1807| `old_string` | string | `"original text"` | Texto a encontrar y reemplazar |1797| `old_string` | string | `"original text"` | Texto a encontrar y reemplazar |
1808| `new_string` | string | `"replacement text"` | Texto de reemplazo |1798| `new_string` | string | `"replacement text"` | Texto de reemplazo |
1809| `replace_all` | boolean | `false` | Si reemplazar todas las ocurrencias |1799| `replace_all` | boolean | `false` | Si se reemplazan todas las ocurrencias |
1810 1800
1811<h5 id="read">1801<h5 id="read">
1812 Read1802 Read
1828 1818
1829| Campo | Tipo | Ejemplo | Descripción |1819| Campo | Tipo | Ejemplo | Descripción |
1830| :- | :- | :- | :- |1820| :- | :- | :- | :- |
1831| `pattern` | string | `"**/*.ts"` | Patrón glob para hacer coincidir archivos contra |1821| `pattern` | string | `"**/*.ts"` | Patrón glob para coincidir archivos contra |
1832| `path` | string | `"/path/to/dir"` | Directorio opcional para buscar en. Por defecto es el directorio de trabajo actual |1822| `path` | string | `"/path/to/dir"` | Directorio opcional para buscar en. Por defecto es el directorio de trabajo actual |
1833 1823
1834<h5 id="grep">1824<h5 id="grep">
1843| `path` | string | `"/path/to/dir"` | Archivo o directorio opcional para buscar en |1833| `path` | string | `"/path/to/dir"` | Archivo o directorio opcional para buscar en |
1844| `glob` | string | `"*.ts"` | Patrón glob opcional para filtrar archivos |1834| `glob` | string | `"*.ts"` | Patrón glob opcional para filtrar archivos |
1845| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Por defecto es `"files_with_matches"` |1835| `output_mode` | string | `"content"` | `"content"`, `"files_with_matches"`, o `"count"`. Por defecto es `"files_with_matches"` |
1846| `-i` | boolean | `true` | Búsqueda insensible a mayúsculas y minúsculas |1836| `-i` | boolean | `true` | Búsqueda insensible a mayúsculas |
1847| `multiline` | boolean | `false` | Habilitar coincidencia multilínea |1837| `multiline` | boolean | `false` | Habilitar coincidencia multilínea |
1848 1838
1849<h5 id="webfetch">1839<h5 id="webfetch">
1878| Campo | Tipo | Ejemplo | Descripción |1868| Campo | Tipo | Ejemplo | Descripción |
1879| :- | :- | :- | :- |1869| :- | :- | :- | :- |
1880| `prompt` | string | `"Find all API endpoints"` | La tarea para que el agente realice |1870| `prompt` | string | `"Find all API endpoints"` | La tarea para que el agente realice |
1881| `description` | string | `"Find API endpoints"` | Descripción breve de la tarea |1871| `description` | string | `"Find API endpoints"` | Descripción corta de la tarea |
1882| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |1872| `subagent_type` | string | `"Explore"` | Tipo de agente especializado a usar |
1883| `model` | string | `"sonnet"` | Alias de modelo opcional para anular el predeterminado |1873| `model` | string | `"sonnet"` | Alias de modelo opcional para anular el predeterminado |
1884 1874
1885Cuando una llamada de Agent en primer plano se completa, su hook [PostToolUse](#posttooluse) recibe el resultado del subagente y 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:1875Cuando una llamada Agent en primer plano se completa, tu [hook PostToolUse](#posttooluse) recibe el resultado del subagente y telemetría de ejecución en `tool_response`. Lee estos campos para inspeccionar la ejecución; para resúmenes de tokens y costos en subagentes, usa 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:
1886 1876
1887| Campo | Tipo | Ejemplo | Descripción |1877| Campo | Tipo | Ejemplo | Descripción |
1888| :- | :- | :- | :- |1878| :- | :- | :- | :- |
1889| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes en segundo plano. A partir de v2.1.198, los subagentes se ejecutan en segundo plano de forma predeterminada, por lo que un `run_in_background` omitido también produce `"async_launched"` |1879| `status` | string | `"completed"` | `"completed"` para subagentes en primer plano, `"async_launched"` para subagentes en segundo plano. A partir de v2.1.198, los subagentes se ejecutan en segundo plano por defecto, por lo que un `run_in_background` omitido también produce `"async_launched"` |
1890| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para la ejecución del subagente |1880| `agentId` | string | `"a4d2c8f1e0b3a297"` | Identificador para la ejecución del subagente |
1891| `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 |1881| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | Los bloques de texto finales del subagente, o, para un subagente cuyo informe pasa a través de `SubagentHandback`, una nota breve sobre esa entrega en su lugar |
1892| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo en el que comenzó el subagente, que puede diferir del modelo solicitado |1882| `resolvedModel` | string | `"claude-sonnet-4-5"` | Modelo en el que comenzó el subagente, que puede diferir del modelo solicitado |
1893| `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 |1883| `modelsUsed` | array | `["claude-sonnet-4-5", "claude-haiku-4-5"]` | Modelos usados en orden, con repeticiones consecutivas colapsadas; establecido solo cuando el modelo fue intercambiado a mitad de ejecución. Requiere Claude Code v2.1.212 o posterior |
1894| `totalTokens` | number | `12450` | Recuento de tokens de la solicitud final de API del subagente: tokens de entrada, salida y caché combinados. Este no es un total en toda la ejecución |1884| `totalTokens` | number | `12450` | Recuento de tokens de la solicitud final de la API del subagente: tokens de entrada, salida y caché combinados. Esto no es un total en toda la ejecución |
1895| `totalDurationMs` | number | `48211` | Duración de reloj de pared de la ejecución del subagente |1885| `totalDurationMs` | number | `48211` | Duración de reloj de pared de la ejecución del subagente |
1896| `totalToolUseCount` | number | `7` | Recuento de llamadas de herramienta que realizó el subagente |1886| `totalToolUseCount` | number | `7` | Recuento de llamadas de herramienta que hizo el subagente |
1897| `usage` | object | `{"input_tokens": 8320, ...}` | Desglose de tokens por tipo de la solicitud final de API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |1887| `usage` | object | `{"input_tokens": 8320, ...}` | Desglose de tokens por tipo de la solicitud final de la API: `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens` |
1898 1888
1899En 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` luego 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`.1889En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference), que Claude Code proporciona en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode), entrega su informe a través de esa herramienta en lugar de devolverlo como texto. El campo `content` de su resultado `completed` entonces lleva una nota breve sobre esa entrega en lugar del informe en sí. Para leer el informe, coincide un hook `PreToolUse` o `PostToolUse` en `SubagentHandback` y lee `tool_input.message`.
1900 1890
1901Para subagentes en segundo plano, la herramienta devuelve cuando la tarea se mueve al segundo plano, por lo que `tool_response` no lleva campos de uso: un lanzamiento en segundo plano devuelve inmediatamente, y una tarea en primer plano que Claude Code pone en segundo plano a mitad de ejecución devuelve en esa transición. Tiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, y `resolvedModel`.1891Para subagentes en segundo plano, la herramienta devuelve cuando la tarea se mueve al segundo plano, por lo que `tool_response` no lleva campos de uso: un lanzamiento en segundo plano devuelve inmediatamente, y una tarea en primer plano que Claude Code pone en segundo plano a mitad de ejecución devuelve en esa transición. Tiene `status: "async_launched"`, `agentId`, `description`, `prompt`, `outputFile`, y `resolvedModel`.
1902 1892
1912 1902
1913| Campo | Tipo | Ejemplo | Descripción |1903| Campo | Tipo | Ejemplo | Descripción |
1914| :- | :- | :- | :- |1904| :- | :- | :- | :- |
1915| `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 |1905| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React"}], "multiSelect": false}]` | Preguntas a presentar, cada una con una cadena `question`, `header` corto, array `options`, y bandera `multiSelect` opcional |
1916| `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 |1906| `answers` | object | `{"Which framework?": "React"}` | Opcional. Mapea 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; suministralo a través de `updatedInput` para responder programáticamente |
1917 1907
1918<h5 id="exitplanmode">1908<h5 id="exitplanmode">
1919 ExitPlanMode1909 ExitPlanMode
1920</h5>1910</h5>
1921 1911
1922Presenta 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 `tool_input` literal del modelo es típicamente vacía. Claude Code inyecta el contenido del plan y la ruta del archivo antes de pasar la entrada a los hooks.1912Presenta un plan y pide al usuario que lo apruebe antes de que Claude salga del [modo plan](/docs/es/permission-modes#analyze-before-you-edit-with-plan-mode). Claude escribe el plan en un archivo en el disco antes de llamar a la herramienta, por lo que la `tool_input` literal del modelo es típicamente vacía. Claude Code inyecta el contenido del plan y la ruta del archivo antes de pasar la entrada a los hooks.
1923 1913
1924| Campo | Tipo | Ejemplo | Descripción |1914| Campo | Tipo | Ejemplo | Descripción |
1925| :- | :- | :- | :- |1915| :- | :- | :- | :- |
1927| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Inyectado |1917| `planFilePath` | string | `"/Users/.../plans/refactor-auth.md"` | Ruta al archivo del plan. Inyectado |
1928| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecado. Claude Code acepta el campo pero lo ignora. Antes de v2.1.205, llevaba permisos basados en prompts que Claude solicitó para implementar el plan |1918| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | Deprecado. Claude Code acepta el campo pero lo ignora. Antes de v2.1.205, llevaba permisos basados en prompts que Claude solicitó para implementar el plan |
1929 1919
1930En `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.1920En `PostToolUse`, `tool_response` es un objeto con campos `plan` y `filePath` que contienen el plan aprobado, más banderas de estado internas. Lee `tool_response.plan` para el contenido del plan en lugar de releer el archivo del disco.
1931 1921
1932<h4 id="pretooluse-decision-control">1922<h4 id="pretooluse-decision-control">
1933 Control de decisión de PreToolUse1923 Control de decisión de PreToolUse
1934</h4>1924</h4>
1935 1925
1936Los hooks `PreToolUse` pueden controlar si procede una llamada de herramienta. A diferencia de otros hooks que usan un campo `decision` de nivel superior, PreToolUse devuelve su decisión dentro de un objeto `hookSpecificOutput`. Esto le da un control más rico: cuatro resultados (permitir, denegar, preguntar o diferir) más la capacidad de modificar la entrada de herramienta antes de la ejecución.1926Los hooks `PreToolUse` pueden controlar si procede una llamada de herramienta. A diferencia de otros hooks que usan un campo `decision` de nivel superior, PreToolUse devuelve su decisión dentro de un objeto `hookSpecificOutput`. Esto le da control más rico: cuatro resultados (permitir, negar, preguntar o diferir) más la capacidad de modificar la entrada de herramienta antes de la ejecución.
1937 1927
1938| Campo | Descripción |1928| Campo | Descripción |
1939| :- | :- |1929| :- | :- |
1940| `permissionDecision` | `"allow"` omite el aviso 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"` 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 |1930| `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 elegantemente para que la herramienta pueda reanudarse más tarde. Las [reglas de negación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan independientemente de lo que devuelva el hook |
1941| `permissionDecisionReason` | Para `"allow"` y `"ask"`, se muestra al usuario pero no a Claude. Para `"deny"`, se muestra a Claude. Para `"defer"`, se ignora |1931| `permissionDecisionReason` | Para `"deny"`, se muestra a Claude. Para `"ask"`, se muestra en el prompt de permiso. Para `"allow"` y `"defer"`, se escribe en el [registro de depuración](#debug-hooks) solo |
1942| `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 [segundo plano automático](/docs/es/tools-reference#background-commands) de un comando Bash contra la entrada que devuelve su hook, no la entrada que envió Claude. Combine con `"allow"` para aprobar automáticamente, o `"ask"` para mostrar la entrada modificada al usuario. Para `"defer"`, se ignora |1932| `updatedInput` | Modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluye campos sin cambios junto con los modificados. Claude Code evalúa reglas de permiso y la [elegibilidad de segundo plano automático](/docs/es/tools-reference#background-commands) de un comando Bash contra la entrada que devuelve tu hook, no la entrada que envió Claude. Combina con `"allow"` para auto-aprobar, o `"ask"` para mostrar la entrada modificada al usuario. Para `"defer"`, se ignora |
1943| `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) |1933| `additionalContext` | Cadena añadida al contexto de Claude junto con el resultado de la herramienta. Se ignora cuando `permissionDecision` es `"defer"`. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
1944 1934
1945Cuando múltiples hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.1935Cuando múltiples hooks PreToolUse devuelven decisiones diferentes, la precedencia es `deny` > `defer` > `ask` > `allow`.
1946 1936
1947Un 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.1937Un 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 negación.
1948 1938
1949Cuando un hook devuelve `"ask"`, el aviso de permiso mostrado al usuario incluye una etiqueta que identifica de dónde vino el hook: `[settings]` para un hook de cualquier archivo de configuración o del frontmatter del agente, `[plugin:<name>]` para el hook de un plugin, o `[skill]` para un hook del frontmatter de skill. Esto ayuda a los usuarios a entender qué fuente de configuración solicita confirmación.1939Cuando 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.
1950 1940
1951Un `"ask"` de un hook también fuerza un aviso de permiso en [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode): el clasificador aún puede 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 aviso 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.1941Un `"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 negar la llamada de herramienta, pero no puede aprobar la llamada silenciosamente. Antes de v2.1.211, el clasificador podría aprobar un comando Bash ejecutándose fuera del [sandbox](/docs/es/sandboxing) sin mostrar el prompt que el hook solicitó; el clasificador aún aplicaba sus propias reglas de seguridad a ese comando, y una negación de hook siempre se honraba.
1952 1942
1953```json theme={null}1943```json theme={null}
1954{1944{
1966 1956
1967<span id="allow-with-updatedinput" />1957<span id="allow-with-updatedinput" />
1968 1958
1969En [modo no interactivo](/docs/es/headless) con la bandera `-p`, Claude Code ofrece `AskUserQuestion` y `ExitPlanMode` solo cuando la ejecución tiene un [anfitrión de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs) para recibir el aviso, como una devolución de llamada `canUseTool` de 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.1959En [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 tu propia UI, y la devuelve en `updatedInput` para que la herramienta se ejecute sin solicitar. Devolver `"allow"` solo no es suficiente para estas herramientas. Para `AskUserQuestion`, devuelve el array `questions` original y añade un objeto [`answers`](#askuserquestion) que mapea el texto de cada pregunta a la respuesta elegida.
1970 1960
1971A partir de v2.1.199, una herramienta MCP cuyo servidor la marca con [`_meta["anthropic/requiresUserInteraction"]`](/docs/es/mcp#require-approval-for-a-specific-tool) es más estricta: un hook no puede omitir su aviso de aprobación con `"allow"`, con o sin `updatedInput`, porque Claude Code no puede confirmar que el hook recopiló la interacción que la herramienta necesita.1961A partir de v2.1.199, una herramienta MCP cuyo servidor la marca con [`_meta["anthropic/requiresUserInteraction"]`](/docs/es/mcp#require-approval-for-a-specific-tool) es más estricta: un hook no puede omitir su 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.
1972 1962
1973<Note>1963<Note>
1974 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.1964 PreToolUse previamente usaba campos `decision` y `reason` de nivel superior, pero estos están deprecados para este evento. Usa `hookSpecificOutput.permissionDecision` y `hookSpecificOutput.permissionDecisionReason` en su lugar. Los valores deprecados `"approve"` y `"block"` se mapean 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</Note>1965</Note>
1976 1966
1977<h4 id="defer-a-tool-call-for-later">1967<h4 id="defer-a-tool-call-for-later">
1978 Diferir una llamada de herramienta para más tarde1968 Diferir una llamada de herramienta para más tarde
1979</h4>1969</h4>
1980 1970
1981`"defer"` es para integraciones que ejecutan `claude -p` como un subproceso y leen su salida JSON, como una aplicación 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.1971`"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 UI 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 1972
1983La herramienta `AskUserQuestion` es el caso típico: Claude quiere hacer una pregunta al usuario, pero no hay terminal para responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [anfitrión de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasa con `--permission-prompt-tool`, así que comience la ejecución con una. El viaje de ida y vuelta funciona así:1973La herramienta `AskUserQuestion` es el caso típico: Claude quiere hacer una pregunta al usuario, pero no hay terminal para responder. Una ejecución `-p` ofrece `AskUserQuestion` solo cuando tiene un [host de permiso](/docs/es/headless#turn-off-permission-prompts-in-unattended-runs), como una herramienta MCP que pasas con `--permission-prompt-tool`, así que comienza la ejecución con una. El viaje de ida y vuelta funciona así:
1984 1974
19851. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.19751. Claude llama a `AskUserQuestion`. Se dispara el hook `PreToolUse`.
19862. 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.19762. El hook devuelve `permissionDecision: "defer"`. La herramienta no se ejecuta. El proceso sale con `stop_reason: "tool_deferred"` y la llamada de herramienta pendiente preservada en la transcripción.
19873. El proceso de llamada lee `deferred_tool_use` del resultado de SDK, muestra la pregunta en su propia interfaz de usuario, y espera una respuesta.19773. El proceso de llamada lee `deferred_tool_use` del resultado del SDK, muestra la pregunta en su propia UI, y espera una respuesta.
19884. El proceso de llamada ejecuta `claude -p --resume <session-id>` con el mismo anfitrión de permiso. Se dispara la misma llamada de herramienta `PreToolUse` nuevamente.19784. 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.
19895. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.19795. El hook devuelve `permissionDecision: "allow"` con la respuesta en `updatedInput`. La herramienta se ejecuta y Claude continúa.
1990 1980
1991El 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:1981El campo `deferred_tool_use` lleva el `id`, `name`, e `input` de la herramienta. El `input` son los parámetros que Claude generó para la llamada de herramienta, capturados antes de la ejecución:
2004}1994}
2005```1995```
2006 1996
2007No 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.1997No hay límite de tiempo de espera o reintento. La sesión permanece en el disco hasta que la reanudes, sujeta a la [limpieza de barrido de retención](/docs/es/claude-directory#cleaned-up-automatically) de [`cleanupPeriodDays`](/docs/es/settings-reference#cleanupperioddays), que elimina archivos de sesión después de 30 días por defecto, siguiendo las [reglas de barrido de retención](/docs/es/claude-directory#cleaned-up-automatically). Si la respuesta no está lista cuando reanudas, el hook puede devolver `"defer"` nuevamente y el proceso sale de la misma manera. El proceso de llamada controla cuándo romper el bucle eventualmente devolviendo `"allow"` o `"deny"` del hook.
2008 1998
2009`"defer"` solo funciona cuando Claude realiza una única llamada de herramienta en el turno. Si Claude realiza 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.1999`"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 2000
2011Si 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ó.2001Si 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 sucede cuando un servidor MCP que proporcionó la herramienta no está conectado para la sesión reanudada. El payload `deferred_tool_use` aún se incluye para que puedas identificar qué herramienta desapareció.
2012 2002
2013<Note>2003<Note>
2014 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. Sin él, Claude Code no restaura el modo de plan. Requiere Claude Code v2.1.246 o posterior.2004 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 aprobación. Si pasas ciertos otros indicadores 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.
2015 2005
2016 Cuando reanuda con `-p`, Claude Code no restaura ningún otro modo de permiso almacenado. Comienza la ejecución en el modo de permiso que comenzaría una nueva ejecución `claude -p`, 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 al reanudar](/docs/es/sessions#permission-mode-on-resume).2006 Cuando reanudas con `-p`, Claude Code no restaura ningún otro modo de permiso almacenado. Comienza la ejecución en el modo de permiso que comenzaría una nueva ejecución `claude -p`, así que pasa `--permission-mode` o `--dangerously-skip-permissions` nuevamente si la sesión diferida usó uno. Cuando reanudas con `claude --resume <session-id>` sin `-p`, Claude Code restaura el modo de permiso almacenado, con las excepciones enumeradas en [modo de permiso en reanudación](/docs/es/sessions#permission-mode-on-resume).
2017</Note>2007</Note>
2018 2008
2019<h3 id="permissionrequest">2009<h3 id="permissionrequest">
2020 PermissionRequest2010 PermissionRequest
2021</h3>2011</h3>
2022 2012
2023Se ejecuta cuando Claude Code está a punto de pedirle permiso para usar una herramienta. En sesiones que no pueden mostrar un aviso, como subagentes en segundo plano en [modo no interactivo](/docs/es/headless), Claude Code aún ejecuta estos hooks, y si ningún hook devuelve una decisión, deniega la llamada de herramienta.2013Se ejecuta cuando Claude Code está a punto de pedirte permiso para usar una herramienta. En sesiones que no pueden mostrar un prompt, como subagentes en segundo plano en [modo no interactivo](/docs/es/headless), Claude Code aún ejecuta estos hooks, y si ningún hook devuelve una decisión, niega la llamada de herramienta.
2024Use [control de decisión PermissionRequest](#permissionrequest-decision-control) para permitir o denegar en nombre del usuario.2014Usa [control de decisión PermissionRequest](#permissionrequest-decision-control) para permitir o negar en nombre del usuario.
2025 2015
2026Use este evento cuando necesite una señal en el momento en que Claude solicita permiso para usar una herramienta. Claude Code ejecuta un hook [Notification](#notification) con el tipo `permission_prompt` solo después de que el aviso ha esperado aproximadamente seis segundos.2016Usa este evento cuando necesites 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.
2027 2017
2028Claude Code no ejecuta hooks PermissionRequest para la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox. Para obtener una señal para ese aviso, use el tipo de notificación `permission_prompt`.2018Claude Code no ejecuta hooks PermissionRequest para la [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox. Para obtener una señal para ese prompt, usa el tipo de notificación `permission_prompt`.
2029 2019
2030Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2020Coincide en nombre de herramienta, los mismos valores que PreToolUse.
2031 2021
2032<h4 id="permissionrequest-input">2022<h4 id="permissionrequest-input">
2033 Entrada de PermissionRequest2023 Entrada de PermissionRequest
2034</h4>2024</h4>
2035 2025
2036Los 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.2026Los hooks PermissionRequest reciben 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 `permission_suggestions` opcional contiene las [actualizaciones de permiso](#permission-update-entries) que Claude Code sugiere para esta solicitud, como añadir una regla de permiso o cambiar el modo de permiso.
2037 2027
2038La 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.2028El array `permission_suggestions` no es una lista exacta de las opciones que ves, porque cada diálogo de permiso construye sus propias opciones. Algunos diálogos, como el de ediciones de archivo, no leen el array en absoluto y derivan sus opciones de la solicitud en sí. Un diálogo que sí lo lee aún puede retener una opción cuya sugerencia permanece en el array, 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.
2039 2029
2040Los 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 denegaría automáticamente una llamada que no puede solicitar. Ninguno de los dos eventos se dispara para [`EndConversation`](/docs/es/tools-reference#endconversation-tool-behavior).2030Los 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 pedirte 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).
2041 2031
2042```json theme={null}2032```json theme={null}
2043{2033{
2066 Control de decisión de PermissionRequest2056 Control de decisión de PermissionRequest
2067</h4>2057</h4>
2068 2058
2069Los 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:2059Los hooks `PermissionRequest` pueden permitir o negar solicitudes de permiso. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, tu script de hook puede devolver un objeto `decision` con estos campos específicos del evento:
2070 2060
2071| Campo | Descripción |2061| Campo | Descripción |
2072| :- | :- |2062| :- | :- |
2073| `behavior` | `"allow"` otorga el permiso, `"deny"` lo deniega. 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 |2063| `behavior` | `"allow"` otorga el permiso, `"deny"` lo niega. Las [reglas de negación y pregunta](/docs/es/permissions#manage-permissions) aún se evalúan, por lo que un hook que devuelve `"allow"` no anula una regla de negación coincidente |
2074| `updatedInput` | Solo para `"allow"`: 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 |2064| `updatedInput` | Solo para `"allow"`: modifica los parámetros de entrada de la herramienta antes de la ejecución. Reemplaza el objeto de entrada completo, así que incluye campos sin cambios junto con los modificados. La entrada modificada se re-evalúa contra reglas de negación y pregunta |
2075| `updatedPermissions` | Solo para `"allow"`: 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 |2065| `updatedPermissions` | Solo para `"allow"`: array de [entradas de actualización de permiso](#permission-update-entries) a aplicar, como añadir una regla de permiso o cambiar el modo de permiso de la sesión |
2076| `message` | Solo para `"deny"`: dice a Claude por qué se denegó el permiso |2066| `message` | Solo para `"deny"`: dice a Claude por qué se negó el permiso |
2077| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |2067| `interrupt` | Solo para `"deny"`: si es `true`, detiene a Claude |
2078 2068
2079Un 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 denegar la solicitud.2069Un 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.
2080 2070
2081```json theme={null}2071```json theme={null}
2082{2072{
2096 Entradas de actualización de permiso2086 Entradas de actualización de permiso
2097</h4>2087</h4>
2098 2088
2099El 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.2089El campo de salida `updatedPermissions` y el campo de entrada [`permission_suggestions`](#permissionrequest-input) ambos usan el mismo array 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.
2100 2090
2101| `type` | Campos | Efecto |2091| `type` | Campos | Efecto |
2102| :- | :- | :- |2092| :- | :- | :- |
2103| `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"` |2093| `addRules` | `rules`, `behavior`, `destination` | Añade reglas de permiso. `rules` es un array de objetos `{toolName, ruleContent?}`. Omite `ruleContent` para coincidir con toda la herramienta. `behavior` es `"allow"`, `"deny"`, o `"ask"` |
2104| `replaceRules` | `rules`, `behavior`, `destination` | Reemplaza todas las reglas del `behavior` dado en el `destination` con las `rules` proporcionadas |2094| `replaceRules` | `rules`, `behavior`, `destination` | Reemplaza todas las reglas del `behavior` dado en el `destination` con las `rules` proporcionadas |
2105| `removeRules` | `rules`, `behavior`, `destination` | Elimina reglas coincidentes del `behavior` dado |2095| `removeRules` | `rules`, `behavior`, `destination` | Elimina reglas coincidentes del `behavior` dado |
2106| `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 |2096| `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| `addDirectories` | `directories`, `destination` | Agrega directorios de trabajo. `directories` es una matriz de cadenas de ruta |2097| `addDirectories` | `directories`, `destination` | Añade directorios de trabajo. `directories` es un array de cadenas de ruta |
2108| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |2098| `removeDirectories` | `directories`, `destination` | Elimina directorios de trabajo |
2109 2099
2110<Note>2100<Note>
2111 `setMode` con `bypassPermissions` solo toma 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).2101 `setMode` con `bypassPermissions` solo toma efecto si iniciaste la sesión con modo 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 gestionada](/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 2102
2113 `bypassPermissions` nunca se persiste como `defaultMode` independientemente de `destination`.2103 `bypassPermissions` nunca se persiste como `defaultMode` independientemente de `destination`.
2114</Note>2104</Note>
2130 2120
2131Se ejecuta inmediatamente después de que una herramienta se completa exitosamente.2121Se ejecuta inmediatamente después de que una herramienta se completa exitosamente.
2132 2122
2133Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2123Coincide en nombre de herramienta, los mismos valores que PreToolUse.
2134 2124
2135Coincida más ampliamente cuando el nombre de la herramienta no es el filtro correcto:2125Coincide más ampliamente cuando el nombre de la herramienta no es el filtro correcto:
2136 2126
2137* 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).2127* Para ejecutar un hook después de que cualquier herramienta se complete exitosamente, omite el `matcher` o establécelo en `"*"`. Tu 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, añade el mismo hook bajo [PostToolUseFailure](#posttoolusefailure).
2138* 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.2128* Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, usa [FileChanged](#filechanged). Claude Code no ejecuta un hook `PostToolUse` que coincida con `Edit|Write` cuando un comando `Bash` o un proceso fuera de Claude Code reescribe el mismo archivo.
2139 2129
2140<h4 id="posttooluse-input">2130<h4 id="posttooluse-input">
2141 Entrada de PostToolUse2131 Entrada de PostToolUse
2142</h4>2132</h4>
2143 2133
2144Los 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 de herramienta de archivo `tool_input` 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).2134Los hooks `PostToolUse` se disparan después de que una herramienta ya se ha ejecutado exitosamente. La entrada incluye tanto `tool_input`, los argumentos enviados a la herramienta, como `tool_response`, el resultado que devolvió. El esquema exacto para ambos depende de la herramienta. Las rutas de `tool_input` de herramienta 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).
2145 2135
2146```json theme={null}2136```json theme={null}
2147{2137{
2166 2156
2167| Campo | Descripción |2157| Campo | Descripción |
2168| :- | :- |2158| :- | :- |
2169| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a avisos de permiso y hooks PreToolUse |2159| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye tiempo gastado en prompts de permiso y hooks PreToolUse |
2170 2160
2171<h4 id="posttooluse-decision-control">2161<h4 id="posttooluse-decision-control">
2172 Control de decisión de PostToolUse2162 Control de decisión de PostToolUse
2173</h4>2163</h4>
2174 2164
2175Los 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:2165Los 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:
2176 2166
2177| Campo | Descripción |2167| Campo | Descripción |
2178| :- | :- |2168| :- | :- |
2179| `decision` | `"block"` agrega el `reason` junto al resultado de la herramienta. Claude aún ve la salida original; para reemplazarla, use `updatedToolOutput` |2169| `decision` | `"block"` añade el `reason` junto al resultado de la herramienta. Claude aún ve la salida original; para reemplazarla, usa `updatedToolOutput` |
2180| `reason` | Explicación mostrada a Claude cuando `decision` es `"block"` |2170| `reason` | Explicación mostrada a Claude cuando `decision` es `"block"` |
2181| `additionalContext` | Cadena agregada al contexto de Claude junto con el resultado de la herramienta. Consulte [Agregar contexto para Claude](#add-context-for-claude) |2171| `additionalContext` | Cadena añadida al contexto de Claude junto con el resultado de la herramienta. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
2182| `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 |2172| `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. Consulta [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| `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 |2173| `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| `updatedMCPToolOutput` | Reemplaza la salida solo para [herramientas MCP](#match-mcp-tools). Prefiera `updatedToolOutput`, que funciona para todas las herramientas |2174| `updatedMCPToolOutput` | Reemplaza la salida solo para [herramientas MCP](#match-mcp-tools). Prefiere `updatedToolOutput`, que funciona para todas las herramientas |
2185 2175
2186El 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`:2176El 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`:
2187 2177
2201```2191```
2202 2192
2203<Warning>2193<Warning>
2204 `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.2194 `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, usa un hook [PreToolUse](#pretooluse) en su lugar.
2205 2195
2206 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.2196 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</Warning>2197</Warning>
2210 Anotar un resultado para el clasificador de modo automático2200 Anotar un resultado para el clasificador de modo automático
2211</h4>2201</h4>
2212 2202
2213Devuelva `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.2203Devuelve `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 soportada 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.
2214 2204
2215El ejemplo a continuación dice al clasificador de dónde vino la salida de una consulta:2205El ejemplo a continuación dice al clasificador de dónde vino la salida de una consulta:
2216 2206
2223}2213}
2224```2214```
2225 2215
2226Cuánto peso da el clasificador a la nota depende de dónde configuró el hook:2216Cuánto peso da el clasificador a la nota depende de dónde configuraste el hook:
2227 2217
2228* **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 la intención del usuario, y si afirma que aprobó o solicitó algo, el clasificador verifica esa afirmación contra sus propios mensajes en la conversación2218* **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 aprobaste o solicitaste algo, el clasificador verifica esa afirmación contra tus propios mensajes en la conversación
2229* **Devoluciones de llamada de Agent SDK en proceso**: cuando una aplicación que integra Claude Code registra el hook como una [devolución de llamada de SDK de TypeScript](/docs/es/agent-sdk/hooks) y devuelve la nota durante la sesión en vivo, el clasificador puede pesar una declaración del usuario retransmitida en la nota como intención del usuario. Tal declaración puede satisfacer un requisito de consentimiento que el clasificador aceptaría de un mensaje que envía, pero nunca levanta un bloqueo que su propio mensaje tampoco podría levantar. Después de que se reanuda una sesión, Claude Code trata las notas restauradas como contexto no verificado. Cuando hooks de ambos grupos anotan la misma llamada, el clasificador trata la nota combinada como contexto no verificado2219* **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íes, pero nunca levanta un bloqueo que tu propio mensaje tampoco pudiera levantar. Después de que se reanuda una sesión, Claude Code trata las notas restauradas como contexto no verificado. Cuando hooks de ambos grupos anotan la misma llamada, el clasificador trata la nota combinada como no verificada
2230 2220
2231Claude Code aplica estos límites al entregar la nota:2221Claude Code aplica estos límites al entregar la nota:
2232 2222
2233* **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 llamada2223* **Longitud**: Claude Code limita las notas para una llamada de herramienta a 2,000 caracteres y trunca el resto. El límite se comparte en cada hook que responde a esa llamada
2234* **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 herramienta2224* **Solo respuestas sincrónicas**: Claude Code ignora el campo en la respuesta de un hook que [se ejecuta en segundo plano](#run-hooks-in-the-background), porque esa respuesta llega después de que Claude Code registra el resultado de la herramienta
2235* **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 llamadas2225* **Llamadas que el clasificador no registra**: la transcripción del clasificador omite búsquedas de solo lectura como lecturas de archivo y búsquedas. Claude Code descarta una nota adjunta a una de esas llamadas
2236* **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 hook la reemplaza. Claude Code entrega una nota que devuelve sin una reescritura incluso cuando otro hook reescribe la salida2226* **Interacción con reescrituras**: cuando la nota describe 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 u otro hook la reemplaza. Claude Code entrega una nota que devuelves sin una reescritura incluso cuando otro hook reescribe la salida
2237 2227
2238<Warning>2228<Warning>
2239 El clasificador lee el contenido que coloca en `classifierContext` como información del anfitrión de la aplicación de la sesión, así que no copie salida de herramienta no confiable 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.2229 El clasificador lee contenido que colocas en `classifierContext` como información del anfitrión de la aplicación de la sesión, así que no copies salida de herramientas no confiables o texto de terceros en él. Mantén 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 uses el campo para entregar mensajes no relacionados o un flujo de eventos.
2240</Warning>2230</Warning>
2241 2231
2242<h3 id="posttoolusefailure">2232<h3 id="posttoolusefailure">
2243 PostToolUseFailure2233 PostToolUseFailure
2244</h3>2234</h3>
2245 2235
2246Se 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 fallas, enviar alertas o proporcionar retroalimentación correctiva a Claude.2236Se ejecuta cuando una herramienta que comenzó a ejecutarse falla: la herramienta lanzó un error, o una herramienta MCP devolvió un resultado de error. Úsalo para registrar fallos, enviar alertas o proporcionar retroalimentación correctiva a Claude.
2247 2237
2248Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2238Coincide en nombre de herramienta, los mismos valores que PreToolUse.
2249 2239
2250<Note>2240<Note>
2251 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).2241 Este evento no se dispara para llamadas de herramienta rechazadas antes de la ejecución: un nombre de herramienta desconocido, entrada que falla en validación de esquema o específica de herramienta, o una negación de permiso. Los rechazos de validación se devuelven como resultados `tool_use_error` y ocurren antes de que se ejecuten los hooks, por lo que no disparan ni `PreToolUse` ni `PostToolUseFailure`. Las negaciones de permiso disparan `PreToolUse` pero no este evento; consulta [PermissionDenied](#permissiondenied).
2252</Note>2242</Note>
2253 2243
2254<h4 id="posttoolusefailure-input">2244<h4 id="posttoolusefailure-input">
2255 Entrada de PostToolUseFailure2245 Entrada de PostToolUseFailure
2256</h4>2246</h4>
2257 2247
2258Los 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:2248Los hooks PostToolUseFailure reciben los mismos campos `tool_name` y `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:
2259 2249
2260```json theme={null}2250```json theme={null}
2261{2251{
2280| :- | :- |2270| :- | :- |
2281| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |2271| `error` | Cadena que describe qué salió mal. El formato depende de la herramienta que falló |
2282| `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 |2272| `is_interrupt` | Booleano opcional. Verdadero cuando el fallo llegó a Claude Code como una interrupción en lugar de como un error que reportó la herramienta. Cancelar una herramienta en ejecución no dispara este hook; el resultado de la herramienta lleva el mensaje de interrupción en su lugar |
2283| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye el tiempo dedicado a avisos de permiso y hooks PreToolUse |2273| `duration_ms` | Opcional. Tiempo de ejecución de la herramienta en milisegundos. Excluye tiempo gastado en prompts de permiso y hooks PreToolUse |
2284 2274
2285La cadena `error` es generalmente el mismo texto que Claude recibe como resultado fallido de la herramienta. 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.2275La cadena `error` es generalmente el mismo texto que Claude recibe como resultado de la herramienta fallida. Su formato varía según la herramienta y el fallo. Clave tu hook en `tool_name`, `is_interrupt`, y la primera línea `Exit code N`; trata el resto de la cadena como texto de visualización, no como un formato estable.
2286 2276
2287* 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 intercalados2277* Para Bash y PowerShell, un comando que se ejecutó y salió produce una primera línea `Exit code N`, luego cualquier salida que el comando produjo como un bloque con stdout y stderr intercalados
2288* 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í2278* Un payload 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* Claude Code trunca a mitad de cadenas largas alrededor de un marcador `... [N characters truncated] ...`, e puede insertar líneas propias, como `Command timed out after 2m 0s`2279* Claude Code trunca a mitad de cadenas largas alrededor de un marcador `... [N characters truncated] ...`, e puede insertar líneas propias, como `Command timed out after 2m 0s`
2290 2280
2291<h4 id="posttoolusefailure-decision-control">2281<h4 id="posttoolusefailure-decision-control">
2292 Control de decisión de PostToolUseFailure2282 Control de decisión de PostToolUseFailure
2293</h4>2283</h4>
2294 2284
2295Los 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:2285Los 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, tu script de hook puede devolver estos campos específicos del evento:
2296 2286
2297| Campo | Descripción |2287| Campo | Descripción |
2298| :- | :- |2288| :- | :- |
2299| `additionalContext` | Cadena agregada al contexto de Claude junto con el error. Consulte [Agregar contexto para Claude](#add-context-for-claude) |2289| `additionalContext` | Cadena añadida al contexto de Claude junto con el error. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
2300 2290
2301```json theme={null}2291```json theme={null}
2302{2292{
2311 PostToolBatch2301 PostToolBatch
2312</h3>2302</h3>
2313 2303
2314Se 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 realiza llamadas de herramienta paralelas. `PostToolBatch` se dispara exactamente una vez con el lote completo, por lo que es el lugar correcto para inyectar contexto que dependa del conjunto de herramientas que se ejecutaron en lugar de en cualquier herramienta única. No hay matcher para este evento.2304Se ejecuta una vez después de que cada llamada de herramienta en un lote se haya resuelto, antes de que Claude Code envíe la siguiente solicitud al modelo. `PostToolUse` se dispara una vez por herramienta, lo que significa que se dispara concurrentemente cuando Claude hace llamadas de herramienta paralelas. `PostToolBatch` se dispara exactamente una vez con el lote completo, por lo que es el lugar correcto para inyectar contexto que dependa del conjunto de herramientas que se ejecutaron en lugar de en cualquier herramienta única. No hay matcher para este evento.
2315 2305
2316<h4 id="posttoolbatch-input">2306<h4 id="posttoolbatch-input">
2317 Entrada de PostToolBatch2307 Entrada de PostToolBatch
2318</h4>2308</h4>
2319 2309
2320Ademá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:2310Además de los [campos de entrada comunes](#common-input-fields), los hooks PostToolBatch reciben `tool_calls`, un array que describe cada llamada de herramienta en el lote:
2321 2311
2322```json theme={null}2312```json theme={null}
2323{2313{
2331 "tool_name": "Read",2321 "tool_name": "Read",
2332 "tool_input": {"file_path": "/.../ledger/accounts.py"},2322 "tool_input": {"file_path": "/.../ledger/accounts.py"},
2333 "tool_use_id": "toolu_01...",2323 "tool_use_id": "toolu_01...",
2334 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2324 "tool_response": "1\tfrom __future__ import annotations\n2\t..."
2335 },2325 },
2336 {2326 {
2337 "tool_name": "Read",2327 "tool_name": "Read",
2338 "tool_input": {"file_path": "/.../ledger/transactions.py"},2328 "tool_input": {"file_path": "/.../ledger/transactions.py"},
2339 "tool_use_id": "toolu_02...",2329 "tool_use_id": "toolu_02...",
2340 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2330 "tool_response": "1\tfrom __future__ import annotations\n2\t..."
2341 }2331 }
2342 ]2332 ]
2343}2333}
2344```2334```
2345 2335
2346`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.2336`tool_response` contiene el mismo contenido que el modelo recibe en el bloque `tool_result` correspondiente. El valor es una cadena serializada o array de bloque de contenido, exactamente como lo emitió la herramienta. Las respuestas pueden ser grandes, así que analiza solo los campos que necesitas.
2347 2337
2348<Note>2338<Note>
2349 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.2339 La forma `tool_response` difiere de la de `PostToolUse`. `PostToolUse` pasa el objeto `Output` estructurado de la herramienta, como `{filePath: "...", type: "create"}` para `Write`; `PostToolBatch` pasa el contenido `tool_result` serializado que el modelo ve.
2350</Note>2340</Note>
2351 2341
2352<h4 id="posttoolbatch-decision-control">2342<h4 id="posttoolbatch-decision-control">
2353 Control de decisión de PostToolBatch2343 Control de decisión de PostToolBatch
2354</h4>2344</h4>
2355 2345
2356Los 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:2346Los 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:
2357 2347
2358| Campo | Descripción |2348| Campo | Descripción |
2359| :- | :- |2349| :- | :- |
2360| `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 |2350| `additionalContext` | Cadena de contexto inyectada una vez antes de la siguiente llamada del modelo. Consulta [Añadir 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 2351
2362```json theme={null}2352```json theme={null}
2363{2353{
2368}2358}
2369```2359```
2370 2360
2371Devolver `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.2361Devolver `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 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.
2372 2362
2373<h3 id="permissiondenied">2363<h3 id="permissiondenied">
2374 PermissionDenied2364 PermissionDenied
2375</h3>2365</h3>
2376 2366
2377Se ejecuta cuando [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) deniega una llamada de herramienta, incluido cuando deniega 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 deniega 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.2367Se ejecuta cuando [modo automático](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) niega una llamada de herramienta, incluyendo 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 niegas manualmente un diálogo de permiso, cuando un hook `PreToolUse` bloquea una llamada, o cuando una regla `deny` coincide. Úsalo para registrar negaciones, ajustar configuración o decirle al modelo que puede reintentar la llamada de herramienta.
2378 2368
2379Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.2369Coincide en nombre de herramienta, los mismos valores que PreToolUse.
2380 2370
2381<h4 id="permissiondenied-input">2371<h4 id="permissiondenied-input">
2382 Entrada de PermissionDenied2372 Entrada de PermissionDenied
2403 2393
2404| Campo | Descripción |2394| Campo | Descripción |
2405| :- | :- |2395| :- | :- |
2406| `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` |2396| `reason` | La razón de la negación. Para un veredicto del clasificador, en la mayoría de sesiones nombra la regla coincidente entre corchetes, como `[Data Exfiltration]`; consulta [Revisar negaciones](/docs/es/auto-mode-config#review-denials) para las otras formas. Para una [negación sin veredicto](#permissiondenied-decision-control), comienza con `Auto mode could not evaluate this action and is blocking it for safety`. Para una negación porque el modelo del clasificador no estaba disponible, es el texto fijo `Classifier unavailable` |
2407 2397
2408<h4 id="permissiondenied-decision-control">2398<h4 id="permissiondenied-decision-control">
2409 Control de decisión de PermissionDenied2399 Control de decisión de PermissionDenied
2410</h4>2400</h4>
2411 2401
2412Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta denegada. Devuelva un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:2402Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta negada. Devuelve un objeto JSON con `hookSpecificOutput.retry` establecido en `true`:
2413 2403
2414```json theme={null}2404```json theme={null}
2415{2405{
2420}2410}
2421```2411```
2422 2412
2423Cuando `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.2413Cuando `retry` es `true`, Claude Code añade un mensaje a la conversación diciéndole al modelo que puede reintentar la llamada de herramienta. Claude Code no revierte la negación en sí. Si tu hook no devuelve JSON, o devuelve `retry: false`, la negación se mantiene y el modelo recibe el mensaje de rechazo original.
2424 2414
2425Claude 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.2415Claude Code ignora `retry: true` cuando el clasificador produjo [ningún veredicto en la acción](/docs/es/errors#auto-mode-cannot-determine-the-safety-of-an-action): su respuesta no se analizó, o una verificación de seguridad separada del modo automático rechazó la propia solicitud del clasificador. Para esas negaciones, Claude Code ya le dice al modelo en el mensaje de rechazo si debe reintentar más tarde o continuar.
2426 2416
2427<h3 id="notification">2417<h3 id="notification">
2428 Notification2418 Notification
2429</h3>2419</h3>
2430 2420
2431Se 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.2421Se ejecuta cuando Claude Code envía notificaciones. Coincide en tipo de notificación. Omite el matcher para ejecutar hooks para todos los tipos de notificación.
2432 2422
2433Recibe 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.2423Recibes estos eventos de hook incluso con notificaciones de escritorio desactivadas: la configuración `preferredNotifChannel`, incluyendo `notifications_disabled`, cambia solo cómo se te alerta, no si tu hook se ejecuta.
2434 2424
2435| Matcher | Cuándo se dispara |2425| Matcher | Cuándo se dispara |
2436| :- | :- |2426| :- | :- |
2437| `permission_prompt` | Claude necesita su permiso para usar una herramienta o una [solicitud de red](/docs/es/sandboxing#network-isolation) de un comando en sandbox, y el aviso ha esperado aproximadamente seis segundos |2427| `permission_prompt` | Claude necesita tu 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| `idle_prompt` | Claude terminó de responder hace aproximadamente 60 segundos y no ha escrito desde entonces |2428| `idle_prompt` | Claude terminó de responder hace aproximadamente 60 segundos y no has escrito desde entonces |
2439| `auth_success` | La autenticación se completa |2429| `auth_success` | La autenticación se completa |
2440| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no ha escrito durante aproximadamente seis segundos |2430| `elicitation_dialog` | Un servidor MCP abre un formulario de elicitación y no has escrito durante aproximadamente seis segundos |
2441| `elicitation_url_dialog` | Un servidor MCP le pide que abra una URL de navegador y no ha escrito durante aproximadamente seis segundos |2431| `elicitation_url_dialog` | Un servidor MCP te pide que abras una URL de navegador y no has escrito durante aproximadamente seis segundos |
2442| `elicitation_complete` | Un servidor MCP reporta que una [elicitación de modo URL](#elicitation-input) está completa |2432| `elicitation_complete` | Un servidor MCP reporta que una [elicitación de modo URL](#elicitation-input) está completa |
2443| `elicitation_response` | Se envía una respuesta de elicitación de MCP de vuelta al servidor |2433| `elicitation_response` | Se envía una respuesta de elicitación de MCP de vuelta al servidor |
2444| `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, o la sesión actual le hace una pregunta de configuración de terminal de [compañero de equipo del agente](/docs/es/agent-teams#choose-a-display-mode) y no ha escrito durante aproximadamente seis segundos |2434| `agent_needs_input` | Una sesión en segundo plano comienza a esperar tu entrada mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal, o la sesión actual te hace una pregunta de [configuración de terminal de compañero de equipo del agente](/docs/es/agent-teams#choose-a-display-mode) y no has escrito durante aproximadamente seis segundos |
2445| `agent_completed` | Una sesión de fondo se completa o falla. Se dispara solo mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal |2435| `agent_completed` | Una sesión en segundo plano se completa o falla. Se dispara solo mientras [vista de agente](/docs/es/agent-view) está abierta en una terminal |
2446| `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) |2436| `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 reinicio, o antes cuando algo que haces en Claude Code durante la espera, como añadir créditos de uso, actualizar tu 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_stale` | Un límite de uso de claude.ai se reinició mientras su computadora dormía durante más de aproximadamente 30 minutos. Claude Code espera a que presione `Enter` en lugar de continuar. Después de un sueño más corto continúa y dispara `quota_auto_resume_fired` en su lugar |2437| `quota_auto_resume_stale` | Un límite de uso de claude.ai se reinició mientras tu computadora dormía durante más de aproximadamente 30 minutos. Claude Code espera a que presiones `Enter` en lugar de continuar. Después de un sueño más corto continúa y dispara `quota_auto_resume_fired` en su lugar |
2448| `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 su cuenta, 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** |2438| `quota_auto_resume_disabled` | Claude Code termina su espera por un límite de uso de claude.ai sin continuar tu 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 su cuenta, la tarea continuada siguió golpeando el límite, o la continuación fue bloqueada antes de llegar al modelo. No se dispara cuando presionas `Esc` o `Ctrl+C`, o seleccionas **No continuar automáticamente** |
2449 2439
2450Los tipos `agent_needs_input` y `agent_completed` requieren Claude Code v2.1.198 o posterior.2440Los tipos `agent_needs_input` y `agent_completed` requieren Claude Code v2.1.198 o posterior.
2451 2441
2456`agent_needs_input` para una pregunta de configuración de terminal de compañero requiere Claude Code v2.1.248 o posterior.2446`agent_needs_input` para una pregunta de configuración de terminal de compañero requiere Claude Code v2.1.248 o posterior.
2457 2447
2458<Note>2448<Note>
2459 Los tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog`, y `elicitation_url_dialog` comparten su tiempo con notificaciones de escritorio, así que en sesiones de terminal solo los ve cuando parece que está lejos de la terminal:2449 Los tipos `permission_prompt`, `idle_prompt`, `elicitation_dialog`, y `elicitation_url_dialog` comparten su tiempo con notificaciones de escritorio, así que en sesiones de terminal solo los ves cuando pareces estar lejos de la terminal:
2460 2450
2461 * Espere `permission_prompt` una vez que no haya escrito durante aproximadamente seis segundos. El temporizador comienza cuando aparece el aviso de permiso, y cada pulsación de tecla lo difiere. Para ejecutar un hook inmediatamente cuando Claude solicita permiso para usar una herramienta, use [PermissionRequest](#permissionrequest) en su lugar.2451 * Espera `permission_prompt` una vez que no hayas 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, usa [PermissionRequest](#permissionrequest) en su lugar.
2462 * 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.2452 * Espera `idle_prompt` aproximadamente 60 segundos después de que Claude termine de responder, y solo si no has 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.
2463 * 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.2453 * Espera `elicitation_dialog` para un formulario de elicitación, o `elicitation_url_dialog` para una solicitud de URL de navegador, una vez que no hayas 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.
2464 2454
2465 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.2455 Una solicitud de permiso o elicitación que llega mientras otro diálogo está en pantalla mantiene la misma puerta de seis segundos, cronometrada desde cuando llega la solicitud. Su notificación puede alcanzarte mientras la solicitud aún espera detrás del diálogo abierto.
2466</Note>2456</Note>
2467 2457
2468Claude Code cronometra `permission_prompt` diferente en sesiones donde envía solicitudes de permiso a la devolución de llamada [`canUseTool`](/docs/es/agent-sdk/user-input) de Agent SDK, que es cómo Claude Desktop y la extensión VS Code alojan Claude Code:2458Claude 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:
2469 2459
2470* Espere `permission_prompt` aproximadamente seis segundos después de que Claude solicita permiso. Claude Code no lo difiere mientras escribe.2460* Espera `permission_prompt` aproximadamente seis segundos después de que Claude solicita permiso. Claude Code no lo difiere mientras escribes.
2471* Si usted o un hook [PermissionRequest](#permissionrequest) responden antes, Claude Code no ejecuta `permission_prompt`.2461* Si tú o un hook [PermissionRequest](#permissionrequest) respondes antes, Claude Code no ejecuta `permission_prompt`.
2472* Establezca [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.2462* Establece [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/es/env-vars) en `1` para desactivar `permission_prompt` en estas sesiones.
2473 2463
2474Antes de v2.1.233, `permission_prompt` no se disparaba en estas sesiones.2464Antes de v2.1.233, `permission_prompt` no se disparaba en estas sesiones.
2475 2465
2476Use 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:2466Usa matchers separados para ejecutar diferentes manejadores dependiendo del tipo de notificación. Esta configuración activa 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:
2477 2467
2478```json theme={null}2468```json theme={null}
2479{2469{
2506 Entrada de Notification2496 Entrada de Notification
2507</h4>2497</h4>
2508 2498
2509Ademá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ó.2499Ademá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` indicando qué tipo se disparó.
2510 2500
2511```json theme={null}2501```json theme={null}
2512{2502{
2520}2510}
2521```2511```
2522 2512
2523Los 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.2513Los hooks Notification no pueden bloquear o modificar notificaciones. Claude Code descarta sus campos `systemMessage` y `continue` pero aún emite [`terminalSequence`](#emit-terminal-notifications), que es en lo que se basa el ejemplo de notificación de escritorio. Los hooks Notification están destinados a efectos secundarios como reenviar la notificación a un servicio externo.
2524 2514
2525<h3 id="subagentstart">2515<h3 id="subagentstart">
2526 SubagentStart2516 SubagentStart
2527</h3>2517</h3>
2528 2518
2529Se 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.2519Se ejecuta cuando Claude genera un subagente con la herramienta Agent, cuando Claude [reanuda un subagente](/docs/es/sub-agents#resume-subagents), y cada vez que un [equipo de agentes](/docs/es/agent-teams) compañero en proceso maneja un nuevo mensaje. Admite matchers para filtrar por nombre de tipo de agente. Para agentes integrados, este es el nombre del agente como `general-purpose`, `Explore`, o `Plan`. Para [subagentes personalizados](/docs/es/sub-agents), este es el campo `name` del frontmatter del agente, no el nombre del archivo.
2530 2520
2531Para subagentes enviados por un [plugin](/docs/es/plugins), 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$`.2521Para subagentes enviados por un [plugin](/docs/es/plugins/overview), el tipo de agente es el identificador con alcance de plugin como `my-plugin:reviewer`, no el nombre de frontmatter desnudo. El colon coloca un nombre con alcance de plugin en la ruta de expresión regular, así que ancla el matcher con `^` y `$` para una coincidencia exacta: `^my-plugin:reviewer$`.
2532 2522
2533<h4 id="subagentstart-input">2523<h4 id="subagentstart-input">
2534 Entrada de SubagentStart2524 Entrada de SubagentStart
2547}2537}
2548```2538```
2549 2539
2550Los hooks SubagentStart no pueden bloquear la creación del subagente, pero pueden inyectar contexto en el subagente. Además de los [campos de salida JSON](#json-output) disponibles para todos los hooks, puede devolver:2540Los 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:
2551 2541
2552| Campo | Descripción |2542| Campo | Descripción |
2553| :- | :- |2543| :- | :- |
2554| `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) |2544| `additionalContext` | Cadena añadida al contexto del subagente al inicio de su conversación, antes de su primer prompt. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
2555 2545
2556```json theme={null}2546```json theme={null}
2557{2547{
2562}2552}
2563```2553```
2564 2554
2565Cuando 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.2555Cuando 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 [compactación automática](/docs/es/sub-agents#auto-compaction) descarta esa copia, Claude Code inyecta el contexto de la siguiente ejecución nuevamente.
2566 2556
2567<h3 id="subagentstop">2557<h3 id="subagentstop">
2568 SubagentStop2558 SubagentStop
2569</h3>2559</h3>
2570 2560
2571Se ejecuta cuando un subagente de Claude Code ha terminado de responder. Coincide en el tipo de agente, los mismos valores que SubagentStart.2561Se ejecuta cuando un subagente de Claude Code ha terminado de responder. Coincide en tipo de agente, los mismos valores que SubagentStart.
2572 2562
2573<h4 id="subagentstop-input">2563<h4 id="subagentstop-input">
2574 Entrada de SubagentStop2564 Entrada de SubagentStop
2578 2568
2579No 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.2569No 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.
2580 2570
2581Un `matcher` que nombra tipos de agente no coincide con un `agent_type` vacío. Un hook cuyo matcher está omitido, `""`, o `"*"`, o es una expresión regular que coincide con una cadena vacía, se ejecuta para eventos con un `agent_type` vacío también.2571Un `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.
2582 2572
2583En 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` luego 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 coincida en `SubagentHandback` recibe como `tool_input.message`.2573En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta [`SubagentHandback`](/docs/es/tools-reference) entrega su informe a través de esa herramienta antes de que se detenga. El campo `last_assistant_message` entonces contiene el texto de cierre del subagente, si lo hay, que no es el informe entregado. El informe es la entrada `message` de esa llamada, que un hook `PreToolUse` o `PostToolUse` que coincide en `SubagentHandback` recibe como `tool_input.message`.
2584 2574
2585Los hooks SubagentStop también reciben las matrices `background_tasks` y `session_crons` descritas en [Entrada de Stop](#stop-input). Ambas matrices tienen alcance a la sesión padre, no al subagente.2575Los hooks SubagentStop también reciben los arrays `background_tasks` y `session_crons` descritos en [Entrada de Stop](#stop-input). Ambos arrays están limitados a la sesión padre, no al subagente.
2586 2576
2587```json theme={null}2577```json theme={null}
2588{2578{
2601}2591}
2602```2592```
2603 2593
2604Los 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.2594Los hooks SubagentStop usan el mismo formato de control de decisión que [hooks Stop](#stop-decision-control), incluyendo `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, usa un hook [`PostToolUse`](#posttooluse) en la herramienta `Agent` en su lugar.
2605 2595
2606<h3 id="taskcreated">2596<h3 id="taskcreated">
2607 TaskCreated2597 TaskCreated
2608</h3>2598</h3>
2609 2599
2610Se 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.2600Se ejecuta cuando se está creando una tarea a través de la herramienta `TaskCreate`. Úsalo para aplicar 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.
2611 2601
2612Los hooks TaskCreated no admiten matchers y se disparan en cada ocurrencia.2602Los hooks TaskCreated no admiten matchers y se disparan en cada ocurrencia.
2613 2603
2637| `task_subject` | Título de la tarea |2627| `task_subject` | Título de la tarea |
2638| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2628| `task_description` | Descripción detallada de la tarea. Puede estar ausente |
2639| `teammate_name` | Nombre del compañero que está creando la tarea. Puede estar ausente |2629| `teammate_name` | Nombre del compañero que está creando la tarea. Puede estar ausente |
2640| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2630| `team_name` | Deprecado. Nombre de equipo derivado de sesión; será eliminado en una versión futura |
2641 2631
2642<h4 id="taskcreated-decision-control">2632<h4 id="taskcreated-decision-control">
2643 Control de decisión de TaskCreated2633 Control de decisión de TaskCreated
2644</h4>2634</h4>
2645 2635
2646Un hook TaskCreated puede bloquear la creación de dos formas. De cualquier manera, 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 continúa trabajando.2636Un hook TaskCreated puede bloquear la creación de dos formas. De cualquier forma, 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.
2647 2637
2648* **Código de salida 2**: Claude Code devuelve el texto stderr como el mensaje.2638* **Código de salida 2**: Claude Code devuelve el texto stderr como el mensaje.
2649* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como el mensaje.2639* **JSON `{"decision": "block", "reason": "..."}`**: Claude Code devuelve `reason` como el mensaje.
2667 TaskCompleted2657 TaskCompleted
2668</h3>2658</h3>
2669 2659
2670Se 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.2660Se 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 [equipo de agentes](/docs/es/agent-teams) compañero termina su turno con tareas en progreso. Úsalo para aplicar criterios de finalización como pasar pruebas o verificaciones de lint antes de que una tarea pueda cerrarse.
2671 2661
2672Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.2662Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.
2673 2663
2698| `task_subject` | Título de la tarea |2688| `task_subject` | Título de la tarea |
2699| `task_description` | Descripción detallada de la tarea. Puede estar ausente |2689| `task_description` | Descripción detallada de la tarea. Puede estar ausente |
2700| `teammate_name` | Nombre del compañero que está completando la tarea. Puede estar ausente |2690| `teammate_name` | Nombre del compañero que está completando la tarea. Puede estar ausente |
2701| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2691| `team_name` | Deprecado. Nombre de equipo derivado de sesión; será eliminado en una versión futura |
2702 2692
2703<h4 id="taskcompleted-decision-control">2693<h4 id="taskcompleted-decision-control">
2704 Control de decisión de TaskCompleted2694 Control de decisión de TaskCompleted
2707Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:2697Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:
2708 2698
2709* **Código de salida 2**: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.2699* **Código de salida 2**: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.
2710* **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.2700* **JSON `{"continue": false, "stopReason": "..."}`**: cuando un compañero terminando su turno activó el evento, detiene completamente al compañero, coincidiendo con el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario. Cuando la herramienta `TaskUpdate` activó el evento, Claude Code ignora `continue: false`; el código de salida 2 aún bloquea la finalización.
2711 2701
2712Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:2702Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:
2713 2703
2732Se 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.2722Se 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.
2733 2723
2734<Tip>2724<Tip>
2735 El comando [`/goal`](/docs/es/goal) es un atajo integrado para un hook Stop basado en prompt con alcance de sesión. Úselo cuando quiera que Claude continúe trabajando hacia una condición sin escribir configuración de hook.2725 El comando [`/goal`](/docs/es/goal) es un atajo integrado para un hook Stop con alcance de sesión basado en prompts. Úsalo cuando quieras que Claude siga trabajando hacia una condición sin escribir configuración de hook.
2736</Tip>2726</Tip>
2737 2727
2738<h4 id="stop-input">2728<h4 id="stop-input">
2739 Entrada de Stop2729 Entrada de Stop
2740</h4>2730</h4>
2741 2731
2742Ademá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. Verifique este valor o procese la transcripción para evitar bloquear en una condición que nunca se resolverá. Claude Code anula el hook y termina el turno después de 8 bloqueos consecutivos.2732Además de los [campos de entrada comunes](#common-input-fields), los hooks Stop reciben `stop_hook_active`, `last_assistant_message`, `background_tasks`, y `session_crons`. El campo `stop_hook_active` es `true` cuando Claude Code ya está continuando como resultado de un hook stop. Verifica este valor o procesa 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 stop hayan continuado el turno ocho veces seguidas, Claude Code anula el siguiente bloqueo y termina el turno. Para elevar el límite, establece [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/es/env-vars).
2743 2733
2744El campo `last_assistant_message` contiene el contenido de texto de la respuesta final de Claude, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción. Para hooks que actúan en el turno recién completado, como hooks de lectura en voz alta o notificación, use este campo en lugar de leer `transcript_path`: el archivo de transcripción no se garantiza que incluya el mensaje final en el tiempo de Stop en todas las versiones.2734El campo `last_assistant_message` contiene el contenido de texto de la respuesta final de Claude, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción. Para hooks que actúan en el turno recién completado, como hooks de lectura en voz alta o notificación, usa este campo en lugar de leer `transcript_path`: el archivo de transcripción no se garantiza que incluya el mensaje final en el tiempo de Stop en todas las versiones.
2745 2735
2746Las matrices `background_tasks` y `session_crons` permiten que los hooks distingan "sesión hecha" de "sesión pausada esperando que el trabajo de fondo la despierte". Ambas matrices están presentes cuando el registro de tareas es accesible y están vacías cuando nada está en vuelo o programado.2736Los arrays `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". Ambos arrays están presentes cuando el registro de tareas es alcanzable y están vacíos cuando nada está en vuelo o programado.
2747 2737
2748Cada entrada en `background_tasks` describe una tarea en vuelo y usa estos campos:2738Cada entrada en `background_tasks` describe una tarea en vuelo y usa estos campos:
2749 2739
2750| Campo | Descripción |2740| Campo | Descripción |
2751| :- | :- |2741| :- | :- |
2752| `id` | Identificador de tarea |2742| `id` | Identificador de tarea |
2753| `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 |2743| `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 bruto para tipos no reconocidos |
2754| `status` | Estado actual de la tarea |2744| `status` | Estado actual de la tarea |
2755| `description` | Descripción de texto libre, limitada a 1000 caracteres con un marcador `… [+N chars]` en cadena cuando se recorta |2745| `description` | Descripción de texto libre, limitada a 1000 caracteres con un marcador `… [+N chars]` en cadena cuando se recorta |
2756| `command` | Línea de comando de shell, limitada a 1000 caracteres. Presente solo para tareas `shell` |2746| `command` | Línea de comando de shell, limitada a 1000 caracteres. Presente solo para tareas `shell` |
2765| :- | :- |2755| :- | :- |
2766| `id` | Identificador de tarea cron |2756| `id` | Identificador de tarea cron |
2767| `schedule` | Expresión cron, por ejemplo `0 9 * * 1-5` |2757| `schedule` | Expresión cron, por ejemplo `0 9 * * 1-5` |
2768| `recurring` | `false` para despertares únicos cuya programación codifica un tiempo de disparo único, `true` para tareas que se disparan nuevamente en cada coincidencia |2758| `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| `prompt` | Prompt enviado cuando se dispara el cron, limitado a 1000 caracteres con el mismo marcador `… [+N chars]` |2759| `prompt` | Prompt enviado cuando se dispara el cron, limitado a 1000 caracteres con el mismo marcador `… [+N chars]` |
2770 2760
2771Este ejemplo muestra una entrada de Stop con una tarea de shell en vuelo y un cron recurrente:2761Este ejemplo muestra una entrada de Stop con una tarea de shell en vuelo y un cron recurrente:
2803 Control de decisión de Stop2793 Control de decisión de Stop
2804</h4>2794</h4>
2805 2795
2806Los 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:2796Los 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:
2807 2797
2808| Campo | Descripción |2798| Campo | Descripción |
2809| :- | :- |2799| :- | :- |
2810| `decision` | `"block"` evita que Claude se detenga. Omita para permitir que Claude se detenga |2800| `decision` | `"block"` evita que Claude se detenga. Omite para permitir que Claude se detenga |
2811| `reason` | Requerido cuando `decision` es `"block"`. Le dice a Claude por qué debe continuar |2801| `reason` | Requerido cuando `decision` es `"block"`. Le dice a Claude por qué debe continuar |
2812| `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 |2802| `hookSpecificOutput.additionalContext` | Retroalimentación sin error para Claude. La conversación continúa para que Claude pueda actuar sobre ella, pero a diferencia de `decision: "block"` se muestra en la transcripción como retroalimentación de hook en lugar de un error de hook |
2813 2803
2820}2810}
2821```2811```
2822 2812
2823Use `additionalContext` cuando el hook está funcionando como se diseñó y dando orientación a Claude, como "ejecutar el conjunto de pruebas antes de terminar". Mantiene la conversación a través de las mismas protecciones de bucle que `decision: "block"`, es decir, la entrada `stop_hook_active` y el límite de 8 continuaciones consecutivas, pero la transcripción la etiqueta como `Stop hook feedback` y no se muestra ninguna notificación de error de hook:2813Usa `additionalContext` cuando el hook está funcionando como se diseñó y dando orientación a Claude, como "ejecuta la suite 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 ninguna notificación de error de hook:
2824 2814
2825```json theme={null}2815```json theme={null}
2826{2816{
2835 StopFailure2825 StopFailure
2836</h3>2826</h3>
2837 2827
2838Se 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 fallas, 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.2828Se 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). Úsalo 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.
2839 2829
2840<h4 id="stopfailure-input">2830<h4 id="stopfailure-input">
2841 Entrada de StopFailure2831 Entrada de StopFailure
2847| :- | :- |2837| :- | :- |
2848| `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` |2838| `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_details` | Detalles adicionales sobre el error, cuando esté disponible |2839| `error_details` | Detalles adicionales sobre el error, cuando esté disponible |
2850| `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 API en sí, como `"API Error: Rate limit reached"` |2840| `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 2841
2852```json theme={null}2842```json theme={null}
2853{2843{
2867 TeammateIdle2857 TeammateIdle
2868</h3>2858</h3>
2869 2859
2870Se 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 que pasen verificaciones de lint o verificar que existan archivos de salida.2860Se ejecuta cuando un compañero de [equipo de agentes](/docs/es/agent-teams) está a punto de quedarse inactivo después de terminar su turno. Úsalo para aplicar 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.
2871 2861
2872Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.2862Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.
2873 2863
2892| Campo | Descripción |2882| Campo | Descripción |
2893| :- | :- |2883| :- | :- |
2894| `teammate_name` | Nombre del compañero que está a punto de quedarse inactivo |2884| `teammate_name` | Nombre del compañero que está a punto de quedarse inactivo |
2895| `team_name` | Deprecado. Nombre de equipo derivado de sesión; se eliminará en una versión futura |2885| `team_name` | Deprecado. Nombre de equipo derivado de sesión; será eliminado en una versión futura |
2896 2886
2897<h4 id="teammateidle-decision-control">2887<h4 id="teammateidle-decision-control">
2898 Control de decisión de TeammateIdle2888 Control de decisión de TeammateIdle
2903* **Código de salida 2**: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.2893* **Código de salida 2**: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.
2904* **JSON `{"continue": false, "stopReason": "..."}`**: detiene completamente al compañero, coincidiendo con el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario.2894* **JSON `{"continue": false, "stopReason": "..."}`**: detiene completamente al compañero, coincidiendo con el comportamiento del hook `Stop`. El `stopReason` se muestra al usuario.
2905 2895
2906Este ejemplo verifica que existe un artefacto de compilación antes de permitir que un compañero se quede inactivo:2896Este ejemplo verifica que exista un artefacto de compilación antes de permitir que un compañero se quede inactivo:
2907 2897
2908```bash theme={null}2898```bash theme={null}
2909#!/bin/bash2899#!/bin/bash
2920 ConfigChange2910 ConfigChange
2921</h3>2911</h3>
2922 2912
2923Se ejecuta cuando un archivo de configuración cambia durante una sesión. Úselo para auditar cambios de configuración, hacer cumplir políticas de seguridad o bloquear modificaciones no autorizadas en archivos de configuración.2913Se 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 archivos de configuración.
2924 2914
2925Claude Code ejecuta hooks ConfigChange cuando un archivo de configuración, un archivo de política administrada o un archivo de skill cambia. Para política administrada, solo los ejecuta cuando `managed-settings.json` o un archivo en `managed-settings.d/` cambia. Aplica [configuración administrada por servidor](/docs/es/server-managed-settings) y cambios en preferencias administradas de macOS o política de registro de Windows sin ejecutarlos. En WSL con [`wslInheritsWindowsSettings`](/docs/es/settings-reference#wslinheritswindowssettings), también aplica un archivo de configuración administrada de Windows modificado en su sondeo de política sin ejecutarlos.2915Claude Code ejecuta hooks ConfigChange cuando un archivo de configuración, un archivo de política gestionada o un archivo de skill cambia. Para política gestionada, los ejecuta solo cuando `managed-settings.json` o un archivo en `managed-settings.d/` cambia. Aplica [configuración gestionada por servidor](/docs/es/server-managed-settings) y cambios a preferencias gestionadas 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 gestionada de Windows modificado en su sondeo de política sin ejecutarlos.
2926 2916
2927El matcher filtra en la fuente de configuración:2917El matcher filtra en la fuente de configuración:
2928 2918
2975 Control de decisión de ConfigChange2965 Control de decisión de ConfigChange
2976</h4>2966</h4>
2977 2967
2978Los 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.2968Los hooks ConfigChange pueden bloquear cambios de configuración de tomar efecto. Usa 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.
2979 2969
2980| Campo | Descripción |2970| Campo | Descripción |
2981| :- | :- |2971| :- | :- |
2982| `decision` | `"block"` evita que se aplique el cambio de configuración. Omita para permitir el cambio |2972| `decision` | `"block"` evita que se aplique el cambio de configuración. Omite para permitir el cambio |
2983| `reason` | Aceptado pero nunca mostrado |2973| `reason` | Aceptado pero nunca mostrado |
2984 2974
2985```json theme={null}2975```json theme={null}
2989}2979}
2990```2980```
2991 2981
2992Los cambios `policy_settings` no se pueden bloquear. Los hooks aún se disparan para fuentes `policy_settings` cuando un archivo de configuración administrada en la máquina cambia, para que pueda usarlos para registrar esas ediciones, pero cualquier decisión de bloqueo se ignora. Esto asegura que la configuración administrada por 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).2982Los cambios `policy_settings` no pueden ser bloqueados. Los hooks aún se disparan para fuentes `policy_settings` cuando un archivo de configuración gestionada en la máquina cambia, para que puedas usarlos para registrar esas ediciones, pero cualquier decisión de bloqueo se ignora. Esto asegura que la configuración gestionada por empresa siempre tenga efecto. Claude Code no ejecuta hooks `ConfigChange` cuando llega o se actualiza [configuración gestionada por servidor](/docs/es/server-managed-settings).
2993 2983
2994Claude 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.2984Claude Code actúa sobre la decisión de bloqueo de la salida JSON de un hook ConfigChange y descarta `systemMessage` y `continue`. Un cambio bloqueado no muestra ningún mensaje para ti o para Claude, ya sea que bloquees con `reason` o con stderr en salida 2. Claude Code solo escribe una línea en el registro de depuración.
2995 2985
2996<h3 id="cwdchanged">2986<h3 id="cwdchanged">
2997 CwdChanged2987 CwdChanged
2998</h3>2988</h3>
2999 2989
3000Se 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.2990Se 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 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 gestionan el entorno por directorio.
3001 2991
3002Los 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.2992Los 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.
3003 2993
3028 3018
3029| Campo | Descripción |3019| Campo | Descripción |
3030| :- | :- |3020| :- | :- |
3031| `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 |3021| `watchPaths` | Array de rutas absolutas. Reemplaza la lista de observación dinámica actual. Las rutas de tu configuración `matcher` siempre se observan. Devolver un array vacío borra la lista dinámica, que es típico al entrar en un nuevo directorio |
3032 3022
3033Los hooks CwdChanged no tienen control de decisión. No pueden bloquear el cambio de directorio.3023Los hooks CwdChanged no tienen control de decisión. No pueden bloquear el cambio de directorio.
3034 3024
3035Claude 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 de SDK.3025Claude 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.
3036 3026
3037<h3 id="directoryadded">3027<h3 id="directoryadded">
3038 DirectoryAdded3028 DirectoryAdded
3039</h3>3029</h3>
3040 3030
3041Se 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 de SDK agregue uno con la solicitud de control `register_repo_root`. Úselo para preparar un repositorio recién agregado, por ejemplo instalando sus dependencias.3031Se ejecuta después de que añadas un directorio de trabajo a mitad de sesión con el comando `/add-dir`, o después de que un cliente del SDK añada uno con la solicitud de control `register_repo_root`. Úsalo para preparar un repositorio recién añadido, por ejemplo instalando sus dependencias.
3042 3032
3043Claude Code no dispara este evento cuando:3033Claude Code no dispara este evento cuando:
3044 3034
3045* Pasa un directorio con la bandera de inicio `--add-dir`; [SessionStart](#sessionstart) cubre esos directorios3035* Pasas un directorio con la bandera de inicio `--add-dir`; [SessionStart](#sessionstart) cubre esos directorios
3046* Agrega un directorio en la pestaña Workspace `/permissions`3036* Añades un directorio en la pestaña Workspace `/permissions`
3047* Agrega un directorio que ya es un directorio de trabajo o está dentro de uno3037* Añades un directorio que ya es un directorio de trabajo o está dentro de uno
3048 3038
3049Claude Code 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.3039Claude Code 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 tu hook. Los comandos del hook en sí se ejecutan sin sandbox.
3050 3040
3051Claude 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.3041Claude 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.
3052 3042
3053El matcher filtra en cómo se agregó el directorio:3043El matcher filtra en cómo se añadió el directorio:
3054 3044
3055| Matcher | Cuándo se dispara |3045| Matcher | Cuándo se dispara |
3056| :- | :- |3046| :- | :- |
3057| `slash_command` | Agrega un directorio con `/add-dir` |3047| `slash_command` | Añades un directorio con `/add-dir` |
3058| `register_repo_root` | Un cliente de SDK agrega un directorio con la solicitud de control `register_repo_root` |3048| `register_repo_root` | Un cliente del SDK añade un directorio con la solicitud de control `register_repo_root` |
3059 3049
3060<h4 id="directoryadded-input">3050<h4 id="directoryadded-input">
3061 Entrada de DirectoryAdded3051 Entrada de DirectoryAdded
3065 3055
3066| Campo | Descripción |3056| Campo | Descripción |
3067| :- | :- |3057| :- | :- |
3068| `directory` | Ruta absoluta del directorio que se agregó |3058| `directory` | Ruta absoluta del directorio que se añadió |
3069| `source` | Cómo se agregó el directorio, `"slash_command"` para `/add-dir` o `"register_repo_root"` para la solicitud de control de SDK |3059| `source` | Cómo se añadió el directorio, `"slash_command"` para `/add-dir` o `"register_repo_root"` para la solicitud de control del SDK |
3070 3060
3071```json theme={null}3061```json theme={null}
3072{3062{
3081 3071
3082Los 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:3072Los 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:
3083 3073
3084* `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ón3074* `slash_command`: Claude Code entrega el `systemMessage` del hook a Claude como contexto en el siguiente turno de conversación, en lugar de mostrártelo. Un recuento de hooks fallidos aparece en la transcripción. La salida de fallo completo va al registro de depuración
3085* `register_repo_root`: Claude Code escribe la salida `systemMessage` y la salida de fallo solo en el registro de depuración3075* `register_repo_root`: Claude Code escribe la salida `systemMessage` y la salida de fallo solo en el registro de depuración
3086 3076
3087<h3 id="filechanged">3077<h3 id="filechanged">
3090 3080
3091Se 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.3081Se ejecuta cuando un archivo observado cambia en el disco. Claude Code detecta cambios con un observador del sistema de archivos, no inspeccionando llamadas de herramientas, por lo que ejecuta el hook sin importar qué cambió el archivo: una llamada de herramienta `Edit` o `Write`, un script que Claude ejecuta con `Bash`, o un proceso fuera de Claude Code completamente. Un uso común es recargar variables de entorno cuando cambian archivos de configuración del proyecto.
3092 3082
3093El `matcher` para este evento sirve dos propósitos:3083El `matcher` para este evento sirve dos roles:
3094 3084
3095* **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`.3085* **Construir la lista de observación**: el valor se divide en `|` y cada segmento se registra como un nombre de archivo literal en el directorio de trabajo, así 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* **Filtrar qué hooks se ejecutan**: cuando un archivo observado cambia, el mismo valor filtra qué grupos de hooks se ejecutan usando las [reglas de matcher](#matcher-patterns) estándar contra el nombre base del archivo cambiado.3086* **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 3087
3098Este 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:3088Este ejemplo normaliza terminaciones de línea en `data.csv` después de cualquier cambio, incluyendo un comando `Bash` o un script externo reescribiendo el archivo:
3099 3089
3100```json theme={null}3090```json theme={null}
3101{3091{
3115}3105}
3116```3106```
3117 3107
3118El 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:3108El 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, así 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. Guarda este script en `/path/to/normalize-line-endings.sh` y hazlo ejecutable:
3119 3109
3120```bash theme={null}3110```bash theme={null}
3121#!/bin/bash3111#!/bin/bash
3125fi3115fi
3126```3116```
3127 3117
3128Para 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.3118Para confirmar que el hook funciona, pídele a Claude que añada una línea CRLF a `data.csv` con un comando `Bash`. Claude Code ejecuta el hook y el archivo termina con terminaciones LF.
3129 3119
3130Para 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 comienza 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 hooks se ejecutan cuando un archivo observado cambia, así que dé al grupo que maneja rutas dinámicas un matcher omitido, que coincide con cada archivo observado y no agrega nada a la lista de observación. Un matcher `"*"` también coincide con cada archivo, pero Claude Code lo registra en la lista de observación como un archivo literal nombrado `*`.3120Para observar archivos que no puedes nombrar por adelantado, devuelve [`watchPaths`](#filechanged-output) de un hook para actualizar la lista de observación dinámicamente. Claude Code comienza el observador solo cuando algo nombra un archivo para observar, así que siembra la lista con un grupo FileChanged cuyo matcher nombra al menos un archivo, o con un hook [SessionStart](#sessionstart-decision-control) o [CwdChanged](#cwdchanged) que devuelve `watchPaths`. El matcher aún filtra qué grupos de hook se ejecutan cuando un archivo observado cambia, así que da al grupo que maneja rutas dinámicas un matcher omitido, que coincide con cada archivo observado y no añade 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 `*`.
3131 3121
3132Los 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.3122Los hooks FileChanged tienen acceso a [`CLAUDE_ENV_FILE`](#persist-environment-variables). Las variables escritas en ese archivo persisten en comandos Bash posteriores hasta el siguiente evento [CwdChanged](#cwdchanged), cuando Claude Code las borra.
3133 3123
3161 3151
3162| Campo | Descripción |3152| Campo | Descripción |
3163| :- | :- |3153| :- | :- |
3164| `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 |3154| `watchPaths` | Array de rutas absolutas. Reemplaza la lista de observación dinámica actual. Las rutas de tu configuración `matcher` siempre se observan. Úsalo cuando tu script de hook descubre archivos adicionales para observar basándose en el archivo cambiado |
3165 3155
3166Los hooks FileChanged no tienen control de decisión. No pueden bloquear el cambio de archivo que ocurre.3156Los hooks FileChanged no tienen control de decisión. No pueden bloquear el cambio de archivo de ocurrir.
3167 3157
3168Claude 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 de SDK.3158Claude 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.
3169 3159
3170<h3 id="worktreecreate">3160<h3 id="worktreecreate">
3171 WorktreeCreate3161 WorktreeCreate
3172</h3>3162</h3>
3173 3163
3174Se 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 de git predeterminado, permitiéndole usar un sistema de control de versiones diferente como SVN, Perforce o Mercurial.3164Se ejecuta cuando se está creando un worktree, ya sea desde `claude --worktree`, desde un [subagente usando `isolation: "worktree"`](/docs/es/sub-agents#choose-the-subagent-scope), o para una [sesión en segundo plano](/docs/es/agent-view#how-file-edits-are-isolated) que Claude Code aísla en su propio worktree. Por defecto Claude Code crea la copia de trabajo aislada con `git worktree`. Configurar un hook WorktreeCreate reemplaza ese comportamiento git predeterminado, permitiéndote usar un sistema de control de versiones diferente como SVN, Perforce o Mercurial.
3175 3165
3176Debido 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.3166Debido a que el hook reemplaza el comportamiento predeterminado completamente, [`.worktreeinclude`](/docs/es/worktrees#copy-gitignored-files-into-worktrees) no se procesa. Si necesitas copiar archivos de configuración local como `.env` en el nuevo worktree, hazlo dentro de tu script de hook.
3177 3167
3178El 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.3168El 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. Consulta [Salida de WorktreeCreate](#worktreecreate-output) para saber cómo cada tipo de hook devuelve la ruta.
3179 3169
3180Claude Code actúa sobre el éxito del hook y la ruta devuelta, y descarta `systemMessage` y `continue`.3170Claude Code actúa sobre el éxito del hook y la ruta devuelta, y descarta `systemMessage` y `continue`.
3181 3171
3182Este 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:3172Este ejemplo crea una copia de trabajo SVN e imprime la ruta para que Claude Code la use. Reemplaza la URL del repositorio con la tuya:
3183 3173
3184```json theme={null}3174```json theme={null}
3185{3175{
3198}3188}
3199```3189```
3200 3190
3201El 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.3191El hook lee el `name` del worktree de la entrada JSON en stdin, verifica una copia fresca en un nuevo directorio e imprime la ruta del directorio. El `echo` en la última línea es lo que Claude Code lee como la ruta del worktree. Redirige cualquier otra salida a stderr para que no interfiera con la ruta.
3202 3192
3203<h4 id="worktreecreate-input">3193<h4 id="worktreecreate-input">
3204 Entrada de WorktreeCreate3194 Entrada de WorktreeCreate
3205</h4>3195</h4>
3206 3196
3207Ademá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`.3197Ademá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 auto-generado, por ejemplo `bold-oak-a3f2`.
3208 3198
3209```json theme={null}3199```json theme={null}
3210{3200{
3222 3212
3223Los 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:3213Los 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:
3224 3214
3225* **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 de hook a stderr.3215* **Hooks de comando** (`type: "command"`): imprime 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, así que los banners de inicio de shell impresos antes de tu `echo` se ignoran. Redirige cualquier otra salida del hook a stderr.
3226* **Hooks HTTP** (`type: "http"`): devuelva `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.3216* **Hooks HTTP** (`type: "http"`): devuelve `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }` en el cuerpo de la respuesta.
3227 3217
3228Si el hook falla o no produce una ruta, la creación del worktree falla con un error.3218Si el hook falla o no produce una ruta, la creación del worktree falla con un error.
3229 3219
3230Claude 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.3220Claude 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 nombrando la ruta y sale con código 1.
3231 3221
3232Claude Code rechaza una ruta absoluta que contiene segmentos `.` o `..`, y cualquier ruta que pase a través de un symlink debajo de la raíz del repositorio, porque un symlink 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 symlink dentro del repositorio. Antes de v2.1.216, la creación del worktree seguía la ruta del hook sin este cribado.3222Claude 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. Devuelve 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.
3233 3223
3234<h3 id="worktreeremove">3224<h3 id="worktreeremove">
3235 WorktreeRemove3225 WorktreeRemove
3237 3227
3238Se ejecuta cuando se está eliminando un worktree. Este es el homólogo de limpieza de [WorktreeCreate](#worktreecreate). El evento se dispara cuando:3228Se ejecuta cuando se está eliminando un worktree. Este es el homólogo de limpieza de [WorktreeCreate](#worktreecreate). El evento se dispara cuando:
3239 3229
3240* sale de una sesión `--worktree` y elige eliminarla3230* sales de una sesión `--worktree` y eliges eliminarlo
3241* un subagente con `isolation: "worktree"` se completa3231* un subagente con `isolation: "worktree"` se completa
3242* elimina una [sesión de fondo](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook3232* eliminas una [sesión en segundo plano](/docs/es/agent-view#what-deleting-a-session-removes) cuyo worktree creó el hook
3243 3233
3244Para worktrees basados en git, Claude Code maneja la limpieza automáticamente con `git worktree remove`. Si configuró un hook WorktreeCreate para un sistema de control de versiones que no es git, emparéjelo con un hook WorktreeRemove para manejar la limpieza. Sin uno, el directorio del worktree se deja en el disco.3234Para worktrees basados en git, Claude Code maneja la limpieza automáticamente con `git worktree remove`. Si configuraste un hook WorktreeCreate para un sistema de control de versiones no git, emparéjalo con un hook WorktreeRemove para manejar la limpieza. Sin uno, el directorio del worktree se deja en el disco.
3245 3235
3246Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.3236Claude Code descarta los [campos de salida JSON](#json-output) de un hook WorktreeRemove, como `systemMessage` y `continue`.
3247 3237
3248Para 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 symlink o pasa a través de uno 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.3238Para una eliminación de sesión en segundo plano, Claude Code verifica la ruta del worktree almacenada antes de ejecutar el hook y rechaza una ruta que es un enlace simbólico o pasa a través de uno por debajo de la raíz del repositorio. El hook se ejecuta para un worktree que aún contiene archivos solo cuando confirmas 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.
3249 3239
3250Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:3240Claude Code pasa la ruta devuelta por WorktreeCreate como `worktree_path` en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:
3251 3241
3282}3272}
3283```3273```
3284 3274
3285El código de salida de un hook WorktreeRemove decide el resultado. Cuando un hook sale con código distinto de cero y el directorio en `worktree_path` aún existe después, la eliminación falla:3275El 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:
3286 3276
3287* El worktree permanece en el disco, y el comando del hook y stderr van al [registro de depuración](#debug-hooks).3277* El worktree permanece en el disco, y el comando del hook y stderr van al [registro de depuración](#debug-hooks).
3288* 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.3278* Si estabas eliminando una sesión en segundo plano, la sesión también permanece. El mensaje de rechazo en [vista de agente](/docs/es/agent-view#what-deleting-a-session-removes) reporta cómo terminó el hook, como `exited 1`, cita el inicio de su stderr, y dice si eliminar la sesión nuevamente elimina el directorio de todas formas.
3289 3279
3290<h3 id="precompact">3280<h3 id="precompact">
3291 PreCompact3281 PreCompact
3293 3283
3294Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.3284Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.
3295 3285
3296El valor del matcher indica si la compactación fue disparada manualmente o automáticamente:3286El valor del matcher indica si la compactación fue activada manualmente o automáticamente:
3297 3287
3298| Matcher | Cuándo se dispara |3288| Matcher | Cuándo se dispara |
3299| :- | :- |3289| :- | :- |
3300| `manual` | `/compact` |3290| `manual` | `/compact` |
3301| `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) |3291| `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) |
3302 3292
3303Salga 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"`.3293Sale con código 2 para bloquear la compactación. Para un `/compact` manual, el mensaje stderr se muestra al usuario. También puedes bloquear devolviendo JSON con `"decision": "block"`.
3304 3294
3305Bloquear 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.3295Bloquear compactación automática tiene diferentes efectos dependiendo de cuándo se dispare. Si la compactación fue activada 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 activada para recuperarse de un error de límite de contexto ya devuelto por la API, el error subyacente aparece y la solicitud actual falla.
3306 3296
3307Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.3297Claude Code descarta los campos `systemMessage` y `continue` de un hook PreCompact.
3308 3298
3310 Entrada de PreCompact3300 Entrada de PreCompact
3311</h4>3301</h4>
3312 3302
3313Además de los [campos de entrada comunes](#common-input-fields), los hooks PreCompact reciben `trigger` e `custom_instructions`. Para `manual`, `custom_instructions` contiene lo que el usuario pasa a `/compact` y es `null` cuando no pasa nada. Para `auto`, `custom_instructions` es `null`.3303Además de los [campos de entrada comunes](#common-input-fields), los hooks PreCompact reciben `trigger` y `custom_instructions`. Para `manual`, `custom_instructions` contiene lo que el usuario pasa a `/compact` y es `null` cuando no pasa nada. Para `auto`, `custom_instructions` es `null`.
3314 3304
3315```json theme={null}3305```json theme={null}
3316{3306{
3327 PostCompact3317 PostCompact
3328</h3>3318</h3>
3329 3319
3330Se 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.3320Se ejecuta después de que Claude Code completa una operación de compactación. Úsalo 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.
3331 3321
3332Los mismos valores de matcher se aplican que para `PreCompact`:3322Los mismos valores de matcher se aplican que para `PreCompact`:
3333 3323
3359 PreModelSwitch3349 PreModelSwitch
3360</h3>3350</h3>
3361 3351
3362Se ejecuta antes de que Claude Code aplique un cambio de modelo que solicitó usted o un cliente. Úselo para bloquear un cambio, requerir confirmación o mostrar cuánto costará el cambio antes de que suceda.3352Se ejecuta antes de que Claude Code aplique un cambio de modelo que solicitaste o un cliente solicitó. Úsalo para bloquear un cambio, requerir confirmación o mostrar cuánto costará el cambio antes de que suceda.
3363 3353
3364PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:3354PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:
3365 3355
3367* El selector de modelo `Option+P` o `Alt+P`3357* El selector de modelo `Option+P` o `Alt+P`
3368* La configuración Model en `/config`3358* La configuración Model en `/config`
3369* Activar [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión3359* Activar [modo rápido](/docs/es/fast-mode) cuando eso cambia el modelo de la sesión
3370* Una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un anfitrión [Agent SDK](/docs/es/agent-sdk/typescript#query-object) o [Control Remoto](/docs/es/remote-control)3360* 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)
3371 3361
3372Claude Code no ejecuta hooks PreModelSwitch para cambios que realiza por su cuenta, 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.3362Claude Code no ejecuta hooks PreModelSwitch para cambios que hace por su cuenta, como un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback) o restaurar el modelo cuando reanudas una sesión. Esos cambios llegan a [PostModelSwitch](#postmodelswitch) solo.
3373 3363
3374Claude 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.3364Claude 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, así que `claude-opus-5` cubre cada deletreo de Opus 5.
3375 3365
3376Cuando Claude Code no puede determinar un nombre canónico para el objetivo, por ejemplo un ID de modelo personalizado que solo su [puerta de enlace LLM](/docs/es/llm-gateway) conoce, ejecuta cada hook PreModelSwitch independientemente del matcher. Un hook que bloquea debe verificar `to_model` de su entrada en lugar de confiar solo en el matcher.3366Cuando Claude Code no puede determinar un nombre canónico para el objetivo, por ejemplo un ID de modelo personalizado que solo tu [puerta de enlace LLM](/docs/es/llm-gateway) conoce, ejecuta cada hook PreModelSwitch independientemente del matcher. Un hook que bloquea debe por lo tanto verificar `to_model` de su entrada en lugar de confiar solo en el matcher.
3377 3367
3378Escriba 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:3368Escribe 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, así que rechaza un cambio a Opus 4.6 saliendo con código 2 y permite cualquier otro objetivo:
3379 3369
3380<Tabs>3370<Tabs>
3381 <Tab title="macOS/Linux">3371 <Tab title="macOS/Linux">
3401 </Tab>3391 </Tab>
3402 3392
3403 <Tab title="Windows (PowerShell)">3393 <Tab title="Windows (PowerShell)">
3404 Registre un hook de comando que ejecute un script a través de PowerShell:3394 Registra un hook de comando que ejecute un script a través de PowerShell:
3405 3395
3406 ```json theme={null}3396 ```json theme={null}
3407 {3397 {
3428 }3418 }
3429 ```3419 ```
3430 3420
3431 Guarde este script en `.claude/hooks/block-opus-46.ps1` en su proyecto:3421 Guarda este script en `.claude/hooks/block-opus-46.ps1` en tu proyecto:
3432 3422
3433 ```powershell theme={null}3423 ```powershell theme={null}
3434 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3424 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
3441 </Tab>3431 </Tab>
3442</Tabs>3432</Tabs>
3443 3433
3444Para 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.3434Para confirmar que el hook funciona, ejecuta `/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 tu mensaje como la razón.
3445 3435
3446<h4 id="premodelswitch-input">3436<h4 id="premodelswitch-input">
3447 Entrada de PreModelSwitch3437 Entrada de PreModelSwitch
3448</h4>3438</h4>
3449 3439
3450Además de los [campos de entrada comunes](#common-input-fields), los hooks PreModelSwitch reciben los campos en esta tabla. Los últimos cinco describen qué cuesta reenviar la conversación al nuevo modelo, para que un hook pueda mostrar esa cifra antes de que suceda el cambio.3440Además de los [campos de entrada comunes](#common-input-fields), los hooks PreModelSwitch reciben los campos en esta tabla. Los últimos cinco describen cuánto cuesta reenviar la conversación al nuevo modelo, para que un hook pueda mostrar esa cifra antes de que suceda el cambio.
3451 3441
3452| Campo | Tipo | Descripción |3442| Campo | Tipo | Descripción |
3453| :- | :- | :- |3443| :- | :- | :- |
3454| `from_model` | string | ID de modelo del que cambia el cambio |3444| `from_model` | string | ID de modelo del que cambia el cambio |
3455| `to_model` | string | ID de modelo al que cambia el cambio. El matcher compara contra el nombre canónico de este modelo |3445| `to_model` | string | ID de modelo al que cambia el cambio. El matcher compara contra el nombre canónico de este modelo |
3456| `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 |3446| `requested_model` | string o `null` | El modelo que la solicitud nombró: un alias como `opus`, un ID de modelo completo, o `null` cuando la solicitud fue para el modelo predeterminado |
3457| `source` | string | De dónde vino la solicitud: `"command"` para `/model <name>`, la configuración Model en `/config`, o activar modo rápido; `"picker"` para un selector de modelo; `"sdk"` para una solicitud `set_model`, o un cambio de modelo en una solicitud `apply_flag_settings`, desde un anfitrión Agent SDK o Control Remoto |3447| `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 |
3458| `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 |3448| `context_tokens` | number | Tokens que la siguiente solicitud reenvía como su prompt: los tokens de entrada, lectura de caché, creación de caché y salida de la última respuesta en la conversación principal, combinados. `0` antes de la primera respuesta |
3459| `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 |3449| `prompt_cache_warm` | boolean | Si el caché de prompt del modelo actual probablemente aún está caliente, lo que significa que el cambio lo pierde |
3460| `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"` |3450| `cache_ttl` | string | [Duración del caché de prompt](/docs/es/prompt-caching#cache-lifetime) que Claude Code solicita para esta sesión: `"5m"` o `"1h"` |
3461| `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 |3451| `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átalo como una estimación |
3462| `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 |3452| `pricing` | string | Cómo Claude Code fijó el precio de `estimated_cache_write_usd`: `"configured"` a tus propias tasas de la organización cuando las ha configurado, `"catalog"` a precio de lista, o `"default"` cuando `to_model` no tiene precio conocido y Claude Code asumió una tasa predeterminada |
3463 3453
3464Este ejemplo muestra la entrada para `/model opus` en una sesión que ejecuta Sonnet 5:3454Este ejemplo muestra la entrada para `/model opus` en una sesión que ejecuta Sonnet 5:
3465 3455
3487 3477
3488Los 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.3478Los 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.
3489 3479
3490Para un control más fino, devuelva `permissionDecision` y `permissionDecisionReason` en un objeto `hookSpecificOutput`, como en [PreToolUse](#pretooluse-decision-control). `PreModelSwitch` acepta `"allow"`, `"deny"`, y `"ask"`. No acepta `"defer"`, `updatedInput`, o `additionalContext`. La tabla a continuación describe ambos campos:3480Para control más fino, devuelve `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:
3491 3481
3492| Campo | Descripción |3482| Campo | Descripción |
3493| :- | :- |3483| :- | :- |
3494| `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 |3484| `permissionDecision` | `"allow"` continúa y omite la [confirmación que Claude Code muestra mientras el caché de prompt está caliente](/docs/es/prompt-caching#switching-models). `"deny"` cancela el cambio. `"ask"` solicita al usuario que lo confirme |
3495| `permissionDecisionReason` | Para `"deny"`, se muestra al usuario como la razón por la que se bloqueó el cambio, o se devuelve como el error para una solicitud `set_model`. Para `"ask"`, se muestra en el aviso de confirmación. Se ignora para `"allow"` |3485| `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"` |
3496 3486
3497Solo `/model` en una sesión interactiva puede mostrar el aviso `"ask"`. En todas las otras superficies, incluido modo no interactivo con la bandera `-p`, `/config`, y solicitudes `set_model`, Claude Code trata `"ask"` como un rechazo.3487Solo `/model` en una sesión interactiva puede mostrar el prompt `"ask"`. En cada otra superficie, incluyendo modo no interactivo con la bandera `-p`, `/config`, y solicitudes `set_model`, Claude Code trata `"ask"` como un rechazo.
3498 3488
3499Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:3489Este ejemplo pide al usuario que confirme y cita el recuento de tokens de `context_tokens`:
3500 3490
3510 3500
3511Cuando múltiples hooks PreModelSwitch devuelven decisiones diferentes, la precedencia es `deny` > `ask` > `allow`.3501Cuando múltiples hooks PreModelSwitch devuelven decisiones diferentes, la precedencia es `deny` > `ask` > `allow`.
3512 3502
3513Claude Code muestra al usuario cualquier `systemMessage` que devuelva su hook independientemente de la decisión, por lo que un hook de informe de costos puede devolver `{"systemMessage": "..."}` y salir con 0.3503Claude Code muestra al usuario cualquier `systemMessage` que devuelva tu hook independientemente de la decisión, así que un hook de informe de costos puede devolver `{"systemMessage": "..."}` y salir 0.
3514 3504
3515Un 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.3505Un 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`, así que los valores predeterminados `prompt` y `agent` no se aplican.
3516 3506
3517Un hook que sale con un código distinto de 0 o 2 y no imprime ninguna decisión JSON no bloquea: Claude Code muestra su stderr y aplica el cambio, como se describe en [Otros códigos de salida](#other-exit-codes).3507Un hook que sale con un código distinto de 0 o 2 y no imprime ninguna decisión JSON no bloquea: Claude Code muestra su stderr y aplica el cambio, como se describe en [Otros códigos de salida](#other-exit-codes).
3518 3508
3520 PostModelSwitch3510 PostModelSwitch
3521</h3>3511</h3>
3522 3512
3523Se ejecuta después de que cambia el modelo de la sesión. Ú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.3513Se ejecuta después de que el modelo de la sesión cambia. Úsalo 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.
3524 3514
3525PostModelSwitch 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:3515PostModelSwitch 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:
3526 3516
3527* Un cambio que solicitó usted o un cliente3517* Un cambio que solicitaste o un cliente solicitó
3528* Un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión3518* Un [fallback de modelo automático](/docs/es/model-config#automatic-model-fallback), que cambia el modelo de la sesión
3529* Una configuración como [`opusplan`](/docs/es/model-config#opusplan-model-setting) entrando o saliendo del modo de plan3519* Una configuración como [`opusplan`](/docs/es/model-config#opusplan-model-setting) entrando o saliendo del modo plan
3530* Claude Code restaurando el modelo cuando reanuda una sesión3520* Claude Code restaurando el modelo cuando reanudas una sesión
3531 3521
3532Claude 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.3522Claude 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.
3533 3523
3534El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.3524El matcher sigue las mismas reglas que [PreModelSwitch](#premodelswitch): Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.
3535 3525
3536Este ejemplo agrega orientación siempre que el modelo de la sesión cambia a cualquier modelo Opus:3526Este ejemplo añade orientación siempre que el modelo de la sesión cambia a cualquier modelo Opus:
3537 3527
3538```json theme={null}3528```json theme={null}
3539{3529{
3553}3543}
3554```3544```
3555 3545
3556Para 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.3546Para confirmar que el hook funciona, cambia a un modelo Opus desde una sesión que ejecuta un modelo diferente, por ejemplo ejecuta `/model opus` desde una sesión Sonnet, luego pregúntale a Claude qué orientación tiene sobre el modelo actual.
3557 3547
3558<h4 id="postmodelswitch-input">3548<h4 id="postmodelswitch-input">
3559 Entrada de PostModelSwitch3549 Entrada de PostModelSwitch
3560</h4>3550</h4>
3561 3551
3562Los 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 realizó por su cuenta, y `"resume"` para el modelo restaurado cuando reanuda una sesión.3552Los 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 su cuenta, y `"resume"` para el modelo restaurado cuando reanudas una sesión.
3563 3553
3564`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es la configuración de modelo guardada que Claude Code restauró.3554`requested_model` es `null` cuando `source` es `"auto"`. Cuando `source` es `"resume"`, es la configuración de modelo guardada que Claude Code restauró.
3565 3555
3567 Control de decisión de PostModelSwitch3557 Control de decisión de PostModelSwitch
3568</h4>3558</h4>
3569 3559
3570Claude Code toma su stdout de texto plano del hook [](#exit-code-0) 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:3560Claude Code toma tu stdout de texto plano 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, puedes devolver:
3571 3561
3572| Campo | Descripción |3562| Campo | Descripción |
3573| :- | :- |3563| :- | :- |
3574| `additionalContext` | Cadena agregada al contexto de Claude con la siguiente solicitud. Consulte [Agregar contexto para Claude](#add-context-for-claude) |3564| `additionalContext` | Cadena añadida al contexto de Claude con la siguiente solicitud. Consulta [Añadir contexto para Claude](#add-context-for-claude) |
3575 3565
3576Si el hook no se ha completado dentro de cinco segundos después de que envía la siguiente solicitud, Claude Code envía esa solicitud sin la salida y la adjunta a la siguiente solicitud en su lugar. Si el modelo cambia varias veces antes de la siguiente solicitud, Claude Code entrega solo la salida para el modelo de destino del último cambio.3566Si el hook no se ha completado dentro de cinco segundos después de que envíes 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.
3577 3567
3578<h3 id="sessionend">3568<h3 id="sessionend">
3579 SessionEnd3569 SessionEnd
3580</h3>3570</h3>
3581 3571
3582Se 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 sesión. Admite matchers para filtrar por razón de salida.3572Se ejecuta cuando termina una sesión de Claude Code. Útil para tareas de limpieza, registrar estadísticas de sesión o guardar estado de sesión. Admite matchers para filtrar por razón de salida.
3583 3573
3584El campo `reason` en la entrada del hook indica por qué terminó la sesión:3574El campo `reason` en la entrada del hook indica por qué terminó la sesión:
3585 3575
3590| `logout` | Usuario cerró sesión |3580| `logout` | Usuario cerró sesión |
3591| `prompt_input_exit` | Usuario salió mientras la entrada de prompt era visible |3581| `prompt_input_exit` | Usuario salió mientras la entrada de prompt era visible |
3592| `other` | Otras razones de salida |3582| `other` | Otras razones de salida |
3593| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Elimine de sus matchers `SessionEnd` |3583| `bypass_permissions_disabled` | Eliminado en v2.1.234; Claude Code no lo envía. Elimina de tus matchers `SessionEnd` |
3594 3584
3595<h4 id="sessionend-input">3585<h4 id="sessionend-input">
3596 Entrada de SessionEnd3586 Entrada de SessionEnd
3597</h4>3587</h4>
3598 3588
3599Ademá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.3589Además de los [campos de entrada comunes](#common-input-fields), los hooks SessionEnd reciben un campo `reason` indicando por qué terminó la sesión. Consulta la [tabla de razones](#sessionend) anterior para todos los valores.
3600 3590
3601```json theme={null}3591```json theme={null}
3602{3592{
3608}3598}
3609```3599```
3610 3600
3611Los 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`.3601Los hooks SessionEnd no tienen control de decisión. No pueden bloquear la terminación de sesión pero pueden realizar tareas de limpieza. Claude Code descarta sus [campos de salida JSON](#json-output), como `systemMessage`.
3612 3602
3613Los hooks SessionEnd tienen un tiempo de espera predeterminado de 1.5 segundos. Se aplica cuando sale, ejecuta `/clear`, o cambia sesiones con `/resume` interactivo. Puede dar a un hook más tiempo de dos formas:3603Los hooks SessionEnd tienen un tiempo de espera predeterminado de 1.5 segundos. Se aplica cuando sales, ejecutas `/clear`, o cambias sesiones con `/resume` interactivo. Puedes dar a un hook más tiempo de dos formas:
3614 3604
3615* **`timeout` por hook**: establezca `timeout` en la configuración de ese hook. El presupuesto general se eleva automáticamente para coincidir con el `timeout` por hook más alto en sus archivos de configuración, hasta 60 segundos. Si eleva el presupuesto de esta manera, un hook sin su propio `timeout` aún mantiene el predeterminado. Los tiempos de espera establecidos en hooks proporcionados por plugins no elevan el presupuesto.3605* **`timeout` por hook**: establece `timeout` en la configuración de ese hook. El presupuesto general sube automáticamente para coincidir con el `timeout` por hook más alto en tus archivos de configuración, hasta 60 segundos. Si subes 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 suben el presupuesto.
3616* **`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`.3606* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**: establece esta variable de entorno en milisegundos para anular el presupuesto explícitamente. El valor que estableces también se convierte en el tiempo de espera para cada hook sin su propio `timeout`.
3617 3607
3618Este ejemplo establece el presupuesto en 5 segundos:3608Este ejemplo establece el presupuesto a 5 segundos:
3619 3609
3620```bash theme={null}3610```bash theme={null}
3621CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3611CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude
3622```3612```
3623 3613
3624Antes de v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` solo elevaba el presupuesto general, y un hook sin su propio `timeout` aún se cancelaba después de 1.5 segundos.3614Antes de v2.1.268, `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` solo subía el presupuesto general, y un hook sin su propio `timeout` aún se cancelaba después de 1.5 segundos.
3625 3615
3626<h3 id="elicitation">3616<h3 id="elicitation">
3627 Elicitation3617 Elicitation
3628</h3>3618</h3>
3629 3619
3630Se 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.3620Se ejecuta cuando un servidor MCP solicita entrada del usuario a mitad de tarea. Por defecto, 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.
3631 3621
3632El campo matcher coincide contra el nombre del servidor MCP.3622El campo matcher coincide contra el nombre del servidor MCP.
3633 3623
3637 3627
3638Ademá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`.3628Ademá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`.
3639 3629
3640Para elicitación de modo de formulario, el caso más común:3630Para elicitación de modo formulario, el caso más común:
3641 3631
3642```json theme={null}3632```json theme={null}
3643{3633{
3676 Salida de Elicitation3666 Salida de Elicitation
3677</h4>3667</h4>
3678 3668
3679Para responder programáticamente sin mostrar el diálogo, devuelva un objeto JSON con `hookSpecificOutput`:3669Para responder programáticamente sin mostrar el diálogo, devuelve un objeto JSON con `hookSpecificOutput`:
3680 3670
3681```json theme={null}3671```json theme={null}
3682{3672{
3695| `action` | `accept`, `decline`, `cancel` | Si aceptar, rechazar o cancelar la solicitud |3685| `action` | `accept`, `decline`, `cancel` | Si aceptar, rechazar o cancelar la solicitud |
3696| `content` | object | Valores de campo de formulario a enviar. Solo se usa cuando `action` es `accept` |3686| `content` | object | Valores de campo de formulario a enviar. Solo se usa cuando `action` es `accept` |
3697 3687
3698El código de salida 2 deniega la elicitación. Claude Code no muestra su mensaje stderr en ningún lugar.3688El código de salida 2 niega la elicitación. Claude Code no muestra tu mensaje stderr en ningún lugar.
3699 3689
3700Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook Elicitation y descarta `systemMessage` y `continue`.3690Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook Elicitation y descarta `systemMessage` y `continue`.
3701 3691
3703 ElicitationResult3693 ElicitationResult
3704</h3>3694</h3>
3705 3695
3706Se 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.3696Se ejecuta después de que un usuario responda a una elicitación de MCP. Los hooks pueden observar, modificar o bloquear la respuesta antes de que se devuelva al servidor MCP.
3707 3697
3708El campo matcher coincide contra el nombre del servidor MCP.3698El campo matcher coincide contra el nombre del servidor MCP.
3709 3699
3731 Salida de ElicitationResult3721 Salida de ElicitationResult
3732</h4>3722</h4>
3733 3723
3734Para anular la respuesta del usuario, devuelva un objeto JSON con `hookSpecificOutput`:3724Para anular la respuesta del usuario, devuelve un objeto JSON con `hookSpecificOutput`:
3735 3725
3736```json theme={null}3726```json theme={null}
3737{3727{
3746| Campo | Valores | Descripción |3736| Campo | Valores | Descripción |
3747| :- | :- | :- |3737| :- | :- | :- |
3748| `action` | `accept`, `decline`, `cancel` | Anula la acción del usuario |3738| `action` | `accept`, `decline`, `cancel` | Anula la acción del usuario |
3749| `content` | object | Anula los valores del campo de formulario. Solo significativo cuando `action` es `accept` |3739| `content` | object | Anula valores de campo de formulario. Solo significativo cuando `action` es `accept` |
3750 3740
3751El 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.3741El código de salida 2 bloquea la respuesta, cambiando la acción efectiva a `decline`. Claude Code no muestra tu mensaje stderr en ningún lugar.
3752 3742
3753Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook ElicitationResult y descarta `systemMessage` y `continue`.3743Claude Code actúa sobre `hookSpecificOutput` de la salida JSON de un hook ElicitationResult y descarta `systemMessage` y `continue`.
3754 3744
3804 3794
3805En lugar de ejecutar un comando Bash, los hooks basados en prompts:3795En lugar de ejecutar un comando Bash, los hooks basados en prompts:
3806 3796
38071. Envían la entrada del hook y su prompt a un modelo Claude, Haiku por defecto37971. Envían la entrada del hook y su prompt a un modelo Claude, por defecto el que Claude Code usa para [funcionalidad en segundo plano](/docs/es/costs#background-token-usage)
38082. El LLM responde con JSON estructurado que contiene una decisión37982. El LLM responde con JSON estructurado que contiene una decisión
38093. Claude Code procesa la decisión automáticamente37993. Claude Code procesa la decisión automáticamente
3810 3800
3837| :- | :- | :- |3827| :- | :- | :- |
3838| `type` | sí | Debe ser `"prompt"` |3828| `type` | sí | Debe ser `"prompt"` |
3839| `prompt` | sí | El texto del prompt a enviar al LLM. Use `$ARGUMENTS` como marcador de posición para la entrada JSON del hook. Si `$ARGUMENTS` no está presente, la entrada JSON se agrega al prompt |3829| `prompt` | sí | El texto del prompt a enviar al LLM. Use `$ARGUMENTS` como marcador de posición para la entrada JSON del hook. Si `$ARGUMENTS` no está presente, la entrada JSON se agrega al prompt |
3840| `model` | no | Modelo a usar para evaluación. Por defecto es un modelo rápido |3830| `model` | no | Modelo a usar para evaluación. Por defecto es el modelo que Claude Code usa para [funcionalidad en segundo plano](/docs/es/costs#background-token-usage) |
3841| `timeout` | no | Tiempo de espera en segundos. Predeterminado: 30 |3831| `timeout` | no | Tiempo de espera en segundos. Predeterminado: 30 |
3842| `continueOnBlock` | no | En los eventos a los que se aplica, `true` retroalimenta una razón `ok: false` a Claude y continúa en lugar de terminar el turno. Predeterminado: `false`. Consulte [Esquema de respuesta](#response-schema) para el comportamiento por evento |3832| `continueOnBlock` | no | En los eventos a los que se aplica, `true` retroalimenta una razón `ok: false` a Claude y continúa en lugar de terminar el turno. Predeterminado: `false`. Consulte [Esquema de respuesta](#response-schema) para el comportamiento por evento |
3843 3833
