Merge pull request #506 from Cai-Tang-www/feat/hook-p3

feat(runtime): P3 Repo Hooks + Workspace Trust Gate (#491)

Author: phantom5099

docs/guides/configuration.md

@@ -137,6 +137,52 @@ context:
 
 > 注意：`warn_only` 在 runtime 内部映射为 `fail_open`，表示记录失败但不阻断主链。
 
+### Repo Hooks（P3）
+
+仓库级 hooks 文件路径固定为：
+
+```text
+<workspace>/.neocode/hooks.yaml
+```
+
+执行受 trust gate 控制，默认不执行。只有当 workspace 出现在 `~/.neocode/trusted-workspaces.json` 中时才会加载。
+
+`hooks.yaml` 示例：
+
+```yaml
+hooks:
+  items:
+    - id: repo-readme-check
+      enabled: true
+      point: before_completion_decision
+      scope: repo
+      kind: builtin
+      mode: sync
+      handler: require_file_exists
+      params:
+        path: README.md
+        message: "请先补齐 README.md"
+```
+
+trust store 示例：
+
+```json
+{
+  "version": 1,
+  "workspaces": [
+    "/absolute/path/to/workspace"
+  ]
+}
+```
+
+约束说明：
+
+- `runtime.hooks.enabled=false` 会关闭全部 hooks（internal/user/repo）。
+- repo hooks 仅支持 builtin 子集（3 个 points + 3 个 handlers）。
+- 执行顺序固定：`internal -> user -> repo`。
+- 跨来源同 ID 允许并存；同来源内重复 ID 会报错。
+- trust store 缺失/空文件/损坏 JSON/结构错误时，按 untrusted 处理并发出 `repo_hooks_trust_store_invalid` 事件，不阻断启动。
+
 ## Budget 解析规则
 
 NeoCode 已不再使用旧的 `auto_compact` 阈值语义，当前统一使用 `context.budget`：

docs/runtime-hooks-design.md

@@ -9,10 +9,10 @@
 - 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`）
+- P3：repo hooks（`<workspace>/.neocode/hooks.yaml`）+ workspace trust gate（`~/.neocode/trusted-workspaces.json`）
 
 当前未实现能力：
 
-- repo hooks（P3）
 - async / async_rewake（P5）
 - command/http/prompt/agent hooks（P6）
 
@@ -26,16 +26,39 @@ P2 仅支持：
 - 挂载点：`before_tool_call`、`after_tool_result`、`before_completion_decision`
 - handler：`require_file_exists`、`warn_on_tool_call`、`add_context_note`
 
-P2 明确不支持：
+当前（P3）明确定义：
 
 - user hook 修改 tool 输入或 tool result
 - user hook 直接写入 provider-facing prompt
+- repo hook 修改 tool 输入或 tool result
+- repo hook 直接写入 provider-facing prompt
+
+## P3 repo hooks 边界
+
+repo hooks 文件路径固定为：
+
+```text
+<workspace>/.neocode/hooks.yaml
+```
+
+仅支持与 P2 相同的 builtin 子集（`kind=builtin`、`mode=sync`、3 个 points、3 个 handlers）。
+
+执行顺序固定为：
+
+```text
+internal -> user -> repo
+```
+
+冲突规则：
+
+- 同来源内重复 `id`：fail-fast
+- 跨来源同 `id`：允许并存（通过 `source` 区分）
 
 ## 安全模型
 
 ### 上下文裁剪
 
-user hook 接收的 `HookContext` 经过白名单裁剪，仅保留最小必要字段：
+user/repo hook 接收的 `HookContext` 经过白名单裁剪，仅保留最小必要字段：
 
 - `run_id` / `session_id`
 - `point` / `tool_call_id` / `tool_name`
@@ -48,7 +71,26 @@ user hook 接收的 `HookContext` 经过白名单裁剪，仅保留最小必要
 
 - API key / capability token
 - service 指针与 provider 客户端对象
-- 原始工具参数明文
+- 原始工具参数明文（`tool_arguments`）
+
+### trust gate
+
+repo hooks 默认不执行，仅 trusted workspace 会加载执行。
+
+trust store 固定路径：
+
+```text
+~/.neocode/trusted-workspaces.json
+```
+
+容错行为（统一降级为 untrusted，且不阻断启动）：
+
+- 文件缺失
+- 空文件
+- JSON 损坏
+- 结构不匹配
+
+上述异常会发出事件：`repo_hooks_trust_store_invalid`。
 
 ### 路径约束
 
@@ -66,9 +108,14 @@ runtime 会透传 hooks 生命周期事件：
 - `hook_finished`
 - `hook_failed`
 - `hook_blocked`
+- `repo_hooks_discovered`
+- `repo_hooks_loaded`
+- `repo_hooks_skipped_untrusted`
+- `repo_hooks_trust_store_invalid`
 
 `hook_finished/hook_failed` 包含 `message` 字段，用于承载 warning/note 文本。  
-user hook 的 `message` 同时进入 runtime 的 annotation buffer（运行态内存缓冲），用于后续观测与诊断。
+hook 事件额外携带 `source` 字段；展示层建议使用 `<source>:<id>`。  
+user/repo hook 的 `message` 会进入 runtime 的 annotation buffer（运行态内存缓冲），用于后续观测与诊断。
 
 ## 失败策略
 

internal/runtime/events.go

@@ -232,6 +232,7 @@ type HookEventPayload struct {
 	HookID     string    `json:"hook_id"`
 	Point      string    `json:"point"`
 	Scope      string    `json:"scope"`
+	Source     string    `json:"source"`
 	Kind       string    `json:"kind"`
 	Mode       string    `json:"mode"`
 	Status     string    `json:"status,omitempty"`
@@ -244,13 +245,29 @@ type HookEventPayload struct {
 // HookBlockedPayload 描述 hook 阻断事件负载。
 type HookBlockedPayload struct {
 	HookID     string `json:"hook_id"`
+	Source     string `json:"source,omitempty"`
 	Point      string `json:"point"`
 	ToolCallID string `json:"tool_call_id,omitempty"`
 	ToolName   string `json:"tool_name,omitempty"`
 	Reason     string `json:"reason,omitempty"`
 	Enforced   bool   `json:"enforced"`
 }
 
+// RepoHooksTrustStoreInvalidPayload 描述 trust store 不可用时的降级信息。
+type RepoHooksTrustStoreInvalidPayload struct {
+	TrustStorePath string `json:"trust_store_path"`
+	Reason         string `json:"reason"`
+}
+
+// RepoHooksLifecyclePayload 描述 repo hooks 发现/加载/跳过等生命周期信息。
+type RepoHooksLifecyclePayload struct {
+	Workspace      string `json:"workspace"`
+	HooksPath      string `json:"hooks_path,omitempty"`
+	TrustStorePath string `json:"trust_store_path,omitempty"`
+	HookCount      int    `json:"hook_count,omitempty"`
+	Reason         string `json:"reason,omitempty"`
+}
+
 const (
 	// EventUserMessage 表示用户消息已写入会话。
 	EventUserMessage EventType = "user_message"
@@ -334,6 +351,14 @@ const (
 	EventHookFailed EventType = "hook_failed"
 	// EventHookBlocked 表示某个 hook 返回 block（是否生效由 payload.enforced 决定）。
 	EventHookBlocked EventType = "hook_blocked"
+	// EventRepoHooksDiscovered 表示检测到仓库 hooks 配置文件。
+	EventRepoHooksDiscovered EventType = "repo_hooks_discovered"
+	// EventRepoHooksLoaded 表示仓库 hooks 已加载并进入执行链。
+	EventRepoHooksLoaded EventType = "repo_hooks_loaded"
+	// EventRepoHooksSkippedUntrusted 表示仓库未信任导致 repo hooks 被跳过。
+	EventRepoHooksSkippedUntrusted EventType = "repo_hooks_skipped_untrusted"
+	// EventRepoHooksTrustStoreInvalid 表示 trust store 缺失或损坏，已降级为 untrusted。
+	EventRepoHooksTrustStoreInvalid EventType = "repo_hooks_trust_store_invalid"
 )
 
 // TokenUsagePayload 承载单轮 token 用量统计。

internal/runtime/hooks/events.go

@@ -23,6 +23,7 @@ type HookEvent struct {
 	HookID     string
 	Point      HookPoint
 	Scope      HookScope
+	Source     HookSource
 	Kind       HookKind
 	Mode       HookMode
 	Status     HookResultStatus

internal/runtime/hooks/executor.go

@@ -61,7 +61,7 @@ func (e *Executor) Run(ctx context.Context, point HookPoint, input HookContext)
 	}
 	for _, spec := range specs {
 		hookInput := input.Clone()
-		if spec.Scope == HookScopeUser {
+		if spec.Scope == HookScopeUser || spec.Scope == HookScopeRepo {
 			hookInput = sanitizeUserHookContext(hookInput)
 		}
 		result := e.runOne(ctx, spec, hookInput)
@@ -70,11 +70,13 @@ func (e *Executor) Run(ctx context.Context, point HookPoint, input HookContext)
 		if result.Status == HookResultBlock {
 			output.Blocked = true
 			output.BlockedBy = spec.ID
+			output.BlockedSource = spec.Source
 			break
 		}
 		if result.Status == HookResultFailed && spec.FailurePolicy == FailurePolicyFailClosed {
 			output.Blocked = true
 			output.BlockedBy = spec.ID
+			output.BlockedSource = spec.Source
 			break
 		}
 	}
@@ -88,6 +90,7 @@ func (e *Executor) runOne(ctx context.Context, spec HookSpec, input HookContext)
 		HookID:    spec.ID,
 		Point:     spec.Point,
 		Scope:     spec.Scope,
+		Source:    spec.Source,
 		Kind:      spec.Kind,
 		Mode:      spec.Mode,
 		StartedAt: startedAt,
@@ -107,6 +110,9 @@ func (e *Executor) runOne(ctx context.Context, spec HookSpec, input HookContext)
 	if result.Scope == "" {
 		result.Scope = spec.Scope
 	}
+	if result.Source == "" {
+		result.Source = spec.Source
+	}
 	if result.DurationMS <= 0 {
 		result.DurationMS = durationMS
 	}
@@ -118,6 +124,7 @@ func (e *Executor) runOne(ctx context.Context, spec HookSpec, input HookContext)
 			HookID:     spec.ID,
 			Point:      spec.Point,
 			Scope:      spec.Scope,
+			Source:     spec.Source,
 			Kind:       spec.Kind,
 			Mode:       spec.Mode,
 			Status:     result.Status,
@@ -131,6 +138,7 @@ func (e *Executor) runOne(ctx context.Context, spec HookSpec, input HookContext)
 			HookID:     spec.ID,
 			Point:      spec.Point,
 			Scope:      spec.Scope,
+			Source:     spec.Source,
 			Kind:       spec.Kind,
 			Mode:       spec.Mode,
 			Status:     result.Status,
@@ -166,6 +174,7 @@ func (e *Executor) callHandler(
 			HookID:    spec.ID,
 			Point:     spec.Point,
 			Scope:     spec.Scope,
+			Source:    spec.Source,
 			Status:    HookResultFailed,
 			Message:   err,
 			Error:     err,
@@ -201,6 +210,7 @@ func (e *Executor) callHandler(
 			HookID:    spec.ID,
 			Point:     spec.Point,
 			Scope:     spec.Scope,
+			Source:    spec.Source,
 			Status:    HookResultFailed,
 			Message:   err,
 			Error:     err,
@@ -213,6 +223,7 @@ func (e *Executor) callHandler(
 				HookID:    spec.ID,
 				Point:     spec.Point,
 				Scope:     spec.Scope,
+				Source:    spec.Source,
 				Status:    HookResultFailed,
 				Message:   err,
 				Error:     err,
@@ -222,6 +233,7 @@ func (e *Executor) callHandler(
 		outcome.result.HookID = spec.ID
 		outcome.result.Point = spec.Point
 		outcome.result.Scope = spec.Scope
+		outcome.result.Source = spec.Source
 		if outcome.result.Status == "" {
 			outcome.result.Status = HookResultPass
 		}
@@ -233,6 +245,7 @@ func (e *Executor) callHandler(
 				HookID:    spec.ID,
 				Point:     spec.Point,
 				Scope:     spec.Scope,
+				Source:    spec.Source,
 				Status:    HookResultFailed,
 				Message:   err,
 				Error:     err,

internal/runtime/hooks/executor_test.go

@@ -704,3 +704,44 @@ func TestExecutorSanitizeUserHookContext(t *testing.T) {
 		t.Fatal("capability_token should be stripped for user hook context")
 	}
 }
+
+func TestExecutorSanitizeRepoHookContext(t *testing.T) {
+	t.Parallel()
+
+	registry := NewRegistry()
+	executor := NewExecutor(registry, nil, 100*time.Millisecond)
+	var captured HookContext
+	if err := registry.Register(HookSpec{
+		ID:     "repo-hook",
+		Point:  HookPointBeforeToolCall,
+		Scope:  HookScopeRepo,
+		Source: HookSourceRepo,
+		Handler: func(_ context.Context, input HookContext) HookResult {
+			captured = input
+			return HookResult{Status: HookResultPass}
+		},
+	}); err != nil {
+		t.Fatalf("Register() error = %v", err)
+	}
+
+	_ = executor.Run(context.Background(), HookPointBeforeToolCall, HookContext{
+		RunID:     "run-1",
+		SessionID: "session-1",
+		Metadata: map[string]any{
+			"tool_name":        "bash",
+			"tool_arguments":   "--secret-token=abc",
+			"capability_token": "should-not-leak",
+			"workdir":          "/tmp/work",
+		},
+	})
+
+	if got := captured.Metadata["tool_name"]; got != "bash" {
+		t.Fatalf("tool_name = %v, want bash", got)
+	}
+	if _, exists := captured.Metadata["tool_arguments"]; exists {
+		t.Fatal("tool_arguments should be stripped for repo hook context")
+	}
+	if _, exists := captured.Metadata["capability_token"]; exists {
+		t.Fatal("capability_token should be stripped for repo hook context")
+	}
+}

internal/runtime/hooks/registry.go

@@ -43,12 +43,13 @@ func (r *Registry) Register(spec HookSpec) error {
 
 	r.mu.Lock()
 	defer r.mu.Unlock()
-	if _, exists := r.hooks[normalized.ID]; exists {
-		return fmt.Errorf("%w: %s", ErrHookAlreadyExists, normalized.ID)
+	key := registryHookKey(normalized.Source, normalized.ID)
+	if _, exists := r.hooks[key]; exists {
+		return fmt.Errorf("%w: %s:%s", ErrHookAlreadyExists, normalized.Source, normalized.ID)
 	}
 
 	r.seq++
-	r.hooks[normalized.ID] = registryEntry{
+	r.hooks[key] = registryEntry{
 		spec: normalized,
 		seq:  r.seq,
 	}
@@ -67,10 +68,16 @@ func (r *Registry) Remove(id string) error {
 
 	r.mu.Lock()
 	defer r.mu.Unlock()
-	if _, exists := r.hooks[id]; !exists {
+	removed := false
+	for key, entry := range r.hooks {
+		if strings.EqualFold(strings.TrimSpace(entry.spec.ID), id) {
+			delete(r.hooks, key)
+			removed = true
+		}
+	}
+	if !removed {
 		return fmt.Errorf("%w: %s", ErrHookNotFound, id)
 	}
-	delete(r.hooks, id)
 	return nil
 }
 
@@ -110,3 +117,7 @@ func (r *Registry) Resolve(point HookPoint) []HookSpec {
 	}
 	return out
 }
+
+func registryHookKey(source HookSource, id string) string {
+	return strings.ToLower(strings.TrimSpace(string(source))) + "\x00" + strings.ToLower(strings.TrimSpace(id))
+}