Records and verification

The signed chain is ${PLUGIN_DATA}/ledger/decisions.ndjson. Decisions record tool names, input SHA-256, byte counts, actor identifiers, configured cost and the policy result. They never retain tool input content or output text. Tool names and identifiers can still be sensitive metadata, so protect the policy, the private signing key and the records.

flowchart TD
  D[Decision row] -->|links by decision ID| R[Outcome receipt]
  D --> H1[SHA-256 over canonical JSON]
  R --> H2[SHA-256 over canonical JSON]
  H1 --> C[Hash chain]
  H2 --> C
  C --> S[Ed25519 signature per row]
  S --> V{verify_chain}
  V -->|public key only| OK[Valid: hashes, signatures, no sequence gaps]
  V --> BAD[Invalid from the first altered row]

Outcome receipts link to the preceding decision ID. Host timing is preferred; otherwise duration is elapsed pre and post time including scheduling. Explicit errors and structured exit codes determine success. Codex 0.154 unified Bash provides raw output without an exit code, so those receipts use status: "unknown" and success: null. The plugin does not parse output text to guess success.

Durability

Before replying, the worker signs and writes each complete ledger row to the operating system; a later asynchronous sync confirms a durable chain head, so a crash or power loss can lose an unconfirmed tail. On restart it verifies surviving rows against that head, discards only an incomplete final row beyond it, and appends a signed integrity event when surviving evidence shows an unconfirmed tail or sync failure. Complete invalid rows are never silently repaired.

An older ledger without a durability checkpoint receives one conservative integrity event at first startup. Status counts integrity events separately from tool decisions and configured spend.

Status, verification and export

Use the agentguard-status skill for an operator summary, or the optional read-only MCP tools. They do not change policy, execute business tools or write an export file.

Tool	Result
get_status	Tier, seats used, limit, storage verification, expiry, effective mode and reason; UTC-day decisions, configured spend, blocks, outcomes, integrity events and fail-open health.
list_decisions	A bounded page of content-free decision summaries, using fromSequence and limit.
verify_chain	Verifies hashes and signatures against the local public verification key. Available on every tier.
export_receipts	A bounded page of signed receipts and the public key when a usable paid license is present. The caller saves the bundle.

Fail-open health reports count, total and rate over the last hour and since worker start. Either rate above five percent produces a one-line warning with a known cause. Health counters are unsigned operational observations and may lag the signed chain. Never add pending recovery counts to the verified total.

Custodian bundle

node "${PLUGIN_ROOT}/runtime/verify.cjs" export RECEIPTS_FILE

Note

Preserve the verification public key through a trusted channel separate from the bundle. A bundled key proves consistency with that key, not who controlled it. Export never includes the signing private key.

Disable the optional MCP server

config.toml

[plugins."agentguard@agentguard".mcp_servers.agentguard]
enabled = false