plugin-scanner 2.2.105__tar.gz → 2.2.107__tar.gz

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.2.105
+Version: 2.2.107
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Security, https://hol.org/guard/security
@@ -259,7 +259,7 @@ artifact and policy pipeline as existing command classifications.
 - `kimi`
   Guard installs managed `PreToolUse` and `UserPromptSubmit` hooks in `~/.kimi-code/config.toml`, blocks with exit code `2` and a JSON `permissionDecision: "deny"` response, and fails open on hook crash or timeout.
 - `grok`
-  Guard installs managed Grok hook JSON under `~/.grok/hooks/` plus permission deny rules in `~/.grok/managed_config.toml`, blocks with exit code `2` and a Grok-native `{"decision":"deny"}` response, never reads `~/.grok/auth`, and launches only a trusted absolute Grok executable. Custom install roots can be selected once with `hol-guard run grok --grok-executable /absolute/path/to/grok`.
+  Guard installs a catch-all Grok `PreToolUse` hook plus observe-only prompt and subagent hooks under `~/.grok/hooks/`, writes permission deny rules and backup hooks in `~/.grok/managed_config.toml`, blocks tool calls with exit code `2` and a Grok-native `{"decision":"deny"}` response, never reads `~/.grok/auth`, and launches only a trusted absolute Grok executable. Custom install roots can be selected once with `hol-guard run grok --grok-executable /absolute/path/to/grok`. After upgrading an existing Grok install, run `hol-guard apps repair grok` so the catch-all hook replaces the older per-tool matcher list.
 - `pi`
   Guard scans `~/.pi/agent/` and project `.pi/` packages, extensions, skills, prompts, and themes; installs a managed Pi extension that reviews `input` and `tool_call` events inline; and blocks with a Pi-native `{"decision":"deny"}` response when Guard policy says no.
 - `zcode`

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/README.md

@@ -206,7 +206,7 @@ artifact and policy pipeline as existing command classifications.
 - `kimi`
   Guard installs managed `PreToolUse` and `UserPromptSubmit` hooks in `~/.kimi-code/config.toml`, blocks with exit code `2` and a JSON `permissionDecision: "deny"` response, and fails open on hook crash or timeout.
 - `grok`
-  Guard installs managed Grok hook JSON under `~/.grok/hooks/` plus permission deny rules in `~/.grok/managed_config.toml`, blocks with exit code `2` and a Grok-native `{"decision":"deny"}` response, never reads `~/.grok/auth`, and launches only a trusted absolute Grok executable. Custom install roots can be selected once with `hol-guard run grok --grok-executable /absolute/path/to/grok`.
+  Guard installs a catch-all Grok `PreToolUse` hook plus observe-only prompt and subagent hooks under `~/.grok/hooks/`, writes permission deny rules and backup hooks in `~/.grok/managed_config.toml`, blocks tool calls with exit code `2` and a Grok-native `{"decision":"deny"}` response, never reads `~/.grok/auth`, and launches only a trusted absolute Grok executable. Custom install roots can be selected once with `hol-guard run grok --grok-executable /absolute/path/to/grok`. After upgrading an existing Grok install, run `hol-guard apps repair grok` so the catch-all hook replaces the older per-tool matcher list.
 - `pi`
   Guard scans `~/.pi/agent/` and project `.pi/` packages, extensions, skills, prompts, and themes; installs a managed Pi extension that reviews `input` and `tool_call` events inline; and blocks with a Pi-native `{"decision":"deny"}` response when Guard policy says no.
 - `zcode`

plugin_scanner-2.2.107/ci/test-suite-ratchet-baseline.json

@@ -0,0 +1,5 @@
+{
+  "maximum_collected_cases": 12730,
+  "maximum_test_source_lines": 290450,
+  "schema_version": 1
+}

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/docs/guard/get-started.md

@@ -400,11 +400,13 @@ Current strategy:
   calls and prompts with exit code `2` plus a JSON `permissionDecision: "deny"` response, and fails open on hook crash
   or timeout
 - `grok`
