Policy

Every action an agent takes is a request for a capability, with a target (the tool, the path, the host, the server). The policy decides each request: allow it, deny it, or ask a person. An ask pauses the run until someone decides (durable runs); the security model explains the design.

How a request is decided

A deny rule that matches wins.
Otherwise an ask rule that matches: a person decides. An ask outranks an allow, so 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 that matches.
Otherwise the policy’s mode decides: permissive allows, interactive asks, strict denies, each with reason unknown_capability and no rule named, so the evidence tells it apart from a rule’s decision.

A decision is recorded in the run’s trace with its effect and reason_code (matched_allow, matched_ask, matched_deny, unknown_capability, approved when a person allowed an ask, follows_command for the runtime’s own listing after a sandbox command, and others). Two capabilities are decided when the agent connects, not during a run: mcp.server.start and mcp.server.connect. There is no run to pause then, so an ask on them fails the connection with ApprovalRequiredError; allow the servers you trust. The served agent’s policy also decides what an operator asks of OmniServe’s background API: background.task.* and background.run.*. A refusal there is an HTTP 403.

Writing a rule

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"},
    )
)
agent_config = {"governance_config": {"enabled": True, "policy": policy}}

Or the whole policy as a dict:

agent_config = {
    "governance_config": {
        "enabled": True,
        "policy": {
            "name": "support-desk",
            "mode": "strict",  # anything no rule covers is denied
            "rules": {
                "allow": [{"rule_id": "tools", "capability": "tool.local.call"}],
                "ask": [
                    {
                        "rule_id": "refunds",
                        "capability": "tool.local.call",
                        "target": {"tool_name": "issue_refund"},
                    }
                ],
            },
        },
    }
}

Field	What it is
`rule_id`	Your name for the rule; it is recorded with every decision it makes.
`effect`	`allow`, `ask` or `deny` (the list it is in, for a dict policy).
`capability`	A capability below, or a glob: `workspace.files.`, `network.http.`, `*`.
`target`	Optional. Any of `tool_name`, `mcp_server`, `path`, `host`, `resource`; each a glob the request’s target must match.
`conditions`	Optional. `risk_level` (list), `provider`, `execution_surface`, `exclude_execution_surface` (list), `exclude_capability` (list of globs), `mcp_server`, `method`, `host`. A surface is one of `artifact`, `background`, `code`, `filesystem`, `host`, `mcp`, `memory`, `network`, `sandbox`, `secret`, `secret_broker`, `serve`, `subagent`, `telemetry`, `tool`, `workspace`; any other is refused when the policy loads.
`constraints`	Optional. `approval_expires_seconds` (how long a person’s decision stays valid), `sandbox_required`, `audit_required`.
`command`	Optional, `process.exec` rules only: what the rule matches in a shell command. See Rules on shell commands.
`examples`	Optional, with `command`: `match` and `not_match` lists of commands, checked when the policy loads. A rule that contradicts its own examples does not load.

A policy can carry its budgets under a budgets key: in a dict policy, in a JSON policy file (policy_path), or as policy.budgets on a policy object. It takes the same shape as governance_config["budgets"] (budgets), and the budgets are hashed with the policy. Set budgets in the policy or in governance_config, not both: both is refused.

Rules on shell commands

Command rules decide which commands run without asking. They are not a security boundary: what a command can touch is decided by the sandbox it runs in. An allowed program can do anything its own options allow, and sudo rm is a command named sudo, not rm; sh build.sh runs a script as python x.py does; and git -c alias.x='!rm -rf build' x is a command named git.

Every command an agent runs reaches the policy as process.exec on sh (the execute tool runs sh -c <command>). A command matcher names a command by its first words:

policy = {
    "name": "build-box",
    "mode": "strict",
    "rules": {
        "deny": [{"rule_id": "deny_rm", "capability": "process.exec",
                  "command": {"program": "rm"},
                  "examples": {"match": ["ls && rm -rf build"], "not_match": ["git rm x"]}}],
        "ask": [{"rule_id": "ask_git_push", "capability": "process.exec",
                 "command": {"prefix": ["git", ["push", "reset"]]}}],
        "allow": [{"rule_id": "allow_git_readonly", "capability": "process.exec",
                   "command": {"prefix": ["git", ["status", "log", "diff"]]}}],
    },
}

`command` field	Matches
`prefix`	The first words: the program’s name (without its directory), then later words. Each word is literal, or a list of alternatives.
`program`	Shorthand for a prefix of one word, or a list of alternatives for it.

