ACTION_RECORD and links the records of a session into a SHA-256 hash chain. This page explains what a record holds, which parts of it the chain protects, how rootsign verify reaches each of its three verdicts, and the cases verification does not cover.
What gets recorded
Inside arootsign.session(), a session file holds three kinds of event, in order:
This is the first
ACTION_RECORD from the quickstart:
input_redacted and output_redacted are the tool’s arguments and result after PII redaction. Redaction runs before hashing, so the stored payload and its hash always describe the same redacted value.
How the chain is built
Each record gets two kinds of hash. Payload hashes.input_hash and output_hash are SHA-256 digests of the redacted arguments and result. They bind the stored payloads to the record.
The record hash. self_hash is the SHA-256 of eight fields, serialized as JSON with sorted keys:
Because
prev_action_hash is one of the eight fields, each record’s hash depends on every record before it. Changing an earlier record changes its self_hash, which no longer matches the prev_action_hash stored in the record after it.
This formula is frozen. Every backend and every future SDK uses the same eight fields, so a session verifies the same way whether it was stored in a JSONL file or in PostgreSQL. The full specification is in ADR-001.
The three verdicts
rootsign verify recomputes every hash in the session and returns one of three verdicts:
When a session has both an altered record and a gap, the verdict is
TAMPERED, and the missing ranges are still reported. An altered session is never reported as merely incomplete.
The separate exit codes let a CI job or a scheduled audit tell the two failures apart: an edit points to tampering, while a gap may be a lost upload.
Exit code 3 is not a verdict. It means there was nothing to verify: a session ID the database has never seen, a session file that is missing, unreadable or empty, or bad arguments. In 0.3.1 and earlier, an unknown session ID reported VALID with 0 records and exit code 0.
What verify does not check
The chain protects the eight fields above and, through the payload hashes, the stored arguments and results. Some data sits outside it:- Records deleted from the end of a session. A chain cannot tell how long it was meant to be, so removing the last tool calls leaves a shorter chain that still verifies as
VALID.SESSION_CLOSErecords atotal_actionscount, butSESSION_CLOSEis not hashed andverifydoes not compare against it. - Session events.
SESSION_OPENandSESSION_CLOSE, including the session’sobjective, are not part of the chain. - Fields that change after the call.
authorization_statusis excluded because it legitimately changes when a human approves or rejects a pending action.duration_msis excluded too. Approval decisions are stored as separate approval records, not in the chain.
Recording never breaks your agent
If RootSign fails to write a record, for example because the database is unreachable, it logs a warning and your tool call completes normally. The audit layer never raises an error into the tool it wraps. The design is in ADR-002.Where records are stored
You choose the backend with the
ROOTSIGN_BACKEND environment variable. The instrumentation code is the same for all three, and all three use the same hash formula.
Design records
The decisions behind this page are written up as design records in the repository:- ADR-001: canonical hash specification
- ADR-006: redaction contract
- ADR-011: JSONL local backend
- All design records
Next steps
Quickstart
Record a session and see all three verdicts on your own machine.
Ingest specification
The wire format: envelope fields, event types, error codes and the hashing contract.