Human approval checkpoint

Purpose

A human approval checkpoint pauses a consequential action and hands a bounded decision to an accountable person. It presents the requested outcome, the exact action, the evidence, the evaluator’s verdict, and unresolved risks. The person can approve, reject, or request a revision.

The approval applies only to the reviewed subject and action. It should be recorded as a scoped authorization that the executor can verify, not as a chat message that a worker interprets.

When to use

Use a human checkpoint when policy assigns final authority to a person or when the consequences exceed what the automated controls may authorize. Examples include production deployment, irreversible migration, access expansion, customer-facing publication, legal or safety claims, and unusual financial commitments.

Do not require approval merely because a workflow contains an agent. Routine, low-risk actions with tested policy and evaluation paths can stay automated. Place human attention at the boundary where judgment, accountability, or risk ownership is required.

Inputs and outputs

Inputs:

• the intent brief and current version;
• the proposed action, target, and subject digest;
• the sealed evidence packet;
• policy and evaluator decisions;
• known gaps, warnings, rollback information, and expected impact;
• the approver role and expiry policy.

Outputs:

• approved, rejected, or revision-requested;
• the approver identity and role;
• a timestamp, expiry, and single action digest;
• an optional reason or requested change;
• a signed or otherwise verifiable approval reference for the executor.

Smallest useful interface

type ApprovalRequest = {
  intentRef: string;
  action: string;
  target: string;
  subjectDigest: string;
  evidencePacketRef: string;
  policyDecisionRef: string;
  evaluationRef: string;
  risks: string[];
  expiresAt: string;
};

type ApprovalDecision = {
  requestDigest: string;
  result: "approved" | "rejected" | "revision-requested";
  approver: string;
  approverRole: string;
  decidedAt: string;
  expiresAt?: string;
  reason?: string;
};

function recordApproval(
  request: ApprovalRequest,
  decision: Omit<ApprovalDecision, "requestDigest">
): ApprovalDecision;

The executor should accept an approval only when the approver has the required role, the request digest matches, the approval is current, and no newer artifact has replaced the reviewed subject.

Example

A checkout change has passed its evaluator and reached the production policy gate. The policy requires an on-call release approver. The checkpoint displays:

intent: checkout-timeout-fix@2
action: Deploy checkout-api release 2026.08.13.3 to production
subject: sha256:94ab...
evaluation: pass
policy: review required for production
evidence:
  focused-timeout-test: pass
  checkout-integration-suite: pass
  release-artifact-digest: sha256:94ab...
known-risks:
  - The change adds a new retry response on one upstream timeout path.
rollback:
  - Redeploy release 2026.08.12.5 using the existing release procedure.
expires: 2026-08-13T12:30:00Z

The approver selects approved. The checkpoint issues a decision bound to the production target and release digest. If a worker rebuilds the release, the new digest requires a new approval even when the source diff appears unchanged.

Failure modes

• The request asks only “approve?” The person cannot see scope or consequence. Show the action, target, artifact, evidence, gaps, and rollback information in a compact decision view.
• Approval applies to a moving branch or latest release. The subject can change after review. Bind approval to an immutable digest.
• A chat reaction becomes authorization. The executor cannot verify who approved what. Record a structured decision through an authenticated path.
• The only easy action is approve. This encourages a rubber-stamp path. Give rejection and revision equal visibility and require no workaround to stop the action.
• Every workflow requests human review. Repeated low-value prompts consume attention and hide unusual risk. Use policy to reserve checkpoints for named boundaries and exceptions.
• The approver lacks the relevant role. Identity alone is not authority. Resolve the required role at decision time and record it.
• The request expires but execution continues. Verify freshness at the execution boundary and request approval again after expiry.
• New evidence arrives after approval. Treat changes to the subject, required evidence, or risk statement as a new request.

What it does not solve

A human checkpoint does not guarantee that a person will notice every defect or make the best decision. It cannot compensate for missing evidence, a misleading summary, or an approver without enough context. It also does not replace access control at the execution platform. Its job is narrower: preserve human authority at a named boundary and make the resulting authorization specific, visible, and enforceable.

Related reading

• Intent brief
• Policy gate
• Evidence packet
• Independent evaluator
• Your agent should not be its own reviewer