@michaelxwb/code-flow 0.6.1 → 0.6.3

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

@@ -18,17 +18,23 @@ description: 标记子任务为阻塞状态
 
 1. 用 Glob 定位任务文件，Read 读取
 2. 定位 `## TASK-001` 段落，检查当前 Status：
-   - `done` → 拒绝：`TASK-001 已完成，无法标记阻塞`
+   - `done` / `verified` → 拒绝：`TASK-001 已完成，无法标记阻塞`
    - `blocked` → 提示：`TASK-001 已处于 blocked 状态`，仍追加新的阻塞原因
    - `draft` / `in-progress` → 继续
-3. 用 Edit 更新 Status 为 `blocked`
-4. 在 `### Log` 前追加：`> BLOCKED: <阻塞原因>`
-5. 在 `### Log` 追加：`- [<当前日期>] blocked (<阻塞原因>, was <原状态>)`
-6. 更新文件头 `Updated` 日期
-7. 输出确认：`TASK-001 已标记为 blocked: <原因>`
+3. 调用统一 workflow service 入口（与 active block 同一状态机），不要先编辑状态或 marker：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py block --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --reason "<阻塞原因>" --json
+```
+
+命令同时更新 Status、阻塞原因、Log、Updated 和匹配的 marker；无 marker 的 draft 任务只改变任务文档。仅在返回成功后确认阻塞；其他需求的 marker 不得改动。
 
 ## 解除阻塞
 
-阻塞的解除不通过本命令操作，而是：
-- 如果是 Notes 导致的阻塞 → 用 `/project:cf-task:note` 与 AI 讨论解决后自动解除
-- 如果是 `[BLOCKED]` 标记 → 用户手动编辑文件移除 `[BLOCKED]` 条目，或用 `/project:cf-task:start` 重新启动（需所有阻塞条件清除）
+先解决 Notes 或外部依赖，再执行：
+
+```bash
+python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+```
+
+resume 会检查未解决的 #NOTES 和依赖，原子同步任务与 marker。未激活的 blocked 任务恢复 draft；已有匹配 marker 的任务恢复 in-progress。失败时保留阻塞状态，不通过手动改 Status 绕过。

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

@@ -17,6 +17,12 @@ description: 可视化子任务依赖关系 DAG
 
 ## 执行步骤
 
+### 0. 程序计算（推荐）
+
+用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK：批次内“可并行”指可独立开发，而非可同时激活。
+
+`batches` 是组内可独立开发的拓扑批次；`dependency_components` 是依赖连通分组，只保证组与组之间独立，组内仍有先后依赖。`independent_groups` 仅为后者的兼容别名，不要把它显示成组内并行。
+
 ### 1. 读取任务数据
 
 - 指定文件：Glob 定位后 Read
@@ -69,7 +75,8 @@ Layer 2:
 按子任务状态标注：
 - `[draft]` — 待启动
 - `[in-progress]` — 进行中
-- `[done]` — 已完成
+- `[done]` — 实现完成，E2E 可能仍待终验
+- `[verified]` — 终验完成
 - `[blocked]` — 被阻塞（附原因）
 
 ### 5. 多文件模式

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

@@ -138,10 +138,7 @@ TASK-002:
 所有 `#NOTES` 讨论完毕后：
 
 1. 再次扫描文件，确认无残留 `#NOTES` 标记
-2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`：
-   - 扫描 `### Log`，查找 `blocked` 记录中的原状态
-   - 用 Edit 恢复原状态
-   - 在 `### Log` 追加：`- [<当前日期>] unblocked (all #NOTES resolved, restored to <原状态>)`
+2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`，清除当前阻塞条目后调用 `python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`。命令检查依赖和残留 Notes，同步 marker 与任务状态；不得从历史 Log 猜测状态后只改 Markdown。失败保留 blocked 并报告原因。
 3. 更新文件头 `Updated` 日期
 
 ### 6. 输出摘要

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

@@ -1,8 +1,3 @@
----
-description: 从设计文档拆解需求，生成结构化任务文件
----
-
-
 # cf-task:plan
 
 从设计文档或设计简报拆解需求，生成结构化任务文件。
@@ -13,6 +8,8 @@ description: 从设计文档拆解需求，生成结构化任务文件
 - `/cf-task:plan` — 交互式选择（从 `docs/` 目录列出候选）
 - `/cf-task:plan <设计文档路径> --explore` — 仅输出分析报告，不生成文件
 - `/cf-task:plan <设计文档路径> --quick` — 跳过缺口分析，直接拆解（保持原有行为）
+- `/cf-task:plan <设计文档路径> --draft` — 仅生成任务草案，必须经过 `--verify-plan` 后才能启动
+- `/cf-task:plan <任务文件> --verify-plan` — 执行完整 Acceptance Coverage 与 Spec Rule 门禁
 - `/cf-task:plan <.design.md 路径>` — 从 cf-task:align 产出的设计简报拆解（自动跳过缺口分析）
 
 ## 执行步骤
@@ -62,6 +59,17 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
 
 此索引用于后续步骤中精确记录每个子任务的来源章节。
 
+### 2.4.1. Draft / Verify Plan 模式
+
+`--draft` 只生成任务结构、依赖、Source 和初步验收映射，产物状态必须保持 `draft`，不得直接进入 `start`。用户确认拆分后执行 `--verify-plan`，完成全部场景覆盖、唯一 Rule owner、verifier、测试层级和真实边界校验；默认模式仍执行完整校验。
+
+`--verify-plan` 的执行命令为：
+
+```bash
+python3 .code-flow/scripts/cf_acceptance_manifest.py \
+  --verify-plan --task-dir <需求目录> --task-file <任务文件>
+```
+
 ### 2.5. Explore 模式（--explore）
 
 如果用户传入 `--explore`，在建立章节索引后，输出以下分析报告，**不生成任务文件**：
@@ -303,6 +311,33 @@ TASK-002: <标题> [P1]
 python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
 ```
 
