javi-forge 1.40.0 → 1.41.0

package/assets/claude-hooks/javi-forge-skillguard-pre-tool-use.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 export const MANAGED_MARKER = "// javi-forge-managed: claude-pretooluse v1";
 export const INPUT_LIMIT_BYTES = 1_048_576;
 export const SUPPORTED_TOOLS = Object.freeze(["Bash", "PowerShell", "Read", "Write", "Edit"]);
+export function mapGrokToolName(toolName, platform = process.platform) { return toolName === "run_terminal_command" ? (platform === "win32" ? "PowerShell" : "Bash") : toolName === "read_file" ? "Read" : toolName === "search_replace" ? "Edit" : toolName; }
 export const POLICY_REGISTRY = Object.freeze({ schemaVersion: 1, policyVersion: 2, diagnosticsMaxBytes: 240 });
 export function resolvePlatformSupport(platform = process.platform) { return platform === "linux" || platform === "win32" ? { supported: true } : { supported: false, reason: "unsupported-platform" }; }
 const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
@@ -15,6 +16,7 @@ const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
 // never to an event field or a command token. This is intentionally an exact,
 // two-file allowlist rather than a whole-home or whole-.codex policy.
 const HOST_HOME = os.homedir();
+const GROK_HOME_ROOT = process.env.GROK_HOME ? path.resolve(process.env.GROK_HOME) : path.join(HOST_HOME, ".grok");
 // Per-agent adapter config (S0 core-extraction): every agent-specific input the guard needs
 // (the isManaged protected-path set, the project-dir source, the managed marker) is resolved by
 // the --agent selector instead of a baked-in literal. The pure evaluate*/utility engine stays
@@ -23,8 +25,10 @@ const HOST_HOME = os.homedir();
 const CLAUDE_MANAGED_SET = Object.freeze({ exact: Object.freeze([".claude/settings.json", ".claude/settings.local.json", ".claude/CLAUDE.md", "CLAUDE.md", ".javi-forge/ci.yaml"]), prefixes: Object.freeze([".claude/hooks/", ".claude/agents/", ".claude/skills/"]), caseFoldExact: Object.freeze(["claude.md", ".claude/claude.md"]) });
 const CODEX_MANAGED_SET = Object.freeze({ exact: Object.freeze([".codex/hooks.json", ".claude/settings.json", ".claude/settings.local.json", ".claude/CLAUDE.md", "CLAUDE.md", ".javi-forge/ci.yaml"]), prefixes: Object.freeze([".claude/hooks/", ".claude/agents/", ".claude/skills/"]), caseFoldExact: Object.freeze(["claude.md", ".claude/claude.md"]) });
 const OPENCODE_MANAGED_SET = Object.freeze({ exact: Object.freeze(["opencode.json", "opencode.jsonc", ".opencode/opencode.json", ".opencode/opencode.jsonc", ".opencode/AGENTS.md", "AGENTS.md", ".javi-forge/ci.yaml"]), prefixes: Object.freeze([".opencode/plugins/", ".opencode/agents/", ".opencode/skills/", ".agents/skills/", ".claude/hooks/", ".claude/agents/", ".claude/skills/"]), caseFoldExact: Object.freeze(["agents.md", ".opencode/agents.md", "claude.md", ".claude/claude.md"]) });
+const GROK_MANAGED_SET = Object.freeze({ exact: Object.freeze([".grok/config.toml", "AGENTS.md", ".claude/settings.json", ".claude/settings.local.json", ".claude/CLAUDE.md", "CLAUDE.md", ".javi-forge/ci.yaml"]), prefixes: Object.freeze([".grok/hooks/", ".claude/hooks/", ".claude/agents/", ".claude/skills/"]), caseFoldExact: Object.freeze(["agents.md", "claude.md", ".claude/claude.md"]) });
 const CODEX_GLOBAL_MANAGED_PATHS = Object.freeze([".codex/hooks.json", ".codex/config.toml"]);
-export const AGENT_CONFIGS = Object.freeze({ claude: Object.freeze({ id: "claude", managedSet: CLAUDE_MANAGED_SET, globalManagedPaths: Object.freeze([]), projectDir: Object.freeze({ envVar: "CLAUDE_PROJECT_DIR", fallback: "asset-root" }), marker: MANAGED_MARKER }), codex: Object.freeze({ id: "codex", managedSet: CODEX_MANAGED_SET, globalManagedPaths: CODEX_GLOBAL_MANAGED_PATHS, projectDir: Object.freeze({ envVar: null, fallback: "cwd" }), marker: "// javi-forge-managed: codex-pretooluse v1" }), opencode: Object.freeze({ id: "opencode", managedSet: OPENCODE_MANAGED_SET, globalManagedPaths: Object.freeze([]), projectDir: Object.freeze({ envVar: null, fallback: "cwd" }), marker: "// javi-forge-managed: opencode-skillguard v1" }) });
+const GROK_GLOBAL_MANAGED_PATHS = Object.freeze([path.join(GROK_HOME_ROOT, "hooks", "javi-forge-skillguard-pre-tool-use.json"), path.join(GROK_HOME_ROOT, "hooks", "javi-forge-skillguard-pre-tool-use.mjs")]);
+export const AGENT_CONFIGS = Object.freeze({ claude: Object.freeze({ id: "claude", managedSet: CLAUDE_MANAGED_SET, globalManagedPaths: Object.freeze([]), projectDir: Object.freeze({ envVar: "CLAUDE_PROJECT_DIR", fallback: "asset-root" }), marker: MANAGED_MARKER }), codex: Object.freeze({ id: "codex", managedSet: CODEX_MANAGED_SET, globalManagedPaths: CODEX_GLOBAL_MANAGED_PATHS, projectDir: Object.freeze({ envVar: null, fallback: "cwd" }), marker: "// javi-forge-managed: codex-pretooluse v1" }), opencode: Object.freeze({ id: "opencode", managedSet: OPENCODE_MANAGED_SET, globalManagedPaths: Object.freeze([]), projectDir: Object.freeze({ envVar: null, fallback: "cwd" }), marker: "// javi-forge-managed: opencode-skillguard v1" }), grok: Object.freeze({ id: "grok", managedSet: GROK_MANAGED_SET, globalManagedPaths: GROK_GLOBAL_MANAGED_PATHS, projectDir: Object.freeze({ envVar: null, fallback: "cwd" }), marker: "javi-forge-managed: grok-pretooluse v1" }) });
 // Fail-closed agent selector: a missing/unknown --agent means we cannot know what to protect, so refuse.
 function resolveAgentConfig(argv) { const arg = argv.find((value) => typeof value === "string" && value.startsWith("--agent=")); const id = arg === undefined ? undefined : arg.slice("--agent=".length); const config = id === undefined ? undefined : AGENT_CONFIGS[id]; if (!config) fail("invalid-config"); return config; }
 // Project root per agent: the env var when set (Claude = CLAUDE_PROJECT_DIR); otherwise the per-agent
