ADR 298 · Accepted

The invocation history binds a check to its proposal

Context

A tool invocation rule sees the earlier calls of its run through ToolInvocationHistory (ADR-216): tool, outcome and target per entry. That is enough for "a read ran before the write". It is not enough for "the check ran on exactly this proposal, and the record is still what the check saw": the history does not say with which arguments a call ran, nor what it observed. A model can check one variant and write another, or check, wait while an editor changes the record, and write; a rule cannot tell either from a correct sequence.

Time does not close the second gap. A TYPO3 record's tstamp is the EXEC_TIME of the request or process that wrote it, its start and not the moment of the write, so a writer that started before the check and wrote after it leaves an older stamp than the check.

The history is persisted inside the sealed suspended state of a run (ADR-114), next to the pending calls, and ToolInvocationHistory is @api.

Decision

An entry may carry arguments and state. Both are digests: v1: followed by the hex HMAC-SHA256 of a canonical form, keyed with the installation's encryption key (SYS/encryptionKey) joined with a purpose string of nr-llm, the construction TYPO3's HashService uses. Each field has its own purpose string (nr_llm.history.arguments and nr_llm.history.state), so an arguments digest never equals a state digest of the same value. PHP's hash_hmac() computes it, because TYPO3 13.4's HashService offers SHA-1 only. An empty encryption key gives no digest.

  • arguments is the digest of the call's final arguments, after any input a human typed (ADR-216 item 5). The runtime fills it at every append() whose arguments can be encoded.

  • state is the digest of a record state a tool observed: the canonical form of an object with the table, the uid, and the listed fields as a map from field name to value (so their order does not matter). Only an ok result carries one; withObservedState() on an error result is ignored, as withWriteTarget() is.

One public class, InvocationDigests, computes both. arguments(array) returns the digest of an arguments map, or null when it cannot be encoded. observe(table, uid, fields, execution) reads the record as the workspace of the run shows it (ADR-260, the workspace the writing tools write into), takes exactly the listed fields, writes each value as a string (null stays null), and returns an ObservedState. It returns null, and so no digest, when that workspace shows no such row (deleted, a version of another workspace, a table without versioning seen from a draft workspace), the table is unknown, the field list is empty, or a listed field is not a database column of the table. It reads with the deleted restriction only, so a hidden record has a state. ObservedState holds the digest and the field values it was computed from, as the public readonly properties digest and values; its constructor is @internal and refuses anything but the v1: format, so tools take one from observe(). A tool reports it through ToolResult::withObservedState(ObservedState), kept as the public readonly property observedState and carried by every ToolResult wither, and the runtime copies its digest into the entry.

A rule computes arguments() of the call in front of it and observe() of the same record and fields now, and compares both with the most recent ok entry of the check tool, so a later check of another variant replaces an earlier one. Equal means the same final arguments and the same fields as the run's workspace shows them. When either returns null at that moment, the rule refuses. Which fields count is the tool's and rule's shared declaration: the fields the check judged, not tstamp, which a hook moves without a relevant change (the same reason ADR-184 gives).

Canonical form, version 1. The JSON encoding of the value, where an array that is not a list has its keys sorted as strings (ksort(SORT_STRING)) and stays an object, and a list keeps its order. Slashes and Unicode are not escaped, integers and numeric strings stay apart, floats are written with serialize_precision -1, and a float without a fraction whose magnitude is below 2^53 is written as an integer (-0.0 as 0): a suspended state does not keep the fraction, so 1.0 and 1 must not differ across a resume. PHP writes larger integral floats up to about 1e17 without a fraction as well, so they share the digest of the equal integer, as they do after a resume; every other float keeps its JSON float form. Whether an array is a list is decided before its keys are sorted. A value that cannot be encoded (JSON_THROW_ON_ERROR) gets no digest. A new canonical form is a new version prefix.

What a digest is for. The history already lies in a sealed store next to the arguments themselves, so keying adds no secrecy there. It keeps a digest meaningless outside its installation and useless for guessing short values should it ever leave that store, at the cost of one HMAC per entry.

The stored format stays compatible. Both keys are optional, and an entry without a digest omits the key; it is never stored as null. An entry stored before this change has neither; a rule that needs a digest treats a missing one as not matching and refuses. A present key must match ^v1:[0-9a-f]{64}\z; any other value, an unknown version included, makes the whole history unreadable and incomplete, as a malformed entry does today. A runtime before this change drops both keys when it rebuilds the entries, which again fails closed.

The public surface grows additively. ToolInvocationHistory::append() gains two optional trailing ?string parameters (null omits the key), an entry's array shape gains the two optional keys, ToolResult gains withObservedState(ObservedState) and the property observedState, and InvocationDigests and ObservedState are public, so that a tool and a rule, in nr-llm or outside it, compute the same digests.

A check tool judges the values of the ObservedState it reports and reads the record no second time, so its verdict and its digest describe the same snapshot. A record changed and changed back between two reads cannot make a check pass on values it never judged. A binding rule does not require a complete history (requiresCompleteHistory() is false): an incomplete history after a retry still holds the check the model makes next.

A binding rule is asked when the call runs. Its answer depends on the history, which before the approval card does not hold the calls of the same turn, so it does not implement PreApprovalInvocationRuleInterface (ADR-293). The write runs after the check of the same turn and is compared then; in a run with a pinned process the check may already have run before the card, which changes nothing for the rule.

The first users are a check tool and the contract rule of the A2A page metadata skill: a write of the skill must be preceded by a successful check of exactly its arguments, and the record must still be in the state that check observed. The check tool takes exactly the write tool's arguments, so the same map can be checked and written. A check whose verdict is negative reports failed, so only a passed check counts.

Consequences

  • ●● A rule can require that a check ran on the very proposal being written and that the record has not changed since; checking one variant and writing another, and writing over a changed record, are refused before the write runs. No clock is compared. A change between the rule's comparison and the write itself is not seen, as with ADR-184.

  • ◑ The refusal comes after the approval: an editor can approve a write that is then refused, and nothing is written. After an ADR-184 re-ask the second approval can be refused the same way.

  • ◑ Old suspended states keep resuming; their entries have no digest, so a binding rule refuses until the model checks again.

  • ◑ Rotating the encryption key, or changing the canonical form, invalidates the digests of waiting runs; a binding rule asks for a new check, the conservative direction.

  • ◑ The tool and the rule must declare the same fields; the shared class makes the read and the digest identical, not the choice of fields. A field outside the list can change without being noticed, as with ADR-184.

Net Score: 0

Alternatives considered

Store the arguments. Rejected: ADR-216 item 7 keeps policy metadata from copying arguments, and a second copy in the history serves no rule better than a digest.

Compare clocks. Rejected: a record's tstamp is the writer's start time, so "changed after the check" cannot be told from it.

A plain SHA-256. Rejected for the reasons above; it would also make digests comparable across installations.

Bind through the target only. Rejected: a target names the record, not the values; two variants for the same record share it.

← All ADRs