@webpresso/agent-kit 0.21.5 → 0.23.0

package/dist/esm/cli/commands/blueprint/router.js

@@ -5,6 +5,7 @@ import { parseBlueprintForDb } from '#db/parser/blueprint-db-parser';
 import { blueprintToSpecKit } from '#export/spec-kit/index';
 import { getProjectRoot } from '#cli/utils';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
+import { getBlueprintDocumentPaths } from '#utils/document-paths.js';
 import { applyBlueprintLifecycleToFile, BlueprintCreationService, BlueprintService, complexitySchema, relativeBlueprintSlug, parseBlueprint, planStatusSchema, runBlueprintAudit, resolveBlueprintFile, serializeBlueprint, validateAllTasksDone, } from '#local';
 import { resolvePackageAssetPreferred } from '#utils/package-assets';
 import { describeBlueprintExecutionRuntime, buildBlueprintLaunchSpec, buildStoppedRuntimeEvidence, controlBlueprintExecution, initializeBlueprintExecutionProgressBridge, launchBlueprintExecution, persistBlueprintExecutionArtifacts, persistBlueprintExecutionMetadata, recordLaunchFailure, reconcileBlueprintRuntimeSnapshot, readBlueprintExecutionState, syncBlueprintExecutionProgress, writeBlueprintRuntimeSnapshot, } from './execution.js';