-  installs Guard-owned Grok hook JSON in `~/.grok/hooks/` and permission deny rules in `~/.grok/managed_config.toml`,
-  blocks with Grok-native stdout JSON `{"decision":"deny"}` plus approval-center copy, never reads `~/.grok/auth`, and
-  treats `--always-approve` or `bypassPermissions` as degraded protection when detected. Guard launches only a trusted
+  installs a catch-all Guard `PreToolUse` hook plus observe-only prompt and subagent hooks in `~/.grok/hooks/`,
+  writes permission deny rules and backup hooks in `~/.grok/managed_config.toml`, blocks tool calls with Grok-native
+  stdout JSON `{"decision":"deny"}` plus approval-center copy, never reads `~/.grok/auth`, and treats
+  `--always-approve` or `bypassPermissions` as degraded protection when detected. Guard launches only a trusted
   absolute Grok executable; for a custom install root, select it once with
-  `hol-guard run grok --grok-executable /absolute/path/to/grok`.
+  `hol-guard run grok --grok-executable /absolute/path/to/grok`. After upgrading an existing Grok install, run
+  `hol-guard apps repair grok` so the catch-all hook replaces the older per-tool matcher list.
 
 Guard does not claim VS Code Copilot extension-host interception in this pass. A VS Code inline tool prompt by itself is
 not proof that Guard blocked the action, because that prompt can come from VS Code's own permission surface. For Copilot,

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/docs/guard/harness-support.md

@@ -86,11 +86,12 @@ Current Guard support in this repo:
   - fails open if a hook crashes or times out, so Kimi Code keeps working when Guard is unreachable
   - uses the same JSON stdin/stdout wire protocol as Codex and Claude Code
 - `grok`
-  - detects a trusted absolute `grok` executable, `~/.grok/config.toml`, `~/.grok/managed_config.toml`, `~/.grok/hooks/`, skills, plugins, and project `.grok/` surfaces
+  - detects a trusted absolute `grok` executable, `~/.grok/config.toml`, `~/.grok/managed_config.toml`, `~/.grok/hooks/`, skills, plugins, agents, personas, workflows, sandbox profiles, and project `.grok/` surfaces
   - rejects relative, current-directory, workspace, unsafe-owner/mode, and workspace-targeting symlink executables before probing or launch; custom install roots can be selected once with `hol-guard run grok --grok-executable /absolute/path/to/grok`
   - binds an explicit custom selection to its SHA-256 identity and sanitizes code-loader variables and unsafe PATH entries without adding prompts to unchanged launches
-  - installs Guard-owned `PreToolUse` hooks for `Bash`, `Read`, `Edit`, `Grep`, `MCPTool`, and `WebFetch` plus `UserPromptSubmit` prompt screening in `~/.grok/hooks/hol-guard-*.json`
-  - installs Guard-managed deny rules in `~/.grok/managed_config.toml` without touching user `~/.grok/config.toml` or `~/.grok/auth`
+  - installs one catch-all `PreToolUse` hook so native tools, `spawn_subagent`, `list_dir`, and `server__tool` MCP names are reviewed once
+  - installs observe-only `UserPromptSubmit`, `SubagentStart`, and `SessionStart` hooks for inventory; Grok ignores deny on those events
+  - installs Guard-managed deny rules and backup hooks in `~/.grok/managed_config.toml` without touching user `~/.grok/config.toml` or `~/.grok/auth`
   - blocks by returning exit code `2` and Grok-native stdout JSON `{"decision":"deny","reason":"..."}` with approval-center copy in stderr
   - surfaces `--always-approve`, `bypassPermissions`, and sandbox `off` as degraded protection states when detected in Grok config
   - fails open if a hook crashes or times out, so Grok keeps working when Guard is unreachable
