Builtin Policy Reference: All Omnigent Policy Handlers

Builtin policies are Python callables in the omnigent.policies.builtins namespace that you reference by dotted path in your agent YAML or server config. Each policy follows the same contract: it receives a PolicyEvent dict and returns one of three verdicts — ALLOW (proceed), DENY (block with an error), or ASK (pause for user approval). Multiple policies compose: the engine evaluates them in declaration order, and a DENY from any policy short-circuits the rest.

Safety

Module: omnigent.policies.builtins.safety

max_tool_calls_per_session

Kind: factory — requires factory_params. Limits the total number of tool calls in a session. DENYs once the limit is reached.

Parameter	Type	Default	Description
`limit`	integer	`100`	Maximum tool calls allowed across the session.

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

ask_on_os_tools

Kind: direct callable — no factory_params needed. Requires user approval (ASK) before any file or shell tool call. Covers:

Omnigent built-in OS tools: sys_os_read, sys_os_write, sys_os_edit, sys_os_shell
Claude Code and Codex native tools: Bash, Read, Write, Edit, Glob, Grep (via the PreToolUse hook)
Pi native tools: read, bash, write, edit

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

ask_on_add_policy

Kind: direct callable — no factory_params needed. Requires user approval (ASK) before sys_add_policy executes. Prevents agents from silently installing new policies on a session.

policies:
  guard_policy_adds:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_add_policy

block_skills

Kind: factory — requires factory_params. Prevents the agent from loading specific skills. Matching is case-insensitive. Intercepts:

load_skill and read_skill_file runner tools (non-native harnesses)
The native Skill tool on Claude Code and Codex (via the PreToolUse hook)
Slash commands (/skill-name) submitted by the user

Parameter	Type	Default	Description
`blocked`	list of strings	(required)	Skill names to block. Case-insensitive.

policies:
  no_deploy_skill:
    type: function
    handler: omnigent.policies.builtins.safety.block_skills
    factory_params:
      blocked: [deploy, rollback]

enforce_sandbox

Kind: factory — requires factory_params. Forces a specific sandbox configuration on every agent start. Intercepts the synthetic __agent_start tool call and overrides the agent’s declared sandbox config. Fields not specified in the policy are inherited from the agent’s existing config.

Parameter	Type	Default	Description
`sandbox_type`	string	`linux_bwrap`	Sandbox backend to force: `linux_bwrap`, `darwin_seatbelt`, or `none`.
`allow_network`	boolean	`true`	Whether to allow network access in the sandbox.
`write_paths`	list of strings	`null` (inherit)	Writable paths to enforce. `null` inherits the agent’s existing config.
`read_paths`	list of strings	`null` (inherit)	Read-only paths to enforce. `null` inherits the agent’s existing config.
`env_passthrough`	list of strings	`null` (inherit)	Environment variables allowed through the sandbox. `null` inherits.

policies:
  enforce_bwrap:
    type: function
    handler: omnigent.policies.builtins.safety.enforce_sandbox
    factory_params:
      sandbox_type: linux_bwrap
      allow_network: false
      write_paths: ["/workspace"]

deny_pii_in_llm_request

Kind: factory — requires factory_params. Scans user messages and LLM request prompts for PII patterns. Fires on both the request phase (user messages) and the llm_request phase (full prompt content). Works with all harnesses.

Parameter	Type	Default	Description
`pii_types`	list of strings	all categories	PII categories to scan: `ssn`, `credit_card`, `email`, `phone`. Defaults to all four when empty or omitted.
`action`	string	`DENY`	Action when PII is detected: `DENY` or `ASK`.

policies:
  no_pii:
    type: function
    handler: omnigent.policies.builtins.safety.deny_pii_in_llm_request
    factory_params:
      pii_types: [ssn, credit_card]
      action: DENY

Cost

Module: omnigent.policies.builtins.cost

cost_budget

Kind: factory — requires factory_params. Gates a session on cumulative LLM spend (USD) at the tool-call phase. Behavior:

Soft thresholds (ask_thresholds_usd): ASKs the first time spend crosses each checkpoint. Approved checkpoints are remembered in session state and won’t re-prompt. A declined ASK blocks that one tool call and re-asks next time.
Hard limit (max_cost_usd): once reached, acts as a downgrade gate — DENYs tool calls while the session is on an expensive model, telling the user to switch with /model. Once on a cheaper model, tool calls are allowed again.

