halo-record

Registros de ejecución para agentes de IA a prueba de manipulación: la traza de auditoría que el proveedor opera pero no puede editar.

Cada acción que realiza tu agente (llamadas a herramientas, llamadas al modelo, acceso a datos, aprobaciones) se convierte en un registro en un log de estructura anexa y encadenado por hashes. Cualquier parte que posea un checkpoint de la cadena puede verificar que los registros anteriores nunca fueron alterados, sin tener que confiar en quien los produjo. Cuando el equipo de seguridad de un cliente pregunta «¿qué hizo tu agente con nuestros datos?», le entregas un enlace en lugar de un párrafo. Las revisiones de seguridad ya formulan preguntas sobre IA junto a la lista de verificación SOC 2, y hoy una garantía por escrito todavía se acepta. La apuesta detrás de este proyecto es que eso no durará mucho.

El formato de registro es abierto y libre de implementar. Este paquete es la implementación de referencia: grabador, verificador, cliente testigo y servidor de informes.

Por qué puedes confiar en este código

Se te pide que pongas un grabador dentro de tu agente. No deberías aceptarlo sin más:

• Cero dependencias en tiempo de ejecución. Solo la biblioteca estándar. pip install halo-record instala exactamente un paquete.
• Sin llamadas de red, salvo el testigo, que es opcional y recibe solo un contador de registros y una huella de la cadena. El contenido de los registros nunca sale de tu infraestructura.
• Las entradas en bruto nunca entran en un registro. Los argumentos se hashean y se almacenan solo como un resumen redactado — nunca el valor en bruto. La redacción es de mejor esfuerzo (regex sobre formatos comunes de secretos y PII): trátala como defensa en profundidad, no como una garantía.
• Lo suficientemente pequeño para auditar. ~4.300 líneas de Python. Puedes leerlo todo en una tarde.
• Apache-2.0.

Demo de 60 segundos

No se requiere ningún agente. Con uv, no hay nada que instalar:

uvx --from halo-record halo demo --serve

o la forma clásica:

pip install halo-record
halo demo --serve

Cualquiera de las dos opciones genera un proveedor ficticio de agentes de soporte con dos clientes, atestigua las cadenas, sirve sus informes de ejecución con acceso restringido y abre la consola del operador en tu navegador. Luego prueba la prueba de manipulación: elimina una línea de uno de los archivos .jsonl y recarga. El informe lo detecta.

Registra tu propio agente

Una línea en el límite:

from halo import trace

agent = trace(run_my_agent, profile="my-agent", log="audit.jsonl")   # wraps your entrypoint; records every tool call to ./audit.jsonl

Sin log=, los registros van a ~/.halo/my-agent.jsonl (una cadena por agente). O usa el adaptador para lo que ya ejecutas (consulta la matriz a continuación). Luego genera el informe:

halo report audit.jsonl -o report.html    # one chain -> self-verifying HTML
halo serve ./records --port 8721          # all tenants, gated per customer

El inicio rápido termina cuando ves el informe de ejecución de tu propio agente en un navegador. Si obtuviste un archivo JSONL y ningún informe, algo está mal: abre un issue.

Conéctalo a lo que ya ejecutas

Cada registro lleva una etiqueta source, por lo que el informe revela cómo se recopiló cada pieza de evidencia. Los registros capturados e ingeridos residen en la misma cadena.

Cualquier cosa que emita spans GenAI de OpenTelemetry (CrewAI, LlamaIndex y la mayoría de los frameworks de agentes con instrumentación OTel) llega a la cadena a través del adaptador OTel, y el paquete TypeScript incluye adaptadores nativos para el Vercel AI SDK y el ecosistema de agentes JS. ¿Te falta un adaptador para tu stack? Abre un issue. La mayoría de los adaptadores tienen alrededor de cien líneas.

Registra tu agente de codificación

Claude Code dispara un hook PostToolUse después de cada llamada a una herramienta. Apúntalo a halo hook y cada acción — escrituras de archivos, comandos de shell, llamadas al conector MCP — se convierte en un registro en una cadena local. Sin cambios de código; una entrada de configuración:

