Governing Agents with Policies: Allow, Deny, and Ask

Policies are declarative gates that evaluate every agent action at specific enforcement points and return one of three verdicts: ALLOW (the action proceeds), DENY (the action is blocked and the agent receives an error), or ASK (the action is paused for your approval — approved becomes ALLOW, refused becomes DENY). Multiple policies can be active at once; they compose in declaration order, and a DENY from any policy short-circuits the rest.

Session policies evaluate first and can enforce stricter rules than the agent spec or server defaults — a user-level policy can DENY an action before spec or admin policies ever run.

Policy trust levels

Policies are configured at three levels, each serving a different persona.

Level	Who sets it	How	Evaluated
Server-wide	Admin	`policies` block in server config YAML, or REST API	Last
Agent spec	Agent developer	`policies` block in agent YAML	Middle
Session	End user	Session info panel in the web UI, or chat	First

Session policies evaluate before spec policies, which evaluate before server-wide policies. This means a session-level DENY short-circuits the rest of the chain.

Configuring server-wide policies

Server-wide policies act as organizational guardrails and apply to every session on the server.

Add policies to your server config

# server_config.yaml
policies:
  session_budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 10.00
      ask_thresholds_usd: [5.00]
  global_rate_limit:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 200

If you use policies outside the builtins, register their module paths so they appear in the registry:

# server_config.yaml
policy_modules:
  - myorg_policies
  - github_mcp_policy

Start the server

omnigent server --config server_config.yaml

You can also add or remove policies at runtime through the REST API. For example, to create a server-wide policy:

curl -X POST http://localhost:6767/v1/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "global_rate_limit",
    "type": "python",
    "handler": "omnigent.policies.builtins.safety.max_tool_calls_per_session",
    "factory_params": {"limit": 200}
  }'

Adding policies to an agent spec

Policies declared in an agent YAML apply to every session that uses that agent. They are evaluated in declaration order:

name: github_agent
prompt: You are a coding assistant with access to GitHub.

executor:
  harness: claude-sdk
  model: databricks-claude-sonnet-4-6

tools:
  github:
    type: mcp
    url: https://api.githubcopilot.com/mcp/

policies:
  limit_tool_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 100
  github_access:
    type: function
    handler: omnigent.policies.builtins.github.github_policy
    factory_params:
      write_repos:
        - myorg/my-repo
      write_branches:
        - "feature/*"
  google_policy:
    type: function
    handler: omnigent.policies.builtins.google.gdrive_policy
    factory_params:
      read_all: true
      allow_create: true

Each policy entry requires type ("function") and handler (a dotted Python import path). Add factory_params when the handler is a factory that accepts configuration.

Adding policies to a session

Session-level policies let you customize agent behavior for your current task without modifying the spec or server config. There are two ways to add them:

Web UI — Open the session’s info panel to browse available policies and toggle them on or off.
Chat — Tell the agent directly, for example: “Add a policy that asks me before running shell commands.” The agent uses its built-in sys_add_policy tool to configure it.

Builtin policies

Safety

Handler	Description	Key parameters
`omnigent.policies.builtins.safety.max_tool_calls_per_session`	DENYs after a total tool-call limit is reached	`limit` (int, default `100`)
`omnigent.policies.builtins.safety.ask_on_os_tools`	ASKs before any `sys_os_read`, `sys_os_write`, `sys_os_edit`, or `sys_os_shell` call (and native equivalents)	none
`omnigent.policies.builtins.safety.block_skills`	DENYs loading of specific skills by name	`blocked` (string[])
`omnigent.policies.builtins.safety.enforce_sandbox`	Forces a sandbox configuration on every agent start	`sandbox_type`, `allow_network`, `write_paths`, `read_paths`, `env_passthrough`
`omnigent.policies.builtins.safety.deny_pii_in_llm_request`	Scans user messages and LLM prompts for PII patterns	`pii_types`, `action`

Cost

Handler	Description	Key parameters
`omnigent.policies.builtins.cost.cost_budget`	ASKs at soft thresholds; DENYs tool calls on expensive models once the hard limit is reached	`max_cost_usd`, `ask_thresholds_usd`, `expensive_models`
`omnigent.policies.builtins.cost.user_daily_cost_budget`	Same behavior as `cost_budget` but tracks the session owner’s cumulative spend across all sessions for the current UTC day	`max_cost_usd`, `ask_thresholds_usd`, `expensive_models`

