@webpresso/agent-kit 0.26.1 → 0.26.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Webpresso agent-kit Claude Code plugin: blueprints, skills, hooks, MCP server",
-    "version": "0.26.1"
+    "version": "0.26.3"
   },
   "plugins": [
     {
@@ -23,5 +23,5 @@
       ]
     }
   ],
-  "version": "0.26.1"
+  "version": "0.26.3"
 }

package/.claude-plugin/plugin.json

@@ -1,66 +1,9 @@
 {
   "name": "webpresso",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Webpresso agent-kit: blueprints, skills, lore commit protocol, tech-debt lifecycle",
   "skills": "./skills",
   "commands": "./commands",
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash|Edit|Write|MultiEdit|WebFetch|Read|Grep",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-pretool-guard.js"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-post-tool.js",
-            "timeout": 15
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-stop-qa.js"
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-guard-switch.js",
-            "timeout": 5
-          }
-        ]
-      }
-    ],
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/wp-sessionstart-routing.js"
-          }
-        ]
-      }
-    ]
-  },
   "mcpServers": {
     "webpresso": {
       "command": "node",

package/README.md

@@ -44,6 +44,15 @@ Playwright, unit-test and file-based e2e smoke assets), wires `AGENTS.md` /
 execution-owned vs authoring-owned dependency migration guidance. Re-running
 refreshes the webpresso-owned pieces and preserves consumer-owned files.
 
+> **`wp setup` is required for hooks.** The Claude Code hooks (PreToolUse guard,
+> Stop-QA gate, SessionStart routing, …) are installed by `wp setup` into your
+> repo's `.claude/settings.json`. They are intentionally **not** shipped in the
+> plugin manifest — declaring them in both places double-fires every hook (Claude
+> Code does not dedup across sources), and settings.json is the more reliable
+> surface. So enabling the plugin alone does **not** activate hooks; run
+> `wp setup`. Run `wp hooks doctor` to check — it warns if the managed hooks are
+> missing from `.claude/settings.json`.
+
 `wp` owns **execution** for the generic tool lanes it manages (test / mutation /
 e2e / lint / format / typecheck). That does **not** mean every local
 devDependency disappears — keep dependencies your repo imports directly (e.g.

package/catalog/AGENTS.md.tpl

@@ -36,9 +36,9 @@ vp install && vp run setup:agent  # setup:agent runs wp setup, which scaffolds .
 agent-kit's catalog is the single source of truth for generated agent surfaces.
 Agent-kit owns the generated agent surfaces in this file; the Webpresso CLI host owns the end-user command surface.
 To customize skills, commands, or workflows, edit them in agent-kit's catalog
-and publish — not in individual repos. The default `omx` preset chains
-`omx setup --yes --scope user` and installs missing OMX through
-`vp install -g oh-my-codex`. The default `omc` preset ensures OMC through
+and publish — not in individual repos. The default `omx` preset refreshes
+Vite+ through `vp upgrade`, chains `omx setup --yes --scope user`, and installs
+missing OMX through `vp install -g oh-my-codex`. The default `omc` preset ensures OMC through
 Claude Code's plugin marketplace in user scope when `claude` is on `PATH`.
 `wp setup` also repairs the managed `.gitignore` block for regenerated agent
 surfaces so repo-local `.codex/`,

package/dist/esm/audit/repo-guardrails.d.ts

@@ -73,6 +73,23 @@ export interface NoRelativeParentImportsOptions {
  * tsconfig `extends`, `paths`, `references`, etc.
  */
 export declare function auditNoRelativeParentImports(root: string, options?: NoRelativeParentImportsOptions): RepoAuditResult;
+export interface TestIsolationOptions {
+    /** Directory to scan for test files. Defaults to `src`. */
+    srcDir?: string;
+    /** Test-file suffixes to inspect. Defaults to `.test.ts` / `.test.tsx`. */
+    extensions?: readonly string[];
+}
+/**
+ * Fail if any `*.test.ts` reaches the repo's own `catalog/` template source
+ * through `process.cwd()`. The catalog tree is the source of every
+ * agent-surface template, so a `process.cwd()`-anchored path is both brittle
+ * (it depends on the runner's working directory) and the exact pattern behind
+ * the scaffold-agents-md footgun, where a test read the live
+ * `catalog/AGENTS.md.tpl` off cwd. Anchor catalog reads to the package via the
+ * import.meta-based `resolveCatalogDir()` helper instead, and write only into
+ * `mkdtemp`/`tmpdir` sandboxes.
+ */
+export declare function auditTestIsolation(root: string, options?: TestIsolationOptions): RepoAuditResult;
 export interface NoRelativePackageScriptsOptions {
     /** Glob-style subdirectory patterns relative to root to skip. */
     excludeDirs?: readonly string[];

package/dist/esm/audit/repo-guardrails.js

@@ -809,6 +809,81 @@ function walkTsconfigParentPaths(startDir, reportRoot, violations) {
     walk(startDir);
     return checked;
 }
+const TEST_ISOLATION_SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    '.git',
+    '.cache',
+    '.next',
+    '.turbo',
+    '.omx',
+    '.stryker-tmp',
+    '.claude',
+    // Scaffolding templates become a downstream consumer's tree, not ours.
+    'template',
+    // Workspace-level scratch/archive space.
+    '_sandbox',
+]);
+// `(join|resolve)(process.cwd(), ... 'catalog' ...)` — a test reaching into the
+// live catalog template source off the runner's working directory.
+const CWD_CATALOG_PATH_PATTERN = /\b(?:join|resolve)\s*\(\s*process\.cwd\(\)[^)]*\bcatalog\b/;
+/**
+ * Fail if any `*.test.ts` reaches the repo's own `catalog/` template source
+ * through `process.cwd()`. The catalog tree is the source of every
+ * agent-surface template, so a `process.cwd()`-anchored path is both brittle
+ * (it depends on the runner's working directory) and the exact pattern behind
+ * the scaffold-agents-md footgun, where a test read the live
+ * `catalog/AGENTS.md.tpl` off cwd. Anchor catalog reads to the package via the
+ * import.meta-based `resolveCatalogDir()` helper instead, and write only into
+ * `mkdtemp`/`tmpdir` sandboxes.
+ */
+export function auditTestIsolation(root, options = {}) {
+    const srcDir = resolve(root, options.srcDir ?? 'src');
+    const extensions = options.extensions ?? ['.test.ts', '.test.tsx'];
+    const violations = [];
+    let checked = 0;
+    function walk(dir) {
+        if (!existsSync(dir))
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (TEST_ISOLATION_SKIP_DIRS.has(entry.name))
+                    continue;
+                walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!extensions.some((ext) => entry.name.endsWith(ext)))
+                continue;
+            checked++;
+            const content = readFileSync(full, 'utf-8');
+            const rel = relativePath(root, full);
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i] ?? '';
+                // Skip comment lines so prose referencing the pattern doesn't trip it.
+                if (/^\s*(?:\/\/|\/\*|\*)/.test(line))
+                    continue;
+                if (CWD_CATALOG_PATH_PATTERN.test(line)) {
+                    violations.push({
+                        file: rel,
+                        message: `Line ${i + 1}: test reads the catalog template source via process.cwd() — anchor catalog reads to the package with resolveCatalogDir() (import.meta-based) so the test does not depend on the runner's working directory: ${line.trim()}`,
+                    });
+                }
+            }
+        }
+    }
+    walk(srcDir);
+    return {
+        ok: violations.length === 0,
+        title: 'test-isolation',
+        checked,
+        violations,
+    };
+}
 function withFilePrefix(file, auditResult) {
     return {
         ...auditResult,

package/dist/esm/blueprint/aggregate.d.ts

@@ -50,9 +50,9 @@ export declare const readTargetSchema: z.ZodObject<{
     project_id: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodEnum<{
         all: "all";
+        workspace: "workspace";
         current: "current";
         roots: "roots";
-        workspace: "workspace";
     }>>;
 }, z.core.$strict>;
 export type ReadTarget = z.infer<typeof readTargetSchema>;

package/dist/esm/blueprint/core/schema.d.ts

@@ -39,8 +39,8 @@ export declare const lifecycleBlueprintStatusSchema: z.ZodEnum<{
  */
 export declare const taskStatusSchema: z.ZodEnum<{
     blocked: "blocked";
-    todo: "todo";
     done: "done";
+    todo: "todo";
     in_progress: "in_progress";
 }>;
 /**

package/dist/esm/blueprint/db/enums.d.ts

@@ -27,8 +27,8 @@ export declare const blueprintComplexitySchema: z.ZodEnum<{
 export declare const taskStatusSchema: z.ZodEnum<{
     blocked: "blocked";
     "in-progress": "in-progress";
-    todo: "todo";
     done: "done";
+    todo: "todo";
     dropped: "dropped";
 }>;
 export declare const techDebtStatusSchema: z.ZodEnum<{

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

@@ -32,6 +32,7 @@ const REPO_AUDIT_REGISTRY = {
     }),
     'no-link-protocol': async (root) => (await import('#audit/repo-guardrails')).auditNoLinkProtocol(root),
     'no-relative-package-scripts': async (root) => (await import('#audit/repo-guardrails')).auditNoRelativePackageScripts(root),
+    'test-isolation': async (root) => (await import('#audit/repo-guardrails')).auditTestIsolation(root),
     'bucket-boundary': async (root, options) => (await import('#audit/bucket-boundary')).auditBucketBoundary(root, {
         changedOnly: options.changedOnly,
         strict: options.strict,

package/dist/esm/cli/commands/init/detect-consumer.d.ts

@@ -45,5 +45,16 @@ export declare function discoverWorkspacePackages(repoRoot: string, globs: strin
  * class that the catch-wrap doesn't surface.
  */
 export declare function warnIfNonLocalCli(repoRoot: string, cliUrl?: string): void;
+/**
+ * agent-kit's own package name — the source repo for every agent-surface
+ * template (`catalog/`, the tracked `.agent/`/`.claude/` surfaces). Scaffolding
+ * into this repo overwrites the canonical sources, so `wp setup` refuses it
+ * unless explicitly overridden. Distinct from base-kit's broader
+ * `SELF_PACKAGE_NAMES` (which also covers the legacy `webpresso` framework
+ * identity); only agent-kit hosts the catalog templates.
+ */
+export declare const AGENT_KIT_PACKAGE_NAME = "@webpresso/agent-kit";
+/** True when the consumer being scaffolded is agent-kit's own template-source repo. */
+export declare function isAgentKitTemplateSourceRepo(packageName: string | undefined): boolean;
 export declare function detectConsumer(startDir?: string): ConsumerContext | null;
 //# sourceMappingURL=detect-consumer.d.ts.map

package/dist/esm/cli/commands/init/detect-consumer.js

@@ -261,6 +261,19 @@ export function warnIfNonLocalCli(repoRoot, cliUrl = import.meta.url) {
             ? 'This repo already pins `webpresso`; rerun via the repo-local CLI (`vp run setup:agent` or `vp exec wp setup`).'
             : 'Pin `webpresso` as a local dep for reproducible setup.'));
 }
+/**
+ * agent-kit's own package name — the source repo for every agent-surface
+ * template (`catalog/`, the tracked `.agent/`/`.claude/` surfaces). Scaffolding
+ * into this repo overwrites the canonical sources, so `wp setup` refuses it
+ * unless explicitly overridden. Distinct from base-kit's broader
+ * `SELF_PACKAGE_NAMES` (which also covers the legacy `webpresso` framework
+ * identity); only agent-kit hosts the catalog templates.
+ */
+export const AGENT_KIT_PACKAGE_NAME = '@webpresso/agent-kit';
+/** True when the consumer being scaffolded is agent-kit's own template-source repo. */
+export function isAgentKitTemplateSourceRepo(packageName) {
+    return packageName === AGENT_KIT_PACKAGE_NAME;
+}
 export function detectConsumer(startDir = process.cwd()) {
     const repoRoot = findGitRoot(startDir);
     if (!repoRoot)

package/dist/esm/cli/commands/init/index.d.ts

@@ -11,6 +11,7 @@ export interface InitFlags {
     cwd?: string;
     strict?: boolean;
     project?: boolean;
+    allowSelfScaffold?: boolean;
 }
 export declare const EXIT_SUCCESS = 0;
 export declare const EXIT_SETUP_FAIL = 1;

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

@@ -14,7 +14,7 @@ import { readPackageVersion } from '#cli/utils';
 import { resolveBlueprintRoot } from '#utils/blueprint-root';
 import { runUnifiedSync } from '#symlinker/unified-sync';
 import { defaultConfig, mergeConfig, readConfig, writeConfig, } from './config.js';
-import { detectConsumer, warnIfNonLocalCli } from './detect-consumer.js';
+import { detectConsumer, isAgentKitTemplateSourceRepo, warnIfNonLocalCli, } from './detect-consumer.js';
 import { runPreflight, DOCS_URL } from './preflight.js';
 import { summarizeResults } from './merge.js';
 import { resolveTier3Selection } from './prompts.js';
@@ -138,6 +138,19 @@ export async function runInit(flags) {
             `Run \`git init\` first, or pass --cwd pointing at a git working tree.`);
         return EXIT_SETUP_FAIL;
     }
+    // Self-repo guard: agent-kit is the SOURCE of every agent-surface template
+    // (catalog/, the tracked .agent/.claude surfaces). Scaffolding into its own
+    // working tree overwrites those canonical sources — the footgun where a stray
+    // `wp setup` reported `overwritten: 2, drifted: 11, git index cleanup: 6
+    // untracked` against the live repo. Refuse loudly and write nothing unless the
+    // maintainer explicitly opts in with --allow-self-scaffold.
+    if (isAgentKitTemplateSourceRepo(consumer.packageJson?.name) && flags.allowSelfScaffold !== true) {
+        console.error(`wp setup: refusing to scaffold @webpresso/agent-kit's own repo (${consumer.repoRoot}).\n` +
+            `  This repo is the source of the agent-surface templates; running setup here\n` +
+            `  overwrites the canonical sources under catalog/ and the tracked .agent/.claude surfaces.\n` +
+            `  To deliberately regenerate agent-kit's own surfaces, re-run with --allow-self-scaffold.`);
+        return EXIT_SETUP_FAIL;
+    }
     warnIfNonLocalCli(consumer.repoRoot);
     // Run the 5-point compatibility preflight before any scaffolders fire.
     const preflightResult = await runPreflight(consumer.repoRoot, flags.strict ?? false);
@@ -839,6 +852,7 @@ export function registerInitCommand(cli, commandName = 'init') {
         .option('--cwd <dir>', 'Working tree to scaffold into (default: process.cwd())')
         .option('--strict', 'Abort if any compatibility check fails (default: warn and continue)')
         .option('--project', 'Configure OMX/OMC in project scope instead of the default user scope')
+        .option('--allow-self-scaffold', "Override the self-repo guard to scaffold @webpresso/agent-kit's own template-source repo (maintainers only)")
         .action(async (flags) => {
         const code = await runInit(flags);
         if (code !== EXIT_SUCCESS) {

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

@@ -13,6 +13,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'n
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isHookName } from '#cli/commands/hook.js';
 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';
@@ -623,13 +624,65 @@ function resolvePackageRoot() {
     }
     throw new Error('wp setup: could not locate @webpresso/agent-kit package root for hook launchers.');
 }
+// Consumer-side runtime package directory for the current platform. Mirrors the
+// canonical target table in `src/build/runtime-targets.ts`; kept inline here to
+// avoid a deep cross-tree import for a small lookup. If that target list ever
+// changes, update both. Returns undefined for platforms with no compiled
+// runtime package.
+function compiledRuntimePackageDir() {
+    const osLabel = process.platform === 'win32' ? 'windows' : process.platform;
+    const id = `${osLabel}-${process.arch}`;
+    const known = new Set(['darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64', 'windows-x64']);
+    return known.has(id) ? `agent-kit-runtime-${id}` : undefined;
+}
+/**
+ * Absolute path to the consumer's self-contained compiled `wp` binary, when the
+ * platform runtime package (`@webpresso/agent-kit-runtime-<platform>`) is
+ * installed. The compiled binary bundles its own runtime, so preferring it makes
+ * the hook launcher survive node-path staleness — an nvm/version change
+ * invalidates the captured absolute node path but not a self-contained binary.
+ * Returns undefined when no compiled runtime is installed (today's default), so
+ * the launcher keeps its absolute-node fallback unchanged.
+ */
+function resolveCompiledWpBinary(repoRoot) {
+    const packageDir = compiledRuntimePackageDir();
+    if (!packageDir)
+        return undefined;
+    const filename = process.platform === 'win32' ? 'wp.exe' : 'wp';
+    const candidate = join(repoRoot, 'node_modules', '@webpresso', packageDir, 'bin', filename);
+    return existsSync(candidate) ? candidate : undefined;
+}
+/**
+ * The `wp hook <sub>` subcommand a managed launcher should dispatch to via the
+ * compiled binary, or undefined when `binName` is not a dispatchable hook (e.g.
+ * `wp-check-dev-link`, which has no `wp hook` handler). The names map 1:1 by
+ * stripping the `wp-` prefix; `isHookName` is the single source of truth.
+ */
+function hookSubcommandFor(binName) {
+    const sub = binName.startsWith('wp-') ? binName.slice(3) : binName;
+    return isHookName(sub) ? sub : undefined;
+}
 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';
+    // Prefer the self-contained compiled `wp` binary when it resolves: it bundles
+    // its own runtime, so it is immune to the node-path staleness that would break
+    // the absolute `$NODE_BINARY` path below. Only emitted for dispatchable hooks
+    // with an installed compiled runtime; otherwise the node path is unchanged.
+    const hookSub = hookSubcommandFor(binName);
+    const compiledWp = hookSub ? resolveCompiledWpBinary(repoRoot) : undefined;
+    const compiledPreamble = compiledWp !== undefined
+        ? `WP_BIN=${quoteShell(compiledWp)}
+if [ -x "$WP_BIN" ]; then
+  exec "$WP_BIN" hook ${hookSub} "$@"
+fi
+
+`
+        : '';
     return `#!/bin/sh
-NODE_BINARY=${nodeBinary}
+${compiledPreamble}NODE_BINARY=${nodeBinary}
 PROJECT_BIN_PATH=${projectBinPath}
 FALLBACK_BIN_PATH=${fallbackBinPath}
 

package/dist/esm/cli/commands/init/scaffolders/omx/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * `omx` scaffolder preset.
  *
- * Ensures `omx` is installed, then chains `omx setup --yes --scope user` after the
- * webpresso scaffold completes. OMX (oh-my-codex) is the operator-workflow
+ * Refreshes Vite+ (`vp`), ensures `omx` is installed, then chains
+ * `omx setup --yes --scope user` after the webpresso scaffold completes.
+ * OMX (oh-my-codex) is the operator-workflow
  * execution layer; it manages its own scaffolding idempotently.
  *
  * Required when downstream features rely on `omx team` (see
@@ -55,7 +56,8 @@ type OmxSetupScope = 'user' | 'project';
 export declare function deduplicateCodexHookTrustState(config: string): string;
 export declare function migrateDeprecatedCodexHooksFeatureFlag(raw: string): string;
 /**
- * Ensure `omx` is on PATH then run `omx setup --yes --scope user` in the consumer repo.
+ * Refresh `vp`, ensure `omx` is on PATH, then run
+ * `omx setup --yes --scope user` in the consumer repo.
  * Idempotent: safe to run on every `wp setup`.
  */
 export declare function ensureOmx(input: EnsureOmxInput): EnsureOmxResult;

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

@@ -1,8 +1,9 @@
 /**
  * `omx` scaffolder preset.
  *
- * Ensures `omx` is installed, then chains `omx setup --yes --scope user` after the
- * webpresso scaffold completes. OMX (oh-my-codex) is the operator-workflow
+ * Refreshes Vite+ (`vp`), ensures `omx` is installed, then chains
+ * `omx setup --yes --scope user` after the webpresso scaffold completes.
+ * OMX (oh-my-codex) is the operator-workflow
  * execution layer; it manages its own scaffolding idempotently.
  *
  * Required when downstream features rely on `omx team` (see
@@ -14,7 +15,7 @@ import { homedir } from 'node:os';
 import { dirname, join, resolve, sep } from 'node:path';
 import { defaultCodexHooksPathFromConfig, normalizeGlobalCodexHooksFile, resolveBinaryOnPath, } from '#cli/commands/init/scaffolders/agent-hooks/codex-global-normalize';
 const NOT_FOUND_HINT = 'omx (oh-my-codex) is not on PATH after `vp install -g oh-my-codex`. Install it manually and re-run.';
-function shouldSkipOmxRefresh(env = process.env) {
+function shouldSkipManagedToolRefresh(env = process.env) {
     return env.WP_SKIP_UPDATE_CHECK === '1';
 }
 function defaultCodexConfigPath() {
@@ -190,7 +191,8 @@ function pruneEmptyProjectScopedDirs(repoRoot, relativeFile) {
     }
 }
 /**
- * Ensure `omx` is on PATH then run `omx setup --yes --scope user` in the consumer repo.
+ * Refresh `vp`, ensure `omx` is on PATH, then run
+ * `omx setup --yes --scope user` in the consumer repo.
  * Idempotent: safe to run on every `wp setup`.
  */
 export function ensureOmx(input) {
@@ -210,6 +212,9 @@ export function ensureOmx(input) {
         }
     }
     let installed = false;
+    if (!shouldSkipManagedToolRefresh()) {
+        spawn('vp', ['upgrade'], { stdio: 'inherit' });
+    }
     let probe = spawn('omx', ['--version'], { encoding: 'utf8' });
     if (probe.error || (probe.status !== null && probe.status !== 0)) {
         const install = spawn('vp', ['install', '-g', 'oh-my-codex'], { stdio: 'inherit' });
@@ -222,7 +227,7 @@ export function ensureOmx(input) {
             return { kind: 'omx-not-found', hint: NOT_FOUND_HINT };
         }
     }
-    else if (!shouldSkipOmxRefresh()) {
+    else if (!shouldSkipManagedToolRefresh()) {
         spawn('vp', ['update', '-g', 'oh-my-codex'], { stdio: 'inherit' });
     }
     const result = spawn('omx', ['setup', '--yes', '--scope', scope], {

package/dist/esm/config/docs-lint/schemas/agents.d.ts

@@ -17,8 +17,8 @@ export declare const agentsFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";
@@ -57,8 +57,8 @@ export declare const agentEntryFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/audit.d.ts

@@ -18,8 +18,8 @@ export declare const auditFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/common.d.ts

@@ -25,8 +25,8 @@ export declare const baseFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/cookbook.d.ts

@@ -19,8 +19,8 @@ export declare const cookbookFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/core.d.ts

@@ -18,8 +18,8 @@ export declare const coreFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";
@@ -54,8 +54,8 @@ export declare const readmeFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";
@@ -88,8 +88,8 @@ export declare const securityFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";
@@ -169,8 +169,8 @@ export declare const agentsFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/evaluation.d.ts

@@ -19,8 +19,8 @@ export declare const evaluationFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/ongoing-initiative.d.ts

@@ -38,8 +38,8 @@ export declare const planArtifactFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";
@@ -79,8 +79,8 @@ export declare const planReportFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/config/docs-lint/schemas/rule.d.ts

@@ -18,8 +18,8 @@ export declare const ruleFrontmatter: z.ZodObject<{
         monitoring: "monitoring";
         resolved: "resolved";
         open: "open";
-        deprecated: "deprecated";
         current: "current";
+        deprecated: "deprecated";
         complete: "complete";
         active: "active";
         review: "review";

package/dist/esm/hooks/doctor.d.ts

@@ -13,6 +13,8 @@ export interface DoctorCheck {
     name: string;
     ok: boolean;
     detail?: string;
+    /** Advisory checks surface a warning but do not flip the doctor's exit code. */
+    advisory?: boolean;
 }
 export interface DoctorResult {
     ok: boolean;
@@ -28,6 +30,16 @@ export interface RunHooksDoctorOptions {
 }
 export declare function findOwningPackageRoot(startDir: string): string | null;
 export declare function checkRtkOnPath(cwd?: string): Promise<DoctorCheck | null>;
+/**
+ * Verify the consumer's `.claude/settings.json` carries the managed agent-kit
+ * hook launchers. Since the hooks are single-sourced there (not in the plugin
+ * manifest), a missing reference means a plugin-only install that never ran
+ * `wp setup` — i.e. no agent-kit hooks are active.
+ */
+export declare function checkManagedHooksInstalled(cwd?: string): {
+    ok: boolean;
+    detail?: string;
+};
 export declare function runHooksDoctor(opts?: RunHooksDoctorOptions): Promise<DoctorResult>;
 export declare function printHooksDoctor(opts?: RunHooksDoctorOptions): Promise<number>;
 export {};

package/dist/esm/hooks/doctor.js

@@ -590,6 +590,40 @@ function checkLiveSourceDevLink(cwd = process.cwd()) {
         detail: `${state.package} → ${state.linkedFrom}`,
     };
 }
+// Marker for the managed hook launchers `wp setup` writes under
+// `.claude/hooks/managed/` (CLAUDE_MANAGED_HOOK_SUBDIR in the agent-hooks
+// scaffolder). The plugin manifest no longer ships hooks (they double-fired
+// against these and were the less reliable surface), so settings.json is the
+// single source — if it does not reference them, the hooks are not installed.
+const MANAGED_HOOK_MARKER = 'hooks/managed/wp-pretool-guard';
+/**
+ * Verify the consumer's `.claude/settings.json` carries the managed agent-kit
+ * hook launchers. Since the hooks are single-sourced there (not in the plugin
+ * manifest), a missing reference means a plugin-only install that never ran
+ * `wp setup` — i.e. no agent-kit hooks are active.
+ */
+export function checkManagedHooksInstalled(cwd = process.cwd()) {
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    if (!tryAccess(settingsPath)) {
+        return {
+            ok: false,
+            detail: 'no .claude/settings.json — run `wp setup` to install the agent-kit hooks',
+        };
+    }
+    try {
+        const raw = readFileSync(settingsPath, 'utf-8');
+        if (!raw.includes(MANAGED_HOOK_MARKER)) {
+            return {
+                ok: false,
+                detail: 'agent-kit hooks not found in .claude/settings.json — run `wp setup`',
+            };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, detail: `failed to read .claude/settings.json: ${String(err)}` };
+    }
+}
 export async function runHooksDoctor(opts = {}) {
     const checks = [];
     const isWin = platform() === 'win32';
@@ -609,6 +643,11 @@ export async function runHooksDoctor(opts = {}) {
     }
     checks.push(checkConsumerCodexHookPaths(opts.cwd));
     checks.push({ name: 'plugin.json integrity', ...checkPluginJson() });
+    checks.push({
+        name: 'managed hooks installed (.claude/settings.json)',
+        advisory: true,
+        ...checkManagedHooksInstalled(opts.cwd),
+    });
     if (opts.skipMcp) {
         checks.push({ name: 'MCP server liveness', ok: true, detail: 'skipped (--skip-mcp)' });
     }
@@ -676,7 +715,7 @@ export async function runHooksDoctor(opts = {}) {
             }
         }
     }
-    const nonMcpChecks = checks.filter((c) => !c.name.startsWith('MCP '));
+    const nonMcpChecks = checks.filter((c) => !c.name.startsWith('MCP ') && !c.advisory);
     const overallOk = nonMcpChecks.every((c) => c.ok);
     return { ok: overallOk, checks };
 }

package/dist/esm/mcp/tools/_shared/result.d.ts

@@ -9,8 +9,8 @@ export declare const transformMetadataSchema: z.ZodObject<{
     toolName: z.ZodString;
     normalizedToolName: z.ZodString;
     tier: z.ZodEnum<{
-        registered: "registered";
         passthrough: "passthrough";
+        registered: "registered";
     }>;
     rawBytes: z.ZodNumber;
 }, z.core.$strip>;
@@ -38,8 +38,8 @@ export declare const summaryFirstResultSchema: z.ZodObject<{
         toolName: z.ZodString;
         normalizedToolName: z.ZodString;
         tier: z.ZodEnum<{
-            registered: "registered";
             passthrough: "passthrough";
+            registered: "registered";
         }>;
         rawBytes: z.ZodNumber;
     }, z.core.$strip>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpresso/agent-kit",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "private": false,
   "repository": {
     "type": "git",
@@ -710,10 +710,10 @@
     "@stryker-mutator/typescript-checker": "^9.6.1",
     "@playwright/test": "^1.55.0",
     "wrangler": "^4.50.0",
-    "@webpresso/agent-kit-runtime-darwin-arm64": "0.26.1",
-    "@webpresso/agent-kit-runtime-darwin-x64": "0.26.1",
-    "@webpresso/agent-kit-runtime-linux-x64": "0.26.1",
-    "@webpresso/agent-kit-runtime-linux-arm64": "0.26.1",
-    "@webpresso/agent-kit-runtime-windows-x64": "0.26.1"
+    "@webpresso/agent-kit-runtime-darwin-arm64": "0.26.3",
+    "@webpresso/agent-kit-runtime-darwin-x64": "0.26.3",
+    "@webpresso/agent-kit-runtime-linux-x64": "0.26.3",
+    "@webpresso/agent-kit-runtime-linux-arm64": "0.26.3",
+    "@webpresso/agent-kit-runtime-windows-x64": "0.26.3"
   }
 }