fix hook matcher validation and preview sanitization

Author: Cai-Tang-www

docs/runtime-hooks-design.md

@@ -129,8 +129,7 @@ runtime 内置 `HookPointCapability` 作为唯一真源，定义每个点位是
 说明：
 
 - `arguments_contains` 基于 `tool_arguments_preview` 字段匹配，不读取 `tool_arguments` 原文。
-- `warn_on_tool_call` 的旧参数 `params.tool_name/tool_names` 仍兼容；未配置 `match` 时会自动桥接为 matcher。
-- 若 `match` 与旧参数共存，以 `match` 为准，并发出 `hook_notification` 迁移提示事件。
+- `warn_on_tool_call` 当前要求显式配置 `match`；旧参数 `params.tool_name/tool_names` 不再承担匹配语义。
 
 ### trust gate
 

internal/runtime/hooks/matcher.go

@@ -54,6 +54,9 @@ func CompileHookMatcher(point HookPoint, raw map[string]any) (*HookMatcher, erro
 	if len(raw) == 0 {
 		return nil, nil
 	}
+	if err := validateHookMatcherFields(raw); err != nil {
+		return nil, err
+	}
 	if !HasHookMatcherConfig(raw) {
 		return nil, fmt.Errorf("match contains no recognized matcher fields (expected: tool_name, tool_name_regex, arguments_contains)")
 	}
@@ -104,6 +107,26 @@ func CompileHookMatcher(point HookPoint, raw map[string]any) (*HookMatcher, erro
 	return matcher, nil
 }
 
+// validateHookMatcherFields 校验 matcher 配置中不存在未支持字段，避免拼写错误被静默忽略。
+func validateHookMatcherFields(raw map[string]any) error {
+	if len(raw) == 0 {
+		return nil
+	}
+	for key := range raw {
+		normalized := strings.ToLower(strings.TrimSpace(key))
+		switch normalized {
+		case hookMatcherFieldToolName, hookMatcherFieldToolNameRegex, hookMatcherFieldArgumentsContains:
+			continue
+		default:
+			return fmt.Errorf(
+				"match contains unknown field %q (allowed: tool_name, tool_name_regex, arguments_contains)",
+				key,
+			)
+		}
+	}
+	return nil
+}
+
 // IsEmpty 判断 matcher 是否包含可执行维度。
 func (m *HookMatcher) IsEmpty() bool {
 	if m == nil {

internal/runtime/hooks/matcher_test.go

@@ -111,6 +111,12 @@ func TestCompileHookMatcherValidation(t *testing.T) {
 	}); err == nil {
 		t.Fatal("expected completely unknown matcher field to be rejected")
 	}
+	if _, err := CompileHookMatcher(HookPointBeforeToolCall, map[string]any{
+		"tool_name":  "bash",
+		"tool_names": []any{"filesystem"},
+	}); err == nil {
+		t.Fatal("expected mixed matcher fields with typo to be rejected")
+	}
 
 	if _, err := CompileHookMatcher(HookPointBeforeToolCall, nil); err != nil {
 		t.Fatal("nil raw should succeed with nil matcher")
@@ -306,8 +312,8 @@ func TestCompileHookMatcherRegexWhitespaceSkipped(t *testing.T) {
 	t.Parallel()
 
 	matcher, err := CompileHookMatcher(HookPointBeforeToolCall, map[string]any{
-		"tool_name":          "bash",
-		"tool_name_regex":    []string{"  ", "\t"},
+		"tool_name":       "bash",
+		"tool_name_regex": []string{"  ", "\t"},
 	})
 	if err != nil {
 		t.Fatalf("CompileHookMatcher() error = %v", err)
@@ -320,7 +326,6 @@ func TestCompileHookMatcherRegexWhitespaceSkipped(t *testing.T) {
 	}
 }
 
-
 func TestCompileHookMatcherRegexOnly(t *testing.T) {
 	t.Parallel()
 

internal/runtime/toolexec.go

@@ -10,6 +10,7 @@ import (
 	"sort"
 	"strings"
 	"sync"
+	"unicode"
 
 	"neo-code/internal/checkpoint"
 	providertypes "neo-code/internal/provider/types"
@@ -766,10 +767,104 @@ func buildToolArgumentsPreview(arguments string) string {
 	if trimmed == "" {
 		return ""
 	}
-	masked := hookToolArgumentsSensitivePattern.ReplaceAllString(trimmed, `$1=***`)
+	masked := sanitizeHookToolArguments(trimmed)
 	return truncateHookTextByChars(masked, hookToolArgumentsPreviewMaxChars)
 }
 
+// sanitizeHookToolArguments 优先按 JSON 结构递归脱敏，非 JSON 输入回退为轻量正则脱敏。
+func sanitizeHookToolArguments(arguments string) string {
+	if masked, ok := sanitizeHookToolArgumentsJSON(arguments); ok {
+		return masked
+	}
+	return hookToolArgumentsSensitivePattern.ReplaceAllString(arguments, `$1=***`)
+}
+
+// sanitizeHookToolArgumentsJSON 尝试解析 JSON 并按敏感键递归替换值。
+func sanitizeHookToolArgumentsJSON(arguments string) (string, bool) {
+	var decoded any
+	if err := json.Unmarshal([]byte(arguments), &decoded); err != nil {
+		return "", false
+	}
+	sanitized := maskHookToolArgumentValue(decoded)
+	encoded, err := json.Marshal(sanitized)
+	if err != nil {
+		return "", false
+	}
+	return string(encoded), true
+}
+
+// maskHookToolArgumentValue 递归处理 JSON 节点，对敏感键对应的值统一替换为 "***"。
+func maskHookToolArgumentValue(value any) any {
+	switch typed := value.(type) {
+	case map[string]any:
+		masked := make(map[string]any, len(typed))
+		for key, item := range typed {
+			if isSensitiveHookToolArgumentKey(key) {
+				masked[key] = "***"
+				continue
+			}
+			masked[key] = maskHookToolArgumentValue(item)
+		}
+		return masked
+	case []any:
+		masked := make([]any, len(typed))
+		for index, item := range typed {
+			masked[index] = maskHookToolArgumentValue(item)
+		}
+		return masked
+	default:
+		return value
+	}
+}
+
+// isSensitiveHookToolArgumentKey 判断参数键名是否属于敏感信息字段。
+func isSensitiveHookToolArgumentKey(key string) bool {
+	tokens := tokenizeHookToolArgumentKey(key)
+	if len(tokens) == 0 {
+		return false
+	}
+	for index, token := range tokens {
+		switch token {
+		case "password", "passwd", "secret", "token", "auth", "authorization":
+			return true
+		case "apikey", "accesskey", "authtoken", "accesstoken":
+			return true
+		case "api", "access":
+			if index+1 < len(tokens) && tokens[index+1] == "key" {
+				return true
+			}
+		case "key":
+			if index > 0 && (tokens[index-1] == "api" || tokens[index-1] == "access") {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// tokenizeHookToolArgumentKey 将参数键拆分为小写词元，兼容 snake/kebab/camelCase。
+func tokenizeHookToolArgumentKey(key string) []string {
+	trimmed := strings.TrimSpace(key)
+	if trimmed == "" {
+		return nil
+	}
+	var builder strings.Builder
+	var prev rune
+	for _, current := range trimmed {
+		switch {
+		case unicode.IsLetter(current) || unicode.IsDigit(current):
+			if unicode.IsUpper(current) && unicode.IsLower(prev) {
+				builder.WriteByte(' ')
+			}
+			builder.WriteRune(unicode.ToLower(current))
+		default:
+			builder.WriteByte(' ')
+		}
+		prev = current
+	}
+	return strings.Fields(builder.String())
+}
+
 // truncateHookTextByChars 按字符长度截断文本，避免 metadata 放大。
 func truncateHookTextByChars(text string, maxChars int) string {
 	if maxChars <= 0 {

internal/runtime/toolexec_preview_test.go

@@ -0,0 +1,81 @@
+package runtime
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestBuildToolArgumentsPreviewMaskJSONSensitiveFields(t *testing.T) {
+	t.Parallel()
+
+	raw := `{"api_key":"sk-123","password":"p@ss","nested":{"secret":"abc"},"safe":"ok"}`
+	preview := buildToolArgumentsPreview(raw)
+	if strings.Contains(preview, "sk-123") {
+		t.Fatalf("preview leaked api_key: %q", preview)
+	}
+	if strings.Contains(preview, "p@ss") {
+		t.Fatalf("preview leaked password: %q", preview)
+	}
+	if strings.Contains(preview, `"secret":"abc"`) {
+		t.Fatalf("preview leaked nested secret: %q", preview)
+	}
+	if !strings.Contains(preview, `"api_key":"***"`) {
+		t.Fatalf("preview should mask api_key: %q", preview)
+	}
+	if !strings.Contains(preview, `"password":"***"`) {
+		t.Fatalf("preview should mask password: %q", preview)
+	}
+	if !strings.Contains(preview, `"secret":"***"`) {
+		t.Fatalf("preview should mask nested secret: %q", preview)
+	}
+	if !strings.Contains(preview, `"safe":"ok"`) {
+		t.Fatalf("preview should keep non-sensitive keys: %q", preview)
+	}
+}
+
+func TestBuildToolArgumentsPreviewMaskNonJSONFallback(t *testing.T) {
+	t.Parallel()
+
+	preview := buildToolArgumentsPreview(`token=abc password:xyz arg=ok`)
+	if strings.Contains(preview, "abc") || strings.Contains(preview, "xyz") {
+		t.Fatalf("preview leaked fallback credentials: %q", preview)
+	}
+	if !strings.Contains(preview, "token=***") {
+		t.Fatalf("preview should mask token in fallback mode: %q", preview)
+	}
+	if !strings.Contains(preview, "password=***") {
+		t.Fatalf("preview should mask password in fallback mode: %q", preview)
+	}
+}
+
+func TestBuildToolArgumentsPreviewTruncate(t *testing.T) {
+	t.Parallel()
+
+	raw := strings.Repeat("a", hookToolArgumentsPreviewMaxChars+20)
+	preview := buildToolArgumentsPreview(raw)
+	if len([]rune(preview)) != hookToolArgumentsPreviewMaxChars {
+		t.Fatalf("preview length=%d, want %d", len([]rune(preview)), hookToolArgumentsPreviewMaxChars)
+	}
+}
+
+func TestIsSensitiveHookToolArgumentKey(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		key  string
+		want bool
+	}{
+		{key: "api_key", want: true},
+		{key: "accessKey", want: true},
+		{key: "authorization", want: true},
+		{key: "auth_token", want: true},
+		{key: "password", want: true},
+		{key: "author", want: false},
+		{key: "tool_name", want: false},
+	}
+	for _, tc := range cases {
+		if got := isSensitiveHookToolArgumentKey(tc.key); got != tc.want {
+			t.Fatalf("isSensitiveHookToolArgumentKey(%q)=%v, want %v", tc.key, got, tc.want)
+		}
+	}
+}