@michaelxwb/code-flow 0.6.2 → 0.6.4

package/src/adapters/opencode/commands/cf-task/start.md

@@ -10,7 +10,8 @@ description: 激活子任务并开始编码
 ## 输入
 
 - `/cf-task:start <file> TASK-001` — 激活指定文件中的单个子任务
-- `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务
+- `/cf-task:start <file>` — 激活文件内所有可执行的 draft 子任务；批次内独立任务默认并行派发子 agent
+- `/cf-task:start <file> --serial` — 整文件模式强制串行执行，不建 worktree
 
 其中 `<file>` 为 `.code-flow/tasks/` 下的文件名，可省略日期目录前缀和 `.md` 后缀。
 
@@ -27,8 +28,8 @@ description: 激活子任务并开始编码
 用 Read 读取任务文件，定位 `## TASK-xxx` 段落：
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
-- `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
+- `in-progress` → 校验现有 marker 的需求目录、TASK-ID 与 Context；匹配且为 active 才继续步骤 2，跳过重复 Start。paused/blocked 先解除原因并调用 resume；marker 缺失或不匹配先 doctor，不能仅改 Markdown。
+- `done` / `verified` → 实现已完成；done 的 E2E 可为 e2e_deferred，转 verify-e2e 终验。发现缺口时报告并显式重新规划修复任务，不直接把终态改成 in-progress。
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -37,7 +38,7 @@ description: 激活子任务并开始编码
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
-- 所有依赖必须为 `done`
+- 所有依赖必须为 `done` 或 `verified`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
 **验收契约检查**：
@@ -65,12 +66,12 @@ description: 激活子任务并开始编码
 
 在改状态或生产代码前，顺序固定且不得跳步：
 
-1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/pending/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
-3. 只有前两步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+3. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令（E2E 只登记，不在本阶段执行）
+5. 先编写验收测试（E2E 只编写并登记）。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败。E2E 场景不执行 RED，登记为 e2e_deferred 留给 verify-e2e
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -88,11 +89,10 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
-2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
-3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
-4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
-5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
+1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
+2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
+3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
+4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
 
 ### 3.5 TASK-bound Spec Session
 
@@ -110,16 +110,18 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
 - `manual` 场景已有用户确认和可复核记录
 
-满足后：
-1. 用 Edit 更新 Status 为 `done`
-2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
-3. 更新文件头 `Updated` 日期
-4. 输出：`TASK-xxx 已完成`
+满足后，执行唯一收尾入口：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate（acceptance 场景 + spec verifiers + 全量 validation.yml，含 heavy）；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 
@@ -185,14 +187,81 @@ Spec 同步提示:
   - TASK-004: #NOTES 未解决
   - TASK-005: 依赖 TASK-004 (blocked)
 
-开始执行...
+开始执行（批次内默认并行派发子 agent，预检失败自动回退串行）...
 ```
 
-### 4. 按序执行
+### 4. 执行批次
+
+对每个批次执行；批次内仅 1 个 TASK、传入 `--serial`、或并行预检失败时，走 4.6 串行回退。
+
+#### 4.1 并行预检与 worktree 准备
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
+  --task-file "<任务文件相对路径>" --tasks TASK-001,TASK-003 --json
+```
+
+- 返回 `{"ok": true, "run_id": ..., "worktrees": [...]}` 才可并行；`ok: false` 时打印 `code`/`message` 并回退串行，禁止手工建 worktree/分支。
+- 预检内容：git 仓库、`.code-flow/.gitignore` 含 `worktrees/`、主 worktree 无 active marker、tracked 工作区干净。命令会自动提交仅位于当前需求目录内的流程产物（任务文件等）；需求目录以外存在未提交改动时拒绝并行，提示用户先提交或收起。
+
+#### 4.2 派发子 agent（平台自适应）
+
+若当前平台提供子 agent/Task 派发能力，为本批次每个 TASK 各派发一个子 agent（同一批并发不超过 3，超出时按 TASK 顺序拆成多轮）。子 agent prompt 必须包含 worktree 绝对路径、TASK-ID、任务文件相对路径，并声明以下硬性要求：
+
+1. 进入 worktree：所有命令 `cd <worktree>` 执行，文件读写使用该 worktree 内路径。
+2. 按本命令"单任务模式"步骤 1-4 完成该 TASK：`cf_spec_context.py start` → functional RED → 实现 → functional GREEN（E2E 只登记）→ `cf_task_workflow.py finish --root "<worktree>"`。
+3. 平台 hook 注入绑定主工作区；子 agent 必须显式读取 Spec Session（`.code-flow/specs/_session/task-*.md`）与详设章节，不得依赖自动注入。
+4. 完成时在 worktree 内提交全部改动（含任务文件 Checklist/Evidence/Status 更新），提交信息 `cf-task(<TASK-ID>): <标题>`。
+5. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+
+平台不支持子 agent 时，不建 worktree，直接走 4.6 串行回退。
+
+#### 4.3 收集与校验
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py collect --root "$PWD" --run-id <run_id> --json
+```
+
+- 每个任务必须 `ok: true`（改动已提交、Status 为 done/verified、marker 已清理、有提交）。
+- 任一任务失败：停止本批次，不合并；保留 worktree 并列出失败原因。修复后重跑 collect；确认放弃时执行 4.5 cleanup。
+
+#### 4.4 回并主分支
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
+按 TASK-ID 先后顺序逐个回并；先 rebase 再合并，让冲突只在任务自己的 worktree 内解决。
 
