$ 接收,方法按命名空间分组,例如 $.ui 和 $.fs。事件决定何时运行 hook,mods API 是 hook 运行后调用的内容。
在开始之前,请构建您的第一个 mod。对于每个方法,请参阅 mods API 方法或阅读您的构建的类型。
添加命令或工具
mod 可以添加供用户运行的命令和供 Claude 调用的工具。在session.start hook 中注册两者。Claude Code 在第一个提示之前等待该 hook,因此您注册的内容从第一轮开始就可用。
添加命令
命令是供用户使用的。注册它,然后为其名称处理command.run。此示例添加了一个 /standup 命令,该命令接受可选的天数:
/standup 及其描述会出现在您键入 / 时看到的列表中。argumentHint 在您键入命令和空格后显示在提示中,如 /standup [days]。当您运行 /standup 3 时,第二个 hook 返回 Summary for the last 3 day(s): ...,并且成绩单在插件名称后显示该文本。hook 永远不会调用 next,因为该命令除了您的行为外没有其他行为。
您返回的 text 会打印在成绩单中,Claude 会读取它。要不打印任何内容,如仅打开窗格的命令,请返回 {}。要让命令在 Claude 工作时运行,请在注册中添加 immediate: true。
选择一个没有内置命令使用的名称。在会话中键入 / 以查看它们。$.command.register 对于已占用的名称会抛出异常,并显示诸如 "/focus" refused: it is the built-in /focus 的消息。抛出异常的 hook 会被跳过,因此您的 session.start hook 的其余部分也不会运行。在该 hook 中最后注册命令,或将调用包装在 try 和 catch 中。
添加工具
工具是供 Claude 使用的。使用名称、Claude 读取的描述和其输入的 JSON Schema 注册它。Claude 在由mcp__、您的插件名称、两个下划线和您注册的名称组成的较长名称下看到它。您在 tool.call hook 中处理其调用,该 hook 被过滤到该完整名称。此示例来自名为 my-mod 的插件,注册 ticket,因此完整名称是 mcp__my-mod__ticket。它为 Claude 提供了一个在问题跟踪器中查找工单的工具:
mcp__my-mod__ticket。第二个 hook 获取工单并返回响应体,Claude 将其作为工具的结果读取。当服务器以错误状态回答时,Claude 读取 Lookup failed with status 和数字。
调用模型
mod 可以向模型发送自己的请求,用于分类或总结文本等小任务。$.model.complete 单独发送您的提示词,而 $.model.fork({ prompt }) 发送当前对话,并将您的提示词附加在末尾。
下表比较了每种请求包含的内容:
fork 会重复对话的最后一个请求,因此在对话仍处于缓存中时,Claude API 会从提示缓存中提供其大部分内容。
这两种调用都使用会话的凭据,因此费用计入用户的套餐、API 密钥或云提供商。您的构建的类型记录了每个
$.model 方法。
发送单个提示词
向$.model.complete 传入 model 和 prompt。prompt 会成为用户消息。要向模型提供指令(例如角色或输出格式),还需传入 system,它会成为系统提示词。
此 hook 通过要求小型模型标记在其后键入的文本来回答 /triage 命令(注册为命令):
/triage the export button does nothing 时,mod 将该文本发送到模型并打印其答案,例如 Label: bug。当模型不回答时,标签是 unknown。
Claude API 失败不会拒绝调用,因此请检查 r.isAnswered,并在其为 false 时读取 r.reason。对于 Claude Code 不会发送的请求,例如您的组织阻止的模型,调用会被拒绝。
您的构建的类型列出了其他选项,例如 effort,限制给出了 maxTokens 的默认值。
使用提示缓存
$.model.complete 支持 Claude API 的提示缓存。API 会缓存请求的开头部分(称为前缀),直到您设置的缓存断点为止。当每次调用都以相同的长静态内容(例如指令或参考资料)开头时,请在该内容的末尾设置断点。之后的调用就会从缓存中读取这部分内容,而无需为其支付完整的输入价格。
要设置断点,请将 prompt 作为 { text } 块的数组而不是字符串传入,并在静态内容的最后一个块上添加 cache: true。Claude Code 会使用 API 的 cache_control 字段发送该块。system 也接受相同的数组形式。要在两者之间做出选择,请参阅在 prompt 和 system 之间选择。
块数组需要 Claude Code v2.1.292 或更高版本。早期版本会拒绝
prompt 中的数组,并报出以 takes { model, prompt } (host check) 结尾的错误,而 system 中的数组则会被排除在请求之外。/triage hook 在要标记的文本之前发送一组较长的标记规则,并在规则之后设置断点。RULES 是您自己定义的字符串:
- TTL:缓存条目在最后一次使用后持续五分钟。TTL 来自用户的 Claude Code 设置,而不是来自调用。如需一小时,请将
subagentPromptCacheTtl设置为1h。 - 每个请求的断点数:API 接受最多四个,再多一个则会在
r.reason中返回api-error
在 prompt 和 system 之间选择
除非您确定请求直接发送到 Claude API,否则请将各调用共享的静态内容放在 prompt 的开头:
- 使用 API 密钥或 Claude 订阅直接发送到 Claude API:两个字段都可以
- 通过 Amazon Bedrock、Claude Platform on AWS、Google Cloud’s Agent Platform、Microsoft Foundry 或 LLM 网关发送:使用
prompt。Claude Code 会在系统提示词开头添加一个归属块,其指纹来自用户消息的开头。api.anthropic.com端点会在缓存之前去除该块。其他端点则会将其作为提示词的一部分接收,因此当prompt的开头不同时,system中的断点可能无法命中。 - 在其他人运行的 mod 中:使用
prompt,因为您无法选择他们的提供商
system 位于 prompt 之前,因此 prompt 中的断点也会覆盖 system,而 system 不同的调用将无法命中缓存。
检查缓存命中
$.model.complete 的结果包含一个 usage 对象,其中带有 API 的缓存字段。usage.cache_creation_input_tokens 统计调用写入缓存的 token 数,usage.cache_read_input_tokens 统计调用从缓存读取的 token 数。预期第一次调用会产生写入,而在 TTL 内的后续调用会产生读取。
如果每次调用都在写入而没有任何读取,则说明各调用之间的前缀不同,或者调用间隔超过了 TTL。关于前缀不同的情况,请参阅在 prompt 和 system 之间选择。
如果在模型已回答的调用中两个字段都保持为零,则说明没有缓存任何内容。请逐一检查以下原因:
- 前缀太短:API 不会缓存短于模型最小长度的前缀,并且不会返回错误
- 提示缓存已禁用:当某个
DISABLE_PROMPT_CACHING变量适用于该模型时,Claude Code 会移除断点并以不缓存的方式发送文本 - 您的网关去除了
cache_control:网关可能会移除该字段但仍返回成功 - 另一个 mod 重写了文本的开头:此时 Claude Code 会不带断点发送文本
model.complete hook 接收的内容
如果您通过 hook 监听 model.complete 事件来检查或更改其他 mod 的请求,请从以下字段读取文本:
e.prompt:始终是字符串。当调用方传入数组时,它是各块文本按顺序拼接的结果。e.system:以相同方式构建的字符串,当调用方未传入system时则不存在e.promptBlocks和e.systemBlocks:调用方的数组,当调用方为相应字段传入数组时才存在
next 的字符串,并使用您随之传入的数组来放置缓存断点。它会保留仍与字符串开头匹配的前导块及其断点,并以不带断点的方式发送字符串的其余部分。例如,next({ ...e, prompt: e.prompt + NOTE }) 会保留调用方的断点,而更改 prompt 开头的 hook 会移除这些断点。
在后台运行工作
超越一个事件的工作,例如每分钟检查一次,在您从session.start 启动的计时器上运行。hook 本身为一个事件运行,其自身运行时间有时间限制。在 next 或 mods API 调用上花费的时间不计算,除了 $.clock.sleep。$.clock.every 和 $.clock.after 代替 setInterval 和 setTimeout,延迟以毫秒为单位:$.clock.after(5000, fn) 在五秒后调用 fn 一次。每个都返回一个带有 cancel() 方法的计时器,await $.clock.now() 给出以毫秒为单位的时间。
此 hook 每分钟查找一次拉取请求的检查,并在提示下显示结果。summarize 是您自己的函数,将命令的 JSON 输出转换为几个单词:
⚠、mod 的名称,然后是 checks: 和您的摘要。之后每分钟替换一次。计时器的回调在任何事件之外运行,因此它在轮次之间保持运行,不会启动一个。如果回调抛出异常,错误会进入调试日志,计时器在下一个间隔再次运行。
显示内容而不启动轮次
后台工作可以显示用户内容而不启动轮次。这些调用中的每一个都将文本放在不同的位置:$.ui.notify 是其中唯一会返回应答的调用。当用户的频道将通知写入其终端时,它解析为 { isSent: true, channel }。channel 是发送该通知的设置值,例如 kitty 或 terminal_bell。terminal_bell 频道只会响铃,既不显示您的文本,也不显示标题。
否则,调用解析为 { isSent: false, reason }:
当
text 不是字符串、另一个 mod 在 ui.notify 上的 hook 返回 { deny },或写入终端失败时,调用会 reject 而不是解析。
您的 mod 无法选择频道,Claude Code 也不限制 mod 发送通知的频率。用户的设置是唯一的开关。
当调用到达正在运行的会话时,用户的 Notification hook 会以类型 plugin_notification 运行。即使应答为 disabled,以及在没有终端、应答为 no-surface 的会话中,它们也会运行。对于在会话启动之前或 Claude Code 退出时发起的调用,不会运行任何 hook。您的 mod 调用 $.ui.notify 所在的那个 hook 不参与这次运行,因此发送通知的 classic.Notification hook 不会因其自身的通知而再次被调用。
终端不会报告是否显示了通知,因此 isSent: true 表示通知已发送,而不代表用户看到了它。
此示例在主对话的轮次未被中断而结束时发送通知,并在没有发出带文本的通知时回退到 toast。它在传递事件之前不等待通知,因为用户的 Notification hook 会先运行,可能需要一段时间:
从后台工作启动轮次
当后台工作发现需要 Claude 注意的内容时,它可以通过使用$.prompt.submit({ text }) 提交提示来启动轮次。Claude 在命名您的 mod 为发送者的句子后读取文本。要将其作为用户自己的话发送,不带该句子,请添加 asUser: true。调用等待直到会话空闲,然后启动新轮次。它在该轮次启动时解析,因此不要在 Claude 工作时运行的处理程序中 await 它。
停止后台工作
模块重新加载后,计时器会停止。对于 hook 内的长时间运行工作,next.signal 是一个 AbortSignal,当您的 hook 处理的事件被放弃时(例如用户中断时)会中止。请将其传递给任何长时间运行的内容。
用户中断轮次后的调用和后台工作
结果或错误中的原因the session was stopped and nobody has sent input since 表示用户停止了正在运行的轮次,例如通过 Esc 或 Stop。在该中断之后,在会话中启动新工作的调用会被拒绝,直到用户的下一次输入,例如在输入框中输入的一条消息。
除 $.prompt.submit 和 $.command.run 外,这种中断后对调用和后台工作的处理需要 Claude Code v2.1.304 或更高版本。
重试被拒绝或被丢弃的调用
从turn.complete hook 中再次发起被拒绝或被丢弃的调用。调用会一直被拒绝,直到用户的下一次输入,并且不会有任何机制替您将其排队或重复执行。
当调用的结果或错误包含以下字符串之一时,保留其参数以便稍后重试:
the session was stopped and nobody has sent input since:调用被拒绝was removed from the queue before it ran:提示词或命令未运行就离开了队列并被丢弃,例如当用户停止了轮次时
submitPrompt 来代替 $.prompt.submit。将 pendingText 变量和 submitPrompt 函数放在 register 之上,并将 turn.complete hook 放在其内部,因为验证会拒绝传递给在 register 内部声明的函数的 $。当结果或错误带有上述字符串之一时,submitPrompt 会将文本保存在 pendingText 中,供 turn.complete hook 再次提交:
turn.complete 可能会为被中断的轮次本身以及子代理的轮次触发,此时发起的调用会再次被拒绝。在这种情况下,submitPrompt 会保留文本,留给之后的 turn.complete。
对于会 reject 的调用,例如 $.command.run,请捕获错误,并以 submitPrompt 测试 reason 的方式测试其消息。
被拒绝的调用返回什么
在结果中,<reason> 代表调用被拒绝的原因。在中断之后,该原因为 the session was stopped and nobody has sent input since。有关其他原因,请参阅在 claude -p 运行和 Agent SDK 会话中被拒绝的调用。
当这些
$.session.send 或 $.tool.call 调用之一在交互式会话中因中断而被拒绝时,用户可能会看到 Stopped: toast。
您的 mod 在中断前启动的工作
用户停止正在运行的轮次后(例如通过 Esc),您的 mod 已经启动的部分工作会被丢弃,部分工作会等待用户的下一次输入。
当计划作业到期或监视器在用户下一次输入之前触发事件时,用户可能会看到
Stopped: toast。
在 claude -p 运行和 Agent SDK 会话中被拒绝的调用
在 claude -p 运行或 Agent SDK 会话中,诸如 { drop: 'the run reached its --max-turns limit' } 这样的结果表示该运行拒绝了您的 mod 的调用。
被拒绝的 $.prompt.submit 解析为 { drop: '<reason>' }。其他被拒绝的调用,例如 $.command.run 和 $.agent.spawn,会给出被拒绝的调用返回什么中所示的结果,其中 <reason> 替换为相应的原因。在下方找到您的 <reason>,了解如何处理:
the run reached its --max-turns limit:来自您的 mod 的提示词以及它生成的子代理所产生的轮次都会计入--max-turns或 Agent SDK 的轮次限制。如需更多轮次,请使用更高的限制启动运行。如果无法这样做,请让您的 mod 停止发起被拒绝的调用。如果运行从用户或 SDK 应用程序接收到另一个提示词,轮次计数会重置,运行会再次接受调用。the run is past its --max-budget-usd limit:使用更高的--max-budget-usd启动运行,或提高 Agent SDK 的花费限制。如果无法这样做,请让您的 mod 停止发起被拒绝的调用。该限制适用于运行到目前为止的总花费。当运行接收到另一个提示词时,该总额会继续累加,因此重试会返回相同的原因。the host has ended its input:例如,SDK 应用程序结束了其流式输入,或者使用--input-format stream-json启动的运行的 stdin 已关闭。运行正在结束,不再接受任何输入,因此重试会返回相同的原因。请让您的 mod 停止发起被拒绝的调用。如果运行由您自己启动,下次请保持该输入打开,直到您的 mod 不再需要发起调用。the session was stopped and nobody has sent input since:运行被中断,例如通过 Agent SDK 的interrupt()。要在用户或 SDK 应用程序的下一条消息之后再次发起调用,请按照重试被拒绝或被丢弃的调用操作。
加载您的 mod 的 claude -p 运行永不退出
如果您的 mod 在每个轮次结束时都提交一个提示词,则每个提示词都会启动另一个轮次。如果没有 --max-turns 或 --max-budget-usd,加载该 mod 的 claude -p 运行会一直持续,直到您自己将其停止。
要让运行自行结束,请在 shell 中为命令添加其中任一标志。如果由其他人启动运行,请让您的 mod 在完成工作后停止提交提示词。以下命令添加了 --max-turns:
claude --version,如果您的版本低于 v2.1.304,请更新 Claude Code。从 v2.1.299 起,mod 的提示词会在达到限制时被拒绝。如果您的 mod 生成子代理,从 v2.1.304 起,它们的轮次会计入 --max-turns。
在会话之间发送和接收消息
mod 可以向您的另一个会话、此会话的子代理之一或其 agent team 中的队友发送纯文本消息,还可以观察到达和离开的消息。 要发送消息,请调用$.session.send({ to, text }),它与 SendMessage 工具进行相同的传递。根据消息的接收者设置 to:
- 您的另一个会话:
{ sessionId } - 子代理或队友:
{ agentId },使用来自$.agent.list()的 id - 您收到的某条消息的发送者:该消息来源的字符串地址
{ isDelivered: true }。当没有传递任何内容时,它使用 { isDelivered: false, reason } 解析,reason 说明原因。
此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 /ping 命令(注册为命令):
Status? One line.。当没有传递任何内容时,toast 通知会给出原因。
session.receive 和 session.send 让 mod 观察消息。从两者都返回 next(e) 以不变地传递每条消息:
设置为拒绝入站消息的会话在
session.receive 触发之前拒绝消息,因此 hook 永远看不到它。为您的批准而保留的消息首先到达 hook,因此 mod 可以读取您尚未批准的消息。hook 的 next(e) 在消息未传递时拒绝。
接收消息上的发送者名称是发送者写的任何内容,因此不要基于它做出决定。
访问文件、进程和网络
mod 通过 mods API 访问文件系统、进程和网络,具有与运行 Claude Code 的用户相同的权限。hook 模块本身没有 Node.js API、没有计时器全局变量(如setTimeout),也没有自己的网络或文件访问。标准 JavaScript 和 Web API(如 URL、TextEncoder、AbortController 和 crypto.subtle)可用。下面的每个命名空间涵盖一种访问:
文件、进程和请求有一些自己的规则:
- 路径:相对路径相对于会话的工作目录进行解析,或相对于 hook 正在处理其事件的子代理的工作目录进行解析
$.fs.list:将一个目录的条目作为{ name, kind, size, isLink }返回,不进行递归$.process.run:接受参数列表,不使用 shell。它解析为{ exitCode, stdout, stderr },无论退出码如何。如果程序无法启动或在超时时仍在运行,它会拒绝,默认为 30 秒,因此将其包装在try和catch中。$.http.fetch:最多跟随五次重定向。当重定向到不同的源时,它只保留您设置的accept、accept-language、content-type和user-agent请求头,并丢弃其余请求头,因此依赖其他请求头(如Authorization)的请求在该重定向之后可能会失败。限制中列出了它的超时时间和体大小。
$.,例如 fs.read 用于 $.fs.read。链中较早的 mod 可以观察、重写或拒绝您的调用,这是组织限制 mod 到达的方式。
mod 可以在命令已产生输出或已退出之后拒绝您的 $.process.spawn 调用,且该命令已执行的任何操作都不会被撤销。此时该调用会拒绝,并返回一条以下列字符串之一加上拒绝方 mod 的原因结尾的消息:
$.process.spawn started, and a plugin withheld its result::拒绝方 mod 尚未将命令的输出读取到末尾。如果命令仍在运行,Claude Code 会将其停止。$.process.spawn ran, and a plugin withheld its result::拒绝方 mod 已将命令的输出读取到末尾,因此命令已经退出
读取全部设置、单个来源或单个键
$.settings.read() 解析为一个对象,其中包含所有正在使用的来源的设置,按优先级合并。传入 { source } 可改为读取单个来源,传入 { key } 可读取单个键,也可以同时传入两者:
对于
source,传入要读取的单个设置来源的名称:
user:~/.claude/settings.jsonproject:.claude/settings.jsonlocal:.claude/settings.local.jsonflag:通过--settings传入的内容,以及 SDK 的内联设置policy:托管设置
key,传入单个顶层键的确切名称,而不是指向嵌套对象内部的点分路径。key 参数需要 Claude Code v2.1.304 或更高版本。