@@ -170,7 +171,7 @@ Generated from `src/codex_plugin_scanner/guard/adapters/contracts.py`.
 | `openclaw` | `openclaw` | ❌ | ✅ | ❌ | mcp_tool |
 | `antigravity` | `antigravity` | ❌ | ✅ | ❌ | mcp_tool, prompt |
 | `kimi` | `kimi`, `kimi-code`, `kimi-cli` | ❌ | ✅ | ❌ | shell, prompt |
-| `grok` | `grok`, `grok-build`, `grok-build-cli`, `xai-grok` | ❌ | ✅ | ❌ | shell, prompt, mcp_tool, file_read |
+| `grok` | `grok`, `grok-build`, `grok-build-cli`, `xai-grok` | ❌ | ✅ | ❌ | shell, prompt, mcp_tool, file_read, file_write |
 | `pi` | `pi`, `pi-agent`, `pi-coding-agent` | ✅ | ✅ | ✅ | shell, prompt, mcp_tool, file_read, tool_result |
 | `omp` | `omp`, `oh-my-pi` | ✅ | ✅ | ✅ | shell, prompt, mcp_tool, file_read, tool_result |
 | `zcode` | `zcode`, `zai`, `z-code`, `zai-zcode` | ❌ | ✅ | ❌ | shell, prompt, mcp_tool, file_read |

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.2.105"
+version = "2.2.107"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.2.105"
+version = "2.2.107"
 description = "Open-source antivirus and runtime protection for AI agents, tools, MCP servers, plugins, skills, and package installs."
 readme = "README.md"
 license = "Apache-2.0"

plugin_scanner-2.2.105/release-metadata/plugin-scanner-v2.2.105.toolchain.cdx.json → plugin_scanner-2.2.107/release-metadata/plugin-scanner-v2.2.107.toolchain.cdx.json

@@ -27,7 +27,7 @@
     "component": {
       "name": "hol-guard-release-toolchain",
       "type": "application",
-      "version": "2.2.105"
+      "version": "2.2.107"
     }
   },
   "specVersion": "1.6",

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/src/codex_plugin_scanner/guard/adapters/contracts.py

@@ -307,13 +307,15 @@ HARNESS_CONTRACTS: tuple[HarnessProtectionContract, ...] = (
             "~/.grok/managed_config.toml",
             "~/.grok/hooks/",
         ),
-        event_surfaces=("shell", "prompt", "mcp_tool", "file_read"),
+        event_surfaces=("shell", "prompt", "mcp_tool", "file_read", "file_write"),
         native_approval=False,
         browser_fallback=True,
         resume_support=False,
         known_blind_spots=(
-            "--always-approve and bypassPermissions weaken prompt policy, but the bounded Guard hook still "
-            "returns a native deny when its local review cannot finish."
+            "Grok UserPromptSubmit hooks are observe-only, so prompt screening cannot block the model from "
+            "seeing a prompt. Enforcement is the catch-all PreToolUse hook, including subagent and MCP tools. "
+            "--always-approve and bypassPermissions weaken Grok's own prompt policy, but the Guard hook still "
+            "returns a native deny when policy blocks a tool call."
         ),
         smoke_command="hol-guard install grok --dry-run",
     ),

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/src/codex_plugin_scanner/guard/adapters/grok.py

