Builtin Policies

Omnigent ships with policies for common guardrails, organized into two categories: Safety and Cost Control. Your Omnigent can apply any of these by name when you ask it to add a policy, or you can reference them in YAML by their full path in the handler field.

All builtin policies live under omnigent.policies.builtins.

Safety

Orchestration

Safety guardrails for supervisor agents that dispatch sub-agents (like Polly) — they keep fan-out bounded, writes contained, and dangerous shell commands in check. They live under omnigent.policies.builtins.orchestration.

Confine confidential Google Drive data (gdrive_policy)

gdrive_policy can layer Bell-LaPadula's classic "no write-down" rule on top of its access controls. You declare a set of confidential documents up front with confidential_files (file IDs or Google URLs). The rule engages only once the session reads one of those files: from then on, its writes are confined to the confidential set. A write to — or creation of — any other file would move confidential data into a less-protected place, so it is blocked.

# Omnigent config (policies block)
policies:
  confidential_containment:
    type: function
    handler: omnigent.policies.builtins.google.gdrive_policy
    factory_params:
      # The confidential compartment: file IDs or Google URLs.
      confidential_files:
        - "1ConfidentialStrategyDocID"
      # Allow creating new files, so a create can be shown being gated as a
      # write-down rather than blocked outright by the base access rules.
      allow_create: true
      # DENY (hard block) or ASK (require human approval) on a write-down.
      write_down_action: DENY

Key behaviors:

• Off by default. With no confidential_files, the base access policy is unchanged.
• Read-triggered. Containment engages only after the session reads a confidential file by id. The rule does not restrict reads.
• Not a write grant. Listing a file in confidential_files does not make it writable — writing to a confidential file still requires it to be created this session or listed in write_files.
• write_down_action. "DENY" (default) hard-blocks a write-down; "ASK" routes it to human approval. It is ignored when confidential_files is empty.

Because the confidential set is declared explicitly rather than inferred from a per-document classification label, the rule works on any Google Drive tenant.

Cost Control

Usage examples

Common scenarios: warn an engineer before a session gets expensive, cap daily spend per user across all sessions, or block expensive models once a session hits a hard limit while still letting work continue on a cheaper one.

Make spend visible before you restrict it

Start with soft thresholds only. Engineers see when they're running an expensive session and can decide whether the task warrants it. No one gets blocked; habits change on their own.

# Omnigent config (policies block)
policies:
  session_visibility:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      ask_thresholds_usd: [1.0, 5.0]
      max_cost_usd: 999.0 # effectively no hard cap
  daily_visibility:
    type: function
    handler: omnigent.policies.builtins.cost.user_daily_cost_budget
    factory_params:
      ask_thresholds_usd: [10.0, 25.0]
      max_cost_usd: 999.0

This gives you real data on where spend is concentrated before you decide where to add guardrails.

Server-wide team policy

A reasonable starting point for a team deployment: per-user daily visibility at $25, a soft check at $50. Engineers can still use any model for any task — they just get asked before spending more than $25 in a day.

# config.yaml
policies:
  daily_budget:
    type: function
    function:
      path: omnigent.policies.builtins.cost.user_daily_cost_budget
      arguments:
        ask_thresholds_usd: [25.0, 50.0]
        max_cost_usd: 100.0

omnigent server -c config.yaml

The daily cap exists to surface sessions that are genuinely off the rails, not to penalize productive use.

detect_task_switch

Use this policy to keep sessions focused and avoid wasting tokens on stale context. On each user request, it classifies whether the latest message continues the current task or starts a new one, and returns the configured action when it detects a task switch. It requires a server llm: config and fails open if no LLM client is available.

# Omnigent config (policies block)
policies:
  keep_context_lean:
    type: function
    handler: omnigent.policies.builtins.context.detect_task_switch
    factory_params:
      min_turns: 2
      history_window: 4
      action: ASK