Policies

Policies are rules that determine how permission requests are handled. They can auto-approve safe operations, require human approval for risky ones, or outright deny certain requests.

Policy Structure

Each policy consists of:

Name - A descriptive name for the policy
Conditions - Rules that must match for the policy to apply
Action - What to do when the policy matches
Priority - Order in which policies are evaluated
Scope Template - Default constraints to apply to matching requests

name: "Auto-approve internal emails"
conditions:
  action:
    equals: "email.send"
  context.recipient:
    matches: ".*@mycompany\.com$"
action: auto_approve
priority: 100
scope_template:
  max_emails: 5
  ttl: 600

Policy Actions

auto_approve

The request is approved immediately without human intervention. A token is issued and returned to the agent.

require_approval

The request requires human approval. Notifications are sent via configured channels (Telegram, email, webhook). The agent waits until approved or timeout.

deny

The request is rejected immediately. No token is issued. Use this for operations that should never be allowed.

Condition Operators

Conditions support various operators for matching against request fields:

Operator	Description	Example
equals	Exact match	action: {equals: "email.send"}
not_equals	Not equal to	status: {not_equals: "blocked"}
starts_with	String prefix match	action: {starts_with: "bank."}
ends_with	String suffix match	resource: {ends_with: ".pdf"}
matches	Regex pattern match	email: {matches: ".*@company\\.com$"}
less_than	Numeric comparison	amount: {less_than: 1000}
greater_than	Numeric comparison	priority: {greater_than: 5}
in	Value in list	type: {in: ["read", "list"]}
not_in	Value not in list	action: {not_in: ["delete"]}

Field Paths

Conditions can match against any field in the permission request using dot notation:

# Match the action field
action:
  equals: "email.send"

# Match the resource field
resource:
  starts_with: "file:/home/user/documents"

# Match fields within scope
scope.max_amount:
  less_than: 1000

# Match fields within context
context.reason:
  matches: ".*invoice.*"

# Match nested fields
context.metadata.priority:
  greater_than: 5

Policy Evaluation Order

Policies are evaluated in order of priority (highest first). The first matching policy determines the action. If no policy matches, the default action is deny.

Evaluation Example

Priority 100Financial operations → require_approval⏸ Skip (no match)

Priority 50Internal emails → auto_approve✓ Match!

Priority 10External emails → require_approval— Not evaluated

Priority -1000Default deny— Not evaluated

Example Policies

Auto-approve file reads

name: "Auto-approve small file reads"
conditions:
  action:
    equals: "file.read"
  scope.max_size:
    less_than: 1048576  # 1MB
action: auto_approve
priority: 50
scope_template:
  allowed_extensions: [".txt", ".md", ".json", ".csv"]

Require approval for financial operations

name: "Financial operations need approval"
conditions:
  action:
    starts_with: "bank."
action: require_approval
priority: 100

Auto-approve low-value transfers

name: "Auto-approve small transfers"
conditions:
  action:
    equals: "bank.transfer"
  scope.amount:
    less_than: 100
  scope.currency:
    in: ["USD", "EUR"]
action: auto_approve
priority: 110  # Higher than general financial rule

Deny dangerous operations

name: "Block dangerous commands"
conditions:
  action:
    equals: "shell.execute"
  scope.command:
    matches: ".*(rm -rf|drop table|truncate).*"
action: deny
priority: 1000  # Highest priority

Best Practices

Start restrictive - Begin with require_approval or deny as defaults, then add auto_approve rules for specific safe operations
Use high priority for denies - Security-critical deny rules should have the highest priority
Be specific - Narrow conditions reduce the chance of unintended auto-approvals
Document policies - Use descriptive names and add comments explaining the rationale
Test thoroughly - Test policies with sample requests before deploying to production