nodrail

All guides

Agent receipts and run history: make every AI agent end with a verdict

Preview guide. We’re verifying these steps against the public installation.

By Nodrail · 6 min read

On this page
  1. Why every agent should end with a verdict
  2. What a receipt looks like
  3. What the run records around the receipt
  4. How receipts feed gates
  5. How receipts feed reports and Insights
  6. What a receipt does not prove
  7. Can a passing receipt be reused after a push?
  8. Next steps

An agent receipt is a short, structured block an AI agent writes at the end of its work: a verdict such as pass or fail, the categories of what it found, and the usage it reports. Recorded against a run with the time and step, receipts become a history you can check before risky actions and count afterwards. In Nodrail, receipts feed gates (has QA passed since the last change?) and budgets, and in Nodrail Cloud they feed Insights, such as how often a gate held work and how often a person overrode it.

This guide uses Claude Code with example agents dev, qa, reviewer and github. The names are yours to change.

The agent names, rules and numbers in this guide are illustrative. Adapt them to your own agents and test them before relying on them.

Why every agent should end with a verdict

A subagent usually ends with a paragraph. "I ran the tests and most of them pass, there is one flaky case I left for later." A person can read that. A rule cannot, and a person reading forty of them a day stops reading carefully.

A verdict is one word you agree on in advance. qa ends with pass or fail. reviewer ends with ship, ship_with_debt or block. Now three things become possible:

  • a rule can check the verdict before the next action;
  • a person can scan a run and see where it went back;
  • you can count verdicts over many runs.

What a receipt looks like

In the local Claude Code integration, the receipt is a fenced block at the end of the agent's final message, with the info string nodrail-receipt:

The fix handles the empty-list case. Two tests added.

```nodrail-receipt
verdict: pass
findings: [correctness]
```

Claude Code's SubagentStop hook includes the subagent's last message, so the integration can read the block when the step finishes. The block must be the last thing in the message: a receipt followed by more text is treated as a quote and ignored. Ask for it in each agent's instructions, for example: "End your final message with a nodrail-receipt block containing your verdict."

What to record:

FieldWhat it is for
verdictThe one word a gate checks. Pick a short, fixed list per agent. Verdicts are lowercased and spaces become _.
findingsCategories, not prose: correctness, tests, security, style. They let you count what kinds of problems each agent finds.
tokens, usdOptional numbers: the usage the agent reports, if your setup provides it. Budgets on tokens and usd add these up.

Keep the detail in the message. The receipt is for rules and counts.

What the run records around the receipt

The receipt is one part of the run history. The integration also records:

  • Run: the piece of work. The key is NODRAIL_RUN when it is set; otherwise the repository and branch the session started on, kept for the whole session, or the session itself on the default branch.
  • Steps: each dispatched agent, with its start and finish. In Claude Code, tool calls made by a subagent carry its agent id and type, so each action is tied to the step that made it.
  • Actions: every tool call Nodrail decided in the run, with the decision.

Who a step belongs to comes from the dispatch the integration observed, not from the receipt. An agent field written in a receipt is ignored.

Locally, the history is one JSON Lines file per run in your repository's git directory. You can read it with the CLI:

nodrail-policy runs list
nodrail-policy runs show github.com/acme/app/fix-42
nodrail-policy runs report

How receipts feed gates

A gate holds an action until the run contains the right steps. For example, "do not dispatch github until qa passed and reviewer said ship, both after the last dev work":

- required_engine_version: 3

- list: builders
  items: [dev, infra]

- gate: Review before the pull request
  tool: claude-code
  operation: agent
  resource: { kind: agent, match: exact, value: github }
  requires:
    - { agent: qa, verdict: pass, since: { list: builders } }
    - { agent: reviewer, verdict: [ship, ship_with_debt], since: { list: builders } }
  otherwise: require_approval

This fragment shows only the gate. A gate never allows on its own: the dispatch still needs an allow rule. A step without a receipt, or a receipt without a verdict, does not meet a requirement. The gate fails closed. The full rules file and what since means are in how to stop an AI coding agent from opening a pull request before QA (preview).

How receipts feed reports and Insights

Once runs carry verdicts, some questions get numbers. Locally, nodrail-policy runs report counts, per agent, the steps, the verdicts and the actions that were held.

In Nodrail Cloud, the history is shared across the machines and agents connected to a workspace, and Insights goes further:

  • Per gate: how many actions it checked and held, the share of runs where it did not hold the first action it checked, and how often a person approved a held action anyway. A high override rate means the gate is wrong or the process is being skipped. Both are worth knowing.
  • Per budget: how many actions it held, and in which runs.
  • Per agent: steps, verdicts, steps that ended without a receipt, back-steps (the agent started again after a check sent the work back), and contradicted passes (an accepted verdict that the same agent reversed in a later step with no builder work in between).

In Cloud, the Runs view of Activity lists each run, and its timeline shows it step by step. See pricing for Cloud plans.

What a receipt does not prove

  • A receipt is what the agent said. An agent prompted to say pass will say pass. The receipt does not show that the tests were good. It shows that a qa step ran, at a recorded time, in a recorded run, and reported a verdict. That is still more than most agent setups have.
  • Usage is self-reported. Token and dollar budgets limit only what agents report. Tool-call counts come from the actions Nodrail recorded, not from receipts.
  • The run key is declared, not authenticated. Like agent names, it is what the integration reports.
  • The local history is a file. Anyone who can write to your repository's git directory can change it, so deny agent writes under .git. A shared, server-side history is a Cloud feature.
  • Nodrail does not check receipts against CI results.

Can a passing receipt be reused after a push?

A receipt still describes the revision QA reviewed. In our GitHub merge check pilot, QA passed on 05f39ae. After a formatting-only push, the current head was 3fed234. The runner checked the quota independently on both commits, but only a fresh QA receipt could satisfy the gate on the new one. Read the GitHub merge check pilot.

Next steps

Keep the receipt alongside the decision that used it. Record who reported a verdict and when, so reviewers can interpret the evidence. Read the APF run-history contract (preview) and see how receipts feed a QA gate (preview).