+通过 Plan Gate 后，锁定验收基线：
+
+```bash
+python3 .code-flow/scripts/cf_acceptance_manifest.py \
+  --task-file <任务文件> \
+  --output <需求目录>/.acceptance-manifest.json
+```
+
+Manifest 锁定场景 ID、来源、测试层级、真实边界和责任 TASK。编码阶段不得静默修改这些字段；如发生范围变化，必须重新执行 plan 验证。
+
+验收类型按测试层级归类：
+- `unit/integration` → `functional`（Done Gate 自动执行）
+- `E2E` → `e2e`（延迟至所有任务完成后，需 `--include-e2e` 显式执行）
+- `manual` → `manual`（用户手动验证，永不自动执行）
+
+E2E 场景依赖外部环境（数据库、API、浏览器），在编码阶段默认跳过（状态 `e2e_deferred`），不阻断 Done Gate。所有子任务完成后，执行：
+
+```bash
+python3 .code-flow/scripts/cf_acceptance_runner.py \
+  --manifest <需求目录>/.acceptance-manifest.json \
+  --root . \
+  --include-e2e \
+  --write-evidence
+```
+
+不得为了提速降低 design 指定的 E2E 层级。
+
 只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
 
 ### 6. 输出摘要

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

@@ -27,8 +27,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 +37,7 @@ description: 激活子任务并开始编码
 
 **依赖检查**：读取 `Depends` 字段
 - 对每个依赖的 TASK-ID，在同文件中查找其 Status
-- 所有依赖必须为 `done`
+- 所有依赖必须为 `done` 或 `verified`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
 **验收契约检查**：
@@ -65,13 +65,12 @@ description: 激活子任务并开始编码
 
 在改状态或生产代码前，顺序固定且不得跳步：
 
-1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
-2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
-3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
-4. 只有前三步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
-5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+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. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -89,11 +88,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 已在编码前锁定场景、断言、真实边界和命令，完整 GREEN 留给 verify-e2e。
+2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
+3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
+4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
 
 ### 3.5 TASK-bound Spec Session
 
@@ -111,16 +109,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；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
 
 任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
 

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