{
  "hooks": {
    "PostToolUse": [
      {"matcher": "*", "hooks": [{"type": "command", "command": "halo hook"}]}
    ]
  }
}

Añade eso a ~/.claude/settings.json y los registros se guardan en ~/.halo/audit.jsonl (puedes cambiarlo con $HALO_LOG). Las herramientas de orquestación pura que no tocan datos, red ni estado externo se omiten — la cadena registra acciones que cruzan el límite de confianza, no el pensamiento. Establece HALO_HASH_ONLY=1 para registrar hashes de contenido sin resúmenes. Establece HALO_AGENT_VERSION (y opcionalmente HALO_AGENT_MODEL) para vincular cada registro al build del agente que lo produjo — cuando un auditor pregunta por la versión que se ejecutaba en un período determinado, la exportación responde por columnas en lugar de por memoria.

Si necesitas que el informe responda «¿bajo qué reglas ocurrió esta ejecución?», configura HALO_AUTHORITY_FILE con una instantánea JSON de la autoridad efectiva para la sesión. Mantenlo seguro para la privacidad: hashes y referencias, no prompts en bruto, texto de políticas privadas, secretos ni esquemas completos de herramientas.

{
  "snapshot_id": "auth_2026_07_08T1100Z",
  "captured_at": "2026-07-08T11:00:00Z",
  "scope": "session",
  "workspace": {"path_hash": "sha256:...", "git_commit": "abc1234"},
  "refs": [
    {"kind": "project_rules", "id": "CLAUDE.md", "hash": "sha256:...", "loaded": true, "truncated": false},
    {"kind": "mcp_tool_registry", "id": "filesystem", "hash": "sha256:..."}
  ],
  "omissions": [{"kind": "private_policy", "reason": "customer_secret", "hash": "sha256:..."}],
  "stale_if": ["project_rules_hash_changed", "mcp_tool_registry_hash_changed"]
}

HALO_AUTHORITY_FILE=./authority.json halo hook

La instantánea se sella en la misma cadena de hashes que los registros de acciones. Un buen valor predeterminado es una instantánea a nivel de sesión al inicio, más una nueva instantánea cuando cambian las reglas, Skills, hooks, registros de herramientas MCP o la política de compactación. Para mantener las sesiones largas ligeras, los registros consecutivos con el mismo authority.snapshot_id se compactan después de la primera instantánea completa: los registros posteriores conservan solo {"snapshot_id": "...", "same_as_previous": true}. El puntero permanece encadenado por hash, pero el voluminoso bloque de refs/omissions/stale-if no se repite en cada acción. Luego, lo habitual:

halo verify ~/.halo/audit.jsonl
halo report ~/.halo/audit.jsonl -o report.html

Cualquier runtime de agente que exponga un hook posterior a la acción puede alimentar el mismo comando: el hook lee un evento como JSON en stdin y anexa un registro.

Integridad vs. completitud (lee esta parte)

Sé preciso sobre qué demuestra cada capa — porque son afirmaciones distintas, y las diferencias son el punto:

Una cadena en manos del propio operador demuestra integridad relativa a una cabeza establecida: dada una cabeza de cadena que alguien ya posee, cualquier edición, reordenamiento o eliminación en los registros anteriores se vuelve detectable. Por sí sola — antes de que alguien externo al operador haya visto una cabeza — una cadena demuestra consistencia interna, no historia: un operador podría eliminar un registro y volver a sellar, y el nuevo archivo se verificaría. La cadena se vuelve históricamente confirmada en el momento en que su cabeza sale del control del operador.

Eso es el testigo: una parte externa al operador que guarda huellas periódicas de la cadena (un contador y un hash de la cabeza, nada más). Los checkpoints hacen detectable la reescritura de la historia confirmada, y un checkpoint omitido es en sí mismo un evento visible:

halo anchor audit.jsonl witness.jsonl           # anchor a checkpoint to a local witness
halo anchor audit.jsonl witness.jsonl --check   # completeness verdict against it

Un límite más, dicho claramente: ni la cadena ni el testigo demuestran que cada acción del mundo real pasó por el grabador. Eso es completitud de captura — una propiedad de dónde se sitúa el grabador en el stack (instrumentación nativa, hooks, ingesta por gateway), no de ningún hash. Los registros llevan una etiqueta source precisamente por esta razón.

