Approval Gates

Sophon pauses and asks for approval whenever an agent wants to do something risky. This guide covers what you see, how to respond, and how to tune the behavior. For the deeper reference — risk levels, timeouts, audit trail — see Approval Gates & Risk Levels.

What you see

When an agent proposes a High or Critical action, a card appears in Dashboard → Approvals (and, if you have mobile enabled, a push notification). The card shows:

• Tool — what the agent is about to call
• Risk — Medium / High / Critical, color-coded
• Parameters — the exact inputs the agent chose
• Preview — if available (e.g., the draft email body)
• Countdown — time remaining before auto-timeout (default: 5 minutes)

You can:

• Approve — run with the original parameters
• Edit — tweak parameters before approving (only if the tool allows editing)
• Reject — skip this call, the agent will decide what to do next

Approving from where you are

You don't have to be at the Dashboard.

• Mobile push — if you have Sophon Mobile installed and approvalRequests notifications enabled, the request arrives as a push notification with Approve / Reject action buttons. Tap to respond without opening the app. (Respects quiet hours — see below.)
• Channel of origin — if the agent was invoked from Telegram, WhatsApp, Slack, etc., the approval request is posted back to that same channel. You reply approve, reject, or edit there.
• CLI — sophon approvals list shows pending requests; sophon approvals approve <id> / sophon approvals reject <id> works from a terminal.

Info requests

A related pattern: the agent needs information, not a yes/no. You'll see a question with optional predefined choices — pick one, type a free-form answer, or cancel. These don't gate tool execution the same way approvals do; they just block the agent on your answer.

Quiet hours

Between hours you configure (e.g., 22:00–07:00):

• Critical requests are auto-rejected — the agent won't bother you, and any tool that needed approval just errors.
• High requests are queued until quiet hours end — you'll see them in the morning, newest-first.
• Medium (plan-triggered) requests also queue.

Configure in Settings → Notifications → Quiet hours, or edit ~/.sophon/config/approvals.json:

{
  "quietHours": { "start": "22:00", "end": "07:00", "timezone": "Europe/Tirana" }
}

Trust lists

If a tool is safe for this specific agent, you can exempt it from approval:

• Per-agent trusted tools — e.g., Ada (your research agent) can call web.search freely even though it's ordinarily Low-risk.
• Trusted skills — the whole skill is exempted from approval. Useful for internal / company-signed skills you've already vetted.

{
  "perAgentOverrides": {
    "research": { "trustedTools": ["browser.navigate", "web.search", "web.scrape"] }
  },
  "trustedSkills": ["acme-internal"]
}

Trust lists are additive — they only lower the default risk; they can't raise it above Critical.

Timeout behavior

• Default timeout: 5 minutes.
• Timeout = reject. The agent sees the tool call fail with "approval timed out" and decides what to do next (usually asks you directly or tries another approach).
• Per-request override — workflows can set longer timeouts (up to 24 hours) for approvals that need human deliberation.

Plan approvals

If a multi-step plan has any Medium+ step, the whole plan is gated before any step runs. You see the full DAG — every step, its risk, its dependencies — and approve once. Plan approvals have a longer default timeout (10 minutes) since you have more to read.

Editing a plan opens it in the Workflow Builder with every step pre-populated, so you can modify parameters, reorder, or remove steps before approving.

Audit trail

Every approval decision is logged — who, when, which tool, which parameters, what outcome. View at Admin → Audit. Filterable by user, tool, date, and outcome. Required for compliance in Enterprise.

Where to go next

• Approval Gates & Risk Levels — the full reference with risk definitions
• Notifications — push categories and quiet-hours behavior
• Planning — how plan-level approvals work