docs(hooks): add OpenCode hooks config tools design and clarify Runti…

[JohnLee1243]

docs(hooks): add OpenCode hooks config tools design and clarify RuntimeHookRegistry wrapping

Summary

新增 docs/architecture/extensions/opencode-hooks-config-tools-design.md，作为 BitFun 接入 OpenCode 插件 Hooks / Config / Tool 的正式归档设计；同步在 docs/architecture/agent-runtime-services-design.md 标注 RuntimeHookRegistry 自身已是内部共享的可克隆句柄，AgentRuntime 不再外套 Arc。

Fixes #

Type and Areas

Type: docs

Areas: docs (architecture / extensions)

Motivation / Impact

BitFun 已有 command Hook 与 builtin Hook，但缺少 OpenCode 插件 JavaScript function Hook 的接入路径，也没有将插件 config / tool 结果投影到 Agent、Permission、Tool、Skill 业务模块的端到端设计。本 PR 沉淀这一设计，作为后续实现、评审与兼容性演进的依据，统一以下核心决策：

1. 统一 Hook Runtime 只有 Command / Builtin / Plugin 三种 Handler；Plugin 通过 host.hook.call 调用插件侧 JavaScript function。
2. RuntimeHookRegistry 是注册事实的唯一 owner，由 AgentRuntime 长期持有。
3. AgentHookEngine 不长期持有注册状态，每次 dispatch 基于 Registry clone 与一次不可变 snapshot 创建。
4. Config / Tool / Agent / Permission / Skill 是统一 Hook Runtime 之后的业务投影或消费者，仍由既有业务模块拥有。

同步的 1 行注释修正了 AgentRuntime 中 hooks 字段的包装语义，与上述第 2 条决策一致：RuntimeHookRegistry 本身已是共享可克隆句柄，无需再外套 Arc。

No direct user-facing change — 本 PR 仅新增 / 调整设计文档，不改变任何运行时行为。

Verification

Docs-only change，按 AGENTS.md「Verification」第 3 条选择最轻量检查：

• 提交前已 git diff --cached --stat 确认变更范围：2 个文件、+1122 / -1 行，无意外文件混入。
• 新增文档内部引用路径 opencode-plugin-complete-compatibility-backlog.zh-CN.md 指向已存在的未跟踪同目录文档（属同一 hook-docs 工作流，将在后续 PR 跟进），未引入指向仓库外资源的链接。
• 未触碰 Rust / TS / locale 资源，无需 pnpm run fmt:rs、i18n:audit、theme:color-audit:all 等运行时 / 契约检查。

Reviewer Notes

• 新增设计文档为 1121 行，覆盖设计基线、待解决问题、统一 Hook Runtime、Config / Tool / Agent / Permission / Skill 投影、生命周期与兼容性演进；它是后续实现的 single source of truth，评审时建议重点看 §1（范围与核心决策）、§2（设计基线）、§3 起的 Runtime 边界。
• agent-runtime-services-design.md 的修改为单行注释，与既有结构等价，不影响 AgentRuntime 的字段布局或语义合同。
• 兼容性风险：无。本 PR 不引入持久化形状变化、不新增 Tauri 命令、不触及远端 / Peer / Dispatch 路径。
• 回滚：直接 revert 该提交即可，无迁移、无副作用。

Checklist

• This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts.
• Relevant verification is recorded above, or skipped checks are explained.
• User-facing strings, docs, and locales are updated where applicable.

[limityan]

Review：Request Changes（docs-only，但基线失真与双源重复会误导后续实现）

本审查按仓库规则在隔离上下文中完成，证据均以当前 main 代码与既有文档逐条核对。该文档自称"后续实现、评审和兼容性演进均以本文定义…为依据"（§1），因此基线错误不能以"仅是文档"为由忽略。

---

Blocking

B1. 设计基线把不存在的模块/协议写成"已有"，违反治理规则

• 问题：§2.2 声称"设计开始时"已存在：src/apps/extension-host（受监督 Node/Bun 进程）、Rust PluginHost/PluginHostClient（进程生命周期与通用 RPC client）、"loopback TCP、4-byte length framing、JSON-RPC 2.0"传输；§2.2 基线矩阵与 §15 模块表还把 src/crates/adapters/opencode-plugin-host、src/crates/assembly/core/src/plugin_host.rs、plugin_hook_bridge.rs 列为代码落点。
• 事实：全仓不存在 extension-host、PluginHost、PluginHostClient 与 "loopback TCP"（仅有 contracts 中的 PluginHostLifecyclePhase 枚举）；现有 worker 协议是 stdin/stderr 换行 JSON-RPC（src/apps/desktop/resources/worker_host.js:4-5）；AgentHookEngine 只有 new(settings)（src/crates/execution/agent-runtime/src/native_hooks/engine.rs:36），不存在 §4.6 伪码使用的 with_registry。
• 风险：直接违反 plugin-runtime-design.md:11（"目标不能被写成已经交付的能力"）与根 AGENTS.md 的 OpenCode P0 规则（"do not treat a design target as an already available capability"）。实现者会以不存在的接口为基线，产生错误依赖或重复造轮子。
• 建议：§2.2 全部改写为"目标（当前未实现）"，引用 plugin-runtime-design.md §1/§2 的现状（既有对象是 PluginRuntimeClient、ScriptToolRuntime/NodeScriptToolRuntime）；§15 删除不存在的路径，把职责映射到既有边界；所有 Rust 伪码标注 Target。

