Interceptar y controlar el comportamiento del agente con hooks

Interceptar y personalizar el comportamiento del agente en puntos clave de ejecución con hooks

Los hooks son funciones de devolución de llamada que ejecutan su código en respuesta a eventos del agente, como una herramienta siendo llamada, una sesión iniciándose, o la ejecución deteniéndose. Con hooks, puede:

• Bloquear operaciones peligrosas antes de que se ejecuten, como comandos de shell destructivos o acceso a archivos no autorizado
• Registrar y auditar cada llamada de herramienta para cumplimiento, depuración o análisis
• Transformar entradas y salidas para sanitizar datos, inyectar credenciales o redirigir rutas de archivos
• Requerir aprobación humana para acciones sensibles como escrituras en bases de datos o llamadas a API
• Rastrear el ciclo de vida de la sesión para gestionar estado, limpiar recursos o enviar notificaciones

Esta guía cubre cómo funcionan los hooks, cómo configurarlos, y proporciona ejemplos para patrones comunes como bloquear herramientas, modificar entradas y reenviar notificaciones.

Cómo funcionan los hooks

El siguiente ejemplo reúne estos pasos. Registra un hook PreToolUse (paso 1) con un matcher "Write|Edit" (paso 3) para que la devolución de llamada solo se dispare para herramientas de escritura de archivos. Cuando se activa, la devolución de llamada recibe la entrada de la herramienta (paso 4), verifica si la ruta del archivo apunta a un archivo .env, y devuelve permissionDecision: "deny" para bloquear la operación (paso 5):

import asyncio
from claude_agent_sdk import (
AssistantMessage,
ClaudeSDKClient,
ClaudeAgentOptions,
HookMatcher,
ResultMessage,
)


# Define a hook callback that receives tool call details
async def protect_env_files(input_data, tool_use_id, context):
# Extract the file path from the tool's input arguments
file_path = input_data["tool_input"].get("file_path", "")
file_name = file_path.split("/")[-1]

# Block the operation if targeting a .env file
if file_name == ".env":
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": "Cannot modify .env files",
}
}

# Return empty object to allow the operation
return {}


async def main():
options = ClaudeAgentOptions(
hooks={
# Register the hook for PreToolUse events
# The matcher filters to only Write and Edit tool calls
"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]
}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Update the database configuration")
async for message in client.receive_response():
# Filter for assistant and result messages
if isinstance(message, (AssistantMessage, ResultMessage)):
print(message)


asyncio.run(main())

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

// Define a hook callback with the HookCallback type
const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {
// Cast input to the specific hook type for type safety
const preInput = input as PreToolUseHookInput;

// Cast tool_input to access its properties (typed as unknown in the SDK)
const toolInput = preInput.tool_input as Record<string, unknown>;
const filePath = toolInput?.file_path as string;
const fileName = filePath?.split("/").pop();

// Block the operation if targeting a .env file
if (fileName === ".env") {
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "deny",
permissionDecisionReason: "Cannot modify .env files"
}
};
}

// Return empty object to allow the operation
return {};
};

for await (const message of query({
prompt: "Update the database configuration",
options: {
hooks: {
// Register the hook for PreToolUse events
// The matcher filters to only Write and Edit tool calls
PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]
}
}
})) {
// Filter for assistant and result messages
if (message.type === "assistant" || message.type === "result") {
console.log(message);
}
}

Hooks disponibles

El SDK proporciona hooks para diferentes etapas de la ejecución del agente. Algunos hooks están disponibles en ambos SDK, mientras que otros son solo para TypeScript.

Configurar hooks

Para configurar un hook, páselo en el campo hooks de sus opciones de agente (ClaudeAgentOptions en Python, el objeto options en TypeScript):

options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[my_callback])]}
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Your prompt")
async for message in client.receive_response():
print(message)

for await (const message of query({
prompt: "Your prompt",
options: {
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [myCallback] }]
}
}
})) {
console.log(message);
}

La opción hooks es un diccionario (Python) u objeto (TypeScript) donde:

• Las claves son nombres de eventos de hook (por ejemplo, 'PreToolUse', 'PostToolUse', 'Stop')
• Los valores son matrices de matchers, cada una conteniendo un patrón de filtro opcional y sus funciones de devolución de llamada

Matchers

