A new open-source project called halo-record is being developed to create cryptographically verifiable audit trails for AI agents, recording actions such as tool calls, model interactions, data access and approval events in append-only logs.
The project is designed around a simple goal: make records of agent activity easier for customers, security teams and auditors to verify without relying entirely on logs controlled by the company operating the AI system.
Halo-record was created by Brian Kuan and is positioned as an evidence layer for AI-agent systems rather than a replacement for existing observability platforms.
The project stores runtime events in append-structured JSONL files. Each record is linked to the previous record through a SHA-256 hash, creating a chain in which changes to earlier entries can be detected during verification.
Before hashing, halo-record uses the RFC 8785 JSON Canonicalization Scheme so that the same record can produce a consistent digest when independently processed.
The first record in a chain uses 64 zeroes as its previous hash. Subsequent records contain the hash of the preceding entry, allowing a verifier to process the chain from the beginning and identify broken links.
Hash chaining alone, however, does not establish that a particular version of a complete log was the original one. An operator with control over the entire file could potentially rewrite history and create another internally consistent chain.
Halo-record addresses that problem with an external witness mechanism. The witness stores a record count and chain-head fingerprint, allowing later verification of whether previously committed history has been changed.
The project also supports optional RFC 3161 timestamping. The timestamp service receives the checkpoint state hash rather than the underlying audit records, providing evidence that a particular chain state existed by a certain time.
The system can ingest telemetry from several sources, including OpenTelemetry, LangChain and LangGraph, MCP servers, gateway logs, LiteLLM and Langfuse.
It also provides capture paths for the OpenAI Agents SDK and Claude Code, among other integrations. The OpenTelemetry route is intended to make the system usable with additional agent frameworks that emit compatible GenAI telemetry.
For Claude Code, halo-record can operate through a PostToolUse hook. This allows tool activity to be recorded without requiring changes to the agent’s application code.
The project can also attach agent-version and model information to runtime records through environment variables, allowing later reports to identify the software and model associated with recorded activity.
Another feature, called an authority snapshot, can capture hashed references to the configuration and controls governing an agent session. These references can include project rules, skills, MCP tool registries, Git commits and workspace information without requiring the underlying policy material itself to be stored in the record.
Halo-record is focused on observable actions rather than preserving an AI system’s private reasoning. Its audit records can describe actions such as tool calls, data access and authorization outcomes without attempting to store a model’s chain of thought.
The project also supports verification blocks that can attach policy or guardrail outcomes to individual records. A record can indicate whether an action was reported as allowed, blocked, modified or unverified.
Those cryptographic protections have clear limits. A recorded authorization result can be shown to have remained unchanged after it was written, but the record by itself does not prove that the underlying security check was correctly performed or that an action could never have occurred outside the logging path.
The same limitation applies to completeness. A perfectly hash-linked chain can still be incomplete if an action never reaches the recorder. The project’s documentation therefore places importance on where the capture mechanism is deployed and which events it can observe.
Halo-record offers both fail-open and fail-closed approaches depending on the integration. Some adapters can allow an agent action to continue when recording fails, while the native tracing wrapper can instead fail the action when evidence cannot be written.
Privacy is another consideration. Raw tool arguments are not intended to be stored directly. Instead, halo-record uses hashes, redacted summaries, detection of common sensitive patterns and entropy-based checks.
The project explicitly notes that this does not guarantee anonymization. Information that does not match a detection rule can remain in a record.
Because the chain is designed to remain verifiable, removing already committed information can break later verification. The project therefore recommends using privacy-safe pseudonymous identifiers and maintaining any mapping separately where appropriate.
Halo-record currently does not provide a built-in retention or pruning mechanism.
The project can convert audit data into self-verifying HTML Runtime Reports. A verifier can inspect the generated report in a browser without rerunning the original agent, while the report links the selected evidence back to the underlying chain.
More recent releases added date-windowed reports, allowing users to generate evidence for a defined period while retaining the relevant chain anchor and head.
Halo-record also supports CSV evidence exports and manifests that connect the exported material back to the original chain. The export can include timestamps, actions, agents, models, agent versions, identities, authorization decisions, tools, results, provenance and other audit fields.
The manifest includes a hash of the exported CSV. A later modification to that file would therefore cause the stored hash to no longer match the exported data.
The project describes this evidence workflow as suitable for use with governance, risk and compliance platforms, including Vanta and Drata.
Halo-record has also created mappings for security and governance frameworks. Its documentation maps runtime evidence to selected AIUC-1 accountability controls and to the OWASP security guidance for agentic applications.
Those mappings are presented as evidence-supporting references rather than as proof that installing the project makes an organization compliant with a particular standard or regulation.
The repository also discusses the relevance of runtime evidence to record-keeping obligations associated with the EU AI Act, as well as ISO 42001 and customer security questionnaires.
The Python project is licensed under Apache-2.0 and supports Python 3.8 and later. PyPI lists version 0.2.37 as the latest release found in the research, uploaded on August 23, 2026.
The project was first published on PyPI on June 12, 2026, with the initial 0.1.0 release followed by a series of 0.2.x updates.
The repository is still classified as an alpha-stage project, despite its growing feature set. The GitHub repository has accumulated dozens of commits and a growing number of public users and forks.
A separate TypeScript implementation, halo-record-ts, is also available for Node and TypeScript environments. The project states that the Python and TypeScript implementations use the same record format and witness protocol, allowing records from either implementation to be verified across implementations.
The project’s approach has been influenced by concerns among security and governance teams about the reliability of vendor-controlled AI-agent logs. Kuan has described situations in which organizations buying AI-agent systems must depend on the same vendor for evidence of what the system did.
The issue becomes more difficult as agents perform large numbers of autonomous actions. Kuan has pointed to a July 2026 incident involving an autonomous agent at Hugging Face that reportedly carried out about 17,600 actions over five days, highlighting the difficulty of reconstructing complex agent activity from conventional logs.
Halo-record is not presented as a mechanism for preventing such incidents. Its purpose is to make the resulting activity easier to reconstruct and verify when an investigation is required.
The project’s development model also separates the open record format and implementations from its planned hosted services. Kuan has indicated that a hosted witness service could provide a way to fund the project while allowing organizations to operate the recording system themselves.
At its core, halo-record is attempting to address a specific problem created by increasingly autonomous AI systems: not simply collecting records of what an agent did, but creating records that can be checked for subsequent alteration.
Its effectiveness will still depend on the capture point, the completeness of the telemetry and the independence of external witnesses. Those limitations mean the technology does not provide proof that every agent action was recorded, but it can provide stronger integrity guarantees for the records that are captured.
For organizations evaluating AI-agent systems, the distinction could become increasingly important as security reviews move beyond model behavior and begin examining the actions agents take across tools, data sources and approval systems.
Discover more from Aree Blog
Subscribe now to keep reading and get access to the full archive.
