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 an action at or above the approval threshold — Medium out of the box, and Critical always asks whatever the threshold is — 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 — the level the call was actually raised at, 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

One prompt, and it comes first

As of 2.0 a tool that needs approval asks once, before it runs. Earlier versions asked twice, and the second prompt arrived after the tool had already executed — approving or rejecting it changed nothing. A rejected call now comes back to the agent as an error result, so it can say what it could not do rather than carrying on as if nothing happened.

The one place you'll still see two cards is a shell command on a paired desktop: the general gate asks first, then the desktop tool asks again at Critical with the exact command as an editable preview. Redundant rather than unsafe, and on the list to collapse.

Every request ends in exactly one recorded outcome: Approved, Edited, Rejected, Cancelled or Timed out, written once. If two devices answer the same card, the first answer is the one that counts. A timeout or a cancel can never later turn into an approval.

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 your push quiet hours — see Notifications.)
• Channel of origin — if the conversation is running on Telegram, WhatsApp, Slack, etc., the approval request is posted back to that same chat. You answer there with approve <id> or reject <id>, using the id the prompt carries.
• By voice — on the Voice page, the Command Bridge, or Sophon Mobile's Voice tab, the prompt is read out and you answer out loud. A plain "yes" is enough at None, Low and Medium risk; High and Critical need you to say "yes, approve". See Approvals & Questions by Voice.
• CLI — sophon approvals pending lists what's waiting; sophon approvals decide <id> --approve / --reject answers from a terminal, and sophon approvals edit <id> opens the preview in $EDITOR and approves with edits. Inside the chat, /approvals lists the open gates, and in the full-screen chat an approval arrives as a card with a live countdown and one-key Approve, Reject and Skip (plus Edit where the tool allows it).

Answer in one place and the rest close on their own: deciding a request — or letting it time out, or having it cancelled — closes the open cards on the other surfaces and any voice prompt waiting on it.

Answering from a channel

Two things are worth knowing about the channel path, both new in 2.0.

An approve/reject reply is accepted only from the chat the request was actually delivered to. Someone in another group wired to the same bot cannot answer by guessing an id. The flip side is that the check is per chat, not per person: anyone in that chat can answer, and if the Gateway restarts while a request is still pending, the reply falls back to the channel's default chat. Per-sender binding is on the roadmap — do not treat the current scoping as one.

Requests raised outside a conversation turn have no channel to go to. An MCP tools/call, a workflow step, or a background job is answered on the Dashboard or mobile instead.

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).

Requests from a plan step or a sub-agent

New in 2.0. When a plan step or a sub-agent needs an approval or an answer, the card now surfaces in the conversation you're actually watching — Dashboard, Mobile, CLI and the channel the conversation came from — tagged with the step it came from, with a link into that step's own session. Previously a sub-agent could sit on a request nobody ever saw until it expired.

These waits are held in memory, not parked durably, so a Gateway restart while one is open fails that step attempt and the plan retries it. And nobody answering is still a decision: an unanswered approval is rejected, an unanswered question tells the step to proceed on its best judgment. Neither ever becomes an approval or a silently picked option.

Tuning what gets asked

Two host-wide settings, both at Settings → Security → Approvals, both live — a save applies to the next tool call, with no Gateway restart:

• Approval threshold — the level at or above which a call needs a human. Default Medium.
• Per-tool overrides — replace one tool's declared risk, up or down.

The order they're applied in matters:

1. A per-tool override replaces the tool's static risk.
2. A per-call assessed risk can only raise the result — a tool whose risk depends on its arguments (remote.control, say) classifies each call, and the higher of the two wins.
3. Critical always prompts, whatever the threshold and whatever the override. On a Critical tool an override does nothing at all.
4. Otherwise you're asked when the effective risk lands at or above the threshold.

{
  "Sophon": {
    "ApprovalPolicy": {
      "DefaultRiskThreshold": "Medium",
      "PerToolOverrides": { "email.send": "High", "code.execute": "High" }
    }
  }
}

To stop a single conversation asking about routine calls, turn on auto-approve for that session with a risk ceiling. Critical is never auto-approved whatever ceiling you pick, and auto-approvals are still recorded in the audit trail.

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 steps still raise their own tool-level approvals whenever a call reaches the threshold, and a Critical one always does.
• 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
• Approvals & Questions by Voice — what Sophon says, and what counts as an answer
• Notifications — push categories and quiet-hours behavior
• Planning — how plan-level approvals work