Skip to content

This content is not available in your language yet.

Hook 用于运行时扩展和拦截,不对 LLM 直接暴露。参考 Claude Code hooks 机制设计。

Hook 声明文件位于 .openharness/hooks/*.yaml,每个文件定义一个 hook。

路径用途
hooks/*.yamlHook 声明入口(唯一)
hooks/scripts/脚本和代码文件
hooks/prompts/Prompt handler 复用的提示词
hooks/resources/配置片段、资源文件、测试数据

warning

hooks 在统一 workspace 模型下按声明生效,不再区分额外的只读对话形态。
name: redact-secrets
events:
- before_model_call
matcher: "platform/openai-default|workspace/openai-default"
handler:
type: command
command: node ./.openharness/hooks/scripts/redact-secrets.js
capabilities:
- rewrite_model_request
字段必填说明
name是Hook 名称,必须唯一
events是触发事件列表
matcher否正则过滤,匹配事件查询值
handler是Handler 定义
capabilities否可操作对象(如 rewrite_model_request、rewrite_tool_request)
事件触发时机在执行链中的位置
before_context_compact自动 compact 摘要生成前compact 阈值判定通过、摘要输入消息确定之后,compact summary 模型调用之前
after_context_compact自动 compact 摘要生成后compact boundary / summary 生成之后、写入消息存储之前
before_context_buildModel context messages 组装前自动 compact 完成之后,静态 system prompt 拼装之前
after_context_buildModel context messages 组装后静态 prompt、history、system reminder 拼装完成之后
before_model_callLLM 调用前最终模型请求发出之前
after_model_callLLM 响应后模型完整响应返回之后
before_tool_dispatchTool 执行前executor 分发到 native / action / skill / MCP 之前
after_tool_dispatchTool 执行后tool 返回结果之后、结果回填模型之前
run_completedRun 成功完成assistant 消息持久化、run 标记完成之后
run_failedRun 执行失败run 标记失败或超时之后

当一次模型输入准备过程中发生自动 compact 时,hook 时间点顺序为:

  1. before_context_compact
  2. 生成 compact summary
  3. after_context_compact
  4. before_context_build
  5. 静态 system prompt + history + reminder 装配
  6. after_context_build
  7. before_model_call

若本轮无需 compact,则直接从 before_context_build 开始。

matcher 使用正则(不是 glob),匹配目标因事件而异:

事件匹配目标
before/after_tool_dispatchtool_name
before/after_model_callmodel_ref
run_completed / run_failedtrigger_type
before_context_compact / after_context_compact忽略 matcher
before/after_context_build忽略 matcher

未声明 matcher 时匹配该事件下的所有触发。

handler:
type: command
command: python ./.openharness/hooks/scripts/check.py
cwd: ./
timeout_seconds: 30
environment:
MODE: strict
字段必填说明
command是命令字符串
cwd否工作目录
timeout_seconds否执行超时
environment否追加环境变量
handler:
type: http
url: https://example.internal/hooks/check
method: POST
timeout_seconds: 10
headers:
Authorization: Bearer ${env.HOOK_TOKEN}
字段必填说明
url是HTTP endpoint
method否默认 POST
headers否请求头
timeout_seconds否请求超时
handler:
type: prompt
prompt:
file: ./.openharness/hooks/prompts/review.md
model_ref: platform/openai-default
timeout_seconds: 20
字段必填说明
prompt是支持 inline 或 file
model_ref否Hook 使用的模型入口
timeout_seconds否执行超时
handler:
type: agent
agent: policy-reviewer
task:
inline: |-
Inspect the invocation and return a structured decision.
timeout_seconds: 30
字段必填说明
agent是执行 hook 的 agent 名称
task是支持 inline 或 file
timeout_seconds否执行超时

所有 handler 接收同一份 JSON envelope。

公共字段:

字段说明
workspace_id当前 workspace
session_id当前 session
run_id当前 run
cwd工作目录
hook_event_name触发事件名
agent_name配置的 agent 名
effective_agent_name实际生效的 agent 名

事件附加字段:

事件附加字段
before_model_callmodel_ref, model_request
after_model_callmodel_ref, model_request, model_response
before_context_compactcontext.messages、contextWindowTokens、compactThresholdTokens、estimatedInputTokens、estimatedPostCompactTokens、summarizedMessageCount、configuredRecentGroupCount、keepRecentGroupCount、compactThroughMessageId?
after_context_compactsummaryText、boundaryMessage、summaryMessage、contextWindowTokens、compactThresholdTokens、estimatedInputTokens、estimatedPostCompactTokens、summarizedMessageCount、configuredRecentGroupCount、keepRecentGroupCount、compactThroughMessageId?
before_context_build / after_context_buildcontext.messages
before_tool_dispatchtool_name, tool_input, tool_call_id
after_tool_dispatchtool_name, tool_input, tool_output, tool_call_id
run_completed / run_failedtrigger_type, run_status

传递方式: command 通过 stdin;http 作为 POST body;prompt/agent 注入上下文。

统一输出结构:

{
"continue": true,
"suppressOutput": false,
"systemMessage": "Optional warning",
"decision": "block",
"reason": "Explanation",
"hookSpecificOutput": {
"hookEventName": "before_tool_dispatch",
"additionalContext": "Extra context",
"patch": { "tool_input": { "command": "npm run lint" } }
}
}
字段说明
continue默认 true;false 终止当前 run
stopReasoncontinue=false 时的说明
suppressOutput是否隐藏 hook 原始输出
systemMessage给操作者的提示
decision当前仅支持 "block"
reasonBlock 原因
hookSpecificOutput.patch改写对象,仅在 capability 允许时生效

Patch 范围:context、model_request、model_response、tool_input、tool_output。无对应 capability 的 patch 被忽略并记录 warning。

Handler成功阻断错误
commandexit 0,stdout JSON 按协议解析exit 2,stderr 作为原因其他 exit code,记录后继续
http2xx + JSON body—非 2xx / 超时,记录后继续
prompt返回可解析的统一 JSON——
agent返回可解析的统一 JSON——
name: block-dangerous-commands
events:
- before_tool_dispatch
matcher: "Bash"
handler:
type: command
command: node ./.openharness/hooks/scripts/check-command.js
timeout_seconds: 5
capabilities:
- rewrite_tool_request

.openharness/hooks/scripts/check-command.js

Section titled “.openharness/hooks/scripts/check-command.js”
const input = JSON.parse(require("fs").readFileSync("/dev/stdin", "utf8"));
const dangerous = ["rm -rf /", "drop table", "format c:"];
const cmd = input.tool_input?.command || "";
const blocked = dangerous.some((d) => cmd.toLowerCase().includes(d));
if (blocked) {
console.log(JSON.stringify({
continue: false,
decision: "block",
reason: "Command blocked: contains dangerous pattern",
}));
} else {
console.log(JSON.stringify({ continue: true }));
}