首页/Grok Build 功能/钩子

钩子

钩子是 Grok 在生命周期事件发生时调用的 shell 命令或 HTTP 端点：在危险命令运行前阻止、记录工具使用、编辑后运行格式化工具，或在轮次结束时发送通知。

配置

钩子是 JSON 文件。个人钩子位于 ~/.grok/hooks/*.json；项目钩子位于 <project>/.grok/hooks/*.json。Claude Code（.claude/settings.json）和 Cursor（.cursor/hooks.json）的钩子文件也会被读取。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bin/safety-check.sh", "timeout": 10 }]
      }
    ]
  }
}

matcher 是针对工具名测试的正则表达式（Claude 工具名如 Bash、Read、Edit 会自动映射到 Grok 的名称）；省略则匹配所有。type 为 "command" 或 "http"（带 url POST 事件）。timeout 单位为秒，默认 5。在扩展弹窗的 /hooks 标签页中管理和查看已加载的钩子。

项目钩子在运行前需要信任：首次打开带钩子的仓库时，通过 /hooks-trust 或启动时传入 --trust 授予。决定存储在 ~/.grok/trusted_folders.toml 中，同时覆盖项目 MCP 和 LSP 服务器。

事件

事件	触发时机
`SessionStart`、`SessionEnd`	会话开始或结束
`UserPromptSubmit`	提交提示
`PreToolUse`	工具即将运行 — 唯一的阻塞事件
`PostToolUse`、`PostToolUseFailure`	工具完成或失败
`PermissionDenied`	权限系统拒绝工具调用
`Stop`、`StopFailure`	轮次结束，或以 API 错误结束
`Notification`	智能体发送通知
`SubagentStart`、`SubagentStop`	子智能体启动或完成
`PreCompact`、`PostCompact`	对话压缩运行

脚本契约

事件以 JSON 格式通过 stdin 传入，包含 hookEventName、sessionId、cwd、workspaceRoot，以及工具事件的 toolName 和 toolInput。每个钩子进程还会在环境中接收 GROK_HOOK_EVENT、GROK_HOOK_NAME、GROK_SESSION_ID 和 GROK_WORKSPACE_ROOT。

PreToolUse 钩子通过向 stdout 写入 JSON 做出决定：

{ "decision": "deny", "reason": "Unsafe command detected" }

退出码 0 允许，退出码 2 拒绝。其他所有情况 — 超时、崩溃、格式错误的输出 — 都是失败放行：失败被记录在会话中但工具调用继续。只有明确的 deny 才会阻止。对于被动事件，stdout 被忽略；成功时退出 0。