Policies

A policy decides every request an agent makes: allow, ask or deny. Here: write one, test it without a model, and read its decisions.

Every output on this page is what the code printed when it was run. The model’s wording will differ on your run; the decisions will not.

Start from a profile, add a rule

A built-in profile plus the one rule you need:

from omnicoreagent import OmniCoreAgent
from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

policy = build_default_policy("interactive-dev")
policy.rules.ask.append(
    PolicyRule(
        rule_id="ask_before_refunds",
        effect=PolicyEffect.ASK,
        capability="tool.local.call",
        target={"tool_name": "issue_refund"},
        reason="Refunds need a person.",
    )
)

agent = OmniCoreAgent(
    name="support",
    system_instruction="You help with orders.",
    model_config={"provider": "openai", "model": "gpt-5.4-mini"},
    agent_config={"governance_config": {"enabled": True, "policy": policy}},
)

Every issue_refund call now pauses for a person (Approvals). Or set "profile": "..." alone. The three profiles on the same four calls (the script is below):

permissive-dev
  lookup_order  allow ['allow_local_tools']
  write_file    allow ['allow_local_dev_workspace']
  delete_file   allow ['allow_local_dev_workspace']
  search        allow matched_allow
interactive-dev
  lookup_order  allow ['allow_local_tools']
  write_file    allow ['allow_workspace']
  delete_file   ask   ['ask_high_risk']
  search        ask   ['ask_mcp_tool_call']
strict-production
  lookup_order  deny  unknown_capability
  write_file    deny  unknown_capability
  delete_file   deny  unknown_capability
  search        deny  unknown_capability

lookup_order is your tool, search an MCP tool. A delete is high-risk, so interactive-dev’s ask_high_risk asks. Every profile rule: policy reference.

A rule

A rule:

{
    "rule_id": "no_prod_deletes",          # recorded with every decision it makes
    "capability": "workspace.files.delete", # or a glob: "workspace.files.*", "*"
    "target": {"path": "prod/*"},           # optional: tool_name, mcp_server, path, host, resource
    "conditions": {"risk_level": ["high", "critical"]},  # optional
    "reason": "Nothing under prod/ is deleted by an agent.",  # optional
}

Field	Matches
`capability`	`tool.local.call`, `workspace.files.write`, … or a glob (all)
`target`	`tool_name`, `mcp_server`, `path`, `host`, `resource` (globs)
`conditions`	`risk_level`, `provider`, `execution_surface`, `exclude_execution_surface`, `exclude_capability`, `mcp_server`, `method`, `host`
`constraints`	`approval_expires_seconds`, `sandbox_required`, `audit_required`
`reason`	shown to the approver, recorded with the decision

Its effect is the list it is in: deny, ask or allow.

How a request is decided

A deny rule matches: denied

Deny wins over everything. The model is told the call was refused and why.

Otherwise an ask rule matches: a person decides

An ask outranks an allow. Adding an allow rule to a profile does not lift that profile’s asks; remove the ask rule, or write your own policy.

Otherwise an allow rule matches: allowed

Otherwise the mode decides

permissive allows, interactive asks, strict denies. The decision’s reason_code is unknown_capability and matched_rule_ids is empty.

matched_rule_ids lists every matching rule in the winning list.

Test a rule before you run

Build the request a tool call makes and ask the evaluator the agent uses. No model needed:

from omnicoreagent.governance import (
    PolicyEvaluator,
    policy_from_mapping,
    tool_authority_requests,
)

policy = policy_from_mapping({
    "name": "support-desk",
    "mode": "strict",
    "rules": {
        "deny": [
            {"rule_id": "no_bulk_refunds", "capability": "tool.local.call",
             "target": {"tool_name": "refund_all"}},
        ],
        "ask": [
            {"rule_id": "ask_before_refunds", "capability": "tool.local.call",
             "target": {"tool_name": "issue_refund"},
             "reason": "Refunds need a person."},
        ],
        "allow": [
            {"rule_id": "my_tools", "capability": "tool.local.call"},
            {"rule_id": "read_workspace", "capability": "workspace.files.read"},
        ],
    },
})

evaluator = PolicyEvaluator()
calls = [
    ("lookup_order", "local", {"order_id": "1042"}),
    ("issue_refund", "local", {"order_id": "1042", "amount": 42.0}),
    ("refund_all", "local", {}),
    ("read_file", "workspace", {"path": "notes.md"}),
    ("write_file", "workspace", {"path": "notes.md", "content": "hi"}),
]
for name, provider, args in calls:
    for request in tool_authority_requests(tool_name=name, tool_args=args, tool_provider=provider):
        decision = evaluator.evaluate(policy, request)
        print(f"{name:13} {request.capability:22} {decision.effect.value:5} "
              f"{decision.reason_code.value:19} {decision.matched_rule_ids}")

lookup_order  tool.local.call        allow matched_allow       ['my_tools']
issue_refund  tool.local.call        ask   matched_ask         ['ask_before_refunds']
refund_all    tool.local.call        deny  matched_deny        ['no_bulk_refunds']
read_file     workspace.files.read   allow matched_allow       ['read_workspace']
write_file    workspace.files.write  deny  unknown_capability  []

