Agent：门卫之后还能插一脚：PreToolUse / PostToolUse Hooks

门卫之后还能插一脚PreToolUse / PostToolUse Hooks系列回顾主循环 · 代码库工具 · REPL · 项目上下文 · Skills · 权限 Write · MCP 概念 · MCP 实现 · Context Budget · Bash · compact 2.0 · autocompact到上一篇为止react-agent-mini 的工具链已经很长校验 → 门卫canUseTool→Tool.call→tool_result。但有一个缺口项目想「自动拦某类命令 / 审计每次工具结果」时只能改源码或盯着 REPL 点y/N。这篇讲v5-hooks用一份.agents/hooks.json在工具真正执行前后插上命令型生命周期钩子——仍然不改query()。门卫解决的是「人批不批」不是「项目规约」回忆权限篇非只读工具Write / Edit / Bash / 默认 MCP会走canUseTool。门卫canUseToolHooks本篇谁决定人REPL y/N或 headless 策略项目配置里的命令粒度这次调用允不允许可按工具名匹配可拦、可记日志位置call前门卫通过之后仍在call前后所以人说「可以写」≠ 项目说「允许跑 rm -rf」Hooks 补的是后半句把仓库级规约挂进工具流水线。插在哪工具单次执行变成Zod 校验 → canUseTool门卫 → PreToolUse可 deny跳过 call → Tool.call → PostToolUse只观测 / 记日志不撤销结果 → tool_result 回给模型对应代码在runToolUse门卫通过后runPreToolUse工具跑完或抛错再runPostToolUse。事件时机失败默认PreToolUsecall前exit 2或 stdout JSONdeny→不执行工具其它非 0fail-soft 放行可设denyOnFailurePostToolUsecall后只警告不改已有tool_result这很重要Post 不是「事后反悔」工具已经跑完了它适合审计、指标、通知。配置长什么样工作区放.agents/hooks.json没有文件 /HOOKS0→ 整条跳过{PreToolUse:[{matcher:Bash,command:node examples/hooks/deny-bash.mjs}],PostToolUse:[{matcher:*,command:node examples/hooks/log-post.mjs}]}字段很克制字段含义matcher工具名精确匹配或*匹配全部command经 shell 执行的命令timeoutMs可选默认 5s超时当失败exit 124denyOnFailure仅 Pre非 0 退出也按 deny默认 false也兼容外面再包一层{ hooks: { ... } }方便以后和更完整的 settings 形态对齐。命令怎么和 Host 说话Host 把 JSON payload 写进 hook 的stdin{hook_event_name:PreToolUse,tool_name:Bash,tool_input:{command:bun test}}Post 还会带上{hook_event_name:PostToolUse,tool_name:Read,tool_input:{file_path:README.md},tool_result:…摘要文本…,tool_is_error:false}Pre 如何拒绝exit 2最简单—— stderr/stdout 文本当作拒绝原因stdout 末行 JSONpermissionDecision/decision/behavior为deny非 0 且配置了denyOnFailure: true被拒时不调用Tool.call回给模型一条is_error: true的tool_result说明被 hook 拦住——模型可以换策略而不是假装工具成功了。30 秒试一把New-Item-ItemType Directory-Force.agents|Out-NullCopy-Itemexamples/hooks/hooks.json.agents/hooks.json bun run dev然后让模型跑 Bash或 mock 触发 Bash# Preexit 2 → 工具不执行 # stderrexamples/hooks: Bash blocked by PreToolUse demo # 其它工具结束后 # [hooks-demo] post Read errorfalse …关闭$env:HOOKS 0可观测$env:TRACE 1# [trace] hooks.pre toolBash matcherBash exitCode2# [trace] hooks.post toolRead matcher* exitCode0示例脚本就在examples/hooks/deny-bash.mjs拦 Bashlog-post.mjs把结果摘要打到 stderr。和门卫、Skills、MCP 怎么区分机制一句话canUseTool人或 headless 策略批不批这次副作用PreToolUse项目脚本在执行前再拦一层 / 改口风PostToolUse执行后记账不改结果Skills给模型说明书按需注入上下文MCP外挂工具 / 材料 / 开场模板Hooks不替代门卫顺序是先门卫、再 Pre。人拒绝了根本不会进 hook人同意了项目规约还能否决。和主循环的关系L1 CLI / REPL → 可选加载 hooksHOOKS0 跳过 L2 query() → 不变 L3 runToolUse → 门卫后插 Pre / Post L4 services/hooks → load run可注入 fake exec 单测Hooks 改的是「单次工具怎么进出」不是 ReAct 怎么转。测试里可把hooksConfig/hookExec注进ToolUseContext不必真起 shell——和callModel/microcompact同一套可测思路。安全为什么文档一直喊命令型 hook 任意 shell。配置写在工作区里等于信任「能改这个仓库的人」。默认姿态没有.agents/hooks.json→ 什么都不跑HOOKS0→ 强制跳过只加载当前工作区这份配置不扫全球用户目录Pre 默认 fail-softhook 自己挂了不轻易误杀工具除非你显式denyOnFailure生产环境只提交你审过的 hook 命令别把不可信脚本挂进 Pre。刻意没做什么没做意味着什么Stop hook模型说完一轮后再拦 / 要求继续——本版推迟SessionStart / Agent hooks会话级、子代理级事件未接PreCompact / PostCompact不挂在摘要管道上完整 settings schema先独立.agents/hooks.json字段最小用 hook 改 tool 入参 / 改写结果Pre 只能 allow/denyPost 只观测这一刀验证的是 harness 可扩展性的最小面配置加载 → matcher → 命令 stdin JSON → Pre 可拦 → call → Post 可记 → TRACE 可观测 → HOOKS0 可关系列拼图篇能力门卫 Write人批副作用Bash终端钥匙compact 三连上下文预算本篇项目级工具生命周期扩展点Harness 又多一根柱子循环、工具、会话、上下文、技能、权限、外部协议、预算、hooks。你可以从这里带走什么门卫和 hooks 是两层——人批之后项目脚本还能再拦。Pre 可否决Post 只旁观——别指望 Post「撤销」已经发生的写盘。协议要极简——stdin JSON exit 2/ 末行 JSON deny就够做拦与审计。默认 fail-soft——hook 挂了不轻易误杀要严再开denyOnFailure。命令型 信任边界——只信本工作区配置HOOKS0是总闸。不改query()——扩展点挂在runToolUse主循环继续干净。仓库与相关文档GitHubhttps://github.com/jimchou-h/react-agent-mini上一篇autocompact · 权限 Write示例examples/hooks源码src/services/hooks术语表CONTEXT.md欢迎 Star、Issue 和 PR。本文基于 react-agent-mini 变更v5-hooksPreToolUse / PostToolUse .agents/hooks.json撰写。