@@ -0,0 +1,110 @@
+---
+description: Execute deferred E2E scenarios after all functional tests pass
+globs: []
+---
+
+# cf-task:verify-e2e
+
+执行需求目录下被延迟的 E2E 验收场景。
+
+## 使用场景
+
+E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+
+## 调用方式
+
+```
+/cf-task:verify-e2e <需求目录>
+```
+
+## 执行步骤
+
+### 1. 检查前置条件
+
+确认需求目录下所有子任务状态为 `done`（实现完成）或 `verified`（终验已闭环）：
+
+```bash
+rg "^- \*\*Status\*\*:" <需求目录>/*.md
+```
+
+如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
+
+### 2. 检查环境依赖
+
+读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
+
+- `HTTP API` → 提示确认 API 服务运行中
+- `Browser` → 提示确认浏览器驱动已安装
+- `Database` → 提示确认测试数据库可访问
+
+显示清单并询问：
+
+```
+E2E 场景需要以下环境：
+  - 本地 API 服务 (http://localhost:3000)
+  - PostgreSQL 测试数据库
+  - Chrome WebDriver
+
+环境已就绪？(y/N)
+```
+
+### 3. 执行 E2E 场景
+
+用户确认后，执行：
+
+```bash
+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": "block",
+  "results": [
+    {"id": "E-01", "kind": "e2e", "status": "passed"},
+    {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
+  ]
+}
+```
+
+- `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
+- `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
+
+### 5. 更新任务状态
+
+确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
+
+## 失败处理
+
+E2E 失败时：
+
+1. 显示失败场景的完整命令和退出码
+2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
+3. 不自动修改任务状态，等待用户修复后重新执行
+
+## 示例
+
+```
+/cf-task:verify-e2e .code-flow/tasks/2026-03-15/auth-module
+
+> 检查子任务状态... 所有任务已完成
+> 
+> E2E 场景需要以下环境：
+>   - 本地 API 服务 (http://localhost:3000)
+>   - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
+> 
+> 环境已就绪？(y/N) y
+> 
+> 执行 E2E 场景...
+>   ✓ E-01: 用户登录流程 (1.2s)
+>   ✓ E-02: 权限验证链路 (0.8s)
+> 
+> E2E 验收完成！2/2 场景通过
+> 已更新任务状态为 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. 读取验证规则
 
@@ -41,14 +41,13 @@ validators:
 
 ### 3. 匹配并执行验证
 
-对每条验证规则：
-- 将 `trigger` glob 与变更文件列表做匹配
-- 匹配到 → 用 Bash 执行 `command`
-  - 如果 command 包含 `{files}` → 替换为匹配到的文件路径列表，**每个路径用单引号包裹**（如 `'src/foo.ts' 'src/bar.ts'`）
-  - 如果 command 不含 `{files}` → 直接执行原命令（如 `npx tsc --noEmit` 本身就检查全局）
-- 未匹配 → 跳过该规则
+执行统一验证入口：
 
-每条命令使用对应的 `timeout` 值（毫秒）。
+```bash
+python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
+```
+
+显式范围追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；同一运行内相同 argv/cwd/timeout 去重，跨运行不复用。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
 
 ### 4. 汇总结果
 
@@ -65,13 +64,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/plugins/code-flow/index.js

@@ -1,12 +1,21 @@
-import { spawnSync } from "child_process";
+import { execFile } from "child_process";
 import { join } from "path";
 import { appendFileSync, mkdirSync } from "fs";
 
 const SCRIPT_DIR = ".code-flow/scripts";
 
-// 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
+// system.transform. Never overwrite — chat.message arriving between idle and
+// transform 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 {
@@ -22,25 +31,39 @@ function pythonPath(projectRoot, 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;
+  // 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 system.transform (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 extractPromptText(output) {
@@ -65,11 +88,10 @@ export const CodeFlow = async (ctx) => {
         const sid =
           input.event?.properties?.sessionID ||
           input.event?.properties?.info?.id || "";
-        const result = callHook(projectRoot, "cf_stop_hook.py", { session_id: sid }, 35000);
+        const result = await 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);
+          sessionContext.set(sid, mergePending(sessionContext.get(sid), result.reason));
           debugLog(projectRoot, `stop-check feedback queued`);
         }
       }
@@ -81,7 +103,7 @@ export const CodeFlow = async (ctx) => {
 
       debugLog(projectRoot, `chat.message sid=${input.sessionID} prompt_len=${promptText.length}`);
 
-      const result = callHook(projectRoot, "cf_user_prompt_hook.py", {
+      const result = await callHook(projectRoot, "cf_user_prompt_hook.py", {
         prompt: promptText,
         session_id: input.sessionID,
       });
@@ -89,9 +111,10 @@ export const CodeFlow = async (ctx) => {
       if (result?.hookSpecificOutput?.additionalContext) {
         const ctxLen = result.hookSpecificOutput.additionalContext.length;
         debugLog(projectRoot, `hook matched — context ${ctxLen} chars cached`);
+        // Append, never overwrite: queued stop-check feedback survives.
         sessionContext.set(
           input.sessionID,
-          result.hookSpecificOutput.additionalContext
+          mergePending(sessionContext.get(input.sessionID), result.hookSpecificOutput.additionalContext)
         );
       } else {
         debugLog(projectRoot, `hook returned no context`);
@@ -104,7 +127,7 @@ export const CodeFlow = async (ctx) => {
       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", {
+      const result = await callHook(projectRoot, "cf_post_hook.py", {
         tool_name: tool === "write" ? "Write" : "Edit",
         tool_input: { file_path: filePath },
         session_id: input?.sessionID || "",
@@ -113,8 +136,7 @@ export const CodeFlow = async (ctx) => {
       if (ctx) {
         // 反馈排队，下一轮 system.transform 注入（opencode 无法当轮插话）
         const sid = input?.sessionID || "";
-        const pending = sessionContext.get(sid);
-        sessionContext.set(sid, pending ? pending + "\n\n" + ctx : ctx);
+        sessionContext.set(sid, mergePending(sessionContext.get(sid), ctx));
         debugLog(projectRoot, `post-check feedback queued ${ctx.length} chars`);
       }
     },