Merge pull request #504 from Cai-Tang-www/feat/issue-490-user-builtin-hooks-p2

feat(runtime): P2 全局 User Builtin Hooks 接入与安全裁剪（#490）

Author: phantom5099

docs/guides/configuration.md

@@ -29,6 +29,23 @@ runtime:
   max_no_progress_streak: 5
   max_repeat_cycle_streak: 3
   max_turns: 90
+  hooks:
+    enabled: true
+    user_hooks_enabled: true
+    default_timeout_sec: 2
+    default_failure_policy: warn_only
+    items:
+      - id: warn-bash
+        enabled: true
+        point: before_tool_call
+        scope: user
+        kind: builtin
+        mode: sync
+        handler: warn_on_tool_call
+        priority: 100
+        params:
+          tool_name: bash
+          message: "bash tool is invoked"
   assets:
     max_session_asset_bytes: 20971520
     max_session_assets_total_bytes: 20971520
@@ -94,9 +111,32 @@ context:
 | `runtime.max_no_progress_streak` | 连续“无进展”轮次提醒阈值，默认 `5`；达到 `limit-1` 起会向模型注入纠偏提示，不会直接终止运行 |
 | `runtime.max_repeat_cycle_streak` | 连续“重复调用同一工具参数”提醒阈值，默认 `3`；达到阈值后触发重复循环提醒，不会直接终止运行 |
 | `runtime.max_turns` | 单次 Run 的最大推理轮数上限，默认 `40`；达到上限后直接终止并返回明确 stop reason |
+| `runtime.hooks.enabled` | hooks 总开关；关闭后不执行 runtime hooks |
+| `runtime.hooks.user_hooks_enabled` | user hooks 开关；关闭后不加载 `runtime.hooks.items` |
+| `runtime.hooks.default_timeout_sec` | user hook 默认超时秒数，需 `> 0` |
+| `runtime.hooks.default_failure_policy` | 默认失败策略，支持 `warn_only` / `fail_open` / `fail_closed` |
+| `runtime.hooks.items` | user builtin hooks 列表；仅支持 `scope=user`、`kind=builtin`、`mode=sync` |
 | `runtime.assets.max_session_asset_bytes` | 单个 `session_asset` 最大原始字节数，默认 `20971520`（20 MiB）；`0` 或未配置时回退默认值 |
 | `runtime.assets.max_session_assets_total_bytes` | 单次请求可携带的 `session_asset` 原始总字节上限，默认 `20971520`（20 MiB）；`0` 或未配置时回退默认值 |
 
+### `runtime.hooks.items` 字段约束
+
+| 字段 | 说明 |
+|------|------|
+| `id` | hook 唯一标识，同一配置文件内不可重复 |
+| `enabled` | 是否启用该 hook，默认 `true` |
+| `point` | 仅支持 `before_tool_call` / `after_tool_result` / `before_completion_decision` |
+| `scope` | P2 固定为 `user` |
+| `kind` | P2 固定为 `builtin` |
+| `mode` | P2 固定为 `sync` |
+| `handler` | 仅支持 `require_file_exists` / `warn_on_tool_call` / `add_context_note` |
+| `priority` | 同一 hook point 内执行优先级，数值越大越先执行 |
+| `timeout_sec` | 覆盖默认超时；未配置时继承 `runtime.hooks.default_timeout_sec` |
+| `failure_policy` | 覆盖默认失败策略；未配置时继承 `runtime.hooks.default_failure_policy` |
+| `params` | handler 参数；不同 handler 使用不同键 |
+
+> 注意：`warn_only` 在 runtime 内部映射为 `fail_open`，表示记录失败但不阻断主链。
+
 ## Budget 解析规则
 
 NeoCode 已不再使用旧的 `auto_compact` 阈值语义，当前统一使用 `context.budget`：

docs/runtime-hooks-design.md

