Notes/Tokening

Tokening Adds a Flight Recorder That Proves What AI Agents Did With Their Grants

Tokening hands AI agents narrow grants for one action at a time. Version 0.1.2 adds the other half of that: a flight recorder that writes down every grant issued or revoked, every call, every decision and every result. Each entry goes into the database in the same transaction as the change it records and carries the hash of the entry before it, so an edit, a deletion or a swap anywhere in the log breaks the chain.

tokening flight verify walks the chain and names the first broken entry. export pulls one agent, one grant or one time range for a reviewer, and replay shows what an agent did, in order. head prints the latest entry so you can keep it somewhere else, which also catches someone who rebuilds the whole chain from scratch. The log keeps argument names and a digest of each call. Argument values, credentials and grant secrets never go in.

On a real 42-entry log with its protective triggers removed, 208 of 208 tampering cases were caught. Eight connections writing 800 entries and four processes writing 400 left every chain intact, and a writer killed at random 20 times left a log that verified to its last complete entry every time. Binaries are out for Linux, macOS and Windows.

An independent review found four bugs, fixed in 0.1.3. The most serious let verify pass a log line with a repeated field, so another tool reading the same file could see a value verify never checked. Case studies followed, all run locally against a stand-in site: replaying a publish session where a one-use grant allowed exactly one publish, edits to the log caught entry by entry, including a full rebuild that only a saved head could catch, and one agent exported for a reviewer. Those runs turned up one more bug: an empty saved head skipped the head check and passed. Version 0.1.4 now refuses it, and the recipes post shows the checks for audits and incident reviews. The previous note has the use examples for grants.