@@ -309,10 +310,12 @@ export async function moveBlueprint(slug, status, options = {}) {
     const projectRoot = resolveProjectRoot(options.projectRoot);
     const nextStatus = normalizeBlueprintStatus(status);
     const location = await resolveBlueprintLocation(slug, projectRoot);
+    const isFlatFile = path.basename(location.path) !== '_overview.md';
     const sourceDir = path.dirname(location.path);
-    const targetDir = path.join(resolveBlueprintRoot(projectRoot), nextStatus, relativeBlueprintSlug(location.slug));
-    const targetPath = path.join(targetDir, '_overview.md');
-    if (sourceDir === targetDir && location.blueprint.status === nextStatus) {
+    const targetPaths = getBlueprintDocumentPaths(resolveBlueprintRoot(projectRoot), nextStatus, relativeBlueprintSlug(location.slug));
+    const targetDir = targetPaths.directory;
+    const targetPath = isFlatFile ? targetPaths.flat : targetPaths.folder;
+    if (location.path === targetPath && location.blueprint.status === nextStatus) {
         return {
             fromPath: location.path,
             fromStatus: location.blueprint.status,
@@ -328,18 +331,18 @@ export async function moveBlueprint(slug, status, options = {}) {
         throw new Error('Blueprint move is recovery-only. Use wp blueprint start/task/finalize for normal lifecycle changes, or pass --force-recovery.');
     }
     assertBlueprintCanMoveToStatus(location.blueprint, nextStatus);
-    if (sourceDir !== targetDir) {
-        await mkdir(path.dirname(targetDir), { recursive: true });
-        await rename(sourceDir, targetDir);
+    if (location.path !== targetPath) {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await rename(isFlatFile ? location.path : sourceDir, isFlatFile ? targetPath : targetDir);
     }
     const updated = await writeBlueprintWithStatus(targetPath, location.blueprint, nextStatus);
     return {
         fromPath: location.path,
         fromStatus: location.blueprint.status,
-        message: sourceDir === targetDir
+        message: location.path === targetPath
             ? `Updated blueprint ${location.slug} to ${nextStatus}.`
             : `Moved blueprint ${location.slug} to ${nextStatus}.`,
-        moved: sourceDir !== targetDir,
+        moved: location.path !== targetPath,
         slug: location.slug,
         toPath: targetPath,
         toStatus: nextStatus,

package/dist/esm/cli/commands/hook.d.ts

@@ -0,0 +1,8 @@
+import type { CAC } from 'cac';
+declare const HOOK_NAMES: readonly ["pretool-guard", "post-tool", "stop-qa", "guard-switch", "sessionstart-routing"];
+export type HookName = (typeof HOOK_NAMES)[number];
+export declare function isHookName(value: string): value is HookName;
+export declare function runHookCommand(name: string): Promise<void>;
+export declare function registerHookCommand(cli: CAC): void;
+export {};
+//# sourceMappingURL=hook.d.ts.map

package/dist/esm/cli/commands/hook.js

@@ -0,0 +1,47 @@
+const HOOK_NAMES = [
+    'pretool-guard',
+    'post-tool',
+    'stop-qa',
+    'guard-switch',
+    'sessionstart-routing',
+];
+const HOOK_HANDLERS = {
+    'pretool-guard': async () => {
+        const { main } = await import('#hooks/pretool-guard/index');
+        await main();
+    },
+    'post-tool': async () => {
+        const { main } = await import('#hooks/post-tool/lint-after-edit');
+        await main();
+    },
+    'stop-qa': async () => {
+        const { main } = await import('#hooks/stop/qa-changed-files');
+        await main();
+    },
+    'guard-switch': async () => {
+        const { main } = await import('#hooks/guard-switch/index');
+        await main();
+    },
+    'sessionstart-routing': async () => {
+        const { main } = await import('#hooks/sessionstart/index');
+        await main();
+    },
+};
+export function isHookName(value) {
+    return value in HOOK_HANDLERS;
+}
+export async function runHookCommand(name) {
+    if (!isHookName(name)) {
+        throw new Error(`Unknown hook "${name}". Expected one of: ${HOOK_NAMES.join(', ')}`);
+    }
+    await HOOK_HANDLERS[name]();
+}
+export function registerHookCommand(cli) {
+    cli
+        .command('hook <name>', 'Run an internal plugin hook entrypoint')
+        .action(async (name) => {
+        await runHookCommand(name);
+        return 0;
+    });
+}
+//# sourceMappingURL=hook.js.map

package/dist/esm/cli/commands/init/index.js

@@ -30,6 +30,7 @@ import { BASE_KIT_QUALITY_TARGETS, collectRuntimeContractGuidance, scaffoldBaseK
 import { scaffoldMonorepoNav } from './scaffold-monorepo-nav.js';
 import { REQUIRED_CORE_CAPABILITIES, auditHostSkillVisibility, parseAgentHosts, serializeHostVisibility, summarizeHostVisibility, } from './host-visibility.js';
 import { scaffoldAgentHooks, trustCodexWebpressoHooksForRepo, trustCodexPresetHooksForUser, } from './scaffolders/agent-hooks/index.js';
+import { ensureAgentKitGlobal } from './scaffolders/agent-kit-global/index.js';
 import { scaffoldAuditHooks } from './scaffolders/audit-hooks/index.js';
 import { ensureClaudeCodeUserPlugin } from './scaffolders/claude-plugin/index.js';
 import { scaffoldClaudeRules } from './scaffolders/claude-rules/index.js';
@@ -495,6 +496,37 @@ export async function runInit(flags) {
                 console.log(`  codex webpresso mcp: ⚠ no install root found (checked ${webpressoMcpResult.checked.length} paths). Install webpresso globally (\`bun add -g webpresso\`) or via the Claude plugin to wire up codex MCP.`);
                 break;
         }
+        // Self-update the ONE globally-distributed agent-kit binary (PATH `wp`,
+        // plugin MCP, hooks all resolve to it), mirroring omx/omc/codex/claude.
+        // Non-fatal: a failed refresh never fails consumer setup, and it skips
+        // cleanly on a source/git clone, on `WP_SKIP_AUTO_INSTALL=1`, and in CI.
+        if (isCiEnvironment) {
+            console.log('  agent-kit global: - skipped (CI environment)');
+        }
+        else {
+            const agentKitGlobalResult = ensureAgentKitGlobal({ options });
+            switch (agentKitGlobalResult.kind) {
+                case 'agent-kit-global-updated':
+                    console.log('  agent-kit global: ✓ refreshed via vp install -g');
+                    break;
+                case 'agent-kit-global-skipped-dry-run':
+                    console.log('  agent-kit global: skipped (--dry-run)');
+                    break;
+                case 'agent-kit-global-skipped-opt-out':
+                    console.log('  agent-kit global: skipped (WP_SKIP_AUTO_INSTALL=1)');
+                    break;
+                case 'agent-kit-global-skipped-source-clone':
+                    console.log(`  agent-kit global: - skipped (running from source clone ${agentKitGlobalResult.repoRoot})`);
+                    break;
+                case 'agent-kit-global-skipped-no-vp':
+                    console.warn(`  agent-kit global: ⚠ ${agentKitGlobalResult.hint}`);
+                    break;
+                case 'agent-kit-global-failed':
+                    console.warn(`  agent-kit global: ⚠ \`${agentKitGlobalResult.command.join(' ')}\` exited with ${agentKitGlobalResult.exitCode}; ` +
+                        'the existing global binary is unchanged. Re-run `wp setup` once the registry is reachable.');
+                    break;
+            }
+        }
         const claudePluginResult = ensureClaudeCodeUserPlugin({
             options,
             packageRoot,
@@ -697,7 +729,9 @@ export async function runInit(flags) {
                 }
             }
         }
-        printRuntimeContractGuidance(options.dryRun ? consumer.packageJson : readPackageJsonSafe(consumer.repoRoot) ?? consumer.packageJson);
+        printRuntimeContractGuidance(options.dryRun
+            ? consumer.packageJson
+            : (readPackageJsonSafe(consumer.repoRoot) ?? consumer.packageJson));
         console.log('\nwp init: setup phases finished.');
         if (omxFailure === 'not-found')
             return EXIT_SETUP_FAIL;

package/dist/esm/cli/commands/init/scaffold-base-kit.js

@@ -119,7 +119,7 @@ function mergePackageJson(repoRoot, options, globalInstall = false) {
     const hasTestMutationScript = typeof scripts['test:mutation'] === 'string';
     const hasE2eScript = typeof scripts['e2e'] === 'string';
     const hasQaScript = typeof scripts['qa'] === 'string';
-    const verifyPathsScript = 'WP_SKIP_UPDATE_CHECK=1 wp audit absolute-path-policy --root .';
+    const verifyPathsScript = 'wp audit absolute-path-policy --root .';
     const verifySecretsScript = 'bun scripts/check-no-dev-vars.ts';
     const secretQuarantineAuditScript = 'bun scripts/audit-secret-provider-quarantine.ts';
     const lintScript = 'wp lint src e2e *.config.ts';

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

@@ -10,6 +10,8 @@ export const KNOWN_WEBPRESSO_CODEX_BINS = [
 const KNOWN_WEBPRESSO_CODEX_BIN_SET = new Set(KNOWN_WEBPRESSO_CODEX_BINS);
 const NODE_MODULES_BIN_PATTERN = /^(?:\.\/|\/.*\/)?node_modules\/\.bin\/([\w-]+)$/u;
 const GUARDED_NODE_MODULES_BIN_PATTERN = /^\[ -x (["']?)((?:\.\/|\/.*\/)?node_modules\/\.bin\/([\w-]+))\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
+const MANAGED_LAUNCHER_PATTERN = /^(?:["']?)((?:\.\/|\/.*\/)?\.codex\/managed-hooks\/((?:wp|ak)-[\w-]+)\.sh)(?:["']?)$/u;
+const GUARDED_MANAGED_LAUNCHER_PATTERN = /^\[ -x (["']?)((?:\.\/|\/.*\/)?\.codex\/managed-hooks\/((?:wp|ak)-[\w-]+)\.sh)\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
 export function isWebpressoOwnedCodexHook(metadata, expectedSourcePaths) {
     if (!isObject(metadata))
         return false;
@@ -46,8 +48,14 @@ function extractDirectNodeModulesBin(command) {
     const match = NODE_MODULES_BIN_PATTERN.exec(normalizedCommand);
     if (match?.[1])
         return match[1];
+    const managedLauncherMatch = MANAGED_LAUNCHER_PATTERN.exec(normalizedCommand);
+    if (managedLauncherMatch?.[2])
+        return managedLauncherMatch[2];
     const guardedMatch = GUARDED_NODE_MODULES_BIN_PATTERN.exec(command.trim());
-    return guardedMatch?.[3] ?? null;
+    if (guardedMatch?.[3])
+        return guardedMatch[3];
+    const guardedManagedLauncherMatch = GUARDED_MANAGED_LAUNCHER_PATTERN.exec(command.trim());
+    return guardedManagedLauncherMatch?.[3] ?? null;
 }
 function stripSingleShellQuotePair(value) {
     if (value.length < 2)

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

@@ -9,9 +9,10 @@
  *
  * Runs by default on every `wp setup`.
  */
-import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { patchJsonFile } from '#cli/commands/init/merge';
 import { CodexAppServerClient } from '#codex/app-server/client.js';
 import { normalizeGlobalCodexHooksFile, resolveBinaryOnPath, } from '#cli/commands/init/scaffolders/agent-hooks/codex-global-normalize';
@@ -28,16 +29,32 @@ import { buildSkillTag, extractSkillHooks, isTaggedSkillHook, } from './skill-ho
 //   bypass when the guard binary is missing/non-executable.
 const PRETOOL_GUARD_BIN = 'wp-pretool-guard';
 const PRETOOL_GUARD_MISSING_DENY = `printf '%s\\n' '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"wp-pretool-guard is unavailable. Run vp install or wp setup."}}'`;
+const CLAUDE_MANAGED_HOOK_SUBDIR = '.claude/hooks/managed';
+const CODEX_MANAGED_HOOK_SUBDIR = '.codex/managed-hooks';
+function claudeManagedHookLauncherPath(name) {
+    return `$CLAUDE_PROJECT_DIR/${CLAUDE_MANAGED_HOOK_SUBDIR}/${name}.sh`;
+}
+function codexManagedHookLauncherPath(repoRoot, name) {
+    return resolve(repoRoot, CODEX_MANAGED_HOOK_SUBDIR, `${name}.sh`);
+}
+function quoteShell(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function quoteHookCommandPath(value) {
+    if (value.startsWith('$CLAUDE_PROJECT_DIR/'))
+        return `"${value}"`;
+    return quoteShell(value);
+}
 function buildGuardedHookCommand(binPath, name) {
+    const quotedBinPath = quoteHookCommandPath(binPath);
     if (name === PRETOOL_GUARD_BIN) {
-        return `[ -x "${binPath}" ] && "${binPath}" || ${PRETOOL_GUARD_MISSING_DENY}`;
+        return `[ -x ${quotedBinPath} ] && ${quotedBinPath} || ${PRETOOL_GUARD_MISSING_DENY}`;
     }
-    return `[ -x "${binPath}" ] && "${binPath}" || true`;
+    return `[ -x ${quotedBinPath} ] && ${quotedBinPath} || true`;
 }
-const CC_BIN = (name) => buildGuardedHookCommand(`$CLAUDE_PROJECT_DIR/node_modules/.bin/${name}`, name);
+const CC_BIN = (name) => buildGuardedHookCommand(claudeManagedHookLauncherPath(name), name);
 const CODEX_BIN = (repoRoot) => (name) => {
-    const binPath = resolve(repoRoot, 'node_modules', '.bin', name);
-    return buildGuardedHookCommand(binPath, name);
+    return buildGuardedHookCommand(codexManagedHookLauncherPath(repoRoot, name), name);
 };
 // Canonical hook event names recognised by both Claude Code and Codex CLI.
 // Used by `hoistTopLevelEvents` to identify legacy flat-form keys to migrate.
@@ -77,6 +94,8 @@ const DIRECT_NODE_MODULES_BIN_PATTERN = /^(?:\.\/|\/.*\/)?node_modules\/\.bin\/(
 const GUARDED_NODE_MODULES_BIN_PATTERN = /^\[ -x (["']?)((?:\.\/|\/.*\/)?node_modules\/\.bin\/([\w-]+))\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
 const DIRECT_CLAUDE_NODE_MODULES_BIN_PATTERN = /^["']?\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/([\w-]+)["']?$/u;
 const GUARDED_CLAUDE_NODE_MODULES_BIN_PATTERN = /^\[ -x (["']?)\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/([\w-]+)\1 \] && \1\$CLAUDE_PROJECT_DIR\/node_modules\/\.bin\/\2\1 \|\| (?:true|printf .+)$/u;
+const DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN = /^(?:["']?)((?:\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.codex\/managed-hooks)\/((?:wp|ak)-[\w-]+)\.sh)(?:["']?)$/u;
+const GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN = /^\[ -x (["']?)((?:\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.claude\/hooks\/managed|(?:\.\/|\/.*\/)?\.codex\/managed-hooks)\/((?:wp|ak)-[\w-]+)\.sh)\1 \] && \1\2\1 \|\| (?:true|printf .+)$/u;
 // Capture the basename of any path that ends in a known script extension.
 // Handles trailing chars (quote, space, end-of-string).
 const SCRIPT_BASENAME_PATTERN = new RegExp(String.raw `([\w-]+\.(?:${SCRIPT_EXTENSIONS.join('|')}))(?=$|["'\s])`, 'u');
@@ -110,9 +129,15 @@ function extractAgentKitCodexBinName(command) {
     const directBinMatch = DIRECT_NODE_MODULES_BIN_PATTERN.exec(normalizedCommand);
     if (directBinMatch !== null)
         return directBinMatch[1] ?? null;
+    const directManagedLauncherMatch = DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN.exec(normalizedCommand);
+    if (directManagedLauncherMatch !== null)
+        return directManagedLauncherMatch[2] ?? null;
     const guardedBinMatch = GUARDED_NODE_MODULES_BIN_PATTERN.exec(command.trim());
     if (guardedBinMatch !== null)
         return guardedBinMatch[3] ?? null;
+    const guardedManagedLauncherMatch = GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN.exec(command.trim());
+    if (guardedManagedLauncherMatch !== null)
+        return guardedManagedLauncherMatch[3] ?? null;
     return null;
 }
 function extractClaudeBinName(command) {
@@ -120,9 +145,15 @@ function extractClaudeBinName(command) {
     const directBinMatch = DIRECT_CLAUDE_NODE_MODULES_BIN_PATTERN.exec(normalizedCommand);
     if (directBinMatch !== null)
         return directBinMatch[1] ?? null;
+    const directManagedLauncherMatch = DIRECT_MANAGED_HOOK_LAUNCHER_PATTERN.exec(normalizedCommand);
+    if (directManagedLauncherMatch !== null)
+        return directManagedLauncherMatch[2] ?? null;
     const guardedBinMatch = GUARDED_CLAUDE_NODE_MODULES_BIN_PATTERN.exec(command.trim());
     if (guardedBinMatch !== null)
         return guardedBinMatch[2] ?? null;
+    const guardedManagedLauncherMatch = GUARDED_MANAGED_HOOK_LAUNCHER_PATTERN.exec(command.trim());
+    if (guardedManagedLauncherMatch !== null)
+        return guardedManagedLauncherMatch[3] ?? null;
     return null;
 }
 function stripSingleShellQuotePair(value) {
@@ -305,20 +336,33 @@ function normalizeCodexAgentKitCommands(hooks, repoRoot) {
     }
     return normalized;
 }
-function pruneLegacyClaudeAgentKitCommands(hooks) {
+function normalizeClaudeAgentKitCommands(hooks) {
     const normalized = {};
     for (const [event, groups] of Object.entries(hooks)) {
-        const keptGroups = groups
-            .map((group) => {
-            const keptHooks = group.hooks.filter((hook) => {
-                const classification = classifyWebpressoHookBin(extractClaudeBinName(hook.command));
-                return classification === null || classification.kind !== 'legacy';
-            });
-            return keptHooks.length > 0 ? { ...group, hooks: keptHooks } : null;
-        })
-            .filter((group) => group !== null);
-        if (keptGroups.length > 0)
-            normalized[event] = keptGroups;
+        const normalizedGroups = groups.reduce((dedupedGroups, group) => {
+            const nextGroup = {
+                ...group,
+                hooks: group.hooks.flatMap((hook) => {
+                    const command = hook.command;
+                    if (typeof command !== 'string')
+                        return hook;
+                    const classification = classifyWebpressoHookBin(extractClaudeBinName(command));
+                    if (classification === null)
+                        return hook;
+                    if (classification.kind === 'legacy')
+                        return [];
+                    return {
+                        ...hook,
+                        command: CC_BIN(classification.binName),
+                    };
+                }),
+            };
+            if (nextGroup.hooks.length === 0)
+                return dedupedGroups;
+            return ensureGroup(dedupedGroups, nextGroup);
+        }, []);
+        if (normalizedGroups.length > 0)
+            normalized[event] = normalizedGroups;
     }
     return normalized;
 }
@@ -380,7 +424,7 @@ function patchClaudeUserSettings(existing) {
     return next;
 }
 function patchClaudeSettings(existing, skillHooks) {
-    const existingHooks = pruneLegacyClaudeAgentKitCommands((existing.hooks ?? {}));
+    const existingHooks = normalizeClaudeAgentKitCommands((existing.hooks ?? {}));
     const withSkills = mergeSkillHooks(existingHooks, skillHooks);
     const webpresso = buildWebpressoHookGroups({
         resolveBin: CC_BIN,
@@ -560,8 +604,74 @@ function ensureGstackHooks(repoRoot, options = {}) {
         chmodSync(sessionPath, 0o755);
     }
 }
+function resolveProjectHookBinPath(repoRoot, binName) {
+    return resolve(repoRoot, 'node_modules', '@webpresso', 'agent-kit', 'bin', `${binName}.js`);
+}
+function resolvePackageHookBin(binName) {
+    return join(resolvePackageRoot(), 'bin', `${binName}.js`);
+}
+function resolvePackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth++) {
+        if (existsSync(join(dir, 'package.json')) && existsSync(join(dir, 'bin', 'wp.js'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('wp setup: could not locate @webpresso/agent-kit package root for hook launchers.');
+}
+function renderManagedWebpressoHookLauncher(repoRoot, binName) {
+    const nodeBinary = quoteShell(process.execPath);
+    const projectBinPath = quoteShell(resolveProjectHookBinPath(repoRoot, binName));
+    const fallbackBinPath = quoteShell(resolvePackageHookBin(binName));
+    const missingFallback = binName === PRETOOL_GUARD_BIN ? PRETOOL_GUARD_MISSING_DENY : 'exit 0';
+    return `#!/bin/sh
+NODE_BINARY=${nodeBinary}
+PROJECT_BIN_PATH=${projectBinPath}
+FALLBACK_BIN_PATH=${fallbackBinPath}
+
+if [ ! -x "$NODE_BINARY" ]; then
+  ${missingFallback}
+  exit 0
+fi
+
+if [ -f "$PROJECT_BIN_PATH" ]; then
+  exec "$NODE_BINARY" "$PROJECT_BIN_PATH" "$@"
+fi
+
+if [ -f "$FALLBACK_BIN_PATH" ]; then
+  exec "$NODE_BINARY" "$FALLBACK_BIN_PATH" "$@"
+fi
+
+${missingFallback}
+exit 0
+`;
+}
+function ensureManagedWebpressoHookLaunchers(repoRoot, options = {}) {
+    if (options.dryRun)
+        return;
+    const launcherTargets = [
+        join(repoRoot, CLAUDE_MANAGED_HOOK_SUBDIR),
+        join(repoRoot, CODEX_MANAGED_HOOK_SUBDIR),
+    ];
+    for (const directory of launcherTargets) {
+        mkdirSync(directory, { recursive: true });
+        for (const binName of WEBPRESSO_HOOK_BIN_NAMES) {
+            const launcherPath = join(directory, `${binName}.sh`);
+            const content = renderManagedWebpressoHookLauncher(repoRoot, binName);
+            if (!existsSync(launcherPath) || readFileSync(launcherPath, 'utf8') !== content) {
+                writeFileSync(launcherPath, content, 'utf8');
+            }
+            chmodSync(launcherPath, 0o755);
+        }
+    }
+}
 export async function scaffoldAgentHooks(input) {
     ensureGstackHooks(input.repoRoot, input.options);
+    ensureManagedWebpressoHookLaunchers(input.repoRoot, input.options);
     const skillHooks = extractSkillHooks(join(input.repoRoot, '.agent', 'skills'));
     const result = {
         claude: patchJsonFile(join(input.repoRoot, '.claude', 'settings.json'), (existing) => patchClaudeSettings(existing, skillHooks), input.options),

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

@@ -0,0 +1,65 @@
+/**
+ * `agent-kit-global` self-update scaffolder.
+ *
+ * Keeps the ONE globally-distributed `@webpresso/agent-kit` binary fresh on
+ * every `wp setup`, mirroring how omx / omc / codex / claude self-update their
+ * own global installs. The PATH `wp`, the Claude plugin MCP, and the agent
+ * hooks all resolve to this single global binary, so refreshing it here means
+ * the next invocation everywhere runs the latest published release.
+ *
+ * Uses the exact same command the auto-update installer infers
+ * (`buildVpGlobalInstallCommand` — single source of truth), so there is no
+ * second place that can drift on the install incantation.
+ *
+ * Skipped (no-op, non-fatal) when:
+ *   - `--dry-run` (no writes anywhere),
+ *   - `WP_SKIP_AUTO_INSTALL=1` (the documented opt-out, surfaced in the update
+ *     banner),
+ *   - the running binary resolves into a webpresso source/git clone — a global
+ *     install would clobber the developer's working clone with a published
+ *     tarball (`detectGitInstall`),
+ *   - `vp` is not on PATH (nothing to install with).
+ *
+ * A failed refresh is reported but NEVER fails consumer setup: keeping the
+ * global tool current is ancillary to scaffolding the consumer repo (same
+ * warn-only contract as the codex-cli scaffolder).
+ */
+import { spawnSync } from 'node:child_process';
+import type { MergeOptions } from '#cli/commands/init/merge';
+import { type SpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+export interface EnsureAgentKitGlobalInput {
+    options: MergeOptions;
+    /** DI seam for child_process.spawnSync. */
+    spawn?: typeof spawnSync;
+    /** DI seam for environment-backed opt-out. */
+    env?: NodeJS.ProcessEnv;
+    /** The running binary path (defaults to process.argv[1]). Used for source-clone detection. */
+    argv1?: string;
+    /** DI seam for source/git-clone detection. */
+    detectGit?: (argv1: string) => string | null;
+    /** DI seam for spinner. Defaults to noop when !process.stdout.isTTY. */
+    spinnerFactory?: SpinnerFactory;
+}
+export type EnsureAgentKitGlobalResult = {
+    kind: 'agent-kit-global-updated';
+    command: readonly string[];
+} | {
+    kind: 'agent-kit-global-skipped-dry-run';
+} | {
+    kind: 'agent-kit-global-skipped-opt-out';
+} | {
+    kind: 'agent-kit-global-skipped-source-clone';
+    repoRoot: string;
+} | {
+    kind: 'agent-kit-global-skipped-no-vp';
+    hint: string;
+} | {
+    kind: 'agent-kit-global-failed';
+    exitCode: number;
+    command: readonly string[];
+};
+/**
+ * Refresh the single global `@webpresso/agent-kit` install via `vp install -g`.
+ */
+export declare function ensureAgentKitGlobal(input: EnsureAgentKitGlobalInput): EnsureAgentKitGlobalResult;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,64 @@
+/**
+ * `agent-kit-global` self-update scaffolder.
+ *
+ * Keeps the ONE globally-distributed `@webpresso/agent-kit` binary fresh on
+ * every `wp setup`, mirroring how omx / omc / codex / claude self-update their
+ * own global installs. The PATH `wp`, the Claude plugin MCP, and the agent
+ * hooks all resolve to this single global binary, so refreshing it here means
+ * the next invocation everywhere runs the latest published release.
+ *
+ * Uses the exact same command the auto-update installer infers
+ * (`buildVpGlobalInstallCommand` — single source of truth), so there is no
+ * second place that can drift on the install incantation.
+ *
+ * Skipped (no-op, non-fatal) when:
+ *   - `--dry-run` (no writes anywhere),
+ *   - `WP_SKIP_AUTO_INSTALL=1` (the documented opt-out, surfaced in the update
+ *     banner),
+ *   - the running binary resolves into a webpresso source/git clone — a global
+ *     install would clobber the developer's working clone with a published
+ *     tarball (`detectGitInstall`),
+ *   - `vp` is not on PATH (nothing to install with).
+ *
+ * A failed refresh is reported but NEVER fails consumer setup: keeping the
+ * global tool current is ancillary to scaffolding the consumer repo (same
+ * warn-only contract as the codex-cli scaffolder).
+ */
+import { spawnSync } from 'node:child_process';
+import { makeNoopSpinnerFactory } from '#cli/commands/init/scaffolders/spinner';
+import { buildVpGlobalInstallCommand, detectGitInstall, PUBLIC_PACKAGE_NAME, } from '#cli/auto-update/detect-pm.js';
+const NO_VP_HINT = 'vp (vite-plus) is not on PATH; cannot refresh the global ' +
+    `${PUBLIC_PACKAGE_NAME}. Install vite-plus, then re-run \`wp setup\`.`;
+/**
+ * Refresh the single global `@webpresso/agent-kit` install via `vp install -g`.
+ */
+export function ensureAgentKitGlobal(input) {
+    if (input.options.dryRun)
+        return { kind: 'agent-kit-global-skipped-dry-run' };
+    const env = input.env ?? process.env;
+    if (env.WP_SKIP_AUTO_INSTALL === '1') {
+        return { kind: 'agent-kit-global-skipped-opt-out' };
+    }
+    const argv1 = input.argv1 ?? process.argv[1] ?? '';
+    const detectGit = input.detectGit ?? detectGitInstall;
+    const sourceCloneRoot = argv1.length > 0 ? detectGit(argv1) : null;
+    if (sourceCloneRoot !== null) {
+        return { kind: 'agent-kit-global-skipped-source-clone', repoRoot: sourceCloneRoot };
+    }
+    const spawn = input.spawn ?? spawnSync;
+    const spinner = (input.spinnerFactory ?? makeNoopSpinnerFactory())('agent-kit-global');
+    const probe = spawn('vp', ['--version'], { encoding: 'utf8' });
+    if (probe.error || (probe.status !== null && probe.status !== 0)) {
+        return { kind: 'agent-kit-global-skipped-no-vp', hint: NO_VP_HINT };
+    }
+    const command = buildVpGlobalInstallCommand();
+    spinner.start();
+    const install = spawn(command[0], command.slice(1), { stdio: 'inherit' });
+    if (install.status !== 0) {
+        spinner.fail('agent-kit global refresh failed');
+        return { kind: 'agent-kit-global-failed', exitCode: install.status ?? -1, command };
+    }
+    spinner.succeed('agent-kit global up to date');
+    return { kind: 'agent-kit-global-updated', command };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/cli/commands/package-manager.d.ts

@@ -0,0 +1,15 @@
+import type { CAC } from 'cac';
+import type { SpawnSyncReturns } from 'node:child_process';
+export declare const PACKAGE_MANAGER_VERBS: readonly ["install", "add", "remove", "update", "exec", "run"];
+export type PackageManagerVerb = (typeof PACKAGE_MANAGER_VERBS)[number];
+export interface PackageManagerCommandConfig {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface PackageManagerCommandDeps {
+    readonly run?: (command: string, args: readonly string[]) => SpawnSyncReturns<string>;
+}
+export declare function registerPackageManagerCommand(cli: CAC, verb: PackageManagerVerb): void;
+export declare function buildPackageManagerCommand(verb: PackageManagerVerb, argv?: readonly string[]): PackageManagerCommandConfig;
+export declare function runPackageManagerCommand(verb: PackageManagerVerb, deps?: PackageManagerCommandDeps): number;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/esm/cli/commands/package-manager.js

@@ -0,0 +1,42 @@
+import { spawnSync } from 'node:child_process';
+import { getManagedRunner } from '#tool-runtime';
+export const PACKAGE_MANAGER_VERBS = ['install', 'add', 'remove', 'update', 'exec', 'run'];
+const HELP_BY_VERB = {
+    install: 'Install dependencies through the managed vp facade.',
+    add: 'Add dependencies through the managed vp facade.',
+    remove: 'Remove dependencies through the managed vp facade.',
+    update: 'Update dependencies through the managed vp facade.',
+    exec: 'Run a binary through the managed vp facade.',
+    run: 'Run a package script through the managed vp facade.',
+};
+export function registerPackageManagerCommand(cli, verb) {
+    cli
+        .command(`${verb} [...args]`, HELP_BY_VERB[verb])
+        .allowUnknownOptions()
+        .action(() => runPackageManagerCommand(verb));
+}
+export function buildPackageManagerCommand(verb, argv = process.argv) {
+    const resolution = getManagedRunner('vp', { outputPolicy: 'structured' });
+    return {
+        command: resolution.command,
+        args: [...resolution.args, verb, ...extractVerbArgs(verb, argv)],
+    };
+}
+export function runPackageManagerCommand(verb, deps = {}) {
+    const command = buildPackageManagerCommand(verb);
+    const result = (deps.run ?? defaultRun)(command.command, command.args);
+    return typeof result.status === 'number' ? result.status : 1;
+}
+function extractVerbArgs(verb, argv) {
+    const verbIndex = argv.findIndex((arg, index) => index >= 2 && arg === verb);
+    return verbIndex === -1 ? [] : argv.slice(verbIndex + 1);
+}
+function defaultRun(command, args) {
+    return spawnSync(command, [...args], {
+        encoding: 'utf8',
+        env: process.env,
+        stdio: 'inherit',
+        windowsHide: true,
+    });
+}
+//# sourceMappingURL=package-manager.js.map

package/dist/esm/cli/commands/test.d.ts

@@ -2,6 +2,7 @@ import type { CommandConfig, TestCommandOptions } from '#test';
 import type { CAC } from 'cac';
 export declare const TEST_COMMAND_HELP: string;
 export interface AkTestCommandInput extends TestCommandOptions {
+    cwd?: string;
     package?: readonly string[] | string;
     file?: readonly string[] | string;
     targets?: readonly string[] | string;

package/dist/esm/cli/commands/test.js

@@ -14,7 +14,7 @@ export function createAkTestCommandConfig(input) {
         file: toArray(input.file),
         positional: toArray(input.targets),
     });
-    return buildTestCommand(target, input);
+    return buildTestCommand(target, { ...input, cwd: input.cwd });
 }
 export function registerTestCommand(cli) {
     cli
@@ -35,6 +35,7 @@ export function registerTestCommand(cli) {
         .action((targets, flags) => {
         const rawArgv = process.argv.slice(2);
         const command = createAkTestCommandConfig({
+            cwd: process.cwd(),
             package: flags.package,
             file: flags.file,
             targets: targets ?? [],