En modo no interactivo con la bandera -p, Claude Code ofrece AskUserQuestion y ExitPlanMode solo cuando la ejecución tiene un anfitrión de permiso 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 que asigne el texto de cada pregunta a la respuesta elegida.

A partir de v2.1.199, una herramienta MCP cuyo servidor la marca con _meta["anthropic/requiresUserInteraction"] 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.

Diferir una llamada de herramienta para más tarde

"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 con la bandera -p. En sesiones interactivas registra una advertencia e ignora el resultado del hook.

La 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, 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í:

1. Claude llama a AskUserQuestion. Se dispara el hook PreToolUse.
2. 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.
3. 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.
4. 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.
5. El hook devuelve permissionDecision: "allow" con la respuesta en updatedInput. La herramienta se ejecuta y Claude continúa.

El 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:

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

No 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, que elimina archivos de sesión después de 30 días de forma predeterminada, siguiendo las reglas de barrido de retención. 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.

"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.

Si 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ó.

PermissionRequest

Se 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, Claude Code aún ejecuta estos hooks, y si ningún hook devuelve una decisión, deniega la llamada de herramienta. Use control de decisión PermissionRequest para permitir o denegar en nombre del usuario.

Use 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 con el tipo permission_prompt solo después de que el aviso ha esperado aproximadamente seis segundos.

Claude Code no ejecuta hooks PermissionRequest para la solicitud de red de un comando en sandbox. Para obtener una señal para ese aviso, use el tipo de notificación permission_prompt.

Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.

Entrada de PermissionRequest

Los 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. Una matriz permission_suggestions opcional contiene las actualizaciones de permiso que Claude Code sugiere para esta solicitud, como agregar una regla de permiso o cambiar el modo de permiso.

La 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 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, que cambia el modo de permiso directamente en lugar de a través de una actualización de permiso.

Los 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.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

Control de decisión de PermissionRequest

Los hooks PermissionRequest pueden permitir o denegar solicitudes de permiso. Además de los campos de salida JSON disponibles para todos los hooks, su script de hook puede devolver un objeto decision con estos campos específicos del evento:

Un 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.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Entradas de actualización de permiso

El campo de salida updatedPermissions y el campo de entrada permission_suggestions 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.

El campo destination en cada entrada determina si el cambio permanece en memoria o persiste en un archivo de configuración.

Un hook puede devolver una de las permission_suggestions que recibió como su propia salida updatedPermissions.

PostToolUse

Se ejecuta inmediatamente después de que una herramienta se completa exitosamente.

Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.

Coincida más ampliamente cuando el nombre de la herramienta no es el filtro correcto:

• 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.
• Para ejecutar un hook cuando un archivo específico cambia en el disco, sin importar qué lo escribió, use 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.

Entrada de PostToolUse

Los 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: 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.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

Control de decisión de PostToolUse

Los 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 disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:

El 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:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

Anotar un resultado para el clasificador de modo automático

Devuelva classifierContext para enviar una nota breve sobre el resultado de la llamada de herramienta al clasificador de modo automático en lugar de a Claude. El clasificador nunca recibe resultados de herramientas en sí, 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.

El ejemplo a continuación dice al clasificador de dónde vino la salida de una consulta:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

Cuánto peso da el clasificador a la nota depende de dónde configuró el hook:

• 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ón
• 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 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 verificado

Claude Code aplica estos límites al entregar la nota:

• 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
• Solo respuestas sincrónicas: Claude Code ignora el campo en la respuesta de un hook que se ejecuta en segundo plano, porque esa respuesta llega después de que Claude Code registra el resultado de la herramienta
• 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
• 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 salida

PostToolUseFailure

Se 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.

Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.

Entrada de PostToolUseFailure

Los 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. Por ejemplo, un comando npm test fallido podría entregar:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

La 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.

• 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
• 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í
• 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

Control de decisión de PostToolUseFailure

Los hooks PostToolUseFailure pueden proporcionar contexto a Claude después de un fallo de herramienta. Además de los campos de salida JSON disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

Se 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.

Entrada de PostToolBatch

Además de los campos de entrada comunes, los hooks PostToolBatch reciben tool_calls, una matriz que describe cada llamada de herramienta en el lote:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

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.

Control de decisión de PostToolBatch

Los hooks PostToolBatch pueden inyectar contexto para Claude. Además de los campos de salida JSON disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Devolver 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.

PermissionDenied

Se ejecuta cuando modo automático 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 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.

Coincide en el nombre de la herramienta, los mismos valores que PreToolUse.

Entrada de PermissionDenied