tool_provider: local, workspace, artifact, mcp (with tool_server), skill, sandbox or code. write_file fell through to strict mode. Put checks like these in your tests. The profile comparison above:

from omnicoreagent.governance import PolicyEvaluator, build_default_policy, tool_authority_requests

calls = [
    ("lookup_order", "local", {"order_id": "1042"}),
    ("write_file", "workspace", {"path": "notes.md", "content": "hi"}),
    ("delete_file", "workspace", {"path": "notes.md"}),
    ("search", "mcp", {"q": "refunds"}),
]
evaluator = PolicyEvaluator()
for profile in ("permissive-dev", "interactive-dev", "strict-production"):
    policy = build_default_policy(profile)
    print(profile)
    for name, provider, args in calls:
        request = tool_authority_requests(
            tool_name=name, tool_args=args, tool_provider=provider,
            tool_server="docs" if provider == "mcp" else None,
        )[0]
        decision = evaluator.evaluate(policy, request)
        print(f"  {name:13} {decision.effect.value:5} {decision.matched_rule_ids or decision.reason_code.value}")

Three ways to give the policy

A dict
Objects
A policy file

The whole policy in your code. Here, a strict policy that allows one tool and nothing else:

import asyncio
from omnicoreagent import OmniCoreAgent, ToolRegistry

tools = ToolRegistry()

@tools.register_tool("lookup_order")
def lookup_order(order_id: str) -> dict:
    """Look an order up."""
    return {"order_id": order_id, "status": "processing", "total": 42.0}

@tools.register_tool("cancel_order")
def cancel_order(order_id: str) -> dict:
    """Cancel an order."""
    return {"order_id": order_id, "cancelled": True}

policy = {
    "name": "support-desk",
    "mode": "strict",  # anything no rule covers is denied
    "rules": {
        "allow": [
            {"rule_id": "lookups", "capability": "tool.local.call",
             "target": {"tool_name": "lookup_order"}},
        ],
    },
}

async def main():
    agent = OmniCoreAgent(
        name="support",
        system_instruction="You help with orders. Answer in plain text, in one sentence.",
        model_config={"provider": "openai", "model": "gpt-5.4-mini"},
        local_tools=tools,
        agent_config={"governance_config": {"enabled": True, "policy": policy}},
    )
    result = await agent.run("Cancel order 1042.")
    print(result["response"])

    trajectory = await agent.get_trajectory(result["trace_id"])
    for step in trajectory["steps"]:
        for call in step["tool_calls"]:
            print(call["tool_name"], call["outcome"], call["error"])
            for decision in call["governance"]:
                print("  ", decision["capability"], decision["effect"],
                      decision["reason_code"], decision["matched_rule_ids"])
    await agent.cleanup()

asyncio.run(main())

I’m unable to cancel order 1042 because the system denied the action.
cancel_order denied {'type': 'UnknownCapabilityError', 'message': 'Denied by strict policy: no rule matches this tool.local.call request.'}
   tool.local.call deny unknown_capability []

The tool never ran; the model was told why. (“No rule covers” means no rule matched this call: lookups only matches lookup_order.)

build_default_policy(name) returns a PolicyEnvelope; append PolicyRules to rules.deny, rules.ask, rules.allow and pass it as "policy". policy_from_mapping(dict) builds one from a dict.

JSON only:

{
  "name": "support-desk",
  "mode": "strict",
  "rules": {
    "ask": [
      {"rule_id": "ask_before_refunds", "capability": "tool.local.call",
       "target": {"tool_name": "issue_refund"}}
    ],
    "allow": [
      {"rule_id": "my_tools", "capability": "tool.local.call"}
    ]
  }
}

agent_config = {
    "governance_config": {
        "enabled": True,
        "policy_path": "policies/support.json",
    }
}

Read on the first run. To test it, load it the way the agent does:

from omnicoreagent.governance import PolicyEvaluator, load_policy_file, tool_authority_requests

policy = load_policy_file("policies/support.json", project_root=".")
print(policy.name, policy.mode.value, policy.provenance.source.value, policy.provenance.policy_hash[:16])

request = tool_authority_requests(tool_name="issue_refund", tool_args={"order_id": "1042", "amount": 42.0})[0]
decision = PolicyEvaluator().evaluate(policy, request)
print(decision.effect.value, decision.matched_rule_ids)

support-desk strict file f86919474a7abb3a
ask ['ask_before_refunds']

The agent records the same hash in every trace.The file must be inside project_root (default: current directory), and not in the workspace or under a directory named workspace(s), artifact(s), output(s), tmp or temp.

Auto-discovery. With neither policy nor policy_path, an omnicoreagent.policy.json or .omnicoreagent/policy.json in the project root is merged onto the profile. It can only narrow: its deny and ask rules are added, the stricter mode wins, and a wider allow is refused.