Use matchers para filtrar cuándo se disparan sus devoluciones de llamada. El campo matcher coincide con un valor diferente dependiendo del tipo de evento de hook. Por ejemplo, los hooks basados en herramientas coinciden con el nombre de la herramienta, mientras que los hooks Notification coinciden con el tipo de notificación. Vea la referencia de hooks de Claude Code para la lista completa de valores de matcher para cada tipo de evento.

Los matchers del SDK siguen las mismas reglas que matchers en archivos de configuración: un matcher que contiene solo letras, dígitos, _ y | se compara como una cadena exacta, con | separando alternativas, por lo que Write|Edit coincide exactamente con esas dos herramientas. Un matcher de *, una cadena vacía, u omitir el matcher completamente coincide con cada ocurrencia del evento; un matcher que contiene cualquier otro carácter se evalúa como una expresión regular, por lo que ^mcp__ coincide con cada herramienta MCP. Un matcher como mcp__memory contiene solo letras y guiones bajos, por lo que se compara como una cadena exacta y no coincide con ninguna herramienta; use mcp__memory__.* para coincidir con cada herramienta de ese servidor.

Use el patrón matcher para dirigirse a herramientas específicas siempre que sea posible. Un matcher con 'Bash' solo se ejecuta para comandos Bash, mientras que omitir el patrón ejecuta sus devoluciones de llamada para cada ocurrencia del evento. Tenga en cuenta que para hooks basados en herramientas, los matchers solo filtran por nombre de herramienta, no por rutas de archivo u otros argumentos. Para filtrar por ruta de archivo, verifique tool_input.file_path dentro de su devolución de llamada.

Funciones de devolución de llamada

Entradas

Cada devolución de llamada de hook recibe tres argumentos:

• Datos de entrada: un objeto tipado que contiene detalles del evento. Cada tipo de hook tiene su propia forma de entrada (por ejemplo, PreToolUseHookInput incluye tool_name y tool_input, mientras que NotificationHookInput incluye message). Vea las definiciones de tipo completas en las referencias del SDK de TypeScript y Python.
  • Todas las entradas de hook comparten session_id, cwd y hook_event_name.
  • agent_id y agent_type se rellenan cuando el hook se dispara dentro de un subagente. En TypeScript, estos están en la entrada de hook base y disponibles para todos los tipos de hook. En Python, están solo en PreToolUse, PostToolUse y PostToolUseFailure.
• ID de uso de herramienta (str | None / string | undefined): correlaciona eventos PreToolUse y PostToolUse para la misma llamada de herramienta.
• Contexto: en TypeScript, contiene una propiedad signal (AbortSignal) para cancelación. En Python, este argumento está reservado para uso futuro.

Salidas

Su devolución de llamada devuelve un objeto con dos categorías de campos:

• Campos de nivel superior funcionan igual en cada evento: systemMessage muestra un mensaje al usuario, y continue (continue_ en Python) determina si el agente sigue ejecutándose después de este hook.
• hookSpecificOutput controla la operación actual. Los campos dentro dependen del tipo de evento de hook. Para hooks PreToolUse, aquí es donde establece permissionDecision ("allow", "deny", "ask" o "defer"), permissionDecisionReason e updatedInput. Devolver "defer" finaliza la consulta para que pueda reanudarla más tarde. Para hooks PostToolUse, puede establecer additionalContext para agregar información al resultado de la herramienta. Para reemplazar la salida de la herramienta antes de que Claude la vea, establezca updatedToolOutput, que funciona para cualquier herramienta en ambos SDK. El campo anterior updatedMCPToolOutput reemplaza solo la salida de herramientas MCP y está deprecado.

Devuelva {} para permitir la operación sin cambios. Los hooks de devolución de llamada del SDK usan el mismo formato de salida JSON que hooks de comandos de shell de Claude Code, que documenta cada campo y opción específica del evento. Para las definiciones de tipo del SDK, vea las referencias del SDK de TypeScript y Python.

Salida asincrónica

De forma predeterminada, el agente espera a que su hook devuelva antes de continuar. Si su hook realiza un efecto secundario (registro, envío de webhook) y no necesita influir en el comportamiento del agente, puede devolver una salida asincrónica en su lugar. Esto le dice al agente que continúe inmediatamente sin esperar a que el hook termine:

async def async_hook(input_data, tool_use_id, context):
# Start a background task, then return immediately
asyncio.create_task(send_to_logging_service(input_data))
return {"async_": True, "asyncTimeout": 30000}

