Approval Flow

When a tool call requires approval (T2-T3 by default), the ApprovalBroker manages the request lifecycle across all channels.

How It Works

1. SecurityGate determines: NeedsApproval
2. ApprovalRequest created with:
   - Unique ID
   - Tool name + input summary
   - Effective tier
   - Session ID
3. Request published to EventBus
4. Channel adapter renders approval UI
5. User approves or denies
6. Result sent back via oneshot channel
7. SecurityGate proceeds or returns error

Approval UX by Channel

REPL (Terminal)

⚠ Approval required for bash (tier: T3)
  Command: git push origin main
  [approve / deny]
> approve
✓ Approved. Executing...

TUI (ratatui)

A modal dialog appears with the tool name, tier, and input. Press y to approve, n to deny.

Ryvos sends a message with inline buttons:

⚠ Approval Required
Tool: bash (T3)
Command: git push origin main

[✓ Approve]  [✕ Deny]

Tap the button to respond.

Discord

An embed with action buttons:

⚠ Approval Required
Tool: bash
Tier: T3
Input: git push origin main

[Approve] [Deny]

Slack

A Blocks UI message with button actions, rendered in the thread where the conversation is happening.

Web UI

A modal overlay in the browser with approve/deny buttons and full input details.

Timeout

If no response is received within approval_timeout_secs (default: 60), the request is automatically denied. This prevents the agent from stalling indefinitely.

[security]
approval_timeout_secs = 60

Slash Commands

In channel adapters (Telegram, Discord, Slack), you can also use text commands:

/approve <request-id>
/deny <request-id>

Approval Events

The EventBus publishes events for all approval activity:

ApprovalRequested — new request created
ApprovalResolved — request approved or denied

These events are available to hooks and can be used for audit logging.

Configuration

[security]
auto_approve_up_to = "t1"      # T0-T1 skip approval entirely
approval_timeout_secs = 60     # Timeout = deny
 
# Auto-approve everything except T4 (not recommended):
# auto_approve_up_to = "t3"