@@ -28,7 +28,9 @@ from .grok_config import (
     GROK_DIR,
     GROK_HOOKS_DIR,
     GROK_MANAGED_CONFIG_FILE,
+    GROK_PROJECT_SURFACE_RELATIVES,
     GROK_REQUIREMENTS_FILE,
+    GROK_SURFACE_RELATIVES,
     GUARD_HOOK_PRETOOL_FILE,
     GUARD_HOOK_PROMPT_FILE,
     GUARD_MANAGED_BEGIN,
@@ -39,6 +41,7 @@ from .grok_config import (
     append_mcp_artifacts,
     append_permission_artifacts,
     build_managed_config_block,
+    build_observe_hook_json,
     build_pretool_hook_json,
     degraded_mode_warnings,
     remove_managed_block,
@@ -69,12 +72,12 @@ class GrokHarnessAdapter(HarnessAdapter):
     launcher_name = "grok"
     approval_tier = "approval-center"
     approval_summary = (
-        "Guard intercepts Grok tool calls through native PreToolUse hooks and routes blocked "
-        "actions to the local approval center."
+        "Guard intercepts every Grok tool call, including subagent and MCP tools, through a "
+        "catch-all PreToolUse hook and routes blocked actions to the local approval center."
     )
     fallback_hint = (
-        "Grok receives plain-language allow or deny responses from Guard hooks. "
-        "Use the Guard approval center when native prompting is unavailable."
+        "Grok prompt hooks are observe-only; enforcement happens on PreToolUse. "
+        "Use the Guard approval center when a tool call is denied."
     )
 
     @staticmethod
@@ -272,13 +275,13 @@ class GrokHarnessAdapter(HarnessAdapter):
                     )
                 )
 
-        for relative in ("skills", "plugins", "plugins/marketplaces", "plugins/known_marketplaces.json", "sessions"):
+        for relative in GROK_SURFACE_RELATIVES:
             candidate = grok_root / relative
             if candidate.exists():
                 append_found_path(found_paths, candidate)
 
         if project_root is not None:
-            for relative in ("skills", "plugins", "hooks"):
+            for relative in GROK_PROJECT_SURFACE_RELATIVES:
                 candidate = project_root / relative
                 if candidate.exists():
                     append_found_path(found_paths, candidate)
@@ -399,26 +402,11 @@ class GrokHarnessAdapter(HarnessAdapter):
 
         pretool_payload = build_pretool_hook_json(hook_command)
         pretool_path.write_text(json.dumps(pretool_payload, indent=2) + "\n", encoding="utf-8")
-        prompt_payload = {
-            "hooks": {
-                "UserPromptSubmit": [
-                    {
-                        "hooks": [
-                            {
-                                "type": "command",
-                                "command": hook_command,
-                                "timeout": 30,
-                            }
-                        ]
-                    }
-                ]
-            }
-        }
-        prompt_path.write_text(json.dumps(prompt_payload, indent=2) + "\n", encoding="utf-8")
+        prompt_path.write_text(json.dumps(build_observe_hook_json(hook_command), indent=2) + "\n", encoding="utf-8")
 
         existing_text = managed_config_path.read_text(encoding="utf-8") if managed_config_path.is_file() else ""
         cleaned_text = remove_managed_block(existing_text)
-        managed_block = build_managed_config_block()
+        managed_block = build_managed_config_block(hook_command)
         managed_config_path.write_text(f"{cleaned_text.rstrip()}\n\n{managed_block}\n".lstrip(), encoding="utf-8")
 
         self._state_path(context).write_text(
@@ -444,8 +432,9 @@ class GrokHarnessAdapter(HarnessAdapter):
             "config_path": str(managed_config_path),
             **shim_manifest,
             "notes": [
-                "Guard hooks installed in .grok/hooks/hol-guard-*.json",
-                "Guard permission rules installed in .grok/managed_config.toml",
+                "Guard catch-all PreToolUse hook installed in .grok/hooks/hol-guard-pretooluse.json",
+                "Guard observe hooks installed for prompts, session start, and subagent start",
+                "Guard permission rules and backup hooks installed in .grok/managed_config.toml",
                 *shim_notes,
             ],
         }

{plugin_scanner-2.2.105 → plugin_scanner-2.2.107}/src/codex_plugin_scanner/guard/adapters/grok_config.py

@@ -20,20 +20,44 @@ GUARD_MANAGED_END = "# END HOL GUARD MANAGED GROK"
 GUARD_MANAGED_MARKER = "HOL GUARD MANAGED GROK"
 GUARD_HOOK_PRETOOL_FILE = "hol-guard-pretooluse.json"
 GUARD_HOOK_PROMPT_FILE = "hol-guard-prompt.json"
