---
title: Approvals
description: The human-in-the-loop approval queue — how an agent asks permission, where the request surfaces, how a decision is delivered, and what if nobody answers.
keywords: agent approval queue, human in the loop AI agent, agent permission requests, phone approvals
eyebrow: Dashboard
---

# Approvals

What is waiting on you.

Some agent actions should not happen without a human saying yes. Approvals is
where those requests queue up, and — when the cloud is connected — where they
get routed to your phone.

## How a request happens

Two paths produce an approval:

1. **The runtime asks.** Runtimes with a permission model — a pre-tool hook, a
   sandbox policy, a question tool — raise a request when they hit a gated
   action. ClawMetry surfaces it.
2. **A ClawMetry gate holds it.** Where a runtime exposes a pre-tool hook,
   ClawMetry can hold an action before the tool runs and require a decision.
   See [Approvals and pre-tool gates](/docs/guard/approvals/).

## The queue

Each row shows what is being asked for, by which agent, in which session, and
what the agent said it was trying to do. You approve or reject; the decision is
delivered back to the waiting agent.

```bash
curl -s localhost:8900/api/hitl/pending | jq
curl -s localhost:8900/api/hitl/status/<session_id> | jq
```

## Deciding

```bash
curl -s localhost:8900/api/hitl/decide -X POST \
  -H 'content-type: application/json' \
  -d '{"request_id": "…", "decision": "approve"}'
```

In the UI it is a button. The API exists because approvals are exactly the kind
of thing people want to wire into an existing on-call flow.

## Phone approvals

With cloud sync connected, a pending approval can reach your phone as a push
notification and be decided from the lock screen. The decision travels back
through the same queue.

The relay is a long poll rather than a fixed-interval push, so a decision made
on a phone reaches the waiting agent in seconds rather than at the next cycle.

## Fail-closed runtimes

Not every runtime's hook can be relied on to fail safely. Where a hook is
**fail-closed** — the action does not proceed if the gate cannot answer — the
gate is a real control. Where it is not, ClawMetry says so rather than implying
a guarantee it cannot make. The per-runtime position is in
[Approvals and pre-tool gates](/docs/guard/approvals/).

## When nobody answers

An unanswered request stays pending. It does not time out into an approval —
that would defeat the point — and the badge count on the navigation keeps
showing it.

If your agents are blocking on approvals nobody sees, that is an argument for
connecting the cloud (so requests reach a phone) or for narrowing what is gated,
rather than for auto-approving.

## Tier

The approval queue is a Starter-and-above feature (`approval_queue`). The
underlying pre-tool gates and tool-permission surface are separate — see
[Tool permissions](/docs/guard/tool-policy/).