docs: 拆分 AGENTS.md，根文件只保留全局规则

根 AGENTS.md 从约 78KB 压缩到约 10KB，避免作为常驻规则加载时被截断：
只保留仓库定位、扩展清单、跨扩展硬规则与通用验证命令。各扩展的维护
约定与验证命令移入对应目录的 AGENTS.md（新增 extensions/AGENTS.md 承载
系统提示词与根目录 TS/LSP 约定），上游来源记录统一放进各目录的中文
UPSTREAM.md，并补齐 pi-permission-system 与 pi-rtk-optimizer 的来源记录。

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

pi-subagents/AGENTS.md

@@ -1,3 +1,16 @@
+# my-pi 维护约定（优先于下文上游约定）
+
+- 扩展入口是 `pi-subagents/src/index.ts`，测试保留在该目录的 `test/`，来源记录是 `pi-subagents/UPSTREAM.md`。
+- 同步上游必须从明确 tag/commit 移植并保留 README、CHANGELOG、SECURITY、作者和 LICENSE；不得导入嵌套 `.git`、上游 `.pi` 状态、`node_modules`、覆盖率或构建产物。
+- 根包必须通过 `file:./pi-subagents` 提供运行时依赖，并只通过 `extensions/subagents.ts` wrapper 直接加载仓库源码；不得绕过 wrapper 直接列出上游入口，不得同时安装或加载 npm 预编译入口，也不得把 Pi host runtime 作为组合包开发依赖带入根安装。3 个根编排工具由 Tool Search 的 `subagents` 组按需加载。
+- 子会话必须在 `bindExtensions()` 前注册到 `pi-permission-system` 的 process-global child registry，并在真实 dispose 时清理；resume、并发和嵌套 Agent 必须维持正确 parent/child session identity。
+- `extensions/subagents.ts` 是组合包配置入口：它只能把组合包内权威 `extensions/permission-system.ts` 的 canonical absolute path 作为 mandatory extension 注入。Agent frontmatter 的 `extensions: false`、`isolated` 和 `exclude_extensions` 均不得移除该 lifecycle；路径缺失、被同名其他路径冒充或 reload 后未精确命中必须在创建 AgentSession 前 fail-closed。
+- mandatory extension 只强制绑定 handlers，不自动开放它注册的工具；工具可见性仍由 Agent 的正常 extensions/tools 策略决定。mandatory 列表不得从 Agent Markdown 或项目配置读取。
+- 三个 my-pi 扩展选项必须保持 opt-in 且上游兼容，不传时 `buildAgentPrompt` 逐字节维持上游行为：`basePrompt?: () => string | undefined`（返回非空串时替代父提示词嵌入，省略 `<sub_agent_context>` 与 replace 头，保留环境/worktree/custom 分区与 extras，`<active_agent>` tag 仍恰好一个）；`bundledAgentsDir?: string`（目录下 `*.md` 经现有 parser 加载为内置 Agent，替换同名嵌入默认项、排序确定性，标记 `isDefault` 无 `source`/`sourcePath`，优先级 embedded < bundled < global < workspace < project）；`excludedExtensionPaths?: readonly string[]`（canonical 化后从每个子会话加载扩展中移除，无论 frontmatter，与 mandatory 路径重叠必须 fail closed）。组合包由 `extensions/subagents.ts` 注入 `config/prompt/subagent/` preamble 与 agents 目录并排除 `pi-ask-user`。
+- `ask` 可由 auto-review 明确 `allow` 时自动批准，包括路径请求；reviewer `defer` 或异常必须转发父会话人工 authority，不得因子会话无 UI 静默放宽。父模型生成的子 Agent prompt 不得伪装成人类直接授权证据。
+- 子 Agent 转发的 access facts 必须先由根 authority 的 `SessionRules` 匹配；父会话 whole-session grant 可覆盖语义一致的后代操作，普通单次批准不得复制为可重复消费的子 Agent grant。auto-review 必须运行在根会话并只使用根 transcript 的可信用户证据。
+- 修改 Agent lifecycle、权限桥接、tool/extension scope、resume、nested agents 或 session persistence 时，必须同步包内 README、CHANGELOG、测试，并运行 `npm run lint`、`npm run typecheck`、`npm run test` 和 `npm run build`。
+
 # Development Rules
 
 ## Conversational Style

pi-subagents/UPSTREAM.md

@@ -13,4 +13,4 @@
 
 初始导入保留了上游 TypeScript 源码、测试、示例、文档、媒体、包元数据和许可证。上游 `.github/` 自动化与本地 `.pi/` 状态有意未导入。
 
-源码包含在根包中，并通过根 `file:./pi-subagents` 依赖安装，而宿主自有的 `extensions/subagents.ts` wrapper 当前不由根 `pi.extensions` 默认加载。本地快照新增了文档化的权限子会话生命周期桥接、根 authority 转发身份、活跃 Agent 身份，以及宿主自有的精确路径 mandatory extension 策略。组合包 wrapper 保护 `extensions/permission-system.ts` 免受 Agent 控制的扩展过滤，并在该入口不可用时 fail closed。根编排工具归入 Tool Search 已提交的 `subagents` 分组，Pi host peer 标记为 optional，以免组合包安装第二套 Pi runtime。
+源码包含在根包中，通过根 `file:./pi-subagents` 依赖安装，并由宿主自有的 `extensions/subagents.ts` wrapper 经根 `pi.extensions` 默认加载。本地快照新增了文档化的权限子会话生命周期桥接、根 authority 转发身份、活跃 Agent 身份，以及宿主自有的精确路径 mandatory extension 策略。组合包 wrapper 保护 `extensions/permission-system.ts` 免受 Agent 控制的扩展过滤，并在该入口不可用时 fail closed。另新增三个 opt-in 扩展选项（`basePrompt`、`bundledAgentsDir`、`excludedExtensionPaths`，经 `createPiSubagentsExtension` → `AgentManager` → agent-runner → `buildAgentPrompt` 透传），不传时保持上游逐字节行为。根编排工具归入 Tool Search 已提交的 `subagents` 分组，Pi host peer 标记为 optional，以免组合包安装第二套 Pi runtime。