const asyncHook: HookCallback = async (input, toolUseID, { signal }) => {
// Start a background task, then return immediately
sendToLoggingService(input).catch(console.error);
return { async: true, asyncTimeout: 30000 };
};

Ejemplos

Modificar entrada de herramienta

Este ejemplo intercepta llamadas de herramienta Write y reescribe el argumento file_path para anteponer /sandbox, redirigiendo todas las escrituras de archivo a un directorio aislado. La devolución de llamada devuelve updatedInput con la ruta modificada y permissionDecision: 'allow' para aprobar automáticamente la operación reescrita:

async def redirect_to_sandbox(input_data, tool_use_id, context):
if input_data["hook_event_name"] != "PreToolUse":
return {}

if input_data["tool_name"] == "Write":
original_path = input_data["tool_input"].get("file_path", "")
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "allow",
"updatedInput": {
**input_data["tool_input"],
"file_path": f"/sandbox{original_path}",
},
}
}
return {}

const redirectToSandbox: HookCallback = async (input, toolUseID, { signal }) => {
if (input.hook_event_name !== "PreToolUse") return {};

const preInput = input as PreToolUseHookInput;
const toolInput = preInput.tool_input as Record<string, unknown>;
if (preInput.tool_name === "Write") {
const originalPath = toolInput.file_path as string;
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "allow",
updatedInput: {
...toolInput,
file_path: `/sandbox${originalPath}`
}
}
};
}
return {};
};

Agregar contexto y bloquear una herramienta

Este ejemplo bloquea escrituras en el directorio /etc y explica por qué tanto al modelo como al usuario:

• permissionDecision: 'deny' detiene la llamada de herramienta.
• permissionDecisionReason le dice al modelo por qué, para que evite reintentar.
• systemMessage muestra al usuario qué sucedió.

async def block_etc_writes(input_data, tool_use_id, context):
file_path = input_data["tool_input"].get("file_path", "")

if file_path.startswith("/etc"):
return {
# Top-level field: message shown to the user
"systemMessage": "Remember: system directories like /etc are protected.",
# hookSpecificOutput: block the operation
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": "Writing to /etc is not allowed",
},
}
return {}

const blockEtcWrites: HookCallback = async (input, toolUseID, { signal }) => {
const preInput = input as PreToolUseHookInput;
const toolInput = preInput.tool_input as Record<string, unknown>;
const filePath = toolInput?.file_path as string;

if (filePath?.startsWith("/etc")) {
return {
// Top-level field: message shown to the user
systemMessage: "Remember: system directories like /etc are protected.",
// hookSpecificOutput: block the operation
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "deny",
permissionDecisionReason: "Writing to /etc is not allowed"
}
};
}
return {};
};

Aprobar automáticamente herramientas específicas

De forma predeterminada, el agente puede solicitar permiso antes de usar ciertas herramientas. Este ejemplo aprueba automáticamente herramientas del sistema de archivos de solo lectura (Read, Glob, Grep) devolviendo permissionDecision: 'allow', permitiéndoles ejecutarse sin confirmación del usuario mientras deja todas las otras herramientas sujetas a verificaciones de permiso normales:

async def auto_approve_read_only(input_data, tool_use_id, context):
if input_data["hook_event_name"] != "PreToolUse":
return {}

read_only_tools = ["Read", "Glob", "Grep"]
if input_data["tool_name"] in read_only_tools:
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "allow",
"permissionDecisionReason": "Read-only tool auto-approved",
}
}
return {}

const autoApproveReadOnly: HookCallback = async (input, toolUseID, { signal }) => {
if (input.hook_event_name !== "PreToolUse") return {};

const preInput = input as PreToolUseHookInput;
const readOnlyTools = ["Read", "Glob", "Grep"];
if (readOnlyTools.includes(preInput.tool_name)) {
return {
hookSpecificOutput: {
hookEventName: preInput.hook_event_name,
permissionDecision: "allow",
permissionDecisionReason: "Read-only tool auto-approved"
}
};
}
return {};
};

Registrar múltiples hooks

Cuando se dispara un evento, todos los hooks coincidentes se ejecutan en paralelo. Para decisiones de permiso, el resultado más restrictivo gana: un único deny bloquea la llamada de herramienta independientemente de lo que devuelvan los otros hooks. Debido a que el orden de finalización es no determinista, escriba cada hook para actuar de forma independiente en lugar de depender de que otro hook se haya ejecutado primero.

