> For the complete documentation index, see [llms.txt](https://chaincontext.gitbook.io/help-center/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chaincontext.gitbook.io/help-center/safety/hitl-approvals.md).

# Human-in-the-Loop Approvals

Mark any write tool as `requiresApproval` and pause execution until a human approves. The calling agent receives a task ID and polls for the decision. Approvers see the decoded tx + Tenderly simulation + Blockaid risk score when deciding.

## Enabling approval for a tool

In the tool editor, open the **Security** panel and toggle **Require human approval**. Deploy.

## Approver routing

| Project mode | Who approves?           | How they're notified                                 |
| ------------ | ----------------------- | ---------------------------------------------------- |
| **Private**  | You (the operator)      | Your configured dashboard, email, webhook            |
| **Public**   | The connecting end-user | Their `approverContact` declared at MCP `initialize` |

### Private projects

Configure email recipients + webhook URL on the project settings page. Approvals land in your **Approvals** queue and are fanned out simultaneously.

### Public projects

The end-user's MCP client must declare an approver contact in the `initialize` params:

```jsonc
{
  "clientInfo": { "name": "claude-desktop" },
  "approverContact": {
    "email":      "me@example.com",
    "webhookUrl": "https://example.com/approve"
  }
}
```

If `approverContact` is missing and the client calls a `requiresApproval` tool, the call is rejected with a clear error.

## Approval lifecycle

```
agent calls tool
  → task created in pending_approval state
  → hitl_approvals row written
  → notifications dispatched (email/webhook/dashboard)
  → agent polls tasks/get every 30s
  → human approves OR rejects (or 24h timeout → expired)
  → approved → tool executes → task.status=completed
  → rejected → task.status=failed (with decisionNote)
```

## Plan limits

| Plan           | Feature       | Max pending per project |
| -------------- | ------------- | ----------------------- |
| Studio         | Enabled       | 100                     |
| Enterprise     | Enabled       | Unlimited               |
| Free / Builder | Not available | —                       |

## Approval queue UI

The Approvals page shows every pending and decided approval with:

* Tool name + parameters
* Decoded calldata (Tenderly simulation output)
* Blockaid risk score (0-100) + flagged warnings
* Requester (end-user or agent ID)
* Approve + Reject buttons with optional note