Parameter	Type	Default	Description
`max_cost_usd`	number	(required)	Hard spend limit in USD.
`ask_thresholds_usd`	list of numbers	`null`	Soft warning checkpoints in USD. Each value must be `> 0` and `< max_cost_usd`.
`expensive_models`	list of strings	Opus + GPT-5.5	Case-insensitive substring tokens for the model tiers blocked once over budget (e.g. `opus` matches any Opus deployment). `[]` disables the hard limit.

policies:
  session_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"]

user_daily_cost_budget

Kind: factory — requires factory_params. Same ASK / downgrade-gate behavior as cost_budget, but the budget is the session owner’s cumulative spend across all their sessions for the current UTC day. Soft-threshold approvals are remembered per user+day, so an approved checkpoint won’t re-prompt that user again today — even from a different session. Useful as a server-wide per-user daily cap.

Parameter	Type	Default	Description
`max_cost_usd`	number	(required)	Hard daily limit in USD.
`ask_thresholds_usd`	list of numbers	`null`	Soft daily warning checkpoints in USD.
`expensive_models`	list of strings	Opus + GPT-5.5	Case-insensitive substring tokens for blocked model tiers. `[]` disables the hard limit.

# server_config.yaml — a per-user daily cap applied to every session
policies:
  daily_budget:
    type: function
    handler: omnigent.policies.builtins.cost.user_daily_cost_budget
    factory_params:
      max_cost_usd: 25.00
      ask_thresholds_usd: [10.00, 20.00]

GitHub

Module: omnigent.policies.builtins.github

github_policy

Kind: factory — requires factory_params. Controls GitHub access across MCP tools and git/gh shell commands. Covers:

The official GitHub MCP server (per-operation tools like create_pull_request, push_files, etc.)
The layered HTTP-proxy wrapper (github_read_api_call / github_write_api_call)
git and gh commands dispatched through sys_os_shell

Shell commands whose target repo or branch cannot be determined (e.g. a local remote alias) return ASK rather than DENY.

Parameter	Type	Default	Description
`read_all`	boolean	`true`	Allow all reads. When `false`, restrict reads to `read_repos`.
`read_repos`	list of strings	`[]`	Repos readable when `read_all` is `false`, as `owner/repo` or GitHub URLs.
`write_repos`	list of strings	`[]`	Repos the agent may write to, as `owner/repo` or GitHub URLs.
`write_branches`	list of strings	`[]`	Branches writable within allowed repos. Empty means any branch is writable.
`mcp_tool_prefixes`	list of strings	`["mcp__github__", "github__"]`	Tool-name prefixes to strip when canonicalizing GitHub MCP tool names.
`shell_tools`	list of strings	`["sys_os_shell"]`	Shell tools whose `command` argument is parsed for git/gh invocations.

policies:
  github_guard:
    type: function
    handler: omnigent.policies.builtins.github.github_policy
    factory_params:
      write_repos:
        - myorg/frontend
        - myorg/backend
      write_branches:
        - main
        - develop

Branch names are matched exactly (git branch names are case-sensitive). Glob patterns are not supported — list each branch you want to allow individually.

Google Workspace

Module: omnigent.policies.builtins.google All three Google policies recognize tools from mcp__google__* and google__* server prefixes by default.

gdrive_policy

Kind: factory — requires factory_params. Controls Google Drive / Docs / Sheets / Slides access. Writes are restricted to files the agent created in the current session plus any explicitly allowed files.

Parameter	Type	Default	Description
`read_all`	boolean	`true`	Allow all reads. When `false`, only `read_files` are readable.
`read_files`	list of strings	`[]`	File IDs or Google URLs readable when `read_all` is `false`.
`allow_create`	boolean	`false`	Allow creating new files.
`write_files`	list of strings	`[]`	File IDs or URLs writable regardless of whether the agent created them.
`comment_files`	list of strings	`[]`	File IDs or URLs the agent may comment on (in addition to files it created).
`tool_prefixes`	list of strings	`["mcp__google__", "google__"]`	Tool-name prefixes to strip.

policies:
  gdrive_guard:
    type: function
    handler: omnigent.policies.builtins.google.gdrive_policy
    factory_params:
      read_all: true
      allow_create: true

gmail_policy

Kind: factory — requires factory_params. Controls Gmail access. Defaults to read + draft but no send. Draft edits are restricted to drafts the agent created this session.

Parameter	Type	Default	Description
`allow_read`	boolean	`true`	Allow reading mail (search, list, get).
`allow_send`	boolean	`false`	Allow sending mail. Off by default (draft-only).
`allow_drafts`	boolean	`true`	Allow creating drafts and editing the agent’s own drafts.
`allow_modify`	boolean	`false`	Allow modifying messages/threads (labels, move, trash).
`tool_prefixes`	list of strings	`["mcp__google__", "google__"]`	Tool-name prefixes to strip.

