When to use this / when not to use this
Use this when
- AI-assisted changes need a portable review, handoff, audit, or policy record tied to repository state.
- You can define a bounded capture policy and distinguish observed evidence from unavailable provider context.
Do not use this when
- You need to capture private reasoning, secrets, or every prompt as a prerequisite for trust.
- You want the receipt to replace code review, tests, security analysis, or human accountability.
Define the evidence boundary before recording
A useful recording starts with a precise claim: this agent session began from a known repository state, observed a bounded set of actions, and ended with a particular patch and set of checks. It does not claim that every model thought was captured or that the agent caused every byte written while the recorder was running. Sources: SLSA provenance specification, in-toto Statement v1.
Take the baseline before launching the agent. Record the repository root, current commit, worktree status, active instruction files, tool versions, and recorder policy. Existing dirty files must be named explicitly so a later verifier can distinguish prior user work from session activity.
Minimum start record
- Repository identity, merge base, HEAD commit, branch, and initial git status.
- Hashes and paths for AGENTS.md, CLAUDE.md, installed skills, and relevant tool configuration.
- Recorder version, schema version, clock source, platform, and capture policy.
- A session identifier generated outside the model transcript.
- Explicit exclusions such as raw prompts, secret-bearing output, or unrelated filesystem roots.
Capture typed events, not one giant transcript
A transcript is presentation. Evidence needs stable event types and relationships. Commands, tool calls, file observations, git transitions, approvals, and quality checks should each have their own payload and source. A provider event can explain intent, while git and filesystem observations establish what changed; neither should silently stand in for the other.
Append events and chain their hashes so removal or reordering becomes detectable. Canonicalize the payload before hashing, keep timestamps as supporting context rather than the ordering authority, and assign a monotonic sequence within the session. The recorder should survive missing provider logs by degrading confidence instead of refusing to finalize. Sources: RFC 8785 JSON Canonicalization Scheme.
Useful event distinctions
- Proposed tool arguments versus the normalized arguments actually sent.
- Command start, command exit, and the captured stdout or artifact reference.
- Filesystem observation versus a git diff that proves the final tracked change.
- Automated policy decision versus explicit human approval.
- A check that ran and failed versus a check that never ran.
The recorder observes the session and creates immutable evidence; the verifier consumes only the receipt and repository state.
Source: AgentReceipt replay contract- 01BaselineGit state + instructions
- 02ObserveCommands + files + provider events
- 03FinalizePatch + gates + artifact hashes
- 04SignCanonical receipt manifest
- 05VerifyIndependent integrity and diff checks
Finalize a receipt around the artifact graph
At stop time, derive the final patch against the declared baseline, inventory untracked files, capture the terminal git state, and attach quality-gate results. Large or sensitive artifacts should live beside the receipt under content-addressed names; the manifest stores their hashes, media types, sizes, and redaction status.
Sign the canonical manifest after every reference is fixed. Signing a human-readable HTML or Markdown report is brittle because formatting changes alter the bytes without changing the evidence. A stable JSON encoding or another versioned canonical form gives independent implementations something deterministic to verify. Sources: DSSE envelope specification, RFC 8785 canonical JSON.
Receipt contents worth keeping separate
- Session manifest and hash-chain head.
- Patch, untracked-file inventory, and start/end repository snapshots.
- Instruction manifest and provider-capture confidence.
- Quality-gate commands, exit codes, and bounded output references.
- Signature, public-key identifier, and canonicalization version.
Verify the receipt from a clean process
Verification should work without invoking the model. Recompute every artifact hash, walk the event chain, verify the signature, and compare the recorded final patch with the current worktree or a checked-out commit. The verifier must report which layer failed: schema, integrity, signature, baseline, patch, or quality evidence. Sources: Sigstore blob verification documentation.
A green receipt means the evidence is internally consistent and matches the inspected repository state. It does not mean the code is correct, the agent followed every instruction, or the tests were sufficient. Those remain review questions; the receipt makes them answerable from a stable record.
Verification should fail closed when
- An artifact is missing, has a different digest, or resolves outside the receipt root.
- The event sequence has a duplicate, gap, or incorrect previous-event hash.
- The signing key is unknown, revoked for the claimed time, or the signature is invalid.
- The current patch differs from the patch bound into the receipt.
- A required gate is absent even if all recorded gates passed.
A receipt schema that separates claims from evidence
This reduced manifest is the boundary I use when reasoning about AgentReceipt: stable session identity, an explicit repository baseline, content-addressed artifacts, named gates, and a signature over the canonical payload.
{
"schema_version": 1,
"session_id": "ar_ses_01J5Y7M8K2",
"repository": {
"head": "9c2f7d1",
"baseline_status_sha256": "sha256:31f1…"
},
"event_chain": {
"count": 42,
"head_sha256": "sha256:a842…"
},
"artifacts": [
{ "path": "diffs/final.patch", "sha256": "sha256:b71c…" }
],
"gates": [
{ "name": "typecheck", "exit_code": 0, "evidence_ref": "events:40" }
],
"signature": {
"algorithm": "ed25519",
"key_id": "sha256:44ad…",
"value": "base64:MEUC…"
}
}| Path | Type | Requirement | Purpose |
|---|---|---|---|
| repository.head | git object id | required | Fixes the repository state from which the session claim begins. |
| event_chain.head_sha256 | digest | required | Detects removed, reordered, or mutated events. |
| artifacts[].sha256 | digest | required | Binds patches, logs, and snapshots without embedding their bytes. |
| gates[].evidence_ref | event reference | conditional | Distinguishes a gate that ran from one merely asserted in a report. |
| signature.value | base64 signature | derived | Authenticates the canonical manifest after every reference is fixed. |
Implementation examples
Concrete commands and data shapes you can adapt.
agentreceipt start --watch
# work with the coding agent in the same repository
agentreceipt stop
agentreceipt replay --session <id> --json > replay.json
agentreceipt verify diff --session <id> --against merge-base --json{
"session_id": "01J...",
"sequence": 42,
"type": "command.finished",
"source": "shell-observer",
"payload_sha256": "a842...",
"previous_event_sha256": "7d11...",
"captured_at": "2026-08-10T09:42:17Z"
}Decision log
The choices that shape the design—and what each choice costs.
- Run as a sidecar
The recorder can observe different coding agents without becoming their launcher or proxy.
Tradeoff: Provider-specific intent capture is best-effort and may be less complete than filesystem evidence. - Keep raw prompts out of exports by default
Most verification questions can be answered from hashes, actions, patches, and gates without retaining sensitive conversation data.
Tradeoff: A reviewer may know which instruction artifact was active without seeing every natural-language exchange. - Sign the manifest, not the report
Canonical machine data is stable across renderers and can be verified by a small standalone tool.
Tradeoff: Human reports must preserve links back to signed fields instead of being treated as the evidence itself.
Failure cases
What breaks, how it presents, and the recovery boundary.
- The repository was already dirty
- Signal
Start status contains modified or untracked paths.
- Response
Record them as baseline state and exclude them from causal claims unless the session later changes them.
- Provider logs cannot be matched
- Signal
No provider session has sufficient repository or time correlation.
- Response
Finalize from git and filesystem evidence, mark provider coverage unavailable, and lower confidence explicitly.
- The patch changes after stop
- Signal
Current diff digest differs from the receipt's final patch digest.
- Response
Fail diff verification and report the added, removed, or modified paths rather than rewriting the receipt.
Repositories and primary references
Read the implementation, specifications, and tool documentation behind the article.
Related projects
Inspect the systems that ground this guide in implementation work.
- Go · CLI · AI ToolingAgentReceiptLocal-first Go CLI for recording AI coding sessions and producing verifier-ready replay evidence.
- TypeScript · CLI · AI ToolingSkills DoctorTypeScript CLI for auditing Claude/Codex Agent Skills for quality, structure, scoring, and repair readiness.
- TypeScript · CLI · AI WorkflowsRitualAITypeScript CLI that scans local Claude/Codex prompt history and turns repeated workflows into reusable skills.
Last updated: