【免费下载链接】moai-adk
Agentic development harness for Claude Code — SPEC-driven plan/run/sync, TRUST 5 quality gates, model+effort routing, and Claude×GLM multi-LLM cost control. Single Go binary, 16 languages, zero deps.
MoAI-ADK Hooks 系统是为 Claude Code 打造的确定性规则执行层：它把"提示词里写了但 AI 可能不遵守"的规则，变成事件触发、必定执行的机械检查。本篇参考覆盖27 个 Hook 事件类型与JSON stdin/stdout 协议，帮你快速理解每个事件何时触发、如何响应、如何拦截危险操作，是 AI 开发框架（Agent Harness）中质量门禁的完整实现。
为什么 Hooks 是 AI 开发中"必定执行"的一层？
在智能体框架里，CLAUDE.md 和提示词是概率型指令——模型可能遵循，也可能忽略。而 Hooks 是确定性指令：事件一到，代码必跑，结果必被 Claude Code 采纳。
这正是 MoAI-ADK 作为 Agent Harness 的核心理念：框架从外部包裹并约束 Claude Code（概率型工作者），而 Hooks 就是这道围栏上真正通电的部分。
Hooks 在 Claude Code 中的位置
Hooks 与 Skills、Plugins、MCP 并列，是 Claude Code 四大官方扩展点之一。与它们不同的是：只有 Hooks 能否决模型的行为。
MoAI-ADK 的实现架构是shell 包装器 + 单个 Go 二进制：
.claude/hooks/moai/handle-<event>.sh只是薄转发层，负责把 stdin 的 JSON 交给moai hook <event>子命令- 格式化、lint、安全扫描、LSP 诊断等全部逻辑编译在 Go 二进制内部
- 零 Python 依赖：不需要
uv、虚拟环境，moai在 PATH 中即可工作；二进制缺失时包装器安全退出（exit 0），绝不阻塞 Claude Code
27 个 Hook 事件类型总览
事件常量完整定义在 internal/hook/types.go。按用途分为 9 大类：
| 类别 | 事件 | 触发时机 |
|---|---|---|
| 🔄 生命周期 | SessionStart/SessionEnd | 会话开始 / 结束 |
Stop/SubagentStop/SubagentStart | 主智能体或子智能体停止 / 启动 | |
StopFailure | 因 API 错误（限流、鉴权失败）停止 | |
Setup | --init/--maintenance启动流程 | |
| 🔧 工具 | PreToolUse | 工具执行前（可拦截） |
PostToolUse | 工具执行后（可反馈） | |
PostToolUseFailure | 工具执行失败 | |
| 📄 上下文 | PreCompact | 上下文压缩（/clear）前 |
PostCompact | 上下文压缩后 | |
InstructionsLoaded | CLAUDE.md / rules 加载完成 | |
| ⌨️ 输入 | UserPromptSubmit | 用户提交提示词时（可改写） |
Elicitation/ElicitationResult | MCP 服务器请求用户输入 / 用户已响应 | |
| 🛡️ 安全 | PermissionRequest | 权限对话框弹出时（可自动裁决） |
PermissionDenied | 权限被拒后（可触发重试） | |
| 👥 团队 | TeammateIdle/TaskCompleted/TaskCreated | 团队成员空闲 / 任务完成 / 任务创建 |
| 🌳 Worktree | WorktreeCreate/WorktreeRemove | 隔离工作树创建 / 删除 |
| 🌍 环境 | ConfigChange/CwdChanged/FileChanged | 配置变更 / 目录切换 / 文件外部变更 |
| 📢 UI | Notification | Claude Code 发送通知时 |
💡 除上述 27 个已接线事件外，types.go 还声明了
PostToolBatch、UserPromptExpansion、MessageDisplay三个观察型预留事件（已识别、暂不注册处理器）。
每个事件可注册多个处理器，按序执行；任一处理器返回block即短路跳过后续处理器（见 internal/hook/registry.go）。
JSON 协议：一个进、一个出
MoAI-ADK 与 Claude Code 的通信契约非常简洁（见 internal/hook/doc.go）：
① 输入—— Claude Code 通过stdin推送 JSON。结构定义在 HookInput：
{ "session_id": "abc-123", "cwd": "/path/to/project", "hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": { "command": "rm -rf /" }, "permission_mode": "default" }不同事件携带不同字段：UserPromptSubmit带prompt，PreCompact带trigger，FileChanged带file_path与change_type……字段全部是官方 Claude Code 协议命名。
② 输出—— 处理器通过stdout返回 JSON（结构定义在 HookOutput）。stdout只允许出现 JSON，所有诊断日志走 stderr：
| 字段 | 适用场景 | 作用 |
|---|---|---|
hookSpecificOutput.permissionDecision | PreToolUse | "allow"/"deny"/"ask"三态裁决 |
hookSpecificOutput.decision.behavior | PermissionRequest | "allow"/"deny"自动裁决权限请求 |
hookSpecificOutput.additionalContext | 多数事件 | 向模型注入额外上下文 |
hookSpecificOutput.updatedInput | PreToolUse / UserPromptSubmit | 直接改写工具入参或用户提示词 |
decision: "block"+reason | Stop / PostToolUse | 阻断动作并给出理由 |
continue: false+stopReason | 通用 | 终止会话流程 |
systemMessage | 通用 | 向用户显示警告 |
③ 退出码—— 最简单的"拦截协议"：
0→ 允许 / 成功2→拦截，附理由- 其他 → 非阻塞错误，记录后继续
⚠️ 默认超时30 秒（DefaultHookTimeout），官方指南建议：安全守卫（pre-tool）控制在 5 秒内，格式化/lint（post-tool）10 秒内，避免拖慢 Claude Code 响应。
实战中最值钱的 3 类 Hooks
🛡️ PreToolUse：安全守卫，拦截危险操作
这是 Hooks 的核心价值所在。MoAI-ADK 的 pre-tool 处理器会：
- 拦截对
secrets/、~/.ssh/*、*.pem、.git/*、~/.aws/*等敏感路径的 Write/Edit - 拦截危险 Bash 命令：
rm -rf /、git push --force origin main、terraform destroy、docker system prune -a - 命中时返回
permissionDecision: "deny"，Claude Code 立即中止该操作
规则从"提示词里写一句请不要删库"变成"删库命令在机械层面就走不过去"。
🔧 PostToolUse：格式化 → lint → AST-grep → LSP 流水线
每次文件修改后自动执行四步检查（16 种语言支持，如 Go 用gofmt+golangci-lint、Python 用ruff、Rust 用clippy），发现问题通过additionalContext反馈给模型，成为下一轮自动修复的输入——智能体书写，钩子检查，这条流水线承担了反馈循环的一半。
📄 PreCompact / SessionEnd：跨会话的上下文保险
上下文压缩是一次用信息换代币的交易。PreCompact在/clear前把当前 SPEC 状态、任务清单、已改文件、核心决策存入.moai/state/session-memo.md；SessionEnd则保存会话指标与状态快照到~/.moai/state/last-session-state.json。
配置方法：settings.json 中注册 Hooks
Hooks 在项目.claude/settings.json的hooks段注册，最小示例：
{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-pre-tool.sh\"", "timeout": 5 } ] } ], "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/moai/handle-post-tool.sh\"", "timeout": 10 } ] } ] } }关键配置项：
| 字段 | 说明 | 示例 |
|---|---|---|
matcher | 工具名正则，收窄触发范围 | "Write\|Edit" |
type | Hook 类型（command / prompt / agent / http / mcp_tool） | "command" |
command | 要执行的命令 | shell 包装器路径 |
timeout | 超时秒数 | 5 |
💡 MoAI-ADK 在
PreToolUse下为危险命令守卫注册了双匹配器：Write|Edit|Bash与单独的PowerShell，确保无论模型经由哪个工具执行 shell 命令，拦截都同样生效。
延伸阅读：源码与文档路径
| 资源 | 路径 |
|---|---|
| 事件类型与 JSON 协议定义 | internal/hook/types.go |
| 处理器注册与事件分发 | internal/hook/registry.go |
| 事件 × 处理器身份表 | internal/hook/handler_names.go |
| Hooks 指南（中文文档） | docs-site/content/zh/advanced/hooks-guide.md |
| Hooks 事件完整参考 | docs-site/content/zh/advanced/hooks-reference.md |
总结：提示词决定 AI "应该怎么做"，Hooks 决定 AI "被允许做什么"。掌握 27 个事件与 JSON 协议后，你就能把自己的团队规范——安全红线、代码风格、完成标准——全部变成机械执行的确定性规则，这正是一个成熟 Agent Harness 与玩具级提示词工程的分水岭。
【免费下载链接】moai-adk
Agentic development harness for Claude Code — SPEC-driven plan/run/sync, TRUST 5 quality gates, model+effort routing, and Claude×GLM multi-LLM cost control. Single Go binary, 16 languages, zero deps.
相关推荐
Gemini CLI Hooks 技术参考：事件系统、I/O JSON 规范与退出码语义全解
Gemini CLI Hooks 技术参考：事件系统、I/O JSON 规范与退出码语义全解 本文基于 Gemini CLI 仓库中的 Hooks 技术参考文档
人工智能AI Agent交互助手CLIMCP ClientsSuperClaude 行为规则系统（RULES.md）深度解析：从规则优先级到可执行的 Agent 编排协议
SuperClaude 行为规则系统（RULES.md）深度解析：从规则优先级到可执行的 Agent 编排协议 SuperClaude Framework 是一
开发工具CLIAI 技能/插件测试人工智能AI 评测Dism++ 规则结构参考：清理规则、系统优化规则与执行引擎完整语法详解
Dism++ 规则结构参考：清理规则、系统优化规则与执行引擎完整语法详解 本文是 Dism++ 规则体系的语法白皮书，系统讲解清理规则（V1/V2 结构体）、系
后端文档
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
