Two ways the engine checks a call
Two methods run the same gate: a synchronous intercept_tool_execution and an asynchronous twin, and they answer an allowed call in different shapes, so the check your code writes depends on which one you call.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
Every example so far called intercept_tool_execution, the synchronous method, from the One choke point for every tool call lesson. An agent written with asyncio calls intercept_tool_execution_async instead, and the two do not answer the same way. This is the one piece of the library's shape worth learning before it costs you an afternoon.
The synchronous gate: None means allow
The synchronous method returns None for an allowed call and a dictionary for a blocked one, the convention the rest of this part has used.
from agent_control_plane import PolicyEngine, AgentKernel
policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])
kernel = AgentKernel(policy_engine=policy)
print("allow:", kernel.intercept_tool_execution("support", "order_status", {}))
print("block:", kernel.intercept_tool_execution("support", "delete_account", {}))allow: None
block: {'status': 'blocked', 'error': 'RuntimeError: PolicyViolation - Role support cannot use tool delete_account', 'policy': 'delete_account', 'agent': 'support', 'mute': True}The asynchronous twin: a dict even on allow
The asynchronous method is a coroutine, so it is awaited. An allowed call comes back as {'allowed': True}, not None, and a blocked call carries an allowed key instead of a status key.
import asyncio
async def main():
allow = await kernel.intercept_tool_execution_async("support", "order_status", {})
block = await kernel.intercept_tool_execution_async("support", "delete_account", {})
print("allow:", allow)
print("block:", block)
asyncio.run(main())allow: {'allowed': True}
block: {'allowed': False, 'error': 'RuntimeError: PolicyViolation - Role support cannot use tool delete_account', 'policy': 'delete_account', 'agent': 'support', 'mute': True}The allowed call is the difference that bites. Code that tests verdict is None for allow, written against the synchronous gate, treats every asynchronous allow as a block, because {'allowed': True} is not None.
Which shape your code must check
| Call | intercept_tool_execution (sync) | intercept_tool_execution_async |
|---|---|---|
| Allowed | None | {'allowed': True} |
| Blocked | dict with status='blocked' | dict with allowed=False |
| Test for allow | verdict is None | verdict['allowed'] |
Shadow mode answers differently again
A kernel in shadow mode reports an allowed call as simulated instead of running it, which is how you try a policy without enforcing it. Even the allowed call now returns a dictionary, and the two methods disagree on its keys.
shadow = AgentKernel(policy_engine=policy, shadow_mode=True)
print("sync :", shadow.intercept_tool_execution("support", "order_status", {}))
print("async:", asyncio.run(shadow.intercept_tool_execution_async("support", "order_status", {})))sync : {'status': 'simulated', 'result': 'Success (Simulated)', 'meta': {'shadow': True}}
async: {'allowed': False, 'result': 'Success (Simulated)', 'shadow': True}What the two methods agree and disagree on
- They enforce the same policy. A blocked call is blocked on both, for the same reason, with the same
error. - They report an allow differently. The synchronous method returns
None; the asynchronous one returns{'allowed': True}. - Shadow mode splits them further. A simulated allow is a
status='simulated'dict on the synchronous method and anallowed=Falsedict on the asynchronous one.
Where this difference matters
- An async agent, where the gate must be awaited and the allow test is
verdict['allowed'], notverdict is None. - Porting a gate from sync to async, where the allow check has to change or every call looks blocked.
- Turning on shadow mode, where a loop that runs the tool on a
Noneverdict stops running anything, because an allow is no longerNone.
Related
- Previous: Freeze the policy at start-up
- Next: Writing a policy in a YAML file
- Block a call on both methods and confirm the
errorstring is identical. - Write an allow test that works for the asynchronous method and check it on an allowed and a blocked call.
- Run the shadow-mode block with a blocked tool and compare its output to the allowed one.
Slow is fine. Stopping is the only problem.