GitHub

Handler	Description	Key parameters
`omnigent.policies.builtins.github.github_policy`	Controls GitHub access via MCP tools and shell commands; restricts writes to specific repos and branches	`write_repos`, `write_branches`, `read_all`, `read_repos`

Google Workspace

Handler	Description	Key parameters
`omnigent.policies.builtins.google.gdrive_policy`	Controls Google Drive/Docs/Sheets/Slides access	`read_all`, `allow_create`, `write_files`
`omnigent.policies.builtins.google.gmail_policy`	Controls Gmail access — defaults to read + draft, no send	`allow_read`, `allow_send`, `allow_drafts`
`omnigent.policies.builtins.google.gcalendar_policy`	Controls Google Calendar access — defaults to read-only	`allow_read`, `allow_create_events`, `allow_modify_events`

Working directory

Handler	Description	Key parameters
`omnigent.policies.builtins.working_dir.block_working_dir_changes`	Blocks `cd`, `pushd`, `git -C`, and `git worktree` commands	`block_cd`, `block_worktree`, `allowed_dirs`, `action`

Routing

Handler	Description	Key parameters
`omnigent.policies.builtins.routing.deny_trivial_to_expensive_model`	Classifies messages as TRIVIAL or COMPLEX and denies trivial tasks from using expensive models	`expensive_models`, `classification_prompt`

Full YAML examples

max_tool_calls_per_session
ask_on_os_tools
cost_budget

cap_calls:
  type: function
  handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
  factory_params:
    limit: 50

approve_file_ops:
  type: function
  handler: omnigent.policies.builtins.safety.ask_on_os_tools

No factory_params are needed — this is a direct callable, not a factory.

budget:
  type: function
  handler: omnigent.policies.builtins.cost.cost_budget
  factory_params:
    max_cost_usd: 5.00
    ask_thresholds_usd: [1.00, 3.00]
    expensive_models: ["opus", "gpt-5.5"]

Writing a custom policy

A policy is a Python callable that receives a PolicyEvent dict and returns a PolicyResponse dict (or None to abstain).

from omnigent.policies.schema import PolicyEvent, PolicyResponse

def my_policy(event: PolicyEvent) -> PolicyResponse | None:
    if event["type"] != "tool_call":
        return None  # abstain on non-tool phases
    tool = event["data"]["name"]
    if tool == "dangerous_tool":
        return {"result": "DENY", "reason": "This tool is blocked."}
    return {"result": "ALLOW"}

For policies that need configuration, write a factory — a function that accepts parameters and returns the actual evaluator:

def block_domains(blocked_domains: list[str]) -> callable:
    blocked = frozenset(d.lower() for d in blocked_domains)

    def evaluate(event: PolicyEvent) -> PolicyResponse | None:
        if event["type"] != "tool_call" or event["target"] != "web_fetch":
            return None
        url = event["data"]["arguments"].get("url", "")
        for domain in blocked:
            if domain in url.lower():
                return {"result": "DENY", "reason": f"Domain {domain} is blocked."}
        return {"result": "ALLOW"}

    return evaluate

The result field is the only required key in the response dict. Valid values are "ALLOW", "DENY", and "ASK". Return None to abstain and let the next policy in the chain evaluate. To make custom policies appear in the UI registry, export a POLICY_REGISTRY list from your module and register the module in the server config under policy_modules.

Builtin policy reference

Full parameter tables, default values, and YAML examples for every builtin policy.

Get Started

Core Concepts

Guides

Deployment

Reference

Governing Agents with Policies: Allow, Deny, and Ask

Policy trust levels

Configuring server-wide policies

Adding policies to an agent spec

Adding policies to a session

Builtin policies

Safety

Cost

GitHub

Google Workspace

Working directory

Routing

Full YAML examples

Writing a custom policy

Builtin policy reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Reference

Documentation Index

​Policy trust levels

​Configuring server-wide policies

​Adding policies to an agent spec

​Adding policies to a session

​Builtin policies

​Safety

​Cost

​GitHub

​Google Workspace

​Working directory

​Routing

​Full YAML examples

​Writing a custom policy

Builtin policy reference

Build docs developers (and LLMs) love

Policy trust levels

Configuring server-wide policies

Adding policies to an agent spec

Adding policies to a session

Builtin policies

Safety

Cost

GitHub

Google Workspace

Working directory

Routing

Full YAML examples

Writing a custom policy