diff --git a/docs/reference/exec-tool.md b/docs/reference/exec-tool.md
index 5a3f758dc..9552fd50f 100644
--- a/docs/reference/exec-tool.md
+++ b/docs/reference/exec-tool.md
@@ -391,4 +391,30 @@ type ToolResult struct {
   "ForUser": "This command is not allowed for security reasons",
   "IsError": true
 }
+
+## Permission System (New)
+
+When `tools.exec.ask_permission = true` (default), the exec tool will ask for user permission before accessing paths outside workspace.
+
+### How It Works
+
+1. Exec tool detects command accesses path outside workspace
+2. Checks PermissionCache - if no permission, returns early
+3. LLM calls `request_permission` tool
+4. Tool returns prompt for user: "Allow once" or "Allow for session"
+5. User responds, LLM re-calls exec tool
+6. Permission cached for "once" (consumed after use) or "session" (persists)
+
+### Request Permission Tool
+
+| Field | Description |
+|-------|-------------|
+| `path` | Path that needs permission |
+| `command` | Original command (for context) |
+
+### Permission Options
+
+- **once**: Permission consumed after first use
+- **session**: Permission persists for entire session
+- **no**: Access denied
 ```
diff --git a/docs/reference/tools-api.md b/docs/reference/tools-api.md
index 165c33279..3f7158c9d 100644
--- a/docs/reference/tools-api.md
+++ b/docs/reference/tools-api.md
@@ -261,9 +261,16 @@ The `ToolRegistry` (`pkg/tools/registry.go`) manages all tools:
 |-----------|-------------|----------|------------|
 | `tool_search_tool_regex` | Discover hidden MCP tools by regex | discovery | `mcp.discovery.use_regex` |
 | `tool_search_tool_bm25` | Discover hidden MCP tools by semantics | discovery | `mcp.discovery.use_bm25` |
+| `request_permission` | Request user permission for outside-workspace access | permission | `exec.ask_permission` |
 
 **Dependencies**: Requires `mcp` and `mcp.discovery` to be enabled
 
+### Permission Tools
+
+| Tool Name | Description | Category | Config Key |
+|-----------|-------------|----------|------------|
+| `request_permission` | Request user permission for outside-workspace access | permission | `exec.ask_permission` |
+
 ## Backend API Endpoints
 
 ### Base URL