Permissions that depend on the context
A conditional permission is a policy rule that allows a tool only when a field in the request's context says so, so the same call can be permitted for one caller and refused for another.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The Three YAML formats, and which one is real lesson settled which YAML dialect the loader reads. This part uses that loader to write rules that read the situation a call arrives in, not only the tool's name. The first situation is who is asking: the shop agent may issue a refund, but only when a manager is behind the request.
Loading a policy written inline
Every example in this part loads a short policy the same way. load writes the YAML to a temporary file and reads it back with from_yaml, the same loader a policy on disk uses, so each example stays self-contained.
import warnings; warnings.simplefilter("ignore")
import tempfile
from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator
def load(text): # write the YAML to a file, then load it back
f = tempfile.NamedTemporaryFile("w", suffix=".yaml", delete=False)
f.write(text)
f.close()
return PolicyDocument.from_yaml(f.name)A rule that reads the caller's role
A condition is one {field, operator, value} triple. This policy has two rules: one allows the refund at priority 10 when the role field equals manager, and a default-priority rule denies the refund tool outright. A manager's request matches both, and the higher priority wins; everyone else matches only the deny.
POLICY = """
version: "1.0"
name: refund-by-role
# a manager may refund; any other role is denied the refund tool
rules:
- name: manager-may-refund
condition: {field: role, operator: eq, value: manager}
action: allow
priority: 10
- name: refund-needs-a-manager
condition: {field: tool, operator: eq, value: refund}
action: deny
"""The same refund, two contexts
Build the evaluator from the loaded document and call evaluate with a context dict. The only thing that changes between the two calls is the role field, and the verdict changes with it.
doc = load(POLICY)
evaluator = PolicyEvaluator(policies=[doc])
# the same refund, asked once as a manager and once as an agent
for role in ["manager", "agent"]:
d = evaluator.evaluate({"tool": "refund", "role": role})
print(f"{role:8} allowed={d.allowed} action={d.action} rule={d.matched_rule}")manager allowed=True action=allow rule=manager-may-refund agent allowed=False action=deny rule=refund-needs-a-manager
What the context decided
- The manager's refund was allowed by
manager-may-refund, because itsrolecondition matched and its priority of 10 beat the default-priority deny rule. - The agent's refund was denied by
refund-needs-a-manager: the role condition did not match, so only the deny rule was left. - The tool name never changed. Both calls were a refund; the context field decided the outcome, which is the whole point of a conditional permission.
A permission on the name alone, or on the context
| A permission on the tool name | A conditional permission | |
|---|---|---|
| Decides from | The tool name only | A field in the request context |
| Same tool, two callers | Same verdict for both | Can allow one and deny the other |
| Where it lives | An allow-list of names | A rule with a condition |
Where you use a conditional permission
- A tool only some roles may run, such as a refund a manager approves but a front-line agent cannot.
- A tenant or environment check, so the same tool is allowed in staging and denied in production.
- A per-customer limit, where a field on the request marks an account the action is or is not allowed against.
role, and keep a low-priority deny as the backstop, the way this policy does.Related
- Previous: Three YAML formats, and which one is real
- Next: Conditions on a tool's arguments
- Reference: Agent Governance Toolkit documentation
- Add a
role: admincase and giveadminits own allow rule at priority 20. - Remove the
rolefield from one context and watch the deny rule catch it. - Give
refund-needs-a-managera priority of 20 and watch it deny even a manager.
Every expert started right here.