feat(policy): add --admin-policy flag for supplemental admin policies (#20360)

docs/reference/configuration.md

@@ -92,6 +92,13 @@ their corresponding top-level category object in your `settings.json` file.
   - **Default:** `[]`
   - **Requires restart:** Yes
 
+#### `adminPolicyPaths`
+
+- **`adminPolicyPaths`** (array):
+  - **Description:** Additional admin policy files or directories to load.
+  - **Default:** `[]`
+  - **Requires restart:** Yes
+
 #### `general`
 
 - **`general.preferredEditor`** (string):

docs/reference/policy-engine.md

@@ -191,9 +191,13 @@ User, and (if configured) Admin directories.
 
 #### System-wide policies (Admin)
 
-Administrators can enforce system-wide policies (Tier 3) that override all user
-and default settings. These policies must be placed in specific, secure
-directories:
+Administrators can enforce system-wide policies (Tier 4) that override all user
+and default settings. These policies can be loaded from standard system
+locations or supplemental paths.
+
+##### Standard Locations
+
+These are the default paths the CLI searches for admin policies:
 
 | OS          | Policy Directory Path                             |
 | :---------- | :------------------------------------------------ |
@@ -201,10 +205,25 @@ directories:
 | **macOS**   | `/Library/Application Support/GeminiCli/policies` |
 | **Windows** | `C:\ProgramData\gemini-cli\policies`              |
 
-**Security Requirements:**
+##### Supplemental Admin Policies
 
-To prevent privilege escalation, the CLI enforces strict security checks on
-admin directories. If checks fail, system policies are **ignored**.
+Administrators can also specify supplemental policy paths using:
+
+- The `--admin-policy` command-line flag.
+- The `adminPolicyPaths` setting in a system settings file.
+
+These supplemental policies are assigned the same **Admin** tier (Base 4) as
+policies in standard locations.
+
+**Security Guard**: Supplemental admin policies are **ignored** if any `.toml`
+policy files are found in the standard system location. This prevents flag-based
+overrides when a central system policy has already been established.
+
+#### Security Requirements
+
+To prevent privilege escalation, the CLI enforces strict security checks on the
+**standard system policy directory**. If checks fail, the policies in that
+directory are **ignored**.
 
 - **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
   or others (e.g., `chmod 755`).
@@ -214,6 +233,11 @@ admin directories. If checks fail, system policies are **ignored**.
   for non-admin groups. You may need to "Disable inheritance" in Advanced
   Security Settings._
 
+**Note:** Supplemental admin policies (provided via `--admin-policy` or
+`adminPolicyPaths` settings) are **NOT** subject to these strict ownership
+checks, as they are explicitly provided by the user or administrator in their
+current execution context.
+
 ### TOML rule schema
 
 Here is a breakdown of the fields available in a TOML policy rule: