如何配置钩子（hooks）？

[lbk1124]

我在界面里没有找到配置钩子hooks的地方，也没有hooks命令；我的一些桌宠软件依赖hooks改变运行时桌宠状态，我想在运行zcode时也有桌宠陪伴。

[GoooIce]

直接让 zcode 自己写 hook 啊

---

基于对 zcode.cjs 源码的反编译分析，我把 ZCode 的 hook 系统摸清楚了。下面给你一份完整说明。

有，ZCode 支持 Hooks
每个插件目录里的 hooks/hooks.json 不是摆设——ZCode 有一套完整的事件钩子系统。从源码（zcode.cjs）确认：

支持的 7 种事件
事件 触发时机
SessionStart 会话开始时
UserPromptSubmit 用户提交 prompt 后、发给模型前
PreToolUse 工具调用执行前（可拦截）
PermissionRequest 权限请求时（可决策）
PostToolUse 工具调用执行后
PostToolUseFailure 工具调用失败后
Stop 模型停止/回复结束时
Hook 的执行机制（来自源码）

js
// zcode.cjs 里的核心逻辑（反混淆后）
class HookRunner {
constructor(t = {}) {
this.defaultTimeoutMs = t.defaultTimeoutMs ?? 60000 // 默认 60s 超时
this.hooks = [...t.hooks ?? []]
}
async run(event, context) {
// 按 event + matcher 过滤匹配的 hooks
// 每个 hook 带超时执行
// 收集 additionalContext 注入到模型
}
}
关键点：每个 hook 独立超时（默认 60 秒），执行结果里的 additionalContext 会被注入到模型上下文中。

Hook 的两种类型
从 schema 确认，hook 回调支持：

command — 执行一个外部命令（最常用）
inline — 内联逻辑（源码里也有引用）
Permission 行为（拦截类 hook 的核心能力）
PreToolUse 和 PermissionRequest 这类 hook 的返回值能控制权限决策，源码里确认的取值：

allow — 允许执行
deny — 拒绝（状态记为 permission_denied）
ask — 交给用户决定（默认行为）
返回码语义：exit code 0 = 成功；非零可被解释为 block/失败。

配置格式
从 schema（be.object({...}) 那段）还原出来的完整结构：

jsonc
// 全局 config.json 里的写法（zcode.cjs 里看到的 eKr schema）
{
"hooks": {
"enabled": true,
"timeoutMs": 60000, // 全局超时
"maxOutputBytes": 32768, // 输出截断阈值
"events": {
"PreToolUse": [
{
"matcher": "Bash", // 匹配工具名（正则），省略=全部
"hooks": [
{
"type": "command",
"command": "/path/to/your/script.sh",
"args": ["--flag"],
"cwd": "/optional/working/dir",
"env": { "KEY": "value" },
"timeoutMs": 30000 // 单 hook 超时，覆盖全局
}
]
}
],
"UserPromptSubmit": [ /* ... / ],
"Stop": [ / ... */ ]
}
}
}
每个 events.<事件名> 是个数组，数组元素结构为 { matcher, hooks: [...] } —— 这点很重要，和 Claude Code 的 hooks 格式是一致的。

插件里的 hook
插件通过 hooks/hooks.json 声明自己的 hook，格式应该是同样的 events 结构。官方插件目前都是 { "hooks": {} } 空的（只是占位）。

hook 收到的输入
源码里能看到的 hook 上下文字段：hook_event_name、cwd、session_id、tool_name、tool_input 等（通过 stdin JSON 传入命令）。命令的 stdout 里的 additionalContext 会被注入到模型。

一个真实例子：拦截危险的 Bash 命令

jsonc
{
"hooks": {
"enabled": true,
"events": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash",
"args": ["-c", "echo "$HOOK_TOOL_INPUT" | grep -qiE 'rm -rf|drop table|format' && exit 2 || exit 0"]
}
]
}
]
}
}
}

[Aealen]

https://github.com/Aealen/zcode-hooks-poc

可以参考一下我这个，把tool请求和 用户询问部分定位到了 并且实现了一个POC 不知道能不能帮到你