功能

Hooks

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

配置

Hooks 是 JSON 文件。个人 Hooks 存储在 ~/.grok/hooks/*.json 中；项目 Hooks 存储在 <project>/.grok/hooks/*.json 中。也会读取 Claude Code (.claude/settings.json) 和 Cursor (.cursor/hooks.json) 的 Hook 文件，包括 Cursor 的 camelCase 事件名称。

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。

项目 Hooks 在运行前需要信任：第一次打开带有 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。每个 Hook 进程也会在其环境中接收 GROK_HOOK_EVENT、GROK_HOOK_NAME、GROK_SESSION_ID 和 GROK_WORKSPACE_ROOT。

PreToolUse Hook 通过写入 JSON 到 stdout 来决定：

json

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

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

功能 ​

Hooks ​

配置 ​

事件 ​

脚本合约 ​

功能

Hooks

配置

事件

脚本合约