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

Cost Control

Usage examples

Confine confidential Google Drive data

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

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

Catch a stuck agent

detect_thrashing watches tool_result events and flags an agent that is failing repeatedly — retrying the same broken command, looping on a permission error, or otherwise making no progress. Unlike detect_task_switch, it needs no server LLM: error detection is heuristic (common error prefixes like Error:, Traceback (most recent call last), Permission denied, and JSON payloads carrying an "error" key).

It keeps a rolling window of recent tool-result outcomes (error or success) in session state and fires when either condition is met:

• the last consecutive_threshold results are all errors, or
• the error rate within the last window results reaches or exceeds window_error_rate.

On detection it returns the configured action with a message telling the user the agent appears stuck. The window is not reset on firing — a thrashing agent tends to keep failing, so the policy keeps firing until the user intervenes or the agent recovers naturally (successful results push old errors out of the window).

# Omnigent config (policies block)
policies:
  catch_stuck_agent:
    type: function
    handler: omnigent.policies.builtins.context.detect_thrashing
    factory_params:
      consecutive_threshold: 5 # fire after 5 errors in a row (0 disables)
      window: 10 # rolling window for the rate check
      window_error_rate: 0.8 # fire at ≥80% errors in the window (0 disables)
      action: ASK # ASK escalates to the user; DENY blocks the next result

Both checks are independent — set consecutive_threshold: 0 to rely purely on the window error rate, or window_error_rate: 0 to rely purely on the consecutive-error run.

Track custom state from a CEL expression

cel_policy evaluates a CEL (Common Expression Language) expression against every policy event. The expression must return a map with a result key ("DENY", "ASK", or "ALLOW") and may add an optional reason. A non-map return (or a map without a valid result) abstains, passing to the next policy. Because CEL is non-Turing-complete and side-effect-free, the expression itself can't mutate anything.

To let a CEL policy accumulate its own session state across turns, the returned map may also include a state_updates key. It must be a list of maps, each shaped:

{ "key": string, "action": "set" | "increment" | "delete" | "append", "value": any }

The action values behave as follows, and value is required for set, increment, and append and ignored for delete:

For example, this policy allows every tool call while counting them and recording the last tool name in session state:

# Omnigent config (policies block)
policies:
  count_tool_calls:
    type: function
    handler: omnigent.policies.builtins.cel.cel_policy
    factory_params:
      expression: |
        event.type == "tool_call"
          ? {
              "result": "ALLOW",
              "state_updates": [
                {"key": "call_count", "action": "increment", "value": 1},
                {"key": "last_tool", "action": "set", "value": event.data.name}
              ]
            }
          : {"result": "ALLOW"}

State written this way is shared session state, so a later policy (or a later evaluation of the same CEL expression) can read it back and branch on it, just like the stateful builtin policies do.

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.

Keep sessions focused

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