Hook 是 Grok 在 lifecycle event 发生时调用的 shell 命令或 HTTP endpoint：在危险命令运行前阻止它、记录工具使用、在编辑后运行 formatter，或在 turn 结束时发送通知。

配置

Hooks 是 JSON 文件。个人 hooks 位于 ~/.grok/hooks/*.json；项目 hooks 位于 <project>/.grok/hooks/*.json。也会读取 Claude Code（.claude/settings.json）和 Cursor（.cursor/hooks.json）hook 文件，包括 Cursor 的 camelCase event 名称。

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

matcher 是针对工具名称进行测试的 regular expression（Bash、Read 和 Edit 等 Claude tool 名称会自动映射到 Grok）；省略则匹配所有内容。type 为 "command" 或 "http"（使用 url 接收 POST event）。timeout 单位为秒，默认为 5。在 extensions modal 的 /hooks tab 中管理并检查已加载 hooks。

项目 hooks 运行前需要信任：首次打开包含 hooks 的 repository 时，使用 /hooks-trust 授权，或通过 --trust 启动。该决定保存在 ~/.grok/trusted_folders.toml 中，也涵盖项目 MCP 和 LSP servers。

Events

Event	触发时机
`SessionStart`, `SessionEnd`	Session 启动或结束
`UserPromptSubmit`	你提交 prompt
`PreToolUse`	工具即将运行，这是唯一会阻塞的 event
`PostToolUse`, `PostToolUseFailure`	工具完成或失败
`PermissionDenied`	权限系统拒绝工具调用
`Stop`, `StopFailure`	Turn 结束，或因 API 错误而结束
`Notification`	Agent 发送通知
`SubagentStart`, `SubagentStop`	Subagent 启动或完成
`PreCompact`, `PostCompact`	运行对话压缩

脚本契约

Event 以 JSON 形式从 stdin 传入，包括 hookEventName、sessionId、cwd、workspaceRoot；对于工具 event，还包括 toolName 和 toolInput。每个 hook process 还会在环境中收到 GROK_HOOK_EVENT、GROK_HOOK_NAME、GROK_SESSION_ID 和 GROK_WORKSPACE_ROOT。

PreToolUse hook 通过向 stdout 写入 JSON 来做出决定：

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

Exit code 0 表示允许，exit code 2 表示拒绝。其他所有情况（timeout、crash、格式错误的输出）都采用 fail-open：失败会记录到 session 中，但工具调用仍继续。只有显式 deny 会阻止调用。对于被动 event，stdout 会被忽略；成功时返回 exit 0。