B2. 与既有权威文档大面积重复且自称 single source of truth，制造双源

• 问题：§8-§12（Config 投影、Agent/mode 映射、Permission、Tool 隔离、Skill 投影）与 opencode-config-assets-adapter-design.md §5.2（Agents/Modes/Skills 映射、logical_id + route owner、权限收紧、Skill root 治理，且已标注"当前已实现范围"）重复；§4.7-§4.9、§6-§7（function Hook 变换语义、tool.execute.before/after、错误策略、调用协议、生命周期）与 opencode-plugin-runtime-adapter-design.md §6（钩子分类已含 config/tool.execute.before/after 及变换规则）、§8.2（跨进程调用协议：期限/取消/迟到响应）、§9（生命周期）、§11（当前实现与迁移）重复；§13 与 plugin-runtime-design.md §2/§3 重复。§1 的"缺少 OpenCode 插件 JavaScript function Hook 的接入路径"与 plugin-runtime-adapter §6 已定义该接入设计相矛盾。
• 风险：两份文档对同一对象给出两套表述，后续演进必然漂移；违反根 AGENTS.md 的反冗余与"架构事实沉淀到该领域既有文档"原则。
• 建议（遵循根 AGENTS.md "Process artifacts" 规则）：不新增独立大文档，真正增量只有三块：(a) 统一 Command/Builtin/Plugin 三 Handler 的 Hook Registry/Engine 模型 → 并入 agent-runtime-services-design.md；(b) host.hook.call/host.tool.execute RPC 与 generation fencing 细节 → 并入 opencode-plugin-runtime-adapter-design.md §8.2；(c) deveco-harness 具体投影规则 → 作为 opencode-config-assets-adapter-design.md §5.2 的增量。其余全部改为交叉引用。若坚持独立文档，也必须先删掉与既有文档重复的陈述并改为引用。

B3. 断链：引用了未随本 PR 提交的文件

• 问题：§1 与 §18 链接 opencode-plugin-complete-compatibility-backlog.zh-CN.md，该文件不在本 PR（仅 2 个文件）也不在仓库；合并后即死链。且它建立第二套缺口跟踪源，与 opencode-extension-compatibility.md 审计矩阵 + docs/plans/opencode-extension-compatibility-plan.md 冲突。
• 风险：读者无法找到其余 Hook 的处理方式；两套 backlog 会分裂缺口状态。
• 建议：删除自建 backlog 概念，改链既有矩阵/计划；或将目标文件纳入本 PR 一并评审。

B4. 对 agent-runtime-services-design.md 的单行修改断言错误

• 问题：新注释"自身已是内部共享的可克隆句柄"与当前代码不符。实际 RuntimeHookRegistry 只是 Vec<RuntimeHookPlan> 的 derive(Clone) 包装（post_call_hooks.rs:132-135），clone 是独立副本、无内部共享；新文档 §3.1（"所有 clone 指向同一个内部状态"）描述的共享语义依赖 §3.3 展示的 Arc<RwLock<…>> 目标结构，属于未来改动而非现状。字段名 hooks 也与代码（runtime.rs:210 的 hook_registry）及新文档自身 §3.3 使用的 hook_registry 不一致。
• 风险：注释把"改造为内部共享"这一未来变更伪装成已成立前提，实现者可能按错误的共享语义编码。
• 建议：注释改为明确目标态（如 hooks: RuntimeHookRegistry, // target: inner Arc<RwLock<…>>；当前实现仅是 Vec 包装的独立 clone），并把字段名对齐 hook_registry。

B5. "Plugin Generation Coordinator" 与 plugin_host.rs 命名违反既有治理

• 问题：§3.1/§3.3/§7.3/§13 引入 "Plugin Generation Coordinator" 角色；§15 把 open/prepare/commit/rollback/close 协调职责放到 src/crates/assembly/core/src/plugin_host.rs。
• 事实：plugin-runtime-design.md:15 明确"不再为同一职责增加 Host、Controller、Manager 或 Coordinator 别名"；:52 明确"不得把 Rust 侧实现命名为 Host"。
• 风险：与既有角色体系冲突，实现时会再造一个与 PluginRuntimeClient/能力归属模块平行的生命周期管理对象。
• 建议：删除该别名与 plugin_host.rs 落点，把 generation 协调职责映射到既有"能力归属模块 + PluginRuntimeClient"边界；若确需新角色，先修订 plugin-runtime-design.md 再引用。

---

其他（建议一并修正）

1. §6.2 握手示例 "opencodeVersion": "1.17.18" 与仓库钉版不一致（opencode-extension-compatibility.md:24 为 v1.18.9、plugin-runtime-adapter 为 v1.18.4）且无说明；建议统一并交叉引用升级流程。
2. §4.1 的 RuntimeHookKind 枚举（含 Lifecycle/PluginHook）与当前实现（post_call_hooks.rs:11-14，仅 SuccessfulToolPostCall/DeepReviewSharedContextToolUse）差异未标注为目标变更；§4.6 的 with_registry 同理（见 B1）。
3. 本文设计将 OpenCode 插件 Hook 变为可执行，会关闭 agent-hooks.md:124 的 "intentionally excluded" 偏差；按 AGENTS.md 要求（偏差 added/closed 时必须更新 deviations 表），文档应记录"实现落地时同步 agent-hooks.md 偏差表"的待办。

---

结论：方向（统一 Hook Runtime + OpenCode function Hook 接入）有价值，但请按 B2 的裁剪方案重构文档归属，并修复 B1/B3/B4/B5 后再提交。