-完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
+1. 取主工作区当前分支名（主工作区执行 `git rev-parse --abbrev-ref HEAD`，记为 <主分支>），在任务 worktree 内对齐：
+
+```bash
+cd <worktree> && git rebase <主分支>
+```
+
+- rebase 冲突：读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ `git rebase --abort`，保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。
+- rebase 成功后重跑该任务的 functional 验收命令（E2E 留给 verify-e2e）；失败则在 worktree 内修复并提交，再执行 4.3 collect 复核。
+
+2. 回到主工作区合并（此时应无冲突）：
+
+```bash
+git merge --no-ff -m "merge cf-task <TASK-ID>" <branch>
+```
+
+- 仍出现冲突（主区期间有新合并）：按双方意图解决并重跑双方 functional 验收；通过后提交 merge。
+- 合并后验收失败：记录合并前 HEAD 并 `git reset --hard <合并前HEAD>`（分支与 worktree 原样保留），回到 4.2 让对应子 agent 修复后重新 collect / rebase / 合并。
+
+3. 全部任务合并完成后进入 4.5 清理。
+
+- E2E 验收留给 verify-e2e，不在本步骤执行。
+
+#### 4.5 清理
+
+```bash
+python3 .code-flow/scripts/cf_task_parallel.py cleanup --root "$PWD" --run-id <run_id> --json
+```
+
+清理 worktree；已合入的分支自动删除，未合入的保留供排查。worktree 存在未提交改动时 cleanup 会拒绝，先人工确认再决定处理方式。全部批次完成后进入步骤 5。
+
+#### 4.6 串行回退
+
+未启用并行、批次仅 1 个任务或预检失败时，对批次内可激活子任务执行单任务模式步骤 3-4（详设已在步骤 2 加载，无需重复读取），完成一个后再解锁下一个。
 
 ### 5. 输出摘要与文档同步检查
 
@@ -217,3 +286,5 @@ Spec 同步提示:
 
   运行 /cf-learn --map 可自动更新导航地图。
 ```
+
+3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。

package/src/adapters/opencode/commands/cf-task/verify-e2e.md

@@ -21,10 +21,10 @@ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶
 
 ### 1. 检查前置条件
 
-确认需求目录下所有子任务状态为 `done` 或 `verified`：
+确认需求目录下所有子任务状态为 `done`（实现完成）或 `verified`（终验已闭环）：
 
 ```bash
