my-pi/pi-permission-system/AGENTS.md

# my-pi 维护约定（pi-permission-system）

- 扩展入口是 `pi-permission-system/src/index.ts`，公共跨扩展服务入口是 `pi-permission-system/src/service.ts`，测试保留在该目录的 `test/`；根包经 `extensions/permission-system.ts` 直接加载源码。
- 同步上游必须从明确 tag/commit 移植并记录快照；保留上游 `LICENSE`、作者和来源，不导入 `dist/`、嵌套 `.git` 或上游包目录的 `.pi` 本地状态。双上游来源见 `UPSTREAM.md` 与 `docs/auto-review/UPSTREAM.md`。
- 配置在 `authorizerChain` 中显式命名的 authorizer 可对任一普通策略 `ask`（包括 `path`）返回最终 `allow` / `deny`；`defer` 才继续下一个 authorizer 或终端人工 authority。
- `auto-review` 是内置 authorizer，不是独立扩展或第二个 `tool_call` gate；只复核普通策略产生的 `ask`，不会重复处理普通策略已 `allow` / `deny` 或硬防御已 `deny` 的请求。
- reviewer 是对话式 Codex Guardian 风格审查：以独立请求（不写入主会话）把有界 active-branch 对话记录与权限请求交给模型，模型只能通过 `approve` / `reject` 两个工具给出带 `reason` 的结论，不强制 `toolChoice`。`approve` 自动批准（包括 `path`）；`reject` 以及配置、模型、超时、Provider 错误、截断、未调用工具、多次调用或参数无效等一切异常都必须 `defer` 到人工提示，并在弹窗中显示原因（模型理由标注为模型生成）。正文文本即使是合法 JSON 也不得作为结论；只有用户按 Esc 中止当前操作时才直接拒绝。不得在 authorizer chain 外增加第二层内置授权范围限制，也不得恢复 annotator 机制。唯一例外是 `protectedWrites`：硬防御文件里配置的确定性 human-only 写路径——它不经 authorizer chain（含 AutoReview）、yolo 或 Session grant，无确认界面时直接拒绝，本身不产生裁决，只是永远把人拉进回路。
- reviewer 默认跟随会话当前主模型（每次审查实时读取 `ctx.model`），经 `modelRegistry.streamSimple(...).result()` 调用；`autoReview.provider` / `autoReview.model` 必须同时设置（固定审查模型）或同时留空，只设其一视为配置错误并 `defer`。默认 `reasoning: "low"`（仅对支持推理的模型生效）、总超时 30 秒、最多 2 次尝试（仅 Provider 错误重试）、`maxOutputTokens` 4000。只把 active branch 中的直接用户消息与已识别、未取消的结构化问答作为授权证据，assistant/tool/compaction 内容不能自行授权；工具结果可替换为更短的 pi-compaction 摘要，但仍属不可信证据。同一条用户消息内完全相同的请求只缓存 `approve` 结论。
- `config/pi-permission-policy.jsonc` 必须显式配置 `authorizerChain: ["auto-review"]`，普通未匹配请求和需要自动复核的类别声明为 `ask`；普通 pattern 必须按具体度优先（精确匹配、字面字符更多、通配符更少、pattern 更长，最后才以声明顺序破同级）；`autoReview` 段只保留 `enabled`，不设 provider/model 种子值。`config/pi-permission-hard-guards.jsonc` 独立保存可由用户调整但不能被普通策略、Session grant、per-agent 规则或 reviewer 覆盖的高危 `deny`，以及 `protectedWrites` 人工写保护清单。
- `protectedWrites` 是确定性的 human-only 写路径，不属于普通策略也不是第二个授权范围：命中目标的 `write`/`edit` 与本地 `bash` 写入（redirect-out、写操作程序参数、`bash -c`/`eval` 等包装载荷中的受保护路径）一律弹出人工确认，跳过 AutoReview、yolo 与既有 Session grant，弹窗不提供「本会话允许」选项；没有可用确认界面（无 UI、子代理转发终端）时直接拒绝。读取不受影响；`ssh_bash` 等远端 shell 工具不参与本机路径保护。
- 策略默认允许常规只读与低风险工具；`web_fetch`、`ctx_fetch_and_index`、`skill_manage` 保持 `ask`（模型自选的 URL 可能外传数据，skill 写入会进入所有后续会话）；硬防御默认只保留确定性的破坏性 Shell 命令；Git 只读管道命令放行，其余非只读操作、包管理、文件/系统/网络高风险操作与 `mcp__<server>__<tool>` 调用按唯一全局 policy 判定。项目外路径不产生独立 `external_directory` 判断，只走配置中的工具、`path` 与 Bash pattern。
- `HardGuardPolicyLoader` 必须保持 global-only、无 SessionRules、无项目覆盖；唯一的组合包 hard-guards 文件不可用时 fail closed 到 deny-all，并报告配置问题。普通 policy 与 hard guard 配置不得合并成一份文件。
- 内置 AutoReview 实现位于 `src/auto-review/`；同步原 AutoReview 上游时必须从源码仓库明确 tag/commit 移植，保留 `LICENSES/pi-permission-auto-review-MIT.txt`、作者和 `docs/auto-review/UPSTREAM.md`，不得恢复顶层独立扩展、npm 预编译入口或平行 gate。
- reviewer 只能处理普通策略已判定为 `ask` 且未被 hard guard 拒绝的请求；不得绕过硬 `deny`。
- 根包必须通过 `file:./pi-permission-system` 提供运行时依赖，包装入口必须直接加载仓库源码；不得同时加载 npm 预编译入口或第二个 permission-system 实例。权限系统只能在调用时裁决，不能读写 active tool 列表（工具显隐由 `pi-tool-search` 独占管理）。
- 修改 gate、authorizer chain、子代理转发、公共 service 类型、reviewer 策略、可信证据边界、配置结构、hard-guard precedence、模型解析或 authorizer/lifecycle 注册时，必须同步更新包内 README/架构文档、配置文档、schema 和相应测试。

## 验证

- 在本目录内至少运行 `npm run typecheck`、`npm run test` 和 `npm run build`。涉及内置 AutoReview 或硬防御时，还要验证 authorizer 对普通工具与 `path` 的 `allow` / `deny` / `defer`、hard-guard precedence、未配置/未知 provider 或模型时的 `defer` 与一次性提示，以及 owner-only 持久化。