Govern a tool call

Route a tool call through EVE so it is checked before the side effect runs. EVE CoreGuard makes a deterministic ALLOW / BLOCK / MODIFY decision, no LLM is in that decision path, and the decision can produce signed evidence you can verify offline.

Prerequisites

The EVE SDK installed (see install.md).
For a fully local run, the embedded service facade from the EVE repo (from core.eve_sdk import EVE). For a client-only run, a reachable hosted endpoint and from eve_coreguard import EVE.
A synthetic tool (recording, no real side effects) for testing. Do not use production credentials.

Installation

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

Runnable code

This uses the embedded facade and a recording tool (mirrors examples/eve_sdk/govern_tool_call.py):

from core.eve_sdk import EVE, verify_evidence

IDENT = {"tenant_id": "acme", "principal_id": "agent-1", "session_id": "sess-1"}

eve = EVE(policy="lending_v1", mode="embedded")

# Ask EVE before doing anything with a side effect.
decision = eve.govern_tool_call(
    tool="loan_approval",
    arguments={"amount": 1000},
    context={**IDENT, "credit_score": 760, "debt_to_income": 0.15, "employment_verified": True},
)
print("action:", decision.action, "allowed:", decision.allowed)

if decision.allowed:
    # Only now run the real tool.
    print("executing loan_approval")

With the hosted client, replace the import with from eve_coreguard import EVE and pass mode="hosted", endpoint=....

Expected result

A low-risk request returns action = ALLOW, allowed = True; you then run the tool.
A high-risk request (for example amount=500000 with credit_score=480, debt_to_income=0.9, employment_verified=False) returns action = BLOCK, allowed = False, with reason_codes explaining why — and the tool is never called.

Evidence output

Each decision carries a signed certificate bound to that decision:

GovernanceResult{action: ALLOW, reason_codes: [...], decision_id: "...", certificate: {...}}
certificate.llm_in_decision_path == false

The certificate is signed with Ed25519 in the production configuration (HMAC-SHA256 fallback).

Verification

Verify the decision evidence independently, without trusting the EVE server:

result = verify_evidence("decision", decision.certificate, expected_tenant="acme")
print(result["valid"], result["reason"])

Independent (asymmetric) verification requires the Ed25519 public key. See verify-evidence-offline.md.

Failure example

If the governance service is unreachable, the SDK fails closed:

try:
    eve.govern_tool_call(tool="loan_approval", arguments={"amount": 1000}, context=IDENT)
except Exception as err:
    print("fail-closed (no silent allow):", err)

The hosted client returns a BLOCK on service-unavailable rather than raising. In neither case does the SDK silently allow the action.

Production considerations

Always place the govern_tool_call check before the code path that produces the side effect, and treat BLOCK as terminal for that call.
Identity (tenant_id, principal_id, session_id) should come from your authenticated context; in the hosted/MCP path, server-derived identity is authoritative and forged headers are rejected.
Wrapping a tool in a Python wrapper is convenient but a direct call to the underlying tool bypasses the wrapper. For hard enforcement, use a gateway or sidecar boundary.

Limitations

CoreGuard deterministic evaluation is PILOT_READY. The claim covers the governance verdict only; the governed application may still use LLMs elsewhere.
The pip client reaches CoreGuard via hosted mode (needs an endpoint); embedded in-process evaluation runs inside the EVE service.
Signed decision evidence is SUPPORTED, but independent verification needs the Ed25519 public key; the HMAC fallback is symmetric and not independently verifiable.

Next step

Wrap an entire agent's tool surface with govern-an-agent.md, or require a human approval step with require-human-approval.md.