Require human approval

Configure EVE so a governed action can require an explicit approval step before it executes. Instead of ALLOW or BLOCK, the deterministic decision can require approval, and the tool does not run until the request is approved.

Prerequisites

• The EVE SDK installed (see install.md).
• A hosted or embedded EVE service (approvals are handled via the service).
• Synthetic tools only; no production credentials.

Installation

pip install ./eve_coreguard-0.2.2-py3-none-any.whl   # hosted client
# or run the embedded facade from the EVE repo

Runnable code

from core.eve_sdk import EVE

IDENT = {"tenant_id": "acme", "principal_id": "agent-1", "session_id": "sess-1"}
eve = EVE(policy="lending_v1", mode="embedded")

decision = eve.govern_tool_call(
    tool="loan_approval",
    arguments={"amount": 250000},
    context={**IDENT, "credit_score": 640, "debt_to_income": 0.42, "employment_verified": True},
)

print("action:", decision.action, "allowed:", decision.allowed)
if not decision.allowed:
    # Do not run the tool. Route the decision to a human approver, then
    # re-govern the approved request through the service before executing.
    print("held for review:", decision.reason_codes)

Approvals are resolved through the EVE service; the client observes the decision and must not execute a held action locally.

Expected result

• A borderline request returns a non-ALLOW decision (allowed = False) with reason codes describing why it needs review.
• The tool is not executed while the request is held.
• After approval through the service, re-governing the same request returns an executable decision.

Evidence output

Each stage carries a signed certificate bound to the decision:

GovernanceResult{action: <ALLOW|BLOCK|MODIFY>, reason_codes: [...], decision_id: "...", certificate: {...}}

The evidence chain records that the tool did not run while the request was held.

Verification

Verify the held decision's evidence offline (see verify-evidence-offline.md):

from core.eve_sdk import verify_evidence
v = verify_evidence("decision", decision.certificate, expected_tenant="acme")
print(v["valid"], v["reason"])

Failure example

If the service is unreachable at approval time, the SDK fails closed — the held action stays blocked, and no client-side path silently promotes it to ALLOW.

Production considerations

• Treat a held decision as terminal for the current call; never execute locally on the assumption of approval.
• Approval state is resolved by the service. Approvals and identity should come from authenticated context, not user input.
• Keep the approval loop in front of the side effect, not after it.

Limitations

• Approvals are handled via the EVE service; the pip/npm clients govern via hosted mode and require an endpoint. The TypeScript client cannot run embedded mode.
• CoreGuard deterministic evaluation is PILOT_READY; the decision covers the governance verdict only.
• No SDK silently falls back to permissive behavior when the service errors — a held action stays held.

Next step

Combine approvals with anomaly monitoring in detect-behavioral-anomalies.md, or enforce hard limits with enforce-a-budget.md.