Human Approval Gate for AI Agent Actions in Python

How to read this: every arrow has one precondition, and any call that does not satisfy it raises an error and leaves the state as it was.

Verified: capstone/fde-product-discovery-copilot/app/workflow/approval.py

    def execute(self, approval_id: str, args: QuoteDraftArgs) -> dict[str, object]:
        approval = self._get(approval_id)
        if approval.status != "approved":
            raise ApprovalError(f"Approval {approval_id} is {approval.status}, not approved.")
        if approval.digest != args_digest(ACTION, args):
            raise ApprovalError("These arguments are not the ones that were approved.")
        approval.status = "used"  # single use
        draft = {"draft_id": f"qd-{len(self.quote_drafts) + 1}", **args.model_dump()}
        self.quote_drafts.append(draft)
        return draft

The gate stores a digest, not the arguments. Keep the arguments the person was shown and pass those to execute.

Worked example

Alice proposes 40 units of LUM-VS-100 for cust-1; Bob, a second partner, approves. Canonical JSON: {"action":"create_quote_draft","args":{"customer_ref":"cust-1","quantity":40,"sku":"LUM-VS-100"}}.

Assumptions: illustrative values; the digests below were computed by running the capstone's args_digest.

The approval id is the first 12 characters of the digest.

At the customer: a security reviewer asks, "Can the AI send a quote on its own?" A good answer says no: the model can only create a pending request, a second person approves it, the action runs with exactly the approved arguments, and each approval works once. Name what is missing: expiry, a database, an audit trail.

Build it

Verified: capstone/fde-product-discovery-copilot/lessons/M4-L5/m4_l5_approval_flow.py

def propose(gate: ApprovalGate, proposed: dict[str, object], requester: Identity) -> PendingQuote:
    args = QuoteDraftArgs.model_validate(proposed)  # bad arguments from the model stop here
    return PendingQuote(args, gate.request(args, requester))


def review_text(pending: PendingQuote) -> str:
    """The screen the approver reads: the exact arguments, not the model's description of them."""
    a = pending.args
    return f"{ACTION}: {a.quantity} x {a.sku} for {a.customer_ref} [{pending.approval.approval_id}]"


def decide(gate: ApprovalGate, pending: PendingQuote, approver: Identity, approve: bool) -> dict[str, object] | None:
    """Approve and execute with the stored arguments, or do nothing. A rejection leaves the request pending."""
    if not approve:
        return None
    gate.approve(pending.approval.approval_id, approver)
    return gate.execute(pending.approval.approval_id, pending.args)

cd capstone/fde-product-discovery-copilot
./.venv/Scripts/python -m pytest lessons/M4-L5 -q

Decision exercise. Fewer clicks wanted. Options: (A) every draft needs a second person's approval; (B) drafts under a quantity threshold skip approval; (C) the requester confirms their own draft in the UI. Choose one for the pilot and say what evidence would change your mind.

Explain it back. Explain to a customer's security reviewer, in three sentences, why the approval is tied to a digest of the arguments. A good one says what could change in between, that a changed value gives a different digest so the call is refused, and that the approval is used once.

Exercise

Add expiry to the gate. In lessons/M4-L5/, write a subclass of ApprovalGate whose approvals stop working a fixed time after approval. Use a fake clock.

Acceptance criteria:

• An approval executes at exactly the limit and is refused one second after it.
• A refused execution creates no draft.
• The limit counts from approval, not from the request.

Done when three tests pass without any sleeping.

Common mistakes

• Putting the rule in the prompt. A crafted document can talk the model out of it. Check in code.
• Approving an action, not a call. Bind the approval to a digest of the arguments.
• Re-reading arguments from the model at execution. Store and use the arguments the person saw.
• Letting the requester approve. One person is then both checks. Require a second identity.

Knowledge check

You can now

• Explain why approval is enforced in code and bound to the exact arguments.
• Walk a request through pending, approved and used and name the call for each step.
• Write tests for changed arguments, a second use and self-approval.
• List what a production approval flow adds.

Further reading

• LLM06:2025 Excessive Agency, OWASP: human approval of high-impact actions.
• json.dumps parameters, Python documentation: sort_keys and separators.
• hashlib, Python documentation: SHA-256 and hexdigest.

Last verified: 2026-11-02

Next

Testing tool failure and malformed input