policies:
  gmail_guard:
    type: function
    handler: omnigent.policies.builtins.google.gmail_policy
    factory_params:
      allow_read: true
      allow_send: false
      allow_drafts: true

gcalendar_policy

Kind: factory — requires factory_params. Controls Google Calendar access. Defaults to read-only.

Parameter	Type	Default	Description
`allow_read`	boolean	`true`	Allow reading calendars/events/free-busy.
`allow_create_events`	boolean	`false`	Allow creating events or calendars.
`allow_modify_events`	boolean	`false`	Allow updating or deleting events.
`tool_prefixes`	list of strings	`["mcp__google__", "google__"]`	Tool-name prefixes to strip.

policies:
  calendar_guard:
    type: function
    handler: omnigent.policies.builtins.google.gcalendar_policy
    factory_params:
      allow_read: true
      allow_create_events: false
      allow_modify_events: false

CEL

Module: omnigent.policies.builtins.cel

cel_policy

Kind: factory — requires factory_params. Evaluates an inline CEL (Common Expression Language) expression as a policy. CEL is non-Turing-complete, side-effect-free, and guaranteed to terminate — no sandbox escapes, no infinite loops. The expression receives the full PolicyEvent dict as an event variable and must return a map with a result key ("DENY", "ASK", or "ALLOW") and an optional "reason" key. Non-map returns abstain. Available event fields:

Field	Description
`event.type`	Phase: `request`, `tool_call`, `tool_result`, `response`, `llm_request`, `llm_response`, `output_logged`
`event.target`	Tool name on `tool_call`/`tool_result`, `null` otherwise
`event.data`	Phase-specific: string for request/response, `{"name": str, "arguments": map}` for tool_call
`event.context.actor.run_as`	The session user’s email
`event.context.usage.total_cost_usd`	Cumulative session spend in USD

Parameter	Type	Default	Description
`expression`	string	(required)	CEL expression evaluated per policy event.
`reason`	string	`"Denied by policy."`	Fallback reason for DENY/ASK when the map omits a `reason` key.

policies:
  block_shell:
    type: function
    handler: omnigent.policies.builtins.cel.cel_policy
    factory_params:
      expression: >
        event.type == "tool_call" && event.data.name == "sys_os_shell"
          ? {"result": "DENY", "reason": "Shell access is blocked."}
          : {"result": "ALLOW"}
      reason: Shell access is blocked.

Routing

Module: omnigent.policies.builtins.routing

deny_trivial_to_expensive_model

Kind: factory — requires factory_params. Classifies user messages as TRIVIAL or COMPLEX using the server-level LLM client with structured output. Denies trivial tasks from using expensive models, redirecting them to cheaper alternatives.

This policy requires the server to have an llm: config block. It abstains when no client is available.

Classification results are cached in session_state by message hash, so only one classifier call is made per user message even across multiple LLM round-trips in a turn.

Parameter	Type	Default	Description
`expensive_models`	list of strings	(required)	Model IDs to gate, e.g. `["databricks-claude-opus-4-6"]`.
`classification_prompt`	string	(builtin default)	System instructions for the classifier LLM call. The output format is enforced via structured output, not this prompt.

# server_config.yaml
llm:
  model: databricks-gpt-5-4-mini

policies:
  deny_trivial_opus:
    type: function
    handler: omnigent.policies.builtins.routing.deny_trivial_to_expensive_model
    factory_params:
      expensive_models:
        - databricks-claude-opus-4-6

Working directory

Module: omnigent.policies.builtins.working_dir

block_working_dir_changes

Kind: factory — requires factory_params. Gates shell commands that move the agent out of its current working directory or switch git worktrees. Parses commands robustly: chained commands (cd /x && …), env prefixes, and shell-interpreter wrappers (bash -c "cd /x") are all unwrapped and re-parsed so the gate cannot be bypassed. By default gates both sys_os_shell (Omnigent built-in) and Bash (Claude/Codex native tool). Gated commands include:

cd, chdir, pushd, popd and git -C <path> (when block_cd is true)
git worktree add, git worktree move, git worktree remove (when block_worktree is true)

Read-only worktree subcommands (list, prune, lock, unlock, repair) are never gated.