-rg "^Status:" <需求目录>/*.md
+rg "^- \*\*Status\*\*:" <需求目录>/*.md
 ```
 
 如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
@@ -53,20 +53,19 @@ E2E 场景需要以下环境：
 用户确认后，执行：
 
 ```bash
-python3 .code-flow/scripts/cf_acceptance_runner.py \
-  --manifest <需求目录>/.acceptance-manifest.json \
-  --root . \
-  --include-e2e \
-  --write-evidence
+python3 .code-flow/scripts/cf_task_workflow.py verify-e2e \
+  --task-dir "<需求目录>" --root "$PWD" --json
 ```
 
+该入口重新检查所有 TASK、锁定 manifest 和 functional/manual 最新证据，内部以 `--only-e2e` 调用 runner；只有全通过才把任务提升为 verified。不得手动改状态。
+
 ### 4. 报告结果
 
 解析执行结果：
 
 ```json
 {
-  "decision": "pass",
+  "decision": "block",
   "results": [
     {"id": "E-01", "kind": "e2e", "status": "passed"},
     {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
@@ -79,7 +78,7 @@ python3 .code-flow/scripts/cf_acceptance_runner.py \
 
 ### 5. 更新任务状态
 
-所有 E2E 通过后，将需求目录下的任务状态更新为 `verified`（如果当前是 `done`）。
+确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
 
 ## 失败处理
 

package/src/adapters/opencode/commands/cf-validate.md

@@ -8,7 +8,7 @@ description: 根据变更文件自动匹配并执行验证规则
 
 ## 输入
 
-- `/project:cf-validate` — 基于 git diff 自动获取变更文件
+- `/project:cf-validate` — 自动获取任务基线或 Git 全部变更文件
 - `/project:cf-validate src/Foo.tsx` — 验证指定文件
 - `/project:cf-validate --files=src/a.ts,src/b.ts` — 验证多个文件
 
@@ -19,10 +19,10 @@ description: 根据变更文件自动匹配并执行验证规则
 用 Bash 执行：
 
 ```bash
-git diff --name-only HEAD
+python3 .code-flow/scripts/cf_validation.py --root "$PWD" --scope-only --json
 ```
 
-如果用户指定了文件路径，使用用户指定的文件。如果无变更文件，输出"无变更需要验证"。
+有 active TASK 时使用冻结基线以来的全部任务变更（含已提交文件）；无 active TASK 时包含暂存、未暂存和未跟踪文件。用户指定路径时用 `--files "src/a.py" "src/b.py"` 原样传递；若结果确实为空才输出“无变更需要验证”。
 
 ### 2. 读取验证规则
 
@@ -36,19 +36,21 @@ validators:
     trigger: "**/*.{ts,tsx}"
     command: "npx tsc --noEmit"
     timeout: 30000
