An Agent Decision Record is one JSON object per consequential action, written before the action runs. A second record follows with the outcome, and a closing record ends the session. Every record is signed, and every record carries the hash of the one before it. This post walks through what's inside, block by block.
The eight blocks
principal_chain: who- The human sponsor (identity provider, subject, session), then the agent (id, version), then any sub-agents, with how the delegation narrowed the scope at each step.
authority_t0: what it was allowed, at that instant- The grants, and the things explicitly not granted, as they were at that moment, plus expiry and a hash of the stated purpose. Permissions change, so the record keeps the ones that applied when the decision was made.
horizon: what it knew- What the agent had
observed(with content hashes), and whether any of that content reached the action by value. That second part is decided from the bytes, not guessed. It also lists what wasaccessible_not_retrieved, the things it could have read and didn't, along with how that set was known. When the set can't be enumerated, the record abstains instead of inventing a list. action: what it tried to do- The tool, a hash of the arguments, every target (source and destination), and the state before and after.
policy: why it was allowed or stopped- The rule id and the verdict:
allow,soft_denyorhard_deny. For a human checkpoint it also records who decided and the hash of exactly what they were shown. Arguments are never stored, only hashed. outcome: what happened- Success, error or blocked, the affected references and a result hash. At the gateway, an outcome is what the agent reports, unless the agent's runner signs a receipt under a key you pinned.
witness: who else saw the chain- Optional countersignatures of an earlier head by separate witness processes, inside the signed body.
coverage: what this record cannot see- The insertion point, its transports and tool surface, how the signing key was held, the witness setup, and
uncovered: a stated list of blind spots.
Then comes sig: an Ed25519 signature over the canonical body, a key id, and the previous record's hash inside the signed body. The public key is never written into the chain. You pin it yourself.
A blocked action, as recorded
Here's the shape of an intent record for a call that was stopped. It's trimmed for reading; real records carry the full hashes and every block.
{
"schema": "adr/0.2", "seq": 4, "phase": "intent",
"prev_hash": "sha256:…",
"principal_chain": {"sponsor": {"idp": "okta", "sub": "u_x"}, "agent": {"id": "agt", "version": "1"}},
"authority_t0": {"grants": ["read_file", "write_file", "db.exec"], "not_granted": ["db.drop", "spawn_agent"]},
"horizon": {"observed": [{"ref": "repo/app.py", "hash": "sha256:…"}],
"accessible_not_retrieved": [{"ref": "repo/secret.env"}]},
"action": {"tool": "db.drop", "ref": "db/execs"},
"policy": {"rule_id": "explicitly_not_granted", "verdict": "hard_deny"},
"outcome": {"status": "pending"},
"coverage": {"insertion_point": "…", "uncovered": ["…"]},
"sig": {"alg": "Ed25519", "kid": "signer-1", "body_hash": "sha256:…", "value": "…"}
}
Reading it is a sentence: a named person's agent tried to drop a table it had never been granted, having read repo/app.py and with repo/secret.env within reach but unread, and the rule explicitly_not_granted stopped it. The outcome record that follows says blocked.
Why it says "unknown" so often
The fastest way to make evidence worthless is to let it guess. If the record claimed an agent "used" a file because it read it, a careful auditor would stop trusting every other claim in it. So the deterministic claims (content reached the action by value, or didn't) carry full confidence. The semantic claim (read and reasoned about, but not copied) is labelled as a heuristic. Anything the record can't establish goes into abstain.
What the verifier checks
dh verify checks every signature under the key you pinned, then the chain: sequence, hash links, the closing record's own count and head, and whether any intent never got an outcome. It flags reordering, truncation, splicing, a forged record under the right key id, and a record added after the session closed. Each of those is a test in the package. Run it on your own machine; you don't need us.
dh verify chain.jsonl --pub signer.key.pub
The concepts section of the docs has the full field reference and every verifier code.