Grok Build CLI support: search + skills already work via Claude-plugin compat; hooks don't load

[HF-teamdev]

Update (2026-09-19): a working Grok bridge, tested live, is in this comment. It includes the full source, the real Grok payload keys, and a hook log. Fix checklist:

• Installer: write ~/.grok/hooks/ruvnet-brain.json (always trusted) that points at a stable grok-hook.mjs, the same way Codex uses codex-hook.mjs. Detect Grok with ~/.grok/bin/grok.
• In the Grok wrapper (or hook-shim.mjs), add snake_case aliases for Grok's camelCase keys. This is critical for the stop_hook_active loop guard (ADR-0043).
• Map Grok tool names to Claude's (search_replace → Edit/Write, run_terminal_command → Bash, …).
• Skip the Stop gates when reason != "end_turn".
• Register SessionStart for Grok without a matcher. startup|resume|… didn't fire; confirmed fixed live in Update 2.
• Make --doctor and the installer report Grok's state instead of "not wired". Don't add a second MCP entry to ~/.grok/config.toml.
• Offer to add the "call search_ruvnet first" line to ~/.grok/AGENTS.md. Grok discards UserPromptSubmit and SessionStart context, and live testing showed this line is what makes Grok ground itself (Update 2).
• Separate issue: a model download that doesn't finish leaves search broken with a misleading "sandbox" error. See the section at the bottom.

Summary

Grok Build CLI (xAI's grok, v1.0.34) already picks up the RuvNet Brain Claude Code plugin, because it reads ~/.claude/plugins/installed_plugins.json. I tested it live:

• ✅ search_ruvnet works in Grok. It's called as ruvnet-brain__search_ruvnet and returns real cited source.
• ✅ All 9 skills load (/rvbc, /brain-build, /brain-score, …).
• ❌ None of the lifecycle hooks run. grok inspect finds hooks/hooks.json, but /hooks-list in a live session doesn't show any RuvNet hooks.
• ⚠️ Even once they load, two contract gaps would bite. Grok drops additionalContext from UserPromptSubmit and SessionStart, and it sends hook input with camelCase keys.

So Grok users get the tool and the skills, but not the proactive grounding. A small grok host adapter would probably close most of the gap. Details below.

Environment

• macOS (Darwin 27), Node on PATH
• ruvnet-brain 4.3.26, installed with npx ruvnet-brain for Claude Code and Codex. The installer printed "Grok was not wired".
• Grok Build grok 1.0.34 (3736acbc8658) [stable]

Live test results in Grok

1. MCP search: works

Prompt: Call the ruvnet-brain MCP tool search_ruvnet with query "RuVector RVF file format" and k=3…

Tool name: ruvnet-brain__search_ruvnet
Succeeded: yes
Source paths:
  1. ruvector/crates/rvf/rvf-wire/Cargo.toml
  2. ruvector/npm/packages/rvf/src/index.ts
  3. ruvector/crates/rvf/rvf-manifest/Cargo.toml

2. Hooks: discovered but not loaded

grok inspect --json lists the plugin with "hooks": true and a hook entry pointing at …/ruvnet-brain/4.3.26/hooks/hooks.json. But /hooks-list in the same session shows only my own 4 statusline hooks:

Loaded hooks (4):
  global/statusline-compact:pre_compact[0] ...  ~/.grok/statusline/compact-hook.zsh
  global/settings:pre_compact[0] ...            ~/.claude/statusline/compact-hook.zsh
  global/statusline-compact:post_compact[0] ... ~/.grok/statusline/compact-hook.zsh
  global/settings:post_compact[0] ...           ~/.claude/statusline/compact-hook.zsh

Grok does load hooks from ~/.claude/settings.json (the global/settings rows), and [compat.claude] hooks is on. So Claude hook compat isn't disabled. It's specifically the plugin's hooks.json that isn't being activated.

Likely cause: grok plugin list prints "No plugins installed". Grok only discovered RuvNet as a Claude-compat plugin; it isn't a native Grok install. Grok's plugin docs say "Enabled plugins require trust to load skills, commands, hooks, MCP servers", and only plugins under ~/.grok/plugins/ are trusted automatically. In practice the compat plugin's skills and MCP load but its hooks don't. grok plugin validate <plugin dir> reports "Plugin manifest is valid", so the manifest isn't the problem.

What works around it: hooks placed in ~/.grok/hooks/*.json are always trusted. So the installer could write a ~/.grok/hooks/ruvnet-brain.json that points at a stable grok-hook.mjs wrapper, the same way Codex uses ~/.cache/ruvnet-brain/codex-hook.mjs. That wrapper is also the natural place to handle the key-name differences below.

Hook contract differences to plan for (from ~/.grok/docs/user-guide/10-hooks.md)

1. UserPromptSubmit can't inject context. The docs say: "an allowing hook's stdout / additionalContext is discarded rather than added as context." So ground-ruvnet's "ground before you assert" directive never reaches Grok's model. It can still block, with exit 2 or {"decision":"block"}.

2. SessionStart is passive. Its output doesn't reach the model, so the "RuvNet Brain vX active / grounding PROVEN" banner is lost.

3. Hook input uses camelCase keys. Grok sends toolName, toolInput, stopHookActive, lastAssistantMessage. Only hook_event_name gets a snake_case copy. These scripts read the Claude spelling:

   • scripts/decision-gate.mjs:222-223 reads tool_name / tool_input
   • scripts/continuation-gate.mjs:265 reads stop_hook_active
   • scripts/grounding-turn-gate.mjs:116 reads stop_hook_active

   The stop_hook_active ones matter most. Under Grok, that loop guard would never trip, and only Grok's built-in cap of 8 continuations per turn would stop the gate. Normalizing keys in hook-shim.mjs (camelCase → snake_case) would fix all three in one place.

4. Extra Stop events at session end. Grok fires Stop again with reason: "channel_closed" or "shutdown". Counters and gates should act only when reason == "end_turn".

5. What already matches: Stop decision:block / additionalContext (keeps the agent working), PreToolUse permissionDecision / deny, and PostToolUse additionalContext. CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA / CLAUDE_PROJECT_DIR are all set. Grok's MCP tool names (server__tool) already match your ^(?:.*__)?search_ruvnet$ matcher, and Grok maps Claude tool names in matchers (e.g. Edit also matches search_replace).

Suggested changes

1. Add a host-adapters/grok.json that detects ~/.grok/bin/grok, so the installer and --doctor report "Grok: search + skills via Claude-plugin compat; hooks " instead of "not wired". It shouldn't add a second [mcp_servers.ruvnet-brain] to ~/.grok/config.toml, since Grok already loads the plugin's .mcp.json.
2. Host detection. session-start-core.mjs:136 branches on RUVNET_HOOK_HOST === 'codex'. Grok sets GROK_AGENT (plus GROK_PLUGIN_ROOT and GROK_WORKSPACE_ROOT) in the hook environment, so the shim could set RUVNET_HOOK_HOST=grok from those.
3. Normalize hook input keys in hook-shim.mjs, per item 3 above.
4. Grounding fallback for Grok. Since prompt-time injection isn't possible, lean on the Stop grounding-turn-gate, which Grok honors, and on the ruvnet-brain skill body. Or suggest adding a one-line rule to ~/.grok/AGENTS.md.
5. Docs. explainer/llms-full.txt lists Claude Code and Codex as the hosts. A line on Grok support and its limits would help.

Unrelated, but hit on the same machine: embedder download

On first install, the ONNX weights for Xenova/bge-base-en-v1.5 and the ms-marco-MiniLM-L-6-v2 reranker (onnx/model_quantized.onnx) never finished downloading. Only the tokenizer and config files landed. On this connection, the huggingface.co redirect alone took about 3.7s, close to the worker's 5s reachability timeout. search_ruvnet then failed everywhere with "cannot reach the embedding-model host … This environment looks network-restricted (sandbox/container?)", which was misleading because the network was fine.

Downloading the two files by hand into the pinned revision folders fixed it (105 MB + 22 MB, about 2 minutes on the same network). --doctor then said "Grounding PROVEN" in 16.8s. A longer timeout or a resumable download at install time would avoid this. --doctor still shows "Codex MCP is registered but degraded" with the old warmup error, which looks like a cached status from before the fix.

Not verified

• Why the plugin's hooks don't activate in Grok (trust, a compat gap, or a Grok bug).
• Whether Grok also sends snake_case copies of tool_name and the other keys. The docs only mention hook_event_name.
• Whether decision-gate's matcher catches Grok's file-write tools.

Happy to test a branch on Grok if that helps. Thanks for building this, Stu!

[HF-teamdev]

Update: working Grok bridge, tested live

I got the hooks running in Grok with a small bridge. Posting it as a reference implementation for a grok host adapter. It's modeled on your codex-hook.mjs.

What it is

• ~/.grok/hooks/ruvnet-brain.json: Grok always trusts hook files in ~/.grok/hooks/, which gets around the untrusted compat plugin. It mirrors hooks/hooks.json, and every command runs node ~/.grok/ruvnet-brain/grok-hook.mjs <hook-id> [args].
• ~/.grok/ruvnet-brain/grok-hook.mjs:
  1. Adds snake_case aliases for Grok's camelCase keys (stopHookActive → stop_hook_active, sessionId → session_id, toolName/toolInput, lastAssistantMessage, transcriptPath, and so on).
  2. Maps Grok tool names to Claude's: search_replace → Edit (or Write when there's no old_string), run_terminal_command → Bash, read_file → Read, spawn_subagent → Task, and so on.
  3. Skips continuation-gate and grounding-turn-gate when the Stop reason isn't end_turn. Grok fires an extra Stop on session shutdown.
  4. Resolves the active generation from active.json and runs its scripts/hook-shim.mjs with CLAUDE_PLUGIN_ROOT set to that tree, so nightly updates flow through.
  5. Always exits 0, except for a real exit 2 from decision-gate or unprompted-speech. It also writes a key-only event log with no values.

Why the key aliasing matters

Your ADR-0043 (docs/adr/0043-continuation-gate-must-force-not-whisper.md) calls stop_hook_active "the documented loop-safety" and describes the 2026-07-22 incident, where the gate continued the agent "8 times consecutively because the gate ignored stdin". Under Grok, where the key is spelled stopHookActive, that guard can't be reached, so you'd get the same runaway.

Live results (Grok 1.0.34, Brain 4.3.26)

/hooks-list shows all 11 RuvNet hooks. Test prompt, which doesn't mention searching: "What vector database should I use for agent memory in a small Node project?" Grok called ruvnet-brain__search_ruvnet on its own and cited agentdb/docs/adrs/ADR-006-unified-self-learning-rvf-integration.md, ruvector/npm/packages/ruvector/src/index.ts and ruvector/crates/rvf/rvf-adapters/agentdb/src/lib.rs. Bridge log for that turn:

UserPromptSubmit  unprompted-speech    status 0
UserPromptSubmit  ground-ruvnet        status 0  (918 bytes out; Grok discards it)
UserPromptSubmit  grounding-turn-mark  status 0
PostToolUse       grounding-stamp      tool=ruvnet-brain__search_ruvnet  status 0
Stop              continuation-gate    status 0
Stop              session-snapshot     status 0
Stop              grounding-turn-gate  status 0  (allowed: turn was grounded)
--- quitting the session ---
SessionEnd        session-snapshot     status 0
Stop (shutdown)   continuation-gate / grounding-turn-gate  skipped

In offline tests with synthetic Grok payloads, the gate emitted its hookSpecificOutput.additionalContext directive for an ungrounded turn. Grok honors that on Stop and keeps the agent working. With stopHookActive: true, the gate allowed the stop.

Real Grok payload keys, captured live

• UserPromptSubmit: cwd, hookEventName, hook_event_name, permissionMode, prompt, promptId, sessionId, timestamp, workspaceRoot
• PostToolUse: cwd, durationMs, hookEventName, hook_event_name, isBackgrounded, permissionMode, sessionId, timestamp, toolInput, toolInputTruncated, toolName, toolResult (+ tool_response alias per the docs)
• Stop: backgroundTasks, cwd, hookEventName, hook_event_name, lastAssistantMessage, permissionMode, promptId, reason, sessionCrons, sessionId, stopHookActive, timestamp, transcriptPath, workspaceRoot
• SessionEnd: cwd, hookEventName, hook_event_name, permissionMode, reason, sessionId, timestamp, transcriptPath, workspaceRoot

Still open

• SessionStart with a matcher (startup|resume|clear|compact|fork) didn't fire on a fresh Grok session. It probably doesn't match Grok's start-source value, so I dropped the matcher.
• SessionStart and UserPromptSubmit output never reaches Grok's model. That's a Grok limitation. I added one line to ~/.grok/AGENTS.md ("call search_ruvnet first for RuvNet questions"). Between that and the Stop gate, grounding happened unprompted in the test above. The installer could offer to add that line.
• The bridge doesn't handle route-dispatch, hijack-ruvnet, learn-capture or the other hooks the Codex adapter wires. I only mirrored the Claude hooks.json.

~/.grok/ruvnet-brain/grok-hook.mjs

#!/usr/bin/env node
// Grok Build -> RuvNet Brain hook bridge (local workaround for stuinfla/ruvnet-brain#301).
//
// Grok discovers the ruvnet-brain Claude plugin but never activates its hooks (compat plugins are
// untrusted), and Grok's hook stdin uses camelCase keys where the Brain's scripts read Claude's
// snake_case. ~/.grok/hooks/ruvnet-brain.json (always trusted) points every hook here. This file:
//   1. adds snake_case aliases for Grok's camelCase keys and maps Grok tool names to Claude's,
//   2. skips the Stop gates on Grok's extra session-end Stop (reason != "end_turn"),
//   3. runs hook-shim.mjs from the ACTIVE Brain generation (~/.cache/ruvnet-brain/active.json),
//      so nightly Brain updates flow through without touching this file.
// Any failure exits 0: a broken optional hook must never block Grok.
// Set RUVNET_GROK_HOOK_LOG=0 to stop the key-only event log in ~/.grok/ruvnet-brain/events.log.

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { spawnSync } from 'node:child_process';

const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
const LOG = path.join(os.homedir(), '.grok', 'ruvnet-brain', 'events.log');
const args = process.argv.slice(2);
const hookId = args[0] || '';

// Hooks whose exit 2 is a real refusal; every other hook is advisory and always exits 0.
const BLOCKING = new Set(['decision-gate', 'unprompted-speech']);
const STOP_GATES = new Set(['continuation-gate', 'grounding-turn-gate']);
const TIMEOUT_MS = { 'decision-gate': 6000, 'ground-ruvnet': 9000, 'continuation-gate': 9000,
  'grounding-turn-gate': 9000, 'session-snapshot': 9000, 'unprompted-speech': 8000 };

// Grok tool name -> the Claude name the Brain's matchers and parsers expect.
const TOOL_MAP = {
  run_terminal_command: 'Bash', run_terminal_cmd: 'Bash', read_file: 'Read', grep: 'Grep',
  list_dir: 'Glob', web_search: 'WebSearch', web_fetch: 'WebFetch', spawn_subagent: 'Task',
  todo_write: 'TodoWrite',
};

const snake = (k) => k.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);

function readStdin() {
  try { return fs.readFileSync(0); } catch { return Buffer.alloc(0); }
}

function normalize(ev) {
  for (const [k, v] of Object.entries(ev)) {
    const s = snake(k);
    if (s !== k && !(s in ev)) ev[s] = v;
  }
  const input = ev.tool_input && typeof ev.tool_input === 'object' ? ev.tool_input : null;
  if (input) {
    for (const [k, v] of Object.entries(input)) {
      const s = snake(k);
      if (s !== k && !(s in input)) input[s] = v;
    }
    if (!input.file_path) input.file_path = input.path || input.target_file || input.filename;
    if (!input.file_path) delete input.file_path;
  }
  const t = ev.tool_name;
  if (typeof t === 'string') {
    ev.grok_tool_name = t;
    if (TOOL_MAP[t]) ev.tool_name = TOOL_MAP[t];
    else if (t === 'search_replace' || t === 'write_file' || t === 'edit_file') {
      ev.tool_name = input && ('old_string' in input || 'oldString' in input) ? 'Edit' : 'Write';
    }
  }
  return ev;
}

function log(entry) {
  if (process.env.RUVNET_GROK_HOOK_LOG === '0') return;
  try {
    fs.mkdirSync(path.dirname(LOG), { recursive: true });
    try { if (fs.statSync(LOG).size > 256 * 1024) fs.renameSync(LOG, `${LOG}.1`); } catch {}
    fs.appendFileSync(LOG, `${JSON.stringify({ ts: new Date().toISOString(), ...entry })}\n`);
  } catch {}
}

function activeRoot() {
  try {
    const active = JSON.parse(fs.readFileSync(path.join(BRAIN_HOME, 'active.json'), 'utf8'));
    const root = path.resolve(BRAIN_HOME, active.codeRoot);
    const versions = fs.realpathSync(path.join(BRAIN_HOME, 'versions'));
    const real = fs.realpathSync(root);
    return real.startsWith(versions + path.sep) ? real : null;
  } catch { return null; }
}

const raw = readStdin();
let ev = null;
try { ev = raw.length ? JSON.parse(raw.toString('utf8')) : {}; } catch { /* pass through untouched */ }
if (ev && typeof ev === 'object') ev = normalize(ev);

const event = ev?.hook_event_name || process.env.GROK_HOOK_EVENT || '';
const entry = { hook: args.join(' '), event, tool: ev?.grok_tool_name, mapped: ev?.tool_name,
  keys: ev ? Object.keys(ev).filter((k) => !k.includes('_') || k === 'hook_event_name').sort() : null,
  input_keys: ev?.tool_input && typeof ev.tool_input === 'object' ? Object.keys(ev.tool_input).sort() : undefined };

if (STOP_GATES.has(hookId) && ev?.reason && ev.reason !== 'end_turn') {
  log({ ...entry, skipped: `stop reason ${ev.reason}` });
  process.exit(0);
}

const root = activeRoot();
const shim = root && path.join(root, 'scripts', 'hook-shim.mjs');
if (!shim || !fs.existsSync(shim)) { log({ ...entry, error: 'no active brain generation' }); process.exit(0); }

const started = Date.now();
const r = spawnSync(process.execPath, [shim, ...args], {
  input: ev ? JSON.stringify(ev) : raw,
  encoding: 'utf8',
  env: { ...process.env, CLAUDE_PLUGIN_ROOT: root, RUVNET_GROK_BRIDGE: '1' },
  timeout: TIMEOUT_MS[hookId] || 4000,
  killSignal: 'SIGKILL',
});
log({ ...entry, status: r.status, signal: r.signal || undefined, ms: Date.now() - started,
  out_bytes: (r.stdout || '').length, err: (r.stderr || '').split('\n')[0].slice(0, 160) || undefined });

if (r.status === 2 && BLOCKING.has(hookId)) {
  if (r.stdout) process.stdout.write(r.stdout);
  if (r.stderr) process.stderr.write(r.stderr);
  process.exit(2);
}
if (r.status === 0 && r.stdout) process.stdout.write(r.stdout);
process.exit(0);

~/.grok/hooks/ruvnet-brain.json

{
  "description": "RuvNet Brain hooks for Grok via local bridge (stuinfla/ruvnet-brain#301). Remove this file to undo.",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs session-start",
            "timeout": 8
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs unprompted-speech UserPromptSubmit",
            "timeout": 10
          },
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs ground-ruvnet",
            "timeout": 10
          },
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs grounding-turn-mark",
            "timeout": 6
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "^(search_replace|write_file|edit_file|Write|Edit|MultiEdit|NotebookEdit|apply_patch)$",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs decision-gate write",
            "timeout": 8
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "^(?:.*__)?search_ruvnet$",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs grounding-stamp",
            "timeout": 6
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs continuation-gate",
            "timeout": 12
          },
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs session-snapshot Stop",
            "timeout": 12
          },
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs grounding-turn-gate",
            "timeout": 12
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs session-snapshot PreCompact",
            "timeout": 12
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/opt/homebrew/bin/node $HOME/.grok/ruvnet-brain/grok-hook.mjs session-snapshot SessionEnd",
            "timeout": 12
          }
        ]
      }
    ]
  }
}