Además de los campos de entrada comunes, los hooks PermissionDenied reciben tool_name, tool_input, tool_use_id, y reason. Para una herramienta MCP, también reciben el objeto mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

Control de decisión de PermissionDenied

Los hooks PermissionDenied pueden decirle al modelo que puede reintentar la llamada de herramienta denegada. Devuelva un objeto JSON con hookSpecificOutput.retry establecido en true:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Cuando 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.

Claude Code ignora retry: true cuando el clasificador produjo ningún veredicto sobre la acción: 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.

Notification

Se 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.

Recibe 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.

Los tipos agent_needs_input y agent_completed requieren Claude Code v2.1.198 o posterior.

Los tipos quota_auto_resume_fired, quota_auto_resume_stale, y quota_auto_resume_disabled requieren Claude Code v2.1.234 o posterior.

En sesiones de terminal, permission_prompt para una solicitud de red de un comando en sandbox requiere Claude Code v2.1.246 o posterior.

agent_needs_input para una pregunta de configuración de terminal de compañero requiere Claude Code v2.1.248 o posterior.

Claude Code cronometra permission_prompt diferente en sesiones donde envía solicitudes de permiso a la devolución de llamada canUseTool de Agent SDK, que es cómo Claude Desktop y la extensión VS Code alojan Claude Code:

• Espere permission_prompt aproximadamente seis segundos después de que Claude solicita permiso. Claude Code no lo difiere mientras escribe.
• Si usted o un hook PermissionRequest responden antes, Claude Code no ejecuta permission_prompt.
• Establezca CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS en 1 para desactivar permission_prompt en estas sesiones.

Antes de v2.1.233, permission_prompt no se disparaba en estas sesiones.

Use 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:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Entrada de Notification

Además de los campos de entrada comunes, los hooks Notification reciben message con el texto de notificación, un title opcional, y notification_type que indica qué tipo se disparó.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Los hooks Notification no pueden bloquear o modificar notificaciones. Claude Code descarta sus campos systemMessage y continue pero aún emite terminalSequence, 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.

SubagentStart

Se ejecuta cuando Claude genera un subagente con la herramienta Agent, cuando Claude reanuda un subagente, y cada vez que un compañero de equipo de agente 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, este es el campo name del frontmatter del agente, no el nombre del archivo.

Para subagentes enviados por un plugin, 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$.

Entrada de SubagentStart

Además de los campos de entrada comunes, los hooks SubagentStart reciben agent_id con el identificador único para el subagente y agent_type con el nombre del agente que el matcher filtra.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Los 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 disponibles para todos los hooks, puede devolver:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Cuando 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 del subagente intacto. Después de que la compactación automática descarta esa copia, Claude Code inyecta el contexto de la siguiente ejecución nuevamente.

SubagentStop

Se ejecuta cuando un subagente de Claude Code ha terminado de responder. Coincide en el tipo de agente, los mismos valores que SubagentStart.

Entrada de SubagentStop

Además de los campos de entrada comunes, los hooks SubagentStop reciben stop_hook_active, agent_id, agent_type, agent_transcript_path, y last_assistant_message. El campo agent_type es el valor utilizado para filtrado de matcher. El transcript_path es la transcripción de la sesión principal, mientras que agent_transcript_path es la propia transcripción del subagente almacenada en una carpeta subagents/ anidada. El campo last_assistant_message contiene el contenido de texto de la respuesta final del subagente, por lo que los hooks pueden acceder a él sin analizar el archivo de transcripción.

En Claude Code v2.1.271 o posterior, un subagente que se ejecuta con la herramienta SubagentHandback 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.

Los hooks SubagentStop también reciben las matrices background_tasks y session_crons descritas en Entrada de Stop. Ambas matrices tienen alcance a la sesión padre, no al subagente.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

Los hooks SubagentStop usan el mismo formato de control de decisión que hooks Stop, 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 en la herramienta Agent en su lugar.

TaskCreated

Se 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, este evento no se dispara.

Los hooks TaskCreated no admiten matchers y se disparan en cada ocurrencia.

Entrada de TaskCreated

Además de los campos de entrada comunes, los hooks TaskCreated reciben task_id, task_subject, y opcionalmente task_description, teammate_name, y team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Control de decisión de TaskCreated

Un 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.

• Código de salida 2: Claude Code devuelve el texto stderr como el mensaje.
• JSON {"decision": "block", "reason": "..."}: Claude Code devuelve reason como el mensaje.

Este ejemplo bloquea tareas cuyos asuntos no siguen el formato requerido:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

Se 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 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.

Los hooks TaskCompleted no admiten matchers y se disparan en cada ocurrencia.

