From ca50360cbde7e6726c70744e31828c04e26a318b Mon Sep 17 00:00:00 2001 From: Nicolas Ouellet-Payeur Date: Tue, 31 Mar 2026 20:02:30 +0000 Subject: [PATCH] docs(policy): mention that workspace policies are broken (#18186, #21580) Update the policy engine documentation to reflect that project-level (workspace) policies are currently disabled. Added a warning callout and updated the tier and location tables to accurately represent the feature's status. --- docs/reference/policy-engine.md | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/reference/policy-engine.md b/docs/reference/policy-engine.md index a86c201b85b..d9dc21f49cb 100644 --- a/docs/reference/policy-engine.md +++ b/docs/reference/policy-engine.md @@ -120,6 +120,12 @@ There are three possible decisions a rule can enforce: ### Priority system and tiers +> [!WARNING] The **Workspace** tier (project-level policies) is currently +> non-functional. Defining policies in a workspace's `.gemini/policies` +> directory will not have any effect. See +> [issue #18186](https://github.com/google-gemini/gemini-cli/issues/18186). Use +> User or Admin policies instead. + The policy engine uses a sophisticated priority system to resolve conflicts when multiple rules match a single tool call. The core principle is simple: **the rule with the highest priority wins**. @@ -127,13 +133,13 @@ rule with the highest priority wins**. To provide a clear hierarchy, policies are organized into three tiers. Each tier has a designated number that forms the base of the final priority calculation. -| Tier | Base | Description | -| :-------- | :--- | :-------------------------------------------------------------------------------- | -| Default | 1 | Built-in policies that ship with Gemini CLI. | -| Extension | 2 | Policies defined in extensions. | -| Workspace | 3 | Policies defined in the current workspace's configuration directory. | -| User | 4 | Custom policies defined by the user. | -| Admin | 5 | Policies managed by an administrator (for example, in an enterprise environment). | +| Tier | Base | Description | +| :-------- | :--- | :-------------------------------------------------------------------------------------------- | +| Default | 1 | Built-in policies that ship with Gemini CLI. | +| Extension | 2 | Policies defined in extensions. | +| Workspace | 3 | **(Currently disabled)** Policies defined in the current workspace's configuration directory. | +| User | 4 | Custom policies defined by the user. | +| Admin | 5 | Policies managed by an administrator (for example, in an enterprise environment). | Within a TOML policy file, you assign a priority value from **0 to 999**. The engine transforms this into a final priority using the following formula: @@ -214,11 +220,11 @@ User, and (if configured) Admin directories. ### Policy locations -| Tier | Type | Location | -| :------------ | :----- | :---------------------------------------- | -| **User** | Custom | `~/.gemini/policies/*.toml` | -| **Workspace** | Custom | `$WORKSPACE_ROOT/.gemini/policies/*.toml` | -| **Admin** | System | _See below (OS specific)_ | +| Tier | Type | Location | +| :------------ | :----- | :------------------------------------------------------- | +| **User** | Custom | `~/.gemini/policies/*.toml` | +| **Workspace** | Custom | **(Disabled)** `$WORKSPACE_ROOT/.gemini/policies/*.toml` | +| **Admin** | System | _See below (OS specific)_ | #### System-wide policies (Admin)