code-context-control 2.129.1__py3-none-any.whl → 2.131.0__py3-none-any.whl

cli/_hook_utils.py

@@ -392,20 +392,28 @@ def record_unlocked_files(
 #            hookSpecificOutput.hookEventName is REQUIRED. Unknown keys are a
 #            hard deserialization error, not a warning, so emitting the Claude
 #            shape makes Codex discard the whole hook response.
+#   grok   — Grok Build: native tool names and tagged results on the way in
+#            (core/grok_payload.translate); context only under
+#            hookSpecificOutput, and Stop context would keep the agent working.
 HOST_CLAUDE = "claude"
 HOST_GEMINI = "gemini"
 HOST_CODEX = "codex"
+HOST_GROK = "grok"
 
 
 def detect_host(data: dict, explicit_host: str | None = None) -> str:
     """Use the hook's explicit host or wire identity, never its parent's env."""
     named = explicit_host or (data.get("_c3_host") if isinstance(data, dict) else None)
     aliases = {"claude-code": HOST_CLAUDE, "claude": HOST_CLAUDE,
-               "codex": HOST_CODEX, "gemini": HOST_GEMINI, "antigravity": HOST_GEMINI}
+               "codex": HOST_CODEX, "gemini": HOST_GEMINI, "antigravity": HOST_GEMINI,
+               "grok": HOST_GROK, "grok-build": HOST_GROK}
     if named in aliases:
         return aliases[named]
     if not isinstance(data, dict):
         return HOST_CLAUDE
+    from core.grok_payload import is_grok_payload
+    if is_grok_payload(data):
+        return HOST_GROK
     if data.get("turn_id"):
         return HOST_CODEX
     response = data.get("tool_response")

cli/c3.py

@@ -91,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.129.1"
+__version__ = "2.131.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -316,7 +316,7 @@ _BASH_STANDARD = _BASH_READONLY + [
     "Bash(pip:*)", "Bash(pip3:*)", "Bash(npm:*)", "Bash(node:*)",
     "Bash(cargo:*)", "Bash(go:*)",
     # AI CLIs
-    "Bash(claude:*)", "Bash(codex:*)", "Bash(gemini:*)",
+    "Bash(claude:*)", "Bash(codex:*)", "Bash(gemini:*)", "Bash(grok:*)",
     # Utilities
     "Bash(timeout:*)", "Bash(time:*)", "Bash(curl:*)", "Bash(gh:*)",
     "Bash(for:*)", "Bash(do:*)", "Bash(done:*)",
@@ -755,6 +755,7 @@ def _select_init_ide(default_ide: str) -> str:
         "Cursor       — .cursor/mcp.json",
         "Codex        — .codex/config.toml + AGENTS.md",
         "Antigravity  — ~/.gemini/antigravity/mcp_config.json + AGENTS.md",
+        "Grok Build   — .grok/config.toml + .grok/hooks + AGENTS.md",
     ]
     selected = _prompt_choice("Step 1/3 — Choose IDE profile", choices)
     mapping = {
@@ -764,6 +765,7 @@ def _select_init_ide(default_ide: str) -> str:
         choices[3]: "cursor",
         choices[4]: "codex",
         choices[5]: "antigravity",
+        choices[6]: "grok",
     }
     chosen = mapping.get(selected or "", normalize_ide_name(default_ide) if default_ide != "auto" else "auto")
     print(f"  IDE profile: {chosen}")
@@ -1034,7 +1036,7 @@ def _parse_cli_ide_arg(value: str) -> str:
     normalized = normalize_ide_name(raw)
     if normalized not in PROFILES:
         raise argparse.ArgumentTypeError(
-            "Unsupported IDE. Use one of: auto, claude, vscode, cursor, codex, antigravity."
+            "Unsupported IDE. Use one of: auto, claude, vscode, cursor, codex, antigravity, grok."
         )
     return normalized
 