Entrada de TaskCompleted

Además de los campos de entrada comunes, los hooks TaskCompleted reciben task_id, task_subject, y opcionalmente task_description, teammate_name, y team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

Control de decisión de TaskCompleted

Los hooks TaskCompleted admiten dos formas de controlar la finalización de tareas:

• Código de salida 2: la tarea no se marca como completada y el mensaje stderr se devuelve al modelo como retroalimentación.
• 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.

Este ejemplo ejecuta pruebas y bloquea la finalización de tareas si fallan:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

Se 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 en su lugar.

Entrada de Stop

Además de los campos de entrada comunes, 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.

El 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.

Las 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.

Cada entrada en background_tasks describe una tarea en vuelo y usa estos campos:

Cada entrada en session_crons describe un despertar programado con alcance de sesión, originado de CronCreate, ScheduleWakeup, y /loop:

Este ejemplo muestra una entrada de Stop con una tarea de shell en vuelo y un cron recurrente:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Control de decisión de Stop

Los hooks Stop y SubagentStop pueden controlar si Claude continúa. Además de los campos de salida JSON disponibles para todos los hooks, su script de hook puede devolver estos campos específicos del evento:

Un hook que bloquea saliendo con 2 se enruta de la misma manera que reason: Claude recibe el mensaje stderr como la explicación de por qué debe continuar.

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

Use 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:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

Se ejecuta en lugar de 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. Ú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.

Entrada de StopFailure

Además de los campos de entrada comunes, los hooks StopFailure reciben error, error_details opcional, y last_assistant_message opcional. El campo error identifica el tipo de error y se utiliza para filtrado de matcher.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

Los hooks StopFailure no tienen control de decisión. Se ejecutan solo con fines de notificación y registro.

TeammateIdle

Se ejecuta cuando un compañero de equipo de agente 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.

Los hooks TeammateIdle no admiten matchers y se disparan en cada ocurrencia.

Entrada de TeammateIdle

Además de los campos de entrada comunes, los hooks TeammateIdle reciben teammate_name y team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

Control de decisión de TeammateIdle

Los hooks TeammateIdle admiten dos formas de controlar el comportamiento del compañero:

• Código de salida 2: el compañero recibe el mensaje stderr como retroalimentación y continúa trabajando en lugar de quedarse inactivo.
• JSON {"continue": false, "stopReason": "..."}: detiene completamente al compañero, coincidiendo con el comportamiento del hook Stop. El stopReason se muestra al usuario.

Este ejemplo verifica que existe un artefacto de compilación antes de permitir que un compañero se quede inactivo:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

Se 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.

Claude 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 y cambios en preferencias administradas de macOS o política de registro de Windows sin ejecutarlos. En WSL con wslInheritsWindowsSettings, también aplica un archivo de configuración administrada de Windows modificado en su sondeo de política sin ejecutarlos.

El matcher filtra en la fuente de configuración:

Este ejemplo registra todos los cambios de configuración para auditoría de seguridad:

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

Entrada de ConfigChange

Además de los campos de entrada comunes, los hooks ConfigChange reciben source y opcionalmente file_path. El campo source indica qué tipo de configuración cambió, y file_path proporciona la ruta al archivo específico que se modificó.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

Control de decisión de ConfigChange

Los 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.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

Los 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.

Claude 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.

CwdChanged

Se 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 para herramientas como direnv que administran el entorno por directorio.

Los hooks CwdChanged tienen acceso a CLAUDE_ENV_FILE. Las variables escritas en ese archivo persisten en comandos Bash posteriores hasta el siguiente evento CwdChanged, cuando Claude Code las borra.

CwdChanged no admite matchers y se dispara en cada ocurrencia.

Entrada de CwdChanged

Además de los campos de entrada comunes, los hooks CwdChanged reciben old_cwd y new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

Salida de CwdChanged

Además de los campos de salida JSON disponibles para todos los hooks, los hooks CwdChanged pueden devolver watchPaths para establecer dinámicamente qué rutas de archivo FileChanged observa:

Los hooks CwdChanged no tienen control de decisión. No pueden bloquear el cambio de directorio.

Claude 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.

DirectoryAdded

Se 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.

Claude Code no dispara este evento cuando:

• Pasa un directorio con la bandera de inicio --add-dir; SessionStart cubre esos directorios
• Agrega un directorio en la pestaña Workspace /permissions
• Agrega un directorio que ya es un directorio de trabajo o está dentro de uno

Claude 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.

Claude 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.

El matcher filtra en cómo se agregó el directorio:

Entrada de DirectoryAdded

