[PER-14506] Add Human-in-the-Loop approvals documentation#628
Open
EliMoshkovich wants to merge 10 commits intomasterfrom
Open
[PER-14506] Add Human-in-the-Loop approvals documentation#628EliMoshkovich wants to merge 10 commits intomasterfrom
EliMoshkovich wants to merge 10 commits intomasterfrom
Conversation
New dedicated HITL documentation page covering: - How approval flow works (gateway pauses → notifies → resumes/rejects) - Approval queue UI (pending cards, batch actions, keyboard shortcuts) - Rejection with reasons (presets + custom) - Approval history with status filter - Configuring approval policies (per-tool, per-server, per-trust-level) - Trusted agent bypass for automation - Email and Slack notification setup - Timeout and fail-closed behavior - Agent-side experience (what the user sees during wait/rejection) Screenshots included for all major features. Also: - Updated advanced-features.mdx to link to the new dedicated page - Updated platform.mdx sidebar description to include Approvals - Updated feature maturity table to reflect HITL is now available Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add Quick Start tip box at top for fast onboarding - Soften "interception point" language to be less surveillance-like - Add trust-level cross-reference links to guide page - Clarify who can approve (any Platform user) - Explain what "cancelled" means in history (client disconnected) - Explain the Extend button mechanism (click to add 5 more minutes) - Add note about finding agent client IDs on the Agents page - Fix enterprise maturity table (HITL is Enterprise, not "Available") - Remove unused approval-history.png screenshot - Change example tool in agent notification from get_issue to delete_repo Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Blur URL bar and bookmarks bar in notification-settings.png and server-policy-and-bypass.png (contained local dev URLs and personal bookmarks) - Blur email addresses in approval-history-full.png Decided By column (contained real employee email) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a dedicated Permit MCP Gateway documentation page for the Human-in-the-Loop (HITL) approvals feature, and updates existing docs to link to it.
Changes:
- Added a new
human-in-the-loop.mdxpage documenting the HITL flow, policies, notifications, timeouts, and agent experience (with screenshots). - Updated
advanced-features.mdxto summarize HITL capabilities and link to the dedicated guide; updated the feature maturity table entry to link to the new page. - Updated
platform.mdxto include an “Approvals” sidebar item description linking to the HITL guide.
Reviewed changes
Copilot reviewed 3 out of 11 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/permit-mcp-gateway/platform.mdx | Adds “Approvals” to the documented Platform sidebar navigation and links to HITL guide. |
| docs/permit-mcp-gateway/human-in-the-loop.mdx | New dedicated HITL approvals documentation page (queue/history/notifications/policies/timeouts + screenshots). |
| docs/permit-mcp-gateway/advanced-features.mdx | Links HITL section + maturity table entry to the new dedicated HITL page. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Fix sidebar_position collision: change HITL from 8 to 7.5 (permit-integration already uses 8) - Rewrite trust level threshold description to clearly explain that "High" is least restrictive and "Low" is most restrictive - Add Enterprise Plan admonition matching the pattern in advanced-features.mdx Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The docs sidebar is configured manually in sidebars.js, not auto-generated from frontmatter sidebar_position. Added the human-in-the-loop page between Architecture and Permit.io Integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Shows the tool list with individual HITL toggles — get_issue enabled (amber), other tools disabled. This was a missing screenshot identified in the docs review: customers need to see where the per-tool toggle lives on the MCP server detail page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…s, blurred emails) New screenshot shows 7 entries (up from 4) with all status types (Approved, Rejected, Cancelled) and Decision Time column. Email addresses in Decided By column are blurred. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…only data rows Re-applied blur starting below the header row (y=285) instead of covering the header (y=280). The Decided By column header is now preserved while email addresses in data rows are blurred. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…s, limits Added missing customer-relevant documentation: - Policy evaluation order: bypass → per-tool → per-server → trust level, with explicit explanation of how tiers interact - History table columns: Time, Tool, Server, Agent, Decided By, Decision Time, Decision — each explained - Tool arguments truncation note (64KB limit) - Timer color indicators (green → amber → red) - Slack privacy: tool arguments intentionally excluded from notifications - Extend limits: up to 30 min per extension, 1 hour max total - Pending limit: 50 concurrent approvals per host - Notification scope: settings apply per-host, policies per-server - Escape keyboard shortcut for deselect Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…n copy Removed customer-irrelevant details: - 64KB argument truncation limit - 50 pending approvals limit - 30-minute/1-hour extend limits - 4-tier numbered policy evaluation section (replaced with one sentence) - Notification scope callout - "fail-closed" jargon - Color indicator details (green/amber/red) - History column-by-column breakdown (replaced with one sentence) Simplified: - Keyboard shortcuts: compact single-line format - Batch actions: merged into pending approvals section - Timeouts: shorter, less edge-case focused - Trust level threshold: clearer single example - Overall ~30% shorter Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds dedicated documentation for the Human-in-the-Loop (HITL) approval feature.
docs/permit-mcp-gateway/human-in-the-loop.mdx— full guide covering approval queue, policies, notifications, timeouts, and agent experienceadvanced-features.mdxlinks to the new dedicated page, maturity table updatedplatform.mdxsidebar description includes ApprovalsDocumentation covers:
Test plan
/permit-mcp-gateway/guideand/permit-mcp-gateway/human-in-the-loopwork🤖 Generated with Claude Code