name: hook-schema-audit description: 审计钩子事件模式以检测漂移。比较实现与官方文档。 user-invocable: true argument-hint: “[–fix | --json | --verbose]” allowed-tools: Read, Bash, Glob, Grep, Task, Skill, WebFetch

审计钩子模式

检测钩子分发器 EVENT_FIELD_REGISTRY 与官方 Claude Code 文档之间的漂移。

参数

--fix: 生成更新的注册代码（仅输出，不自动应用）
--json: 用于 CI/自动化的机器可读 JSON 输出
--verbose: 显示所有字段，而不仅仅是差异

工作流程

步骤 1: 加载官方文档

加载 hook-management 技能并查询官方钩子事件模式：

Skill(hook-management)

同时启动 claude-code-guide 代理以获取实时网络文档：

Task(claude-code-guide, "WebFetch https://code.claude.com/docs/en/claude_code_docs_map.md 以查找钩子事件文档页面。然后 WebFetch 这些页面。提取每个钩子事件的输入字段：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Notification、UserPromptSubmit、Stop、SubagentStart、SubagentStop、PreCompact、SessionStart、SessionEnd、TeammateIdle、TaskCompleted。返回结构化数据，包含事件名称和字段列表。")

步骤 2: 解析当前实现

从 hook_dispatcher.py 读取 EVENT_FIELD_REGISTRY：

# 提取注册表定义
grep -A 30 "EVENT_FIELD_REGISTRY = {" plugins/claude-code-observability/hooks/hook_dispatcher.py

将注册表解析为结构化格式以进行比较。

步骤 3: 比较和报告

对于每个钩子事件，比较：

文档字段（来自官方文档）
实现字段（来自 EVENT_FIELD_REGISTRY）

生成报告显示：

事件	文档字段	实现字段	缺失	额外
pretooluse	5	3	tool_input	-
notification	2	0	message, notification_type	-

步骤 4: 输出格式

默认输出：

钩子模式审计报告
========================
模式版本：1.7.0
审计日期：2026-02-15T15:30:00Z

覆盖摘要：
- 总事件数：14
- 完全覆盖：11 (79%)
- 部分覆盖：2 (14%)
- 缺失：1 (7%)

发现：
[警告] notification: 缺失字段：message, notification_type
[警告] userpromptsubmit: 缺失字段：prompt
[正常] pretooluse: 所有文档字段存在
...

建议：更新 EVENT_FIELD_REGISTRY 以包含缺失字段。

使用 --json：

{
  "schema_version": "1.7.0",
  "audit_timestamp": "2026-02-15T15:30:00Z",
  "coverage": {
    "total_events": 14,
    "fully_covered": 11,
    "partially_covered": 2,
    "missing": 1
  },
  "events": {
    "pretooluse": {
      "status": "ok",
      "documented": ["tool_name", "tool_input", "tool_use_id"],
      "implemented": ["tool_name", "tool_input", "tool_use_id"],
      "missing": [],
      "extra": []
    }
  }
}

使用 --fix：

输出可复制粘贴到 hook_dispatcher.py 的更新后的 Python 代码用于 EVENT_FIELD_REGISTRY。

步骤 5: 建议

基于发现，提供可操作建议：

如果字段缺失：建议添加到注册表
如果在日志中找到额外字段：调查是否为新的 Claude Code 字段
如果模式版本过时：建议增加 SCHEMA_VERSION

使用示例

# 基本审计
/claude-code-observability:audit-hook-schema

# CI 集成（机器可读）
/claude-code-observability:audit-hook-schema --json

# 生成修复
/claude-code-observability:audit-hook-schema --fix

# 详细输出
/claude-code-observability:audit-hook-schema --verbose

退出代码（用于 CI）

使用 --json 时：

0：所有事件完全覆盖
1：某些字段缺失（部分覆盖）
2：检测到关键漂移（事件完全缺失）