Hooks del Agent SDK: interceptar llamadas y normalizar resultados

Un hook es código tuyo que el Agent SDK corre en un momento fijo del ciclo del agente. Como lo ejecuta el SDK y no el modelo, da una garantía determinística (deterministic guarantee): pasa siempre, decida lo que decida Claude. La clave para el examen es el momento en que corre cada uno.

Antes o después de la herramienta

	PreToolUse	PostToolUse
Cuándo corre	Antes de ejecutar la herramienta	Después de ejecutarla y antes de que el modelo vea el resultado
Qué puede hacer	Bloquear la llamada o modificar su entrada	Transformar, recortar o enmascarar el resultado
Para qué sirve	Políticas: “esto nunca se ejecuta sin…”	Datos: “el modelo siempre recibe esto limpio”

PreToolUse: interceptar la llamada

El hook previo a la herramienta (PreToolUse hook) mira el nombre de la herramienta y sus parámetros, y decide. Sirve para interceptar la llamada (tool call interception):

• Bloquear: un reembolso de más de $500 no se ejecuta y el caso se deriva a una persona. En el SDK, el hook devuelve una decisión de denegar junto con un motivo.
• Explicar el bloqueo: el motivo vuelve al agente. Si dice por qué se negó y qué hacer en cambio (“primero corré aml_check” o “escalá a un supervisor”), el agente cambia de rumbo. Un bloqueo mudo hace que repita la misma llamada hasta el límite.
• Modificar la entrada: si search_orders llega sin rango de fechas, el hook agrega 90 días por defecto antes de ejecutar. El escaneo completo de la tabla nunca ocurre, y si el agente sí dio un rango, queda como estaba.

PostToolUse: normalizar el resultado

El hook posterior a la herramienta (PostToolUse hook) es el último punto antes de que el resultado entre al contexto. Sirve para la normalización de datos (data normalization):

• tres servidores MCP devuelven fechas como Unix timestamp, ISO 8601 y “03/04/26”: el hook las pasa todas a ISO 8601 y el modelo deja de confundir día con mes;
• códigos de estado numéricos se traducen a texto;
• números de tarjeta completos se enmascaran, así nunca llegan al contexto ni a los registros, sin tocar una herramienta que no podés cambiar;
• una respuesta de 40 KB se recorta a los tres campos que importan.

Un control no confía en el modelo

Para saber si aml_check aprobó antes de permitir transfer_funds, el PreToolUse no puede mirar un parámetro que escribió el modelo ni buscar una frase en la conversación: eso es creerle al modelo lo que dice de sí mismo. El diseño confiable es que un PostToolUse sobre aml_check registre el resultado real en el estado de la aplicación y que el PreToolUse sobre transfer_funds consulte ese estado.

Las trampas típicas

• Bloquear con PostToolUse: cuando corre, la transferencia ya salió. Para prevenir, PreToolUse.
• Normalizar con PreToolUse: las fechas desordenadas vienen en el resultado, no en la llamada.
• Pedirle al modelo que ignore o no repita algo: el dato igual entra al contexto, y sigue siendo probabilístico.
• Mejorar el prompt para pasar de 95% a 100%: ningún prompt llega a 100%; un hook sí.
• Sacar herramientas para evitar el problema: recorta funcionalidad en lugar de arreglarla.

En el examen

Preguntate dos cosas: ¿hace falta una garantía o alcanza con una guía? Si hace falta garantía, ¿el problema está en la llamada (PreToolUse) o en el resultado (PostToolUse)? Con esas dos respuestas casi siempre queda una sola opción.