Concepts
Attribution and signing
Every capture, every context, every resolution carries its author in the object model — recorded at write time, never reconstructed from metadata. Signing is optional Ed25519 over the resolved state of a thread. Three signature modes distinguish a human's review from an agent's preview from a second agent's co-review.
Object-level attribution
"Object-level" means the author identity is part of the
state's canonical encoding — it's hashed into the hd-… ID. You can't strip it after the fact,
you can't forge it without producing a different state ID,
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— the registered identity that fired the capture. Could be a coding agent, a human, a CI process. - Model.
opus 4.7fromanthropic— 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 produces a 64-byte signature; verification is constant-time.
Multiple parties can sign the same state without rebuilding
the artefact.
Sign a resolved state
bash$ heddle review sign task/biscuit-authzSigned task/biscuit-authz · ed25519:a8f3c1d7Three signature modes
Not every signature means the same thing. Heddle distinguishes three:
read— a human reviewed the resolved state and accepts it. This is the default and the strongest signature mode.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 thanagent_previewbecause 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. The signing operation accepts a key identifier; your environment resolves it to an actual key.
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
git commit --author object-level actor Git's author is text in a header. Heddle's actor is part of the object's canonical encoding. You can't quietly change a Heddle actor without producing a different state ID.
git commit -S heddle review sign Git signs commits. Heddle signs resolved states. The unit difference matters: signing the resolved state means you're attesting to the *outcome*, not to every messy step.
GPG / SSH commit signing Ed25519 signing Heddle uses Ed25519 by default — smaller signatures, faster verification, no GPG ceremony. Keys integrate with whatever you already use.
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.