Además de los campos de entrada comunes, los hooks DirectoryAdded reciben directory y source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

Los 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:

• 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ón
• register_repo_root: Claude Code escribe la salida systemMessage y la salida de fallo solo en el registro de depuración

FileChanged

Se 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.

El matcher para este evento sirve dos propósitos:

• 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.
• 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 estándar contra el nombre base del archivo cambiado.

Este 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:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

El hook lee la ruta absoluta del archivo cambiado del campo file_path de la entrada JSON 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:

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Para 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.

Para observar archivos que no puede nombrar por adelantado, devuelva watchPaths 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 o 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 *.

Los hooks FileChanged tienen acceso a CLAUDE_ENV_FILE. Las variables escritas en ese archivo persisten en comandos Bash posteriores hasta el siguiente evento CwdChanged, cuando Claude Code las borra.

Entrada de FileChanged

Además de los campos de entrada comunes, los hooks FileChanged reciben file_path y event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

Salida de FileChanged

Además de los campos de salida JSON disponibles para todos los hooks, los hooks FileChanged pueden devolver watchPaths para actualizar dinámicamente qué rutas de archivo se observan:

Los hooks FileChanged no tienen control de decisión. No pueden bloquear el cambio de archivo que ocurre.

Claude 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.

WorktreeCreate

Se ejecuta cuando se está creando un worktree, ya sea desde claude --worktree, desde un subagente usando isolation: "worktree", o para una sesión de fondo 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.

Debido a que el hook reemplaza el comportamiento predeterminado completamente, .worktreeinclude 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.

El 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 para saber cómo cada tipo de hook devuelve la ruta.

Claude Code actúa sobre el éxito del hook y la ruta devuelta, y descarta systemMessage y continue.

Este 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:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

El 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.

Entrada de WorktreeCreate

Además de los campos de entrada comunes, 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.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

Salida de WorktreeCreate

Los 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:

• 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.
• Hooks HTTP (type: "http"): devuelva { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } en el cuerpo de la respuesta.

Si el hook falla o no produce una ruta, la creación del worktree falla con un error.

Claude 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.

Claude 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.

WorktreeRemove

Se ejecuta cuando se está eliminando un worktree. Este es el homólogo de limpieza de WorktreeCreate. El evento se dispara cuando:

• sale de una sesión --worktree y elige eliminarla
• un subagente con isolation: "worktree" se completa
• elimina una sesión de fondo cuyo worktree creó el hook

Para 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.

Claude Code descarta los campos de salida JSON de un hook WorktreeRemove, como systemMessage y continue.

Para 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; para tal worktree, claude rm 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.

Claude Code pasa la ruta devuelta por WorktreeCreate como worktree_path en la entrada del hook. Este ejemplo lee esa ruta y elimina el directorio:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

Entrada de WorktreeRemove

Además de los campos de entrada comunes, los hooks WorktreeRemove reciben el campo worktree_path, que es la ruta absoluta al worktree que se está eliminando.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

El 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:

• El worktree permanece en el disco, y el comando del hook y stderr van al registro de depuración.
• Si estaba eliminando una sesión de fondo, la sesión también permanece. El mensaje de rechazo en vista de agente 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.

PreCompact

Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.

El valor del matcher indica si la compactación fue disparada manualmente o automáticamente:

Salga 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".

Bloquear 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.

Claude Code descarta los campos systemMessage y continue de un hook PreCompact.

Entrada de PreCompact

Además de los campos de entrada comunes, 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.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": null
}

PostCompact

Se 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.

Los mismos valores de matcher se aplican que para PreCompact:

Entrada de PostCompact

Además de los campos de entrada comunes, los hooks PostCompact reciben trigger y compact_summary. El campo compact_summary contiene el resumen de conversación generado por la operación de compactación.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

Los hooks PostCompact no tienen control de decisión. No pueden afectar el resultado de la compactación pero pueden realizar tareas de seguimiento.

PreModelSwitch

Se 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.

PreModelSwitch requiere Claude Code v2.1.251 o posterior. Claude Code lo ejecuta para estas solicitudes:

• /model <name> y el selector /model
• El selector de modelo Option+P o Alt+P
• La configuración Model en /config
• Activar modo rápido cuando eso cambia el modelo de la sesión
• Una solicitud set_model, o un cambio de modelo en una solicitud apply_flag_settings, desde un anfitrión Agent SDK o Control Remoto

Claude Code no ejecuta hooks PreModelSwitch para cambios que realiza por su cuenta, como un fallback de modelo automático o restaurar el modelo cuando reanuda una sesión. Esos cambios llegan a PostModelSwitch solo.

