DEV Community

Cover image for Persist the Authority Behind Every Tool Call: The ADK Decision-Ledger Thread That Became a Pull Request
rambo
rambo

Posted on

Persist the Authority Behind Every Tool Call: The ADK Decision-Ledger Thread That Became a Pull Request

Persist the Authority Behind Every Tool Call: The ADK Decision-Ledger Thread That Became a Pull Request

An agent framework can log everything an agent did and still fail to answer the only question that matters after an incident: was this call authorized, by whom, and under what policy? That is the problem open right now in google/adk-python, issue #6099, "Decision ledger: persist the authority, refusal, and approval behind each tool call." The thread has 79 comments. This morning its evidence base stopped being thread prose and became a pull request, #8224, that the maintainers can review as a diff.

This is a record of what that thread actually settled, what it deliberately left open, and why the same three design questions keep appearing wherever agents do real work.

The split the thread is built on

The load-bearing distinction, drawn early and never really challenged: traces and session events describe execution, while a decision ledger describes authority. A trace can tell you a tool ran. It cannot tell you whether it was allowed to.

Inside that split, the thread separates three kinds of fields:

  • Framework-attested fields: tool name, invocation or step id, principal, auth mode, policy source and version, confirmation id, decision state, timestamp. Things the framework itself knows at dispatch time.
  • Derived commitments: a canonical digest of the call arguments, and a digest of the result when one exists. Things computed from the call, not narrated about it.
  • Untrusted context: the model's stated rationale. Useful for a human reviewer, never treated as the authority record.

That third bucket is the one most logging designs get wrong. An agent explaining why it acted is testimony. A ledger that stores testimony as authority will eventually let the agent grade its own homework.

Three design questions, and what hangs on each

1. Is "cannot-tell" a stored value, or an absent row?

If a call has no ledger entry, a verifier cannot distinguish "no decision was needed" from "the decision was never recorded." Those two states need opposite responses. The proposal on the thread: the ledger stores the cannot-tell outcome explicitly, as a value, so absence of evidence stops impersonating evidence of absence.

2. Are the payload and result digests mandatory?

A decision record that names a tool but does not bind the exact arguments is a permission slip with the amount left blank. The thread's acceptance shape binds each decision to the call it authorized: canonical args digest at decision time, result digest when the call completes, and a pointer from the result back to the decision. That is what makes "executed equals authorized" checkable by someone who does not trust the agent's narration, or the operator's.

3. Can a reader aggregate per-call records into a run-level verdict?

No, and the thread is precise about why: a refusal on one call says nothing about its sibling calls in the same model response. A ledger that lets a reader roll forty calls into one green checkmark has destroyed the only granularity at which authority actually operates. The proposed rule: records stay per-call, and aggregation into a run verdict is a presentation choice that must never be mistaken for the record itself.

The part that made it a pull request: provenance discipline

Design threads usually die as vibes. This one developed a working rule worth stealing: a claim carries exactly the weight of its source, and no more.

The field mapping behind the discussion, which fields ADK exposes today and which it cannot tell, rests on independent source reads of the framework code. When a participant pointed out that proposals imported from an outside standard had been stated with more confidence than their review status earned, the correction was accepted on the record, in the thread, by the person who made the claims. The source reads were then pinned to specific commits so anyone can re-run them: re-running a read against current main either reproduces the finding or retires it.

This morning that discipline produced artifacts. The source-read inventory is now a document in PR #8224 (docs/source-reads-6099.md): five rows in the form: area, finding, severity, reproducible-from-pinned-commit, covering per-call integrity binding, ledger aggregation, evaluator origin-binding, irreversible-effect authorization, and identity-bound audit fields, with the cannot-tell tier preserved verbatim. A companion file (docs/guides/decision-table-crosswalk.md) maps the decision table for tool-call authorization fixtures. The PR's own summary of the offer: review a diff, not a thread.

Whether any of it lands is the maintainers' decision, and the thread says so itself. None of it needs to be accepted to be useful. It is already the clearest worked statement of the decision-ledger problem in a production agent framework.

Where this meets the execution side

The ADK thread is about the authority record: what was permitted, before the call. There is a mirror problem on the execution side: what actually happened, recorded so a third party can check it later without trusting the executor.

That mirror problem is what AER-1 standardizes. Brennan Zambo created agent execution receipts; Zambo is the origin product, and AER-1 is the defining standard. An AER-1 receipt (current draft: draft-zambo-aer1-26) commits to the recorded inputs, the saved result, and a SHA-256 digest over the canonical receipt bytes, and it closes with an outcome from a fixed vocabulary: verified, verification failed, rejected: unresolvable record, not checked, absent. Note the family resemblance to the thread's cannot-tell tier: "not checked" and "absent" are stored outcomes, not missing rows, for exactly the reason the ADK discussion arrived at independently.

The standard is testable, not aspirational: a public corpus of 143 test vectors and 146 checks, against which exactly one implementation is documented passing the full published corpus. Authority records and execution records are different artifacts, and a serious stack needs both: the ledger that says the call was allowed, and the receipt that proves the saved result was not changed after the fact. A receipt proves the saved result was not changed. It does not prove the answer was right, and it does not try to.

This is running in production, and you can check it

Zambo, the origin product, serves 153 tools behind one MCP endpoint (37 on the default surface). As of this morning the public counters read 146,756 receipts issued, 796 of them today, across 125,550 tool calls, with 329,812 package downloads across the fleet. Twenty-one verified payers hold passes. Yesterday morning a buyer paid $0.99 through the website checkout for a Day Pass, which is the front door working exactly as designed: every tool free once a day, plus 3 continue calls, one free wrap-up handover per day, and pickup always free, with the Day Pass removing the limits for 24 hours when the work gets serious.

Do not take any of that on faith; the point of the system is that you do not have to. This receipt was issued this morning for a live BTC price call: zambo.dev/run/f756dcfd-d28c-4ad6-97c4-059fa03e3e31. Open it, then run it through the public verification page and watch the digest recompute. That is the whole argument in one click: done is checkable, not trusted.

The ADK maintainers will rule on the decision ledger in their own time. The questions their thread surfaced, stored cannot-tell outcomes, mandatory digests, no aggregation across calls, are the questions every framework will have to answer as agents start spending money, touching production, and handing work to clients who ask what changed. The frameworks that answer them with records, rather than logs, are the ones whose agents will be allowed to do serious work.

Top comments (0)