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

Always-on approval guards

Two safety guards are appended to every session's policy set automatically. You don't declare them, they take no parameters, and they can't be removed — they are present even when no policies are configured at any level, and sub-agent sessions get them too. They run after any session, agent, and server-wide policies you have declared.

Declining either prompt denies that tool call; accepting allows it to proceed.

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.

Keys that begin with _policy_ are reserved for the runtime, and a CEL expression can't change them. If a state_updates entry targets a reserved key, the event is denied and none of that result's state updates are applied. See StateUpdateEntry for the full list of reserved keys.

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.

Per-user monthly (or weekly, quarterly, yearly) budget

A daily cap doesn't catch a user who stays just under it every day. user_period_cost_budget applies the same gating as user_daily_cost_budget over a longer window: it sums the owner's spend across all of their sessions for the current UTC period and gates on the total.

# config.yaml
policies:
  monthly_budget:
    type: function
    function:
      path: omnigent.policies.builtins.cost.user_period_cost_budget
      arguments:
        period: month # day | week | month | quarter | year
        ask_thresholds_usd: [250.0, 400.0]
        max_cost_usd: 500.0
        # Omit (or pass []) for a true hard stop that blocks every model at
        # the limit; name tiers for a downgrade gate that only blocks those.
        expensive_models: [opus]

How the period is computed (all in UTC):

Behavior matches the daily policy:

• Soft checkpoints (ask_thresholds_usd) ASK the first time the period's spend crosses each value. An approval is recorded per user, so the same checkpoint won't re-prompt that user again this period — including from a different session. A decline blocks just that turn or tool call.
• Hard limit (max_cost_usd) DENYs the turn (request phase) or each tool call once the period's spend reaches it. With expensive_models set, only the named tiers are blocked so the user can /model down to a cheaper one; without it, every model is blocked.
• The policy abstains when the period's spend is 0.0 or the session has no owner (single-user mode), so it never trips on missing data.

ask_thresholds_usd values must each be greater than 0 and less than max_cost_usd, and max_cost_usd must be greater than 0.

Configure one user_period_cost_budget policy per policy set. Don't combine it with user_daily_cost_budget; to cap daily spend, use period: day. Stacking several period policies (for example weekly + monthly) isn't supported.

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