Claude 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.

Cuando 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 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.

Escriba 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:

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Para 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.

Entrada de PreModelSwitch

Además de los campos de entrada comunes, 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.

Este ejemplo muestra la entrada para /model opus en una sesión que ejecuta Sonnet 5:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

Control de decisión de PreModelSwitch

Los 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.

Para un control más fino, devuelva permissionDecision y permissionDecisionReason en un objeto hookSpecificOutput, como en PreToolUse. PreModelSwitch acepta "allow", "deny", y "ask". No acepta "defer", updatedInput, o additionalContext. La tabla a continuación describe ambos campos:

Solo /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.

Este ejemplo pide al usuario que confirme y cita el recuento de tokens de context_tokens:

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Cuando múltiples hooks PreModelSwitch devuelven decisiones diferentes, la precedencia es deny > ask > allow.

Claude 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.

Un hook PreModelSwitch que no responde antes de su tiempo de espera bloquea el cambio. En PreToolUse, 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.

Un 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.

PostModelSwitch

Se 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.

PostModelSwitch 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:

• Un cambio que solicitó usted o un cliente
• Un fallback de modelo automático, que cambia el modelo de la sesión
• Una configuración como opusplan entrando o saliendo del modo de plan
• Claude Code restaurando el modelo cuando reanuda una sesión

Claude Code no ejecuta hooks PostModelSwitch cuando un modelo de una cadena de modelo de fallback sirve un turno, porque esa sustitución dura un turno y deja el modelo de la sesión sin cambios.

El matcher sigue las mismas reglas que PreModelSwitch: Claude Code compara contra el nombre canónico del modelo al que la sesión cambió.

Este ejemplo agrega orientación siempre que el modelo de la sesión cambia a cualquier modelo Opus:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Para 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.

Entrada de PostModelSwitch

Los hooks PostModelSwitch reciben los mismos campos que PreModelSwitch, 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.

requested_model es null cuando source es "auto". Cuando source es "resume", es la configuración de modelo guardada que Claude Code restauró.

Control de decisión de PostModelSwitch

Claude Code toma su 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 disponibles para todos los hooks, puede devolver:

Si 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.

SessionEnd

Se 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.

El campo reason en la entrada del hook indica por qué terminó la sesión:

Entrada de SessionEnd

Además de los campos de entrada comunes, los hooks SessionEnd reciben un campo reason que indica por qué terminó la sesión. Consulte la tabla de razones anterior para todos los valores.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

Los 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, como systemMessage.

Los 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:

• 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.
• 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.

Este ejemplo establece el presupuesto en 5 segundos:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Antes 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.

Elicitation

Se 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.

El campo matcher coincide contra el nombre del servidor MCP.

Entrada de Elicitation

Además de los campos de entrada comunes, los hooks Elicitation reciben mcp_server_name, message, y campos opcionales mode, url, elicitation_id, y requested_schema.

Para elicitación de modo de formulario, el caso más común:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Para elicitación de modo URL, utilizada para autenticación basada en navegador:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Salida de Elicitation

Para responder programáticamente sin mostrar el diálogo, devuelva un objeto JSON con hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

El código de salida 2 deniega la elicitación. Claude Code no muestra su mensaje stderr en ningún lugar.

Claude Code actúa sobre hookSpecificOutput de la salida JSON de un hook Elicitation y descarta systemMessage y continue.

ElicitationResult

Se 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.

El campo matcher coincide contra el nombre del servidor MCP.

Entrada de ElicitationResult

Además de los campos de entrada comunes, los hooks ElicitationResult reciben mcp_server_name, action, y campos opcionales mode, elicitation_id, y content.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

Salida de ElicitationResult

Para anular la respuesta del usuario, devuelva un objeto JSON con hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

El 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.

Claude Code actúa sobre hookSpecificOutput de la salida JSON de un hook ElicitationResult y descarta systemMessage y continue.

Hooks basados en prompts

Además de hooks de comando, HTTP y herramientas MCP, Claude Code admite hooks basados en prompts (type: "prompt") que usan un LLM para evaluar si permitir o bloquear una acción, y hooks de agente (type: "agent") que generan un verificador agentico con acceso a herramientas. No todos los eventos admiten todos los tipos de hooks.

Eventos que admiten los cinco tipos de hooks (command, http, mcp_tool, prompt y agent):

• PermissionDenied
• PermissionRequest
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

Eventos que admiten hooks command, http y mcp_tool pero no prompt o agent:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart y Setup admiten hooks command y mcp_tool, y MCP tool hook fields describe cuándo se ejecutan sus hooks mcp_tool. No admiten hooks http, prompt o agent.