@@ -0,0 +1,87 @@
+# Runtime Hooks 设计说明
+
+本文记录 NeoCode runtime hooks 的当前实现边界与约束，确保配置、运行时行为与可观测性一致。
+
+## 当前阶段
+
+当前已实现能力：
+
+- P0：hooks core（registry / executor / timeout / panic recover / failure policy / hook events）
+- P1：接入 `before_tool_call`、`after_tool_result`、`before_completion_decision`
+- P2：全局 user builtin hooks（`runtime.hooks`）
+
+当前未实现能力：
+
+- repo hooks（P3）
+- async / async_rewake（P5）
+- command/http/prompt/agent hooks（P6）
+
+## P2 user hooks 边界
+
+P2 仅支持：
+
+- `scope=user`
+- `kind=builtin`
+- `mode=sync`
+- 挂载点：`before_tool_call`、`after_tool_result`、`before_completion_decision`
+- handler：`require_file_exists`、`warn_on_tool_call`、`add_context_note`
+
+P2 明确不支持：
+
+- user hook 修改 tool 输入或 tool result
+- user hook 直接写入 provider-facing prompt
+
+## 安全模型
+
+### 上下文裁剪
+
+user hook 接收的 `HookContext` 经过白名单裁剪，仅保留最小必要字段：
+
+- `run_id` / `session_id`
+- `point` / `tool_call_id` / `tool_name`
+- `is_error` / `error_class`
+- `result_content_preview` / `result_metadata_present`
+- `execution_error`
+- `workdir`
+
+不会暴露：
+
+- API key / capability token
+- service 指针与 provider 客户端对象
+- 原始工具参数明文
+
+### 路径约束
+
+`require_file_exists` 对 `params.path` 强制执行工作目录边界检查：
+
+- 相对路径按当前运行 workdir 解析
+- 绝对路径必须位于 workdir 内
+- symlink 路径会进行 realpath 校验，禁止绕过
+
+## 可观测性
+
+runtime 会透传 hooks 生命周期事件：
+
+- `hook_started`
+- `hook_finished`
+- `hook_failed`
+- `hook_blocked`
+
+`hook_finished/hook_failed` 包含 `message` 字段，用于承载 warning/note 文本。  
+user hook 的 `message` 同时进入 runtime 的 annotation buffer（运行态内存缓冲），用于后续观测与诊断。
+
+## 失败策略
+
+配置层支持：
+
+- `warn_only`
+- `fail_open`
+- `fail_closed`
+
+运行时映射：
+
+- `warn_only` -> `fail_open`
+- `fail_open` -> `fail_open`
+- `fail_closed` -> `fail_closed`
+
+其中 `warn_only/fail_open` 不阻断主链，仅记录失败；`fail_closed` 触发阻断。

internal/app/bootstrap.go

@@ -212,6 +212,9 @@ func BuildGatewayServerDeps(ctx context.Context, opts BootstrapOptions) (Runtime
 			return resolution.PromptBudget, string(resolution.Source), nil
 		},
 	))
+	if err := agentruntime.ConfigureRuntimeHooks(runtimeSvc, cfg); err != nil {
+		return RuntimeBundle{}, err
+	}
 
 	// 注入记忆提取钩子：当 AutoExtract 启用且 memoSvc 可用时，ReAct 循环完成后异步提取记忆。
 	if memoSvc != nil && cfg.Memo.AutoExtract {

internal/config/loader_test.go

@@ -101,6 +101,80 @@ func TestLoaderLoadMalformedYAML(t *testing.T) {
 	}
 }
 
