add-coder 0.1.17 → 0.2.0

package/templates/adapters/vscode/settings.json

@@ -2,10 +2,9 @@
     "mcp": {
         "servers": {
             "{{projectName}}-dev-tools": {
-                "command": "npx",
+                "command": "{{mcpServerCommand}}",
                 "args": [
-                    "tsx",
-                    "scripts/add-coder-mcp-server.ts"
+                    ".vscode/scripts/mcp-server.ts"
                 ],
                 "env": {
                     "NODE_ENV": "development"

package/templates/adapters/vscode/tasks.json

@@ -4,7 +4,7 @@
         {
             "label": "ADD: Run MCP Server",
             "type": "shell",
-            "command": "{{mcpServerCommand}} .qoder/scripts/mcp-server.ts",
+            "command": "{{mcpServerCommand}} {{magicDir}}/scripts/mcp-server.ts",
             "presentation": {
                 "reveal": "always",
                 "panel": "new"
@@ -14,7 +14,7 @@
         {
             "label": "ADD: Check Plan Exists (Pre-save)",
             "type": "shell",
-            "command": "echo 'VS Code 无原生 hook，请在保存源码前手动确认 Plan 已创建。' && ls .qoder/plans/ 2>/dev/null || echo '⚠ 未找到 .qoder/plans/ 目录'",
+            "command": "ls {{magicDir}}/plans/ 2>/dev/null || echo '⚠ 未找到 {{magicDir}}/plans/ 目录'",
             "presentation": {
                 "reveal": "silent",
                 "panel": "shared"
@@ -27,7 +27,7 @@
         {
             "label": "ADD: Checklist Audit",
             "type": "shell",
-            "command": "echo '请手动检查 .qoder/specs/ 下的 checklist.md 勾选状态'",
+            "command": "echo '请手动检查 {{magicDir}}/specs/ 下的 checklist.md 勾选状态'",
             "presentation": {
                 "reveal": "silent",
                 "panel": "shared"

package/templates/core/docs/ADD-governance-claude-code.md

@@ -0,0 +1,121 @@
+# ADD 范式在 Claude Code 上的确定性运行
+
+> **定位**：描述 ADD 范式如何通过 Claude Code 的 Hook 机制在 agent 生命周期中确定性运行。面向 add-coder 用户和贡献者，说明每个 hook 事件的治理职能和注入通道。
+> **关联文档**：[add-coder-hook-full-alignment-plan-v1](../.qoder/plans/2026-07/17/add-coder-hook-full-alignment-plan-v1.md) | [issue-6-report](../.qoder/reports/issue-6-tool-call-throttling-report.md)
+> **Hook 参考**: https://code.claude.com/docs/zh-CN/hooks
+
+---
+
+## Claude Code Hook 事件模型
+
+Claude Code 支持 17 种事件，按频率分三档：
+
+| 频率 | 事件 |
+|---|---|
+| 每会话一次 | SessionStart、SessionEnd |
+| 每轮一次 | UserPromptSubmit、Stop、StopFailure |
+| 每次工具调用 | PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、PermissionDenied |
+| 其他 | PreCompact、SubagentStart、SubagentStop、Notification、ConfigChange、WorktreeCreate/Remove |
+
+配置位置：`.claude/hooks/*.sh` + `.claude/settings.json`
+
+---
+
+## ADD 治理卡位映射
+
+```
+Claude Code Agent 生命周期          ADD 治理卡位
+─────────────────────────────      ─────────────────────
+SessionStart ─────────────────→ ① 模板索引注入 + ADD 状态恢复
+SessionEnd   ─────────────────→ ② 标记清理 + 审计结算 + Stop 兜底
+UserPromptSubmit ────────────→ ③ 触发词路由 + 模板全文注入 + 契约卡位
+PreToolUse   ─────────────────→ ④ 危险命令/模板路径兜底/写入前置守卫
+PostToolUse  ─────────────────→ ⑤ 格式化 + 文档守卫 + 审计落库
+PostToolUseFailure ───────────→ ⑥ 失败等价审计(ADD-6) + 429 降级
+Stop         ─────────────────→ ⑦ 验收检查 + devlog + 阻断
+StopFailure  ─────────────────→ ⑧ 紧急审计转储 + 异常标记
+PreCompact   ─────────────────→ ⑨ ADD 状态保存 + 恢复清单导出
+SubagentStart ────────────────→ ⑩ 子 agent 上下文传递 + 审计初始化
+SubagentStop ─────────────────→ ⑪ 子 agent 结果校验 + 审计聚合
+Notification ─────────────────→ ⑫ 开发提醒/Token 预警
+PermissionRequest ────────────→ ⑬ 分级决策(allow/deny/ask)
+PermissionDenied ─────────────→ ⑭ 拒绝原因记录 + 替代方案
+```
+
+---
+
+## 注入通道
+
+Claude Code 的注入通道为 **stdout → additionalContext**——hook 脚本的 stdout 输出会自动作为额外上下文注入模型。
+
+| 注入场景 | 触发事件 | 注入内容 | Token 成本 |
+|---|---|---|---|
+| 会话启动 | SessionStart | 模板索引（13 个文件名 + 一行用途） | ~500 token |
+| 开发触发 | UserPromptSubmit（首次命中 ADD 关键词） | 13 个模板全文 | 依模板总量 |
+| 去重 | UserPromptSubmit（同会话后续命中） | 短路跳过（tpl-injected 标记文件） | 0 |
+
+---
+
+## 完整生命周期数据流
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   Claude Code 会话                     │
+├──────────────────────────────────────────────────────┤
+│                                                      │
+│  SessionStart                                        │
+│  ├─ detect_active_add() 扫描 plans/ 恢复 ADD 状态    │
+│  ├─ preload-templates.sh --index                     │
+│  └─ stdout → additionalContext 注入                  │
+│        │                                             │
+│        ▼                                             │
+│  UserPromptSubmit                                    │
+│  ├─ match_trigger() 检测 ADD 触发词                  │
+│  ├─ 首次命中 → preload-templates.sh --full            │
+│  ├─ touch tpl-injected 标记                          │
+│  └─ 同会话二次命中 → 短路                             │
+│        │                                             │
+│        ▼                                             │
+│  ┌──── 工具调用循环 ────┐                            │
+│  │ PreToolUse            │                            │
+│  │ ├─ Bash → 危险命令拦截│                            │
+│  │ ├─ Write → 写入前置守卫│                           │
+│  │ └─ Read → 模板路径兜底 │                           │
+│  │       │               │                            │
+│  │   [工具执行]           │                            │
+│  │       │               │                            │
+│  │ PostToolUse            │                            │
+│  │ ├─ Edit → 格式化+文档守卫│                         │
+│  │ └─ record_dev_operation│                           │
+│  └────────────────────────┘                           │
+│        │                                             │
+│        ▼                                             │
+│  Stop（可阻断）                                       │
+│  ├─ checklist 验证 + tsc + RAHS                      │
+│  ├─ 不通过 → exit 2 阻断                             │
+│  └─ 通过 → devlog + exit 0                           │
+│        │                                             │
+│        ▼                                             │
+│  PreCompact                                          │
+│  ├─ 保存 ADD 状态到标记文件                           │
+│  └─ rm tpl-injected（允许重注）                       │
+│        │                                             │
+│        ▼                                             │
+│  SessionEnd                                          │
+│  ├─ rm tpl-injected 清理                              │
+│  ├─ query_audit_logs 汇总                             │
+│  └─ Stop 未触发兜底                                   │
+│                                                      │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Claude Code 独有治理能力
+
+| 事件 | 能力 |
+|---|---|
+| PermissionRequest | 自动放行 Read/Grep/Glob，拦截 rm -rf/DROP TABLE |
+| PermissionDenied | 记录拒绝原因 + 建议替代方案 |
+| StopFailure | 异常退出前紧急 dump State |
+| ConfigChange | settings.json 热重载 + 变更审计 |

package/templates/core/docs/ADD-governance-codex.md

@@ -0,0 +1,75 @@
+# ADD 范式在 Codex 上的确定性运行
+
+> **定位**：描述 ADD 范式如何通过 Codex 的 Hook 机制在 agent 生命周期中确定性运行。
+> **关联文档**：[add-coder-hook-full-alignment-plan-v1](../.qoder/plans/2026-07/17/add-coder-hook-full-alignment-plan-v1.md)
+> **Hook 参考**: https://www.runoob.com/codex/codex-hooks.html | Codex 设置 → 导入其他 agent 配置
+
+---
+
+## Codex Hook 事件模型
+
+Codex 支持 6 种 Hook 事件：
+
+| 频率 | 事件 |
+|---|---|
+| 每会话一次 | SessionStart |
+| 每轮一次 | UserPromptSubmit、Stop |
+| 每次工具调用 | PreToolUse、PostToolUse |
+| 异步 | Notification |
+
+配置位置：项目级 `.codex/hooks.json`（或 `~/.codex/hooks.json` 全局）
+
+**关键差异**：Codex 不支持 SessionEnd / PreCompact / SubagentStart / SubagentStop / PostToolUseFailure / StopFailure。但 **支持导入 Claude Code Hook 配置**（设置 → 导入其他 agent 配置 → 选择 Claude Code），可通过 Claude 通道获得完整 14 事件体系。`npx add-coder init --adapter=codex` 同步产出 `.claude/` 目录。
+
+---
+
+## ADD 治理卡位映射
+
+```
+Codex Agent 生命周期                ADD 治理卡位
+─────────────────────────────      ─────────────────────
+SessionStart ─────────────────→ ① 模板索引注入 + ADD 状态恢复
+UserPromptSubmit ────────────→ ③ 触发词路由 + 模板全文注入
+PreToolUse   ─────────────────→ ④ 危险命令/模板路径兜底/写入前置守卫
+PostToolUse  ─────────────────→ ⑤ 格式化 + 文档守卫 + 审计落库
+Stop         ─────────────────→ ⑦ 验收检查 + devlog + 阻断
+Notification ─────────────────→ ⑫ 开发提醒/Token 预警
+```
+
+> **Codex 端不支持的卡位**：②（SessionEnd）→ 无 hookpoint；⑥（PostToolUseFailure）→ 无 hookpoint；⑧⑨⑩⑪⑬⑭⑮ → 无 hookpoint。
+
+---
+
+## 注入通道
+
+Codex 的注入通道为 **stdout**（与 Claude Code 兼容）。Codex 支持导入 Claude Code Hook 配置，可通过双通道架构获得完整治理：
+
+- **Codex 原生**（6 事件，`.codex/hooks.json` → `.codex/hooks/xxx.sh`）
+- **Claude Code 导入**（14 事件，`.claude/settings.json` → `.claude/hooks/xxx.sh`）——Codex 设置中开启「导入其他 agent 配置」即可。同一套脚本，两通道共享，脚本内置幂等保护。
+
+```
+npx add-coder init --adapter=codex
+        │
+        ├──→ .codex/hooks.json （6 事件 → .codex/hooks/xxx.sh）
+        ├──→ .codex/settings.json
+        └──→ .claude/ ★ （含完整 14 事件 hooks + settings.json + mcp.json）
+```
+
+| 注入场景 | 触发事件 | 注入内容 | 通道 |
+|---|---|---|---|
+| 会话启动 | SessionStart | 模板索引 + ADD 状态 | stdout |
+| 开发触发 | UserPromptSubmit | 13 个模板全文 | stdout |
+
+---
+
+## 端差异汇总
+
+| 维度 | Codex | Claude Code |
+|---|---|---|
+| 事件数 | 0 (原生) / 14 (导入 Claude) | 17 |
+| 配置格式 | `.codex/hooks.json` | `.claude/settings.json` |
+| Claude Hook 导入 | ✅ 原生支持（导入其他 agent 配置） | — |
+| 全局 Hook | `~/.codex/hooks.json` | `~/.claude/settings.json` |
+| SessionEnd | ❌ | ✅ |
+| PreCompact | ❌ | ✅ |
+| 权限系统 | PreToolUse 可阻断 | PermissionRequest/Denied |

package/templates/core/docs/ADD-governance-qoder-cn.md

@@ -0,0 +1,99 @@
+# ADD 范式在 Qoder CN 上的确定性运行
+
+> **定位**：描述 ADD 范式如何通过 Qoder CN 的 Hook 机制在 agent 生命周期中确定性运行。
+> **关联文档**：[add-coder-hook-full-alignment-plan-v1](../.qoder/plans/2026-07/17/add-coder-hook-full-alignment-plan-v1.md)
+> **Hook 参考**: https://help.aliyun.com/zh/lingma/qoder-cn-update-log
+
+---
+
+## Qoder CN Hook 事件模型
+
+Qoder CN v1.7.0（2026-07-15）升级至 30+ 事件。以下为 ADD 治理覆盖的 10 个核心事件：
+
+| 频率 | 事件 |
+|---|---|
+| 每会话一次 | SessionStart（v1.7.0 新增）、SessionEnd（v1.7.0 新增） |
+| 每轮一次 | UserPromptSubmit、Stop |
+| 每次工具调用 | PreToolUse、PostToolUse、PostToolUseFailure |
+| 其他 | SubagentStart（v1.7.0 新增）、SubagentStop（v1.7.0 新增）、Notification（v1.7.0 新增） |
+
+配置位置：`.qoder/hooks/*.sh` + `.qoder/settings.json`
+
+**关键差异**：Qoder CN 不支持 PreCompact / PermissionRequest / PermissionDenied / StopFailure / ConfigChange / Worktree——这些 Claude Code 独有事件在 Qoder 端无对应 hookpoint，相关脚本不编译到 Qoder adapter。
+
+---
+
+## ADD 治理卡位映射
+
+```
+Qoder CN Agent 生命周期             ADD 治理卡位
+─────────────────────────────      ─────────────────────
+SessionStart ─────────────────→ ① 模板索引注入 + ADD 状态恢复
+SessionEnd   ─────────────────→ ② 标记清理 + 审计结算 + Stop 兜底
+UserPromptSubmit ────────────→ ③ 触发词路由 + 模板全文注入（增量插入 Layer 1/2/3）
+PreToolUse   ─────────────────→ ④ 危险命令/模板路径兜底/写入前置守卫
+PostToolUse  ─────────────────→ ⑤ 格式化 + 文档守卫 + 审计落库
+PostToolUseFailure ───────────→ ⑥ 失败等价审计(ADD-6) + 429 降级
+Stop         ─────────────────→ ⑦ 验收检查 + devlog + 阻断（RAHS 不可用时降级为基础检查）
+SubagentStart ────────────────→ ⑩ 子 agent 上下文传递 + 审计初始化
+SubagentStop ─────────────────→ ⑪ 子 agent 结果校验 + 审计聚合
+Notification ─────────────────→ ⑫ 开发提醒/Token 预警
+```
+
+> **Qoder 端不支持的卡位**：⑧（StopFailure）→ 无 hookpoint；⑨（PreCompact）→ 无 hookpoint；⑬⑭（权限）→ 由 Qoder IDE 内置权限系统处理。
+
+---
+
+## 注入通道
+
+Qoder CN 的注入通道为 **stderr → 下一轮 system prompt 注入**。这与 Claude Code 的 stdout 直接注入不同——stderr 内容不会即时进入当前轮上下文，而是在模型下一轮响应前由 Qoder IDE 自动注入 system prompt。
+
+| 注入场景 | 触发事件 | 注入内容 | 通道 |
+|---|---|---|---|
+| 会话启动 | SessionStart | 模板索引 + ADD 状态 | stderr → 下一轮 system prompt |
+| 开发触发 | UserPromptSubmit（首次命中） | 13 个模板全文 | stderr → 下一轮 system prompt |
+| 去重 | UserPromptSubmit（同会话后续命中） | 短路跳过 | — |
+
+**重要约束**：Qoder 端 `prompt-submit.sh` 已有 73 行完善的触发词路由系统（Layer 1 精准 P0 触发词 → Layer 2 开发关键词检测 → Layer 3 活跃 ADD 状态注入 + 验收幂等保护）。模板全文注入逻辑以**增量方式**插入 Layer 2 之后，禁止覆盖现有分流逻辑。
+
+---
+
+## 端差异汇总
+
+| 维度 | Claude Code | Qoder CN |
+|---|---|---|
+| 注入通道 | stdout → additionalContext | stdout → additionalContext（JSON hookSpecificOutput） |
+| PreCompact | ✅ | ❌ |
+| 权限系统 | PermissionRequest/Denied hook | IDE 内置权限弹窗 |
+| StopFailure | ✅ | ❌ |
+| 独有特性 | ConfigChange / Worktree | asyncRewake（v1.7.0）+ if 条件匹配 |
+
+---
+
+## 调试与排错
+
+### Hook 日志路径
+
+Qoder CN IDE 的 hook 执行遥测日志位于 `~/.qoder-cn/logs/latest/`。当 hook 脚本通过 stdout 输出 `hookSpecificOutput.additionalContext` JSON 时，IDE 会在日志中记录：
+
+```
+UserPromptSubmit hook additional context: ADD workflow active. ...
+```
+
+这是验证 additionalContext 是否成功注入的**唯一确定性证据**——日志有这行 = 注入成功。
+
+### 常见排错清单
+
+| 现象 | 根因 | 修复 |
+|---|---|---|
+| hook 注册了但不执行 | `command` 缺少 `bash` 前缀 | settings.json 所有 command 加 `bash` 前缀 |
+| hook 执行但 stdout 未被注入 | 纯文本不被 IDE 解析为 additionalContext | 改用 JSON 格式：`{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}` |
+| 脚本 exit 0 但没有输出 | `VOCABULARY_FILE` 用了 `$PWD`，hook 运行时 cwd 不是项目根 | 改为 `${PROJECT_DIR:-$PWD}` |
+| `detect_active_add` 返回空 | `PROJECT_DIR` 在 `source lib/vocabulary.sh` 之后才设置 | `export PROJECT_DIR` 移到所有 `source` 语句之前 |
+| additionalContext 有时注入有时不注入 | 注入代码在 Layer 1 之后——P0 触发词匹配后 `exit 0` 跳过了注入 | 将 additionalContext 注入移到 Layer 1 之前 |
+
+### 关键设计决策
+
+1. **`PROJECT_DIR` 必须最先设置**：所有 `source lib/*.sh` 之前，因为被 source 的脚本可能依赖 `${PROJECT_DIR}` 定位文件
+2. **additionalContext 放在入口最前**：在任何 `exit` 分支之前，确保所有代码路径都能注入上下文
+3. **Stop/PreToolUse 不用 JSON**：中断/阻断类输出走 stderr 纯文本，不走 stdout JSON

package/templates/core/docs/ADD-governance-trae.md

@@ -0,0 +1,63 @@
+# ADD 范式在 Trae 上的确定性运行
+
+> **定位**：描述 ADD 范式如何通过 Trae 的 Hook 机制在 agent 生命周期中确定性运行。
+> **关联文档**：[add-coder-hook-full-alignment-plan-v1](../.qoder/plans/2026-07/17/add-coder-hook-full-alignment-plan-v1.md)
+> **Hook 参考**: https://docs.trae.cn/ide_automate-actions-with-hooks | https://docs.trae.cn/ide_hook-configuration-reference
+
+---
+
+## Trae Hook 事件模型
+
+Trae v3.3.66（2026-06-12）支持 6 种 Hook 事件：
+
+| 频率 | 事件 |
+|---|---|
+| 每会话一次 | SessionStart |
+| 每轮一次 | UserPromptSubmit、Stop |
+| 每次工具调用 | PreToolUse、PostToolUse |
+| 异步 | Notification |
+
+配置位置：项目级 `hooks.json`（通过 设置 > Hooks 管理，或直接编辑 JSON 文件）
+
+**关键差异**：Trae 不支持 SessionEnd / PreCompact / SubagentStart / SubagentStop / PostToolUseFailure / StopFailure。但 **支持导入 Claude Code Hook 配置**（`.claude/settings.json`），可通过 Claude 通道获得完整 14 事件体系。`npx add-coder init --adapter=trae` 同步产出 `.claude/` 目录。
+
+---
+
+## ADD 治理卡位映射
+
+```
+Trae Agent 生命周期                ADD 治理卡位
+─────────────────────────────      ─────────────────────
+SessionStart ─────────────────→ ① 模板索引注入 + ADD 状态恢复
+UserPromptSubmit ────────────→ ③ 触发词路由 + 模板全文注入
+PreToolUse   ─────────────────→ ④ 危险命令/模板路径兜底/写入前置守卫
+PostToolUse  ─────────────────→ ⑤ 格式化 + 文档守卫 + 审计落库
+Stop         ─────────────────→ ⑦ 验收检查 + devlog + 阻断
+Notification ─────────────────→ ⑫ 开发提醒/Token 预警
+```
+
+> **Trae 端不支持的卡位**：②（SessionEnd）→ 无 hookpoint；⑥（PostToolUseFailure）→ 无 hookpoint；⑧⑨⑩⑪⑬⑭⑮ → 无 hookpoint。
+
+---
+
+## 注入通道
+
+Trae 的注入通道为 **stdout**（与 Claude Code 兼容）。Trae 支持导入 Claude Code Hook 配置，因此 `prompt-submit.sh` 和 `session-start.sh` 的 stdout 输出方式与 Claude Code 端一致。
+
+| 注入场景 | 触发事件 | 注入内容 | 通道 |
+|---|---|---|---|
+| 会话启动 | SessionStart | 模板索引 + ADD 状态 | stdout |
+| 开发触发 | UserPromptSubmit | 13 个模板全文 | stdout |
+
+---
+
+## 端差异汇总
+
+| 维度 | Trae | Claude Code |
+|---|---|---|
+| 事件数 | 0 (原生) / 14 (导入 Claude) | 17 |
+| 配置格式 | `hooks.json` | `.claude/settings.json` |
+| Claude Hook 导入 | ✅ 原生支持 | — |
+| SessionEnd | ❌ | ✅ |
+| PreCompact | ❌ | ✅ |
+| 权限系统 | 无 hookpoint | PermissionRequest/Denied |

package/templates/core/docs/ADD-governance-vscode-copilot.md

@@ -0,0 +1,132 @@
+# ADD 范式在 VS Code Copilot 上的确定性运行
+
+> **定位**：描述 ADD 范式如何通过 VS Code Copilot 的 Agent Hook 机制在 agent 生命周期中确定性运行。
+> **关联文档**：[add-coder-hook-full-alignment-plan-v1](../.qoder/plans/2026-07/17/add-coder-hook-full-alignment-plan-v1.md) | [issue-6-report](../.qoder/reports/issue-6-tool-call-throttling-report.md)
+> **Hook 参考**: https://docs.github.com/zh/copilot/concepts/agents/hooks | https://vscode.js.cn/docs/agent-customization/hooks
+> **VS Code 版本要求**: 1.127+（Agent Hook 预览），1.129+（Agent Host 架构，支持 `.claude/settings.json`）
+
+---
+
+## VS Code Copilot Hook 事件模型
+
+VS Code Copilot 支持 10 种 Agent Hook 事件（官方 8 + Cloud Agent 2）：
+
+| 频率 | 事件 |
+|---|---|
+| 每会话一次 | **SessionStart**、**SessionEnd** |
+| 每轮一次 | **UserPromptSubmit**、**Stop** |
+| 每次工具调用 | **PreToolUse**、**PostToolUse** |
+| 子 agent | **SubagentStart**、**SubagentStop** |
+| 其他 | **PreCompact**、errorOccurred（Cloud Agent 专属） |
+
+配置位置：`.github/hooks/*.json`（JSON 格式，`command` 字段指向 shell 脚本）
+
+**关键差异 vs Claude Code**：不支持 PostToolUseFailure / StopFailure / Notification / PermissionRequest。但 **VS Code 1.129+ Agent Host 同时读取 `.claude/settings.json`**，`npx add-coder init --adapter=vscode` 会同步产出 `.claude/` 目录，`.github/hooks/*.json` 的 `command` 统一指向 `.claude/hooks/xxx.sh`——双通道共享同一套完整脚本。
+
+---
+
+## ADD 治理卡位映射
+
+```
+VS Code Copilot Agent 生命周期       ADD 治理卡位
+─────────────────────────────      ─────────────────────
+SessionStart ─────────────────→ ① 模板索引注入 + ADD 状态恢复
+SessionEnd   ─────────────────→ ② 标记清理 + 审计结算 + Stop 兜底
+UserPromptSubmit ────────────→ ③ 触发词路由 + 模板全文注入
+PreToolUse   ─────────────────→ ④ 危险命令/模板路径兜底/写入前置守卫
+PostToolUse  ─────────────────→ ⑤ 格式化 + 文档守卫 + 审计落库
+Stop         ─────────────────→ ⑦ 验收检查 + devlog + 阻断
+PreCompact   ─────────────────→ ⑨ ADD 状态保存 + 恢复清单导出
+SubagentStart─────────────────→ ⑩ ADD 上下文注入子 agent + 审计初始化
+SubagentStop ─────────────────→ ⑪ 子 agent 结果校验 + 审计聚合
+errorOccurred ────────────────→ ⑮ 错误分类 + 429 降级 + 审计（Cloud Agent 独有）
+```
+
+> **VS Code Copilot 端不支持的卡位**：⑥→ 合入 errorOccurred；⑧ → 无 hookpoint；⑫ → 无 hookpoint；⑬⑭ → IDE 内置处理。
+
+---
+
+## 注入通道
+
+VS Code Copilot 的注入通道为 **`.github/hooks/*.json` 的 `command` stdout**。
+
+VS Code 1.129+ 的 Agent Host 架构让同一项目支持多 Agent 并行运行——Copilot、Claude Code 各走各的通道：
+
+| 通道 | 配置位置 | 脚本路径 | 说明 |
+|---|---|---|---|
+| **VS Code 原生** | `.github/hooks/*.json` | `.claude/hooks/xxx.sh` | 10 个 JSON 文件，command 指向完整 Claude 脚本 |
+| **Agent Host (Claude)** | `.claude/settings.json` | `.claude/hooks/xxx.sh` | 同一套脚本，Claude Code agent 直接读取 |
+
+```
+npx add-coder init --adapter=vscode
+        │
+        ├──→ .github/hooks/*.json （10 个，→ .claude/hooks/xxx.sh）
+        ├──→ .vscode/settings.json （MCP 配置）
+        ├──→ .vscode/hooks/lib/ （共享库）
+        └──→ .claude/ ★ （Agent Host 双通道，含完整 hooks + settings.json + mcp.json）
+```
+
+| 注入场景 | 触发事件 | 注入内容 | 配置 |
+|---|---|---|---|
+| 会话启动 | SessionStart | 模板索引 | `session-start.json` → `.claude/hooks/lib/preload-templates.sh --index` |
+| 开发触发 | UserPromptSubmit | 13 个模板全文 | `user-prompt-submit.json` → `.claude/hooks/lib/preload-templates.sh --full --top 5 --mark` |
+
+---
+
+## 路径约定
+
+VS Code Copilot hooks 必须位于 **项目根目录** 的 `.github/hooks/` 下。`npx add-coder init --adapter vscode` 会将 JSON 文件分发到此路径，而非 `.vscode/` 子目录。
+
+**Issue #6 背景**：本端的 429 并发问题是最初触发源。轮次 1 优先交付 `session-start.json` + `user-prompt-submit.json` 两个文件，仅这两个 JSON 即可消灭模板读取风暴（429 不再触发）。
+
+---
+
+## 端差异汇总
+
+| 维度 | VS Code Copilot | Claude Code |
+|---|---|---|
+| 配置格式 | `.github/hooks/*.json` | `.claude/settings.json` |
+| 注入通道 | JSON command stdout | stdout → additionalContext |
+| 脚本路径 | `.claude/hooks/xxx.sh`（与 Claude 共享） | `.claude/hooks/xxx.sh` |
+| 独有事件 | errorOccurred | PermissionRequest/Denied / StopFailure / Notification / PostToolUseFailure |
+| 子 agent 启动 | ✅ SubagentStart | ✅ SubagentStart |
+| Agent Host 双通道 | ✅ `.claude/` 同步产出 | — |
+
+---
+
+## 自定义 Hook 源切换
+
+VS Code Copilot 的 `.github/hooks/*.json` 默认指向 `.vscode/hooks/xxx.sh`（VS Code 原生完整脚本）。项目同时产出 `.claude/` 目录（含 Claude Code 完整 hook 体系 + settings.json），两套体系可切换。
+
+### 两套体系对比
+
+| 维度 | `.vscode/hooks/`（默认） | `.claude/hooks/`（备选） |
+|---|---|---|
+| 适配 IDE | VS Code Copilot | Claude Code（Agent Host / CLI） |
+| 事件覆盖 | 10 个（VS Code 全事件） | 14 个（Claude 全事件，含 Notification/PermissionRequest/StopFailure） |
+| 环境变量 | `$PWD`（VS Code cwd=项目根） | `$CLAUDE_PROJECT_DIR` |
+| 退出码阻断 | ✅ exit 2（与 Claude 相同） | ✅ exit 2 |
+| 上下文注入 | stdout 纯文本（VS Code 格式） | stdout → additionalContext（Claude 格式） |
+| 共享 lib | ✅ `hooks/lib/common.sh` | ✅ `hooks/lib/common.sh` |
+| 治理能力 | 完整四路守卫 + 验收阻断 + 审计 | 完整四路守卫 + 验收阻断 + 审计（与 VS Code 版同等） |
+
+> **两套实现代码质量同等，能力完整，差异仅在于环境变量和输出格式。**
+
+### 切换方式
+
+编辑 `.github/hooks/` 下的任意 JSON 文件，将 `bash` 字段中的路径从 `.vscode/hooks/` 改为 `.claude/hooks/` 即可：
+
+```json
+// 默认（VS Code 原生，推荐）
+"bash": "bash .vscode/hooks/pre-tool-use.sh"
+
+// 切换为 Claude Code 体系（如果同时使用 Claude Code 并希望统一脚本）
+"bash": "bash .claude/hooks/pre-tool-use.sh"
+```
+
+**切换场景建议**：
+- 只用 VS Code Copilot → 保持默认 `.vscode/hooks/`
+- VS Code + Claude Code 混用 → 切到 `.claude/hooks/` 统一脚本（Copilot 会同时加载两套来源，但脚本幂等）
+- 只用 Claude Code CLI → 不需要改 JSON，直接走 `.claude/settings.json`
+
+---