[Hooks RFC #679] Task Matcher: Hook tool 选择器与 matcher DSL

[Cai-Tang-www]

父 RFC: #679

背景

对齐 Claude Code 的 matcher 字段。目前 warn_on_tool_call 用 params.tool_name / params.tool_names 自定义匹配,只对单个 handler 生效,缺通用机制。其它点位 (例如 before_tool_call 想"只在 Bash 工具上挂") 没有标准过滤手段。

目标

为所有点位提供统一的 matcher,在 hook 调度层完成过滤,handler 只看到匹配后的调用。

范围

配置

```yaml

• id: deny-rm-rf
  point: before_tool_call
  match:
  tool_name: "Bash" # 精确
  tool_name_regex: "^(Bash|Shell)$" # 二选一
  arguments_contains: ["rm -rf"] # 仅 before_tool_call/after_tool_failure 等持有 arguments 的点位有效
  ```
• 多字段为 AND;同字段多值为 OR
• matcher 字段需在 HookPointCapability 中声明"可用 matcher 维度",runtime 拒绝在不支持的点位使用(例:session_start 用 tool_name → fail-fast)

实装

• internal/runtime/hooks/matcher.go (新): 编译 + 执行
• internal/runtime/hooks/executor.go: 在 Resolve 后、调用 handler 前过滤
• 兼容:旧 warn_on_tool_call 的 params 兜底,迁移期同时支持;同时存在以 matcher 为准并 emit warning event

安全

• regex 限制最大长度 256 + 编译超时
• arguments_contains 仅匹配 sanitized HookContext 暴露的字段,不还原原始参数明文

验收

• 单测覆盖:精确 / regex / 多字段 AND / 同字段 OR / 不支持点位 fail-fast
• warn_on_tool_call 现有 e2e 测试通过(走兼容路径)
• 文档:matcher 语义表格 + 每个点位允许的 matcher 维度

依赖

• #Task-A (能力查询 API)

不在本任务范围

• glob 风格匹配 (后续可加)
• 基于 LLM 的语义匹配