Agent Governance ToolkitAgent Governance Toolkit 4.1.0 · Python 3.10+
Dashboard
0%

Freeze the policy at start-up

Freezing a policy engine makes it reject every change after start-up, so an agent that can run code cannot grant itself a tool the policy denied.

Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0

Every rule in the Writing your own policy rules lesson was added with a method call. An agent that can run code can call those methods too, which makes the policy engine itself a target. Freezing closes that door.

The one-line self-grant

The attack needs no cleverness. Any code in the same process can call add_constraint and hand a role the tool it was denied.

ExampleThe engine grants itself the denied tool
from agent_control_plane import PolicyEngine, AgentKernel

policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])
kernel = AgentKernel(policy_engine=policy)
print("before:", kernel.intercept_tool_execution("support", "delete_account", {}) is None)

policy.add_constraint("support", ["order_status", "delete_account"])   # the attack
print("after: ", kernel.intercept_tool_execution("support", "delete_account", {}) is None)

The deletion was denied, then allowed, by one extra call. A tool that executes code, or anything that arrived through a dependency, can make that call.

Freezing blocks every change

Call freeze after the policy is built. Every mutating method then raises, and the message says the call is irreversible, because there is no unfreeze by design: one would be the first thing an attacker reached for.

ExampleAfter freeze, add_constraint raises
policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])
policy.freeze()

try:
    policy.add_constraint("support", ["delete_account"])
except RuntimeError as exc:
    print(exc)

Even direct assignment is refused

Freezing does more than set a flag. The engine's internal dictionaries become read-only views, so reaching past the methods to assign a permission directly fails as well. Checking still works; only changing is blocked.

ExampleThe permission tables are read-only after freeze
print("frozen:", policy.is_frozen)

try:
    policy.state_permissions["support"] = {"delete_account"}   # reach past the methods
except TypeError as exc:
    print("direct:", exc)

A record of every change

Every change is recorded as it happens, the freeze included, so you have a record of how the policy reached the state it is in.

ExampleEach change, in order, ending with the freeze
policy = PolicyEngine()
policy.add_constraint("support", ["order_status"])
policy.add_constraint("readonly", ["order_status"])
policy.freeze()

for entry in policy.mutation_log:        # the freeze is logged too
    print(entry["operation"], entry["details"])

What freezing does and does not stop

  • It stops every change after start-up. add_constraint, add_custom_rule and the rest all raise once the engine is frozen.
  • It stops reaching past the methods, because the permission tables become read-only views, not plain dictionaries.
  • It leaves checking untouched. A frozen engine answers check_violation exactly as before, which is why you freeze and then serve.

Before and after freezing

OperationBefore freezeAfter freeze
add_constraintChanges the policyRaises RuntimeError
Direct dictionary assignmentChanges the policyRaises TypeError
check_violationWorksWorks
freeze againFreezesNo complaint

Where you freeze the policy

  • At the end of start-up, the moment the policy is fully built, so the serving phase runs on a policy nothing can edit.
  • In any process that runs agent-chosen code, where a tool could otherwise reach the engine and widen its own permissions.
  • In a test, to prove the self-grant attack raises rather than succeeds.
Watch out. The mutation log lives in memory and disappears with the process, so it is not the audit trail you show an auditor. The durable record that survives a restart is built in Recording every decision: the flight recorder.
Try it yourself
  • Call freeze twice and confirm the second call does not complain.
  • Freeze before the add_constraint calls and watch the set-up fail instead of the attack.
  • Print policy.mutation_log after a blocked change and confirm the refused call left no entry.

You understood something today that you didn't yesterday.