El ejemplo a continuación registra tres verificaciones independientes para cada llamada de herramienta:

options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
HookMatcher(hooks=[authorization_check]),
HookMatcher(hooks=[input_validator]),
HookMatcher(hooks=[audit_logger]),
]
}
)

const options = {
hooks: {
PreToolUse: [
{ hooks: [authorizationCheck] },
{ hooks: [inputValidator] },
{ hooks: [auditLogger] }
]
}
};

Filtrar con matchers de múltiples herramientas

Use matchers de múltiples herramientas para compartir una devolución de llamada entre herramientas relacionadas. Este ejemplo registra tres matchers con diferentes alcances:

• Una lista exacta separada por tuberías (Write|Edit|Delete) dispara file_security_hook solo para herramientas de modificación de archivos.
• Una expresión regular (^mcp__) dispara mcp_audit_hook para cualquier herramienta MCP cuyo nombre comience con mcp__.
• Un matcher omitido dispara global_logger para cada llamada de herramienta independientemente del nombre.

options = ClaudeAgentOptions(
hooks={
"PreToolUse": [
# Match file modification tools
HookMatcher(matcher="Write|Edit|Delete", hooks=[file_security_hook]),
# Match all MCP tools
HookMatcher(matcher="^mcp__", hooks=[mcp_audit_hook]),
# Match everything (no matcher)
HookMatcher(hooks=[global_logger]),
]
}
)

const options = {
hooks: {
PreToolUse: [
// Match file modification tools
{ matcher: "Write|Edit|Delete", hooks: [fileSecurityHook] },

// Match all MCP tools
{ matcher: "^mcp__", hooks: [mcpAuditHook] },

// Match everything (no matcher)
{ hooks: [globalLogger] }
]
}
};

Rastrear actividad de subagente

Use hooks SubagentStop para monitorear cuándo los subagentes terminan su trabajo. Vea el tipo de entrada completo en las referencias del SDK de TypeScript y Python. Este ejemplo registra un resumen cada vez que un subagente se completa:

async def subagent_tracker(input_data, tool_use_id, context):
# Log subagent details when it finishes
print(f"[SUBAGENT] Completed: {input_data['agent_id']}")
print(f"  Transcript: {input_data['agent_transcript_path']}")
print(f"  Tool use ID: {tool_use_id}")
print(f"  Stop hook active: {input_data.get('stop_hook_active')}")
return {}


options = ClaudeAgentOptions(
hooks={"SubagentStop": [HookMatcher(hooks=[subagent_tracker])]}
)

import { HookCallback, SubagentStopHookInput } from "@anthropic-ai/claude-agent-sdk";

const subagentTracker: HookCallback = async (input, toolUseID, { signal }) => {
// Cast to SubagentStopHookInput to access subagent-specific fields
const subInput = input as SubagentStopHookInput;

// Log subagent details when it finishes
console.log(`[SUBAGENT] Completed: ${subInput.agent_id}`);
console.log(`  Transcript: ${subInput.agent_transcript_path}`);
console.log(`  Tool use ID: ${toolUseID}`);
console.log(`  Stop hook active: ${subInput.stop_hook_active}`);
return {};
};

const options = {
hooks: {
SubagentStop: [{ hooks: [subagentTracker] }]
}
};

Realizar solicitudes HTTP desde hooks

Los hooks pueden realizar operaciones asincrónicas como solicitudes HTTP. Capture errores dentro de su hook en lugar de dejarlos propagarse, ya que una excepción no manejada puede interrumpir el agente.

Este ejemplo envía un webhook después de que cada herramienta se completa, registrando qué herramienta se ejecutó y cuándo. El hook captura errores para que un webhook fallido no interrumpa el agente:

import asyncio
import json
import urllib.request
from datetime import datetime


def _send_webhook(tool_name):
"""Synchronous helper that POSTs tool usage data to an external webhook."""
data = json.dumps(
{
"tool": tool_name,
"timestamp": datetime.now().isoformat(),
}
).encode()
req = urllib.request.Request(
"https://api.example.com/webhook",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def webhook_notifier(input_data, tool_use_id, context):
# Only fire after a tool completes (PostToolUse), not before
if input_data["hook_event_name"] != "PostToolUse":
return {}

try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_webhook, input_data["tool_name"])
except Exception as e:
# Log the error but don't raise. A failed webhook shouldn't stop the agent
print(f"Webhook request failed: {e}")