@@ -4333,9 +4335,9 @@ _C3_HOOKLESS_WORKFLOW = _adapt_workflow_for_ide(
 
 _COPILOT_INSTRUCTIONS_CONTENT = _VSCODE_SESSION_INIT + "\n\n" + _C3_HOOKLESS_WORKFLOW
 
-from services.codex_integration import CODEX_WORKFLOW
+from services.agents_workflow import AGENTS_MD_WORKFLOW
 
-_AGENTS_MD_CONTENT = CODEX_WORKFLOW
+_AGENTS_MD_CONTENT = AGENTS_MD_WORKFLOW
 
 _TERSE_SKILL_CONTENT = """\
 # /terse — Terse Output Mode
@@ -4544,7 +4546,7 @@ def _ensure_instruction_workflow(instructions_path: Path, template: str,
 
 def _ensure_codex_agents_workflow(agents_md_path: Path,
                                   project_path: str = "") -> str:
-    """Ensure AGENTS.md contains the mandatory C3 workflow for Codex sessions."""
+    """Ensure AGENTS.md contains the mandatory C3 workflow (Codex and Grok Build read it)."""
     from services.claude_md import write_c3_instruction_doc
     existing = agents_md_path.read_text(encoding="utf-8") if agents_md_path.exists() else None
     rendered = write_c3_instruction_doc(agents_md_path, _AGENTS_MD_CONTENT, project_path or None)
@@ -4888,8 +4890,15 @@ def _uninstall_mcp_all(project_path: str, include_global: bool = True):
                 except Exception as e:
                     print(f"  Warning: Could not update {mcp_config_path}: {e}")
 
+        # Grok Build: C3 owns the whole .grok/hooks/c3.json, so it is deleted
+        # rather than stripped (its Windows commands are encoded and would not
+        # match the settings scanner anyway).
+        if ide_name == "grok":
+            from services.grok_integration import remove_hooks as remove_grok_hooks
+            if remove_grok_hooks(target):
+                print(f"  Deleted {target / profile.settings_path}")
         # Per-host hooks and settings; remove only C3-owned handlers.
-        if profile.supports_hooks and profile.settings_path:
+        elif profile.supports_hooks and profile.settings_path:
             settings_path = target / profile.settings_path
             if settings_path.exists():
                 try:
@@ -4970,7 +4979,7 @@ def _uninstall_mcp_all(project_path: str, include_global: bool = True):
             print(f"  Warning: Could not update {legacy_cfg}: {e}")
 
     # Final pass: clean up empty IDE directories (.claude, .codex, .gemini, .vscode, .github)
-    dirs_to_check = [".claude", ".codex", ".gemini", ".vscode", ".github"]
+    dirs_to_check = [".claude", ".codex", ".grok", ".gemini", ".vscode", ".github"]
     for dname in dirs_to_check:
         dpath = target / dname
         if dpath.exists() and dpath.is_dir():
@@ -5011,7 +5020,7 @@ back to native tools as the task progresses.
 - **Filter**: `c3_filter(text=...)` — for terminal output >10 lines
 - **Shell**: `c3_shell(cmd, timeout=60)` — structured shell exec (tests/git/build). Auto-filters output, logs git mutations to the ledger. Native Bash for interactive/TTY only
 - **Memory**: `c3_memory(action='recall')` — full recall. `index` + `fetch` for token-efficient two-step retrieval
-- **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|auto')` — offload to other models
+- **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|grok|auto')` — offload to other models
 - **Local CI** (v2.79.0+): `c3_ci(action='inspect|run|rerun|failures')` — run THIS repo's real `.github/workflows` here instead of pushing for feedback. `run` executes in `needs` order; `failures` gives {file,line,message}; `rerun` retries only what failed. Only `FULL_CI_PASS` means safe to push — `PARTIAL_PASS` means something did not run (other OS, unsupported action, or your selection).
 - **Bitbucket** (v2.30.0+, when `c3 bitbucket login` has run): `c3_bitbucket(action='list_prs|get_pr|merge_pr|...')` — self-hosted Bitbucket Data Center / Server. Token in OS keyring; mutating actions auto-log to the edit ledger.
 - **Cross-project** (v2.31.0+): `c3_project(action='list|scan|search|read|edit|...', project='<name|path>')` — discover and operate on OTHER c3-installed projects. Reads run freely; writes (edit/shell/memory) need `allow_write=true`.
@@ -5466,6 +5475,12 @@ def cmd_install_mcp(args):
                 toml_entries["startup_timeout_sec"] = 30
                 toml_entries["tool_timeout_sec"] = 60
                 toml_entries["args"] += ["--host", "codex"]
+            elif profile.name == "grok":
+                # Grok's default startup timeout is 30s; a cold C3 index build can
+                # exceed it. Its tool timeout already defaults to 6000s.
+                toml_entries["enabled"] = True
+                toml_entries["startup_timeout_sec"] = 60
+                toml_entries["args"] += ["--host", "grok"]
             _upsert_toml_section(
                 mcp_config_path,
                 f"{profile.config_key}.c3",
@@ -5517,6 +5532,13 @@ def cmd_install_mcp(args):
         from services.codex_integration import install_hooks
         hook_state = install_hooks(target, sys.executable, cli_dir / "hook_dispatch.py")
         print(f"Codex hooks installed; active: {hook_state['active']}. {hook_state['activation']}")
+    if profile.name == "grok":
+        from services.grok_integration import install_hooks as install_grok_hooks
+        grok_hooks = install_grok_hooks(target, sys.executable, cli_dir / "hook_dispatch.py")
+        from services.artifact_defs import note_pending_write
+        note_pending_write(target, profile.settings_path, "install_mcp")
+        print(f"Wrote {target / profile.settings_path}")
+        print(f"Grok Build: {grok_hooks['activation']}")
     if profile.name == "claude-code" and profile.supports_hooks and profile.settings_path:
         settings_dir = target / Path(profile.settings_path).parent
         settings_dir.mkdir(parents=True, exist_ok=True)
@@ -5812,8 +5834,8 @@ def cmd_install_mcp(args):
         print(f"Wrote {vscode_settings_path}")
         print("  Copilot: C3 instructions linked for code gen, review, and test generation")
 
-    # ── Codex AGENTS.md enforcement file ──────────────────────
-    if profile.name == "codex":
+    # ── Codex / Grok Build AGENTS.md enforcement file ────────────
+    if profile.name in ("codex", "grok"):
         agents_md_path = target / "AGENTS.md"
         agents_state = _ensure_codex_agents_workflow(agents_md_path,
                                                      str(target))
@@ -5824,6 +5846,7 @@ def cmd_install_mcp(args):
         else:
             print(f"Kept  {agents_md_path}  (C3 workflow present)")
 
+    if profile.name == "codex":
         # Warn about a common conflict: global Codex config disables c3.
         global_codex_cfg = Path(os.environ.get("CODEX_HOME") or Path.home() / ".codex") / "config.toml"
         global_enabled = _toml_section_bool_value(global_codex_cfg, "mcp_servers.c3", "enabled")
@@ -9303,7 +9326,10 @@ def _launch_tui() -> None:
 
 
 def cmd_doctor(args):
-    from services.codex_integration import diagnose
+    if getattr(args, "ide", "codex") == "grok":
+        from services.grok_integration import diagnose
+    else:
+        from services.codex_integration import diagnose
     print(json.dumps(diagnose(Path(args.project_path).resolve()), indent=2))
 
 

cli/commands/parser.py

@@ -17,15 +17,15 @@ def build_parser(version: str, parse_cli_ide_arg):
     )
     subparsers = parser.add_subparsers(dest="command")
 
-    p_doctor = subparsers.add_parser("doctor", help="Inspect native Codex integration without a model call")
+    p_doctor = subparsers.add_parser("doctor", help="Inspect native Codex or Grok Build integration without a model call")
     p_doctor.add_argument("project_path", nargs="?", default=".")
-    p_doctor.add_argument("--ide", choices=["codex"], default="codex")
+    p_doctor.add_argument("--ide", choices=["codex", "grok"], default="codex")
 
     p_init = subparsers.add_parser("init", help="Initialize C3 for a project")
     p_init.add_argument("project_path", nargs="?", default=".")
     p_init.add_argument("--force", action="store_true", help="Skip prompts and apply update non-interactively")
     p_init.add_argument("--clear", action="store_true", help="Remove all C3 files and exit without rebuilding")
-    p_init.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity}", help="Target IDE for MCP config (default: auto-detect)")
+    p_init.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", help="Target IDE for MCP config (default: auto-detect)")
     p_init.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="Default MCP mode if install is selected during init (default: direct)")
     p_init.add_argument("--git", action="store_true", help="Initialize a local Git repository during init/update")
     p_init.add_argument("--no-embed", action="store_true", help="Skip building the semantic embedding index during init")
@@ -153,7 +153,7 @@ def build_parser(version: str, parse_cli_ide_arg):
 
     p_install_mcp = subparsers.add_parser("install-mcp", help="Generate MCP config for your IDE")
     p_install_mcp.add_argument("targets", nargs="*", help="Optional project path and/or IDE shorthand (for example: `claude` or `. codex`)")
-    p_install_mcp.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity}", help="Target IDE (default: auto-detect)")
+    p_install_mcp.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", help="Target IDE (default: auto-detect)")
     p_install_mcp.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="MCP entrypoint mode (default: direct)")
     p_install_mcp.add_argument("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     p_install_mcp.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")
@@ -161,7 +161,7 @@ def build_parser(version: str, parse_cli_ide_arg):
 
     p_mcp_install = subparsers.add_parser("mcp-install", help="Alias for install-mcp")
     p_mcp_install.add_argument("targets", nargs="*", help="Optional project path and/or IDE shorthand")
-    p_mcp_install.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity}", help="Target IDE (default: auto-detect)")
+    p_mcp_install.add_argument("--ide", default="auto", type=parse_cli_ide_arg, metavar="{auto,claude,vscode,cursor,codex,antigravity,grok}", help="Target IDE (default: auto-detect)")
     p_mcp_install.add_argument("--mcp-mode", choices=["direct", "proxy"], default="direct", help="MCP entrypoint mode (default: direct)")
     p_mcp_install.add_argument("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     p_mcp_install.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")

cli/docs.html

@@ -789,7 +789,7 @@
       <h1 id="overview">Code <span>Companion</span></h1>
       <div class="subtitle">
         A local code intelligence system that reduces AI coding assistant token usage through compression,
-        indexing, and persistent memory. Works with <strong>Claude Code</strong>, <strong>Google Antigravity</strong>,
+        indexing, and persistent memory. Works with <strong>Claude Code</strong>, <strong>OpenAI Codex</strong>, <strong>Grok Build</strong>, <strong>Google Antigravity</strong>,
         <strong>VS Code Copilot</strong>, and <strong>Cursor</strong> via MCP. Available as an <strong>MCP
           server</strong>,
         <strong>CLI</strong>, and <strong>web dashboard</strong>.
@@ -958,7 +958,9 @@ c3 init /path/to/your/project</code></pre>
               <code>.github/copilot-instructions.md</code> (hard enforcement language) and
               <code>.vscode/settings.json</code> (Copilot instruction links). For Codex, generates
               <code>AGENTS.md</code> with the C3 session protocol. Use <code>--ide vscode</code>,
-              <code>--ide cursor</code>, or <code>--ide codex</code> to override IDE detection.
+              <code>--ide cursor</code>, <code>--ide codex</code>, or <code>--ide grok</code> to override IDE detection.
+              For Grok Build, writes <code>.grok/config.toml</code>, <code>.grok/hooks/c3.json</code> and
+              <code>AGENTS.md</code>.
             </div>
           </div>
         </div>
@@ -968,7 +970,9 @@ c3 init /path/to/your/project</code></pre>
             <div class="step-desc">Open your IDE in the project. For Claude Code, run <code>/mcp</code> to verify C3
               tools appear. For Google Antigravity, the MCP tools will be loaded based on your config.
               For VS Code, check MCP tools in the Copilot agent panel. For Codex, the <code>.codex/config.toml</code> is
-              picked up automatically on next session start.</div>
+              picked up automatically on next session start. For Grok Build, launch <code>grok --trust</code> once in
+              the project (Grok ignores project MCP servers, hooks and <code>AGENTS.md</code> in an untrusted folder),
+              then run <code>c3 doctor --ide grok</code>.</div>
           </div>
         </div>
       </div>
@@ -1016,8 +1020,16 @@ c3 init /path/to/your/project</code></pre>
           <td><strong>OpenAI Codex</strong></td>
           <td><code>.codex/config.toml</code></td>
           <td><code>AGENTS.md</code></td>
-          <td>—</td>
-          <td>No</td>
+          <td><code>.codex/hooks.json</code></td>
+          <td>Yes</td>
+          <td>Yes</td>
+        </tr>
+        <tr>
+          <td><strong>Grok Build</strong></td>
+          <td><code>.grok/config.toml</code></td>
+          <td><code>AGENTS.md</code></td>
+          <td><code>.grok/hooks/c3.json</code></td>
+          <td>Yes (after <code>grok --trust</code>)</td>
           <td>No</td>
         </tr>
         <tr>
@@ -1050,11 +1062,13 @@ python cli/c3.py install-mcp /path/to/project --ide vscode
 python cli/c3.py install-mcp /path/to/project --ide cursor
 python cli/c3.py install-mcp /path/to/project --ide claude
 python cli/c3.py install-mcp /path/to/project --ide codex
+python cli/c3.py install-mcp /path/to/project --ide grok
 python cli/c3.py install-mcp /path/to/project --ide antigravity
 
 # IDE shorthand when already inside the project directory
 python cli/c3.py install-mcp claude
 python cli/c3.py install-mcp codex
+python cli/c3.py install-mcp grok
 python cli/c3.py install-mcp . antigravity</code></pre>
 
       <p><code>--git</code> runs a local-only <code>git init</code>. It does not create remotes or connect to GitHub,
@@ -1111,6 +1125,32 @@ python cli/c3.py install-mcp . antigravity</code></pre>
         </li>
       </ul>
 
+      <p><strong>Grok Build</strong> &mdash; <code>install-mcp --ide grok</code> (and <code>c3 init --ide grok</code>)
+        configure xAI's <code>grok</code> CLI. Everything is project-local:</p>
+      <ul>
+        <li><code>.grok/config.toml</code> &mdash; a <code>[mcp_servers.c3]</code> table (the same TOML shape as Codex)
+          with <code>--host grok</code> and <code>startup_timeout_sec = 60</code>. Other servers and keys are kept.
+          Auto-detected when <code>.grok/config.toml</code> or a <code>.grok/</code> directory exists.
+        </li>
+        <li><code>.grok/hooks/c3.json</code> &mdash; C3's handlers for PreToolUse, PostToolUse, SessionStart,
+          PreCompact, Stop and SessionEnd. C3 owns the whole file. On Windows each command is a
+          <code>powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand</code> line so it runs under
+          whichever shell Grok picks.
+        </li>
+        <li><code>AGENTS.md</code> &mdash; shared with Codex and Antigravity; only the C3 block is refreshed.</li>
+        <li><strong>Folder trust</strong> &mdash; Grok loads none of these until the folder is trusted. Launch
+          <code>grok --trust</code> once in the project (or run <code>/hooks-trust</code> inside Grok). C3 never
+          writes <code>~/.grok/trusted_folders.toml</code> or <code>~/.grok/config.toml</code>;
+          <code>c3 doctor --ide grok</code> reports the CLI version, hook install and trust state.
+        </li>
+        <li><strong>Limitations</strong> &mdash; C3 tools are reached through Grok's <code>search_tool</code> /
+          <code>use_tool</code> and appear as <code>c3__c3_search</code> and so on; PreToolUse hints reach the model
+          after the call runs (denies still block before it); there is no prompt-time memory recall; Stop-hook output
+          is never emitted; with both <code>AGENTS.md</code> and <code>CLAUDE.md</code> present, Grok loads the C3
+          block twice. Full guide: <code>docs/grok-native.md</code>.
+        </li>
+      </ul>
+
       <h3>Graceful Degradation</h3>
       <p>All core C3 tools (search, compress, file_map, memory, sessions) work identically in every IDE. Claude-specific
         features degrade gracefully:</p>
@@ -1118,7 +1158,7 @@ python cli/c3.py install-mcp . antigravity</code></pre>
         <li><strong>Transcript search</strong> — returns a helpful message suggesting <code>c3_memory(action='recall')</code> or
           <code>c3_memory(action='query')</code> as alternatives
         </li>
-        <li><strong>Hooks</strong> — only installed for Claude Code; VS Code, Cursor, and Codex use hard-language
+        <li><strong>Hooks</strong> — installed for Claude Code, Codex and Grok Build; VS Code and Cursor use hard-language
           workflow instructions in their instructions file instead</li>
         <li><strong>Instructions file</strong> — <code>c3_claudemd_generate</code> writes to the IDE-appropriate file
           (CLAUDE.md, copilot-instructions.md, .cursorrules, AGENTS.md, or GEMINI.md). All IDEs use MANDATORY/NEVER
@@ -2053,10 +2093,12 @@ c3 ui /path/to/your/project --silent         # Hide API request logs in terminal
           <div class="tab-name"><span class="badge badge-green">11</span> Settings</div>
           <div class="tab-desc">Project info (editable name, tech stack, description), quick actions (rebuild index,
             save instructions file), project data management (view sizes and item counts per .c3/ category, clear
-            actions), instructions file management, and MCP management: target IDE selector (Claude/Gemini/VS
-            Code/Cursor/Codex/Antigravity), custom MCP add form, installed MCP cards, and per-card trash removal.
+            actions), instructions file management, and MCP management: target IDE selector (Claude/VS
+            Code/Cursor/Codex/Grok Build/Antigravity), custom MCP add form, installed MCP cards, and per-card trash removal.
             Removing <code>c3</code> can also clean related IDE files/hooks. Includes IDE selector for C3 MCP
-            installation and optimization suggestions.</div>
+            installation and optimization suggestions. Delegate backend sections (Codex, Gemini, Grok Build) hold each
+            backend's enable switch, model, timeouts and auto-routed task types; the Grok Build section adds max turns
+            and the write-mode switch (<code>grok_allow_write</code>).</div>
         </div>
       </div>
 
@@ -2595,13 +2637,13 @@ c3 ui /path/to/your/project --silent         # Hide API request logs in terminal
       </p>
 
       <h3>Project Setup</h3>
-          <pre><code>c3 init &lt;project_path&gt; [--ide auto|claude|vscode|cursor|codex|gemini] [--force]
+          <pre><code>c3 init &lt;project_path&gt; [--ide auto|claude|vscode|cursor|codex|grok|antigravity] [--force]
                                            # Initialize C3: builds index, creates config, generates instructions file,
                                            # and automatically installs the MCP config for your IDE.
                                            # Re-running on an existing project now migrates config defaults and
                                            # refreshes instruction workflow files (Update / Clear / Reset options).
 c3 index [--max-files 500]                 # Rebuild the code index
-c3 install-mcp [project_path] [ide] [--ide auto|claude|vscode|cursor|codex|gemini]  # (Re-)generate MCP config manually
+c3 install-mcp [project_path] [ide] [--ide auto|claude|vscode|cursor|codex|grok|antigravity]  # (Re-)generate MCP config manually
 c3 ui [project_path] [--port 3333] [--nano] [--silent]   # Launch web dashboard (full or nano)</code></pre>
 
       <h3>Compression &amp; Search</h3>
@@ -2652,7 +2694,7 @@ c3 session load | claude --resume</code></pre>
 
       <div class="arch">
         <pre>
-  <strong>IDE</strong> (Claude Code / VS Code Copilot / Cursor / Codex / Gemini CLI)
+  <strong>IDE</strong> (Claude Code / VS Code Copilot / Cursor / Codex / Grok Build / Antigravity)
        | MCP Protocol (IDE-specific config file)
        v
   <strong>MCP Proxy</strong> ──── Dynamic tool filtering + context injection (optional, opt-in via MCP config)
@@ -2872,7 +2914,7 @@ c3 session load | claude --resume</code></pre>
     protocol.py          # Compression protocol encoder/decoder
   core/
     __init__.py          # Token counting utilities
-    ide.py               # IDE profile registry (Claude Code, VS Code, Cursor, Codex) + auto-detection
+    ide.py               # IDE profile registry (Claude Code, VS Code, Cursor, Codex, Antigravity, Grok Build) + auto-detection
     config.py            # Hybrid, proxy, delegate, and agent configuration loaders
   install.bat            # Windows installer
   install.sh             # Linux/macOS installer
@@ -3023,8 +3065,11 @@ c3 session load | claude --resume</code></pre>
         <ul>
           <li>Make sure the MCP config file exists (<code>.mcp.json</code> for Claude Code,
             <code>.vscode/mcp.json</code> for VS Code, <code>.cursor/mcp.json</code> for Cursor,
-            <code>.codex/config.toml</code> for Codex)
+            <code>.codex/config.toml</code> for Codex, <code>.grok/config.toml</code> for Grok Build)
           </li>
+          <li>For Grok Build, trust the folder first (<code>grok --trust</code> or <code>/hooks-trust</code>), then
+            check <code>c3 doctor --ide grok</code>, <code>grok mcp doctor c3 --json</code> and <code>grok inspect</code>.
+            Run <code>/hooks</code> inside Grok to see whether C3's hooks loaded.</li>
           <li>Check that the Python path in the config is correct (<code>"command"</code> field for JSON configs;
             <code>command</code> key for Codex TOML)
           </li>

cli/guide/getting-started.html

@@ -174,7 +174,11 @@ c3 init</code></pre>
           </tr>
           <tr>
             <td><code>AGENTS.md</code></td>
-            <td>Instructions for Codex sessions</td>
+            <td>Instructions for Codex, Grok Build and Antigravity sessions</td>
+          </tr>
+          <tr>
+            <td><code>.grok/config.toml</code>, <code>.grok/hooks/c3.json</code></td>
+            <td>Grok Build only: project MCP entry and C3's hooks (written by <code>--ide grok</code>)</td>
           </tr>
         </tbody>
       </table>
@@ -231,6 +235,12 @@ c3 init</code></pre>
       <pre><code>c3 install-mcp antigravity</code></pre>
       <p>Updates the user-global <code>~/.gemini/antigravity/mcp_config.json</code> and <code>AGENTS.md</code>.</p>
 
+      <h3>Grok Build</h3>
+      <pre><code>c3 install-mcp grok
+grok --trust
+c3 doctor --ide grok</code></pre>
+      <p>Updates <code>.grok/config.toml</code> (<code>[mcp_servers.c3]</code>), writes C3's hooks to <code>.grok/hooks/c3.json</code>, and refreshes the C3 block in <code>AGENTS.md</code>. Grok loads none of them until the folder is trusted, so launch <code>grok --trust</code> once in the project (or run <code>/hooks-trust</code> inside Grok). C3 never writes Grok's trust store or <code>~/.grok/config.toml</code>. In Grok, C3's tools are reached through <code>search_tool</code> / <code>use_tool</code> as <code>c3__c3_search</code> and so on. Details and limitations: <code>docs/grok-native.md</code>.</p>
+
       <p><em>The Gemini CLI profile was removed in v2.52 — use Antigravity instead. <code>c3 uninstall</code> still cleans up legacy <code>.gemini/settings.json</code> and <code>GEMINI.md</code> files.</em></p>
 
       <h3>All IDEs at once</h3>

cli/guide/workflow.html

@@ -997,7 +997,7 @@ c3_memory(action=<span class="str">'recall'</span>, query=<span class="str">'pay
       <p>Everything the CLI does — plus the operations that need multi-step safety — is available in the Hub:</p>
       <ul>
         <li><strong>"Link project by path…"</strong> (v2.96.0) — kebab menu on any card, at any depth. Browse anywhere or paste a path; C3 inspects it before anything happens and shows you what you are about to claim — the project's name and version, whether the hub already knows it, how much is in it, who already claims it, and what sub-projects it would bring with it. One confirm registers and links an unregistered project. Unlinked nested projects it finds are offered as suggestions, never applied.</li>
-        <li><strong>Designate</strong> — kebab menu → "Designate sub-project…" on any project card, or from the drill-in <strong>Sub-projects</strong> tab. A folder picker fenced to the parent's subtree validates the choice, shows adopt-vs-initialize expectations up front, and offers an instruction-docs/IDE picker (<code>auto | claude | vscode | cursor | codex | antigravity</code>).</li>
+        <li><strong>Designate</strong> — kebab menu → "Designate sub-project…" on any project card, or from the drill-in <strong>Sub-projects</strong> tab. A folder picker fenced to the parent's subtree validates the choice, shows adopt-vs-initialize expectations up front, and offers an instruction-docs/IDE picker (<code>auto | claude | vscode | cursor | codex | grok | antigravity</code>).</li>
         <li><strong>"Make sub-project of…"</strong> — the reverse move: pick any registered project to sit under. The only projects excluded are this one and its own descendants.</li>
         <li><strong>Sub-projects drill tab</strong> — per-child rows with inline <em>Validate</em> and <em>Promote</em>; inline <em>Reconcile</em> with per-issue detail and planned repair actions; a <em>Cascade</em> launcher with operation picker, include-parent toggle, affected-children preview, live progress, and Cancel.</li>
         <li><strong>Link health, passively</strong> — parents show a red "N link issues" badge and children a status badge (<code>ok · backlink_broken · unregistered · missing_folder · missing_c3 · orphan</code>), computed from config + filesystem on every listing — no manual reconcile needed to spot trouble.</li>
@@ -1022,7 +1022,7 @@ c3_memory(action=<span class="str">'recall'</span>, query=<span class="str">'pay
     <section class="section" id="repo-map">
       <div class="section-title"><span class="icon">🗺️</span> Live Repo Map (v2.60.0)</div>
 
-      <p>Instruction docs (CLAUDE.md / AGENTS.md) no longer embed a frozen project tree. They carry a stable pointer to <code>.c3/MAP.md</code> — a machine-owned map C3 keeps fresh automatically. One map serves every consumer: Claude Code, Codex, Antigravity.</p>
+      <p>Instruction docs (CLAUDE.md / AGENTS.md) no longer embed a frozen project tree. They carry a stable pointer to <code>.c3/MAP.md</code> — a machine-owned map C3 keeps fresh automatically. One map serves every consumer: Claude Code, Codex, Grok Build, Antigravity.</p>
 
       <p>The map contains, in priority order: build/test commands, entry points, module one-liners, the depth-2 tree, and key files — under a token budget (default 1000). Sub-projects appear as boundaries and are never expanded into the parent map.</p>
 

cli/hook_dispatch.py

@@ -57,6 +57,7 @@ from cli._hook_utils import (  # noqa: E402
     HOST_CLAUDE,
     HOST_CODEX,
     HOST_GEMINI,
+    HOST_GROK,
     detect_host,
     log_hook_error,
     normalize_tool_name,
@@ -142,7 +143,10 @@ def _routes(event: str, raw_tool: str, norm_tool: str, host: str = HOST_CLAUDE):
         # is also pointless — its schema has no tool_result, so the filtered
         # text could never replace the output anyway. Skip it entirely rather
         # than risk an allocation failure for a result we must discard.
-        if norm_tool == "Bash" and host != HOST_CODEX:
+        # Grok is excluded for the same reason: it validates a built-in tool's
+        # replacement output against Grok's own tagged shape, so a filtered
+        # string could not replace the result there either.
+        if norm_tool == "Bash" and host not in (HOST_CODEX, HOST_GROK):
             yield "hook_filter"
         if norm_tool == "Read":
             yield "hook_read"
@@ -164,7 +168,10 @@ def _routes(event: str, raw_tool: str, norm_tool: str, host: str = HOST_CLAUDE):
     elif event == "stop":
         yield "hook_session_stats"
         yield "hook_codex_lifecycle" if host == HOST_CODEX else "hook_auto_snapshot"
-        yield "hook_terse_advisor"
+        # Advice needs a channel to the model; Grok's Stop has none that does
+        # not also keep the agent working, and its transcript is not Claude's.
+        if host != HOST_GROK:
+            yield "hook_terse_advisor"
     elif event == "prompt":
         yield "hook_prompt_recall"
     elif event in ("start", "compact", "end"):
@@ -345,6 +352,34 @@ def _codex_output(event: str, deny_hso, contexts: list, tool_result,
     return result or None
 
 
+# Grok Build delivers hookSpecificOutput.additionalContext for tool events.
+# Everything else is passive (SessionStart/End, PreCompact) or harmful: Stop
+# context "keeps the agent working" for up to 8 continuations, and an allowing
+# UserPromptSubmit hook's stdout is discarded. Those events print nothing.
+_GROK_EVENT_NAMES = {"pretool": "PreToolUse", "posttool": "PostToolUse"}
+
+
+def _grok_output(event: str, deny_hso, contexts: list, tool_result,
+                 texts: list) -> dict | None:
+    """Serialize merged sub-hook results into Grok Build's hook contract."""
+    event_name = _GROK_EVENT_NAMES.get(event)
+    if event_name is None:
+        return None
+    if deny_hso is not None and event == "pretool":
+        # A deny drops any context on Grok's side anyway; send only the verdict.
+        return {"hookSpecificOutput": {
+            "hookEventName": event_name,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": str(deny_hso.get("permissionDecisionReason") or "Blocked by C3"),
+        }}
+    if tool_result is not None:
+        contexts.insert(0, str(tool_result))
+    joined = "\n".join(c for c in [*contexts, *texts] if c)
+    if not joined:
+        return None
+    return {"hookSpecificOutput": {"hookEventName": event_name, "additionalContext": joined}}
+
+
 def merge_outputs(outputs: list, warnings: list, is_gemini: bool = False,
                   event: str = "", host: str | None = None) -> dict | None:
     """Compose sub-hook outputs into ONE host-appropriate hook response.
@@ -393,6 +428,8 @@ def merge_outputs(outputs: list, warnings: list, is_gemini: bool = False,
 
     if host == HOST_CODEX:
         return _codex_output(event, deny_hso, contexts, tool_result, texts)
+    if host == HOST_GROK:
+        return _grok_output(event, deny_hso, contexts, tool_result, texts)
 
     is_gemini = host == HOST_GEMINI
     result: dict = {}
@@ -477,6 +514,9 @@ def _collect(event: str, payload: dict, project_path: Path | None = None):
 
 def dispatch(event: str, payload: dict, project_path: Path | None = None) -> dict | None:
     host = detect_host(payload)
+    if host == HOST_GROK:
+        from core.grok_payload import translate
+        payload = translate(payload)
     payload = {**payload, "hook_event_name": payload.get("hook_event_name") or _CODEX_EVENT_NAMES.get(event, event)}
     if payload.get("tool_name") == "apply_patch" and event in ("pretool", "posttool"):
         from core.codex_patch import patch_targets
@@ -517,7 +557,7 @@ def main() -> None:
     import argparse
     parser = argparse.ArgumentParser()
     parser.add_argument("event", nargs="?", default="")
-    parser.add_argument("--host", choices=["codex", "claude", "claude-code", "gemini"])
+    parser.add_argument("--host", choices=["codex", "claude", "claude-code", "gemini", "grok"])
     parser.add_argument("--project")
     args = parser.parse_args()
     event = args.event.strip().lower()

cli/hook_session_stats.py

@@ -100,8 +100,29 @@ def read_transcript_usage(transcript_path) -> dict:
 
 def run(payload: dict, project_path: Path | None = None):
     """Core logic — importable by the dispatcher and tests. Returns None."""
-    from cli._hook_utils import HOST_CODEX, detect_host
-    if detect_host(payload) == HOST_CODEX:
+    from cli._hook_utils import HOST_CODEX, HOST_GROK, detect_host
+    host = detect_host(payload)
+    if host == HOST_GROK:
+        from services.grok_transcript import read_usage
+        base = Path(project_path or payload.get("cwd") or Path.cwd()).resolve()
+        usage = read_usage(payload.get("transcript_path"), str(payload.get("session_id") or ""))
+        row = {"ts": datetime.now(timezone.utc).isoformat(), "session_id": payload.get("session_id"),
+               "provider": "grok", "source": "transcript" if usage is not None else "none",
+               "stop_reason": payload.get("reason"),
+               "input_tokens": usage["input_tokens"] if usage else None,
+               "input_tokens_including_cache": usage["input_tokens_including_cache"] if usage else None,
+               "output_tokens": usage["output_tokens"] if usage else None,
+               "cache_read_tokens": usage["cache_read_tokens"] if usage else None,
+               "cache_creation_tokens": usage["cache_creation_tokens"] if usage else None,
+               "reasoning_tokens": usage["reasoning_tokens"] if usage else None,
+               # Grok measures and reports its own cost, so it is recorded as given.
+               "cost_usd": usage["cost_usd"] if usage else None,
+               "model": usage["model"] if usage else ""}
+        if (base / ".c3").is_dir():
+            with (base / ".c3" / "session_stats.jsonl").open("a", encoding="utf-8") as stream:
+                stream.write(json.dumps(row) + "\n")
+        return None
+    if host == HOST_CODEX:
         from services.codex_transcript import read_rollout
         base = Path(project_path or payload.get("cwd") or Path.cwd()).resolve()
         transcript = payload.get("transcript_path")