From 03e961ba4ae2274ce17fa78b9e38bdc9d75c2046 Mon Sep 17 00:00:00 2001
From: Trung Nguyen <trung.nguyen@docker.com>
Date: Wed, 25 Mar 2026 09:54:40 +0100
Subject: [PATCH] docs: document global permissions from user config

---
 docs/configuration/overview/index.md    |  3 +-
 docs/configuration/permissions/index.md | 49 ++++++++++++++++++++++++-
 docs/guides/tips/index.md               | 20 ++++++++++
 3 files changed, 70 insertions(+), 2 deletions(-)

diff --git a/docs/configuration/overview/index.md b/docs/configuration/overview/index.md
index 73d9bdabf..3f0ea14ee 100644
--- a/docs/configuration/overview/index.md
+++ b/docs/configuration/overview/index.md
@@ -53,7 +53,8 @@ providers:
     base_url: https://api.example.com/v1
     token_key: MY_API_KEY
 
-# 7. Permissions — global tool permission rules (optional)
+# 7. Permissions — agent-level tool permission rules (optional)
+#    For user-wide global permissions, see ~/.config/cagent/config.yaml
 permissions:
   allow: ["read_*"]
   deny: ["shell:cmd=sudo*"]
diff --git a/docs/configuration/permissions/index.md b/docs/configuration/permissions/index.md
index cb57ccfd3..9072c831d 100644
--- a/docs/configuration/permissions/index.md
+++ b/docs/configuration/permissions/index.md
@@ -19,7 +19,18 @@ Permissions provide fine-grained control over tool execution. You can configure
 
 </div>
 
-## Configuration
+## Permission Levels
+
+Permissions can be defined at two levels:
+
+| Level | Location | Scope |
+| ----- | -------- | ----- |
+| **Agent-level** | Agent YAML config (`permissions:` section) | Applies to that specific agent config |
+| **Global (user-level)** | `~/.config/cagent/config.yaml` under `settings.permissions` | Applies to every agent you run |
+
+Both levels use the same `allow`/`ask`/`deny` pattern syntax. When both are present, they are **merged** at startup -- patterns from both sources are combined into a single checker. See [Merging Behavior](#merging-behavior) for details.
+
+## Agent-Level Configuration
 
 ```yaml
 agents:
@@ -42,6 +53,42 @@ permissions:
     - "dangerous_tool"
 ```
 
+## Global Permissions
+
+Global permissions let you enforce rules across **all** agents, regardless of which agent config you run. Define them in your user config file:
+
+```yaml
+# ~/.config/cagent/config.yaml
+settings:
+  permissions:
+    deny:
+      - "shell:cmd=sudo*"
+      - "shell:cmd=rm*-rf*"
+    allow:
+      - "read_*"
+      - "shell:cmd=ls*"
+      - "shell:cmd=cat*"
+```
+
+This is useful for setting personal safety guardrails that apply everywhere -- for example, always blocking `sudo` or always auto-approving read-only tools -- without relying on each agent config to include those rules.
+
+### Merging Behavior
+
+When both global and agent-level permissions are present, they are merged into a single set of patterns before evaluation. The merge works as follows:
+
+- **Deny patterns from either source block the tool.** A global deny cannot be overridden by an agent-level allow, and vice versa.
+- **Allow patterns from either source auto-approve the tool** (as long as no deny pattern matches).
+- **Ask patterns from either source force confirmation** (as long as no deny or allow pattern matches).
+
+The evaluation order remains the same after merging: **Deny > Allow > Ask > default Ask**.
+
+<div class="callout callout-tip">
+<div class="callout-title">Example: Global deny + agent allow
+</div>
+  <p>If your global config denies <code>shell:cmd=sudo*</code> and an agent config allows <code>shell:cmd=sudo apt update</code>, the deny wins. Deny patterns always take priority regardless of source.</p>
+
+</div>
+
 ## Pattern Syntax
 
 Permissions support glob-style patterns with optional argument matching:
diff --git a/docs/guides/tips/index.md b/docs/guides/tips/index.md
index 0d8bcf03a..4be99eefc 100644
--- a/docs/guides/tips/index.md
+++ b/docs/guides/tips/index.md
@@ -232,6 +232,26 @@ permissions:
 docker-agent run --sandbox agent.yaml
 ```
 
+### Set Global Permission Guardrails
+
+Use [global permissions]({{ '/configuration/permissions/' | relative_url }}#global-permissions) in your user config to enforce safety rules across every agent:
+
+```yaml
+# ~/.config/cagent/config.yaml
+settings:
+  permissions:
+    deny:
+      - "shell:cmd=sudo*"
+      - "shell:cmd=rm*-rf*"
+      - "shell:cmd=git push --force*"
+    allow:
+      - "read_*"
+      - "shell:cmd=ls*"
+      - "shell:cmd=cat*"
+```
+
+These rules merge with any agent-level permissions. Deny patterns from your global config cannot be overridden by agent configs, so you can trust that dangerous commands stay blocked regardless of which agent you run.
+
 ### Use Hooks for Audit Logging
 
 Log all tool calls for compliance or debugging: