Hooks

配置

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 以 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。