Cómo funcionan los hooks basados en prompts

En lugar de ejecutar un comando Bash, los hooks basados en prompts:

1. Envían la entrada del hook y su prompt a un modelo Claude, Haiku por defecto
2. El LLM responde con JSON estructurado que contiene una decisión
3. Claude Code procesa la decisión automáticamente

Configuración de hook de prompt

Establezca type en "prompt" y proporcione una cadena prompt en lugar de un command. Use el marcador de posición $ARGUMENTS para inyectar datos de entrada JSON del hook en su texto de prompt.

Este hook Stop le pide al LLM que evalúe si todas las tareas están completas antes de permitir que Claude finalice:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Esquema de respuesta

El LLM debe responder con JSON que contenga:

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

Lo que sucede en ok: false depende del evento:

• Stop y SubagentStop: la razón se retroalimenta a Claude como su siguiente instrucción y el turno continúa, a menos que la respuesta también establezca impossible: true, en cuyo caso Claude Code permite la detención y el turno termina
• PreToolUse: la llamada de herramienta se deniega; por defecto el turno termina y la razón de denegación aparece en el chat como una línea de advertencia. Establezca continueOnBlock: true para devolver la razón a Claude como el error de la herramienta para que pueda ajustarse y continuar, equivalente a un hook de comando con permissionDecision: "deny". Antes de v2.1.210, la razón de denegación se devolvía a Claude como el error de la herramienta y el turno continuaba
• PostToolUse: por defecto el turno termina y la razón aparece en el chat como una línea de advertencia. Establezca continueOnBlock: true para retroalimentar la razón a Claude y continuar el turno en lugar de detener
• PostToolBatch, UserPromptSubmit y UserPromptExpansion: el turno termina y la razón aparece como una línea de advertencia. Estos eventos terminan el turno en decision: "block" independientemente de continue
• PostToolUseFailure y TaskCreated: la razón se devuelve a Claude como un error de herramienta y el turno continúa, independientemente de continueOnBlock
• TaskCompleted: cuando se activa porque una tarea se marca como completada durante un turno, la razón se devuelve a Claude como un error de herramienta y el turno continúa, independientemente de continueOnBlock. Cuando se activa porque un compañero se detiene, se comporta como TeammateIdle y detiene al compañero por defecto
• TeammateIdle: por defecto el compañero se detiene y la razón aparece como una línea de advertencia. Establezca continueOnBlock: true para retroalimentar la razón al compañero y mantenerlo trabajando en su lugar
• PermissionRequest: ok: false no tiene efecto. Para denegar una aprobación desde un hook, use un hook de comando que devuelva hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false no tiene efecto porque la denegación ya sucedió. La única salida que este evento lee es hookSpecificOutput.retry, que los hooks de prompt y agente no pueden establecer. Se ejecutan en este evento, pero su salida se descarta. Use un hook de comando para devolver retry

Si necesita un control más fino en cualquier evento, use un hook de comando con los campos por evento descritos en Control de decisión.

Verificar múltiples condiciones antes de detener

Este hook Stop usa un prompt detallado para verificar tres condiciones antes de permitir que Claude se detenga. Los hooks SubagentStop usan el mismo formato para evaluar si un subagente debe detenerse. Si el modelo devuelve "ok": false porque la condición aún no se cumple, Claude continúa trabajando con la razón proporcionada como su siguiente instrucción:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks basados en agentes

Los hooks basados en agentes (type: "agent") son como hooks basados en prompts pero con acceso a herramientas de múltiples turnos. En lugar de una única llamada LLM, un hook de agente genera un subagente que puede leer archivos, buscar código e inspeccionar la base de código para verificar condiciones. Los hooks de agente admiten los mismos eventos que los hooks basados en prompts.

Cómo funcionan los hooks de agente

Cuando se activa un hook de agente:

1. Claude Code genera un subagente con su prompt y la entrada JSON del hook
2. El subagente puede usar herramientas como Read, Grep y Glob para investigar
3. Después de hasta 50 turnos, el subagente devuelve una decisión estructurada { "ok": true/false }
4. Claude Code permite la acción si ok es true. Si ok es false, Claude Code maneja el bloqueo de la misma manera que un hook de prompt con continueOnBlock: true en ese evento, como se indica en Esquema de respuesta

Los hooks de agente son útiles cuando la verificación requiere inspeccionar archivos reales o salida de prueba, no solo evaluar los datos de entrada del hook solos.

Configuración de hook de agente

