Policy engine
Gemini CLI policy engine 的用途：细粒度控制工具执行、替代简单 allowed tools、适合团队和企业治理。
Policy engine 用来更细粒度地控制工具能否执行、在什么条件下执行。官方 CLI cheatsheet 里也提示 --allowed-tools 已 deprecated，建议使用 policy engine。
权限边界要写进 policy，不要只写进 prompt。Prompt 是建议，policy 是执行前拦截。
它的核心不是“开或关某个工具”，而是按规则决定工具调用应该 allow、deny 还是 ask_user。规则写在 TOML 文件中，可以匹配工具名、参数、交互模式和优先级。
Policy 的价值在于执行前拦截。尤其是 shell、MCP 写工具、subagent 和自动化任务，越不能靠“模型会听话”来控制。规则要能被负例测试触发。
适合控制
- 哪些工具可用。
- 哪些命令需要确认。
- 哪些目录禁止写。
- 哪些 MCP server 可以用。
- 团队默认安全策略。
基本规则
最常见的规则结构包含四个字段：
toolName：匹配工具名，例如run_shell_command。commandPrefix或argsPattern：匹配命令或参数。decision：allow、deny或ask_user。priority：数字越大优先级越高。
例如高风险 shell 前缀应当直接 deny；常见但有副作用的 git、npm、pnpm、docker 命令可以先设为 ask_user。
决策含义
allow：工具直接执行，不再询问。ask_user：让用户确认；headless 场景里通常等同于 deny。deny：阻断工具调用。对于全局 deny，工具还会从模型可见工具列表中排除，这比只靠 prompt 要可靠。
优先级与层级
Policy engine 有 Default、Extension、Workspace、User、Admin 等层级。官方文档特别说明：Workspace tier 当前不可用，项目级 .gemini/policies 不会生效，应使用 User 或 Admin policies。
团队环境里，Admin policy 应该压过个人配置；个人本机可以用 ~/.gemini/policies/*.toml 做默认保护。
使用建议
个人项目可以先用默认确认；团队项目应该把 policy 写清楚，避免每个人用不同的权限模型。
不要只靠“请不要删除文件”这种 prompt 管权限。真正的权限边界应该进入 policy：危险 shell 前缀、未知 MCP 写操作、生产目录写入、部署和删除命令都应明确规则。
| 风险 | 建议 decision |
|---|---|
git status、rg、只读诊断 | allow 或默认确认 |
npm install、docker、迁移命令 | ask_user |
rm -rf、生产目录写入 | deny |
| 未知 MCP 写操作 | ask_user 或 deny |
| headless 中需要人工确认的动作 | deny |
验收方式
写完 policy 后要主动触发测试：让 Gemini CLI 尝试一个应该被拦截的命令，确认它被 deny 或 ask_user；再测试一个应该允许的只读命令，确认没有误伤。否则 policy 只是“看起来安全”。
还要做反向测试：确认高优先级 deny 不会被低优先级 allow 覆盖，确认 headless 中 ask_user 不会变成静默允许。团队环境里，每次改 policy 都应该留下测试用例和预期结果。
企业环境还应把 policy 版本化，避免各机器漂移。
如果一个动作在交互模式下是 ask_user，在无交互 headless 场景里要按不可确认处理。自动化任务不应该依赖人工弹窗；需要人工确认的动作要在 CI 之前拆成审批步骤。
最小上线组合
个人项目可以从三条规则开始：允许只读诊断，询问安装依赖和 Git 写操作，拒绝删除、部署和生产目录写入。团队项目再补 MCP allowlist、subagent 限制和 Admin policy。
Policy 不需要一次写成“大而全”。先覆盖最危险的误操作，再用日志和失败案例补规则，反而更容易维护。
接下来去哪
Enterprise config
团队和企业要把 policy 放进统一配置与管理路径。
MCP 设置
MCP 写工具也要受 policy 和最小权限控制。
Sandbox
policy 管权限，sandbox 管执行环境，两者配合使用。