How a command is read: only a plain chain (simple commands of literal words joined by &&, ||, ;, | or a newline) is split into its commands. Anything else makes the whole command unreadable: a redirect, $(...) or backticks, a variable or ~, a glob, a brace, an escape, a leading NAME=value, a subshell, a group, a heredoc, a function or loop, a command in the background, a program that runs text as a command (eval, source, exec, sh -c, trap, alias), or a shell reading commands from its input (... | sh). How a command is decided:

A deny or ask rule applies when any command of a readable line begins with its prefix: ls && rm -rf build is denied by the rule above.
An allow rule applies only when every command is matched by some allow rule and is named without a path (not ./git or /tmp/git): git status | head needs head allowed too.
An unreadable command is never allowed by a rule. Where the policy has any command rule for it, it is asked about, in every mode (refused in strict), with the reason code command_opaque: a deny rule on rm is not passed by eval "rm -rf x".
A policy without command rules decides exactly as before.

Words are literal: write alternatives (["-r", "-rf", "-fr"]) rather than patterns. A person asked to approve a command sees each command of a plain chain on its own line, or the whole text when it is unreadable, with control and invisible characters shown; the approval is bound to that exact text.

Capabilities

Capability	Allowing it lets the agent
`background.run.cancel`	Cancel a background run.
`background.run.start`	Start a background run.
`background.task.create`	Create a background task.
`background.task.delete`	Delete a background task.
`background.task.pause`	Pause a background task.
`background.task.resume`	Resume a background task.
`background.task.update`	Update a background task.
`code.run`	Run a program with run_code (code mode). Each tool it calls is decided on its own.
`filesystem.delete`	Delete a file on the host, outside the workspace. Target: path.
`filesystem.read`	Read a file on the host, outside the workspace. Target: path.
`filesystem.write`	Write a file on the host, outside the workspace. Target: path.
`mcp.server.connect`	Connect to a remote (SSE or streamable HTTP) MCP server. Decided when the agent connects, like mcp.server.start. Target: mcp_server.
`mcp.server.start`	Start a stdio MCP server process. Decided when the agent connects, outside any run: an ask cannot pause there, so it fails the connection. Target: mcp_server.
`network.http.delete`	Make an HTTP DELETE request. Target: host.
`network.http.get`	Make an HTTP GET request. Target: host.
`network.http.head`	Make an HTTP HEAD request. Target: host.
`network.http.patch`	Make an HTTP PATCH request. Target: host.
`network.http.post`	Make an HTTP POST request. Target: host.
`network.http.put`	Make an HTTP PUT request. Target: host.
`package.install`	Install a package. Target: resource (the package), host (the index).
`process.exec`	Run a command: in the sandbox (execution surface sandbox), or on the host with the local provider (surface host). Target: resource (the command’s name).
`sandbox.environment.set`	Set plain environment variables in the sandbox (their names are in the request, not the target).
`sandbox.execute`	Call the execute tool. Each command it runs is then decided as process.exec.
`sandbox.filesystem.cwd`	Run a command in a working directory the manifest or call names. Target: path.
`sandbox.filesystem.mount`	Mount a host directory into the sandbox. Target: path, resource (the source).
`sandbox.image.use`	Start the sandbox from an image named in the manifest. Target: resource (the image).
`sandbox.network.configure`	Turn the sandbox’s network on, or allow or deny a host in it. Target: host.
`sandbox.resources.set`	Set the sandbox’s CPU, memory, disk or time limits.
`sandbox.workspace.sync`	The runtime’s own listing of the sandbox’s files after a command, to copy what changed back to the workspace. Not an agent command: command rules do not judge it. With no rule of its own it follows the decision for the command that triggered it; a rule you write for it (allow, ask or deny) decides instead. Each file it copies back is still decided by the workspace file rules. Target: resource (the program).
`secret.read`	Read a secret’s value.
`secret.use`	Use a secret without reading it: brokered into a command, never shown to the model.
`skill.files.read`	Read a skill’s instructions and files.
`skill.script.run`	Run a skill’s script (run_skill_script): code runs.
`subagent.spawn`	Start a sub-agent: delegate_<name> to an agent in sub_agents, or spawn_subagents. Target: resource (the agent’s name).
`tool.local.call`	Call one of your Python tools (local_tools), or a sub-agent’s delegate_<name> tool. Target: tool_name.
`tool.mcp.call`	Call a tool on an MCP server. Target: mcp_server, tool_name.
`workspace.artifacts.call`	Any other artifact tool.
`workspace.artifacts.read`	Read a saved tool result: read_artifact, tail_artifact, search_artifact, list_artifacts.
`workspace.files.call`	Any other workspace file tool.
`workspace.files.clear`	Delete every file in the workspace (clear_files).
`workspace.files.delete`	Delete a workspace file (delete_file). Target: path.
`workspace.files.move`	Move or rename a workspace file (move_file). Target: path.
`workspace.files.read`	Read the workspace: ls, read_file, glob, grep. Target: path.
`workspace.files.write`	Write in the workspace: write_file, edit_file, insert_file. Target: path.