Establezca type en "agent" y proporcione una cadena prompt, usando $ARGUMENTS como marcador de posición para la entrada JSON del hook. Los campos de configuración son los mismos que los hooks de prompt, excepto que los hooks de agente tienen un tiempo de espera predeterminado más largo de 60 segundos y no tienen campo continueOnBlock.

El esquema de respuesta es { "ok": true } para permitir o { "ok": false, "reason": "..." } para bloquear. En ok: false, Claude Code maneja un hook de agente de la manera que maneja un hook de prompt con continueOnBlock: true en el mismo evento; los hooks de agente no tienen campo continueOnBlock y no admiten el campo impossible del hook de prompt.

Este hook Stop verifica que todas las pruebas unitarias pasen antes de permitir que Claude finalice:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Ejecutar hooks en segundo plano

Por defecto, los hooks bloquean la ejecución de Claude hasta que se completen. Para tareas de larga duración como implementaciones, conjuntos de pruebas o llamadas a API externas, establezca "async": true para ejecutar el hook en segundo plano mientras Claude continúa trabajando. Los hooks asincronos no pueden bloquear o controlar el comportamiento de Claude: campos de respuesta como decision, permissionDecision y continue no tienen efecto, porque la acción que habrían controlado ya se ha completado.

Configurar un hook asincrónico

Agregue "async": true a la configuración de un hook de comando para ejecutarlo en segundo plano sin bloquear a Claude. Este campo solo está disponible en hooks type: "command".

Este hook ejecuta un script de prueba después de cada llamada a herramienta Write. Claude continúa trabajando inmediatamente mientras run-tests.sh se ejecuta. Cuando el script finaliza, su salida se entrega en el siguiente turno de conversación:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Una vez que un hook asincrónico se está ejecutando en segundo plano, Claude Code no aplica timeout en él. Claude Code aún aplica timeout en un hook que ejecuta con asyncRewake.

Claude Code entrega los resultados de un hook asincrónico solo mientras se ejecuta la sesión:

• En modo no interactivo con la bandera -p, Claude Code mata cualquier hook asincrónico que aún se esté ejecutando al finalizar y lo finaliza con resultado cancelled
• Si el trabajo de su hook debe sobrevivir a una sesión claude -p, inicie un proceso completamente desacoplado desde él

Cómo se ejecutan los hooks asincronos

Cuando se activa un hook asincrónico, Claude Code inicia el proceso del hook e inmediatamente continúa sin esperar a que finalice. El hook recibe la misma entrada JSON a través de stdin que un hook sincrónico.

Después de que el proceso de fondo sale, Claude Code entrega los campos additionalContext y systemMessage de la respuesta JSON del hook a Claude en el siguiente turno de conversación. A diferencia del systemMessage de un hook sincrónico, ninguno de estos campos se le muestra a usted.

Claude Code valida esa respuesta JSON contra el mismo esquema de salida que los hooks sincronos, y descarta cualquier campo cuyo valor tenga el tipo incorrecto, como un systemMessage que no sea una cadena, en lugar de entregarlo. Ejecute con --debug para ver una advertencia que nombre cada campo descartado. Antes de v2.1.202, la salida JSON malformada de un hook asincrónico podría bloquear la sesión, y el bloqueo se repetía cada vez que se reanudaba la sesión.

Las notificaciones de finalización de hooks asincronos se suprimen por defecto. Para verlas, habilite el modo detallado con Ctrl+O o inicie Claude Code con --verbose.

Ejecutar pruebas después de cambios de archivo

Este hook inicia un conjunto de pruebas en segundo plano cada vez que Claude escribe un archivo, luego reporta los resultados a Claude cuando las pruebas finalizan. Guarde este script en .claude/hooks/run-tests-async.sh en su proyecto y hágalo ejecutable con chmod +x:

#!/bin/bash
# run-tests-async.sh

# Lee entrada de hook desde stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Solo ejecute pruebas para archivos de origen
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Ejecute pruebas e informe resultados a Claude a través de additionalContext
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Luego agregue esta configuración a .claude/settings.json en la raíz de su proyecto. La bandera async: true permite que Claude continúe trabajando mientras se ejecutan las pruebas:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Limitaciones

Los hooks asincronos tienen restricciones adicionales en comparación con los hooks sincronos:

• La salida del hook se entrega en el siguiente turno de conversación. Si la sesión está inactiva, la respuesta espera hasta la siguiente interacción del usuario. Excepción: un hook asyncRewake que sale con código 2 despierta a Claude inmediatamente incluso cuando la sesión está inactiva.
• Cada ejecución crea un proceso de fondo separado. No hay deduplicación en múltiples activaciones del mismo hook asincrónico.

