Pattern: external governance gate via on_tool_start (independent /review before irreversible tool calls)

[babyblueviper1]

The SDK already ships on_tool_start / on_tool_end and a set of guardrail examples — input_guardrails.py, output_guardrails.py, llm_as_a_judge.py. One pattern that falls between these is an external governance gate: a second opinion that isn't the same model, running before high-stakes tool execution, with a signed verifiable proof attached.

llm_as_a_judge.py uses the model to grade its own output. The complement: an independent party that isn't the engine, so the grade isn't from the optimist that produced the work.

Pattern using on_tool_start:

import httpx
from agents import RunHooks, RunContextWrapper, Agent, Tool

REVIEW_URL = "https://api.babyblueviper.com/review"
HIGH_STAKES_TOOLS = {"shell", "apply_patch", "file_write", "deploy", "transfer", "swap"}

class GovernanceHooks(RunHooks):
    async def on_tool_start(
        self, context: RunContextWrapper, agent: Agent, tool: Tool
    ) -> None:
        if tool.name not in HIGH_STAKES_TOOLS:
            return

        async with httpx.AsyncClient() as client:
            try:
                r = await client.post(
                    REVIEW_URL,
                    json={
                        "artifact_type": "tool_call",
                        "artifact": {
                            "tool": tool.name,
                            # tool.args available at on_tool_start via ToolContext
                            "args": getattr(context, "tool_arguments", {}),
                        },
                        "sign": True,  # returns a signed, recomputable proof
                    },
                    timeout=5.0,
                )
                if r.status_code == 200:
                    data = r.json()
                    if data.get("verdict") == "reject":
                        raise ValueError(
                            f"[Governance] {tool.name} blocked: {data.get('summary')}\n"
                            f"proof: {data.get('proof', {}).get('id')}"
                        )
                    # proof_id can be logged or attached to context for audit trail
            except httpx.TimeoutException:
                pass  # advisory — never block on gate unavailability

# wire it
result = await Runner.run(agent, input="...", hooks=GovernanceHooks())

Why external matters for high-stakes tools:

The existing guardrails run the same model on its own output — useful for formatting or safety checks, but the model that decided to call shell is also grading whether shell should be called. For high-stakes irreversible actions (deploy, pay, delete, trade), the grade coming from the same engine is the problem.

An external gate:

• Isn't the same model, so it has no incentive to approve what it just decided
• Returns a signed proof (sign: true) — any downstream system can verify the verdict without trusting the agent or the gate
• Degrades gracefully (fail-open on timeout) — the agent stays fully autonomous
• Appends to the audit trail without any changes to agent behavior

The gate is live at https://api.babyblueviper.com/mcp (MCP, tool name: review) or POST /review (REST). The SDK's llms_as_judge.py + this pattern together cover self-grading (fast, free) + external verification (authoritative, signed) for different action classes.

Happy to contribute this as an agent_patterns/external_governance.py example if the direction fits.

[arian-gogani]

the on_tool_start hook is the right surface for a governance gate. one property worth pinning: the gate's decision should produce a verifiable record, not just a boolean.

if the gate blocks an irreversible tool call, the evidence that it was reviewed and blocked should survive outside the agent runtime. if it allows, the evidence that the action was authorized at that moment, with those parameters, should be independently checkable.

that evidence layer is a signed receipt per decision: content-addressed action identity (SHA-256 over RFC 8785 canonical form), Ed25519 signature, hash-chained. a verifier recomputes the hashes and checks signatures against the agent's registered key without calling back to the runtime.

the on_tool_start callback shape maps cleanly: emit a receipt before execution (authorization claim), emit another after (execution evidence). the two form a bilateral record any third party can verify offline.

pip install nobulex
https://github.com/arian-gogani/nobulex

[babyblueviper1]

Strong agreement on the core: the gate's output should be a verifiable record, not a boolean. The bilateral shape — a receipt before execution (authorization claim) and one after (execution evidence), each independently checkable offline — is exactly the right structure, and it's nice to see it converging.

Two distinctions worth pinning, both framed as composable layers rather than competing ones:

1. Who signs determines what the receipt proves. "Checks signatures against the agent's registered key" makes the receipt self-attested: it proves the agent authorized this action with these params — strong, necessary execution evidence. But the gate's judgment is still the agent's own. The original pattern in this issue is specifically a second opinion from a party that isn't the engine — so the grade doesn't come from the optimist that produced the work. Those compose cleanly: the agent signs the execution receipt ("I did X"), an independent verifier signs the judgment receipt ("a party that isn't me reviewed X as sound before it ran"). A receiver who only has agent-signed receipts still has to trust the agent graded itself honestly.

2. A hash-chain needs an external time anchor to resist backdating. Hash-chaining proves the internal ordering of receipts relative to each other, but the whole chain can be regenerated after the fact — nothing outside the issuer pins when the head existed. The property that matters for an irreversible action is "this verdict existed before the outcome," and that requires a clock the issuer doesn't control. We anchor the chain head to Bitcoin via OpenTimestamps, so the pre-commitment is checkable against external proof-of-work, not just against the issuer's own chain. Omission becomes as legible as publication — you can't selectively drop the losing receipts without a visible gap.

On canonicalization, no disagreement: RFC 8785 (JCS) and the canonical-JSON form a Nostr event uses are both fine deterministic surfaces — same recompute-the-hash property, not a point of difference.

Net: agent-signed execution receipts + independent-verifier judgment receipts, with the chain head externally time-anchored, is the full stack. The first proves what ran; the second proves someone other than the actor approved it; the anchor proves the approval came first. Useful to have both designs in the same thread — they answer different halves of "can a third party trust this without trusting the runtime."

[tarunag10]

Opened a docs/example PR: #3699

It adds a runnable external governance gate pattern using RunHooks.on_tool_start, plus guide text on when to use automated fail-closed gates versus manual HITL interruptions.