[PER-14506] Add Human-in-the-Loop approvals documentation

docs/permit-mcp-gateway/advanced-features.mdx

@@ -69,7 +69,9 @@ Agent Interrogation is under active development as an Enterprise capability. The
 
 Require human approval for high-risk agent actions. When an agent requests a sensitive operation — such as deleting records, modifying production data, or accessing restricted resources — the gateway pauses execution and routes an approval request to a designated reviewer. Routine operations continue without interruption.
 
-This is useful for organizations that want to allow agents to attempt sensitive actions but require a human to confirm before execution proceeds.
+HITL includes per-tool, per-server, and per-trust-level approval policies, a real-time approval queue with batch actions, approval history, trusted agent bypass for automation, and email/Slack notifications.
+
+See the dedicated **[Human-in-the-Loop Approvals](/permit-mcp-gateway/human-in-the-loop)** guide for full documentation.
 
 ## Time-Limited Consent
 
@@ -120,7 +122,7 @@ Intent-based access control is an emerging capability. [Contact us](mailto:suppo
 | Feature | Status | Notes |
 | --- | --- | --- |
 | **Agent Interrogation** | Enterprise, active development | Agentic-native identity, fingerprinting, drift detection, and prompt injection defense |
-| **Human-in-the-Loop Approvals** | Enterprise | Available for enterprise plans |
+| **[Human-in-the-Loop Approvals](/permit-mcp-gateway/human-in-the-loop)** | Enterprise | Per-tool, per-server, and per-trust-level approval policies with email/Slack notifications |
 | **Time-Limited Consent** | Enterprise | Available for enterprise plans |
 | **Agent Verification** | Enterprise, early access | Behavioral profiling and drift detection, powered by Agent Interrogation |
 | **Session Monitoring** | Enterprise, early access | Anomaly detection capabilities under active development |

docs/permit-mcp-gateway/human-in-the-loop.mdx

@@ -0,0 +1,128 @@
+---
+title: Human-in-the-Loop Approvals
+sidebar_label: Human-in-the-Loop
+description: Require real-time human approval before high-risk agent tool calls are executed. Configure per-tool, per-server, and per-trust-level approval policies with email and Slack notifications.
+sidebar_position: 7.5
+---
+
+# Human-in-the-Loop Approvals
+
+Human-in-the-Loop (HITL) adds a **real-time approval gate** to your agent workflows. When an agent requests a sensitive operation — such as deleting records, modifying production data, or accessing restricted resources — the gateway pauses execution and routes an approval request to a designated admin. Routine operations continue without interruption.
+
+:::note Enterprise Plan
+Human-in-the-Loop approvals are available on **Enterprise** plans. [Schedule a demo](https://calendly.com/permit-io/demo) to get started.
+:::
+
+:::tip Quick start
+1. Go to **MCP Servers** → select a server → toggle **HITL** on a tool
+2. Trigger that tool from an MCP client (e.g., Cursor, Claude Desktop)
+3. Open **Approvals** in the Platform → approve or reject the request
+:::
+
+## How it works
+
+1. An agent calls a tool that requires approval (e.g., `delete_repo`)
+2. The gateway checks authorization via Permit.io (existing [trust-level](/permit-mcp-gateway/guide) check)
+3. If the tool is approval-gated, the gateway **pauses the request** and creates an approval request
+4. Admins are notified via the Platform UI, email, and/or Slack
+5. An admin reviews the request and **approves or rejects** it
+6. The gateway resumes the tool call (on approval) or returns an error (on rejection/timeout)
+
+The MCP client simply waits for the response — no client changes are needed. If no decision is made within the timeout (default: 5 minutes), the request is automatically rejected.
+
+## Approval queue
+
+The **Approvals** page in the Platform is where admins review and act on pending requests. It has three tabs: **Pending**, **History**, and **Notifications**.
+
+### Pending approvals
+
+Each pending approval card shows the full context needed to make a decision:
+
+- **Tool name** and **server** — what the agent wants to do and where
+- **Agent and user identity** — who is making the request
+- **Tool arguments** — the exact parameters being passed (e.g., which issue ID, which repository)
+- **Countdown timer** — time remaining before automatic rejection
+
+![Approval queue with pending request](/img/agent-security/hitl/approval-queue-pending.png)
+
+Admins can **Approve** or **Reject** each request. When rejecting, you can provide a reason — either a quick preset ("Unauthorized scope", "Suspicious arguments", "Wrong environment") or a custom message.
+
+![Rejecting with a reason](/img/agent-security/hitl/approval-reject-with-reason.png)
+
+The rejection reason is included in the error message returned to the agent, so the user understands why their request was denied.
+
+![Agent sees rejection reason](/img/agent-security/hitl/agent-rejection-message.png)
+
+When multiple approvals are pending, select multiple cards using the checkboxes and use the batch action bar to approve or reject all selected requests at once.
+
+:::tip Keyboard shortcuts
+**J/K** navigate cards · **A** approve · **R** reject · **X** select · **Esc** deselect
+:::
+
+### Approval history
+
+The **History** tab shows all resolved approvals — who made each decision, how long it took, and the outcome (approved, rejected, timed out, or cancelled). Use the status filter to narrow down by outcome.
+
+![Approval history](/img/agent-security/hitl/approval-history-full.png)
+
+## Configuring approval policies
+
+### Per-tool approval
+
+On any MCP server's detail page, each tool has a **HITL toggle**. Enable it to require approval for that specific tool — use this for individual high-risk operations.
+
+![Per-tool HITL toggle on the tool list](/img/agent-security/hitl/per-tool-hitl-toggle.png)
+
+### Server approval policy
+
+The **Server Approval Policy** card on the server detail page provides broader controls:
+
+- **Require approval for all tools** — every tool on this server requires approval
+- **Trust level threshold** — require approval for tools at a specific [trust level](/permit-mcp-gateway/guide) or higher. For example, set to "High" to gate only the most critical tools, or "Low" to gate everything.
+
+![Server approval policy and trusted agent bypass](/img/agent-security/hitl/server-policy-and-bypass.png)
+
+Per-tool toggles, server policies, and trust level thresholds all stack — if any of them requires approval, the tool call is gated.
+
+### Trusted agent bypass
+
+For trusted automation (e.g., CI bots, scheduled pipelines) that should not require manual approval, add the agent's client ID to the **Trusted Agent Bypass** list. Bypassed agents skip the approval check entirely — this takes priority over all other policies.
+
+You can find an agent's client ID on the **Agents** page in the Platform.
+
+## Notifications
+
+Configure where approval notifications are sent so admins know immediately when a request is waiting. Go to **Approvals > Notifications** to set up:
+
+![Notification settings](/img/agent-security/hitl/notification-settings.png)
+
+### Email notifications
+
+Add email addresses to receive a notification whenever a new approval request is created. The email includes the tool name, server, agent identity, and a link to review in the Platform.
+
+![Email notification](/img/agent-security/hitl/email-notification.png)
+
+### Slack notifications
+
+Paste a [Slack Incoming Webhook](https://api.slack.com/messaging/webhooks) URL to receive notifications in a Slack channel. The message includes the approval context and a button to open the Platform for review. For security, tool arguments are not included in Slack messages.
+
+![Slack notification](/img/agent-security/hitl/slack-notification.png)
+
+### Browser notifications
+
+When the Platform is open in a browser tab (even in the background), you'll receive desktop notifications for new approval requests automatically. No configuration needed.
+
+## Timeouts
+
+- **Default timeout:** 5 minutes — if no admin responds, the request is automatically rejected
+- **Extend:** Click the **Extend** button on the approval card to add more time while reviewing
+- Timeouts always result in rejection, never automatic approval
+- If the agent disconnects while waiting, the request is automatically cancelled
+
+## What the agent user sees
+
+When a tool call is paused for approval, the agent receives a notification:
+
+> Tool 'delete_repo' requires admin approval before execution. Waiting for approval (timeout: 5 minutes)...
+
+Most MCP clients (Cursor, Claude Desktop, Claude Code) display this message so the user knows the wait is intentional. If the request is rejected, the error message includes the reason provided by the admin.

docs/permit-mcp-gateway/platform.mdx

@@ -27,6 +27,7 @@ The platform UI is organized around two navigation areas:
 
 - **Dashboard** — host overview with the gateway MCP URL and client configuration snippets
 - **MCP Servers** — import and manage upstream MCP servers
+- **Approvals** — review and act on pending [human-in-the-loop](/permit-mcp-gateway/human-in-the-loop) approval requests, view history, and configure notifications
 - **Agents** — view and manage MCP clients that have connected through the gateway
 - **Humans** — manage user access to MCP servers and view connected agents
 - **Settings** — configure authentication methods, domain restrictions, and SSO

sidebars.js

@@ -213,6 +213,7 @@ const sidebars = {
             "permit-mcp-gateway/consent-service",
             "permit-mcp-gateway/audit-logs",
             "permit-mcp-gateway/architecture",
+            "permit-mcp-gateway/human-in-the-loop",
             "permit-mcp-gateway/permit-integration",
             "permit-mcp-gateway/advanced-features",
             "permit-mcp-gateway/enterprise-deployment",