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、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 持久化。