Permissions & Approval

Two different questions, two different blocks. permissions says who may set an agent in motion. approval says which of its actions stop and wait for a person once it is running.

Who May Invoke

agents:
  - name: support-agent
    role: support
    systemPrompt: You are a courteous support assistant.
    permissions:
      type: agent
      trigger: [admin, member]

Property	Description
permissions.type	User-type discriminator. Always agent.
permissions.trigger	Who may invoke: all, authenticated, or a role array such as [admin, member].
permissions.emailDomain	Domain for the synthetic agent address. Defaults to agents.sovrium.local.

trigger governs the invocation surfaces — the chat panel, the API, an automation. It does not govern what the agent may then do: that remains its role plus its tools allowlist. A viewer allowed to trigger an admin-role agent is triggering something more privileged than themselves, so read trigger as delegation and set it deliberately.

Human-in-the-Loop Approval

approval inserts a person between the model's decision and its effect.

Property	Description
approval.mode	none (execute immediately), all (everything waits), or selective.
approval.required	Actions needing approval — a subset of tools.actions. Required when mode: selective.
approval.timeout	Seconds before a pending approval expires. Defaults to 3600.
approval.escalation	{ after: <seconds>, to: <role> } — hand an unactioned request to another role.

approval:
  mode: selective
  required: [record.delete, email.send]
  timeout: 1800
  escalation:
    after: 600
    to: admin

Read that as a timeline. The agent decides to send an email; the request goes to a human. Ten minutes later, nobody has acted, so it escalates to admin. Twenty minutes after that the timeout hits and the request expires unexecuted.

Choosing a Mode

Mode	Right when
none	Every action the agent can take is reversible and low-stakes. A read-only analyst.
selective	Most work is routine but a few actions leave the building. The usual answer.
all	A new agent you do not yet trust, or one whose whole remit is consequential.

selective is the default choice in practice, and the discipline is to ask of each action: if the model gets this wrong, can I undo it? record.update on an audited table is recoverable. email.send is not — the message is gone. Neither is auth.banUser, from the banned user's point of view.

Running all for a fortnight after deploying a new agent is a cheap way to learn what it actually does before narrowing to selective. The approval queue doubles as a log of intentions.

Approval and Scheduling

Scheduled runs respect approval. An agent with mode: all on a nightly cron does not execute at 3 a.m. — it queues a request that sits until someone arrives, and expires if timeout passes first.

That combination is usually a mistake, and worth naming: an unattended trigger paired with an attended gate produces an agent that reliably does nothing overnight. Either narrow to selective so the routine part proceeds, or accept that the schedule only prepares work for the morning. See Scheduling & Limits.

Related Pages

• Agents Overview — the agent these blocks configure.
• Tools — the actions approval.required selects from.
• Scheduling & Limits — unattended runs.
• Roles & RBAC — the roles named in trigger and escalation.
• AI Chat — one of the surfaces trigger governs.