Cualquiera puede ejecutar un testigo. Un testigo que ejecutas tú mismo confirma la historia para ti; confirmarla para tu cliente requiere un testigo en quien ellos tengan motivos para confiar. El protocolo es abierto en cualquier caso.

Un testigo alojado y reconocido es como este proyecto se sostendrá. Acceso anticipado: [email protected].

Dónde encaja en un stack de cumplimiento

halo-record es una capa de evidencia, no una certificación. Produce el artefacto que los marcos de evaluación piden una y otra vez con diferentes palabras:

• Cuestionarios de seguridad y revisiones SOC 2: responde las secciones de IA con un informe de ejecución verificable en lugar de capturas de pantalla y prosa.
• AIUC-1: produce el registro a prueba de manipulación (E015.4) y los registros de cadena de ejecución completa con eventos de autorización (E015.2) que exigen los controles de Responsabilidad del estándar — evidencia de ejecución continua, no reconstruida en el momento de la auditoría.
• OWASP (Proyecto de Seguridad GenAI): la evidencia de ejecución detrás de los riesgos de comportamiento de los agentes en el OWASP Top 10 para Aplicaciones Agénticas 2026 y el LLM Top 10 — secuestro de objetivos, mal uso de herramientas, abuso de identidad y privilegios — registrada como lo que el agente realmente hizo, con qué herramientas y datos.
• AARM (CSA): produce el recibo de acción a prueba de manipulación que especifica AARM (R5/R6) — encadenado y atestiguado de forma independiente. halo-record es la capa de recibos; combínalo con un gateway de aplicación de políticas para un sistema AARM completo. Consulta AARM.md.
• Controles de Confianza Agéntica (ATC): los registros de ejecución detrás de los controles de evidencia del ATC — registro de acciones a prueba de manipulación (RBM-03) y atestación de autoridad (AID-05) en un único registro encadenado, con la capa de testigos más allá de ambos. Consulta ATC.md.
• EU AI Act: obligaciones de registro y conservación de registros para sistemas de IA de alto riesgo.
• ISO 42001 / NIST AI RMF: la evidencia operativa detrás de los controles del sistema de gestión.

Nada de esto certifica nada por sí mismo. Le da a tu evaluador algo verificable que examinar. Los límites — lo que halo-record deliberadamente no hace y qué decir cuando un revisor pregunta — están documentados en LIMITS.md.

CLI

halo verify   validate schema + hash chain (non-zero exit on failure; CI-friendly)
halo report   render a chain as a self-verifying HTML Runtime Report
              (--from/--to: a date-windowed report covering only the review period)
halo serve    serve per-tenant reports over HTTP, access-scoped per customer
halo grant    designate a report recipient (email or domain)
halo anchor   witness a chain head, or --check completeness
halo demo     scaffold the full vendor demo (record -> witness -> gated report)
halo export   date-bounded evidence export: CSV + manifest tied to the chain head
halo sample   emit a valid example log
halo hash     canonical sha256 of a JSON value
halo hook     Claude Code PostToolUse hook

Modelo de integridad

Para calcular el hash de un registro: toma el registro excluyendo integrity.hash, con integrity.prev_hash establecido al hash del registro anterior; canonicaliza con RFC 8785 (JSON Canonicalization Scheme); aplica SHA-256 a los bytes. El prev_hash del primer registro son 64 ceros. La verificación recalcula cada hash y comprueba cada enlace. No se requiere ningún secreto; ese es el punto.

¿Crees que puedes manipular una cadena sin que el verificador lo note? Los intentos y resultados se encuentran aquí.

Referencia completa de campos: halo-record.schema.json.

TypeScript

El mismo grabador se distribuye para Node: halo-record-ts. Mismo formato de cadena, mismo protocolo de testigos. Los registros escritos en cualquiera de los dos lenguajes se verifican con cualquiera de los dos verificadores.

Contribuciones

Se aceptan issues, discusiones y pull requests — consulta CONTRIBUTING.md para las reglas básicas (versión corta: pruebas requeridas, PRs pequeños, los cambios de esquema se discuten primero).

Licencia

Apache-2.0