halo-record

halo-record is an open-source Python library by Brian Kuan that creates tamper-evident, append-only audit trails for AI agents. Every tool call, model call, data access, and approval an agent makes becomes a hash-chained record that any party can independently verify — without trusting the operator who produced it. The project is licensed under Apache-2.0 and currently in Alpha (Development Status 3), with active releases on PyPI.

What It Is

halo-record implements the Halo Runtime Record format: a JSONL-based, hash-chained log where each record's integrity is anchored to the previous one using RFC 8785 canonicalization and SHA-256. The package ships a recorder, a conformance verifier, a witness client, and a report server — all in approximately 4,300 lines of pure Python with zero runtime dependencies. The format is open and free to implement; this package is the reference implementation. A TypeScript counterpart (halo-record-ts) ships the same chain format and witness protocol for the Node/JS ecosystem.

How the Integrity Model Works

Each record's hash is computed by taking the record (excluding integrity.hash), setting integrity.prev_hash to the previous record's hash, canonicalizing with RFC 8785, and SHA-256-ing the bytes. The first record's prev_hash is 64 zeros. Verification recomputes every hash and checks every link — no secret required. The library distinguishes between integrity (nothing was edited or reordered after the fact, provable by the chain itself) and completeness (no records were deleted and re-sealed, which requires an external witness holding periodic chain fingerprints). The halo anchor command supports both local and hosted witness workflows.

Adapter Matrix and Integrations

halo-record connects to a wide range of agent runtimes and telemetry sources without requiring code rewrites:

• Captured at the boundary: native trace() wrapper, MCP interceptor, LangChain/LangGraph callback, OpenAI Agents SDK hooks, Claude Code/Claude Agent SDK hook
• Ingested from existing telemetry: OpenTelemetry GenAI spans (covering CrewAI, LlamaIndex, and most OTel-instrumented frameworks), LiteLLM callbacks, Langfuse export, any gateway/reverse-proxy log

Every record carries a source tag so the report discloses how each piece of evidence was collected. Raw argument values never enter a record — arguments are hashed and stored only as a redacted summary.

Where It Fits in a Compliance Stack

The project positions halo-record as an evidence layer for AI governance frameworks, not a certification tool. The README maps it to several frameworks:

• SOC 2 / security questionnaires: verifiable Runtime Reports instead of screenshots and prose
• OWASP GenAI Security Project / Top 10 for LLM Applications: runtime evidence for excessive agency, tool misuse, and sensitive-information disclosure
• AARM (CSA): produces the tamper-evident action receipt specified in R5/R6
• EU AI Act: logging and record-keeping obligations for high-risk AI systems
• ISO 42001 / NIST AI RMF: operational evidence behind management-system controls

Update: Version 0.2.4

The latest release is v0.2.4, published on July 9, 2026, following a rapid release cadence since the project's initial v0.1.0 on June 12, 2026. The 0.2.x series introduced the authority snapshot mechanism (sealing session rules, MCP tool registries, and policy refs into the hash chain), the halo hook command for Claude Code's PostToolUse hook, and the halo export command for date-bounded evidence exports. The project has 52 GitHub stars and 6 forks as of the latest metadata, and the repository shows zero open issues.