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

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.

yaml
version: "1.0"
name: payments-gov
scope: "payments/*"
rules:
  - name: block-delete
    condition: {field: action, operator: eq, value: delete_account}
    action: deny
defaults:
  action: allow
ExampleFlat evaluation reads scope but never acts on it
import 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}")

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.

ExampleFolder-scoped evaluation honours the scope glob
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)

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 the scope field.
  • On the folder-scoped path, scope filtered. A path under payments/ matched the glob and the deny applied; a path under reports/ 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 named governance.yaml, and a path in the context. Set a scope on a flat policy and nothing enforces it.

Flat path or folder-scoped path

Flat evaluatorFolder-scoped evaluator
Built withpolicies=[doc]root_dir=...
Finds policies byThe list you passWalking folders for governance.yaml
Needs a path in contextNoYes
Reads the scope fieldNo, it is inertYes, it filters by the glob

Where scope fits

  • A repository with per-folder rules, where each folder's governance.yaml governs 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.
Watch out. Setting 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.
Try it yourself
  • Change the scope to reports/* and watch the folder-scoped verdicts for the two paths swap.
  • Remove the scope line and see the folder-scoped evaluator apply the policy to both paths.
  • Pass the policy flat with no path in the context and confirm the verdict is unchanged.

Slow is fine. Stopping is the only problem.