Spec

Lifecycle event protocol

Every governed run emits a stream of typed events. Events are written transactionally to the ledger with a chained content hash so the log is tamper-evident.

Event shape

{
  "id": "evt_01HQXY...",
  "attempt_id": "att_01HQXX...",
  "sequence": 42,
  "event_type": "command.completed",
  "actor_type": "executor",
  "actor_id": "claude-code",
  "payload_json": { "...": "..." },
  "payload_hash": "sha256:...",
  "previous_chain_hash": "sha256:...",
  "chain_hash": "sha256:...",
  "created_at": "..."
}

Required event types

task.created
task.planned
attempt.started
runtime.created
executor.started
command.started
command.completed
file.changed
test.started
test.completed
scanner.started
scanner.completed
policy.evaluated
approval.requested
approval.recorded
waiver.requested
waiver.recorded
attempt.completed
evidence.generated
outcome.linked

Verifying the chain

surety ledger verify

Walks the event log, recomputes chain hashes, and reports any tampering or gaps. Useful for audit export and compliance review.

Replayable

Because events are typed, transactional, and chained, an attempt can be replayed for debugging, auditing, or root-cause review without re-running the agent.