Consideraciones de seguridad

Descargo de responsabilidad

Confianza del espacio de trabajo

Claude Code verifica la confianza del espacio de trabajo antes de ejecutar cualquier hook desde un archivo de configuración. Lo que cuenta como confiable depende del tipo de sesión:

• Sesión interactiva: Claude Code retiene los hooks de todos los archivos de configuración, incluido su propio ~/.claude/settings.json, hasta que acepte el diálogo de confianza del espacio de trabajo para la carpeta, o para un directorio principal cuya confianza se extienda a ella
• Sesión -p o SDK: Claude Code nunca muestra el diálogo y trata la carpeta como confiable, por lo que los hooks confirmados en el .claude/settings.json de un repositorio se ejecutan en una carpeta que nunca ha confiado

Antes de ejecutar claude -p en un repositorio que no escribió, revise sus archivos de configuración .claude/, comience con --bare, o desactive los hooks para esa ejecución con --settings '{"disableAllHooks": true}'. Los hooks de frontmatter en un subagente de proyecto siguen una regla más estricta que los hooks de archivo de configuración. Lo que se ejecuta antes de confiar en una carpeta enumera cada tipo de contenido de repositorio por tipo de sesión.

Mejores prácticas de seguridad

Tenga en cuenta estas prácticas al escribir hooks:

• Validar y sanitizar entradas: nunca confíe en datos de entrada ciegamente
• Siempre entrecomillar variables de shell: use "$VAR" no $VAR
• Bloquear traversal de ruta: verifique .. en rutas de archivo
• Usar rutas absolutas: especifique rutas completas para scripts. En forma exec, use ${CLAUDE_PROJECT_DIR} y la ruta no necesita entrecomillarse. En forma shell, envuélvala en comillas dobles
• Omitir archivos sensibles: evite .env, .git/, claves, etc.

Herramienta PowerShell en Windows

En Windows, puede ejecutar hooks individuales en PowerShell estableciendo "shell": "powershell" en un hook de comando. Claude Code detecta automáticamente pwsh.exe, el ejecutable de PowerShell 7 y posterior, y recurre a powershell.exe para Windows PowerShell 5.1.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Para hacer referencia al directorio raíz del proyecto desde un comando de forma shell de PowerShell, escriba ${CLAUDE_PROJECT_DIR} o $env:CLAUDE_PROJECT_DIR. A partir de v2.1.198, Claude Code reescribe los marcadores de posición ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} y ${CLAUDE_PLUGIN_DATA} en un comando de forma shell de PowerShell a la forma ${env:NAME} de PowerShell, ya sea que el hook esté definido en settings.json, un plugin o una skill. PowerShell luego resuelve el valor del entorno exportado después del análisis, por lo que el marcador de posición funciona dentro de cadenas entre comillas dobles pero no dentro de cadenas entre comillas simples, donde PowerShell nunca expande variables.

Antes de v2.1.198, esta reescritura se aplicaba solo a hooks de plugins. En versiones anteriores, un hook de settings.json necesita la forma $env: o forma exec, donde ${CLAUDE_PROJECT_DIR} se sustituye en cada elemento args independientemente de dónde se defina el hook.

No escriba la ortografía desnuda $CLAUDE_PROJECT_DIR en un hook de PowerShell. PowerShell la analiza como una variable local indefinida y la resuelve a $null, lo que deja la ruta del script sin su prefijo de directorio raíz del proyecto. Claude Code no reescribe esa forma; en su lugar, registra una advertencia en el registro de depuración.

El ejemplo a continuación muestra un hook de settings.json que ejecuta un script del proyecto con la forma $env:, que funciona en todas las versiones:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Depurar hooks

Los detalles de ejecución de hooks se escriben en el archivo de registro de depuración. Inicie Claude Code con claude --debug-file <path> para escribir el registro en una ubicación conocida, o ejecute claude --debug y lea el registro en ~/.claude/debug/<session-id>.txt. La bandera --debug no imprime en la terminal.

Por ejemplo, un hook PostToolUse en Write cuyo comando imprime hook-ran produce entradas como:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Para detalles de coincidencia de hooks más granulares, establezca CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose para ver líneas de registro adicionales como recuentos de matchers de hooks y coincidencia de consultas.

Para solucionar problemas comunes como hooks que no se activan, hooks Stop que siguen bloqueando, o errores de configuración, consulte Limitaciones y solución de problemas en la guía. Para un recorrido de diagnóstico más amplio que cubra /context, /doctor y precedencia de configuración, consulte Depure su configuración.