@webpresso/agent-kit 0.21.5 → 0.24.0

package/dist/esm/cli/cli.js

@@ -11,6 +11,7 @@ import { resolve as pathResolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bootstrapAk } from './bootstrap.js';
 import { formatUnknownCommandError, normalizeArgv, readPackageVersion } from './utils.js';
+import { registerWpExtensions, resolveWpCommandAlias } from './wp-extensions.js';
 const VERSION = readPackageVersion(import.meta.url);
 const SUPPORTED_COMMANDS = [
     'blueprint',
@@ -37,9 +38,16 @@ const SUPPORTED_COMMANDS = [
     'tech-debt',
     'worktree',
     'mcp',
+    'hook',
     'hooks',
     'gain',
     'bench',
+    'install',
+    'add',
+    'remove',
+    'update',
+    'exec',
+    'run',
 ];
 const ROOT_HELP = [
     'Usage: wp [command] [options]',
@@ -52,6 +60,12 @@ const ROOT_HELP = [
     '  gain                  Show token savings from RTK — run after any AI session',
     '  sync                  Sync agent rules + skills across IDE surfaces (--kind, --check)',
     '  bench                 Run the session-memory benchmark harness',
+    '  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',
     '',
     'Quality:',
     '  audit                 Run packaged audits (bundle budgets, repo guardrails, TPH, tech-debt)',
@@ -123,7 +137,17 @@ export async function main() {
         return 0;
     }
     await bootstrapAk(VERSION, argv);
-    switch (command) {
+    const extensionRuntime = await registerWpExtensions({
+        cli,
+        cwd: process.cwd(),
+        env: process.env,
+        hostVersion: VERSION,
+        baseCommands: [...SUPPORTED_COMMANDS],
+    });
+    for (const warning of extensionRuntime.warnings)
+        console.error(warning);
+    const resolvedCommand = resolveWpCommandAlias(command, extensionRuntime.aliasMap);
+    switch (resolvedCommand) {
         case 'blueprint': {
             const { registerBlueprintRouter } = await import('./commands/blueprint/router.js');
             registerBlueprintRouter(cli);
@@ -177,7 +201,7 @@ export async function main() {
         case 'setup':
         case 'init': {
             const { registerInitCommand } = await import('./commands/init/index.js');
-            registerInitCommand(cli, command);
+            registerInitCommand(cli, resolvedCommand);
             break;
         }
         case 'dev': {
@@ -235,6 +259,11 @@ export async function main() {
             registerMcpCommand(cli);
             break;
         }
+        case 'hook': {
+            const { registerHookCommand } = await import('./commands/hook.js');
+            registerHookCommand(cli);
+            break;
+        }
         case 'hooks': {
             const { registerHooksCommand } = await import('./commands/hooks.js');
             registerHooksCommand(cli);
@@ -250,20 +279,35 @@ export async function main() {
             registerBenchCommand(cli);
             break;
         }
+        case 'install':
+        case 'add':
+        case 'remove':
+        case 'update':
+        case 'exec':
+        case 'run': {
+            const { registerPackageManagerCommand } = await import('./commands/package-manager.js');
+            registerPackageManagerCommand(cli, resolvedCommand);
+            break;
+        }
         case 'worktree': {
             const { registerWorktreeRouter } = await import('./commands/worktree/router.js');
             registerWorktreeRouter(cli);
             break;
         }
         default: {
-            console.error(formatUnknownCommandError(command, SUPPORTED_COMMANDS));
-            return 1;
+            if (!resolvedCommand || !extensionRuntime.commandNames.includes(resolvedCommand)) {
+                console.error(formatUnknownCommandError(command, SUPPORTED_COMMANDS));
+                return 1;
+            }
         }
     }
     cli.help();
     cli.version(VERSION);
     try {
-        cli.parse(argv, { run: false });
+        const effectiveArgv = resolvedCommand && resolvedCommand !== command
+            ? [argv[0] ?? 'node', argv[1] ?? 'wp', resolvedCommand, ...argv.slice(3)]
+            : argv;
+        cli.parse(effectiveArgv, { run: false });
         const result = await cli.runMatchedCommand();
         return typeof result === 'number' ? result : 0;
     }

package/dist/esm/cli/commands/audit-core.d.ts

@@ -1,5 +1,5 @@
 import type { RepoAuditResult } from '#audit/repo-guardrails';
-export type AuditKind = 'tph' | 'tph-e2e' | 'bundle-budget' | 'commit-message' | 'blueprint-lifecycle' | 'roadmap-links' | 'docs-frontmatter' | 'catalog-drift' | 'package-surface' | 'agents' | 'tech-debt' | 'no-relative-parent-imports' | 'no-link-protocol' | 'vision' | 'bucket-boundary' | 'skill-sizes' | 'broken-refs' | 'memory-rotation' | 'gitignore-agent-surfaces' | 'memory-unified' | 'compile-drift' | 'architecture-drift' | 'absolute-path-policy' | 'agent-cost' | 'blueprint-db-consistency' | 'blueprint-lifecycle-sql' | 'tech-debt-cadence' | 'cross-repo-correlation' | 'ai-contracts' | 'mutation' | 'quality' | 'guardrails' | 'hook-surface' | 'no-relative-package-scripts';
+export type AuditKind = 'tph' | 'tph-e2e' | 'bundle-budget' | 'commit-message' | 'blueprint-lifecycle' | 'roadmap-links' | 'docs-frontmatter' | 'catalog-drift' | 'package-surface' | 'agents' | 'tech-debt' | 'no-relative-parent-imports' | 'no-link-protocol' | 'vision' | 'bucket-boundary' | 'skill-sizes' | 'broken-refs' | 'memory-rotation' | 'gitignore-agent-surfaces' | 'memory-unified' | 'compile-drift' | 'architecture-drift' | 'cloudflare-deploy-contract' | 'absolute-path-policy' | 'agent-cost' | 'blueprint-db-consistency' | 'blueprint-lifecycle-sql' | 'tech-debt-cadence' | 'cross-repo-correlation' | 'ai-contracts' | 'mutation' | 'quality' | 'guardrails' | 'hook-surface' | 'no-relative-package-scripts';
 export type AuditOutcome = {
     kind: 'invalid-usage';
     message: string;

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

@@ -56,7 +56,9 @@ const REPO_AUDIT_REGISTRY = {
     'gitignore-agent-surfaces': async (root) => (await import('#audit/gitignore-agent-surfaces')).auditGitignoreAgentSurfaces(root),
     'memory-unified': async (root) => (await import('#audit/memory-unified')).auditMemoryUnified(root),
     'compile-drift': async (root) => (await import('#audit/compile-drift')).auditCompileDrift(root),
+    'no-legacy-cli-bin': async (root) => (await import('#audit/no-legacy-cli-bin')).auditNoLegacyCliBin(root),
     'architecture-drift': async (root) => (await import('#audit/architecture-drift')).auditArchitectureDrift(root),
+    'cloudflare-deploy-contract': async (root) => (await import('#audit/cloudflare-deploy-contract')).auditCloudflareDeployContract(root),
     'absolute-path-policy': async (root) => (await import('#audit/absolute-path-policy')).auditAbsolutePathPolicy(root),
     'agent-cost': async (root) => (await import('#audit/agent-cost')).auditAgentCost(root),
     'blueprint-db-consistency': async (root) => (await import('#audit/blueprint-db-consistency')).auditBlueprintDbConsistency(root),

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