Read the decision

Each tool call in a trajectory has a governance list:

Key	What
`capability`	What was requested
`effect`	`allow`, `ask` or `deny`
`reason_code`	`matched_*`, `unknown_capability` (mode decided), `approved` (a person)
`matched_rule_ids`	the rules behind it
`approval_id`, `approved_by`	set when a person approved

trajectory["harness"]["governance"] has the policy_hash. An approved ask shows two entries: ask, then allow with approved.

Options

In agent_config["governance_config"]:

Key	Default	What it does
`enabled`	`False`	Turns governance on
`profile`	`"interactive-dev"`	Built-in profile
`policy`	`None`	Dict or `PolicyEnvelope`
`policy_path`	`None`	JSON policy file
`project_root`	current directory	Where policy files may live
`approval_mode`, `approval_resolver`	`"suspend"`, `None`	Approvals
`budgets`	`None`	Budgets
`sandbox_config`, `sandbox_manifest`	`None`	Sandbox providers

All settings: agent settings reference.

When things go wrong

ValueError: governance_config cannot set both policy and policy_path

Raised by OmniCoreAgent(...). Pick one: the policy in code, or the file.

PolicyLoadError: Policy file is inside an agent-writable directory

Raised on the first run. The file is in the workspace, or under a directory with one of the names the agent may write to (paths shortened here):

PolicyLoadError: Policy file is inside an agent-writable directory: /srv/app/workspace/policy.json

Move it, for example to policies/.

PolicyLoadError: Policy file escapes trusted project root

The file is outside project_root, which is the current directory unless you set it (path shortened here):

PolicyLoadError: Policy file escapes trusted project root: /srv/outside-policy.json

Set project_root to a directory that contains the file, or move it. Policy file not found: ... means the path is wrong; a relative path is read from the current directory.

PolicyLoadError: YAML policy loading is not enabled

Only JSON policy files are read:

PolicyLoadError: YAML policies are not supported. Use a JSON policy file or a policy in code.

PolicyLoadError: Auto-discovered policy allow rule broadens the default baseline

An omnicoreagent.policy.json that the agent found on its own tried to allow something the profile does not:

PolicyLoadError: Auto-discovered policy allow rule broadens the default baseline: web

A discovered file can only narrow. To widen what is allowed, pass the file explicitly with policy_path.

A rule is rejected when the policy is built

A rule’s shape is checked when the policy is built:

ValueError: Rule 'r' declares effect 'deny' but is stored in the allow bucket
ValueError: Duplicate policy rule_id: r
TypeError: PolicyRule.__init__() got an unexpected keyword argument 'targets'
TypeError: TargetMatcher.__init__() got an unexpected keyword argument 'tool'
ValueError: 'ask' is not a valid PolicyMode

Each rule_id must be unique across the policy; the fields are those in A rule; the mode is permissive, interactive or strict.

ApprovalRequiredError when the agent connects to an MCP server

mcp.server.start and mcp.server.connect are decided when the agent connects, outside any run, so there is nothing to pause. An ask there (as in interactive-dev) fails the connection:

ApprovalRequiredError: Matched ask policy rule.

Allow the servers you trust, by the name you gave them in mcp_tools: {"rule_id": "docs_server", "capability": "mcp.server.*", "target": {"mcp_server": "docs"}}. An allow does not lift a profile’s ask, so with a profile, also remove its ask rule:

from omnicoreagent.governance import PolicyEffect, PolicyRule, build_default_policy

policy = build_default_policy("interactive-dev")
policy.rules.ask = [r for r in policy.rules.ask if r.rule_id != "ask_mcp_server_start"]
policy.rules.allow.append(
    PolicyRule(rule_id="docs_server", effect=PolicyEffect.ALLOW,
               capability="mcp.server.*", target={"mcp_server": "docs"})
)

The docs server now connects; any other server is still asked about, and so still fails to connect.

Approvals

What happens at an ask: pause, decide, resume.

Policy reference

Every capability, and every rule of each profile.

Security model

How the policy fits with the sandbox, budgets and the rest.

Execution

Commands, skill scripts and code mode, and the capabilities they use.

Budgets

Limits that live next to the policy.

Sandbox providers

Where the agent’s commands run.

Get Started

Build

Make It Safe

Run It

See and Improve

How It Works

Reference

HTTP API (OmniServe)

Releases

Policies

Policies

Start from a profile, add a rule

A rule

How a request is decided

Test a rule before you run

Three ways to give the policy

Read the decision

Options

When things go wrong

Next

Approvals

Policy reference

Security model

Execution

Budgets

Sandbox providers

​Policies

​Start from a profile, add a rule

​A rule

​How a request is decided

​Test a rule before you run

​Three ways to give the policy

​Read the decision

​Options

​When things go wrong

​Next

Approvals

Policy reference

Security model

Execution

Budgets

Sandbox providers

Policies

Start from a profile, add a rule

A rule

How a request is decided

Test a rule before you run

Three ways to give the policy

Read the decision

Options

When things go wrong

Next