+func TestLoaderLoadRuntimeHooksConfig(t *testing.T) {
+	t.Parallel()
+
+	loader := NewLoader(t.TempDir(), testDefaultConfig())
+	raw := `
+selected_provider: openai
+current_model: gpt-4.1
+shell: powershell
+runtime:
+  hooks:
+    enabled: true
+    user_hooks_enabled: true
+    default_timeout_sec: 3
+    default_failure_policy: warn_only
+    items:
+      - id: warn-bash
+        enabled: true
+        point: before_tool_call
+        scope: user
+        kind: builtin
+        mode: sync
+        handler: warn_on_tool_call
+        priority: 100
+        timeout_sec: 2
+        failure_policy: warn_only
+        params:
+          tool_name: bash
+          message: "bash is called"
+`
+	writeLoaderConfig(t, loader, raw)
+	cfg, err := loader.Load(context.Background())
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if cfg == nil {
+		t.Fatal("cfg is nil")
+	}
+	if !cfg.Runtime.Hooks.IsEnabled() || !cfg.Runtime.Hooks.IsUserHooksEnabled() {
+		t.Fatalf("unexpected hook switches: %+v", cfg.Runtime.Hooks)
+	}
+	if len(cfg.Runtime.Hooks.Items) != 1 {
+		t.Fatalf("len(items)=%d, want 1", len(cfg.Runtime.Hooks.Items))
+	}
+	item := cfg.Runtime.Hooks.Items[0]
+	if item.Handler != "warn_on_tool_call" {
+		t.Fatalf("handler=%q, want warn_on_tool_call", item.Handler)
+	}
+}
+
+func TestLoaderRejectsUnsupportedRuntimeHookHandler(t *testing.T) {
+	t.Parallel()
+
+	loader := NewLoader(t.TempDir(), testDefaultConfig())
+	raw := `
+selected_provider: openai
+current_model: gpt-4.1
+shell: powershell
+runtime:
+  hooks:
+    items:
+      - id: invalid-handler
+        point: before_tool_call
+        scope: user
+        kind: builtin
+        mode: sync
+        handler: shell_exec
+`
+	writeLoaderConfig(t, loader, raw)
+	_, err := loader.Load(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "runtime.hooks.items[0]") {
+		t.Fatalf("expected runtime hooks validation error, got %v", err)
+	}
+}
+
 func TestLoaderRejectsLegacyWorkdirKey(t *testing.T) {
 	t.Parallel()
 

internal/config/runtime.go

@@ -19,6 +19,7 @@ type RuntimeConfig struct {
 	MaxRepeatCycleStreak int                 `yaml:"max_repeat_cycle_streak,omitempty"`
 	MaxTurns             int                 `yaml:"max_turns,omitempty"`
 	Verification         VerificationConfig  `yaml:"verification,omitempty"`
+	Hooks                RuntimeHooksConfig  `yaml:"hooks,omitempty"`
 	Assets               RuntimeAssetsConfig `yaml:"assets,omitempty"`
 }
 
@@ -35,6 +36,7 @@ func defaultRuntimeConfig() RuntimeConfig {
 		MaxRepeatCycleStreak: DefaultMaxRepeatCycleStreak,
 		MaxTurns:             DefaultMaxTurns,
 		Verification:         defaultVerificationConfig(),
+		Hooks:                defaultRuntimeHooksConfig(),
 		Assets:               defaultRuntimeAssetsConfig(),
 	}
 }
@@ -54,6 +56,7 @@ func (c RuntimeConfig) Clone() RuntimeConfig {
 		MaxRepeatCycleStreak: c.MaxRepeatCycleStreak,
 		MaxTurns:             c.MaxTurns,
 		Verification:         c.Verification.Clone(),
+		Hooks:                c.Hooks.Clone(),
 		Assets:               c.Assets.Clone(),
 	}
 }
@@ -73,6 +76,7 @@ func (c *RuntimeConfig) ApplyDefaults(defaults RuntimeConfig) {
 		c.MaxTurns = defaults.MaxTurns
 	}
 	c.Verification.ApplyDefaults(defaults.Verification)
+	c.Hooks.ApplyDefaults(defaults.Hooks)
 	c.Assets.ApplyDefaults(defaults.Assets)
 }
 
@@ -92,6 +96,11 @@ func (c RuntimeConfig) Validate() error {
 	if err := verification.Validate(); err != nil {
 		return err
 	}
+	hooks := c.Hooks.Clone()
+	hooks.ApplyDefaults(defaultRuntimeHooksConfig())
+	if err := hooks.Validate(); err != nil {
+		return err
+	}
 	if err := c.Assets.Validate(); err != nil {
 		return err
 	}