Skip to main content
RootSign turns each tool call into an 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 a rootsign.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_CLOSE records a total_actions count, but SESSION_CLOSE is not hashed and verify does not compare against it.
  • Session events. SESSION_OPEN and SESSION_CLOSE, including the session’s objective, are not part of the chain.
  • Fields that change after the call. authorization_status is excluded because it legitimately changes when a human approves or rejects a pending action. duration_ms is excluded too. Approval decisions are stored as separate approval records, not in the chain.
If you need to prove that a session was not cut short, keep the record count somewhere outside the session file. For example, record the manifest.json hash that rootsign export prints in a ticket or a chain-of-custody log.

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:

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.