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. As of v1.15, this is a structured ask rather than a one-off question:

• One ask bundles 1–4 questions, each with a short header chip (max 12 characters) so you can see at a glance what's being asked.
• Each question offers 2–4 options, every option carrying a label and a one-line description so you know what you're picking.
• Questions can be multi-select where it makes sense ("which calendars should I watch?").
• Free text is always allowed — options are suggestions, never a cage. Type your own answer at any point.

Where you answer depends on where you are:

• Dashboard — the question card renders each question with its options. Click an option, or just type in the composer: while a question is active, your typed message answers it — the server routes it to the question, no special syntax needed.
• CLI — sequential pickers walk you through the questions one at a time.
• Mobile — the same card, options plus free text.
• External channels (WhatsApp, Telegram, Slack, …) — the agent texts you numbered options; reply with the number(s) or with free text, and the reply is parsed into an answer.

Timeouts are honest: an unanswered ask expires with an explicit TimedOut result to the agent — Sophon never silently assumes the first option.

Pending asks are also available over REST:

GET  /api/info-requests/pending
POST /api/info-requests/{id}/respond

These don't gate tool execution the same way approvals do; they just block the agent on your answer (or on the timeout).

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.
• Plan approvals 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 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

Whether a multi-step plan waits for you is governed by PlanApprovalMode:

• Interactive sessions gate plans by default (mode Always). You see the full DAG — every step, its risk, its dependencies — and approve once before anything runs. Plan approvals have a longer default timeout (10 minutes) since you have more to read.
• Unattended runs — heartbeat, cron, subagent, and webhook — auto-proceed past the plan gate, so a scheduled plan never stalls waiting for someone who isn't there. Individual High and Critical steps still raise their own tool-level approvals as usual.
• Per-session override — you can change the behavior for a single session without touching the default.
• Host default — set it at Settings → Security → Approvals (config key Sophon:AgentExecution:PlanApproval, live-reloaded — no restart needed).

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