-PRETOOL_MATCHERS = (
-    "Bash",
-    "Read",
-    "Edit",
-    "Grep",
-    "MCPTool",
-    "WebFetch",
-    "run_terminal_command",
-    "read_file",
-    "grep",
-    "web_fetch",
-    "web_search",
-    "write",
-    "search_replace",
+# Kept empty: a per-tool matcher list double-fired after Grok aliased Bash→run_terminal_command.
+PRETOOL_MATCHERS: tuple[str, ...] = ()
+MANAGED_DENY_RULES = (
+    "Bash(hol-guard apps disconnect grok*)",
+    "Bash(hol-guard apps uninstall*)",
+    "Bash(rm -rf **/.grok/hooks/hol-guard*)",
+    "Edit(**/.grok/hooks/hol-guard*)",
+    "Edit(**/.grok/managed_config.toml)",
+    "Read(**/.grok/auth/**)",
+    "Read(**/.grok/auth.json)",
+    "Read(**/.env)",
+    "Read(**/.npmrc)",
+    "Read(**/.ssh/**)",
+    "Read(**/.hol-guard/secrets/**)",
+    "Read(**/.hol-guard/totp-secrets/**)",
+    "Read(**/.hol-guard/daemon-auth-token)",
+)
+OBSERVE_HOOK_EVENTS = ("UserPromptSubmit", "SubagentStart", "SessionStart")
+GROK_SURFACE_RELATIVES = (
+    "skills",
+    "plugins",
+    "plugins/marketplaces",
+    "plugins/known_marketplaces.json",
+    "sessions",
+    "agents",
+    "personas",
+    "workflows",
+    "sandbox.toml",
+    "trusted_folders.toml",
+)
+GROK_PROJECT_SURFACE_RELATIVES = (
+    "skills",
+    "plugins",
+    "hooks",
+    "agents",
+    "personas",
+    "workflows",
+    "sandbox.toml",
 )
 SYSTEM_MANAGED_CONFIG = Path("/etc/grok/managed_config.toml")
 SYSTEM_REQUIREMENTS = Path("/etc/grok/requirements.toml")
@@ -48,41 +72,76 @@ DEGRADED_MODE_MARKERS = (
 )
 
 
-def build_pretool_hook_json(hook_command: str) -> dict[str, object]:
-    entries: list[dict[str, object]] = []
-    for matcher in PRETOOL_MATCHERS:
-        entries.append(
+def _command_hook_entry(hook_command: str, *, timeout: int) -> dict[str, object]:
+    return {
+        "hooks": [
             {
-                "matcher": matcher,
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": hook_command,
-                        "timeout": 30,
-                    }
-                ],
+                "type": "command",
+                "command": hook_command,
+                "timeout": timeout,
             }
-        )
-    return {"hooks": {"PreToolUse": entries}}
+        ]
+    }
+
+
+def build_pretool_hook_json(hook_command: str) -> dict[str, object]:
+    """Install one catch-all PreToolUse handler.
+
+    Grok matchers are regexes against the native tool name and also expand
+    aliases, so listing both ``Bash`` and ``run_terminal_command`` ran Guard
+    twice. An omitted matcher covers current and future tools, including
+    ``spawn_subagent``, ``list_dir``, and ``server__tool`` MCP names.
+    """
 
+    return {"hooks": {"PreToolUse": [_command_hook_entry(hook_command, timeout=30)]}}
 