return {}

import { query, HookCallback, PostToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

const webhookNotifier: HookCallback = async (input, toolUseID, { signal }) => {
// Only fire after a tool completes (PostToolUse), not before
if (input.hook_event_name !== "PostToolUse") return {};

try {
await fetch("https://api.example.com/webhook", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
tool: (input as PostToolUseHookInput).tool_name,
timestamp: new Date().toISOString()
}),
// Pass signal so the request cancels if the hook times out
signal
});
} catch (error) {
// Handle cancellation separately from other errors
if (error instanceof Error && error.name === "AbortError") {
console.log("Webhook request cancelled");
}
// Don't re-throw. A failed webhook shouldn't stop the agent
}

return {};
};

// Register as a PostToolUse hook
for await (const message of query({
prompt: "Refactor the auth module",
options: {
hooks: {
PostToolUse: [{ hooks: [webhookNotifier] }]
}
}
})) {
console.log(message);
}

Reenviar notificaciones a Slack

Use hooks Notification para recibir notificaciones del sistema del agente y reenviarlas a servicios externos. Las notificaciones se disparan para tipos de evento tales como:

• permission_prompt cuando Claude necesita permiso
• idle_prompt cuando Claude está esperando entrada
• auth_success cuando la autenticación se completa
• elicitation_dialog, elicitation_complete, y elicitation_response para flujos de elicitación de solicitud del usuario

Cada notificación incluye un campo message con una descripción legible por humanos y opcionalmente un title.

Este ejemplo reenvía cada notificación a un canal de Slack. Requiere una URL de webhook entrante de Slack, que crea agregando una aplicación a su espacio de trabajo de Slack y habilitando webhooks entrantes:

import asyncio
import json
import urllib.request

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


def _send_slack_notification(message):
"""Synchronous helper that sends a message to Slack via incoming webhook."""
data = json.dumps({"text": f"Agent status: {message}"}).encode()
req = urllib.request.Request(
"https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
data=data,
headers={"Content-Type": "application/json"},
method="POST",
)
urllib.request.urlopen(req)


async def notification_handler(input_data, tool_use_id, context):
try:
# Run the blocking HTTP call in a thread to avoid blocking the event loop
await asyncio.to_thread(_send_slack_notification, input_data.get("message", ""))
except Exception as e:
print(f"Failed to send notification: {e}")

# Return empty object. Notification hooks don't modify agent behavior
return {}


async def main():
options = ClaudeAgentOptions(
hooks={
# Register the hook for Notification events (no matcher needed)
"Notification": [HookMatcher(hooks=[notification_handler])],
},
)

async with ClaudeSDKClient(options=options) as client:
await client.query("Analyze this codebase")
async for message in client.receive_response():
print(message)


asyncio.run(main())

import { query, HookCallback, NotificationHookInput } from "@anthropic-ai/claude-agent-sdk";

// Define a hook callback that sends notifications to Slack
const notificationHandler: HookCallback = async (input, toolUseID, { signal }) => {
// Cast to NotificationHookInput to access the message field
const notification = input as NotificationHookInput;

try {
// POST the notification message to a Slack incoming webhook
await fetch("https://hooks.slack.com/services/YOUR/WEBHOOK/URL", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
text: `Agent status: ${notification.message}`
}),
// Pass signal so the request cancels if the hook times out
signal
});
} catch (error) {
if (error instanceof Error && error.name === "AbortError") {
console.log("Notification cancelled");
} else {
console.error("Failed to send notification:", error);
}
}

// Return empty object. Notification hooks don't modify agent behavior
return {};
};

// Register the hook for Notification events (no matcher needed)
for await (const message of query({
prompt: "Analyze this codebase",
options: {
hooks: {
Notification: [{ hooks: [notificationHandler] }]
}
}
})) {
console.log(message);
}

Solucionar problemas comunes

Hook no se dispara

• Verifique que el nombre del evento de hook sea correcto y sensible a mayúsculas (PreToolUse, no preToolUse)
• Verifique que su patrón de matcher coincida exactamente con el nombre de la herramienta
• Asegúrese de que el hook esté bajo el tipo de evento correcto en options.hooks
• Para hooks que no son de herramientas como Stop y SubagentStop, los matchers coinciden contra campos diferentes (vea patrones de matcher)
• Los hooks pueden no dispararse cuando el agente alcanza el límite max_turns porque la sesión termina antes de que los hooks puedan ejecutarse

