计划目录、策略与 Hooks

控制 Plan Mode 的文件写入范围，理解跨模式批准和工具转换的 Hooks 限制。

This page has not been translated into English yet. The original Chinese version is shown below.

Plan Mode 默认策略来自内置 plan.toml；用户 ~/.gemini/policies/ 的规则可以覆盖或扩展。自定义后应检查真实权限，不能仅凭模式名称判断“完全只读”。

限定规则模式

未指定 modes 的策略始终活动，也会影响 Plan。仅希望 Default 和 Auto-Edit 中允许的命令，应明确列出模式：

[[rule]]
toolName = "run_shell_command"
commandPrefix = "npm test"
decision = "allow"
priority = 100
modes = ["default", "autoEdit"]

这是策略枚举 autoEdit，与 CLI 参数 auto_edit 的拼法不同。持久批准也区分上下文：在 Default/Auto-Edit 授予的工具信任不自动带入 Plan；在 Plan 中授予的批准可适用于所有模式。

{
  "general": {
    "plan": {
      "directory": ".gemini/plans"
    }
  }
}

用户配置的计划目录必须位于项目边界内，同时需要对应策略允许 write_file/replace 写该目录中的 Markdown。不能只换目录就假定写权限随之开启，也不要为了计划放行全部项目文件。自定义计划不受默认会话清理自动删除，需要自行管理。

enter_plan_mode 可带 reason；exit_plan_mode 使用必需的 plan_path，验证路径允许、文件存在且非空，再呈交用户。工具专页的示例临时路径较简略，当前 Plan 专页使用带 session-id 的路径，并说明可配置目录；以当前会话生成位置为准。

BeforeTool/AfterTool 可匹配 enter_plan_mode、exit_plan_mode。但手工 /plan 或 Shift+Tab 转换不是工具调用，不触发这些 Hooks；不能据此宣称记录了每一次模式变化。

官方 Plan 页归档脚本示例读取 tool_input.plan_filename，而规划工具参考规定 plan_path，二者不一致。本页不复制该脚本作为可用模板，部署归档前应核对当前工具实际载荷与 Hooks schema。归档外部存储也需要独立配置认证和权限。