fix: 统一 Hook 输出确认与硬门禁故障语义 (v0.14.2)

Author: loong10k

.agents/plugins/marketplace.json

@@ -9,20 +9,20 @@
       "source": {
         "source": "url",
         "url": "https://github.com/partme-ai/partme-codeguard-plugin.git",
-        "ref": "v0.14.1"
+        "ref": "v0.14.2"
       },
       "policy": {
         "installation": "AVAILABLE",
         "authentication": "ON_USE"
       },
       "category": "Developer Tools",
-      "version": "0.14.1",
+      "version": "0.14.2",
       "description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
-      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.1/assets/official-logo.png",
+      "icon": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.2/assets/official-logo.png",
       "interface": {
         "displayName": "代码规范守卫",
         "shortDescription": "Trustworthy code checks and Java impact analysis",
-        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.1/assets/official-logo.png"
+        "logo": "https://cdn.jsdelivr.net/gh/full-stack-plugins/codeguard-plugin@v0.14.2/assets/official-logo.png"
       }
     }
   ]

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codeguard",
-  "version": "0.14.1+codex.20260923",
+  "version": "0.14.2+codex.20260923",
   "description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
   "author": {
     "name": "Full Stack Skills / PartMe.AI",

.zcode-plugin/plugin.json

@@ -5,7 +5,7 @@
     "en": "CodeGuard",
     "zh-CN": "代码规范检查"
   },
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
   "description_i18n": {
     "en": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",

docs/current-architecture.md

@@ -35,7 +35,7 @@ flowchart TD
 | `bin/codeguard`、`scripts/run_check.py`、`scripts/fix.py` | CLI 参数、输出与 MCP stdio 注册 | 不复制扫描器或判定逻辑 |
 | `hooks/` | 宿主 JSON、会话事件、通知与退出协议 | 五类 Hook 将检查编排委托应用服务；入口保留旧导入兼容面及 fail-open 协议 |
 | `scripts/codeguard/check_application.py`、`language_check.py` | 语言选择、检查与修复请求、MCP 工具分发 | 不导入 MCP SDK；旧 `run_per_language.py` 仅再导出 |
-| `startup_application.py`、`session_application.py`、`prompt_application.py`、`git_guard_application.py`、`save_application.py` | 五类 Hook 的盘点、状态消费、软提示、Git 守卫及保存反馈编排 | 返回结构化结果，不打印或调用宿主通知；Hook 控制输出、通知与 fail-open。Stop 在 stdout 刷新后才确认消费；若同时有新统计，为避免丢记录，后续 Stop 可能重复展示旧统计 |
+| `startup_application.py`、`session_application.py`、`prompt_application.py`、`git_guard_application.py`、`save_application.py` | 五类 Hook 的盘点、状态消费、软提示、Git 守卫及保存反馈编排 | 返回结构化结果，不打印或调用宿主通知；Hook 控制输出、通知与 fail-open。Stop、软提示与保存反馈在 stdout 刷新后确认状态；Git 已知拦截在输出故障时仍拦截但不缓存。并发或交付重试可能重复反馈，不得丢掉未交付记录 |
 | `gate.py`、`gate_checks.py`、`repository_policy.py`、`baseline.py` | Git 门禁、单语言结果、安全规则及有证据的存量比较 | 只有准确基线失败且逐条诊断的文件归属、内容及次数覆盖当前结果才可豁免；基线临时路径映射回被检查文件 |
 | `java_build.py`、`java_impact.py`、`java_planning.py` 等 | 构建读取、纯影响闭包、命令选择与环境观察 | 默认保留跳过测试的行为；复杂构建保守扩大检查范围 |
 | `cve_reports.py`、`cve_policy.py`、`cve_scanners.py`、`cve.py` | 漏洞报告、阈值、进程适配与复扫编排 | 无有效结构化报告就没有安全通过结论 |
@@ -66,4 +66,4 @@ python3 scripts/vendor/skill_vendor.py check
 openspec validate refactor-codeguard-architecture --strict
 ```
 
-真实 Maven/Gradle 大型项目、联网漏洞数据库、57 种工具链、Windows 与三宿主已安装运行均需要独立证据。临时 Git 快照不是执行沙箱；构建和扫描命令以当前用户权限运行。当前重构的任务进度和本地证据见 `openspec/changes/refactor-codeguard-architecture/verification.md`。v0.13.0 的源码、CI、tag、Release 和市场已核对；其后工作树变更仍需独立发布，宿主安装运行尚未验收。
+真实 Maven/Gradle 大型项目、联网漏洞数据库、57 种工具链、Windows 与三宿主已安装运行均需要独立证据。临时 Git 快照不是执行沙箱；构建和扫描命令以当前用户权限运行。当前重构的任务进度和本地证据见 `openspec/changes/refactor-codeguard-architecture/verification.md`。v0.14.1 的源码、CI、tag、Release 和市场已核对；其后工作树变更仍需独立发布，宿主安装运行尚未验收。

hooks/post_tool_lint.py

@@ -112,6 +112,7 @@ def _main(payload: dict) -> int:
         if result.system_message is not None:
             message["systemMessage"] = result.system_message
         print(json.dumps(message, ensure_ascii=False))
+    sys.stdout.flush()
     result.acknowledge()
     if result.notification:
         lang, title, message = result.notification

hooks/pre_tool_git_guard.py

@@ -79,26 +79,37 @@ def extract_command(payload: dict) -> str:
 def main() -> int:
     payload = read_payload()
     with session_scope(payload):
-        if not payload.get("tool_use_id"):
-            return _main(payload)
-        key = "pre:" + str(payload["tool_use_id"]) + ":" + extract_command(payload)
-        cached = completed_event(key)
+        key = ("pre:" + str(payload["tool_use_id"]) + ":" + extract_command(payload)
+               if payload.get("tool_use_id") else None)
+        cached = completed_event(key) if key else None
         if cached is not None and cached["code"] == 2:
-            sys.stdout.write(cached["stdout"])
-            sys.stderr.write(cached["stderr"])
+            _deliver(cached["code"], cached["stdout"], cached["stderr"])
             return cached["code"]
         stdout, stderr = io.StringIO(), io.StringIO()
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
             code = _main(payload)
         out, err = stdout.getvalue(), stderr.getvalue()
         # 只复用阻断结果，硬门放行和未验证永远重跑准确快照。
-        sys.stdout.write(out)
-        sys.stderr.write(err)
-        if code == 2:
+        delivered = _deliver(code, out, err)
+        if key and code == 2 and delivered:
             record_completed_event(key, code, out, err)
         return code
 
 
+def _deliver(code: int, stdout: str, stderr: str) -> bool:
+    """刷新宿主输出后才允许缓存；已知拦截不能因输出故障降为放行。"""
+    try:
+        sys.stdout.write(stdout)
+        sys.stderr.write(stderr)
+        sys.stdout.flush()
+        sys.stderr.flush()
+    except (OSError, UnicodeError, ValueError):
+        if code == 2:
+            return False
+        raise
+    return True
+
+
 def _main(payload: dict) -> int:
     ensure_user_path()
     result = evaluate_git_command(

hooks/user_prompt_validator.py

@@ -102,6 +102,7 @@ def _main(payload: dict) -> int:
             "hookEventName": "UserPromptSubmit",
             "additionalContext": result.additional_context,
         }}, ensure_ascii=False))
+    sys.stdout.flush()
     result.acknowledge()
     return 0
 

kimi.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codeguard",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Evidence-backed code checks and Git content gates for AI assistants, with Maven/Gradle module impact analysis. Save hooks provide feedback; unverified checks are explicit.",
   "author": {
     "name": "Full Stack Skills / PartMe.AI"

openspec/changes/refactor-codeguard-architecture/design.md

@@ -88,6 +88,11 @@ Stop 的宿主入口先准备原子可读的状态快照，成功写入并刷新
 后续 Stop 可能重复展示旧统计，但不会丢掉未展示的新统计。旧直接消费接口继续兼容，
 不用于宿主 Stop 交付路径。
 
+同一交付规则也适用于 UserPromptSubmit 和 PostToolUse：入口完成 stdout 刷新后才确认
+已完成事件、保存去重和会话统计。PreToolUse 的已知拦截先保留退出码；写入、编码或刷新
+故障时不缓存未交付结果，不能通过通用 fail-open 异常处理把明确的拦截改成放行。
+这只证明本进程写入管道成功，不能证明宿主最终消费；因此重试允许重复反馈。
+
 事件去重不等于权限缓存。观察 Hook 成功返回后才登记完成，异常允许重试；UPS 有 skipped 时
 保守地不登记。硬门禁只重放已完成拒绝，放行、未验证和执行中一律不复用；并发副本允许
 重复检查而不能预占后直接放行。保存检查只有已获得结论才记去重，未知可立即重试。

openspec/changes/refactor-codeguard-architecture/specs/execution-kernel/spec.md

@@ -62,6 +62,7 @@
 
 统计、绕过明细、冷却与审计的读改写 MUST 在进程锁内完成并原子替换文件。宿主提供 session_id 时，统计 MUST 绑定会话与当前 worktree；Stop MUST 只消费该作用域的记录，并与并发写入互斥。无 session_id 时保留旧共享状态兼容，MUST 明示不能证明跨会话隔离。去重 MUST NOT 把未完成或 UNVERIFIED 的检查当成已完成检查。
 Stop MUST 在宿主输出成功刷新后才确认消费；输出失败时记录必须保留供重试。若确认前有并发新写入，允许后续 Stop 重复展示旧统计，但不得删除未展示的新记录。
+UserPromptSubmit 与 PostToolUse 的已完成事件、文件去重和会话统计 MUST 在相应 stdout 成功刷新后才登记；写入或刷新失败时不得把未交付反馈标记为已交付。PreToolUse 已得到拦截结论时，即使宿主输出失败也 MUST 保留拦截退出码，并且不得缓存该次未交付结果。
 
 #### Scenario: Concurrent writers preserve all increments
 - **WHEN** 多个 Hook 进程同时更新同一统计、绕过记录或审计日志
@@ -75,6 +76,14 @@ Stop MUST 在宿主输出成功刷新后才确认消费；输出失败时记录
 - **WHEN** Stop 已准备总结但宿主 stdout 写入或刷新失败，或在输出期间有新统计写入
 - **THEN** 输出失败时旧统计可在重试中再次展示；并发新统计不得被确认消费误删，允许为了不丢记录而在后续 Stop 重复展示旧统计
 
+#### Scenario: Buffered host feedback fails before delivery
+- **WHEN** UserPromptSubmit 或 PostToolUse 已写入反馈，但 stdout 刷新失败
+- **THEN** 不登记已完成事件、文件去重或会话统计；下次触发仍可重新检查并交付反馈
+
+#### Scenario: Hard Git block survives host output failure
+- **WHEN** PreToolUse 已判定需要拦截，但 stdout 或 stderr 写入或刷新失败
+- **THEN** 保持拦截退出码且不缓存该次结果，不能因宿主输出故障改为放行
+
 #### Scenario: Retry follows an unverified save check
 - **WHEN** 相同文件未变化，上次保存检查未能获得结论，紧接着再次触发
 - **THEN** 再次执行检查，不因此前写入的去重标记而静默跳过