Approval Gates

Approval gates put a human in the loop for high-risk agent actions. When an agent calls a tool that matches an approval policy, execution blocks until a human approves or denies the action.

Approval policies

An ApprovalPolicy defines which tool calls require approval. Policies match on tool name patterns:

• Exact match: send_email — matches only that tool.
• Glob match: send_* — matches any tool starting with send_.
• Wildcard: * — matches all tool calls (useful for high-security agents).

Policies are configured per agent in runtime.toml.

How blocking works

When an agent hits an approval gate:

1. The agent’s thread blocks on a condvar (condition variable) in the ApprovalStore.
2. The pending approval appears in the dashboard and API.
3. A human approves or denies via the dashboard UI or API.
4. The condvar is signaled and the agent resumes (or receives a denial error).

Timeout: if no decision is made within the configured timeout (default 5 minutes), the request is automatically denied. This prevents agents from blocking indefinitely.

Risk scoring

Each pending approval includes a computed risk score (0.0 to 1.0) to help humans prioritize:

• Tool classification: tools are categorized as financial, communications, system, or data operations. Each category has a base risk weight.
• Argument heuristics: the scorer inspects arguments for high-risk patterns (large amounts, sensitive domains, destructive operations).
• Composite score: the final score combines tool classification and argument heuristics.

The risk score is informational — it helps humans triage but does not auto-approve or auto-deny.

Batched approvals

When multiple agents have pending approvals, the dashboard groups them by category. You can approve or deny an entire batch at once instead of handling each request individually.

API endpoints