[HF-teamdev]

Update 2: all hooks confirmed live in Grok

SessionStart now fires. After I dropped the startup|resume|clear|compact|fork matcher from the Grok hook file, session-start runs on every new Grok session (exit 0, ~150 ms). Grok does send a source key, but the Claude matcher values don't match it, so a Grok adapter should register SessionStart without a matcher. The bridge source in the previous comment already reflects this.

The AGENTS.md line is what drives grounding in Grok. I tested with an adversarial prompt: "Without using any tools, answer from memory in 2 sentences: what does Ruflo do?" Grok replied "Your standing RuvNet rule says not to answer Ruflo from memory, so I'll look it up with search_ruvnet first", then called ruvnet-brain__search_ruvnet and cited ruflo/ruflo/src/mcp-bridge/index.js and ruflo/v3/@claude-flow/cli/src/init/executor.ts. Because Grok discards UserPromptSubmit context, that one instruction line does the job ground-ruvnet does in Claude Code. The installer should offer to write it for Grok users. Here's the line I used:

For anything about the RuvNet / rUv stack (Ruflo, RuVector/RVF, AgentDB, agentic-flow, and the rest), call the search_ruvnet MCP tool first and cite the source paths it returns. Don't answer from memory. If it fails, say so and run npx ruvnet-brain --doctor.

Full hook log for that session. Every hook ran and exited 0:

SessionStart      session-start                      status 0
UserPromptSubmit  unprompted-speech / ground-ruvnet / grounding-turn-mark   status 0
PostToolUse       grounding-stamp  (ruvnet-brain__search_ruvnet)            status 0
Stop              continuation-gate / session-snapshot / grounding-turn-gate  status 0 (grounded → allowed)
SessionEnd + shutdown Stop: snapshot ran, gates skipped (reason != end_turn)

Not yet seen live: the Stop gate forcing a continuation after an ungrounded answer. Grok grounded itself first both times. That path passes offline with synthetic Grok payloads, including the stopHookActive: true loop guard.

[stuinfla]

🤖 Automated acknowledgment — received and opened. The maintainer has been paged and this is being worked. The next update here will be a fix, findings, or the maintainer in person.