-def build_managed_config_block() -> str:
-    home = "~"
+
+def build_observe_hook_json(hook_command: str) -> dict[str, object]:
+    """Install observe-only lifecycle hooks.
+
+    Grok ignores deny/stdout on these events. Guard still records prompt and
+    subagent inventory; enforcement stays on PreToolUse.
+    """
+
+    return {
+        "hooks": {event_name: [_command_hook_entry(hook_command, timeout=15)] for event_name in OBSERVE_HOOK_EVENTS}
+    }
+
+
+def _toml_inline_command_hook(hook_command: str, *, timeout: int) -> str:
+    return '{ type = "command", command = ' + json.dumps(hook_command) + f", timeout = {timeout} }}"
+
+
+def build_managed_config_block(hook_command: str = "") -> str:
+    deny_lines = ",\n".join(f'  "{rule}"' for rule in MANAGED_DENY_RULES)
     lines = [
         GUARD_MANAGED_BEGIN,
         "# Permission rules below are managed by HOL Guard. Do not edit manually.",
         "[permission]",
         "deny = [",
-        '  "Bash(hol-guard apps disconnect grok*)",',
-        f'  "Bash(rm -rf {home}/.grok/hooks/hol-guard*)",',
-        f'  "Read({home}/.grok/auth/**)",',
-        f'  "Read({home}/.env)",',
-        '  "Read(**/.env)",',
-        '  "Read(**/.npmrc)",',
-        f'  "Read({home}/.ssh/**)",',
+        deny_lines,
         "]",
-        GUARD_MANAGED_END,
     ]
+    if hook_command.strip():
+        command_hook = _toml_inline_command_hook(hook_command, timeout=30)
+        observe_hook = _toml_inline_command_hook(hook_command, timeout=15)
+        lines.extend(
+            [
+                "",
+                "[[hooks.PreToolUse]]",
+                f"hooks = [{command_hook}]",
+                "",
+                "[[hooks.UserPromptSubmit]]",
+                f"hooks = [{observe_hook}]",
+                "",
+                "[[hooks.SubagentStart]]",
+                f"hooks = [{observe_hook}]",
+                "",
+                "[[hooks.SessionStart]]",
+                f"hooks = [{observe_hook}]",
+            ]
+        )
+    lines.append(GUARD_MANAGED_END)
     return "\n".join(lines)
 
 

plugin_scanner-2.2.107/src/codex_plugin_scanner/guard/adapters/grok_hooks.py

