Define policy in code

A policy doesn’t have to live in YAML. You can construct the same validated model in Python, which is handy for tests, generated policies, and keeping policy next to the code it governs.

Three ways to build a policy

From a dict — the model validates it (including every constraint’s grammar):

from hexgate import AgentPolicy, enforce_policy

policy = AgentPolicy.model_validate({
    "version": 1,
    "default_policy": {"mode": "deny"},
    "tools": {
        "web_search": {"mode": "allow"},
        "refund_order": {"mode": "allow", "constraints": ["args.amount <= 500"]},
    },
})
agent = enforce_policy(agent, policy)

With PolicyBuilder — fluent, and C(...) gives you type-checked constraints instead of hand-written strings:

from hexgate import PolicyBuilder, C, enforce_policy

policy = (
    PolicyBuilder(default="deny")
    .allow("web_search")
    .allow("refund_order", when=[C("args.amount") <= 500, C("args.currency") == "USD"])
    .approve("edit_file")
    .build()
)
agent = enforce_policy(agent, policy)

C covers every operator: <= < > >= == !=, .is_in([...]), .not_in([...]), .count(), and cross-field comparisons (C("args.max") >= C("args.min")). Each constraint is validated the moment you write it, so a typo raises at that line — not later at enforcement. Role-aware, with RolePolicyBuilder — produces a PolicySet:

from hexgate import RolePolicyBuilder, PolicyBuilder, C

policies = (
    RolePolicyBuilder()
    .role("read_only", PolicyBuilder().allow("web_search"), mixin=True)
    .role("default", PolicyBuilder(), inherits=["read_only"])
    .role("billing",
          PolicyBuilder().allow("refund_order", when=[C("args.amount") <= 500]),
          inherits=["read_only"])
    .build()
)

Gate network egress

net_allow and net_approve are builder sugar for the egress plane. They render a host/scheme/port allowlist into ordinary net.http_request constraints, so an egress rule enforces the same way in both the pydantic and WASM engines.

from hexgate import PolicyBuilder

policy = (
    PolicyBuilder(default="deny")
    .net_allow(hosts=["api.github.com"], subdomains=["githubusercontent.com"])
    .net_approve(hosts=["api.stripe.com"])
    .build()
)

subdomains matches the apex and any child (example.com and *.example.com). A host restriction is required: pass hosts=, subdomains=, or any_host=True. Calling net_allow() with only a scheme or port filter raises, because it would authorize every host.

Restrict file tools to paths (`file_scope`)

The file tools read_file, write_file, edit_file (argument file_path), glob and grep (argument path) accept a file_scope that limits which paths they reach:

policy = AgentPolicy.model_validate({
    "version": 1,
    "default_policy": {"mode": "deny"},
    "tools": {
        "read_file": {
            "mode": "allow",
            "file_scope": {
                "allowed_paths": ["docs/*.md", "notes/**"],
                "denied_paths": ["notes/private/*"],
            },
        },
    },
})

tools.<name>.file_scope.denied_paths wins: a path matching it is denied even if file_scope.allowed_paths matches too.
With file_scope.allowed_paths set, a path that matches none of its patterns is denied.
A call without the path argument is denied.

file_scope is not a security boundary yet. Its path matching is being reworked: today some spellings of a path, such as ../, absolute paths or symlinks, can reach files the patterns were meant to exclude. Use it to steer an agent away from files, and rely on the workspace sandbox to contain it.

A denied call names the scope in its hint:

✗ DENY · [default] → read_file({"file_path": "src/app.py"})
  reason: Policy denied tool "read_file" for the requested path
  hint: {'allowed_paths': ['docs/*.md', 'notes/**'], 'denied_paths': ['notes/private/*']}

file_scope runs only on the default Pydantic engine. The WASM/Rego engine doesn’t support it yet, so hexgate policy validate and hexgate policy build reject a policy that uses it rather than produce a bundle that silently drops the path check. Keep it in policies you apply in code, and leave it out of YAML you build into bundles.

Unit-test a policy

The assert_* helpers evaluate a policy the same way the runtime enforces it:

from hexgate import PolicyBuilder, C, assert_allows, assert_denies, assert_needs_approval

policy = (
    PolicyBuilder()
    .allow("refund", when=[C("args.amount") <= 500])
    .approve("edit_file")
    .build()
)

assert_allows(policy, "refund", {"amount": 100})
assert_denies(policy, "refund", {"amount": 999})
assert_denies(policy, "some_unlisted_tool")          # deny-by-default
assert_needs_approval(policy, "edit_file")

For a PolicySet, pass role=:

assert_allows(policies, "refund_order", {"amount": 100}, role="billing")
assert_denies(policies, "refund_order", role="default")

The builder and C emit the exact constraint strings the YAML parser accepts, so a policy built in code enforces identically to the same policy in YAML — there is only one grammar.

Get started

Concepts

Framework adapters

Policy

CLI

Define policy in code

Three ways to build a policy

Gate network egress

Restrict file tools to paths (`file_scope`)

Unit-test a policy

​Three ways to build a policy

​Gate network egress

​Restrict file tools to paths (file_scope)

​Unit-test a policy

Three ways to build a policy

Gate network egress

Restrict file tools to paths (`file_scope`)

Unit-test a policy