Add a comprehensive tool approval system that requires explicit user consent before AI agents execute tools, with granular control at both the parent tool and child function level.
Backend:
Add ENABLE_TOOL_APPROVAL config setting (env var + admin toggle)
Add ToolApprovalManager with in-memory state for pending approvals, always-approved permissions, and YOLO mode tracking
Integrate approval checks into middleware for both streaming and non-streaming tool calls, with per-function granularity
Add Socket.IO handlers for approval responses, always-approved CRUD, and YOLO mode management
Add BUILTIN_TOOL_CATEGORIES canonical mapping and GET /tools/builtin/categories endpoint for dynamic builtin tool category metadata
Frontend:
Add ToolApprovalModal with Allow Once, Always Approve (per-function and per-tool), and Decline actions
Add YOLO Mode and Always Allowed sub-menus to IntegrationsMenu with per-tool toggles and tree-view revocation UI
Add toolApproval Svelte store for socket-based state management
Add cross-tab coordination via BroadcastChannel
Show inline warning for unrecognized tool calls in approval modal
Contribution Note:
This feature was initially developed by @Barbaronno and extended with granular per-function/per-tool permissions, YOLO mode, an always-allowed revocation UI, and unrecognized tool call warnings.
This submitted commit adds @Barbaronno as a co-author.
Note to first-time contributors: Please open a discussion post in Discussions to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request.
This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR.
Before submitting, make sure you've checked the following:
Target branch: Verify that the pull request targets the dev branch. PRs targeting main will be immediately closed.
Description: Provide a concise description of the changes made in this pull request down below.
Changelog: Ensure a changelog entry following the format of Keep a Changelog is added at the bottom of the PR description.
Documentation: Add docs in Open WebUI Docs Repository. Document user-facing behavior, environment variables, public APIs/interfaces, or deployment steps.
Dependencies: Are there any new or upgraded dependencies? If so, explain why, update the changelog/docs, and include any compatibility notes. Actually run the code/function that uses updated library to ensure it doesn't crash.
Testing: Perform manual tests to verify the implemented fix/feature works as intended AND does not break any other functionality. Include reproducible steps to demonstrate the issue before the fix. Test edge cases (URL encoding, HTML entities, types). Take this as an opportunity to make screenshots of the feature/fix and include them in the PR description.
Agentic AI Code: Confirm this Pull Request is not written by any AI Agent or has at least gone through additional human review AND manual testing. If any AI Agent is the co-author of this PR, it may lead to immediate closure of the PR.
Both the description and code were heavily helped by cursor with Opus 4.6 as my favored model, but I am responsible for reviewing and testing it. It made a fair number of odd decisions along the way that I corrected. For instance the backend storage data structure was a mess, but it cleaned things up nicely when I recommended the nested dictionary and tree-view structures.
Code review: Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
Design & Architecture: Prefer smart defaults over adding new settings; use local state for ephemeral UI logic. Open a Discussion for major architectural or UX changes.
Git Hygiene: Keep PRs atomic (one logical change). Clean up commits and rebase on dev to ensure no unrelated commits (e.g. from main) are included. Push updates to the existing PR branch instead of closing and reopening.
Refactor Notice: Minor refactor included. built-in tools for models in the admin panel were hard-coded before. Moved this to a dictionary with an endpoint for the backend so they can be shared with the new features. I kept this in a separate commit in case you'd like a separate PR.
Title Prefix: To clearly categorize this pull request, prefix the pull request title using one of the following:
BREAKING CHANGE: Significant changes that may affect compatibility
build: Changes that affect the build system or external dependencies
ci: Changes to our continuous integration processes or workflows
chore: Refactor, cleanup, or other non-functional code changes
docs: Documentation update or addition
feat: Introduces a new feature or enhancement to the codebase
fix: Bug fix or error correction
i18n: Internationalization or localization changes
perf: Performance improvement
refactor: Code restructuring for better maintainability, readability, or scalability
style: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
test: Adding missing tests or correcting existing tests
WIP: Work in progress, a temporary label for incomplete or ongoing work
Changelog Entry
Description
Adds a human-in-the-loop (HITL) tool approval system that requires explicit user consent before AI agents execute tools during chat. When enabled, every tool call pauses and presents a modal asking the user to Allow Once, Always Approve, or Decline. Approval granularity operates at both the individual function level (e.g. read_file) and the parent tool level (e.g. mcp:desktop_commander). A YOLO Mode option is available for users who want to auto-approve all tool calls without prompts. All approval state is per-chat and in-memory — nothing is persisted to disk or database.
Added
ENABLE_TOOL_APPROVAL configuration setting — toggleable via environment variable or Admin Settings > General. Defaults to true.
ToolApprovalManager backend class (backend/open_webui/utils/tool_approval.py) managing pending approvals, always-approved permissions, and YOLO mode state, all in-memory and per-chat.
Middleware integration for both streaming and non-streaming tool calls that checks approval status before execution, with per-function granularity.
Socket.IO handlers (backend/open_webui/socket/main.py) for real-time approval responses, always-approved CRUD, YOLO mode management, and pending approval recovery.
ToolApprovalModal frontend component with four actions: Allow Once, Always Approve (per-function), Always Approve (per-tool), and Decline.
YOLO Mode sub-menu in IntegrationsMenu with a master "YOLO All Tools" toggle and per-category toggles organized into Default Features (gated by model capabilities), Builtin Tools (loaded dynamically from backend), and Workspace Tools sections.
Always Allowed sub-menu in IntegrationsMenu with a tree-view display of approved parent tools and their child functions, with individual and bulk revocation.
toolApproval Svelte store (src/lib/stores/toolApproval.ts) for socket-based frontend state management.
Cross-tab coordination via BroadcastChannel (src/lib/utils/toolApprovalChannel.ts) to prevent duplicate approval modals across browser tabs.
TypeScript interfaces for tool approval data structures (src/lib/types/index.ts).
Inline warning banner in approval modal when a tool call has an unrecognized parent tool ID.
BUILTIN_TOOL_CATEGORIES dict in tools.py as single source of truth for builtin tool category names, descriptions, and function mappings.
GET /tools/builtin/categories API endpoint serving builtin tool metadata to authenticated users.
Changed
Refactor Notice: built-in tools for models in the admin panel were hard-coded before. Moved this to a dictionary with an endpoint for the backend.
BuiltinTools.svelte admin component fetches categories from backend API instead of hardcoding.
IntegrationsMenu now accepts a chatId prop and displays YOLO Mode and Always Allowed entries when a chat is active.
MessageInput passes chatId down to IntegrationsMenu.
Chat.svelte passes chatId to the message input component.
+layout.svelte handles tool:approval_request and tool:approval_status socket events globally.
Admin config endpoints (routers/auths.py) expose and accept ENABLE_TOOL_APPROVAL.
MCP tools and direct server tools in middleware now carry a tool_id field for parent tool resolution.
Deprecated
N/A
Removed
N/A
Fixed
N/A
Security
N/A
Breaking Changes
N/A
Additional Information
Contribution Note: This feature was initially developed by @Barbaronno and extended with granular per-function/per-tool permissions, YOLO mode, an always-allowed revocation UI, and unrecognized tool call warnings.
This submitted commit adds @Barbaronno as a co-author.
All approval state lives in-memory on the backend (ToolApprovalManager singleton) and resets on server restart. No database migrations or schema changes.
The ENABLE_TOOL_APPROVAL env var can be set to false to disable the feature entirely, bypassing all approval checks.
Approval granularity: functions are identified by their callable name (e.g. read_file), parent tools by their registered ID (e.g. mcp:desktop_commander, direct_server:http://...).
YOLO Mode and Always Approved are scoped per-chat, so enabling YOLO in one conversation does not affect others.
Screenshots or Videos
Scenario 1.a — YOLO a single tool in a new chat
YOLO "Web Search" in a new chat, then
Prompt: Find documentation for aws strands. Result: No permission was asked to use web search tool.
Scenario 1.b — Disable YOLO in the same chat
In the same chat, turn YOLO off for "Web Search".
Prompt: Great! Now find documentation for dynamodb. Result: Approval modal prompts for search_web / builtin:search_web.
Scenario 1.c — Always allow function
Click always allow for the function Result: Search completed and function added to always allow list.
Scenario 1.d — Always allow tool
Prompt: Great! Now generate an image of a cat riding a donkey.
Click always allow at tool level Result: Result: Always allow menu now shows the always allowed function as well as the tool. All functions approved displayed for tool-level approval
Scenario 1.e — Revoke function access
Click the red x to revoke access for a web search
Prompt: Now search for documentation for vLLM Result: Modal prompt for allowing a web search.
Scenario 1.f — Cross-tab coordination
Open the existing chat from Scenario 1.2 in a new browser window. How about my phone!
Result: Approval modal prompts in the new device for web search.
Note: These aren't the only test I preformed, but it became tedious to document it all in this format.
I have tested allow once.
I have tested decline. It suggests to the tool that the user declined it. I have seen this redirect the llm mid stream. For instance it tried to access the knowledge base and I declined it and it did a web search instead.
I have tested with several functions under one tool and confirmed that the allow always ones allow, but not the individual functions for the same tool that aren't in the always allow list.
I have tested it with the subagents tool. Note, this isn't supported at this time. It seemed to ignore permissions.
Error found during testing: Sometimes opening the menu to observe a recently changed setting wouldn't show the change until closing the menu and opening again. Fixed by awaiting the async operation. Updated existing feature commit and pushed. Re-tested.
Bonus screenshot:
Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
Note
Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.
## 📋 Pull Request Information
**Original PR:** https://github.com/open-webui/open-webui/pull/21678
**Author:** [@MaderHatt3r](https://github.com/MaderHatt3r)
**Created:** 2/21/2026
**Status:** ❌ Closed
**Base:** `dev` ← **Head:** `feat/human-in-the-loop`
---
### 📝 Commits (3)
- [`a24db4e`](https://github.com/open-webui/open-webui/commit/a24db4e19c91f424057d0735cd9a6e7adfca33f6) feat: add human-in-the-loop tool approval system
- [`00c3b40`](https://github.com/open-webui/open-webui/commit/00c3b40cf9fc49f80ebf6114d2d9b6fa8bb50584) refactor: load builtin tool categories from backend API
- [`ee7a78a`](https://github.com/open-webui/open-webui/commit/ee7a78a1ed492bff632844ac3ba9feec7b535b5f) style: run prettier and black formatters
### 📊 Changes
**18 files changed** (+2214 additions, -83 deletions)
<details>
<summary>View changed files</summary>
📝 `backend/open_webui/config.py` (+10 -1)
📝 `backend/open_webui/routers/auths.py` (+4 -0)
📝 `backend/open_webui/routers/tools.py` (+11 -1)
📝 `backend/open_webui/socket/main.py` (+222 -0)
📝 `backend/open_webui/utils/middleware.py` (+312 -2)
➕ `backend/open_webui/utils/tool_approval.py` (+211 -0)
📝 `backend/open_webui/utils/tools.py` (+96 -1)
📝 `src/lib/apis/tools/index.ts` (+32 -0)
📝 `src/lib/components/admin/Settings/General.svelte` (+8 -0)
📝 `src/lib/components/chat/Chat.svelte` (+11 -0)
📝 `src/lib/components/chat/MessageInput.svelte` (+3 -0)
📝 `src/lib/components/chat/MessageInput/IntegrationsMenu.svelte` (+517 -29)
➕ `src/lib/components/chat/ToolApprovalModal.svelte` (+290 -0)
📝 `src/lib/components/workspace/Models/BuiltinTools.svelte` (+17 -49)
➕ `src/lib/stores/toolApproval.ts` (+322 -0)
📝 `src/lib/types/index.ts` (+30 -0)
➕ `src/lib/utils/toolApprovalChannel.ts` (+80 -0)
📝 `src/routes/+layout.svelte` (+38 -0)
</details>
### 📄 Description
Add a comprehensive tool approval system that requires explicit user consent before AI agents execute tools, with granular control at both the parent tool and child function level.
Backend:
- Add ENABLE_TOOL_APPROVAL config setting (env var + admin toggle)
- Add ToolApprovalManager with in-memory state for pending approvals, always-approved permissions, and YOLO mode tracking
- Integrate approval checks into middleware for both streaming and non-streaming tool calls, with per-function granularity
- Add Socket.IO handlers for approval responses, always-approved CRUD, and YOLO mode management
- Add `BUILTIN_TOOL_CATEGORIES` canonical mapping and `GET /tools/builtin/categories` endpoint for dynamic builtin tool category metadata
Frontend:
- Add ToolApprovalModal with Allow Once, Always Approve (per-function and per-tool), and Decline actions
- Add YOLO Mode and Always Allowed sub-menus to IntegrationsMenu with per-tool toggles and tree-view revocation UI
- Add toolApproval Svelte store for socket-based state management
- Add cross-tab coordination via BroadcastChannel
- Show inline warning for unrecognized tool calls in approval modal
**Contribution Note**:
This feature was initially developed by @Barbaronno and extended with granular per-function/per-tool permissions, YOLO mode, an always-allowed revocation UI, and unrecognized tool call warnings.
This submitted commit adds @Barbaronno as a co-author.
See the original PR at: https://github.com/open-webui/open-webui/pull/16913
<!--
⚠️ CRITICAL CHECKS FOR CONTRIBUTORS (READ, DON'T DELETE) ⚠️
1. Target the `dev` branch. PRs targeting `main` will be automatically closed.
2. Do NOT delete the CLA section at the bottom. It is required for the bot to accept your PR.
-->
# Pull Request Checklist
### Note to first-time contributors: Please open a discussion post in [Discussions](https://github.com/open-webui/open-webui/discussions) to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request.
This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR.
#### First-time Contributor Acknowledgement
See the discussion at: https://github.com/open-webui/open-webui/discussions/16701
**Before submitting, make sure you've checked the following:**
- [x] **Target branch:** Verify that the pull request targets the `dev` branch. **PRs targeting `main` will be immediately closed.**
- [x] **Description:** Provide a concise description of the changes made in this pull request down below.
- [x] **Changelog:** Ensure a changelog entry following the format of [Keep a Changelog](https://keepachangelog.com/) is added at the bottom of the PR description.
- [x] **Documentation:** Add docs in [Open WebUI Docs Repository](https://github.com/open-webui/docs). Document user-facing behavior, environment variables, public APIs/interfaces, or deployment steps.
- [x] Documentation PR: https://github.com/open-webui/docs/pull/1095
- [x] **Dependencies:** Are there any new or upgraded dependencies? If so, explain why, update the changelog/docs, and include any compatibility notes. Actually run the code/function that uses updated library to ensure it doesn't crash.
- [x] **Testing:** Perform manual tests to **verify the implemented fix/feature works as intended AND does not break any other functionality**. Include reproducible steps to demonstrate the issue before the fix. Test edge cases (URL encoding, HTML entities, types). Take this as an opportunity to **make screenshots of the feature/fix and include them in the PR description**.
- [x] **Agentic AI Code:** Confirm this Pull Request is **not written by any AI Agent** or has at least **gone through additional human review AND manual testing**. If any AI Agent is the co-author of this PR, it may lead to immediate closure of the PR.
- [x] Both the description and code were heavily helped by cursor with Opus 4.6 as my favored model, but I am responsible for reviewing and testing it. It made a fair number of odd decisions along the way that I corrected. For instance the backend storage data structure was a mess, but it cleaned things up nicely when I recommended the nested dictionary and tree-view structures.
- [x] **Code review:** Have you performed a self-review of your code, addressing any coding standard issues and ensuring adherence to the project's coding standards?
- [x] **Design & Architecture:** Prefer smart defaults over adding new settings; use local state for ephemeral UI logic. Open a Discussion for major architectural or UX changes.
- [x] **Git Hygiene:** Keep PRs atomic (one logical change). Clean up commits and rebase on `dev` to ensure no unrelated commits (e.g. from `main`) are included. Push updates to the existing PR branch instead of closing and reopening.
- [x] **Refactor Notice:** Minor refactor included. built-in tools for models in the admin panel were hard-coded before. Moved this to a dictionary with an endpoint for the backend so they can be shared with the new features. I kept this in a separate commit in case you'd like a separate PR.
- [x] **Title Prefix:** To clearly categorize this pull request, prefix the pull request title using one of the following:
- **BREAKING CHANGE**: Significant changes that may affect compatibility
- **build**: Changes that affect the build system or external dependencies
- **ci**: Changes to our continuous integration processes or workflows
- **chore**: Refactor, cleanup, or other non-functional code changes
- **docs**: Documentation update or addition
- **feat**: Introduces a new feature or enhancement to the codebase
- **fix**: Bug fix or error correction
- **i18n**: Internationalization or localization changes
- **perf**: Performance improvement
- **refactor**: Code restructuring for better maintainability, readability, or scalability
- **style**: Changes that do not affect the meaning of the code (white space, formatting, missing semi-colons, etc.)
- **test**: Adding missing tests or correcting existing tests
- **WIP**: Work in progress, a temporary label for incomplete or ongoing work
# Changelog Entry
### Description
Adds a human-in-the-loop (HITL) tool approval system that requires explicit user consent before AI agents execute tools during chat. When enabled, every tool call pauses and presents a modal asking the user to **Allow Once**, **Always Approve**, or **Decline**. Approval granularity operates at both the individual function level (e.g. `read_file`) and the parent tool level (e.g. `mcp:desktop_commander`). A **YOLO Mode** option is available for users who want to auto-approve all tool calls without prompts. All approval state is per-chat and in-memory — nothing is persisted to disk or database.
### Added
- `ENABLE_TOOL_APPROVAL` configuration setting — toggleable via environment variable or Admin Settings > General. Defaults to `true`.
- `ToolApprovalManager` backend class (`backend/open_webui/utils/tool_approval.py`) managing pending approvals, always-approved permissions, and YOLO mode state, all in-memory and per-chat.
- Middleware integration for both streaming and non-streaming tool calls that checks approval status before execution, with per-function granularity.
- Socket.IO handlers (`backend/open_webui/socket/main.py`) for real-time approval responses, always-approved CRUD, YOLO mode management, and pending approval recovery.
- `ToolApprovalModal` frontend component with four actions: Allow Once, Always Approve (per-function), Always Approve (per-tool), and Decline.
- YOLO Mode sub-menu in IntegrationsMenu with a master "YOLO All Tools" toggle and per-category toggles organized into Default Features (gated by model capabilities), Builtin Tools (loaded dynamically from backend), and Workspace Tools sections.
- Always Allowed sub-menu in IntegrationsMenu with a tree-view display of approved parent tools and their child functions, with individual and bulk revocation.
- `toolApproval` Svelte store (`src/lib/stores/toolApproval.ts`) for socket-based frontend state management.
- Cross-tab coordination via `BroadcastChannel` (`src/lib/utils/toolApprovalChannel.ts`) to prevent duplicate approval modals across browser tabs.
- TypeScript interfaces for tool approval data structures (`src/lib/types/index.ts`).
- Inline warning banner in approval modal when a tool call has an unrecognized parent tool ID.
- `BUILTIN_TOOL_CATEGORIES` dict in `tools.py` as single source of truth for builtin tool category names, descriptions, and function mappings.
- `GET /tools/builtin/categories` API endpoint serving builtin tool metadata to authenticated users.
### Changed
- **Refactor Notice:** built-in tools for models in the admin panel were hard-coded before. Moved this to a dictionary with an endpoint for the backend.
- `BuiltinTools.svelte` admin component fetches categories from backend API instead of hardcoding.
- `IntegrationsMenu` now accepts a `chatId` prop and displays YOLO Mode and Always Allowed entries when a chat is active.
- `MessageInput` passes `chatId` down to `IntegrationsMenu`.
- `Chat.svelte` passes `chatId` to the message input component.
- `+layout.svelte` handles `tool:approval_request` and `tool:approval_status` socket events globally.
- Admin config endpoints (`routers/auths.py`) expose and accept `ENABLE_TOOL_APPROVAL`.
- MCP tools and direct server tools in middleware now carry a `tool_id` field for parent tool resolution.
### Deprecated
- N/A
### Removed
- N/A
### Fixed
- N/A
### Security
- N/A
### Breaking Changes
- N/A
---
### Additional Information
- **Contribution Note**: This feature was initially developed by @Barbaronno and extended with granular per-function/per-tool permissions, YOLO mode, an always-allowed revocation UI, and unrecognized tool call warnings.
- This submitted commit adds @Barbaronno as a co-author.
- See the original PR at: https://github.com/open-webui/open-webui/pull/16913
- **Documentation PR**: https://github.com/open-webui/docs/pull/1095
- All approval state lives in-memory on the backend (`ToolApprovalManager` singleton) and resets on server restart. No database migrations or schema changes.
- The `ENABLE_TOOL_APPROVAL` env var can be set to `false` to disable the feature entirely, bypassing all approval checks.
- Approval granularity: functions are identified by their callable name (e.g. `read_file`), parent tools by their registered ID (e.g. `mcp:desktop_commander`, `direct_server:http://...`).
- YOLO Mode and Always Approved are scoped per-chat, so enabling YOLO in one conversation does not affect others.
### Screenshots or Videos
**Scenario 1.a** — YOLO a single tool in a new chat
- YOLO "Web Search" in a new chat, then
- Prompt: `Find documentation for aws strands.`
**Result:** No permission was asked to use web search tool.
<img width="500" height="489" alt="image" src="https://github.com/user-attachments/assets/24fbc7b7-5625-4666-b7e4-55adc502fa10" />
**Scenario 1.b** — Disable YOLO in the same chat
- In the same chat, turn YOLO off for "Web Search".
- Prompt: `Great! Now find documentation for dynamodb.`
**Result:** Approval modal prompts for `search_web` / `builtin:search_web`.
<img width="1271" height="1107" alt="image" src="https://github.com/user-attachments/assets/50dffaa7-b422-468f-816f-334cc3a130d6" />
**Scenario 1.c** — Always allow function
- Click always allow for the function
**Result:** Search completed and function added to always allow list.
<img width="365" height="236" alt="image" src="https://github.com/user-attachments/assets/673cada3-41eb-46d1-a327-e3e6d5d889cf" />
**Scenario 1.d** — Always allow tool
- Prompt: `Great! Now generate an image of a cat riding a donkey.`
- Click always allow at tool level
**Result:** Result: Always allow menu now shows the always allowed function as well as the tool. `All functions approved` displayed for tool-level approval
<img width="1203" height="1097" alt="image" src="https://github.com/user-attachments/assets/7ed76644-f184-46fe-8aa7-bd5c4c52eb06" />
**Scenario 1.e** — Revoke function access
- Click the red x to revoke access for a web search
- Prompt: Now search for documentation for vLLM
**Result:** Modal prompt for allowing a web search.
<img width="1260" height="1100" alt="image" src="https://github.com/user-attachments/assets/327b4677-a219-43d0-9e02-daa2e9895421" />
**Scenario 1.f** — Cross-tab coordination
- Open the existing chat from Scenario 1.2 in a new browser window. How about my phone!
- **Result:** Approval modal prompts in the new device for web search.
<img width="1344" height="2609" alt="Screenshot_20260220-200859" src="https://github.com/user-attachments/assets/5e088cfa-90aa-45aa-b955-9261ec8a2584" />
Note: These aren't the only test I preformed, but it became tedious to document it all in this format.
I have tested allow once.
I have tested decline. It suggests to the tool that the user declined it. I have seen this redirect the llm mid stream. For instance it tried to access the knowledge base and I declined it and it did a web search instead.
<img width="1258" height="1102" alt="image" src="https://github.com/user-attachments/assets/81e53d44-136d-4fb8-8ed3-4b12e06ad72e" />
I have tested with several functions under one tool and confirmed that the allow always ones allow, but not the individual functions for the same tool that aren't in the always allow list.
I have tested it with the subagents tool. Note, this isn't supported at this time. It seemed to ignore permissions.
Error found during testing: Sometimes opening the menu to observe a recently changed setting wouldn't show the change until closing the menu and opening again. Fixed by awaiting the async operation. Updated existing feature commit and pushed. Re-tested.
Bonus screenshot:

### Contributor License Agreement
<!--
🚨 DO NOT DELETE THE TEXT BELOW 🚨
Keep the "Contributor License Agreement" confirmation text intact.
Deleting it will trigger the CLA-Bot to INVALIDATE your PR.
-->
By submitting this pull request, I confirm that I have read and fully agree to the [Contributor License Agreement (CLA)](https://github.com/open-webui/open-webui/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT), and I am providing my contributions under its terms.
> [!NOTE]
> Deleting the CLA section will lead to immediate closure of your PR and it will not be merged in.
---
<sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
📋 Pull Request Information
Original PR: https://github.com/open-webui/open-webui/pull/21678
Author: @MaderHatt3r
Created: 2/21/2026
Status: ❌ Closed
Base:
dev← Head:feat/human-in-the-loop📝 Commits (3)
a24db4efeat: add human-in-the-loop tool approval system00c3b40refactor: load builtin tool categories from backend APIee7a78astyle: run prettier and black formatters📊 Changes
18 files changed (+2214 additions, -83 deletions)
View changed files
📝
backend/open_webui/config.py(+10 -1)📝
backend/open_webui/routers/auths.py(+4 -0)📝
backend/open_webui/routers/tools.py(+11 -1)📝
backend/open_webui/socket/main.py(+222 -0)📝
backend/open_webui/utils/middleware.py(+312 -2)➕
backend/open_webui/utils/tool_approval.py(+211 -0)📝
backend/open_webui/utils/tools.py(+96 -1)📝
src/lib/apis/tools/index.ts(+32 -0)📝
src/lib/components/admin/Settings/General.svelte(+8 -0)📝
src/lib/components/chat/Chat.svelte(+11 -0)📝
src/lib/components/chat/MessageInput.svelte(+3 -0)📝
src/lib/components/chat/MessageInput/IntegrationsMenu.svelte(+517 -29)➕
src/lib/components/chat/ToolApprovalModal.svelte(+290 -0)📝
src/lib/components/workspace/Models/BuiltinTools.svelte(+17 -49)➕
src/lib/stores/toolApproval.ts(+322 -0)📝
src/lib/types/index.ts(+30 -0)➕
src/lib/utils/toolApprovalChannel.ts(+80 -0)📝
src/routes/+layout.svelte(+38 -0)📄 Description
Add a comprehensive tool approval system that requires explicit user consent before AI agents execute tools, with granular control at both the parent tool and child function level.
Backend:
BUILTIN_TOOL_CATEGORIEScanonical mapping andGET /tools/builtin/categoriesendpoint for dynamic builtin tool category metadataFrontend:
Contribution Note:
This feature was initially developed by @Barbaronno and extended with granular per-function/per-tool permissions, YOLO mode, an always-allowed revocation UI, and unrecognized tool call warnings.
This submitted commit adds @Barbaronno as a co-author.
See the original PR at: https://github.com/open-webui/open-webui/pull/16913
Pull Request Checklist
Note to first-time contributors: Please open a discussion post in Discussions to discuss your idea/fix with the community before creating a pull request, and describe your changes before submitting a pull request.
This is to ensure large feature PRs are discussed with the community first, before starting work on it. If the community does not want this feature or it is not relevant for Open WebUI as a project, it can be identified in the discussion before working on the feature and submitting the PR.
First-time Contributor Acknowledgement
See the discussion at: https://github.com/open-webui/open-webui/discussions/16701
Before submitting, make sure you've checked the following:
devbranch. PRs targetingmainwill be immediately closed.devto ensure no unrelated commits (e.g. frommain) are included. Push updates to the existing PR branch instead of closing and reopening.Changelog Entry
Description
Adds a human-in-the-loop (HITL) tool approval system that requires explicit user consent before AI agents execute tools during chat. When enabled, every tool call pauses and presents a modal asking the user to Allow Once, Always Approve, or Decline. Approval granularity operates at both the individual function level (e.g.
read_file) and the parent tool level (e.g.mcp:desktop_commander). A YOLO Mode option is available for users who want to auto-approve all tool calls without prompts. All approval state is per-chat and in-memory — nothing is persisted to disk or database.Added
ENABLE_TOOL_APPROVALconfiguration setting — toggleable via environment variable or Admin Settings > General. Defaults totrue.ToolApprovalManagerbackend class (backend/open_webui/utils/tool_approval.py) managing pending approvals, always-approved permissions, and YOLO mode state, all in-memory and per-chat.backend/open_webui/socket/main.py) for real-time approval responses, always-approved CRUD, YOLO mode management, and pending approval recovery.ToolApprovalModalfrontend component with four actions: Allow Once, Always Approve (per-function), Always Approve (per-tool), and Decline.toolApprovalSvelte store (src/lib/stores/toolApproval.ts) for socket-based frontend state management.BroadcastChannel(src/lib/utils/toolApprovalChannel.ts) to prevent duplicate approval modals across browser tabs.src/lib/types/index.ts).BUILTIN_TOOL_CATEGORIESdict intools.pyas single source of truth for builtin tool category names, descriptions, and function mappings.GET /tools/builtin/categoriesAPI endpoint serving builtin tool metadata to authenticated users.Changed
BuiltinTools.svelteadmin component fetches categories from backend API instead of hardcoding.IntegrationsMenunow accepts achatIdprop and displays YOLO Mode and Always Allowed entries when a chat is active.MessageInputpasseschatIddown toIntegrationsMenu.Chat.sveltepasseschatIdto the message input component.+layout.sveltehandlestool:approval_requestandtool:approval_statussocket events globally.routers/auths.py) expose and acceptENABLE_TOOL_APPROVAL.tool_idfield for parent tool resolution.Deprecated
Removed
Fixed
Security
Breaking Changes
Additional Information
ToolApprovalManagersingleton) and resets on server restart. No database migrations or schema changes.ENABLE_TOOL_APPROVALenv var can be set tofalseto disable the feature entirely, bypassing all approval checks.read_file), parent tools by their registered ID (e.g.mcp:desktop_commander,direct_server:http://...).Screenshots or Videos
Scenario 1.a — YOLO a single tool in a new chat
Find documentation for aws strands.Result: No permission was asked to use web search tool.
Scenario 1.b — Disable YOLO in the same chat
Great! Now find documentation for dynamodb.Result: Approval modal prompts for
search_web/builtin:search_web.Scenario 1.c — Always allow function
Result: Search completed and function added to always allow list.
Scenario 1.d — Always allow tool
Great! Now generate an image of a cat riding a donkey.Result: Result: Always allow menu now shows the always allowed function as well as the tool.
All functions approveddisplayed for tool-level approvalScenario 1.e — Revoke function access
Result: Modal prompt for allowing a web search.
Scenario 1.f — Cross-tab coordination
Note: These aren't the only test I preformed, but it became tedious to document it all in this format.
I have tested allow once.
I have tested decline. It suggests to the tool that the user declined it. I have seen this redirect the llm mid stream. For instance it tried to access the knowledge base and I declined it and it did a web search instead.
I have tested with several functions under one tool and confirmed that the allow always ones allow, but not the individual functions for the same tool that aren't in the always allow list.
I have tested it with the subagents tool. Note, this isn't supported at this time. It seemed to ignore permissions.
Error found during testing: Sometimes opening the menu to observe a recently changed setting wouldn't show the change until closing the menu and opening again. Fixed by awaiting the async operation. Updated existing feature commit and pushed. Re-tested.
Bonus screenshot:

Contributor License Agreement
By submitting this pull request, I confirm that I have read and fully agree to the Contributor License Agreement (CLA), and I am providing my contributions under its terms.
🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.