Attribution and signing

Object-level attribution

"Object-level" means the author identity is part of the state's canonical encoding: it's folded into the state's content-addressed BLAKE3 hash. (The hd-… ID you see is a separate random 128-bit ChangeId, fresh per capture; the content hash is the value that pins the bytes.) You can't strip the author after the fact or forge it without producing a different content hash, and you don't have to scrape it out of a commit-message convention.

Three fields make up the author of a state:

• Agent. claude is the registered identity that fired the capture. Could be a coding agent, a human, a CI process.
• Model. opus 4.7 from anthropic, the specific model the agent was running, if applicable. Recorded so a future reader can know which model produced this state.
• Delegator. anan@heddle.sh, the human who delegated the work to this agent. Carries the authority for actions that need a human accountable.

All three are read from the environment at capture time. No flags required. The shell already knows who's driving; Heddle just records it.

Signing is optional

Attribution is structural and always present. Signing is a separate operation: an Ed25519 signature over the resolved state of a thread, attesting that someone reviewed and accepts it. Signatures are stored as objects alongside the state they sign.

Cheap to add, cheap to verify. heddle review sign submits a pre-computed Ed25519 signature (64 bytes) over a state; verification is constant-time. Multiple parties can sign the same state without rebuilding the artefact.

Submit a review signature on a resolved state

bash$ heddle review sign hd-d01a8b4e --kind read \ --public-key <hex> --signature <hex> --signed-at-unix <ts>signed state hd-d01a8b4e as read (signature_id 1)

Three signature modes

Not every signature means the same thing. Heddle distinguishes three:

• read: a human reviewed the resolved state and accepts it. The strongest signature mode; --kind has no default, so you always state which one you mean.
• agent_preview: an agent looked at the state and verified its own claims (tests pass, lint clean, no obvious regressions). Useful for automated gates; not a substitute for human review.
• agent_co_review: a second agent (often a different model or vendor) reviewed the first agent's work as an adversarial pass. Stronger than agent_preview because the reviewer has no stake in the original work.

Keys

Heddle doesn't ship its own KMS. Ed25519 keys are managed however your organisation already manages them: local key files, hardware tokens, a HashiCorp Vault, AWS KMS, a yubikey. You sign the state's payload yourself, then submit the result: heddle review sign takes the raw --public-key and the pre-computed --signature as hex, so the private key never touches Heddle.

By default, signing is opt-in. A repo with no key configured can still ship work; the bridge to Git will just produce commits without a signed trailer. The repo's policy can require signing for promotion to specific namespaces or branches.

Compared to Git

The commands

• heddle review: show the review payload, sign the resolved state.
• heddle capture: every capture records its actor.
• heddle agent: the identity surface for out-of-process agents.

Next: namespaces for how attribution + signing interact with organisational structure, or redaction and purge for what happens when an attributed action needs to be retracted.