@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/emitters/grok.js

@@ -1,33 +1,55 @@
 /**
  * Grok Build native project hooks emitter.
  *
- * Writes a project-local `.grok/hooks.json` surface with managed commands
- * labeled `WP_HOOK_HOST=grok`. Claude freeload remains the fallback delivery
- * path; this is the first-class native project surface for doctor/setup.
+ * Grok reads project hook configs from `.grok/hooks/*.json` — a near-clone of
+ * the Claude Code hook contract (stdin event JSON incl. hookEventName/cwd,
+ * regex matchers, exit code 2 = deny, JSON stdout for decisions). We write one
+ * managed file, `.grok/hooks/webpresso.json`, with commands labeled
+ * `WP_HOOK_HOST=grok`. Hooks are trust-gated: the user must run `/hooks-trust`
+ * once in Grok before they fire (fail-open on timeout).
+ *
+ * Managed events are the intersection of WP_HOOK_SPECS with Grok's documented
+ * event set — notably Grok has no PermissionRequest event (it has
+ * PermissionDenied instead), so that spec is skipped.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { WP_HOOK_SPECS } from "#cli/commands/init/scaffolders/agent-hooks/ir.js";
-export const GROK_HOOKS_RELATIVE_PATH = ".grok/hooks.json";
+import { updateScaffolderTextFile } from "#cli/commands/init/scaffolders/file-transaction.js";
+export const GROK_HOOKS_DIR_RELATIVE_PATH = ".grok/hooks";
+export const GROK_HOOKS_RELATIVE_PATH = `${GROK_HOOKS_DIR_RELATIVE_PATH}/webpresso.json`;
+/** Grok's documented lifecycle events. */
+const GROK_HOOK_EVENTS = new Set([
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionDenied",
+    "Stop",
+    "StopFailure",
+    "Notification",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+]);
 /**
- * Build managed Grok hook groups. PreToolUse uses a broad Bash|Write|Edit matcher;
- * PermissionRequest and SessionStart are included without matchers.
+ * Build the managed Grok hook document (Claude-contract wrapped shape:
+ * `{ "hooks": { Event: [ { matcher?, hooks: [...] } ] } }`).
  */
 export function buildGrokHookDocument(input) {
     const { resolveBin } = input;
     const hooks = {};
     for (const spec of WP_HOOK_SPECS) {
-        // Grok managed subset: PreToolUse, PermissionRequest, SessionStart, PostToolUse.
-        if (spec.event !== "PreToolUse" &&
-            spec.event !== "PermissionRequest" &&
-            spec.event !== "SessionStart" &&
-            spec.event !== "PostToolUse") {
+        if (!GROK_HOOK_EVENTS.has(spec.event))
             continue;
-        }
-        // resolveBin (GROK_BIN) already labels WP_HOOK_HOST=grok on each branch of the
-        // launcher chain. Only prefix when the resolver returns a bare command.
+        // resolveBin (GROK_BIN) already labels WP_HOOK_HOST=grok on each branch of
+        // the launcher chain — with shell quoting (`WP_HOOK_HOST='grok'`), so match
+        // the variable name, not one quoting variant. Only prefix a bare command;
+        // prefixing a compound `if …` launcher would produce invalid `env … if`.
         const resolved = resolveBin(spec.bin);
-        const command = resolved.includes("WP_HOOK_HOST=grok")
+        const command = /WP_HOOK_HOST=(['"]?)grok\1/u.test(resolved)
             ? resolved
             : `env WP_HOOK_HOST=grok ${resolved}`;
         const group = {
@@ -41,11 +63,7 @@ export function buildGrokHookDocument(input) {
         const existing = hooks[spec.event] ?? [];
         hooks[spec.event] = [...existing, group];
     }
-    return {
-        version: 1,
-        host: "grok",
-        hooks,
-    };
+    return { hooks };
 }
 export function writeGrokProjectHooks(input) {
     const path = join(input.repoRoot, GROK_HOOKS_RELATIVE_PATH);
@@ -53,7 +71,6 @@ export function writeGrokProjectHooks(input) {
     if (input.dryRun) {
         return { path, written: false };
     }
-    mkdirSync(join(input.repoRoot, ".grok"), { recursive: true });
-    writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
-    return { path, written: true };
+    const outcome = updateScaffolderTextFile(path, () => `${JSON.stringify(doc, null, 2)}\n`);
+    return { path, written: outcome === "written" };
 }

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/index.d.ts

@@ -88,6 +88,8 @@ export declare function trustCodexWebpressoHooksForRepo(input: ScaffoldAgentHook
 export interface ScaffoldAgentHooksInput {
     repoRoot: string;
     options: MergeOptions;
+    /** Hosts selected by setup. Omitted by direct callers to scaffold every hook host. */
+    selectedHosts?: readonly string[];
     /**
      * Merge options for the user/home-scope leg (`~/.claude/settings.json`).
      * Defaults to `options`. The setup consent gate passes a dry-run-forced copy

package/dist/esm/cli/commands/init/scaffolders/agent-hooks/index.js

@@ -36,9 +36,16 @@ import { ensureGroup, mergeAgentKitGroups } from "./merge.js";
 // - pretool guard: fail-closed (explicit deny JSON) so policy cannot silently
 //   bypass when the guard binary is missing/non-executable.
 const PRETOOL_GUARD_BIN = "wp-pretool-guard";
-const PRETOOL_GUARD_MISSING_DENY_REASON = "wp not found on PATH. Install with vp install -g @webpresso/agent-kit and re-run wp setup.";
-// Dual envelope (Grok decision + Claude hookSpecificOutput) and exit 2 so Grok cannot fail-open.
-const PRETOOL_GUARD_MISSING_DENY = `printf '%s\\n' '{"decision":"deny","reason":"${PRETOOL_GUARD_MISSING_DENY_REASON}","hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"${PRETOOL_GUARD_MISSING_DENY_REASON}"}}'; exit 2`;
+// GUARD_-coded and within the 80-char permissionDecisionReason budget so the
+// generated fallback honors the same guard-outcome contract as the runtime.
+const PRETOOL_GUARD_MISSING_DENY_REASON = "GUARD_PRETOOL_FAILURE: wp not found on PATH; run wp setup";
+// Claude reads STDERR (not stdout) as the blocking feedback on an exit-2
+// PreToolUse deny, so the coded reason is also echoed to stderr (`>&2`).
+const PRETOOL_GUARD_MISSING_DENY_STDERR = `printf '%s\\n' '${PRETOOL_GUARD_MISSING_DENY_REASON}' >&2`;
+// Codex golden schema forbids a top-level `decision`; emit hookSpecificOutput only.
+const PRETOOL_GUARD_MISSING_DENY_CODEX = `printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"${PRETOOL_GUARD_MISSING_DENY_REASON}"}}'; ${PRETOOL_GUARD_MISSING_DENY_STDERR}; exit 2`;
+// Claude/Grok dual envelope (Grok decision + Claude hookSpecificOutput) + exit 2 so Grok cannot fail-open.
+const PRETOOL_GUARD_MISSING_DENY_DUAL = `printf '%s\\n' '{"decision":"deny","reason":"${PRETOOL_GUARD_MISSING_DENY_REASON}","hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"${PRETOOL_GUARD_MISSING_DENY_REASON}"}}'; ${PRETOOL_GUARD_MISSING_DENY_STDERR}; exit 2`;
 const JSON_ONLY_HOOK_FALLBACK = `printf '%s\\n' '{}'`;
 function quoteShell(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
@@ -58,11 +65,12 @@ const HOOK_SPEC_BY_BIN = new Map(WP_HOOK_SPECS.map((spec) => [spec.bin, spec]));
 function isJsonOnlyHookBin(name) {
     return HOOK_SPEC_BY_BIN.get(name)?.jsonOnly === true;
 }
-function missingLauncherFallbackCommand(name) {
+function missingLauncherFallbackCommand(name, host) {
     if (isJsonOnlyHookBin(name))
         return JSON_ONLY_HOOK_FALLBACK;
-    if (name === PRETOOL_GUARD_BIN)
-        return PRETOOL_GUARD_MISSING_DENY;
+    if (name === PRETOOL_GUARD_BIN) {
+        return host === "codex" ? PRETOOL_GUARD_MISSING_DENY_CODEX : PRETOOL_GUARD_MISSING_DENY_DUAL;
+    }
     return "true";
 }
 function hookSubcommandForRequired(binName) {
@@ -114,7 +122,7 @@ function buildHookStatusGuard(command, fallback) {
 }
 function buildSourcePackageDirectHookCommand(input) {
     const hookName = hookSubcommandForRequired(input.name);
-    const fallback = missingLauncherFallbackCommand(input.name);
+    const fallback = missingLauncherFallbackCommand(input.name, input.host);
     const hostEnv = `env WP_HOOK_HOST=${quoteShell(input.host)}`;
     const hookEntrypointPath = quoteShell(join(input.packageRoot, "src", "cli", "hook-entrypoint.ts"));
     const branches = [];
@@ -146,7 +154,7 @@ function buildConsumerDirectWpHookCommand(name, host) {
     const wpPath = quoteShell(resolveWpHookLauncherPath());
     const nodePath = quoteShell(resolveNodeForHookLauncher());
     const hookName = hookSubcommandForRequired(name);
-    const fallback = missingLauncherFallbackCommand(name);
+    const fallback = missingLauncherFallbackCommand(name, host);
     return `if [ -x ${nodePath} ] && [ -f ${wpPath} ]; then env WP_HOOK_HOST=${quoteShell(host)} ${nodePath} ${wpPath} hook ${hookName}; hook_status=$?; if [ "$hook_status" -eq 2 ]; then exit 2; elif [ "$hook_status" -ne 0 ]; then ${fallback}; fi; else ${fallback}; fi # ${name}`;
 }
 function buildDirectWpHookCommand(repoRoot, name, host) {
@@ -573,7 +581,9 @@ export function disableManagedHooksFromManifest(input, manifest, vendors) {
     return result;
 }
 export function resolvePackageRootForHookLaunchers(options = {}) {
-    return resolveAgentKitPackageRootOrThrow("wp setup: could not locate @webpresso/agent-kit package root for hook launchers.", options);
+    // Default cwd so vitest/bunfs hosts that lose moduleUrl still resolve from
+    // the monorepo/package checkout the process is running in (CI flake fix).
+    return resolveAgentKitPackageRootOrThrow("wp setup: could not locate @webpresso/agent-kit package root for hook launchers.", { cwd: process.cwd(), ...options });
 }
 /**
  * The `wp hook <sub>` subcommand maps each catalogued `wp-*` hook bin to the
@@ -606,37 +616,57 @@ function pruneLegacyGeneratedHookFiles(repoRoot, directorySegments, fileNames) {
     }
     removeDirectoryIfEmpty(directoryPath);
 }
-function pruneLegacyManagedHookDirectories(repoRoot) {
+function pruneLegacyManagedHookDirectories(repoRoot, selectedHosts) {
     const managedHookFiles = WP_HOOK_BIN_NAMES.map((binName) => `${binName}.sh`);
-    pruneLegacyGeneratedHookFiles(repoRoot, [".codex", "managed-hooks"], [...managedHookFiles, ...LEGACY_MANAGED_ONLY_HOOK_FILES]);
-    pruneLegacyGeneratedHookFiles(repoRoot, [".claude", "hooks", "managed"], managedHookFiles);
+    if (selectedHosts.has("codex")) {
+        pruneLegacyGeneratedHookFiles(repoRoot, [".codex", "managed-hooks"], [...managedHookFiles, ...LEGACY_MANAGED_ONLY_HOOK_FILES]);
+    }
+    if (selectedHosts.has("claude")) {
+        pruneLegacyGeneratedHookFiles(repoRoot, [".claude", "hooks", "managed"], managedHookFiles);
+    }
 }
 export async function scaffoldAgentHooks(input) {
+    const selectedHosts = new Set(input.selectedHosts ?? ["claude", "codex", "grok"]);
     const manifest = buildManagedHooksManifest(input.repoRoot);
     const result = {
-        claude: patchJsonFile(join(input.repoRoot, ".claude", "settings.json"), (existing) => patchClaudeSettings(existing, input.repoRoot), input.options),
-        codex: patchJsonFile(join(input.repoRoot, ".codex", "hooks.json"), (existing) => patchCodexHooks(existing, input.repoRoot), input.options),
-        claudeUser: input.skipClaudeUserSettings
-            ? { targetPath: defaultClaudeUserSettingsPath(), action: "identical" }
+        claude: selectedHosts.has("claude")
+            ? patchJsonFile(join(input.repoRoot, ".claude", "settings.json"), (existing) => patchClaudeSettings(existing, input.repoRoot), input.options)
+            : {
+                targetPath: join(input.repoRoot, ".claude", "settings.json"),
+                action: "identical",
+            },
+        codex: selectedHosts.has("codex")
+            ? patchJsonFile(join(input.repoRoot, ".codex", "hooks.json"), (existing) => patchCodexHooks(existing, input.repoRoot), input.options)
+            : {
+                targetPath: join(input.repoRoot, ".codex", "hooks.json"),
+                action: "identical",
+            },
+        claudeUser: input.skipClaudeUserSettings || !selectedHosts.has("claude")
+            ? {
+                targetPath: defaultClaudeUserSettingsPath(),
+                action: "identical",
+            }
             : patchJsonFile(defaultClaudeUserSettingsPath(), (existing) => patchClaudeUserSettings(existing), input.claudeUserOptions ?? input.options),
         manifest,
     };
     // Native Grok project hooks (WP_HOOK_HOST=grok). Freeload via Claude remains fallback.
-    const { writeGrokProjectHooks } = await import("./emitters/grok.js");
-    writeGrokProjectHooks({
-        repoRoot: input.repoRoot,
-        resolveBin: GROK_BIN(input.repoRoot),
-        dryRun: input.options.dryRun === true,
-    });
+    if (selectedHosts.has("grok")) {
+        const { writeGrokProjectHooks } = await import("./emitters/grok.js");
+        writeGrokProjectHooks({
+            repoRoot: input.repoRoot,
+            resolveBin: GROK_BIN(input.repoRoot),
+            dryRun: input.options.dryRun === true,
+        });
+    }
     if (!input.options.dryRun) {
-        pruneLegacyManagedHookDirectories(input.repoRoot);
+        pruneLegacyManagedHookDirectories(input.repoRoot, selectedHosts);
     }
     // Root-gate: the trust leg runs ONLY when the caller passed an explicit
     // trust config carrying its own resolved consent. Omission (or `false`)
     // means no `$CODEX_HOME/config.toml` write and no app-server spawn — this
     // boundary never manufactures an `apply` consent on the caller's behalf.
     const trustSync = input.trustCodexHooks;
-    if (trustSync !== undefined && trustSync !== false) {
+    if (selectedHosts.has("codex") && trustSync !== undefined && trustSync !== false) {
         await trustCodexWebpressoHooksForRepo(input, trustSync.userScope);
     }
     return result;

package/dist/esm/cli/commands/init/scaffolders/codex-mcp/index.d.ts

@@ -19,6 +19,9 @@
  *      forwarded through Codex's stdio `env_vars` allow-list.
  */
 import { spawnSync } from "node:child_process";
+import { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME, type WebpressoInstallProbe } from "#cli/commands/init/mcp-spec.js";
+export { findWebpressoMcpEntry, WEBPRESSO_MCP_SERVER_NAME };
+export type { WebpressoInstallProbe };
 import type { MergeOptions } from "#cli/commands/init/merge";
 import { type PinnedCodexMcpDefinition } from "#hooks/host-config-contract.js";
 import { type GlobalCapableVpCommandInput } from "#cli/global-vp.js";
@@ -29,6 +32,8 @@ export interface CommandMcpServerDefinition {
     args: readonly string[];
     /** Codex TOML env allow-list forwarded by the host MCP client. */
     codexEnvVars?: readonly string[];
+    /** Codex TOML static env map rendered as an inline table. */
+    codexEnv?: Readonly<Record<string, string>>;
     /** Claude `.mcp.json` env expansion map. */
     claudeEnv?: Readonly<Record<string, string>>;
     /** Extra Codex TOML fields beyond command/args/env_vars/enabled. */
@@ -39,9 +44,11 @@ export declare const PLAYWRIGHT_MCP_VERSION = "0.0.78";
 export declare const PLAYWRIGHT_MCP_PACKAGE = "@playwright/mcp@0.0.78";
 export declare function commandMcpHeader(serverId: string): string;
 export declare function commandMcpCodexBlock(definition: CommandMcpServerDefinition): string;
+export declare function hasAmbiguousMcpServerDottedDefinition(raw: string, serverId: string): boolean;
+export declare function hasManagedMcpServerTableConflict(raw: string, serverId: string): boolean;
+export declare function upsertMcpServerBlock(raw: string, serverId: string, block: string): string;
 export declare function upsertCommandMcpServer(raw: string, definition: CommandMcpServerDefinition): string;
 export declare function commandMcpClaudeServer(definition: CommandMcpServerDefinition): ClaudeMcpServer;
-export declare const WEBPRESSO_MCP_SERVER_NAME = "webpresso";
 export declare const WEBPRESSO_MCP_HEADER = "[mcp_servers.webpresso]";
 export interface PinnedCodexMcpRuntime {
     options: MergeOptions;
@@ -136,36 +143,6 @@ export type EnsureClaudePlaywrightMcpResult = {
     path: string;
 };
 export declare function ensureClaudePlaywrightMcp(input: EnsureClaudePlaywrightMcpInput): EnsureClaudePlaywrightMcpResult;
-export interface WebpressoInstallProbe {
-    /** Test seam — override the candidate roots. Default: probe in fixed order. */
-    candidates?: readonly string[];
-    /** Test seam — resolve the stable global `wp` shim available on PATH. */
-    stableEntry?: () => string | null;
-    /** Test seam — return value for `pnpm root -g`. Default: shell out. */
-    pnpmGlobalRoot?: () => string | null;
-    /** Test seam — return value for `npm root -g`. Default: shell out. */
-    npmGlobalRoot?: () => string | null;
-}
-/**
- * Resolve the absolute path to webpresso's global `bin/wp` launcher on this machine. Probes
- * the locations consumers use to install webpresso, in order of stability:
- *
- *   1. the stable global `wp` shim available on PATH
- *   2. the currently executing `@webpresso/agent-kit` package
- *   3. Claude plugin install — `~/.claude/plugins/cache/.../agent-kit/`
- *      (path-stable; updated by Claude Code's plugin manager)
- *   4. bun global — `~/.bun/install/global/node_modules/@webpresso/agent-kit/`
- *   5. pnpm global — `$(pnpm root -g)/@webpresso/agent-kit/`
- *   6. npm global — `$(npm root -g)/@webpresso/agent-kit/`
- *
- * Returns `null` when none of the candidates contain `bin/wp`. The caller
- * surfaces a clear error rather than writing a broken codex config.
- */
-export declare function findWebpressoMcpEntry(probe?: WebpressoInstallProbe): string | null;
-export declare function agentKitMcpLaunchCommand(entryPath: string): {
-    command: string;
-    args: string[];
-};
 export declare function agentKitMcpBlock(entryPath: string): string;
 export declare function upsertWebpressoMcpServer(raw: string, entryPath: string): string;
 export interface EnsureCodexWebpressoMcpInput {
@@ -185,6 +162,10 @@ export type EnsureCodexWebpressoMcpResult = {
     kind: "codex-webpresso-mcp-unchanged";
     path: string;
     entryPath: string;
+} | {
+    kind: "codex-webpresso-mcp-ambiguous";
+    path: string;
+    entryPath: string;
 } | {
     kind: "codex-webpresso-mcp-skipped-dry-run";
     path: string;