Policy scope
Scope is a glob pattern on a policy that limits which action paths it applies to, and in 4.1.0 it takes effect only on the folder-scoped evaluation path, not the flat one this part has used.
Last updated: 14 Oct, 2026 · Agent Governance Toolkit 4.1.0
The Defaults: allow, deny, audit and block lesson built evaluators the way the whole part has: PolicyEvaluator(policies=[doc]). A policy can also carry a scope field, and whether that field does anything depends entirely on which evaluation path you are on, so this lesson shows both.
A policy with a scope, read flat
This file scopes itself to payments/* and denies an account deletion. Loaded into a flat evaluator, the scope field is read into the document and then never consulted, so the path in the context changes nothing.
version: "1.0"
name: payments-gov
scope: "payments/*"
rules:
- name: block-delete
condition: {field: action, operator: eq, value: delete_account}
action: deny
defaults:
action: allowimport warnings; warnings.simplefilter("ignore")
from agent_os.policies.schema import PolicyDocument
from agent_os.policies.evaluator import PolicyEvaluator
doc = PolicyDocument.from_yaml("governance.yaml")
print("scope read from file:", doc.scope)
flat = PolicyEvaluator(policies=[doc]) # no root_dir: the flat path
for path in ["payments/pay.py", "reports/report.py"]:
d = flat.evaluate({"action": "delete_account", "path": path})
print(f"{path:20} allowed={d.allowed}")scope read from file: payments/* payments/pay.py allowed=False reports/report.py allowed=False
The deletion is denied whether the path is under payments/ or reports/. The scope value loaded fine and had no effect on the verdict.
The same policy on the folder-scoped path
Scope only matters when the evaluator discovers policies by folder. Give it a root_dir and a governance.yaml on disk, and pass a path in the context, and the evaluator walks the folders, keeps a policy only when the path matches its scope glob, and applies it.
import os
from agent_os.policies.evaluator import PolicyEvaluator
# folder-scoped: a root dir, the governance.yaml on disk, and a path to match
scoped = PolicyEvaluator(root_dir=os.getcwd())
inside = scoped.evaluate({"action": "delete_account", "path": "payments/pay.py"})
outside = scoped.evaluate({"action": "delete_account", "path": "reports/report.py"})
print("under payments/:", inside.allowed)
print("under reports/ :", outside.allowed)under payments/: False under reports/ : True
What scope did on each path
- On the flat path, scope was inert. The policy applied to every path, because
PolicyEvaluator(policies=[doc])never looks at thescopefield. - On the folder-scoped path, scope filtered. A path under
payments/matched the glob and the deny applied; a path underreports/did not match, so the policy was dropped and the call took the allow default. - The field only works with folder discovery, which needs a
root_dir, a file namedgovernance.yaml, and apathin the context. Set a scope on a flat policy and nothing enforces it.
Flat path or folder-scoped path
| Flat evaluator | Folder-scoped evaluator | |
|---|---|---|
| Built with | policies=[doc] | root_dir=... |
| Finds policies by | The list you pass | Walking folders for governance.yaml |
| Needs a path in context | No | Yes |
Reads the scope field | No, it is inert | Yes, it filters by the glob |
Where scope fits
- A repository with per-folder rules, where each folder's
governance.yamlgoverns only its own paths. - A policy meant for one area, scoped so it cannot reach actions outside it.
- A single shared rule set, where you skip scope and pass the policy flat, because the glob would do nothing there.
scope on a policy you load flat looks like a safety limit and is not one; the field is stored and ignored. Use scope only on the folder-scoped path, and when you want one shared policy, leave scope off so nobody mistakes an inert field for a working one.Related
- Change the scope to
reports/*and watch the folder-scoped verdicts for the two paths swap. - Remove the
scopeline and see the folder-scoped evaluator apply the policy to both paths. - Pass the policy flat with no
pathin the context and confirm the verdict is unchanged.
Slow is fine. Stopping is the only problem.