完整的参考是 Claude Code 的 mod TypeScript 声明，其中描述了每个事件、方法和元素，并附有示例。GitHub 上的副本可能比您安装的 Claude Code 版本更旧。两者不一致时，请以 Claude Code 为您的版本写入的副本为准。
文件
mod 是一个包含以下文件的插件目录：register 接收 on 和 options。options 包含清单所声明的 userConfig 字段的值，并已填入默认值。
hook 函数
mod 通过在register 内调用 on 来注册它的每个 hook（即事件处理程序）。on 接受事件名称、一个可选的匹配器（即对事件字段的过滤条件）以及 hook，如 on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))。on 返回一个注册对象，它只有一个方法 .catch(handler)，用于设置该 hook 的错误处理程序。
事件
事件按其涉及的内容分组，每个事件都列出了触发时机以及其上的 hook 可以返回的内容。turn.step 和 process.spawn 上的 hook 是异步生成器，其他 hook 是异步函数。
每个表格的最后一列使用简写。next(e) 原样传递事件。next({ ...e, text }) 传递一个更改了指定字段的副本，如 next({ ...e, text: e.text.trim() })。对象表示不调用 next 而直接应答该事件，而 reason 之类的词代表您编写的字符串，如 { deny: 'Use the file tools.' }。
工具
工具事件围绕 Claude 发出的每个工具调用触发，涵盖从 Claude 读取的描述到是否运行该调用的决定：tool.check 上的 Agent 和组织字段
在 tool.check hook 中，读取以下字段可区分子代理的调用与主对话的调用，并查看您的组织是否要求对某个连接器工具进行批准：
e.agentId：当子代理或进程内队友发出调用时设置，由主对话发出调用时则不存在e.ceiling：对于您的组织设为ask的连接器工具，其值为ask，适用于该设置能传达到 Claude Code 的会话
tool.check 上，e.agentId 和 e.ceiling 需要 Claude Code v2.1.290 或更高版本。
提示词以及 Claude 读取的内容
提示词事件涵盖用户输入的文本，以及 Claude Code 自行发送给 Claude 的文本，例如系统提示词和提醒：skill.prompt 上的来源和 frontmatter 字段
在 skill.prompt hook 中，除了 e.skill 中的 skill 名称和 e.text 中 Claude 读取的文本之外，您还可以读取以下字段：
hook 可以将更改后的
text 或 frontmatter 传给 next：其后的 hook 会读取这两者，而 Claude 读取最终的 text。更改任何其他字段的 hook 会失败。
在 skill.prompt 上，e.source、e.pluginName、e.path、e.frontmatter 和 e.frontmatterProblem 需要 Claude Code v2.1.299 或更高版本。
命令和配置
命令和配置事件在命令运行或被列出时，以及/config 行显示或更改时触发：
轮次
轮次事件从头到尾跟踪一次回答，包括其中每个发往模型的请求：会话
会话事件标记会话的开始、结束、压缩，以及与其他会话交换消息：子代理
子代理事件在向 Claude 提供某个子代理类型时，以及子代理或 agent team 队友即将启动时触发：
当 Claude 使用
SendMessage 工具恢复子代理时，您的 agent.spawn hook 不会再次运行。要拒绝恢复子代理的 SendMessage 调用，请在 tool.call hook 中匹配该工具。
界面
界面事件在 Claude Code 绘制渲染位置时，以及用户使用 mod 绘制的控件时触发。在界面中绘制展示了ui.render hook 返回的内容：
其他 mod
这些事件让 mod 在其他 mod 加载时对其进行操作，以拒绝某个 mod 或更改它收到的 mods API：
当另一个 mod 的 hook 调用您在
engine.create 中添加的命名空间上的方法时，在该事件上的所有 hook 返回之前，您的方法发出的 $ 调用都在该 hook 的上下文中运行。例如，相对路径基于该 hook 的工作目录解析，而当轮次正在等待该 hook 时，$.prompt.submit 会被拒绝。在此之后您的方法发出的调用将在您的 mod 自身的上下文中运行。
遥测
遥测事件针对 Claude Code 记录的使用情况记录触发：设置 hook 事件
每个设置 hook 事件都是一个名为classic.<Event> 的事件，如 classic.Stop 或 classic.PostToolUse。e 是该 hook 的 stdin JSON。
mods API 调用
每个 mods API 方法也是一个事件，以其命名空间和方法命名，如fs.read、model.complete 或 ui.open。其上的 hook 会拦截在它之后运行的 mod 发出的调用，并可以返回 next(e)、{ deny: reason } 或 { value }。
mods API 方法
mods API 是每个 hook 接收的$ 参数。它的方法按命名空间分组，例如 $.ui。此表按名称列出每个命名空间的方法，因此 $.ui 行中的 open 就是调用 $.ui.open(...)。指南展示了常用方法的用法，而您的构建版本的类型记录了每个方法并附有示例。
渲染位置
渲染位置是 Claude Code 界面中的扩展点。每一行是ui.render hook 中 e.component 的一个值，并列出了 e.props 的字段以及渲染它的应用。e.surface 指明正在绘制的应用，例如 terminal、desktop 或 vscode。更改 Claude Code 已绘制的内容展示了 hook 在某个位置可以做什么，并为每种选择提供了示例。
在 VS Code 扩展中进行渲染需要扩展版本 2.1.299 或更高版本，并且需要一个获取功能标志的会话。在 VS Code 扩展中绘制列出了该扩展在绘制上的不同之处。
e.viewport 包含 columns、rows 和 isFullscreen。在终端和 Desktop 应用中，在应用测量其窗口之前，它不存在。在这两处，它的 rows 是整个窗口的高度，而不是您的窗格的高度。在 VS Code 扩展中，它始终存在。
要使树适配其所在位置，请在 hook 中读取以下 prop：
Pane或横栏的宽度：按e.props.bodyColumns绘制- 会话记录旁的
Pane的高度：当e.props.placement为'dock'时，e.props.scroll.bodyRows是该窗格可供您的树使用的行数 - 输入框上方的
Pane的高度：当e.props.placement为'inline'时，窗格会随您的树增高，直到达到上限，而bodyRows就是该上限。如需请求不同的上限，请参阅$.ui.open的rows字段。
元素
元素是ui.render hook 所返回的树的构建块，您可以从 $.ui.resolve(e) 获取它们。用元素构建树展示了常用元素以及终端如何绘制它们，界面图库提供了大多数元素的截图。对勾表示该应用可以绘制该元素。
更多
Button 规则：action 指定 Claude Code 自身的某个快捷键操作，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 hotkey 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 hotkey 时，由后一个按钮获得它。autoFocus 在任何控件上都只接受 true，因此要关闭它，请省略该 prop。
VS Code 扩展会忽略某些元素 prop，并像您省略了这些 prop 一样绘制该元素：
Box：position和hoverButton：hotkey、plain、autoFocus和action，因此用户在其中通过点击来按下按钮，或在按钮获得焦点后按 EnterCode：language、path、startLine、format和wrap，因此代码绘制时不带颜色或行号，而format: 'diff'代码块会显示 diff 的原始文本Input和Select：autoFocus
Box 边框样式
要在 Box 周围绘制边框，请将其 borderStyle 设置为以下名称之一，例如 borderStyle: 'round'。每一行说明终端针对该名称绘制的内容，并展示边框的上边缘。
如果
Box 的 borderStyle 指定的是其他名称（例如 'rounded'），则绘制时不带边框。
限制
hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。设置和环境变量
以下是影响 mod 的设置和环境变量。“位置”列说明每一项从哪个设置文件或环境中读取：sec-default@builtin 是 Claude Code 内置的守卫，在 /plugin 和调试日志中显示为 cc-plugin-sec-default。在有托管设置的机器上，或对于使用 Team 或 Enterprise 套餐登录的用户，它会在用户安装的每个 mod 之前加载。如果设置了托管的 prependPlugins，则只有当该列表指定了该守卫时它才会加载，并位于列出的位置。其源代码位于 Claude Code 仓库的 mods/sec-default 目录中。
命令
这些命令和标志用于加载、检查和测试 mod。claude 命令在您的 shell 中运行，/ 命令在 Claude Code 输入框中运行。表中的 <directory> 代表您输入的路径，如 claude plugin validate ./first-mod。方括号表示可选参数。