@@ -0,0 +1,243 @@
+"""Grok Build CLI hook payload and response helpers for HOL Guard."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Mapping
+from typing import TextIO
+
+_GROK_TOOL_ALIASES: dict[str, str] = {
+    "run_terminal_command": "Bash",
+    "read_file": "Read",
+    "search_replace": "Edit",
+    "write": "Edit",
+    "write_file": "Edit",
+    "multi_edit": "Edit",
+    "multiedit": "Edit",
+    "grep": "Grep",
+    "glob": "Grep",
+    "list_dir": "Read",
+    "listdir": "Read",
+    "web_fetch": "WebFetch",
+    "web_search": "WebFetch",
+    "open_page": "WebFetch",
+    "open_page_with_find": "WebFetch",
+    "spawn_subagent": "Task",
+    "task": "Task",
+    "use_tool": "MCPTool",
+    "callmcptool": "MCPTool",
+}
+
+_GROK_EVENT_NAMES: dict[str, str] = {
+    "pretooluse": "PreToolUse",
+    "userpromptsubmit": "UserPromptSubmit",
+    "posttooluse": "PostToolUse",
+    "posttoolusefailure": "PostToolUse",
+    "sessionstart": "SessionStart",
+    "sessionend": "SessionEnd",
+    "stop": "Stop",
+    "subagentstart": "SubagentStart",
+    "subagentstop": "SubagentStop",
+    "subagentend": "SubagentStop",
+    "permissiondenied": "PermissionDenied",
+}
+
+# Grok treats these events as observe-only. A deny JSON is ignored, so Guard
+# must not claim they are an enforcement boundary.
+_OBSERVE_ONLY_EVENTS = frozenset(
+    {
+        "UserPromptSubmit",
+        "SessionStart",
+        "SessionEnd",
+        "SubagentStart",
+        "SubagentStop",
+        "PostToolUse",
+        "PermissionDenied",
+    }
+)
+
+
+def _raw_hook_event_name(payload: Mapping[str, object]) -> str:
+    for key in ("hook_event_name", "hookEventName"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip().lower()
+    return ""
+
+
+def _canonical_grok_event_name(raw_event: str) -> str:
+    normalized = raw_event.replace("_", "").replace("-", "").lower()
+    return _GROK_EVENT_NAMES.get(normalized, raw_event or "PreToolUse")
+
+
+def _is_observe_only_event(event_name: str | None) -> bool:
+    if not isinstance(event_name, str) or not event_name.strip():
+        return False
+    return _canonical_grok_event_name(event_name.strip()) in _OBSERVE_ONLY_EVENTS
+
+
+def _canonical_grok_tool_name(raw_tool: object | None) -> str | None:
+    if not isinstance(raw_tool, str) or not raw_tool.strip():
+        return None
+    stripped = raw_tool.strip()
+    return _GROK_TOOL_ALIASES.get(stripped.lower(), stripped)
+
+
+def _mapping_value(value: object) -> Mapping[str, object] | None:
+    return value if isinstance(value, Mapping) else None
+
+
+def _native_mcp_envelope(tool_input: Mapping[str, object]) -> bool:
+    server = tool_input.get("server")
+    tool = tool_input.get("tool")
+    return isinstance(server, str) and bool(server.strip()) and isinstance(tool, str) and bool(tool.strip())
+
+
+def _unwrap_dispatcher_tool(
+    tool_name: str | None,
+    tool_input: Mapping[str, object] | None,
+) -> tuple[str | None, Mapping[str, object] | None]:
+    if tool_name != "MCPTool" or tool_input is None:
+        return tool_name, tool_input
+    # Grok's native MCP payload keeps the method name in `tool` next to `server`.
+    # That is not a dispatcher wrapper and must stay MCPTool.
+    if _native_mcp_envelope(tool_input):
+        return tool_name, tool_input
+    for key in ("tool_name", "toolName", "name", "tool"):
+        inner = tool_input.get(key)
+        if isinstance(inner, str) and inner.strip() and inner.strip() != "MCPTool":
+            inner_input = _mapping_value(tool_input.get("arguments") or tool_input.get("toolInput"))
+            return inner.strip(), inner_input or tool_input
+    return tool_name, tool_input
+
+
+def _apply_qualified_mcp_tool(normalized: dict[str, object], tool_name: str) -> str:
+    if "__" not in tool_name or tool_name.lower() in _GROK_TOOL_ALIASES:
+        return tool_name
+    server, tool = tool_name.split("__", 1)
+    if not server or not tool:
+        return tool_name
+    normalized["mcp_server"] = server
+    normalized["mcp_tool"] = tool
+    normalized["original_tool_name"] = tool_name
+    return "MCPTool"
+
+
+def prepare_grok_hook_payload(payload: Mapping[str, object]) -> dict[str, object]:
+    """Map Grok hook stdin JSON into Guard hook normalization shape."""
+
+    normalized = dict(payload)
+    raw_event = _raw_hook_event_name(normalized)
+    if raw_event:
+        normalized["hook_event_name"] = _canonical_grok_event_name(raw_event)
+    tool_name = normalized.get("tool_name")
+    if tool_name is None:
+        tool_name = normalized.get("toolName")
+    tool_input = normalized.get("tool_input")
+    if tool_input is None:
+        tool_input = normalized.get("toolInput")
+    mapped_input = _mapping_value(tool_input)
+    canonical_tool = _canonical_grok_tool_name(tool_name)
+    canonical_tool, mapped_input = _unwrap_dispatcher_tool(canonical_tool, mapped_input)
+    if isinstance(canonical_tool, str):
+        canonical_tool = _apply_qualified_mcp_tool(normalized, canonical_tool)
+        normalized["tool_name"] = canonical_tool
+    if mapped_input is not None:
+        if canonical_tool == "MCPTool" and _native_mcp_envelope(mapped_input):
+            normalized.setdefault("mcp_server", str(mapped_input["server"]).strip())
+            normalized.setdefault("mcp_tool", str(mapped_input["tool"]).strip())
+        normalized["tool_input"] = dict(mapped_input)
+        tool_input = mapped_input
+    elif tool_input is not None:
+        normalized["tool_input"] = tool_input
+    session_id = normalized.get("session_id")
+    if session_id is None and isinstance(normalized.get("sessionId"), str):
+        normalized["session_id"] = normalized["sessionId"]
+    workspace_root = normalized.get("workspace_root")
+    if workspace_root is None and isinstance(normalized.get("workspaceRoot"), str):
+        normalized["workspace_root"] = normalized["workspaceRoot"]
+    if workspace_root is None and isinstance(normalized.get("cwd"), str):
+        normalized["workspace_root"] = normalized["cwd"]
+    if isinstance(normalized.get("permissionMode"), str) and "permission_mode" not in normalized:
+        normalized["permission_mode"] = normalized["permissionMode"]
+    if isinstance(normalized.get("subagentType"), str) and "subagent_type" not in normalized:
+        normalized["subagent_type"] = normalized["subagentType"]
+    prompt = normalized.get("prompt")
+    if prompt is None and isinstance(normalized.get("userPrompt"), str):
+        normalized["prompt"] = normalized["userPrompt"]
+    if (
+        prompt is None
+        and canonical_tool == "Task"
+        and isinstance(tool_input, Mapping)
+        and isinstance(tool_input.get("prompt"), str)
+    ):
+        normalized["prompt"] = tool_input["prompt"]
+    if canonical_tool == "Task" and isinstance(tool_input, Mapping):
+        subagent_type = tool_input.get("subagent_type") or tool_input.get("subagentType")
+        if isinstance(subagent_type, str) and subagent_type.strip():
+            normalized["subagent_type"] = subagent_type.strip()
+    return normalized
+
+
+def grok_hook_response_from_guard(
+    *,
+    policy_action: str,
+    reason: str,
+    event_name: str | None = None,
+) -> dict[str, object]:
+    """Translate Guard policy action into Grok hook stdout JSON."""
+
+    if _is_observe_only_event(event_name):
+        return {"decision": "allow"}
+    if policy_action in {"review", "require-reapproval", "sandbox-required", "block"}:
+        cleaned_reason = _dedupe_grok_block_reason(reason.strip() if isinstance(reason, str) else "")
+        return {
+            "decision": "deny",
+            "reason": cleaned_reason or "Blocked by HOL Guard.",
+        }
+    return {"decision": "allow"}
+
+
+def _dedupe_grok_block_reason(reason: str) -> str:
+    if not reason:
+        return reason
+    marker = "Open HOL Guard to approve or keep this blocked:"
+    first = reason.find(marker)
+    if first == -1:
+        return reason
+    second = reason.find(marker, first + len(marker))
+    if second == -1:
+        return reason
+    return reason[:second].rstrip()
+
+
+def emit_grok_hook_response(
+    *,
+    policy_action: str,
+    reason: str,
+    event_name: str | None = None,
+    output_stream: TextIO | None = None,
+) -> None:
+    payload = grok_hook_response_from_guard(
+        policy_action=policy_action,
+        reason=reason,
+        event_name=event_name,
+    )
+    stream = output_stream if output_stream is not None else sys.stdout
+    stream.write(json.dumps(payload, separators=(",", ":")) + "\n")
+    stream.flush()
+
+
+def grok_hook_should_block(*, policy_action: str, event_name: str | None = None) -> bool:
+    if _is_observe_only_event(event_name):
+        return False
+    return policy_action in {"review", "require-reapproval", "sandbox-required", "block"}
+
+
+__all__ = [
+    "emit_grok_hook_response",
+    "grok_hook_response_from_guard",
+    "grok_hook_should_block",
+    "prepare_grok_hook_payload",
+]