Built-in profiles

Each profile below is build_default_policy(name). Start from one and add rules, or write your own policy.

`permissive-dev`

Mode permissive.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
deny	`deny_unconfigured_secret_broker_use`	`secret.use`
deny	`deny_unrestricted_process_exec`	`process.exec`	`{'exclude_execution_surface': ['sandbox']}`
deny	`deny_unrestricted_host_filesystem_access`	`filesystem.*`
deny	`deny_unrestricted_network_egress`	`network.*`
deny	`deny_unrestricted_package_install`	`package.install`
ask	`ask_sandbox_network`	`sandbox.network.configure`
ask	`ask_sandbox_host_mount`	`sandbox.filesystem.mount`
allow	`allow_sandboxed_execution`	`process.exec`	`{'execution_surface': 'sandbox'}`
allow	`allow_sandbox_setup`	`sandbox.*`
allow	`allow_skill_scripts`	`skill.*`
allow	`allow_code_mode`	`code.*`
allow	`allow_local_dev_workspace`	`workspace.*`
allow	`allow_local_tools`	`tool.local.call`
allow	`allow_memory_and_telemetry`	`memory.*`
allow	`allow_telemetry`	`telemetry.*`
allow	`allow_subagent_spawn`	`subagent.*`
allow	`allow_background_execution`	`background.*`
allow	`allow_configured_mcp_servers`	`mcp.server.*`
allow	`allow_configured_mcp_tools`	`tool.mcp.call`

`interactive-dev`

Mode interactive.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
ask	`ask_process_exec`	`process.*`	`{'exclude_execution_surface': ['sandbox']}`
ask	`ask_sandbox_network`	`sandbox.network.configure`
ask	`ask_sandbox_host_mount`	`sandbox.filesystem.mount`
ask	`ask_network_egress`	`network.*`
ask	`ask_package_install`	`package.install`
ask	`ask_secret_broker_use`	`secret.use`
ask	`ask_mcp_tool_call`	`tool.mcp.call`
ask	`ask_mcp_server_start`	`mcp.server.*`
ask	`ask_subagent_spawn`	`subagent.*`
ask	`ask_background_execution`	`background.*`
ask	`ask_high_risk`	`*`	`{'risk_level': ['high', 'critical'], 'exclude_execution_surface': ['sandbox'], 'exclude_capability': ['skill.script.run']}`
allow	`allow_sandboxed_execution`	`process.exec`	`{'execution_surface': 'sandbox'}`
allow	`allow_sandbox_setup`	`sandbox.*`
allow	`allow_skill_scripts`	`skill.*`
allow	`allow_code_mode`	`code.*`
allow	`allow_local_tools`	`tool.local.call`
allow	`allow_workspace`	`workspace.*`
allow	`allow_memory`	`memory.*`
allow	`allow_telemetry`	`telemetry.*`

`strict-production`

Mode strict.

Effect	Rule	Capability	Conditions
deny	`deny_credential_or_system_prompt_flow`	`*`	`{'data_classes': ['credential', 'system_prompt']}`
deny	`deny_raw_secret_read`	`secret.read`
allow	`allow_governance_telemetry`	`telemetry.governance.*`

Get Started

Make It Safe

Run It

See and Improve

Build

How It Works

Reference

HTTP API (OmniServe)

Releases

Policy

Policy

How a request is decided

Writing a rule

Rules on shell commands

Capabilities

Built-in profiles

`permissive-dev`

`interactive-dev`

`strict-production`

​Policy

​How a request is decided

​Writing a rule

​Rules on shell commands

​Capabilities

​Built-in profiles

​permissive-dev

​interactive-dev

​strict-production

Policy

How a request is decided

Writing a rule

Rules on shell commands

Capabilities

Built-in profiles

`permissive-dev`

`interactive-dev`

`strict-production`