add-coder 0.2.2 → 0.2.4

package/templates/adapters/trae/hooks/pre-tool-use.sh

@@ -1,78 +1,131 @@
 #!/bin/bash
-# pre-tool-use.sh — Claude Code PreToolUse：四路守卫
+# pre-tool-use.sh — PreToolUse §A§B（阻断模式，通用适配版）
+# §A: Bash 裸写保护 — 拦截所有绕过 IDE 追踪的文件写操作
+# §B: 源码 Plan 关联检查 — 无 Plan 的 src/**/*.ts 编辑阻断
 # 治理卡位 #4: 危险命令拦截 / 模板路径兜底 / 写入前置守卫 / 敏感文件保护
 set -euo pipefail
 
+input=$(cat)
+
+# 探测 MAGIC_DIR 和 PROJECT_DIR（兼容多种 adapter）
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
-COMMON_LIB="$HOOK_DIR/lib/common.sh"
-[ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
-
-input=$(parse_input)
-tool_name=$(json_get "$input" "tool_name")
-[ -z "$tool_name" ] && tool_name=$(echo "$input" | grep -o '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
-
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
-
-# ── ① Bash matcher: 危险命令拦截 + 终端写文件拦截 ──
-if [ "$tool_name" = "Bash" ]; then
-  cmd=$(echo "$input" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
-  # 危险命令
-  if echo "$cmd" | grep -qiE 'rm[[:space:]]+-rf[[:space:]]+/|DROP[[:space:]]+TABLE|git[[:space:]]+push[[:space:]]+--force|mkfs\.|dd[[:space:]]+if='; then
-    echo "⛔ 危险命令已被阻止: $cmd" >&2
-    exit $EXIT_BLOCK
-  fi
-  # 终端写文件拦截（含 > / >> / << heredoc / mv / touch / python -c > file）
-  if echo "$cmd" | grep -qE '(cat|echo|tee|sed[[:space:]]+-i|awk|printf|cp|mv|dd|touch)[[:space:]]*.*([>]{1,2}|[|][[:space:]]*tee|<<)'; then
-    echo "⛔ 禁止通过终端命令直接写文件: $cmd。请使用 Write/Edit/SearchReplace 工具。" >&2
-    exit $EXIT_BLOCK
+PARENT="$(dirname "$HOOK_DIR")"
+MAGIC_DIR="$(basename "$PARENT")"
+PROJECT_DIR="$PWD"
+
+# ── §A 辅助函数: 阻断日志 ──
+_log_block() {
+  local rule="$1" cmd="$2"
+  mkdir -p "$PROJECT_DIR/$MAGIC_DIR/debug-dump"
+  cat >> "$PROJECT_DIR/$MAGIC_DIR/debug-dump/stdin.log" <<BLOCKLOG
+=== $(date) [BLOCKED by §A: ${rule}] ===
+command: ${cmd:0:300}
+=== DONE ===
+BLOCKLOG
+}
+
+# ═══════════════ §A: Bash 工具写入保护 ═══════════════
+# 任何通过 Bash 修改文件内容的操作都会绕过 IDE 工具层（Write/SearchReplace），
+# 导致 Plan 关联检查、doc-format-guard、审计追踪全部失效。
+# 因此全局阻断所有可写文件的 Bash 命令，强制走 IDE 工具通道。
+command=$(echo "$input" | jq -r '.tool_input.command // empty')
+if [ -n "$command" ]; then
+
+  # 检测 1: 脚本解释器 — 可写任意文件，无法解析脚本内容做细粒度拦截
+  if echo "$command" | grep -qE '^\s*(python3?|node|ruby|perl|php)(\s|$)'; then
+    _reason="禁止通过脚本解释器直接修改文件。请使用 Write 或 SearchReplace 工具操作文件。"
+    cat >&2 <<'EOF'
+⛔ [ADD PreToolUse §A] 阻断: 禁止通过脚本解释器直接修改文件。
+
+  python/node/ruby/perl/php 可在脚本中写入任意文件，绕过:
+    · Plan 关联检查（哪个文件属于哪个 ADD Plan？）
+    · doc-format-guard（章节/占位符/禁止词校验）
+    · 审计追踪（agentAudit 无法感知 Bash 内部的文件变更）
+
+  → 请改用 Write 或 SearchReplace 工具操作文件。
+  → 如需运行构建/测试脚本，使用 npx/pnpm/npm 命令。
+EOF
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"${_reason}\"}}"
+    _log_block "脚本解释器" "$command"
+    exit 2
   fi
-  # mv 无重定向但仍操作文件
-  if echo "$cmd" | grep -qE '^[[:space:]]*mv[[:space:]]+/tmp/'; then
-    echo "⛔ 禁止通过 mv /tmp/ 绕过 IDE 工具: $cmd" >&2
-    exit $EXIT_BLOCK
+
+  # 检测 2: sed -i 原地编辑
+  if echo "$command" | grep -qE '\bsed\b.*-i'; then
+    _reason="禁止通过 sed -i 直接编辑文件。请使用 SearchReplace 工具。"
+    cat >&2 <<'EOF'
+⛔ [ADD PreToolUse §A] 阻断: 禁止通过 sed -i 原地编辑文件。
+
+  sed -i 直接写入文件，绕过 IDE 工具层的所有校验。
+  → 请改用 SearchReplace 工具。
+EOF
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"${_reason}\"}}"
+    _log_block "sed -i" "$command"
+    exit 2
   fi
-  # python/node 脚本写文件
-  if echo "$cmd" | grep -qE '(python3|python|node)[[:space:]].*[>]{1,2}'; then
-    echo "⛔ 禁止通过脚本语言直接写文件: $cmd。请使用 Write/Edit/SearchReplace 工具。" >&2
-    exit $EXIT_BLOCK
+
+  # 检测 3: 输出重定向 (>/>>) 写入文件
+  if echo "$command" | grep -qE '[>]{1,2}\s+\S'; then
+    _reason="禁止通过重定向写入文件。请使用 Write 工具。"
+    cat >&2 <<'EOF'
+⛔ [ADD PreToolUse §A] 阻断: 禁止通过重定向(>/>>)写入文件。
+
+  重定向写入绕过 IDE 工具层，变更无法追踪。
+  → 请改用 Write 工具。
+EOF
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"${_reason}\"}}"
+    _log_block "重定向" "$command"
+    exit 2
   fi
-  mark_dev_action
-  exit 0
-fi
 
-# ── ② Write/Edit matcher: 文件写入前置守卫 ──
-if [ "$tool_name" = "Write" ] || [ "$tool_name" = "Edit" ]; then
-  file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
-  [ -z "$file_path" ] && exit 0
-
-  # 检查是否写入 plans/specs/reviews 目录但无活跃 ADD Plan
-  if echo "$file_path" | grep -qE '\.(qoder|claude|add)/plans/|\.(qoder|claude|add)/specs/|\.(qoder|claude|add)/reviews/'; then
-    if type detect_active_add >/dev/null 2>&1; then
-      state=$(detect_active_add 2>/dev/null || true)
-      if [ -z "$state" ]; then
-        echo "[ADD PreToolUse] ⚠️ 正在写入 Plan/Spec/Review 文档但无活跃 ADD Plan——请先执行 add-paradigm" >&2
-      fi
-    fi
+  # 检测 4: tee / dd 写入
+  if echo "$command" | grep -qE '\btee\b|\bdd\b.*of='; then
+    _reason="禁止通过 tee/dd 写入文件。请使用 Write 或 SearchReplace 工具。"
+    cat >&2 <<'EOF'
+⛔ [ADD PreToolUse §A] 阻断: 禁止通过 tee/dd 写入文件。
+
+  → 请改用 Write 或 SearchReplace 工具。
+EOF
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"${_reason}\"}}"
+    _log_block "tee/dd" "$command"
+    exit 2
   fi
 
-  # 敏感文件保护
-  if echo "$file_path" | grep -qE '\.env$|\.env\.production$|\.env\.local$|credentials|secrets'; then
-    echo "⛔ 敏感文件受保护，禁止写入: $file_path" >&2
-    exit $EXIT_BLOCK
+  # 检测 5: cp / mv / touch — 可创建或覆盖文件
+  if echo "$command" | grep -qE '^\s*(cp|mv|touch)\b'; then
+    _reason="禁止通过 cp/mv/touch 操作文件。请使用 Write 或 SearchReplace 工具。"
+    cat >&2 <<'EOF'
+⛔ [ADD PreToolUse §A] 阻断: 禁止通过 cp/mv/touch 操作文件。
+
+  → 请改用 Write 或 SearchReplace 工具。
+EOF
+    echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"${_reason}\"}}"
+    _log_block "cp/mv/touch" "$command"
+    exit 2
   fi
 
-  mark_dev_action
+  # 放行: 构建工具(npx/pnpm/npm/yarn)、版本控制(git)、
+  #        只读操作(ls/cat/grep/find/head/tail/wc)、目录操作(mkdir/rmdir) 等
   exit 0
 fi
 
-# ── ③ Read matcher: 模板路径兜底 ──
-if [ "$tool_name" = "Read" ]; then
-  file_path=$(echo "$input" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
-  if echo "$file_path" | grep -q 'templates/'; then
-    echo "[ADD PreToolUse] 提示: 模板文件已通过 hook 预读到上下文，可跳过重复读取" >&2
-  fi
+# ═══════════════ §B: 源码 Plan 关联检查 ═══════════════
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+[ -z "$file_path" ] && exit 0
+
+if ! echo "$file_path" | grep -qE '(src/|/src/).*\.(ts|tsx)$'; then
+  exit 0
+fi
+
+MOD=$(basename "$file_path" | sed 's/\.[jt]sx\?$//')
+
+MATCHES=$(grep -rl "$MOD" "$PROJECT_DIR/$MAGIC_DIR/plans" "$PROJECT_DIR/$MAGIC_DIR/specs" "$PROJECT_DIR/$MAGIC_DIR/reports" 2>/dev/null | wc -l)
+
+if [ "$MATCHES" -gt 0 ]; then
+  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"permissionDecisionReason\":\"相关 ADD Plan 已存在\"}}"
   exit 0
 fi
 
-exit 0
+echo "⛔ 阻断: ${file_path} 无相关 ADD Plan。请先创建 Plan（plan-template / simple-plan-template）。" >&2
+echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"无相关 ADD Plan。请用 AskUserQuestion 询问用户选择 plan-template 或 simple-plan-template 创建 Plan。\"}}"
+exit 2

package/templates/adapters/trae/hooks/prompt-submit.sh

@@ -1,23 +1,20 @@
 #!/bin/bash
-# UserPromptSubmit — 触发词路由 + 模板全文注入（Claude Code 适配）
+# prompt-submit.sh — UserPromptSubmit 触发词智能路由（通用适配版）
 # 治理卡位 #3: Layer 1 精准触发 → Layer 2 阻断 → Layer 3 状态注入
 set -euo pipefail
 
-HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
-
-COMMON_LIB="$HOOK_DIR/lib/common.sh"
-[ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
-
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
-
-input=$(parse_input)
-prompt=$(echo "$input" | grep -o '"prompt"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | sed 's/.*: *"\([^"]*\)".*/\1/' || echo "")
+input=$(cat)
+prompt=$(echo "$input" | jq -r '.prompt // empty')
 [ -z "$prompt" ] && exit 0
 
-# ─── Layer 1: 精准触发词路由 + 验收幂等保护 ───
-matched=$(match_trigger "$prompt")
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$HOOK_DIR/lib/vocabulary.sh" 2>/dev/null || true
+source "$HOOK_DIR/lib/state-detect.sh" 2>/dev/null || true
+
+# ─── Layer 1: 精准 P0 触发词 ───
+matched=$(match_trigger "$prompt" 2>/dev/null || true)
 if [ -n "$matched" ]; then
+  # 验收幂等保护: 如果已验收，提示不重复
   if echo "$prompt" | grep -qiE '验收|收敛' 2>/dev/null; then
     add_state=$(detect_active_add 2>/dev/null || true)
     if [ -n "$add_state" ]; then
@@ -28,9 +25,12 @@ if [ -n "$matched" ]; then
 [ADD 验收] ⚠️ 已验收。进入 Review 模式:
   ① 重新检查 checklist [T]/[R] 项
   ② 审查 audit 记录完整性
-  ③ 如有差异 → Review 回流至 handoff（增量更新）
+  ③ 如有差异 → Review 回流至 handoff（增量更新，不覆盖已有结论）
   ④ 无差异 → 记录 'Review 已确认，无新发现'
+  ★ 同步检查: 如 checklist 有新 cuid 但 handoff 审计表缺失 → 更新 handoff ADD-7 表 + query_audit_logs 命令
 EOF
+        HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+        "$HOOK_DIR/review-checklist.sh" "$_handoff" "$_add_route" 2>/dev/null || true
         exit 0
       fi
     fi
@@ -39,40 +39,37 @@ EOF
   exit 0
 fi
 
-# ─── 开发关键词检测 ───
-if ! echo "$prompt" | grep -qiE '开发|改功能|修.?bug|加需求|新增|重构|实施|验收|继续|生成plan|生成计划'; then
+# ─── 开发关键词检测（动态加载） ───
+dev_kw=$(load_dev_keywords 2>/dev/null || true)
+if [ -z "$dev_kw" ]; then
   exit 0
 fi
 
-echo "[ADD PromptSubmit] 检测到开发关键词" >&2
+if ! echo "$prompt" | grep -qiE "$dev_kw"; then
+  exit 0
+fi
 
-# ─── Layer 2: 无活跃 ADD → 阻断 ───
+# ─── Layer 2/3: 按活跃 ADD 分流 ───
 state=$(detect_active_add 2>/dev/null || true)
 if [ -z "$state" ]; then
-  cat <<'EOF'
+  # Layer 2: 无活跃 ADD → 强制启动
+  cat >&2 <<'EOF'
 [ADD 强制规则] 检测到开发任务。你必须先执行 add-paradigm SKILL 完成 ADD 工作流:
   Step 0: 文档先行 (Plan → Review → Specs)
+  Step 1: 扩展 AgentAuditPhase
+  Step 2: 确认 agentAudit() 通道
   Step 3: 代码实现 + 审计植入
+  ...
   Step 8: 收敛判断
 如果 add-paradigm SKILL 尚未激活，请先调用它。
 EOF
   exit 2
 fi
 
-# ─── Layer 3: 有活跃 ADD → 注入状态 + 模板全文 ───
-IFS='::' read -r plan step rounds handoff add_route <<< "$state"
-cat <<EOF
-[ADD 当前状态]
-  Plan: ${plan}
-  轮次: ${rounds}
-  当前 Step: ${step}
-  handoff: ${handoff}
-EOF
-
-# 模板全文注入（tpl-injected 去重）
-TPL_SCRIPT="$HOOK_DIR/lib/preload-templates.sh"
-if [ -f "$TPL_SCRIPT" ]; then
-  bash "$TPL_SCRIPT" --full --top 5
-fi
-
+# Layer 3: 有活跃 ADD → 注入状态
+plan=$(echo "$state" | awk -F'::' '{print $1}')
+step=$(echo "$state" | awk -F'::' '{print $2}')
+rounds=$(echo "$state" | awk -F'::' '{print $3}')
+handoff=$(echo "$state" | awk -F'::' '{print $4}')
+echo "[ADD 状态] Plan: ${plan}, 轮次: ${rounds}, Step: ${step}, handoff: ${handoff}"
 exit 0

package/templates/adapters/trae/hooks/review-checklist.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# review-checklist.sh — Review 检查清单校验（Claude Code 适配）
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
+SHARED_LIB="$HOOK_DIR/../../shared/hooks-lib/common.sh"
+[ -f "$SHARED_LIB" ] && source "$SHARED_LIB"
+
+echo "[ADD ReviewChecklist] 请在提交前确认 checklist.md 全部项已勾选。"
+exit 0

package/templates/adapters/trae/hooks/session-end.sh

@@ -1,21 +1,38 @@
 #!/bin/bash
-###
- # @Author       : xiaomingming wujixmm@gmail.com
- # @Date         : 2026-07-17 13:35:03
- # @LastEditors  : xiaomingming wujixmm@gmail.com
- # @LastEditTime : 2026-07-17 13:35:04
- # @FilePath     : /add-coder/templates/adapters/claude/hooks/session-end.sh
- # @Description  : 
-### 
-# SessionEnd — Claude Code 适配（薄包装）
+# SessionEnd — 通用版（核心模板，Trae 等适配器继承）
 # 治理卡位 #2: 标记清理 + 会话审计结算 + Stop未触发兜底
 set -euo pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+COMMON_LIB="$HOOK_DIR/lib/common.sh"
+[ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
 
-# source 共享版本并自动执行 main()
-SHARED="$HOOK_DIR/lib/session-end.sh"
-if [ -f "$SHARED" ]; then
-  source "$SHARED"
+export PROJECT_DIR="$PWD"
+
+# ── ① 清理 tpl-injected 标记 ──
+project_hash=$(echo "${PROJECT_DIR:-$PWD}" | md5sum 2>/dev/null | cut -c1-8 || echo "default")
+rm -f "/tmp/add_tpl_${project_hash}" 2>/dev/null || true
+
+# ── ② 清理 dev action 标记 ──
+rm -f "/tmp/add_dev_${project_hash}" 2>/dev/null || true
+
+# ── ③ Stop 未触发兜底: 如果 dev action 标记还在，补执行 checklist 快照 ──
+if has_dev_action 2>/dev/null; then
+  echo "[ADD SessionEnd] ⚠️ 检测到 dev action 标记未清除——Stop 可能未触发验收检查" >&2
+
+  state=$(detect_active_add 2>/dev/null || true)
+  if [ -n "$state" ]; then
+    handoff=$(echo "$state" | awk -F'::' '{print $4}')
+    add_route=$(echo "$state" | awk -F'::' '{print $5}')
+    if [ -f "$handoff" ]; then
+      echo "[ADD SessionEnd] 补执行 checklist 快照（best-effort，不阻断）" >&2
+      if type check_add_completeness >/dev/null 2>&1; then
+        check_add_completeness "$handoff" "$add_route" >&2 2>/dev/null || true
+      fi
+    fi
+  fi
 fi
+
+# ── ④ 审计结算 ──
+echo "[ADD SessionEnd] 会话结束 — $(date -Iseconds)" >&2
+exit 0

package/templates/adapters/trae/hooks/subagent-guard.sh

@@ -1,36 +1,15 @@
 #!/bin/bash
-###
- # @Author       : xiaomingming wujixmm@gmail.com
- # @Date         : 2026-07-08 18:03:52
- # @LastEditors  : xiaomingming wujixmm@gmail.com
- # @LastEditTime : 2026-07-17 18:04:04
- # @FilePath     : /add-coder/templates/adapters/claude/hooks/subagent-guard.sh
- # @Description  : 
-### 
-# SubagentStart — 子代理 ADD 上下文注入（Claude Code 适配）
-# 治理卡位 #10: ADD上下文注入子agent + 审计初始化
+# SubagentStart/SubagentStop — 子代理门禁（Claude Code 适配）
 set -euo pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-export CURRENT_MAGIC=$(basename "$(dirname "$HOOK_DIR")")
-COMMON_LIB="$HOOK_DIR/lib/common.sh"
-[ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
+SHARED_LIB="$HOOK_DIR/../../shared/hooks-lib/common.sh"
+[ -f "$SHARED_LIB" ] && source "$SHARED_LIB"
 
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+input=$(parse_input)
+event=$(echo "$input" | jq -r '.hook_event_name // empty')
 
-if type detect_active_add >/dev/null 2>&1; then
-  state=$(detect_active_add 2>/dev/null || true)
-  if [ -n "$state" ]; then
-    IFS='::' read -r plan step rounds handoff add_route <<< "$state"
-    cat <<EOF
-[ADD SubagentStart] 子代理上下文注入:
-  Plan: ${plan}
-  Step: ${step}
-  轮次: ${rounds}
-  handoff: ${handoff}
-  遵循 ADD 规范，完成后请检查 checklist 对应项
-EOF
-  fi
+if [ "$event" = "SubagentStart" ]; then
+  echo "[ADD SubagentGuard] 子代理启动，请确认其遵循 ADD 规范。"
 fi
-
-exit 0
+exit 0

package/templates/adapters/trae/hooks/subagent-stop.sh

@@ -1,20 +1,47 @@
 #!/bin/bash
-###
- # @Author       : xiaomingming wujixmm@gmail.com
- # @Date         : 2026-07-17 13:35:20
- # @LastEditors  : xiaomingming wujixmm@gmail.com
- # @LastEditTime : 2026-07-17 13:35:21
- # @FilePath     : /add-coder/templates/adapters/claude/hooks/subagent-stop.sh
- # @Description  : 
-### 
-# SubagentStop — Claude Code 适配（薄包装）
+# SubagentStop — 通用版（核心模板，Trae 等适配器继承）
 # 治理卡位 #11: 子agent边界校验 + 审计聚合 + 阻断
 set -euo pipefail
 
 HOOK_DIR="$(cd "$(dirname "$0")" && pwd)"
-export PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}"
+COMMON_LIB="$HOOK_DIR/lib/common.sh"
+[ -f "$COMMON_LIB" ] && source "$COMMON_LIB"
 
-SHARED="$HOOK_DIR/lib/subagent-stop.sh"
-if [ -f "$SHARED" ]; then
-  source "$SHARED"
+export PROJECT_DIR="$PWD"
+
+input=$(cat 2>/dev/null || echo "{}")
+agent_name=$(echo "$input" | jq -r '.agent_type // .subagent_name // "unknown"' 2>/dev/null || echo "unknown")
+
+# ── ① 边界校验：检查子 agent 交付物是否超出 spec 范围 ──
+state=$(detect_active_add 2>/dev/null || true)
+if [ -z "$state" ]; then
+  echo "[ADD SubagentStop] ⚠️ ${agent_name} 已完成，但无活跃 ADD Plan 无法校验边界" >&2
+  exit 0
 fi
+
+plan_kw=$(echo "$state" | awk -F'::' '{print $1}')
+handoff=$(echo "$state" | awk -F'::' '{print $4}')
+
+echo "[ADD SubagentStop] ${agent_name} 已完成 — 关联 Plan: ${plan_kw}" >&2
+
+# 如果 handoff 中存在允许的文件清单，检查交付物是否越界
+if [ -f "$handoff" ]; then
+  deliverables=$(echo "$input" | jq -r '.deliverables // ""' 2>/dev/null || echo "")
+  if [ -n "$deliverables" ]; then
+    violations=""
+    for f in $deliverables; do
+      if ! grep -q "$f" "$handoff" 2>/dev/null; then
+        violations="${violations} $f"
+      fi
+    done
+    if [ -n "$violations" ]; then
+      echo "[ADD SubagentStop] ❌ ${agent_name} 交付物超出 spec 边界: ${violations}" >&2
+      echo "[ADD SubagentStop] 要求重做——请检查这些文件是否属于本轮 spec 范围" >&2
+      exit "${EXIT_BLOCK:-2}"
+    fi
+  fi
+fi
+
+# ── ② 审计聚合 ──
+echo "[ADD SubagentStop] ${agent_name} 边界校验通过 — $(date -Iseconds)" >&2
+exit 0