Configure human approvals

Human-in-the-loop approvals let you keep humans in control of actions that matter. This guide explains how to decide where approvals are needed and how to configure them so they feel natural to users.

When to require approval

Require approval for actions that are irreversible, sensitive, or high-impact:

Refunds, payments, or financial adjustments above a threshold.
Access grants, privilege escalation, or data exports.
Infrastructure changes or production deployments.
Any action regulated by policy or law.

For low-risk, reversible actions, approval gates add friction without improving safety.

Design the approval flow

A good approval flow answers three questions:

Who approves? — a manager, the data owner, the on-call engineer, or a security team.
How are they asked? — through the same channel the user is on, or via email, Slack, or a ticket.
What happens on timeout? — reject, escalate, or proceed with a default safe action.

Configure the gate

Classify the operation in the registry with the appropriate severity and tier grants. Approval gates only apply to operations the agent is already authorized to invoke under DefaultToolAuthzPolicy(default_deny=True).
Mark the operation as requiring approval with alquimia registry tools set-operation ... --requires-approval or the equivalent registry policy.
Define the approval message the approver will see. Include what is being requested, who requested it, and any relevant context.
Set the timeout and default action. Choose whether a missing response rejects the request, escalates it, or takes a predefined safe path.
Route the request back through the same channel when possible, so the approver does not need to open a separate application.
Test the full cycle — request, wait, approve, resume — and verify the decision is recorded in the worklog.

Approval and role tiers

Authorization is checked before the approval gate is offered:

A reader agent is denied a mutating-recoverable or destructive operation even if it requires approval.
A destructive operation can only ever be granted to operator roles.
An agent can narrow itself with tier_ceiling, but it cannot widen access beyond the registry policy.

If a tool call is denied before the approval prompt appears, see Tool denied.

Approval channels

Approvals work best when they arrive where the approver already works:

Channel	Best for
WhatsApp	Field managers, mobile-first approvers
Slack	Internal teams and on-call engineers
Email	Formal approvals with documentation
Ticket comment	Approvals tied to a ticket or case

Audit and accountability

Every approval request and response is recorded with:

The original task and session identifiers.
The identity of the requester.
The identity of the approver.
The timestamp and channel.
The decision and any accompanying message.

This record is part of the worklog and can be used for compliance, dispute resolution, and post-incident review.