Skip to main content

​
Autonomy Levels

FERAL’s autonomy system controls how much freedom the agent has to act without human approval. Three modes — strict, hybrid, and loose — determine which tools auto-execute and which require explicit confirmation.

​
Strict Mode

Every tool call requires user approval. The agent proposes an action and waits. 
User: "What's the weather in NYC?"
Agent: I'd like to call the weather API for NYC. Approve? [✓ / ✗]
User: ✓
Agent: It's 72°F and sunny in New York.
Best for: first-time setup, untrusted environments, auditing all agent behavior. 
# ~/.feral/config.yaml
autonomy: strict

​
Hybrid Mode

Safe actions (passive + active permission tiers) execute automatically. Risky actions (privileged + dangerous) require approval. 
User: "Search for flights to Tokyo and book the cheapest one."
Agent: [auto] Searching flights... found 3 options.
Agent: The cheapest is $450 on ANA. I need approval to book. Approve? [✓ / ✗]
This is the default mode. Most users stay here — the agent handles research and information retrieval instantly, but pauses before actions with real-world consequences. 
autonomy: hybrid

​
What Auto-Executes in Hybrid

ActionTierAuto?
Search the webpassiveYes
Read memorypassiveYes
Get weatherpassiveYes
Send a chat messageactiveYes
Create a fileactiveYes
Run a shell commandprivilegedNo — asks first
Send an emailprivilegedNo — asks first
Delete filesdangerousNo — asks first
Make a purchasedangerousNo — asks first

​
Loose Mode

Everything except dangerous-tier tools auto-executes. The agent runs on full autopilot for most tasks. 
User: "Clean up my Downloads folder — delete anything older than 30 days."
Agent: [auto] Listing files... found 47 files older than 30 days.
Agent: [auto] Moving 47 files to trash... done.
dangerous tools still require approval even in loose mode. See Security Model for the hard-coded deny list.
autonomy: loose

​
Configuration

​
Environment Variable

export FERAL_AUTONOMY=hybrid   # strict | hybrid | loose
The env var takes precedence over the config file, useful for per-session overrides: 
FERAL_AUTONOMY=strict feral start

​
Config File

# ~/.feral/config.yaml
autonomy: hybrid

​
Per-Session Override

Clients can request an autonomy level during session initialization: 
from feral_sdk import FeralClient

async with FeralClient("http://localhost:9090") as client:
    session = await client.create_session(autonomy="strict")
The server enforces that a session cannot escalate beyond the server-level setting. If the server is hybrid, a session can request strict (more restrictive) but not loose (less restrictive).

​
ApprovalManager

The ApprovalManager handles approval requests and maintains a list of standing approvals — pre-authorized tool+argument patterns that skip the approval prompt. 
from feral_core.security import ApprovalManager

manager = ApprovalManager()

manager.grant_standing(
    tool="shell_exec",
    pattern={"command": "ls *"},     # glob match on args
    expires_in=3600,                  # seconds; None = permanent
)

approved = manager.check("shell_exec", {"command": "ls -la ~/Documents"})
# approved == True (matches "ls *" pattern)

​
Standing Approvals via CLI

# Grant: allow "git status" without asking
feral approve "shell_exec" --pattern '{"command": "git *"}' --expires 1h

# List active standing approvals
feral approve list

# Revoke all standing approvals
feral approve revoke --all

​
Standing Approvals via API

# Grant
curl -X POST http://localhost:9090/api/approvals \
  -H "Content-Type: application/json" \
  -d '{"tool": "shell_exec", "pattern": {"command": "git *"}, "expires_in": 3600}'

# List
curl http://localhost:9090/api/approvals

​
Approval Flow

When a tool call needs approval, the following sequence occurs:
  1. enforce_safety() determines the call requires approval.
  2. The Brain sends an approval_request message to the active channel.
  3. The user responds with approve or deny.
  4. If approved, the tool executes and the result flows back normally.
  5. If denied, the agent receives a “tool denied” signal and re-plans.
{
  "type": "approval_request",
  "payload": {
    "request_id": "apr_abc123",
    "tool": "shell_exec",
    "args": {"command": "rm -rf /tmp/old-cache"},
    "permission_tier": "privileged",
    "reason": "Shell command execution requires approval in hybrid mode"
  }
}

​
Escalation Rules

Server SettingSession RequestEffective Level
strictstrictstrict
stricthybridstrict (capped)
hybridstrictstrict
hybridhybridhybrid
hybridloosehybrid (capped)
looseanyas requested