@webpresso/agent-kit 3.3.4 → 3.3.5

package/dist/esm/content/loader.js

@@ -21,10 +21,12 @@ const DEFAULT_KINDS = ["rule", "skill"];
 const CONSUMER_DIR_BY_KIND = {
     rule: "agent-rules",
     skill: "agent-skills",
+    agent: "agent-agents",
 };
 const CATALOG_DIR_BY_KIND = {
     rule: "rules",
     skill: "skills",
+    agent: "agents",
 };
 export function loadContent(options) {
     const { catalogDir, consumerRoot, kinds = DEFAULT_KINDS } = options;
@@ -83,9 +85,11 @@ function readKind(args) {
     const stat = statSync(root);
     if (!stat.isDirectory())
         return [];
-    return kind === "rule" ? readRules(root, source) : readSkills(root, source);
+    // agent kind shares the rule shape: flat `<slug>.md` files, README.md
+    // excluded. Only `skill` is directory-shaped (`<slug>/SKILL.md`).
+    return kind === "skill" ? readSkills(root, source) : readFlatMarkdown(kind, root, source);
 }
-function readRules(root, source) {
+function readFlatMarkdown(kind, root, source) {
     const out = [];
     for (const entry of readdirSync(root, { withFileTypes: true })) {
         if (!entry.isFile())
@@ -93,9 +97,9 @@ function readRules(root, source) {
         if (!entry.name.endsWith(".md"))
             continue;
         // Skip directory-documentation files. README.md exists in both the
-        // canonical catalog and the consumer-owned agent-rules/ scaffolder
-        // surface; treating it as a rule would produce a spurious slug
-        // collision and would also try to project it into per-IDE surfaces.
+        // canonical catalog and the consumer-owned agent-rules/ (or agent-agents/)
+        // scaffolder surface; treating it as content would produce a spurious
+        // slug collision and would also try to project it into per-IDE surfaces.
         if (entry.name === "README.md")
             continue;
         const filePath = realpathSync(join(root, entry.name));
@@ -103,7 +107,7 @@ function readRules(root, source) {
         const parsed = matter(readFileSync(filePath, "utf8"));
         const raw = { ...parsed.data };
         out.push({
-            kind: "rule",
+            kind,
             slug,
             source,
             filePath,

package/dist/esm/content/skill-policy.d.ts

@@ -1,6 +1,17 @@
 export declare const DEFAULT_PACKAGED_SKILL_SLUGS: readonly ["verify", "fix", "investigate", "ai-deslop", "plan-refine", "ralplan", "best-practice-research", "testing-philosophy", "tph", "claude", "codex", "grok", "opencode-go", "plan-eng-review", "plan-ceo-review", "plan-design-review", "plan-devex-review", "browse", "devex-review", "design-review", "hooks-doctor", "tech-debt", "lore-protocol", "deep-interview", "deep-research", "autoresearch", "ultragoal", "autopilot", "team"];
 export type DefaultPackagedSkillSlug = (typeof DEFAULT_PACKAGED_SKILL_SLUGS)[number];
 export declare const DEFAULT_PACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export declare const UNPACKAGED_SKILL_SLUGS: Readonly<Record<string, string>>;
+export declare const UNPACKAGED_SKILL_SLUG_SET: ReadonlySet<string>;
+export declare function isUnpackagedSkillSlug(slug: string): boolean;
 export declare const MERGED_DELETED_SKILL_SLUGS: readonly ["autoplan", "health", "systematic-debugging", "test-driven-development"];
 export declare const MERGED_DELETED_SKILL_SLUG_SET: ReadonlySet<string>;
 /**

package/dist/esm/content/skill-policy.js

@@ -30,6 +30,39 @@ export const DEFAULT_PACKAGED_SKILL_SLUGS = [
     "team",
 ];
 export const DEFAULT_PACKAGED_SKILL_SLUG_SET = new Set(DEFAULT_PACKAGED_SKILL_SLUGS);
+/**
+ * Catalog skills that are deliberately NOT in DEFAULT_PACKAGED_SKILL_SLUGS,
+ * with a one-line reason each. Every slug under `catalog/agent/skills/` must
+ * appear in either that list or this one (enforced by
+ * `checkCatalogSkillClassification` in `src/audit/agents.ts`) — an
+ * unclassified slug means a new catalog skill shipped without a deliberate
+ * packaging decision.
+ */
+export const UNPACKAGED_SKILL_SLUGS = {
+    qa: "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    "qa-only": "source-catalog QA skill, not package-visible in the default plugin skill set today (see workflow-skills-routing.md)",
+    review: "listed as a default workflow skill in workflow-skills-routing.md but not yet added to DEFAULT_PACKAGED_SKILL_SLUGS",
+    pll: "ultragoal's parallel-execute companion (ready-queue/worktrees driver); not independently default-packaged",
+    "frontend-design": "opt-in design-guidance skill, not part of the default packaged workflow set",
+    "monorepo-navigation": "tier-3 opt-in preset (wp setup --with monorepo-navigation), not default-packaged",
+    "tanstack-query": "tier-3 opt-in preset (wp setup --with tanstack-query), not default-packaged",
+    "react-doctor": "opt-in framework best-practice skill, not default-packaged",
+    "better-auth-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "logging-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "vercel-react-best-practices": "opt-in best-practice reference skill, not default-packaged",
+    "web-design-guidelines": "opt-in best-practice reference skill, not default-packaged",
+    deepseek: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    glm: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    hy3: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    kimi: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    mimo: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    minimax: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+    qwen: "individual OpenCode-Go model reviewer skill; only the aggregate opencode-go skill is default-packaged",
+};
+export const UNPACKAGED_SKILL_SLUG_SET = new Set(Object.keys(UNPACKAGED_SKILL_SLUGS));
+export function isUnpackagedSkillSlug(slug) {
+    return UNPACKAGED_SKILL_SLUG_SET.has(slug);
+}
 export const MERGED_DELETED_SKILL_SLUGS = [
     "autoplan",
     "health",

package/dist/esm/hooks/pretool-guard/dev-routing.js

@@ -296,11 +296,11 @@ const SAFE_PASSTHROUGH_PREFIXES = [
 const SANDBOX_PREFIXES = [
     {
         prefix: "grep",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
+        guidance: "Recursive/directory-wide grep is unbounded; narrow to explicit file target(s) (`grep -n pattern file`) to pass through directly. Otherwise use wp_session_batch_execute for bounded search so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use a bounded `rg -n ... | sed -n '1,120p'` excerpt instead of recursive raw grep output",
     },
     {
         prefix: "find",
-        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
+        guidance: "Use wp_session_batch_execute for bounded shell gathering/search commands so output is capped, indexed, and recallable instead of flooding the transcript — note wp_session_batch_execute runs argv directly (no shell) and cannot express `|`/`>`. If MCP is unavailable, use `rg --files ... | sed -n '1,120p'` or another explicit bounded listing",
     },
     {
         prefix: "cat",
@@ -324,7 +324,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git log",
-        guidance: "Use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use explicit bounds such as `git log --oneline -n 50`",
+        guidance: "Add an explicit count bound (`-N`, `-n N`, or `--max-count=N`) to pass through directly — e.g. `git log --oneline -50`. Otherwise use wp_session_batch_execute for bounded git log shell gathering so output is capped, indexed, and recallable. If MCP is unavailable, use an explicit bound directly, e.g. `git log --oneline -n 50`",
     },
     {
         prefix: "git diff",
@@ -332,7 +332,7 @@ const SANDBOX_PREFIXES = [
     },
     {
         prefix: "git show",
-        guidance: "Use wp_session_batch_execute or wp_session_execute for bounded git show gathering instead of raw large output. If MCP is unavailable, use `git show --stat` or a targeted excerpt",
+        guidance: "Add `--stat`/`--name-only`/`--name-status`/`--shortstat` to pass through directly — e.g. `git show --stat HEAD` — or use wp_session_batch_execute or wp_session_execute for bounded gathering of the full patch",
     },
     {
         prefix: "vp run build",
@@ -782,6 +782,63 @@ const BOUNDED_GIT_DIFF = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTIO
 function isBoundedGitDiffRead(command) {
     return BOUNDED_GIT_DIFF.test(command);
 }
+// `git log`/`git show` reads are bounded (small, predictable output) exactly when
+// they carry an explicit count/summary bound the same way BOUNDED_GIT_DIFF already
+// recognizes `--stat`/`--name-only`/etc. as bounded. Unbounded forms (bare `git log`,
+// full-patch `git show <ref>`) still fall through to the SANDBOX_PREFIXES rules below.
+const SIMPLE_GIT_LOG_PREFIX = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}log\b`, "u");
+const GIT_LOG_COUNT_BOUND = /(?:^|\s)(?:-\d+|-n[=\s]?\d+|--max-count(?:=|\s+)\d+)(?:\s|$)/u;
+function isBoundedGitLogRead(command) {
+    return SIMPLE_GIT_LOG_PREFIX.test(command) && GIT_LOG_COUNT_BOUND.test(command);
+}
+const BOUNDED_GIT_SHOW = new RegExp(String.raw `^git\s+${SIMPLE_GIT_GLOBAL_OPTION}show\b(?=[\s\S]*(?:--stat\b|--shortstat\b|--name-only\b|--name-status\b))(?![\s\S]*(?:--patch\b|-p\b))`, "u");
+function isBoundedGitShowRead(command) {
+    return BOUNDED_GIT_SHOW.test(command);
+}
+// A grep read is bounded when it targets explicit file argument(s) (not a whole
+// directory tree via -r/-R/--recursive/--include/--exclude*) and supplies at least
+// one non-flag file target beyond the pattern itself. Recursive/directory-wide grep
+// stays sandboxed since its output size is unpredictable.
+const GREP_RECURSIVE_LONG_FLAGS = new Set([
+    "--recursive",
+    "--include",
+    "--exclude",
+    "--exclude-dir",
+    "--exclude-from",
+]);
+function isBoundedGrepRead(command) {
+    const tokens = tokenizeCommand(command);
+    if (tokens[0] !== "grep")
+        return false;
+    const positionals = [];
+    let optionsEnded = false;
+    for (let index = 1; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
+            continue;
+        }
+        if (!optionsEnded && token !== "-" && token.startsWith("-")) {
+            const longFlag = token.split("=")[0] ?? token;
+            if (GREP_RECURSIVE_LONG_FLAGS.has(longFlag))
+                return false;
+            // Strip a trailing bundled numeric argument (e.g. the `2` in `-rA2` for
+            // `-r -A 2`) before checking for a bundled `r`/`R` — otherwise a
+            // recursive short flag bundled with a value-taking flag like `-A`/`-B`/
+            // `-C`/`-m` slips past undetected.
+            const shortCluster = token.slice(1).replace(/\d+$/u, "");
+            if (/^[A-Za-z]+$/u.test(shortCluster) && /[rR]/u.test(shortCluster))
+                return false;
+            continue;
+        }
+        positionals.push(token);
+    }
+    // First positional is the search pattern; at least one more explicit file
+    // target is required to count as a bounded (non-stdin, non-directory) read.
+    return positionals.length >= 2;
+}
 function escapedRegexToken(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -982,6 +1039,12 @@ export function routeCommand(command, _sessionId) {
     }
     if (isBoundedGitDiffRead(trimmed))
         return { action: { action: "passthrough" } };
+    if (isBoundedGitLogRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGitShowRead(trimmed))
+        return { action: { action: "passthrough" } };
+    if (isBoundedGrepRead(trimmed))
+        return { action: { action: "passthrough" } };
     // Explicit passthroughs (audits, safe git/nav commands)
     for (const prefix of PASSTHROUGH_PREFIXES) {
         if (matchesPrefix(trimmed, prefix))

package/dist/esm/hooks/pretool-guard/validators/worktree-discipline.js

@@ -850,7 +850,9 @@ const GIT_GLOBAL_RUN = `(?:-C\\s+${QUOTED_ARG}\\s+|-c\\s+${QUOTED_ARG}\\s+|--git
 // branch flags are allowed.
 const FORBIDDEN_SUBCOMMAND = "(commit\\b|switch\\b(?!\\s+(?:-h|--help)\\b)|checkout\\s+(?!--(?:\\s|$))(?:(?:\\S+\\s+)*)\\S|branch\\s+(?:(?!-|--)\\S|--track\\b|--no-track\\b|--create-reflog\\b|--force\\b|-f\\b|-c\\b|-C\\b|-m\\b|-M\\b))";
 const FORBIDDEN_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})${FORBIDDEN_SUBCOMMAND}`, "gu");
-const MAIN_OWNERSHIP_OP = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b[^;&|(){}]*|checkout\\b[^;&|(){}]*|branch\\b[^;&|(){}]*|worktree\\s+add\\b[^;&|(){}]*)`, "gu");
+// Verb-only: deliberately does NOT slurp trailing arguments itself (see
+// mainOwnershipGitOps below for why a naive `[^;&|(){}]*` capture is unsafe).
+const MAIN_OWNERSHIP_VERB = new RegExp(`\\bgit\\s+(${GIT_GLOBAL_RUN})(switch\\b|checkout\\b|branch\\b|worktree\\s+add\\b)`, "gu");
 function labelFor(subcommand) {
     if (subcommand.startsWith("commit"))
         return "git commit";
@@ -958,12 +960,69 @@ function mainOwnershipLabel(words) {
         return "git worktree add main";
     return null;
 }
+/**
+ * Quote-aware segment bounds for `command`, split on the same unquoted
+ * `;&|(){}` control characters as {@link splitShellSegments} (kept in sync
+ * intentionally), but returning OFFSETS instead of trimmed substrings so a
+ * caller can slice the original command text for a match that falls inside a
+ * given segment.
+ */
+function segmentBounds(command) {
+    const bounds = [];
+    let start = 0;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === undefined)
+            continue;
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (quote !== "'" && ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (quote === null || quote === ch)) {
+            quote = quote === ch ? null : ch;
+            continue;
+        }
+        if (!quote && /[;&|(){}]/u.test(ch)) {
+            bounds.push({ start, end: i });
+            start = i + 1;
+        }
+    }
+    bounds.push({ start, end: command.length });
+    return bounds;
+}
+/**
+ * Main-ownership candidate ops (`git switch|checkout|branch|worktree add`).
+ *
+ * MAIN_OWNERSHIP_VERB intentionally does NOT slurp trailing arguments itself
+ * (unlike the pre-fix implementation) — a naive `[^;&|(){}]*` character class
+ * is not quote-aware, so a read-only `git branch --format='%(refname:short)'`
+ * has its captured subcommand text truncated mid-quote at the `(` inside the
+ * quoted format string, producing an unterminated quote that shellWords()
+ * reports as "ambiguous" and gets fail-closed blocked — purely because of a
+ * paren inside its OWN quoted argument, not because it mutates anything.
+ * Bounding the subcommand text to the enclosing quote-aware shell segment
+ * (segmentBounds, sharing splitShellSegments' control-char set) fixes that
+ * without weakening real-mutation detection: genuinely ambiguous syntax
+ * (nested shells, unresolved substitutions, unterminated quotes) still
+ * produces "ambiguous" and fails closed exactly as before.
+ */
 function mainOwnershipGitOps(command) {
     if (!/\bgit\b/u.test(command))
         return [];
     const ops = [];
-    for (const m of command.matchAll(MAIN_OWNERSHIP_OP)) {
-        const subcommand = m[2] ?? "";
+    const segments = segmentBounds(command);
+    for (const m of command.matchAll(MAIN_OWNERSHIP_VERB)) {
+        const verb = m[2] ?? "";
+        const verbStart = (m.index ?? 0) + m[0].length - verb.length;
+        const segment = segments.find((s) => verbStart >= s.start && verbStart < s.end) ??
+            { start: verbStart, end: command.length };
+        const subcommand = command.slice(verbStart, segment.end);
         const words = shellWords(subcommand);
         if (words === "ambiguous") {
             ops.push({ label: "git main", globals: m[1] ?? "", index: m.index ?? 0 });

package/dist/esm/review/authority.js

@@ -9,6 +9,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { evaluateReviewEvents, parseReviewEventLog } from "./events.js";
+import { isPolicyApprovalVerdict } from "./verdict.js";
 import { createDeliverySubjectAtRef, createLegacyPlanSubjectAtRef, createPlanSubjectAtRef, createPreTagsStripPlanSubjectAtRef, resolveReviewCommit, } from "./subject.js";
 const GIT_TIMEOUT_MS = 5_000;
 const GIT_MAX_BUFFER_BYTES = 128 * 1024 * 1024;
@@ -114,6 +115,54 @@ function markCompromisedArtifactEvents(cwd, entries, blueprintDirectory, events)
     }
     return { compromisedIds, issues };
 }
+/** Bounded `git branch -a --contains <commit>` probe, tolerant of a pruned/unknown object. */
+function branchesContainingCommit(cwd, commit) {
+    try {
+        const output = gitBuffer(cwd, ["branch", "-a", "--contains", commit]).toString("utf8");
+        return output
+            .split("\n")
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return null;
+    }
+}
+// Diagnostic-only: names historical ledger approvals whose `reviewedCommit` is
+// no longer reachable from any branch (typically because a rebase rewrote the
+// history that commit lived on). Such an approval no longer matches the
+// current subjectDigest, so it already contributes zero approvals under the
+// existing policy in ./events.ts -- this only makes the reason visible instead
+// of the operator seeing a bare "approvals does not satisfy the promotion
+// reviewer mix" and mistaking a dead commit ref for a genuinely missing
+// review. Never mutates `approvals`/`matching`; policy is unchanged.
+function markOrphanedApprovalEvents(cwd, events, current) {
+    const issues = [];
+    const seen = new Set();
+    for (const event of events) {
+        if (event.purpose !== current.purpose ||
+            event.blueprintSlug !== current.blueprintSlug ||
+            event.subjectScheme !== current.subjectScheme ||
+            event.subjectDigest === current.subjectDigest ||
+            event.status !== "complete" ||
+            !isPolicyApprovalVerdict(event.verdict)) {
+            continue;
+        }
+        const key = `${event.reviewer}:${event.reviewedCommit}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const branches = branchesContainingCommit(cwd, event.reviewedCommit);
+        if (branches === null || branches.length === 0) {
+            issues.push(`Historical approval from ${event.reviewer} (event ${event.id}) reviewed commit ` +
+                `${event.reviewedCommit}, which is unreachable from any branch (git branch -a ` +
+                `--contains ${event.reviewedCommit} found nothing) -- likely orphaned by a rebase. ` +
+                "This approval does not count toward the current subject; rebase this worktree onto " +
+                "the latest base and re-run the gate.");
+        }
+    }
+    return issues;
+}
 export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     const commit = resolveReviewCommit(cwd, ref);
     const entries = parseRefTree(cwd, commit);
@@ -131,6 +180,12 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
     const subject = purpose === "plan"
         ? createPlanSubjectAtRef(cwd, commit, stableSlug, overview.path)
         : createDeliverySubjectAtRef(cwd, commit, stableSlug, overview.path);
+    const orphanIssues = markOrphanedApprovalEvents(cwd, events, {
+        purpose,
+        blueprintSlug: stableSlug,
+        subjectScheme: subject.scheme,
+        subjectDigest: subject.digest,
+    });
     let evaluation = evaluateReviewEvents(events, {
         purpose,
         blueprintSlug: stableSlug,
@@ -166,7 +221,7 @@ export function readReviewAuthorityAtRef(cwd, ref, stableSlug, purpose) {
         subject,
         events,
         ...evaluation,
-        issues,
+        issues: [...issues, ...orphanIssues],
     };
 }
 export function readWorkingReviewEvents(blueprintPath, stableSlug) {

package/dist/esm/review/delivery-verifier.d.ts

@@ -21,6 +21,10 @@ export interface ReviewGateVerification {
     readonly logPath?: string;
     readonly sandbox?: ReviewSandboxMode;
     readonly sandboxReason?: string;
+    readonly violations?: readonly {
+        readonly section: string;
+        readonly message: string;
+    }[];
 }
 /** Runs one gate command in the review checkout and returns its raw result. */
 export type RunSandboxedGate = (args: {

package/dist/esm/review/delivery-verifier.js

@@ -18,7 +18,15 @@ export async function verifyDeliveryPromotionGates(input) {
             parsed.violations[0]?.message === "missing Trust Dossier section") {
             return undefined;
         }
-        return { status: "failed", commands: [], failureCode: "malformed-trust-dossier" };
+        return {
+            status: "failed",
+            commands: [],
+            failureCode: "malformed-trust-dossier",
+            violations: parsed.violations.map((violation) => ({
+                section: violation.section,
+                message: violation.message,
+            })),
+        };
     }
     const gates = parsed.dossier?.gates ?? [];
     if (gates.length === 0)

package/dist/esm/symlinker/consumers.d.ts

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -116,6 +116,8 @@ export declare function unifiedRuleFilename(consumer: UnifiedConsumerConfig, slu
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.

package/dist/esm/symlinker/consumers.js

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -59,6 +59,8 @@ export function unifiedRuleFilename(consumer, slug) {
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.
@@ -69,6 +71,10 @@ export const DEFAULT_UNIFIED_CONSUMERS = [
     { id: "agent-skills", dir: ".agent/skills", acceptsKind: "skill", strategy: "symlink" },
     // Claude: rules are scaffolded to .claude/rules; skills come from native channels.
     { id: "claude-rules", dir: ".claude/rules", acceptsKind: "rule", strategy: "symlink" },
+    // Claude: canonical subagents are scaffolded to .claude/agents. Host-agnostic
+    // (unconditional) because subagents were previously scaffolded unconditionally
+    // by the now-retired standalone scaffoldSubagents scaffolder.
+    { id: "claude-agents", dir: ".claude/agents", acceptsKind: "agent", strategy: "symlink" },
 ];
 /**
  * Projection surfaces retired by a newer agent-kit release.

package/dist/esm/symlinker/unified-sync.d.ts

@@ -1,8 +1,8 @@
 /**
- * Unified rule + skill sync.
+ * Unified rule + skill + agent sync.
  *
- * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
- * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills,agents}/`)
+ * UNION consumer (`<repo>/agent-{rules,skills,agents}/`). The loader returns a
  * source-tagged record list; this module projects that list into per-IDE
  * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *

package/dist/esm/symlinker/unified-sync.js

@@ -1,8 +1,8 @@
 /**
- * Unified rule + skill sync.
+ * Unified rule + skill + agent sync.
  *
- * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
- * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills,agents}/`)
+ * UNION consumer (`<repo>/agent-{rules,skills,agents}/`). The loader returns a
  * source-tagged record list; this module projects that list into per-IDE
  * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
@@ -86,7 +86,9 @@ function planTargets(records, consumers, consumerRoot) {
             const consumerDirAbs = join(consumerRoot, consumer.dir);
             let entryName;
             let targetPath;
-            if (record.kind === "rule") {
+            if (record.kind === "rule" || record.kind === "agent") {
+                // agent records are file-shaped like rules (a single <slug>.md),
+                // not dir-shaped like skills.
                 entryName = unifiedRuleFilename(consumer, record.slug);
                 targetPath = join(consumerDirAbs, entryName);
             }
@@ -248,13 +250,40 @@ function applyTarget(plan, check) {
         }
     }
 }
+/**
+ * True when `fullPath` is a symlink whose resolved target's directory is one
+ * of `managedSourceDirs`. Used to distinguish an agent-kit-managed symlink
+ * (safe to prune when stale/renamed) from a real file or a foreign symlink
+ * (never agent-kit-managed, must survive `wp sync`). The resolved target
+ * itself need not currently exist — a dangling symlink to a since-removed
+ * catalog agent still resolves into the managed source dir and is prunable.
+ */
+function isManagedAgentSymlink(fullPath, managedSourceDirs) {
+    let stat;
+    try {
+        stat = lstatSync(fullPath);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink())
+        return false;
+    try {
+        const linkTarget = readlinkSync(fullPath);
+        const resolved = resolve(dirname(fullPath), linkTarget);
+        return managedSourceDirs.has(dirname(resolved));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Remove entries under each consumer dir that no longer correspond to any
  * planned record. Only removes entries whose shape matches the consumer's
  * managed pattern (rule files: `<slug><ext>`; skill dirs: subdirectories).
  * Real files outside the managed pattern (README.md, .gitkeep) are left alone.
  */
-function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
+function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs, configuredAgentSourceDirs) {
     const expectedByConsumerDir = new Map();
     for (const plan of plans) {
         const key = plan.consumer.dir;
@@ -265,6 +294,25 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
         }
         set.add(plan.entryName);
     }
+    // Directories that agent-kind sources resolve from (the catalog `agents/`
+    // dir, and a consumer `agent-agents/` override dir if present). Unlike
+    // `.claude/rules` and `.claude/skills` — surfaces with no legitimate
+    // hand-authoring workflow — `.claude/agents` is Claude Code's own native
+    // subagent authoring location. A consumer-authored `.claude/agents/foo.md`
+    // that was never agent-kit-managed must survive `wp sync`; only symlinks
+    // that resolve into a known managed source dir are eligible for pruning.
+    //
+    // The set unions plan-derived dirs with the CONFIGURED source dirs so it is
+    // never empty: with an empty or missing catalog agents dir there are no
+    // plans, and a plans-only set would leave nothing provably managed — the
+    // sweep must then delete nothing, not everything. Dangling managed symlinks
+    // (pointing into a configured dir whose file is gone) stay prunable.
+    const agentSourceDirs = new Set([
+        ...configuredAgentSourceDirs,
+        ...plans
+            .filter((plan) => plan.record.kind === "agent")
+            .map((plan) => dirname(plan.record.filePath)),
+    ]);
     let removed = 0;
     const mismatches = [];
     // Each unique dir gets a single sweep — multiple consumers can share a dir
@@ -292,15 +340,28 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
                 preserveSkillSlugs.has(name) &&
                 entry.isDirectory())
                 continue;
-            // Only prune entries that match a managed shape: rule extension OR a
-            // directory (skill).
-            const matchesRulePattern = consumersForDir.some((c) => c.acceptsKind === "rule" && name.endsWith(c.ruleExtension ?? ".md"));
+            // Only prune entries that match a managed shape: rule/agent extension
+            // OR a directory (skill). Agent records are file-shaped like rules.
+            const matchesRulePattern = consumersForDir.some((c) => (c.acceptsKind === "rule" || c.acceptsKind === "agent") &&
+                name.endsWith(c.ruleExtension ?? ".md"));
             const matchesSkillPattern = consumersForDir.some((c) => c.acceptsKind === "skill") && entry.isDirectory();
             // Also handle stale symlinks of either shape.
             const isLink = entry.isSymbolicLink();
             if (!matchesRulePattern && !matchesSkillPattern && !isLink)
                 continue;
             const fullPath = join(dirAbs, name);
+            // Conservative prune for agent-only dirs: skip real files and foreign
+            // symlinks (anything not resolving into a known agent-kit managed
+            // source dir). This guard is unconditional — the source-dir set is
+            // configuration-derived and never empty, so a broken install (empty or
+            // missing catalog agents dir) cannot degrade the sweep into deleting
+            // hand-authored files. Rules/skills dirs have no legitimate
+            // hand-authoring workflow, so their existing
+            // sweep-everything-unexpected behavior is unchanged.
+            const isAgentOnlyDir = consumersForDir.every((c) => c.acceptsKind === "agent");
+            if (isAgentOnlyDir && !isManagedAgentSymlink(fullPath, agentSourceDirs)) {
+                continue;
+            }
             if (check) {
                 mismatches.push({
                     consumerId: consumersForDir[0]?.id ?? dir,
@@ -348,7 +409,7 @@ function pruneEmptyRetiredConsumerDirs(consumers, consumerRoot, check) {
  * Main entrypoint. See module docstring.
  */
 export function runUnifiedSync(options) {
-    const kinds = options.kinds ?? ["rule", "skill"];
+    const kinds = options.kinds ?? ["rule", "skill", "agent"];
     const kindSet = new Set(kinds);
     const consumers = (options.consumers ?? selectUnifiedConsumers(options.hosts)).filter((consumer) => kindSet.has(consumer.acceptsKind));
     const activeDirs = new Set(consumers.map((consumer) => consumer.dir));
@@ -394,10 +455,26 @@ export function runUnifiedSync(options) {
             }
         }
     }
-    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs);
+    // Configuration-derived agent source dirs (catalog `agents/` plus the
+    // consumer `agent-agents/` override). Added in both raw-resolved and
+    // realpath forms so set membership survives the /var → /private/var realm
+    // split on macOS. Present even when the dirs are empty or absent — that is
+    // the point: prune eligibility must not collapse to "everything" when a
+    // broken install yields zero planned agent records.
+    const configuredAgentSourceDirs = new Set();
+    for (const candidate of [
+        join(options.catalogDir, "agents"),
+        join(consumerRoot, "agent-agents"),
+    ]) {
+        configuredAgentSourceDirs.add(resolve(candidate));
+        if (existsSync(candidate)) {
+            configuredAgentSourceDirs.add(realpathSync(candidate));
+        }
+    }
+    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs, configuredAgentSourceDirs);
     fixCount += prune.removed;
     mismatches.push(...prune.mismatches);
-    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined);
+    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined, configuredAgentSourceDirs);
     fixCount += retiredPrune.removed;
     mismatches.push(...retiredPrune.mismatches);
     const retiredDirectories = pruneEmptyRetiredConsumerDirs(retiredConsumers, consumerRoot, options.check === true);

package/dist/esm/test/shard-durations.json

@@ -296,7 +296,6 @@
             "src/hooks/dispatch/index.test.ts": 11.771874999999994,
             "src/hooks/shared/hook-bootstrap.test.ts": 58.217375000000004,
             "src/cli/commands/init/scaffolders/agent-hooks/emitters/grok.test.ts": 67.57654199999999,
-            "src/cli/commands/init/scaffolders/subagents/index.test.ts": 49.99270800000005,
             "src/blueprint/core/validation/criteria.test.ts": 9.635125000000016,
             "src/cli/commands/session.test.ts": 662.8378339999999,
             "src/cli/commands/dash/run-registry.test.ts": 793.002083,