Parameter	Type	Default	Description
`block_cd`	boolean	`true`	Gate `cd`/`chdir`/`pushd`/`popd` and `git -C`.
`block_worktree`	boolean	`true`	Gate `git worktree add/move/remove`.
`allowed_dirs`	list of strings	`[]`	Directories a `cd`/`git -C` may move into (including subdirectories). Empty means no directory change is allowed.
`action`	string	`deny`	What a gated command yields: `deny` (block) or `ask` (park for human approval).
`shell_tools`	list of strings	`["sys_os_shell", "Bash"]`	Shell tools whose `command` arg is parsed.

policies:
  stay_in_workspace:
    type: function
    handler: omnigent.policies.builtins.working_dir.block_working_dir_changes
    factory_params:
      allowed_dirs: ["/workspace"]
      action: deny

Risk score

Module: omnigent.policies.builtins.risk_score

risk_score_policy

Kind: factory — requires factory_params. Accrues a per-session risk score from tool calls and sensitive data labels. Escalates guarded tools to ASK or DENY once the score exceeds a threshold. The running score persists across turns via session_state. Tool matching is MCP-agnostic: a configured tool name matches any raw name that ends with "__" + name, so "gmail_message_send" matches "mcp__google__gmail_message_send" and "google__gmail_message_send" without extra configuration.

Parameter	Type	Default	Description
`threshold`	integer	`50`	Score at/above which `guarded_tools` escalate.
`tool_points`	object	`null`	Tool name → points added on each call, e.g. `{"web_search": 10, "fetch": 5}`. `null` means no per-call scoring.
`sensitive_labels`	object	`null`	Data-classification label → points added when a `tool_result` carries that label (case-insensitive), e.g. `{"Highly Confidential": 30}`. `null` means no label-based scoring.
`guarded_tools`	list of strings	`null`	Tool names gated once the score reaches `threshold`. `null` means nothing is gated (pure scorer).
`escalate_action`	string	`ASK`	Verdict for guarded tools over the threshold: `ASK` (human approval) or `DENY` (hard block).
`initial_scores_by_actor`	object	`null`	`context.actor.run_as` email → starting score offset, e.g. `{"contractor@example.com": 40}`. `null` means no per-actor offset.
`state_key`	string	`risk_score`	`session_state` key holding the running score.
`label_keys`	list of strings	(builtin defaults)	Result-payload keys inspected for a classification label. `null` uses the defaults: `label_classification`, `classification`, `sensitivity`, `sensitivity_label`, `dlp_label`.
`reason`	string	`Elevated session risk.`	Human-readable prefix on ASK/DENY escalations.

policies:
  risk_gate:
    type: function
    handler: omnigent.policies.builtins.risk_score.risk_score_policy
    factory_params:
      threshold: 50
      tool_points:
        web_search: 10
        sys_os_shell: 20
      sensitive_labels:
        "Highly Confidential": 30
      guarded_tools:
        - sys_os_shell
        - gmail_message_send
      escalate_action: ASK

Get Started

Core Concepts

Guides

Deployment

Reference

Builtin Policy Reference: All Omnigent Policy Handlers

Safety

max_tool_calls_per_session

ask_on_os_tools

ask_on_add_policy

block_skills

enforce_sandbox

deny_pii_in_llm_request

Cost

cost_budget

user_daily_cost_budget

GitHub

github_policy

Google Workspace

gdrive_policy

gmail_policy

gcalendar_policy

CEL

cel_policy

Routing

deny_trivial_to_expensive_model

Working directory

block_working_dir_changes

Risk score

risk_score_policy

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

Reference

Documentation Index

​Safety

​max_tool_calls_per_session

​ask_on_os_tools

​ask_on_add_policy

​block_skills

​enforce_sandbox

​deny_pii_in_llm_request

​Cost

​cost_budget

​user_daily_cost_budget

​GitHub

​github_policy

​Google Workspace

​gdrive_policy

​gmail_policy

​gcalendar_policy

​CEL

​cel_policy

​Routing

​deny_trivial_to_expensive_model

​Working directory

​block_working_dir_changes

​Risk score

​risk_score_policy

Build docs developers (and LLMs) love

Safety

max_tool_calls_per_session

ask_on_os_tools

ask_on_add_policy

block_skills

enforce_sandbox

deny_pii_in_llm_request

Cost

cost_budget

user_daily_cost_budget

GitHub

github_policy

Google Workspace

gdrive_policy

gmail_policy

gcalendar_policy

CEL

cel_policy

Routing

deny_trivial_to_expensive_model

Working directory

block_working_dir_changes

Risk score

risk_score_policy