Recibos de herramientas

Los recibos de herramientas son pruebas criptográficas de que un resultado exitoso de una herramienta provino del entorno de ejecución. Cuando los recibos están habilitados, las ejecuciones exitosas de herramientas reciben un resumen HMAC-SHA256 sobre la llamada y su resultado. El resumen se añade al texto del resultado de la herramienta y se devuelve al modelo como parte de la conversación.

El resultado práctico: el modelo no puede afirmar de forma convincente haber ejecutado una herramienta que no ejecutó, y no puede fabricar el resultado de una herramienta. Esas afirmaciones producen recibos faltantes o no válidos.

El modelo de amenazas

Un LLM es un generador de cadenas. Por defecto, nada le impide narrar una llamada a herramienta que nunca realizó (“Ejecuté git log y el commit más reciente es…”), o inventar un resultado para una llamada a herramienta (“La API del clima dice 72°F”, cuando la llamada expiró por tiempo de espera). Para un agente con autonomía, esto es más que un problema de corrección: es un problema de negación de responsabilidad.

Los recibos de herramientas cierran esa brecha con el constructo más económico posible: un MAC simétrico con una clave efímera en memoria.

Qué significa “ephemeral” aquí. Los caminos de canal-servidor mantienen una clave HMAC en memoria durante toda la vida del contexto de ejecución del canal. Las rutas de turno directo del agente crean un ámbito de recibo nuevo para el turno. En ambos casos, la clave permanece en memoria, nunca se envía al modelo y no es un verificador persistente entre sesiones.

Basu, A. (2026). “Recibos de herramientas, no pruebas de conocimiento cero: detección práctica de alucinaciones para agentes de IA.” arXiv:2603.10060.

Cómo funciona

1. Cuando los recibos están habilitados, el runtime crea una clave en memoria de 256 bits para el ámbito de recibo activo. Las rutas channel-server conservan esa clave en ChannelRuntimeContext; las rutas de turno directo crean un ámbito nuevo para el turno. La clave nunca se escribe en disco, nunca se envía al modelo y nunca se registra.

2. Después de cada ejecución exitosa de una herramienta, el entorno de ejecución calcula:

   receipt = HMAC-SHA256(key, tool_name || args || result || timestamp)
   

3. El recibo se anexa al texto del resultado de la herramienta como:

   [receipt: zc-receipt-<timestamp>-<base64url-digest>]
   

4. El resultado de la herramienta (con el recibo) se retroalimenta al modelo.

El modelo ve cada recibo en su historial de conversación. Puede repetirlos en el texto que produce para el usuario. Pero no puede generar un recibo nuevo válido: el HMAC requiere la clave de sesión, que el modelo no tiene.

Forma del recibo

zc-receipt-1774608496-gzpEBuUIRYX1vd4fQl4oYkqhq4-GnoJDStmlYzvQiWA
          ^ epoch seconds     ^ base64url(HMAC-SHA256 digest)

El prefijo zc-receipt- existe para que el detector de fugas no los oculte (los recibidos son seguros de mostrar; no contienen material secreto).

Qué detectan los recibos

Lo que no hacen los recibos

• No restrinjas la salida de texto. El modelo aún puede decir cosas no relacionadas con ninguna llamada a herramienta.
• No fuerces el uso de herramientas. Los recibos solo se generan cuando se llama a una herramienta; no ayudan con “el modelo respondió con conocimiento previo cuando debería haber buscado algo”.
• No cubras llamadas bloqueadas o fallidas. Los rechazos de aprobación, los timeouts, las llamadas bloqueadas y las devoluciones fallidas de herramientas son eventos de observabilidad o auditoría, no resultados de herramientas con acuse de recibo.
• No viajes a través de ámbitos de recibos. Las claves de recibo son efímeras, así que un recibo generado bajo un ámbito no puede verificarse después de que ese ámbito desaparezca.
• No aísles canales o conversaciones entre sí dentro de un mismo contexto de tiempo de ejecución de canal. Las conversaciones canal-servidor en ese contexto comparten la clave. El modelo de amenazas apunta a la fabricación de LLM dentro del tiempo de ejecución, no a la falsificación entre canales.
• No se extiende a generaciones en segundo plano o delegadas desacopladas. Las generaciones delegadas en segundo plano y en paralelo que se desacoplan del turno del usuario (background: true) no muestran recibos en el bloque visible para el usuario, ya que el recopilador por turno se renderiza antes de que esas generaciones finalicen. Los recibos dentro de subagentes delegados sincrónicos sí se capturan.

Ver recibos

En los registros de depuración

RUST_LOG=zeroclaw_runtime::agent=debug zeroclaw daemon

Genera:

DEBUG Tool receipt generated tool=shell receipt=zc-receipt-1774604899-fVRG...

En las respuestas visibles para el usuario

Si [agent.tool_receipts] show_in_response = true, la respuesta incluye un bloque al final:

Here's the weather in Istanbul: 16°C, sunny.

---
Tool receipts:
  weather: zc-receipt-1774608496-gzpEBuUIRYX1vd4fQl4oYkqhq4-GnoJDStmlYzvQiWA

En la propia salida del LLM

Debido a que el modelo ve los receipts en su contexto, puede repetirlos al describir los resultados de las herramientas. El detector de fugas está configurado para dejar pasar los tokens zc-receipt-* sin modificarlos, de modo que esta repetición funcione. Si tanto el runtime como el modelo incluyen un bloque de receipts, el usuario verá dos: elimine uno mediante reglas de formato específicas del canal.

Configuración

Propiedades de seguridad

• Clave efímera en memoria. Se mantiene solo en el alcance activo de recepción: las rutas channel-server usan el contexto de ejecución del canal, y las rutas de turno directo usan un alcance por turno. Nunca se persiste, nunca se registra, nunca está en el contexto del modelo. Comprometer el almacenamiento a largo plazo no aporta nada.
• Primitivas MAC estándar. hmac + sha2 del ecosistema de Rust.
• Carga insignificante. <1 ms por llamada de herramienta.
• No nuevas dependencias externas.

¿Qué recibos no

• No son pruebas ZK. El tiempo de ejecución puede verificar los recibos porque posee la clave. Un tercero no puede hacerlo.
• No está firmado cruzadamente con el hash de la conversación. La manipulación de la conversación anterior no invalida los recibos posteriores (el recibo solo cubre la llamada para la que fue calculado).
• No es un reemplazo para los puntos de control de aprobación. Un recibo demuestra que se realizó una llamada; no decide si debería haberse realizado.

Estado actual

Ver también

• Seguridad → Resumen
• Niveles de autonomía: la capa de políticas que decide si se realiza una llamada que amerita un recibo
• Referencia → Config: referencia de configuración generada