Merge pull request #715 from Cai-Tang-www/codex/feat-hook-payload-schema-685

feat(hooks): publish and version hook payload schema

Author: wynxing

docs/reference/hook-payload.v1.json

@@ -55,8 +55,8 @@ repo hooks 文件路径固定为：
 <workspace>/.neocode/hooks.yaml
 ```
 
-仅支持与 P2 相同的 builtin 子集（`kind=builtin`、`mode=sync`、`UserAllowed=true` points、3 个 handlers）。
-repo hooks 暂不支持 `kind=http`，external kinds（`command/http/prompt/agent`）在 repo 侧仍显式拒绝。
+支持与 P2 相同的 builtin 子集（`kind=builtin`、`mode=sync`、`UserAllowed=true` points、3 个 handlers），并开放 `kind=command + mode=sync`。
+repo hooks 仍不支持 `kind=http`；external kinds 中当前仅 `command` 开放，`prompt/agent` 仍显式拒绝。
 
 执行顺序固定为：
 
@@ -73,22 +73,55 @@ internal -> user -> repo
 
 ### 上下文裁剪
 
-user/repo hook 接收的 `HookContext` 经过白名单裁剪，仅保留最小必要字段：
+user/repo hook 接收的 `HookContext` 经过点位感知的 payload schema 裁剪，仅保留最小必要字段：
 
-- `run_id` / `session_id`
-- `point` / `tool_call_id` / `tool_name`
-- `tool_arguments_preview`（脱敏+截断后的参数预览）
-- `is_error` / `error_class`
-- `result_content_preview` / `result_metadata_present`
-- `execution_error`
-- `workdir`
+- 顶层字段：`run_id` / `session_id`
+- metadata 字段：按 `point` 不同暴露对应的最小子集，例如 `tool_call_id`、`tool_name`、`workdir`
+- 预览/摘要类字段：`tool_arguments_preview`、`result_content_preview`、`todo_summary`、`recent_tool_summary`
+- 完整机器可读契约见 `docs/reference/hook-payload.v1.json`
 
 不会暴露：
 
 - API key / capability token
 - service 指针与 provider 客户端对象
 - 原始工具参数明文（`tool_arguments`）
 
+### Payload Schema
+
+Hook payload 已从 runtime 内部白名单提升为公开契约：
+
+- 版本号真源：`internal/runtime/hooks.PayloadVersion`
+- 当前版本：`payload_version: "1"`
+- 生成命令：`go generate ./internal/runtime/hooks`
+- 生成产物：`docs/reference/hook-payload.v1.json`
+- command stdin 与 HTTP observe body 都带 `payload_version`
+- HTTP observe 在共享字段之外，继续保留 `scope`、`kind`、`mode`、`triggered_at` 作为 transport 附加字段
+- `metadata.point`、`completion_passed`、`has_tool_calls`、`assistant_role` 这类未由 runtime 真实生产的字段不再公开
+
+稳定性分级：
+
+- `stable`：身份/控制类字段，默认兼容承诺
+- `experimental`：预览/摘要类字段，当前包括 `tool_arguments_preview`、`result_content_preview`、`todo_summary`、`recent_tool_summary`
+- `deprecated`：保留给后续版本迁移，本版未使用
+
+各点位 metadata 字段：
+
+| point | metadata fields |
+|---|---|
+| `before_tool_call` | `run_id`, `session_id`, `tool_call_id`, `tool_name`, `tool_arguments_preview` (experimental), `workdir` |
+| `after_tool_result` | `run_id`, `session_id`, `tool_call_id`, `tool_name`, `is_error`, `error_class`, `result_content_preview` (experimental), `result_metadata_present`, `execution_error`, `workdir` |
+| `before_completion_decision` | `run_id`, `session_id` |
+| `accept_gate` | `run_id`, `session_id`, `workdir`, `workspace_changed`, `assistant_text_empty`, `todo_summary` (experimental), `recent_tool_summary` (experimental) |
+| `before_permission_decision` | `run_id`, `session_id`, `tool_call_id`, `tool_name`, `decision`, `reason`, `rule_id`, `workdir` |
+| `after_tool_failure` | `run_id`, `session_id`, `tool_call_id`, `tool_name`, `tool_arguments_preview` (experimental), `is_error`, `error_class`, `execution_error`, `result_content_preview` (experimental), `workdir` |
+| `session_start` | `run_id`, `session_id`, `workdir` |
+| `session_end` | `run_id`, `session_id`, `stop_reason`, `detail` |
+| `user_prompt_submit` | `run_id`, `session_id`, `workdir` |
+| `pre_compact` | `run_id`, `session_id`, `workdir`, `trigger_mode` |
+| `post_compact` | `run_id`, `session_id`, `workdir`, `trigger_mode`, `applied` |
+| `subagent_start` | `run_id`, `session_id`, `task_id`, `role`, `workspace`, `tool_name`, `trigger`, `workdir` |
+| `subagent_stop` | `run_id`, `session_id`, `task_id`, `role`, `state`, `stop_reason`, `step_count`, `error` |
+
 ### 点位能力矩阵（P4）
 
 runtime 内置 `HookPointCapability` 作为唯一真源，定义每个点位是否允许 block/observe/update_input 以及是否允许 user/repo 挂载。
@@ -184,6 +217,7 @@ trust store 固定路径：
 - `hook_id`：hook 配置中的 `id`
 - `point`：触发点位名称
 - `metadata`：经白名单裁剪后的上下文字段（与 builtin/http hook 相同的 allowlist）
+- 完整字段表与稳定性分级见 `docs/reference/hook-payload.v1.json`
 
 ### stdout 协议
 

docs/runtime-hooks-design.md

@@ -0,0 +1,29 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	runtimehooks "neo-code/internal/runtime/hooks"
+)
+
+func main() {
+	content, err := runtimehooks.MarshalPayloadJSONSchema()
+	if err != nil {
+		fail(err)
+	}
+	targetPath := filepath.Clean(filepath.Join("..", "..", "..", "docs", "reference", schemaFileName()))
+	if err := os.WriteFile(targetPath, content, 0o644); err != nil {
+		fail(err)
+	}
+}
+
+func schemaFileName() string {
+	return fmt.Sprintf("hook-payload.v%s.json", runtimehooks.PayloadVersion)
+}
+
+func fail(err error) {
+	_, _ = fmt.Fprintf(os.Stderr, "generate hook payload schema: %v\n", err)
+	os.Exit(1)
+}

internal/runtime/hooks/cmd/hookpayloadschema/main.go

@@ -14,7 +14,7 @@ import (
 )
 
 // CommandHookPayloadVersion 定义 command hook stdin 协议版本号，变更 stdin 结构时递增。
-const CommandHookPayloadVersion = "1"
+const CommandHookPayloadVersion = PayloadVersion
 
 // maxCommandStdoutBytes 限制外部命令 stdout 最大读取字节数，防止 OOM。
 const maxCommandStdoutBytes = 1 << 20 // 1 MiB
@@ -109,14 +109,14 @@ func ParseCommandParams(params map[string]any) (argv []string, shell bool, err e
 // BuildCommandPayload 构造传给外部命令的 stdin JSON payload。
 func BuildCommandPayload(hookID string, point HookPoint, input HookContext) CommandHookPayload {
 	payload := CommandHookPayload{
-		PayloadVersion: CommandHookPayloadVersion,
+		PayloadVersion: PayloadVersion,
 		HookID:         strings.TrimSpace(hookID),
 		Point:          string(point),
 		RunID:          strings.TrimSpace(input.RunID),
 		SessionID:      strings.TrimSpace(input.SessionID),
 	}
-	if len(input.Metadata) > 0 {
-		payload.Metadata = input.Metadata
+	if metadata := sanitizePayloadMetadata(point, input.Metadata); len(metadata) > 0 {
+		payload.Metadata = metadata
 	}
 	return payload
 }
@@ -256,7 +256,7 @@ func buildCommandEnv(spec CommandHookSpec) []string {
 	env := []string{
 		"NEOCODE_HOOK_HOOK_ID=" + spec.HookID,
 		"NEOCODE_HOOK_POINT=" + string(spec.Point),
-		"NEOCODE_HOOK_PAYLOAD_VERSION=" + CommandHookPayloadVersion,
+		"NEOCODE_HOOK_PAYLOAD_VERSION=" + PayloadVersion,
 	}
 	if runtime.GOOS == "windows" {
 		for _, key := range []string{"SystemRoot", "SystemDrive", "USERPROFILE"} {

internal/runtime/hooks/command_handler.go

@@ -18,12 +18,14 @@ func TestBuildCommandPayload(t *testing.T) {
 		RunID:     "run-123",
 		SessionID: "sess-456",
 		Metadata: map[string]any{
-			"tool_name": "bash",
-			"workdir":   "/tmp",
+			"tool_name":        "bash",
+			"workdir":          "/tmp",
+			"tool_arguments":   "rm -rf /tmp",
+			"capability_token": "secret",
 		},
 	})
-	if payload.PayloadVersion != CommandHookPayloadVersion {
-		t.Fatalf("payload_version = %q, want %q", payload.PayloadVersion, CommandHookPayloadVersion)
+	if payload.PayloadVersion != PayloadVersion {
+		t.Fatalf("payload_version = %q, want %q", payload.PayloadVersion, PayloadVersion)
 	}
 	if payload.HookID != "my-hook" {
 		t.Fatalf("hook_id = %q, want %q", payload.HookID, "my-hook")
@@ -40,6 +42,12 @@ func TestBuildCommandPayload(t *testing.T) {
 	if payload.Metadata["tool_name"] != "bash" {
 		t.Fatalf("metadata[tool_name] = %v, want %q", payload.Metadata["tool_name"], "bash")
 	}
+	if _, exists := payload.Metadata["tool_arguments"]; exists {
+		t.Fatal("metadata[tool_arguments] should be stripped by payload schema")
+	}
+	if _, exists := payload.Metadata["capability_token"]; exists {
+		t.Fatal("metadata[capability_token] should be stripped by payload schema")
+	}
 }
 
 func TestBuildCommandPayloadEmptyMetadata(t *testing.T) {
@@ -723,13 +731,13 @@ func TestRunCommandHookStdinPayloadWithMetadata(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		spec = CommandHookSpec{
 			HookID:  "stdin-meta",
-			Point:   HookPointUserPromptSubmit,
+			Point:   HookPointBeforeToolCall,
 			Command: []string{"powershell", "-Command", "$input"},
 		}
 	} else {
 		spec = CommandHookSpec{
 			HookID:  "stdin-meta",
-			Point:   HookPointUserPromptSubmit,
+			Point:   HookPointBeforeToolCall,
 			Command: []string{"cat"},
 		}
 	}

internal/runtime/hooks/command_handler_test.go

@@ -0,0 +1,3 @@
+package hooks
+
+//go:generate go run ./cmd/hookpayloadschema

internal/runtime/hooks/docgen_generate.go

@@ -77,7 +77,7 @@ func (e *Executor) Run(ctx context.Context, point HookPoint, input HookContext)
 	for _, spec := range specs {
 		hookInput := input.Clone()
 		if spec.Scope == HookScopeUser || spec.Scope == HookScopeRepo {
-			hookInput = sanitizeUserHookContext(hookInput)
+			hookInput = sanitizeUserHookContext(spec.Point, hookInput)
 		}
 		if spec.Matcher != nil && !spec.Matcher.Match(hookInput) {
 			continue
@@ -331,59 +331,12 @@ func (e *Executor) callHandler(
 	}
 }
 
-func sanitizeUserHookContext(input HookContext) HookContext {
+func sanitizeUserHookContext(point HookPoint, input HookContext) HookContext {
 	sanitized := HookContext{
 		RunID:     strings.TrimSpace(input.RunID),
 		SessionID: strings.TrimSpace(input.SessionID),
 	}
-	if len(input.Metadata) == 0 {
-		return sanitized
-	}
-	allowedMetadataKeys := map[string]struct{}{
-		"point":                   {},
-		"tool_call_id":            {},
-		"tool_name":               {},
-		"tool_arguments_preview":  {},
-		"is_error":                {},
-		"error_class":             {},
-		"result_content_preview":  {},
-		"result_metadata_present": {},
-		"execution_error":         {},
-		"workdir":                 {},
-		"session_id":              {},
-		"run_id":                  {},
-		"task_id":                 {},
-		"role":                    {},
-		"workspace":               {},
-		"trigger":                 {},
-		"state":                   {},
-		"stop_reason":             {},
-		"step_count":              {},
-		"error":                   {},
-		"trigger_mode":            {},
-		"applied":                 {},
-		"decision":                {},
-		"reason":                  {},
-		"rule_id":                 {},
-		"completion_passed":       {},
-		"has_tool_calls":          {},
-		"assistant_role":          {},
-		"detail":                  {},
-		"workspace_changed":       {},
-		"assistant_text_empty":    {},
-		"todo_summary":            {},
-		"recent_tool_summary":     {},
-	}
-	for key, value := range input.Metadata {
-		normalizedKey := strings.ToLower(strings.TrimSpace(key))
-		if _, ok := allowedMetadataKeys[normalizedKey]; !ok {
-			continue
-		}
-		if sanitized.Metadata == nil {
-			sanitized.Metadata = make(map[string]any, len(input.Metadata))
-		}
-		sanitized.Metadata[normalizedKey] = cloneMetadataValue(value)
-	}
+	sanitized.Metadata = sanitizePayloadMetadata(point, input.Metadata)
 	return sanitized
 }
 

internal/runtime/hooks/executor.go

@@ -959,6 +959,8 @@ func TestExecutorSanitizeUserHookContext(t *testing.T) {
 			"tool_arguments":         "--secret-token=abc",
 			"tool_arguments_preview": "token=***",
 			"capability_token":       "should-not-leak",
+			"completion_passed":      true,
+			"assistant_role":         "assistant",
 			"workdir":                "/tmp/work",
 		},
 	})
@@ -978,6 +980,12 @@ func TestExecutorSanitizeUserHookContext(t *testing.T) {
 	if _, exists := captured.Metadata["capability_token"]; exists {
 		t.Fatal("capability_token should be stripped for user hook context")
 	}
+	if _, exists := captured.Metadata["completion_passed"]; exists {
+		t.Fatal("completion_passed should be stripped when not produced by runtime")
+	}
+	if _, exists := captured.Metadata["assistant_role"]; exists {
+		t.Fatal("assistant_role should be stripped when not produced by runtime")
+	}
 }
 
 func TestExecutorSanitizeRepoHookContext(t *testing.T) {
@@ -1007,6 +1015,8 @@ func TestExecutorSanitizeRepoHookContext(t *testing.T) {
 			"tool_arguments":         "--secret-token=abc",
 			"tool_arguments_preview": "token=***",
 			"capability_token":       "should-not-leak",
+			"completion_passed":      true,
+			"assistant_role":         "assistant",
 			"workdir":                "/tmp/work",
 		},
 	})
@@ -1023,6 +1033,12 @@ func TestExecutorSanitizeRepoHookContext(t *testing.T) {
 	if _, exists := captured.Metadata["capability_token"]; exists {
 		t.Fatal("capability_token should be stripped for repo hook context")
 	}
+	if _, exists := captured.Metadata["completion_passed"]; exists {
+		t.Fatal("completion_passed should be stripped for repo hook context")
+	}
+	if _, exists := captured.Metadata["assistant_role"]; exists {
+		t.Fatal("assistant_role should be stripped for repo hook context")
+	}
 }
 
 func TestExecutorSkipsHookWhenMatcherMissed(t *testing.T) {
@@ -1052,4 +1068,3 @@ func TestExecutorSkipsHookWhenMatcherMissed(t *testing.T) {
 		t.Fatalf("len(Results) = %d, want 0 when matcher missed", len(output.Results))
 	}
 }
-