Approvals
The human-in-the-loop queue: suspend a tool call, resolve it, then let the retry through.
Approvals add a human-in-the-loop step in front of a tool call. A guardrail policy returns a
requireApproval decision instead of allow/deny; the call is suspended, an approver resolves it,
and the outcome decides whether the call proceeds. For the wider policy pipeline see
Custom tools, guardrails & audit replay.
Flow
-
A guardrail policy's
decide()returns:{ allow: false, requireApproval: true, approvalKey: 'approve-big-order' } -
The call is suspended; the caller gets
isErrorwithmcp.approval.pendingand theapprovalKey. The pending entry is stored in the approval queue. -
An admin approves or rejects it (REST or MCP below). Resolution is recorded against the approver.
-
On the next call with the same
approvalKey, the policy can read the queue throughctx.approvalsand allow it.
The queue carries request arguments, so every endpoint is gated to the admin roles — REST uses
adapters.rest.adminRoles, MCP uses adapters.mcp.adminRoles (both default to none). Reading it is a
write-authority boundary, not a read anyone gets.
The queue
A PendingApproval is:
{ approvalKey, action, args, status, createdAt, actorKey, approvedBy? }with status ∈ pending / approved / rejected. The approvalKey is a deterministic hash of
actor + action + args, so repeated calls don't create duplicate pending entries.
Backends implement ApprovalsBackend:
- In-memory (
core/tools) — the default and the test double. - PostgreSQL (
subsystems/approvals) — the persisted store; enable it in config to survive restarts. The store never audits; the queue facade does.
Tool handlers reach it through ctx.approvals (list, count, query, approve, reject).
REST
GET {prefix}/approvals paged list
POST {prefix}/approvals/:key/approve resolve → approved (admin)
POST {prefix}/approvals/:key/reject resolve → rejected (admin)GET supports status, action, actorKey, from, to (createdAt window), limit, offset and
sort/order (default createdAt DESC). It returns { rows, total, limit, offset }. Approve/reject
return { approvalKey, status, approver } and answer approval.notFound when the key is unknown or
already resolved.
MCP
When the queue is wired and the session identity holds an adapters.mcp.adminRoles role, the surface
also exposes list_approvals, approve_approval and reject_approval (subject to the same admin
gate and audited like any tool call). See the MCP tool surface.
Enable
The routes are registered when the tool executor is enabled (tools.toolsDir is set). The queue
defaults to the PostgreSQL backend (subsystems/approvals, the engine's mandated DB); opt out with
an in-process queue:
export default {
tools: {
toolsDir: 'tools',
approvals: { backend: 'memory' }, // default is the persisted PG backend
},
};When the executor is off, the approval routes are absent — no import, zero overhead.
Related
- Custom tools, guardrails & audit replay — where
requireApprovalcomes from - Guardrail policies — decisions and the approval flow
- Workflow → Admin & guardrails — node
requiresApproval - Audit — how resolutions are recorded