feat(runtime-hooks): #494 P6-lite builtin hooks 用户可配置体验闭环（builtin-only）

[Cai-Tang-www]

背景

当前 runtime hooks 已具备 P0~P5 主干能力，但从“用户可配置体验”角度仍有两个现实问题：

1. 外部 hook kind（command/http/prompt/agent）的拒绝语义不够显式
   • 在部分路径下虽然不会真正执行，但报错语义不够统一，不利于用户理解“P6-lite 只支持 builtin”。
2. 缺少“可直接复现”的用户级示例与端到端证明
   • repo hooks 示例已有，但全局 user hooks 的配置与触发链路缺少一份可复制模板与测试证据。

本 PR 聚焦 #494 的 P6-lite 最低闭环：builtin-only、安全可解释、可配置、可测试、可观测。

---

价值（Why this matters）

1) 降低误配与误解成本

当用户尝试写 kind: command/http/prompt/agent 时，系统现在会给出明确、统一、可操作的错误：

external hook kind "<kind>" is not supported in P6-lite; only builtin hooks are enabled

这比泛化的 “not supported” 更能解释当前阶段边界，减少反复试错。

2) 提升“用户自定义规则”可用性

补齐了全局 user hooks 示例和端到端触发测试，用户可直接按文档配置并验证：

• 配完即生效
• 生效后可在事件中看到 source=user
• 不需要阅读 runtime 内部代码才能确认系统行为

3) 保持安全边界不退化

在不开放 external hooks 的前提下，继续确保：

• repo hooks 仍由 trusted workspace gate 控制
• user/repo hooks 仍受 capability matrix 的 UserAllowed 限制
• 无 hooks 配置时主链行为不回归

---

用户故事（User Stories）

Story A：平台使用者（全局规则）

作为使用者，我希望在 ~/.neocode/config.yaml 中定义“调用 bash 前给 warning”这类规则，且系统能稳定触发并可观测。

本 PR 提供：

• 全局 user hooks 示例（runtime.hooks.items）
• 端到端测试证明 user_prompt_submit 触发后事件中 source=user 且 message 生效

Story B：仓库维护者（项目规则）

作为仓库维护者，我希望通过 <workspace>/.neocode/hooks.yaml 约束项目行为，但未 trust 的仓库不能自动执行这些规则。

本 PR保持并增强：

• repo hooks 发现/加载/跳过事件链路
• trust gate 仍是执行前置条件

Story C：安全审阅者（阶段边界）

作为安全审阅者，我希望外部执行类 hook 在 P6-lite 阶段被强拒绝，而不是“看起来可配置但行为不确定”。

本 PR实现：

• user/repo 侧均显式拒绝 external kinds
• 拒绝后不注册进 registry，不进入执行链

---

变更范围

代码变更

• internal/config/runtime_hooks.go
  • user hooks 配置校验新增 external kind 显式拒绝语义。
• internal/runtime/repo_hooks.go
  • repo hooks 校验新增 external kind 显式拒绝语义。
• internal/runtime/user_hooks.go
  • 增加 runtime 装配层兜底校验，避免绕过配置层验证导致 external kind 半生效。

测试补强

• internal/config/runtime_hooks_test.go
  • 覆盖 user external kinds（command/http/prompt/agent）拒绝与报错文案。
• internal/runtime/repo_hooks_test.go
  • 覆盖 repo external kinds 拒绝。
  • 新增 repo hook 执行事件 source=repo 断言。
• internal/runtime/user_hooks_test.go
  • 新增无 hooks 配置行为不变测试。
  • 新增 user external kind 拒绝且不注册测试。
  • 新增 端到端 user hook 触发测试：user_prompt_submit + add_context_note，断言 source=user 和 message。

文档与示例

• 新增 docs/examples/hooks.yaml（repo hooks 示例）
• 新增 docs/examples/user-hooks-config.yaml（全局 user hooks 示例）
• 更新 docs/guides/configuration.md
• 更新 docs/runtime-hooks-design.md

---

使用案例

案例 1：全局 user hook（P6-lite 推荐）

在 ~/.neocode/config.yaml 中配置：

• add_context_note 挂 user_prompt_submit
• warn_on_tool_call 挂 before_tool_call

参考示例：docs/examples/user-hooks-config.yaml

案例 2：仓库 repo hook（需 trust）

在仓库中配置 <workspace>/.neocode/hooks.yaml，并在 ~/.neocode/trusted-workspaces.json 中加入工作区。

参考示例：docs/examples/hooks.yaml

案例 3：误配 external kind

若配置 kind: command（或 http/prompt/agent），会被明确拒绝，不会注册、不执行。

---

兼容性与非目标

兼容性

• 不改变现有 internal -> user -> repo 执行链。
• 不改变 P7 的 before_completion_decision 特殊编排语义。
• 无 hooks 配置时行为保持不变。

非目标（明确不做）

• 不实现 command/http/prompt/agent external hooks。
• 不引入 external sandbox。
• 不改 Verification precheck / AcceptanceService（属于 P7 follow-up）。
• 不做 TUI 大改或 Gateway 外置队列改造。

---

测试

已执行并通过：

go test ./internal/config -run RuntimeHooks -count=1
go test ./internal/runtime -run "(RepoHook|RuntimeHooks|UserBuiltinHookConfiguredEndToEndOnUserPromptSubmit|BeforeCompletionDecision|Hook)" -count=1
go test ./internal/runtime/... -count=1

重点验证：

• user/repo external kind 全部拒绝
• rejected hook 不注册不执行
• repo source 事件可观测
• user 配置触发链路可观测（source=user）
• 无 hooks 配置不回归

---

风险与回滚

风险

• 主要是校验策略变严格：此前写错 kind 可能得到泛化报错，现在会得到阶段化拒绝文案（预期行为变化）。

回滚

• 本 PR 变更集中于 hooks 校验与测试/文档。
• 如需回滚，可按提交粒度回退，不影响 runtime 主推理链路和 provider 协议层。

---

关联

close #494

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[fennoai]

Reviewed the diff in four passes.

• Code quality: no noteworthy issues in the implementation changes.
• Performance: no issues found.
• Security: no issues found.
• Documentation: found one accuracy issue in docs/runtime-hooks-design.md.

[codecov]

Codecov Report

❌ Patch coverage is 86.11111% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runtime/user_hooks.go	80.00%	4 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!