@@ -87,7 +91,7 @@ export function lexicalizePolicyPath(input, options = {}) {
 	let expanded = input;
 	if (options.base) {
 		expanded = expanded.replace(/^\$\{CLAUDE_PROJECT_DIR\}|^\$CLAUDE_PROJECT_DIR/, options.projectRoot ?? PROJECT_ROOT);
-		expanded = expanded.replace(/^~(?=[\\/]|$)|^\$HOME(?=[\\/]|$)/, os.homedir());
+		expanded = expanded.replace(/^~(?=[\\/]|$)|^(?:\$HOME|\$\{HOME\})(?=[\\/]|$)/, os.homedir());
 		if (!POSIX_ABSOLUTE.test(expanded) && !WINDOWS_DRIVE.test(expanded) && !WINDOWS_UNC.test(expanded)) {
 			expanded = path.resolve(options.base, expanded);
 		}
@@ -142,7 +146,7 @@ export function isSensitivePolicyKey(key, platform = process.platform) {
 	return platform === "win32" ? basename.toLowerCase() === "serviceaccountkey.json" : basename === "serviceAccountKey.json";
 }
 function isManaged(key, managedSet = CLAUDE_MANAGED_SET, projectRoot = PROJECT_ROOT, globalManagedPaths = []) {
-	if (globalManagedPaths.some((relative) => key === canonicalizePolicyPath(path.join(HOST_HOME, relative)))) return true;
+	if (globalManagedPaths.some((targetPath) => key === canonicalizePolicyPath(path.isAbsolute(targetPath) ? targetPath : path.join(HOST_HOME, targetPath)))) return true;
 	const project = canonicalizePolicyPath(projectRoot);
 	if (!key.startsWith(`${project}/`) && key !== project) return false;
 	const relative = key.slice(project.length + 1);
@@ -952,30 +956,36 @@ export function parseApplyPatchPaths(command) {
 	return paths;
 }
 export function evaluateEvent(input, config = AGENT_CONFIGS.claude) {
-	if (!isObject(input) || input.hook_event_name !== "PreToolUse" || !isObject(input.tool_input)) fail("invalid-event");
-	const applyPatch = input.tool_name === "apply_patch";
-	if (!applyPatch && !SUPPORTED_TOOLS.includes(input.tool_name)) fail("invalid-event");
+	if (!isObject(input) || input.hook_event_name !== "PreToolUse") fail("invalid-event");
+	const rawToolName = typeof input.tool_name === "string" ? input.tool_name : input.toolName;
+	const toolName = config.id === "grok" && typeof rawToolName === "string" ? mapGrokToolName(rawToolName) : rawToolName;
+	const toolInput = isObject(input.tool_input) ? input.tool_input : input.toolInput;
+	if (typeof toolName !== "string" || !isObject(toolInput)) fail("invalid-event");
+	if (input.toolInputTruncated === true || input.tool_input_truncated === true) return { allowed: false, ruleId: "tool-input-truncated" };
+	const applyPatch = toolName === "apply_patch";
+	if (!applyPatch && !SUPPORTED_TOOLS.includes(toolName)) fail("invalid-event");
 	const cwd = typeof input.cwd === "string" && isAbsolutePolicyPath(input.cwd) ? input.cwd : PROJECT_ROOT;
 	const projectRoot = resolveProjectRoot(config, cwd);
 	if (applyPatch) {
-		if (typeof input.tool_input.command !== "string") fail("invalid-event");
+		if (typeof toolInput.command !== "string") fail("invalid-event");
 		// apply_patch is a WRITE tool (not "Read"), so the managed-config rule fires. Each header
 		// path is made absolute LEXICALLY (no realpath) vs the envelope cwd and handed to evaluateFile
 		// exactly like Write/Edit's raw file_path, so policyPathKeys owns the dual lexical+realpath
 		// canonicalization. Realpath-ing here first would collapse a symlinked managed dir onto its
 		// target and drop the protective lexical key -> managed-config write bypass.
-		for (const target of parseApplyPatchPaths(input.tool_input.command)) {
+		for (const target of parseApplyPatchPaths(toolInput.command)) {
 			const decision = evaluateFile("apply_patch", lexicalizePolicyPath(target, { base: cwd, projectRoot }), config, projectRoot);
 			if (!decision.allowed) return decision;
 		}
 		return { allowed: true };
 	}
-	if (input.tool_name === "Bash" || input.tool_name === "PowerShell") {
-		if (typeof input.tool_input.command !== "string") fail("invalid-event");
-		return input.tool_name === "Bash" ? evaluateBash(input.tool_input.command, cwd, config, projectRoot) : evaluatePowerShell(input.tool_input.command, cwd, config, projectRoot);
+	if (toolName === "Bash" || toolName === "PowerShell") {
+		if (typeof toolInput.command !== "string") fail("invalid-event");
+		return toolName === "Bash" ? evaluateBash(toolInput.command, cwd, config, projectRoot) : evaluatePowerShell(toolInput.command, cwd, config, projectRoot);
 	}
-	if (typeof input.tool_input.file_path !== "string" || !isAbsolutePolicyPath(input.tool_input.file_path)) fail("invalid-event");
-	return evaluateFile(input.tool_name, input.tool_input.file_path, config, projectRoot);
+	const filePath = typeof toolInput.file_path === "string" ? toolInput.file_path : typeof toolInput.filePath === "string" ? toolInput.filePath : config.id === "grok" && typeof toolInput.path === "string" ? lexicalizePolicyPath(toolInput.path, { base: cwd, projectRoot }) : undefined;
+	if (typeof filePath !== "string" || !isAbsolutePolicyPath(filePath)) fail("invalid-event");
+	return evaluateFile(toolName, filePath, config, projectRoot);
 }
 export function parseAndEvaluateInput(input) {
 	if (!Buffer.isBuffer(input) || input.length === 0) fail("invalid-json");
@@ -1072,7 +1082,9 @@ export async function main() {
 		}
 		if (fault === "evaluator-throw") throw new Error("internal-error");
 		const decision = evaluateEvent(parsed, config);
-		if (!decision.allowed) denyAndExit(denialDiagnostic(parsed.tool_name, decision));
+		const rawToolName = typeof parsed.tool_name === "string" ? parsed.tool_name : parsed.toolName;
+		const toolName = config.id === "grok" && typeof rawToolName === "string" ? mapGrokToolName(rawToolName) : rawToolName;
+		if (!decision.allowed) denyAndExit(denialDiagnostic(toolName, decision));
 		process.exitCode = 0;
 	} catch (error) {
 		denyAndExit(diagnostic(error));

package/assets/claude-hooks/manifest.json

@@ -4,7 +4,7 @@
 		"name": "javi-forge-skillguard-pre-tool-use.mjs",
 		"version": 1,
 		"policyVersion": 2,
-		"sha256": "6fe1ef55363e6e3f38253ca94b17ec50c942352c00d8431cd2ff2f6858c094b6",
+		"sha256": "044f6816d18a2894532fde52a145f10347f617cbb361fc10075d04f885327d22",
 		"historical": [
 			"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc",
 			"5dc2a5c31131f4ac7d8657c78b950de52776aad6eaefe78ea0d764a9963c4425",
@@ -15,7 +15,10 @@
 			"59fc4224975ad64cfc85bab50ec60d9bd4948070e9d41f42ab43e6d8231c19a1",
 			"6edfbb31ce0551b27e38ae1ffd1daf9cc4bea54f2c86687c5124132af5b8c0af",
 			"507a57a15f1b967103bb1eefe701a74813d5a9603fa7bcc15579a215b03621e3",
-			"f55ece1aea76251ec005f2b731fa44a58b6245fef8150b58486ae062167a2377"
+			"f55ece1aea76251ec005f2b731fa44a58b6245fef8150b58486ae062167a2377",
+			"6fe1ef55363e6e3f38253ca94b17ec50c942352c00d8431cd2ff2f6858c094b6",
+			"b79ee8dc3df525810b07215927590366ed2669255666fdc817e9637cf0e10cf2",
+			"a352b5b6c29fcdeecf2a014ab0e271cab9373119460134d65134f16a19222e47"
 		]
 	},
 	"settingsEntries": {

package/assets/grok-hooks/manifest.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "hook": {
+    "name": "javi-forge-skillguard-pre-tool-use.json",
+    "version": 1,
+    "matcher": "run_terminal_command|read_file|search_replace",
+    "historicalVersions": []
+  }
+}

package/dist/cli/dispatch/hooks.js

@@ -24,6 +24,7 @@ const AGENT_COMMAND_LOADERS = {
     claude: async () => (await import("../../commands/claude-hooks.js")).runClaudeHookCommand,
     codex: async () => (await import("../../commands/codex-hooks.js")).runCodexHookCommand,
     opencode: async () => (await import("../../commands/opencode-hooks.js")).runOpenCodeHookCommand,
+    grok: async () => (await import("../../commands/grok-hooks.js")).runGrokHookCommand,
 };
 export async function handleHooks(cli) {
     if (cli.flags.help === true) {
@@ -46,7 +47,7 @@ export async function handleHooks(cli) {
         // Validity is decided by the agent registry (isAgentId), the single source
         // of truth; the loader map is exhaustive over AgentId by type.
         if (!isAgentId(agent)) {
-            console.error(`Usage: javi-forge hooks ${sub} <claude|codex|opencode>`);
+            console.error(`Usage: javi-forge hooks ${sub} <claude|codex|opencode|grok>`);
             process.exit(1);
         }
         const run = await AGENT_COMMAND_LOADERS[agent]();

package/dist/cli/help.d.ts

@@ -19,7 +19,7 @@ export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand]
  * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
  * `hooks` is given an unknown subcommand). Whitespace is significant.
  */
-export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> <claude|codex|opencode> [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n    install codex     Install the managed Codex PreToolUse guard (~/.codex/)\n    doctor codex      Report Codex hook execution readiness and trust boundary\n    repair codex      Repair the managed Codex guard; --force overwrites edits\n    install opencode  Install the managed OpenCode global plugin (~/.config/opencode/plugins/)\n    doctor opencode   Report OpenCode plugin and policy file currency (informational)\n    repair opencode   Repair the OpenCode plugin pair; --force overwrites edits\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n    doctor codex exits 0 when runnable, 1 when blocked, and 2 when inconclusive;\n    it does not prove provider trust or runtime execution. Use repair codex\n    --force only to overwrite an edited managed asset.\n    doctor opencode is informational and inspects installed files only; it does\n    not prove OpenCode discovered, loaded, or executed the plugin.\n    Linux: install/repair claude need the acl package (getfacl) to prove the\n    parent chain \u2014 apt install acl / apk add acl / dnf install acl. Without it\n    they refuse fail-closed; an already-installed guard keeps firing, and\n    doctor claude reports the acl capability as its own row.\n    Claude Code spawns the guard with node from ITS path, so node must resolve\n    there, not only inside javi-forge.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n    $ javi-forge hooks install codex\n    $ javi-forge hooks doctor codex\n    $ javi-forge hooks repair codex --force\n    $ javi-forge hooks install opencode\n    $ javi-forge hooks doctor opencode\n    $ javi-forge hooks repair opencode --force\n";
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> <claude|codex|opencode|grok> [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n    install codex     Install the managed Codex PreToolUse guard (~/.codex/)\n    doctor codex      Report Codex hook execution readiness and trust boundary\n    repair codex      Repair the managed Codex guard; --force overwrites edits\n    install opencode  Install the managed OpenCode global plugin (~/.config/opencode/plugins/)\n    doctor opencode   Report OpenCode plugin and policy file currency (informational)\n    repair opencode   Repair the OpenCode plugin pair; --force overwrites edits\n    install grok      Install the Grok Build global PreToolUse hook (~/.grok/hooks/)\n    doctor grok       Report Grok hook registration and policy file currency (informational)\n    repair grok       Repair the Grok hook pair; --force overwrites edits\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n    doctor codex exits 0 when runnable, 1 when blocked, and 2 when inconclusive;\n    it does not prove provider trust or runtime execution. Use repair codex\n    --force only to overwrite an edited managed asset.\n    doctor opencode is informational and inspects installed files only; it does\n    not prove OpenCode discovered, loaded, or executed the plugin.\n    doctor grok is informational and inspects the global hook registration and\n    adjacent policy runtime only; it does not prove Grok loaded or executed them.\n    Linux: install/repair claude and grok need the acl package (getfacl) to\n    prove the parent chain \u2014 apt install acl / apk add acl / dnf install acl.\n    Without it\n    they refuse fail-closed; an already-installed guard keeps firing, and\n    doctor claude reports the acl capability as its own row.\n    Claude Code spawns the guard with node from ITS path, so node must resolve\n    there, not only inside javi-forge.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n    $ javi-forge hooks install codex\n    $ javi-forge hooks doctor codex\n    $ javi-forge hooks repair codex --force\n    $ javi-forge hooks install opencode\n    $ javi-forge hooks doctor opencode\n    $ javi-forge hooks repair opencode --force\n    $ javi-forge hooks install grok\n    $ javi-forge hooks doctor grok\n    $ javi-forge hooks repair grok --force\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -167,7 +167,7 @@ export const CI_HELP_TEXT = `
 export const HOOKS_HELP_TEXT = `
   Usage
     $ javi-forge hooks run <pre-commit|pre-push>
-    $ javi-forge hooks <install|doctor|repair> <claude|codex|opencode> [--force]
+    $ javi-forge hooks <install|doctor|repair> <claude|codex|opencode|grok> [--force]
 
     Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed
     cheap→expensive order, fail-fast. With no hooks: config the default is the
@@ -185,6 +185,9 @@ export const HOOKS_HELP_TEXT = `
     install opencode  Install the managed OpenCode global plugin (~/.config/opencode/plugins/)
     doctor opencode   Report OpenCode plugin and policy file currency (informational)
     repair opencode   Repair the OpenCode plugin pair; --force overwrites edits
+    install grok      Install the Grok Build global PreToolUse hook (~/.grok/hooks/)
+    doctor grok       Report Grok hook registration and policy file currency (informational)
+    repair grok       Repair the Grok hook pair; --force overwrites edits
 
   Notes
     A blocking section failure exits non-zero and blocks the commit/push.
@@ -198,8 +201,11 @@ export const HOOKS_HELP_TEXT = `
     --force only to overwrite an edited managed asset.
     doctor opencode is informational and inspects installed files only; it does
     not prove OpenCode discovered, loaded, or executed the plugin.
-    Linux: install/repair claude need the acl package (getfacl) to prove the
-    parent chain — apt install acl / apk add acl / dnf install acl. Without it
+    doctor grok is informational and inspects the global hook registration and
+    adjacent policy runtime only; it does not prove Grok loaded or executed them.
+    Linux: install/repair claude and grok need the acl package (getfacl) to
+    prove the parent chain — apt install acl / apk add acl / dnf install acl.
+    Without it
     they refuse fail-closed; an already-installed guard keeps firing, and
     doctor claude reports the acl capability as its own row.
     Claude Code spawns the guard with node from ITS path, so node must resolve
@@ -217,6 +223,9 @@ export const HOOKS_HELP_TEXT = `
     $ javi-forge hooks install opencode
     $ javi-forge hooks doctor opencode
     $ javi-forge hooks repair opencode --force
+    $ javi-forge hooks install grok
+    $ javi-forge hooks doctor grok
+    $ javi-forge hooks repair grok --force
 `;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so

package/dist/commands/grok-hooks.d.ts

@@ -0,0 +1,15 @@
+/** Console renderer for the Grok Build global SkillGuard hook manager. */
+import { doctorGrokSkillGuard, installGrokSkillGuard, repairGrokSkillGuard } from "../lib/grok-hook-manager.js";
+export type GrokHookSub = "install" | "doctor" | "repair";
+export interface GrokHookCmdDeps {
+    install?: typeof installGrokSkillGuard;
+    doctor?: typeof doctorGrokSkillGuard;
+    repair?: typeof repairGrokSkillGuard;
+    homeDir?: string;
+    log?: (msg: string) => void;
+    logError?: (msg: string) => void;
+}
+export declare function runGrokHookCommand(sub: GrokHookSub, _cwd: string, opts: {
+    force?: boolean;
+}, deps?: GrokHookCmdDeps): Promise<number>;
+//# sourceMappingURL=grok-hooks.d.ts.map

package/dist/commands/grok-hooks.js

@@ -0,0 +1,45 @@
+/** Console renderer for the Grok Build global SkillGuard hook manager. */
+import { doctorGrokSkillGuard, installGrokSkillGuard, repairGrokSkillGuard, } from "../lib/grok-hook-manager.js";
+function renderMutation(verb, result, log, logError) {
+    if (!result.ok) {
+        logError(`${verb} grok: refused`);
+        for (const error of result.errors)
+            logError(`  ${error}`);
+        for (const backup of result.backups)
+            logError(`  backup: ${backup}`);
+        return 1;
+    }
+    log(`${verb} grok: ok`);
+    if (result.changed.length === 0)
+        log("changed: nothing (already up to date)");
+    else
+        for (const changed of result.changed)
+            log(`changed: ${changed}`);
+    for (const backup of result.backups)
+        log(`backup: ${backup}`);
+    return 0;
+}
+function renderDoctor(report, log) {
+    log(`doctor grok: ${report.healthy ? "healthy" : "unhealthy"}`);
+    log(`  hook: ${report.hook.state}`);
+    log(`  policy: ${report.policy.state}`);
+    log("  runtime: not verified (installed files only)");
+    for (const remediation of report.remediation)
+        log(`  remediation: ${remediation}`);
+    // This is intentionally informational: local files cannot prove that Grok
+    // discovered, loaded, or invoked a plugin in a real session.
+    return 0;
+}
+export async function runGrokHookCommand(sub, _cwd, opts, deps = {}) {
+    const log = deps.log ?? ((message) => console.log(message));
+    const logError = deps.logError ?? ((message) => console.error(message));
+    const home = deps.homeDir;
+    if (sub === "install")
+        return renderMutation("install", await (deps.install ?? installGrokSkillGuard)(home), log, logError);
+    if (sub === "repair")
+        return renderMutation("repair", await (deps.repair ?? repairGrokSkillGuard)(home, {
+            force: opts.force === true,
+        }), log, logError);
+    return renderDoctor(await (deps.doctor ?? doctorGrokSkillGuard)(home), log);
+}
+//# sourceMappingURL=grok-hooks.js.map

package/dist/lib/agent-adapter.d.ts

@@ -14,7 +14,7 @@
  * map is typed `Record<AgentId, …>`, so omitting a loader is a compile error.
  */
 import { validateSettingsShape } from "./claude-hook-settings.js";
-export type AgentId = "claude" | "codex" | "opencode";
+export type AgentId = "claude" | "codex" | "opencode" | "grok";
 export type TrustState = "trusted" | "untrusted" | "unknown";
 export interface TrustDescriptor {
     /** Detect whether the installed hook is TRUSTED from the host config text. */
@@ -47,6 +47,7 @@ export interface AgentAdapter {
 export declare const claudeAdapter: AgentAdapter;
 export declare const codexAdapter: AgentAdapter;
 export declare const opencodeAdapter: AgentAdapter;
+export declare const grokAdapter: AgentAdapter;
 export declare const AGENT_ADAPTERS: Record<AgentId, AgentAdapter>;
 /**
  * Whether a raw CLI token names a known agent adapter. Backed by the

package/dist/lib/agent-adapter.js

@@ -52,6 +52,21 @@ const OPENCODE_MANAGED_SET = [
     ".claude/agents/",
     ".claude/skills/",
 ];
+const GROK_MANAGED_SET = [
+    ".grok/hooks/javi-forge-skillguard-pre-tool-use.json",
+    ".grok/hooks/javi-forge-skillguard-pre-tool-use.mjs",
+    ".grok/config.toml",
+    "AGENTS.md",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".claude/CLAUDE.md",
+    "CLAUDE.md",
+    ".javi-forge/ci.yaml",
+    ".grok/hooks/",
+    ".claude/hooks/",
+    ".claude/agents/",
+    ".claude/skills/",
+];
 export const claudeAdapter = {
     id: "claude",
     configPaths(projectDir) {
@@ -103,10 +118,27 @@ export const opencodeAdapter = {
     emitDeny: "throw-error",
     trust: null,
 };
+export const grokAdapter = {
+    id: "grok",
+    configPaths(homeDir) {
+        const hooksDir = path.join(homeDir, ".grok", "hooks");
+        return {
+            hooksFile: path.join(hooksDir, "javi-forge-skillguard-pre-tool-use.json"),
+            settingsFile: path.join(hooksDir, "javi-forge-skillguard-pre-tool-use.mjs"),
+        };
+    },
+    managedSet: GROK_MANAGED_SET,
+    projectDir: { envVar: null },
+    settingsSchema: null,
+    marker: "javi-forge-managed: grok-pretooluse v1",
+    emitDeny: "exit2+stderr",
+    trust: null,
+};
 export const AGENT_ADAPTERS = {
     claude: claudeAdapter,
     codex: codexAdapter,
     opencode: opencodeAdapter,
+    grok: grokAdapter,
 };
 /**
  * Whether a raw CLI token names a known agent adapter. Backed by the

package/dist/lib/grok-hook-manager.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Grok Build SkillGuard hook ownership manager. Grok reads trusted global hook
+ * definitions from ~/.grok/hooks, so installation is a two-file transaction:
+ * the PreToolUse JSON registration and the adjacent policy runtime. Doctor
+ * deliberately reports installed bytes/registration only, not runtime loading.
+ */
+import type { AssetManifestEntry } from "./claude-hook-manager.js";
+import type { ClaudeHookComponentState } from "./claude-hook-settings.js";
+import { type PlatformSecureFs } from "./secure-fs-transaction.js";
+export declare const GROK_HOOK_NAME = "javi-forge-skillguard-pre-tool-use.json";
+export declare const GROK_POLICY_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+export declare const GROK_HOOK_MARKER = "javi-forge-managed: grok-pretooluse v1";
+export declare const GROK_POLICY_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+export declare const GROK_HOOK_VERSION = 1;
+export declare const GROK_TOOL_MATCHER = "run_terminal_command|read_file|search_replace";
+export declare const GROK_ASSETS_DIR: string;
+export declare const SHIPPED_GROK_POLICY: string;
+export interface GrokHookManifestEntry {
+    name: string;
+    version: number;
+    matcher: string;
+    historicalVersions: number[];
+}
+export interface GrokManifest {
+    hook: GrokHookManifestEntry;
+    policy: AssetManifestEntry;
+}
+export interface GrokConfigPaths {
+    grokDir: string;
+    hooksDir: string;
+    hookFile: string;
+    policyFile: string;
+}
+export declare function resolveGrokHomeRoot(baseDir: string, env?: NodeJS.ProcessEnv): string;
+export declare function grokConfigPaths(baseDir: string, env?: NodeJS.ProcessEnv): GrokConfigPaths;
+/** Generate the complete standalone Grok hook registration for an adjacent asset. */
+export declare function expectedGrokHookJson(policyFile: string): string;
+export interface GrokAssetClassification {
+    state: ClaudeHookComponentState;
+    sha256?: string;
+    version?: number;
+    detail?: string;
+}
+/** Classify an installed policy runtime with the packaged manifest identity. */
+export declare function classifyGrokAsset(target: string, marker: string, manifest: AssetManifestEntry): Promise<GrokAssetClassification>;
+/**
+ * Classify a generated hook registration semantically. JSON whitespace does not
+ * matter; the command is compared against the supplied baseDir's adjacent asset.
+ */
+export declare function classifyGrokHookJson(target: string, policyFile: string, manifest: GrokHookManifestEntry): Promise<GrokAssetClassification>;
+export interface GrokHookDoctorReport {
+    healthy: boolean;
+    hook: GrokAssetClassification;
+    policy: GrokAssetClassification;
+    remediation: string[];
+    /** Installed files and registration only; no Grok execution is observed. */
+    runtimeEvidence: "not-implemented";
+}
+export interface GrokDoctorOptions {
+    manifest?: GrokManifest;
+    policySource?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function doctorGrokSkillGuard(baseDir?: string, options?: GrokDoctorOptions): Promise<GrokHookDoctorReport>;
+interface GrokMutationSuccess {
+    ok: boolean;
+    changed: string[];
+    backups: string[];
+    errors: string[];
+    warnings: string[];
+    report: GrokHookDoctorReport;
+}
+export type GrokHookMutationResult = GrokMutationSuccess;
+export interface GrokHookRunDeps extends GrokDoctorOptions {
+    secureFs?: PlatformSecureFs | null;
+    clock?: () => Date;
+    nonce?: () => string;
+    doctor?: typeof doctorGrokSkillGuard;
+}
+export declare function _runGrok(baseDir: string, mode: "install" | "repair", options: {
+    force?: boolean;
+}, deps?: GrokHookRunDeps): Promise<GrokHookMutationResult>;
+export declare function installGrokSkillGuard(baseDir?: string, deps?: GrokHookRunDeps): Promise<GrokHookMutationResult>;
+export declare function repairGrokSkillGuard(baseDir?: string, options?: {
+    force?: boolean;
+}, deps?: GrokHookRunDeps): Promise<GrokHookMutationResult>;
+export {};
+//# sourceMappingURL=grok-hook-manager.d.ts.map

package/dist/lib/grok-hook-manager.js

@@ -0,0 +1,327 @@
+/**
+ * Grok Build SkillGuard hook ownership manager. Grok reads trusted global hook
+ * definitions from ~/.grok/hooks, so installation is a two-file transaction:
+ * the PreToolUse JSON registration and the adjacent policy runtime. Doctor
+ * deliberately reports installed bytes/registration only, not runtime loading.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { CLAUDE_HOOK_ASSETS_DIR, FORGE_ROOT } from "../constants.js";
+import { safeReadFile } from "./safe-read.js";
+import { selectSecureFs } from "./secure-fs-posix.js";
+import { runTransaction, } from "./secure-fs-transaction.js";
+const MAX_BYTES = 1024 * 1024;
+const READ_OPTS = {
+    maxBytes: MAX_BYTES,
+    hardRejectOverBytes: MAX_BYTES,
+    maxLineLength: Number.POSITIVE_INFINITY,
+};
+export const GROK_HOOK_NAME = "javi-forge-skillguard-pre-tool-use.json";
+export const GROK_POLICY_NAME = "javi-forge-skillguard-pre-tool-use.mjs";
+export const GROK_HOOK_MARKER = "javi-forge-managed: grok-pretooluse v1";
+export const GROK_POLICY_MARKER = "// javi-forge-managed: claude-pretooluse v1";
+export const GROK_HOOK_VERSION = 1;
+export const GROK_TOOL_MATCHER = "run_terminal_command|read_file|search_replace";
+export const GROK_ASSETS_DIR = path.join(FORGE_ROOT, "assets", "grok-hooks");
+export const SHIPPED_GROK_POLICY = path.join(CLAUDE_HOOK_ASSETS_DIR, GROK_POLICY_NAME);
+export function resolveGrokHomeRoot(baseDir, env = process.env) {
+    const override = env.GROK_HOME;
+    return override && override.length > 0
+        ? path.resolve(override)
+        : path.join(baseDir, ".grok");
+}
+export function grokConfigPaths(baseDir, env = process.env) {
+    const grokDir = resolveGrokHomeRoot(baseDir, env);
+    const hooksDir = path.join(grokDir, "hooks");
+    return {
+        grokDir,
+        hooksDir,
+        hookFile: path.join(hooksDir, GROK_HOOK_NAME),
+        policyFile: path.join(hooksDir, GROK_POLICY_NAME),
+    };
+}
+/** Generate the complete standalone Grok hook registration for an adjacent asset. */
+export function expectedGrokHookJson(policyFile) {
+    const definition = {
+        "javi-forge-managed": GROK_HOOK_MARKER,
+        version: GROK_HOOK_VERSION,
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: GROK_TOOL_MATCHER,
+                    hooks: [
+                        {
+                            type: "command",
+                            command: `${JSON.stringify(process.execPath)} ${JSON.stringify(policyFile)} --agent=grok`,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    return `${JSON.stringify(definition, null, 2)}\n`;
+}
+async function fileKind(target) {
+    try {
+        const stat = await lstat(target);
+        if (stat.isSymbolicLink())
+            return { kind: "symlink" };
+        return stat.isFile() ? { kind: "file" } : { kind: "non-regular" };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { kind: "absent" };
+        return { kind: "error", detail: code ?? String(error) };
+    }
+}
+function sha256(content) {
+    return createHash("sha256")
+        .update(Buffer.from(content, "utf8"))
+        .digest("hex");
+}
+/** Classify an installed policy runtime with the packaged manifest identity. */
+export async function classifyGrokAsset(target, marker, manifest) {
+    const stat = await fileKind(target);
+    if (stat.kind === "absent")
+        return { state: "absent" };
+    if (stat.kind === "symlink")
+        return { state: "symlink" };
+    if (stat.kind !== "file")
+        return { state: "non-regular", detail: stat.detail };
+    const read = await safeReadFile(target, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { state: "absent" };
+        if (read.reason === "binary" || read.reason === "too-large")
+            return { state: "foreign", detail: read.reason };
+        return { state: "non-regular", detail: read.reason };
+    }
+    if (!read.content.startsWith(`${marker}\n`))
+        return { state: "foreign" };
+    const observed = sha256(read.content);
+    if (observed === manifest.sha256)
+        return {
+            state: "managed-current",
+            sha256: observed,
+            version: manifest.version,
+        };
+    if (manifest.historical.includes(observed))
+        return {
+            state: "released-outdated",
+            sha256: observed,
+            version: manifest.version,
+        };
+    return { state: "edited-managed", sha256: observed };
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Classify a generated hook registration semantically. JSON whitespace does not
+ * matter; the command is compared against the supplied baseDir's adjacent asset.
+ */
+export async function classifyGrokHookJson(target, policyFile, manifest) {
+    const stat = await fileKind(target);
+    if (stat.kind === "absent")
+        return { state: "absent" };
+    if (stat.kind === "symlink")
+        return { state: "symlink" };
+    if (stat.kind !== "file")
+        return { state: "non-regular", detail: stat.detail };
+    const read = await safeReadFile(target, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { state: "absent" };
+        if (read.reason === "binary" || read.reason === "too-large")
+            return { state: "foreign", detail: read.reason };
+        return { state: "non-regular", detail: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.content);
+    }
+    catch {
+        return { state: "malformed" };
+    }
+    if (!isObject(parsed))
+        return { state: "malformed" };
+    if (parsed["javi-forge-managed"] !== GROK_HOOK_MARKER)
+        return { state: "foreign" };
+    if (typeof parsed.version !== "number")
+        return { state: "edited-managed" };
+    if (manifest.historicalVersions.includes(parsed.version))
+        return { state: "released-outdated", version: parsed.version };
+    const expected = JSON.parse(expectedGrokHookJson(policyFile));
+    if (parsed.version === manifest.version &&
+        JSON.stringify(parsed) === JSON.stringify(expected))
+        return { state: "managed-current", version: parsed.version };
+    return { state: "edited-managed", version: parsed.version };
+}
+async function readManifest() {
+    const [hookRead, policyRead] = await Promise.all([
+        safeReadFile(path.join(GROK_ASSETS_DIR, "manifest.json"), READ_OPTS),
+        safeReadFile(path.join(CLAUDE_HOOK_ASSETS_DIR, "manifest.json"), READ_OPTS),
+    ]);
+    if (!hookRead.ok)
+        throw new Error(`unreadable grok hook manifest: ${hookRead.reason}`);
+    if (!policyRead.ok)
+        throw new Error(`unreadable claude-hooks manifest: ${policyRead.reason}`);
+    const hookManifest = JSON.parse(hookRead.content);
+    const policyManifest = JSON.parse(policyRead.content);
+    return { hook: hookManifest.hook, policy: policyManifest.asset };
+}
+export async function doctorGrokSkillGuard(baseDir = os.homedir(), options = {}) {
+    const manifest = options.manifest ?? (await readManifest());
+    const paths = grokConfigPaths(baseDir, options.env);
+    const [hook, policy] = await Promise.all([
+        classifyGrokHookJson(paths.hookFile, paths.policyFile, manifest.hook),
+        classifyGrokAsset(paths.policyFile, GROK_POLICY_MARKER, manifest.policy),
+    ]);
+    const remediation = [];
+    for (const [name, asset] of [
+        ["hook registration", hook],
+        ["policy runtime", policy],
+    ]) {
+        if (asset.state === "absent" || asset.state === "released-outdated") {
+            remediation.push(`install the Grok ${name} with: javi-forge hooks install grok`);
+        }
+        else if (asset.state === "edited-managed") {
+            remediation.push(`repair the edited Grok ${name} with: javi-forge hooks repair grok --force`);
+        }
+        else if (asset.state !== "managed-current") {
+            remediation.push(`manually review the Grok ${name} (${asset.state}); it will not be overwritten`);
+        }
+    }
+    return {
+        healthy: hook.state === "managed-current" && policy.state === "managed-current",
+        hook,
+        policy,
+        remediation: [...new Set(remediation)],
+        runtimeEvidence: "not-implemented",
+    };
+}
+function writePlan(state, force, name) {
+    if (state === "absent" || state === "released-outdated")
+        return { write: true };
+    if (state === "managed-current")
+        return { write: false };
+    if (state === "edited-managed" && force)
+        return { write: true };
+    if (state === "edited-managed")
+        return {
+            write: false,
+            refusal: `refuse edited ${name}; rerun repair with --force`,
+        };
+    return {
+        write: false,
+        refusal: `refuse ${name} in state ${state} — manual review`,
+    };
+}
+export async function _runGrok(baseDir, mode, options, deps = {}) {
+    const manifest = deps.manifest ?? (await readManifest());
+    const paths = grokConfigPaths(baseDir, deps.env);
+    const doctorFn = deps.doctor ?? doctorGrokSkillGuard;
+    const doctor = () => doctorFn(baseDir, {
+        env: deps.env,
+        manifest,
+        policySource: deps.policySource,
+    });
+    const force = mode === "repair" && options.force === true;
+    const [hook, policy] = await Promise.all([
+        classifyGrokHookJson(paths.hookFile, paths.policyFile, manifest.hook),
+        classifyGrokAsset(paths.policyFile, GROK_POLICY_MARKER, manifest.policy),
+    ]);
+    const hookPlan = writePlan(hook.state, force, "Grok hook registration");
+    const policyPlan = writePlan(policy.state, force, "Grok policy runtime");
+    if (hookPlan.refusal || policyPlan.refusal) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: [hookPlan.refusal ?? policyPlan.refusal ?? "refused"],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    if (!hookPlan.write && !policyPlan.write) {
+        return {
+            ok: true,
+            changed: [],
+            backups: [],
+            errors: [],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    const secureFs = deps.secureFs !== undefined
+        ? deps.secureFs
+        : selectSecureFs(process.platform);
+    if (!secureFs) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: ["windows-secure-object-unavailable"],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    const policySource = deps.policySource ?? SHIPPED_GROK_POLICY;
+    const policyBytes = policyPlan.write ? await readFile(policySource) : null;
+    if (policyBytes &&
+        createHash("sha256").update(policyBytes).digest("hex") !==
+            manifest.policy.sha256) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: ["refuse packaged Grok policy asset with manifest hash mismatch"],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    const hookBytes = hookPlan.write
+        ? Buffer.from(expectedGrokHookJson(paths.policyFile), "utf8")
+        : null;
+    const components = [
+        {
+            path: paths.hookFile,
+            desired: hookBytes,
+            capturePrior: hookPlan.write && hook.state !== "absent",
+            forceBackup: force && hook.state === "edited-managed",
+            wasAbsent: hook.state === "absent",
+        },
+        {
+            path: paths.policyFile,
+            desired: policyBytes,
+            capturePrior: policyPlan.write && policy.state !== "absent",
+            forceBackup: force && policy.state === "edited-managed",
+            wasAbsent: policy.state === "absent",
+        },
+    ];
+    const tx = await runTransaction({
+        secureFs,
+        clock: deps.clock ?? (() => new Date()),
+        nonce: deps.nonce ?? (() => randomBytes(4).toString("hex")),
+        projectDir: path.dirname(paths.grokDir),
+        layout: { containers: [paths.grokDir, paths.hooksDir], components },
+    });
+    return {
+        ok: tx.ok,
+        changed: tx.committed,
+        backups: tx.backups,
+        errors: tx.errors,
+        warnings: [],
+        report: await doctor(),
+    };
+}
+export function installGrokSkillGuard(baseDir, deps = {}) {
+    return _runGrok(baseDir ?? os.homedir(), "install", {}, deps);
+}
+export function repairGrokSkillGuard(baseDir, options, deps = {}) {
+    return _runGrok(baseDir ?? os.homedir(), "repair", options ?? {}, deps);
+}
+//# sourceMappingURL=grok-hook-manager.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.40.0",
+	"version": "1.41.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {