Answers · agent safety
How do I bind a human approver's identity to a content-addressed artifact hash and version before an AI agent can apply side effects?
Last updated
TL;DR: A generic "approved" flag is not enough. Before any side-effecting apply step runs, seal three fields together outside the agent's session: (1) the named human approver from your identity provider (subject, email or employee id — not "the agent said Alice said yes"), (2) a content-addressed hash of the exact bytes or canonical payload that will be applied (SHA-256 of the artifact, config blob, patch, or RFC 8785-canonical JSON of the tool arguments), and (3) the human-readable version or build id that labels those bytes. Hash that triple into the approval action. At apply time, recompute the live artifact hash, re-resolve the approver id from the sealed decision, and refuse unless both match and the version label still names the same digest. request_human_approval binds the yes to the hashed action; verify_human_approval fails if the agent swaps bytes or reuses another person's grant. This is distinct from release-ticket digests alone: the gate is who + which bytes + which version, checked immediately before side effects.
What should I check, step by step?
1. Compute a content-addressed fingerprint of what will be applied: sha256 of the file/image/firmware, or of JCS-canonical tool arguments — never a floating tag (latest) or a mutable branch tip alone.
- Record the semantic version or build id as a label on that digest (version → digest map). Reject a version string that no longer resolves to the sealed digest.
- Resolve the approver from your IdP or SSO session (stable subject id). Put approver_id, artifact_sha256, version, and environment into the request_human_approval action object so they are hashed together.
- Store the signed decision (approver_id, decided_at, artifact_sha256, version, approval_id) in a server DB or ledger the agent's tools cannot UPDATE. Give the agent only the approval_id.
- Immediately before the side-effecting call: re-hash the live artifact or arguments; verify_human_approval against that hash; confirm approver_id on the receipt still matches the human who decided.
- Fail closed on mismatch, missing approval, expired grant, or a version label that now points at different bytes. Do not apply "close enough" builds.
- Append an immutable apply record: who approved, which digest was approved, which digest was applied, when. Prefer append-only rows over edits.
- Keep only approval_id (and maybe a display version) in the agent session — never approved=true, never a mutable copy of artifact_sha256 the model can rewrite.
Why must approver identity, content hash, and version travel together?
A yes bound only to a version string ("ship 2.4.1") fails when CI rebuilds 2.4.1 from a different commit. A yes bound only to a digest with no named approver fails an audit: you cannot say which human authorized those bytes.
- Content-addressing (hash of the exact payload) answers which bytes. The version label answers how humans refer to those bytes. The IdP subject answers who. Drop any one and the apply step can be spoofed or unexplained.
- How to bind an agent approval to a specific tested artifact or version covers release/change-control digests for plant and cluster deploys. This page is the pre-side-effect seal: approver identity + content hash + version must already be bound before the agent may write, send, pay, or deploy.
- How to bind an approver and scope to an agent tool call, its result, and a timestamp is the post-invocation audit seal. Pair them: bind before apply, then record call + result + time after.
How do I seal approver, content hash, and version before side effects run?
request_human_approval hashes the action. Put approver_id (from your session, not from agent text), artifact_sha256, version, target/environment, and a short evidence_ref inside action so verify_human_approval fails if any field drifts.
- Show the human the digest (short form), version, and a preview of what those bytes do — not the model's one-line summary. Escape display fields; treat agent-supplied descriptions as untrusted.
- OpenAI Agents SDK interruptions and LangGraph interrupts pause for a person, but resume must re-check the pending call's argument/artifact hash against the sealed approval. Server-side approval state; no client-uploaded approved=true.
- record_ai_run can store a signed receipt of the sealed triple (approver, digest, version) and the later apply outcome so verify_ai_run can prove what was recorded — proof of the record, not that the plant is safe.
What can go wrong?
Approval UI shows "Alice approved the release" while the action object has no approver_id from the IdP — only chat text the next turn can forge.
- The gate checks version == 2.4.1 but never compares live sha256 to the sealed digest after a silent rebuild.
- A yes for digest A is reused for digest A' because only the tool name was bound, not the content hash.
- approved_digest and approver live only in the agent's session JSON and get overwritten before apply.
How do I ask Rightshold about this (free, no key)?
Add the MCP server https://www.rightshold.com/mcp to Claude, Cursor, ChatGPT, Grok or VS Code, then ask: “Before my agent applies this change, ask me to approve the exact content-addressed artifact (sha256), its version label, and record my approver identity; bind the yes to a hash of those fields and wait for my decision.”
{
"tool": "request_human_approval",
"arguments": {
"summary": "Apply config pack edge-router 1.8.3 (sha256:4e91…) to staging after review by IdP subject alice@example.com",
"action": {
"type": "apply_artifact",
"artifact_id": "edge-router-config",
"version": "1.8.3",
"artifact_sha256": "sha256:4e91…",
"environment": "staging",
"approver_id": "idp:alice@example.com",
"evidence_ref": "ci://runs/CFG-902"
},
"expires_in_minutes": 60
}
}- Needs your API key. The action is hashed; you decide once with decide_human_approval (owner account key). verify_human_approval fails if artifact_sha256, version or environment no longer match.
- record_ai_run can seal the approver + digest + version triple and the later apply outcome outside the agent session; verify_ai_run is free.
- How to bind an agent approval to a specific tested artifact or version covers release digests for tested builds; this page adds named approver identity and the mandatory pre-side-effect check.
- How to show a human the actual change before approving covers rendering diffs and tool arguments — pair that UI with the digest and approver_id fields above.
Rightshold records human approvals and signed AI-run receipts for agents that call it. It does not hash your artifacts, resolve your IdP subjects, sit in your deploy pipeline, or stop an apply path that never asks. Enforce the digest and approver compare in your apply gate too. Not legal advice.
What are the sources?
- NIST SP 800-53 Rev. 5: CM-3 / CM-5 (configuration change control; access restrictions for change)
- SLSA Provenance (content-addressed subjects; who produced what)
- OpenAI Agents SDK (JS): Human-in-the-loop (keep approval state on the server)
- RFC 8785: JSON Canonicalization Scheme (JCS)
- Human approvals on Rightshold
- Verified AI Runs on Rightshold
Related
- How to bind an agent approval to a specific tested artifact or version
- How to bind an approver and scope to an agent tool call, its result, and a timestamp
- How to show a human the actual change before approving an AI agent action
- How to audit which human authorized an AI agent action
Not legal advice. JSON · Markdown · All answers
Get a free API key in one call
No card and no email needed. 100 free credits; the license and policy checks stay free without a key.
curl -s -X POST https://www.rightshold.com/v1/accounts/signup -H "Content-Type: application/json" -d '{"accept_terms":true}'
export RIGHTSHOLD_API_KEY=rs_... # the api_key from the reply (shown once)
curl -s https://www.rightshold.com/v1/licenses/check -H "Authorization: Bearer $RIGHTSHOLD_API_KEY" \
-H "Content-Type: application/json" -d '{"license":"MIT","intended_use":{"commercial_use":true}}'