+    heavy: false          # true = Stop 每轮跳过，finish 与 /cf-validate 执行
     on_fail: "修复建议"
 ```
 
+全量测试 / e2e 等慢命令标 `heavy: true`：Stop 每轮跳过，**任务 finish 自动执行一次**，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
+
 ### 3. 匹配并执行验证
 
-对每条验证规则：
-- 将 `trigger` glob 与变更文件列表做匹配
-- 匹配到 → 用 Bash 执行 `command`
-  - 如果 command 包含 `{files}` → 替换为匹配到的文件路径列表，**每个路径用单引号包裹**（如 `'src/foo.ts' 'src/bar.ts'`）
-  - 如果 command 不含 `{files}` → 直接执行原命令（如 `npx tsc --noEmit` 本身就检查全局）
-- 未匹配 → 跳过该规则
+执行统一验证入口：
+
+```bash
+python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
+```
 
-每条命令使用对应的 `timeout` 值（毫秒）。
+显式范围追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；同一运行内相同 argv/cwd/timeout 去重，跨运行不复用。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
 
 ### 4. 汇总结果
 
@@ -65,13 +67,13 @@ validators:
 
 ## 安全设计
 
-- 对 `{files}` 中的每个文件路径用单引号包裹，防止 shell 注入
-- 仅接受 `git diff` 输出的文件路径或用户显式指定的路径
+- `{files}` 直接展开为 argv 参数；带空格、引号的路径仍是一个参数，不手工拼接引号或执行 shell
+- 范围来自任务基线、Git 状态（包括 untracked）或用户显式指定的路径
 - 用户指定的路径必须位于项目根目录内
 
 ## 异常处理
 
 - validation.yml 不存在 → 尝试检测 package.json scripts 中的 test/lint 命令
 - 命令执行超时 → 输出超时提示，建议增大 timeout 或缩小验证范围
-- 命令不存在 → 提示安装依赖（如 `pip install mypy`）
+- 命令不存在或配置无效 → 返回 block 并提示所缺依赖，不当作验证通过
 - 无变更文件 → 输出"无变更需要验证"

package/src/adapters/opencode/opencode.json

@@ -1,4 +1,3 @@
 {
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": [".opencode/plugins/code-flow"]
+  "$schema": "https://opencode.ai/config.json"
 }

package/src/adapters/opencode/plugins/code-flow/index.js

@@ -1,12 +1,29 @@
-import { spawnSync } from "child_process";
+import { execFile } from "child_process";
 import { join } from "path";
 import { appendFileSync, mkdirSync } from "fs";
 
+// Note: intentionally no `import { Plugin } from "@opencode/plugin"`.
+// The server does not auto-provide that package for local plugins, and
+// `Plugin.define` is only an identity wrapper — a plain default export
+// with `id` + `setup` satisfies the v2 plugin schema dependency-free,
+// so `code-flow init` works offline without npm install.
+
 const SCRIPT_DIR = ".code-flow/scripts";
+const STOP_CHECK_TIMEOUT = 35000;
+const HOOK_TIMEOUT = 5000;
 
-// Per-session cache of spec context to inject into system prompt
+// Per-session queued feedback. Single map, append-only: idle/stop-check and
+// post-check feedback accumulate here and are consumed by the next context
+// hook. Never overwrite — a prompt hook arriving between idle and context
+// must not drop queued stop-check feedback.
 const sessionContext = new Map();
 
+export function mergePending(existing, incoming) {
+  if (!existing) return incoming;
+  if (!incoming) return existing;
+  return existing + "\n\n" + incoming;
+}
+
 function debugLog(projectRoot, msg) {
   if (process.env.CF_DEBUG !== "1") return;
   try {
@@ -21,111 +38,176 @@ function pythonPath(projectRoot, script) {
   return join(projectRoot, SCRIPT_DIR, script);
 }
 
-function callHook(projectRoot, script, input, timeout = 5000) {
-  try {
-    const proc = spawnSync("python3", [pythonPath(projectRoot, script)], {
-      cwd: projectRoot,
-      input: JSON.stringify(input),
-      encoding: "utf-8",
-      timeout,
-      maxBuffer: 1024 * 1024,
-    });
-    if (proc.error || proc.status !== 0) {
-      debugLog(projectRoot, `callHook ${script} failed: ${proc.error || proc.stderr}`);
-      return null;
+function callHook(projectRoot, script, input, timeout = HOOK_TIMEOUT) {
+  // Async child process: never block the plugin event thread. opencode's
+  // idle event cannot interrupt a turn, so stop-check failures queue into
+  // sessionContext for the next context hook (documented platform gap
+  // vs. blocking Stop hooks).
+  return new Promise((resolve) => {
+    const child = execFile(
+      "python3",
+      [pythonPath(projectRoot, script)],
+      { cwd: projectRoot, timeout, maxBuffer: 1024 * 1024 },
+      (error, stdout, stderr) => {
+        if (error) {
+          debugLog(projectRoot, `callHook ${script} failed: ${error.message || stderr}`);
+          resolve(null);
+          return;
+        }
+        const text = (stdout || "").trim();
+        if (!text) {
+          resolve(null);
+          return;
+        }
+        try {
+          resolve(JSON.parse(text));
+        } catch (e) {
+          debugLog(projectRoot, `callHook ${script} bad JSON: ${e.message}`);
+          resolve(null);
+        }
+      }
+    );
+    if (input !== undefined && child.stdin) {
+      child.stdin.write(JSON.stringify(input));
+      child.stdin.end();
     }
-    const stdout = (proc.stdout || "").trim();
-    if (!stdout) return null;
-    return JSON.parse(stdout);
-  } catch (e) {
-    debugLog(projectRoot, `callHook ${script} exception: ${e.message}`);
-    return null;
+  });
+}
+
+function queueFeedback(sessionID, text) {
+  if (!sessionID || !text) return;
+  sessionContext.set(sessionID, mergePending(sessionContext.get(sessionID), text));
+}
+
+function consumeFeedback(sessionID) {
+  const pending = sessionContext.get(sessionID);
+  if (pending) sessionContext.delete(sessionID);
+  return pending;
+}
+
+function toolInputFilePath(input) {
+  if (!input || typeof input !== "object") return "";
+  const args = input;
+  return args.filePath || args.file_path || args.path || "";
+}
+
+async function runStopCheck(projectRoot, sessionID) {
+  const result = await callHook(projectRoot, "cf_stop_hook.py", { session_id: sessionID }, STOP_CHECK_TIMEOUT);
+  if (result?.reason) {
+    // idle 无法阻断，校验失败排队到下一轮 context hook
+    queueFeedback(sessionID, result.reason);
+    debugLog(projectRoot, `stop-check feedback queued`);
   }
 }
 
-function extractPromptText(output) {
-  if (!output.parts) return "";
-  return output.parts
-    .filter((p) => p.type === "text" && !p.synthetic && !p.ignored)
-    .map((p) => p.text)
-    .join("\n");
+async function registerPromptHook(ctx, projectRoot) {
+  await ctx.session.hook("prompt", async (event) => {
+    const promptText = event.prompt?.text || "";
+    if (!promptText) return;
+    debugLog(projectRoot, `prompt sid=${event.sessionID} prompt_len=${promptText.length}`);
+    const result = await callHook(projectRoot, "cf_user_prompt_hook.py", {
+      prompt: promptText,
+      session_id: event.sessionID,
+    });
+    const additional = result?.hookSpecificOutput?.additionalContext;
+    if (additional) {
+      // Append, never overwrite: queued stop-check feedback survives.
+      queueFeedback(event.sessionID, additional);
+      debugLog(projectRoot, `hook matched — context ${additional.length} chars cached`);
+    } else {
+      debugLog(projectRoot, `hook returned no context`);
+    }
+  });
+}
+
+async function registerToolHook(ctx, projectRoot) {
+  await ctx.tool.hook("execute.after", async (event) => {
+    const tool = String(event.tool || "").toLowerCase();
+    if (!["edit", "write", "multiedit", "patch"].includes(tool)) return;
+    const filePath = toolInputFilePath(event.input);
+    if (!filePath) return;
+    const result = await callHook(projectRoot, "cf_post_hook.py", {
+      tool_name: tool === "write" ? "Write" : "Edit",
+      tool_input: { file_path: filePath },
+      session_id: event.sessionID || "",
+    });
+    const additional = result?.hookSpecificOutput?.additionalContext;
+    if (additional) {
+      // 反馈排队，下一轮 context hook 注入（opencode 无法当轮插话）
+      queueFeedback(event.sessionID, additional);
+      debugLog(projectRoot, `post-check feedback queued ${additional.length} chars`);
+    }
+  });
 }
 
-export const CodeFlow = async (ctx) => {
-  const projectRoot = ctx.directory;
+async function registerContextHook(ctx) {
+  await ctx.session.hook("context", (event) => {
+    const pending = consumeFeedback(event.sessionID);
+    if (pending) {
+      event.system.push({ type: "text", text: pending });
+      debugLog(ctx.location.directory, `context — injected ${pending.length} chars`);
+    }
+  });
+}
 
+// 子会话（子 agent / worktree 并行任务）的 idle 不得触发主工作区 stop-check：
+// 子会话的编辑发生在自己的工作区，主区既无 active marker 也没有对应文件，
+// 触发只会重复执行主区 validators（全量测试）。用 session.created.parentID 标记子会话。
+export function createSessionRegistry() {
+  const children = new Set();
   return {
-    event: async (input) => {
-      if (input.event?.type === "session.created") {
-        const sid = input.event?.properties?.info?.id || "";
-        debugLog(projectRoot, `session.created sid=${sid}`);
-        if (sid) sessionContext.delete(sid);
+    observe(event) {
+      if (!event || typeof event.type !== "string") return null;
+      const sid = event.data?.sessionID || "";
+      if (!sid) return null;
+      if (event.type === "session.created") {
+        if (event.data?.parentID) children.add(sid);
+        return { type: "created", sid };
       }
-      if (input.event?.type === "session.idle") {
-        const sid =
-          input.event?.properties?.sessionID ||
-          input.event?.properties?.info?.id || "";
-        const result = callHook(projectRoot, "cf_stop_hook.py", { session_id: sid }, 35000);
-        if (result?.reason) {
-          // idle 无法阻断，校验失败排队到下一轮 system prompt
-          const pending = sessionContext.get(sid);
-          sessionContext.set(sid, pending ? pending + "\n\n" + result.reason : result.reason);
-          debugLog(projectRoot, `stop-check feedback queued`);
-        }
+      if (event.type === "session.idle") {
+        return { type: "idle", sid, child: children.has(sid) };
       }
+      return null;
     },
+  };
+}
 
-    "chat.message": async (input, output) => {
-      const promptText = extractPromptText(output);
-      if (!promptText) return;
-
-      debugLog(projectRoot, `chat.message sid=${input.sessionID} prompt_len=${promptText.length}`);
-
-      const result = callHook(projectRoot, "cf_user_prompt_hook.py", {
-        prompt: promptText,
-        session_id: input.sessionID,
-      });
-
-      if (result?.hookSpecificOutput?.additionalContext) {
-        const ctxLen = result.hookSpecificOutput.additionalContext.length;
-        debugLog(projectRoot, `hook matched — context ${ctxLen} chars cached`);
-        sessionContext.set(
-          input.sessionID,
-          result.hookSpecificOutput.additionalContext
-        );
-      } else {
-        debugLog(projectRoot, `hook returned no context`);
+function startEventSubscription(ctx, projectRoot) {
+  const controller = new AbortController();
+  const registry = createSessionRegistry();
+  void (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        const observed = registry.observe(event);
+        if (!observed) continue;
+        if (observed.type === "created") {
+          debugLog(projectRoot, `session.created sid=${observed.sid}`);
+          sessionContext.delete(observed.sid);
+        } else if (observed.child) {
+          debugLog(projectRoot, `session.idle sid=${observed.sid} (child) — stop-check skipped`);
+        } else {
+          await runStopCheck(projectRoot, observed.sid);
+        }
       }
-    },
-
-    "tool.execute.after": async (input, output) => {
-      const tool = String(input?.tool || "").toLowerCase();
-      if (!["edit", "write", "multiedit", "patch"].includes(tool)) return;
-      const args = output?.args || input?.args || {};
-      const filePath = args.filePath || args.file_path || args.path;
-      if (!filePath) return;
-      const result = callHook(projectRoot, "cf_post_hook.py", {
-        tool_name: tool === "write" ? "Write" : "Edit",
-        tool_input: { file_path: filePath },
-        session_id: input?.sessionID || "",
-      });
-      const ctx = result?.hookSpecificOutput?.additionalContext;
-      if (ctx) {
-        // 反馈排队，下一轮 system.transform 注入（opencode 无法当轮插话）
-        const sid = input?.sessionID || "";
-        const pending = sessionContext.get(sid);
-        sessionContext.set(sid, pending ? pending + "\n\n" + ctx : ctx);
-        debugLog(projectRoot, `post-check feedback queued ${ctx.length} chars`);
+    } catch (err) {
+      if (err?.name !== "AbortError") {
+        debugLog(projectRoot, `event subscription ended: ${err?.message || err}`);
       }
-    },
+    }
+  })();
+  return () => controller.abort();
+}
 
-    "experimental.chat.system.transform": async (input, output) => {
-      const ctx = sessionContext.get(input.sessionID);
-      if (ctx) {
-        output.system.push(ctx);
-        debugLog(projectRoot, `system.transform — injected ${ctx.length} chars, system now ${output.system.length} parts`);
-        sessionContext.delete(input.sessionID);
-      }
-    },
-  };
+const CodeFlowPlugin = {
+  id: "code-flow",
+  async setup(ctx) {
+    const projectRoot = ctx.location.directory;
+    await registerPromptHook(ctx, projectRoot);
+    await registerToolHook(ctx, projectRoot);
+    await registerContextHook(ctx);
+    const stopSubscription = startEventSubscription(ctx, projectRoot);
+    return () => stopSubscription();
+  },
 };
+
+export default CodeFlowPlugin;

package/src/adapters/opencode/plugins/code-flow/package.json

@@ -2,5 +2,5 @@
   "name": "code-flow-opencode",
   "type": "module",
   "main": "index.js",
-  "description": "code-flow spec injection plugin for OpenCode"
+  "description": "code-flow spec injection plugin for OpenCode v2"
 }