Matcher no filtra como se esperaba

Los matchers solo coinciden con nombres de herramientas, no con rutas de archivo u otros argumentos. Para filtrar por ruta de archivo, verifique tool_input.file_path dentro de su hook:

const myHook: HookCallback = async (input, toolUseID, { signal }) => {
  const preInput = input as PreToolUseHookInput;
  const toolInput = preInput.tool_input as Record<string, unknown>;
  const filePath = toolInput?.file_path as string;
  if (!filePath?.endsWith(".md")) return {}; // Skip non-markdown files
  // Process markdown files...
  return {};
};

Tiempo de espera del hook

• Aumente el valor timeout en la configuración HookMatcher
• Use el AbortSignal del tercer argumento de devolución de llamada para manejar la cancelación correctamente en TypeScript

Herramienta bloqueada inesperadamente

• Verifique todos los hooks PreToolUse para devoluciones de permissionDecision: 'deny'
• Agregue registro a sus hooks para ver qué permissionDecisionReason están devolviendo
• Verifique que los patrones de matcher no sean demasiado amplios (un matcher vacío coincide con todas las herramientas)

Entrada modificada no aplicada

• Asegúrese de que updatedInput esté dentro de hookSpecificOutput, no en el nivel superior:

  return {
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "allow",
      updatedInput: { command: "new command" }
    }
  };
  

• Devuelva permissionDecision: 'allow' para aprobar automáticamente la entrada modificada, u 'ask' para mostrarla al usuario para su aprobación

• Incluya hookEventName en hookSpecificOutput para identificar para qué tipo de hook es la salida

Hooks de sesión no disponibles en Python

SessionStart y SessionEnd pueden registrarse como hooks de devolución de llamada del SDK en TypeScript, pero no están disponibles en el SDK de Python (HookEvent los omite). En Python, solo están disponibles como hooks de comandos de shell definidos en archivos de configuración (por ejemplo, .claude/settings.json). Para cargar hooks de comandos de shell desde su aplicación SDK, incluya la fuente de configuración apropiada con setting_sources o settingSources:

options = ClaudeAgentOptions(
setting_sources=["project"],  # Loads .claude/settings.json including hooks
)

const options = {
settingSources: ["project"] // Loads .claude/settings.json including hooks
};

Para ejecutar lógica de inicialización como una devolución de llamada del SDK de Python en su lugar, use el primer mensaje de client.receive_response() como su disparador.

Solicitudes de permiso de subagente multiplicándose

Al generar múltiples subagentes, cada uno puede solicitar permisos por separado. Los subagentes no heredan automáticamente los permisos del agente padre. Para evitar solicitudes repetidas, use hooks PreToolUse para aprobar automáticamente herramientas específicas, o configure reglas de permiso que se apliquen a sesiones de subagente.

Bucles recursivos de hook con subagentes

Un hook UserPromptSubmit que genera subagentes puede crear bucles infinitos si esos subagentes disparan el mismo hook. Para prevenir esto:

• Verifique un indicador de subagente en la entrada del hook antes de generar
• Use una variable compartida o estado de sesión para rastrear si ya está dentro de un subagente
• Alcance los hooks para ejecutarse solo para la sesión del agente de nivel superior

systemMessage no aparece en la salida

El campo systemMessage muestra un mensaje al usuario, no al modelo. Por defecto, el SDK no expone la salida de hooks en el flujo de mensajes, por lo que el mensaje puede no aparecer a menos que establezca includeHookEvents (include_hook_events en Python). Para pasar contexto al modelo en su lugar, devuelva additionalContext.

Si necesita exponer decisiones de hook a su aplicación de manera confiable, regístrelas por separado o use un canal de salida dedicado.

Recursos relacionados

• Referencia de hooks de Claude Code: esquemas completos de entrada/salida JSON, documentación de eventos y patrones de matcher
• Guía de hooks de Claude Code: ejemplos de hooks de comandos de shell y tutoriales
• Referencia del SDK de TypeScript: tipos de hook, definiciones de entrada/salida y opciones de configuración
• Referencia del SDK de Python: tipos de hook, definiciones de entrada/salida y opciones de configuración
• Permisos: controlar qué puede hacer su agente
• Herramientas personalizadas: crear herramientas para extender las capacidades del agente