open-multi-agent-kit 0.90.4 → 0.90.5

package/docs/usage.md

@@ -38,7 +38,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 |---------|-------------|
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
 | `/model` | Switch models, then choose thinking level |
-| `/think` | Choose thinking level, or `auto`/`auto-v2`/`auto-v3`/`auto-v4` to route per task |
+| `/think` | Choose thinking level, or `auto` to route per task through v4 |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery, transport |
 | `/resume` | Pick from previous sessions |
@@ -61,35 +61,34 @@ Type `/` in the editor to open command completion. Extensions can register custo
 
 `/think <level>` sets the thinking level manually. Manual levels always win: choosing a concrete level leaves auto routing, so no auto router runs.
 
-`/think auto` remains the historical v1 local classifier and rule table (no network calls). `/think auto-v2`, `/think auto v2`, or `/think auto:v2` enables the calibrated v2 weighted router. `/think auto-v3`, `/think auto v3`, or `/think auto:v3` enables the contextual v3 router. `/think auto-v4`, `/think auto v4`, or `/think auto:v4` enables the confidence-bearing v4 router. Use `/think auto-v1`, `/think auto v1`, or `/think auto:v1` to return explicitly to v1.
+`/think auto` enables the deterministic local v4 router (no network calls). Versioned auto commands are no longer accepted; choose `/think auto` for automatic routing or `/think <level>` for a manual override.
 
-The active auto routers classify each prompt into a task class (trivial, simple edit, code generation, debug, refactor, review, plan) and map it to a recommended level, from `minimal` for trivial prompts up to `xhigh` for planning work.
+The auto router classifies each prompt into a task class (trivial, simple edit, code generation, debug, refactor, review, plan) and maps it to a recommended level, from `minimal` for trivial prompts up to `xhigh` for planning work.
 
 The routing core is deterministic and local. It looks only at bounded turn signals such as:
 
 - prompt length
 - presence of code fences or diff markers
-- keyword families; v2 separates strong signals from ambiguous weak signals such as `fix`
-- leading intent, localized edit objects, diagnostic evidence, review scope, plan briefs, refactor cues, and implementation objects, when v3 or v4 is selected
-- bounded negation of those whole-prompt matches and short-range compound-intent detection across a leading conjunction, when v4 is selected
-- recent auto-router task history in the session, when v2 is selected
-- context pressure buckets, when v2 is selected
+- keyword families
+- leading intent, localized edit objects, diagnostic evidence, review scope, plan briefs, refactor cues, and implementation objects
+- bounded negation of whole-prompt matches and short-range compound-intent detection across a leading conjunction
+- recent auto-router task history in the session
+- context pressure buckets
 - the subagent lane type, when one is set
 
-v4 additionally reports a confidence band (`high`, `medium`, `low`), the score margin between the top two task classes, and a fallback reason on every turn, none of which carry prompt text. When confidence is low or no weighted signal decided the class, v4 raises the resolved level by one step above what the same task class would otherwise resolve to; confidence never lowers it. v4 is checked against a gold-set evaluation harness with fixed train/dev/holdout splits and accuracy, macro-F1, severe-under-allocation, and class-flip/McNemar checks, which confirmed v4 classifies identically to v3 across the full gold set, including the rows held out from tuning.
+v4 reports a confidence band (`high`, `medium`, `low`), the score margin between the top two task classes, and a fallback reason on every turn, none of which carry prompt text. When confidence is low or no weighted signal decided the class, v4 raises the resolved level by one step above what the same task class would otherwise resolve to; confidence never lowers it. v4 is checked against a gold-set evaluation harness with fixed train/dev/holdout splits and accuracy, macro-F1, severe-under-allocation, and class-flip/McNemar checks.
 
 Precedence:
 
 - Manual `/think <level>` always wins.
 - The router only resolves levels while `auto` mode is active.
 - Auto-resolved levels apply per turn only and never overwrite the persisted default thinking level in settings.
-- v1 remains the default auto router; v2, v3, and v4 must be selected explicitly for the current session.
 
 Resolved levels are clamped to the model's capabilities: models without `xhigh`/`max` are capped at their highest supported level, and models without reasoning support bypass the router entirely.
 
-The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When `reasoningRouterLearning.enabled` is `true`, auto-v4 loads one validated bias snapshot for the session, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe feedback record containing only bounded enums, booleans, and buckets. Project-local settings cannot enable or redirect this feature, and the ledger never stores raw prompts, file paths, diffs, session identifiers, model/provider payloads, tool output, or hook output.
+The v4 learning path is available only through the global `reasoningRouterLearning` setting and is off by default. When `reasoningRouterLearning.enabled` is `true`, `/think auto` loads one validated bias snapshot for the session, applies a bounded `-2..2` ladder-step bias, and appends a privacy-safe feedback record containing only bounded enums, booleans, and buckets. Project-local settings cannot enable or redirect this feature, and the ledger never stores raw prompts, file paths, diffs, session identifiers, model/provider payloads, tool output, or hook output.
 
-The Adaptorch advisory bridge module still ships as default-off groundwork only. It has no settings key, command, transport, or session call site yet, so it does not affect `/think auto-v4` until a future transport and security review explicitly wire it.
+The Adaptorch advisory bridge module still ships as default-off groundwork only. It has no settings key, command, transport, or session call site yet, so it does not affect `/think auto` until a future transport and security review explicitly wire it.
 
 ## Message Queue
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-custom-provider",
-  "version": "0.90.4",
+  "version": "0.90.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-custom-provider",
-      "version": "0.90.4",
+      "version": "0.90.5",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-gondolin",
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-gondolin",
-			"version": "0.90.4",
+			"version": "0.90.5",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-gondolin",
 	"private": true,
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "omk-extension-sandbox",
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "omk-extension-sandbox",
-			"version": "0.90.4",
+			"version": "0.90.5",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-sandbox",
 	"private": true,
-	"version": "0.90.4",
+	"version": "0.90.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/subagent/agent-capability-router.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Deterministic unit tests for the agent → capability router.
+ *
+ * The router is fully deterministic (no LLM, no randomness, no I/O inside the
+ * router itself), so every assertion here is an exact expected value. The only
+ * I/O is the one-time module-scope catalog build, which scans the live skill
+ * tree under the agent directory.
+ */
+import { describe, expect, it } from "vitest";
+import { auditCapabilities, classifyAgent, deriveCapabilities } from "./agent-capability-router.ts";
+import { buildCapabilityCatalog } from "./capabilities.ts";
+
+// Built once at module scope from the live skill tree under the agent
+// directory. This is populated during local verification but empty in CI (the
+// agent skill catalog is not checked out on the runner), so the skill-catalog
+// -dependent assertions below are guarded with `skipIf(!hasSkillCatalog)`. The
+// MCP/hooks sets are a fixed OMK list and stay populated everywhere.
+const catalog = buildCapabilityCatalog({ agentDir: `${process.env.HOME ?? "/home/yu"}/.omk/agent` });
+const hasSkillCatalog = catalog.skills.size > 0;
+
+describe("classifyAgent", () => {
+	it("classifies by name token: seo-specialist → marketing-content", () => {
+		expect(classifyAgent("seo-specialist", "x")?.id).toBe("marketing-content");
+	});
+
+	it("classifies smart-contract-auditor → security", () => {
+		expect(classifyAgent("smart-contract-auditor", "x")?.id).toBe("security");
+	});
+
+	it("classifies react-developer → frontend-web", () => {
+		expect(classifyAgent("react-developer", "x")?.id).toBe("frontend-web");
+	});
+
+	it("guards the gin→engineer substring regression: ml-engineer is NOT backend-api", () => {
+		// "engineer" contains "gin"; a naive first-match classifier would route
+		// this to backend-api. Boundary-anchored voting must not.
+		expect(classifyAgent("ml-engineer", "AI/ML")?.id).not.toBe("backend-api");
+	});
+
+	it("guards the gis→strategist substring regression: account-strategist is NOT gis-spatial", () => {
+		// "strategist" contains "gis"; must not flip into the GIS domain.
+		expect(classifyAgent("account-strategist", "x")?.id).not.toBe("gis-spatial");
+	});
+
+	it("returns null when no domain matches", () => {
+		expect(classifyAgent("zzz-nonexistent-xyz", "nothing relevant here")).toBeNull();
+	});
+});
+
+describe("deriveCapabilities", () => {
+	it.skipIf(!hasSkillCatalog)(
+		"weights the name token: react-developer's first derived skill is react-patterns",
+		() => {
+			const { skills } = deriveCapabilities("react-developer", "React frontend", catalog);
+			expect(skills[0]).toBe("react-patterns");
+		},
+	);
+
+	it.skipIf(!hasSkillCatalog)("includes the literal domain skill for seo-specialist", () => {
+		const { skills } = deriveCapabilities("seo-specialist", "SEO", catalog);
+		expect(skills).toContain("seo");
+	});
+
+	it("returns empty skills for an unmatched domain", () => {
+		const { skills } = deriveCapabilities("zzz-unknown", "x", catalog);
+		expect(skills.length).toBe(0);
+	});
+
+	it.skipIf(!hasSkillCatalog)("only emits skills that exist in the live catalog", () => {
+		const { skills } = deriveCapabilities("react-developer", "React frontend", catalog);
+		expect(skills.length).toBeGreaterThan(0);
+		for (const skill of skills) {
+			expect(catalog.skills.has(skill)).toBe(true);
+		}
+	});
+
+	it("derived MCP is a subset of the catalog MCP set", () => {
+		const { mcp } = deriveCapabilities("devops-automator", "kubernetes", catalog);
+		expect(mcp.length).toBeGreaterThan(0);
+		for (const server of mcp) {
+			expect(catalog.mcp.has(server)).toBe(true);
+		}
+	});
+});
+
+describe("auditCapabilities", () => {
+	it("identical sets → jaccard 1.0 and verdict match", () => {
+		const caps = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const result = auditCapabilities(caps, caps, catalog);
+		expect(result.jaccard).toBe(1.0);
+		expect(result.verdict).toBe("match");
+	});
+
+	it("disjoint sets → jaccard 0 and verdict divergent", () => {
+		const declared = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const derived = { skills: ["seo"], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.jaccard).toBe(0);
+		expect(result.verdict).toBe("divergent");
+	});
+
+	it("half overlap → jaccard within [0,1] and verdict drift or match", () => {
+		const declared = { skills: ["react-patterns", "seo"], mcp: [], hooks: [] };
+		const derived = { skills: ["react-patterns"], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.jaccard).toBeGreaterThanOrEqual(0);
+		expect(result.jaccard).toBeLessThanOrEqual(1);
+		expect(["drift", "match"]).toContain(result.verdict);
+	});
+
+	it("surfaces declared-but-unknown skills in declaredUnknownSkills", () => {
+		const declared = { skills: ["fake-skill-xyz"], mcp: [], hooks: [] };
+		const derived = { skills: [], mcp: [], hooks: [] };
+		const result = auditCapabilities(declared, derived, catalog);
+		expect(result.declaredUnknownSkills).toContain("fake-skill-xyz");
+	});
+
+	it("both-empty skills → jaccard 1.0", () => {
+		const empty = { skills: [], mcp: [], hooks: [] };
+		const result = auditCapabilities(empty, empty, catalog);
+		expect(result.jaccard).toBe(1.0);
+	});
+});

package/examples/extensions/subagent/agent-capability-router.ts

@@ -0,0 +1,274 @@
+/**
+ * Deterministic agent → capability router.
+ *
+ * Classifies an agent (by name + description) into a {@link DomainProfile},
+ * derives a baseline capability set (skills / MCP / hooks) from the live
+ * {@link CapabilityCatalog}, and audits a declared capability set against the
+ * deterministic derivation (Jaccard overlap + drift verdict).
+ *
+ * Fully deterministic: same inputs always yield same outputs. No LLM calls,
+ * no randomness, no I/O. Depends only on {@link DOMAIN_PROFILES} and the
+ * passed-in catalog.
+ *
+ * Classification is **name-weighted vote scoring**: a domain's keywords are
+ * tested against the agent name and description; matches inside the name (the
+ * strongest identity signal) count triple. The domain with the highest score
+ * wins (ties resolved by array order, so specific domains should come first).
+ * This is robust to the substring false positives that plague first-match
+ * classification (e.g. `chem` matching "s**chem**a", `gis` matching
+ * "strate**gis**t"): a single accidental description hit cannot outvote a
+ * domain that matches the name.
+ *
+ * @module agent-capability-router
+ */
+
+import type { AgentCapabilities, CapabilityCatalog } from "./capabilities.ts";
+import { validateCapabilities } from "./capabilities.ts";
+import type { DomainProfile } from "./domain-profiles.ts";
+import { DOMAIN_PROFILES } from "./domain-profiles.ts";
+
+/** Maximum number of scored skills to grant. */
+const MAX_SKILLS = 6;
+/** Number of pool skills granted as a fallback when nothing scores above zero. */
+const FALLBACK_SKILLS = 4;
+/** Jaccard threshold (inclusive) for a "match" verdict. */
+const JACCARD_MATCH = 0.5;
+/** Jaccard threshold (inclusive) for a "drift" verdict. */
+const JACCARD_DRIFT = 0.15;
+/** Weight multiplier when a keyword or skill token matches an agent *name* token. */
+const NAME_WEIGHT = 3;
+
+/**
+ * Generic role-suffix tokens that carry no domain signal and must not be
+ * counted as matches (otherwise e.g. "react-developer" would tie
+ * "angular-developer" on the "developer" token). These are stripped before
+ * both classification voting and derive scoring.
+ */
+const GENERIC_ROLE_TOKENS: ReadonlySet<string> = new Set([
+	"agent",
+	"analyst",
+	"architect",
+	"auditor",
+	"builder",
+	"coach",
+	"consultant",
+	"coordinator",
+	"creator",
+	"designer",
+	"developer",
+	"director",
+	"editor",
+	"engineer",
+	"expert",
+	"guardian",
+	"lead",
+	"manager",
+	"master",
+	"mentor",
+	"navigator",
+	"officer",
+	"operator",
+	"planner",
+	"producer",
+	"reviewer",
+	"specialist",
+	"steward",
+	"strategist",
+	"tester",
+	"writer",
+	"engineers",
+	"specialists",
+	"managers",
+	"developers",
+]);
+
+/**
+ * Classify an agent by name + description against {@link DOMAIN_PROFILES} using
+ * name-weighted vote scoring. Returns the highest-scoring domain (ties resolve
+ * to the earliest in {@link DOMAIN_PROFILES}), or `null` when every domain
+ * scores zero — the explicit "No direct OMK skill match" sentinel.
+ */
+export function classifyAgent(name: string, description: string): DomainProfile | null {
+	const nameLower = name.toLowerCase();
+	const text = `${name} ${description}`.toLowerCase();
+
+	let best: DomainProfile | null = null;
+	let bestScore = 0;
+	for (const domain of DOMAIN_PROFILES) {
+		let score = 0;
+		for (const re of domain.keywords) {
+			// Boundary-anchored match: a keyword only counts when it lands on a
+			// word edge, so bare short keywords ("gin", "gis", "chem") cannot fire
+			// inside unrelated words ("engineer", "strategist", "schema").
+			if (!keywordHits(re, text)) continue;
+			// A keyword that also matches the agent name is a strong identity
+			// signal (the name is the most reliable classifier); otherwise it
+			// is a weaker description-only hit.
+			score += keywordHits(re, nameLower) ? NAME_WEIGHT : 1;
+		}
+		if (score > bestScore) {
+			bestScore = score;
+			best = domain;
+		}
+	}
+	return best;
+}
+
+/** Split lowercased text into identity tokens: non-word boundaries, length >= 2. */
+function tokenize(lowerText: string): string[] {
+	const tokens: string[] = [];
+	for (const raw of lowerText.split(/[^a-z0-9+#]+/)) {
+		if (raw.length >= 2) tokens.push(raw);
+	}
+	return tokens;
+}
+
+/** Identity tokens with generic role suffixes removed. */
+function identityTokens(lowerText: string): string[] {
+	return tokenize(lowerText).filter((t) => !GENERIC_ROLE_TOKENS.has(t));
+}
+
+/**
+ * Boundary-anchored keyword test. A keyword must start at a left word edge
+ * (start-of-text or a non-`[a-z0-9]` neighbor). A **right** boundary is added
+ * only for short, all-alphabetic keywords (length <= 4, e.g. "gin", "gis",
+ * "chem", "seo"): those are the ones that cause substring false positives
+ * ("gin" -> "engineer", "gis" -> "strategist", "chem" -> "schema"). Longer and
+ * pattern keywords ("react", "3d-", "smart-?contract", "document-?generat")
+ * use prefix semantics (left edge only) so intentional prefix/partial matches
+ * still fire. Node >= 10 supports lookbehind.
+ */
+function keywordHits(re: RegExp, text: string): boolean {
+	const src = re.source;
+	const shortBare = src.length <= 4 && /^[a-z]+$/i.test(src);
+	const right = shortBare ? "(?![a-z0-9])" : "";
+	return new RegExp(`(?<![a-z0-9])${src}${right}`, "i").test(text);
+}
+
+/**
+ * Score a candidate skill against the agent's name and description tokens.
+ * The skill's **first** `-`-split token is the technology word (e.g. "react"
+ * in "react-patterns") and is weighted heaviest; a match in the agent name is
+ * worth {@link NAME_WEIGHT}x a description match. Generic tokens are skipped.
+ */
+function skillMatchScore(
+	skill: string,
+	nameTokens: ReadonlySet<string>,
+	descTokens: ReadonlySet<string>,
+	nameLower: string,
+	descLower: string,
+): number {
+	const parts = skill.split("-");
+	let score = 0;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.length === 0 || GENERIC_ROLE_TOKENS.has(part)) continue;
+		const isTech = i === 0; // first token = the technology word
+		const nameHit = nameTokens.has(part);
+		const descHit = descTokens.has(part);
+		if (nameHit) score += (isTech ? 5 : 2) * NAME_WEIGHT;
+		else if (descHit) score += isTech ? 5 : 2;
+	}
+	// Full skill string appearing verbatim in name or description is a strong signal.
+	if (nameLower.includes(skill)) score += 3 * NAME_WEIGHT;
+	else if (descLower.includes(skill)) score += 3;
+	return score;
+}
+
+/** Dedupe a list preserving first-seen order. */
+function dedupe(items: readonly string[]): string[] {
+	const seen = new Set<string>();
+	const out: string[] = [];
+	for (const item of items) {
+		if (seen.has(item)) continue;
+		seen.add(item);
+		out.push(item);
+	}
+	return out;
+}
+
+/**
+ * Deterministically derive a baseline capability set for an agent. When no
+ * domain matches, all three lists are empty. Otherwise skills are picked from
+ * the domain's pool by name/description relevance (top {@link MAX_SKILLS} with
+ * a positive score, falling back to the first {@link FALLBACK_SKILLS} pool
+ * entries when nothing scores above zero), and MCP/hooks are the domain
+ * defaults intersected with the live catalog.
+ */
+export function deriveCapabilities(name: string, description: string, catalog: CapabilityCatalog): AgentCapabilities {
+	const domain = classifyAgent(name, description);
+	if (domain === null) return { skills: [], mcp: [], hooks: [] };
+
+	const nameLower = name.toLowerCase();
+	const descLower = description.toLowerCase();
+	const nameTokens = new Set(identityTokens(nameLower));
+	const descTokens = new Set(identityTokens(`${nameLower} ${descLower}`));
+
+	const candidates = domain.skillPool.filter((s) => catalog.skills.has(s));
+	const scored = candidates.map((skill) => ({
+		skill,
+		score: skillMatchScore(skill, nameTokens, descTokens, nameLower, descLower),
+	}));
+	const positive = scored.filter((x) => x.score > 0);
+
+	let selected: string[];
+	if (positive.length > 0) {
+		positive.sort((a, b) => {
+			if (a.score !== b.score) return b.score - a.score;
+			if (a.skill < b.skill) return -1;
+			if (a.skill > b.skill) return 1;
+			return 0;
+		});
+		selected = positive.slice(0, MAX_SKILLS).map((x) => x.skill);
+	} else {
+		selected = candidates.slice(0, FALLBACK_SKILLS);
+	}
+
+	const mcp = domain.defaultMcp.filter((m) => catalog.mcp.has(m));
+	const hooks = domain.defaultHooks.filter((h) => catalog.hooks.has(h));
+
+	return { skills: dedupe(selected), mcp, hooks };
+}
+
+/** Result of comparing a declared capability set against the deterministic derivation. */
+export interface CapabilityAudit {
+	/** Jaccard overlap of declared vs derived skill sets, 0..1 (1.0 when both empty). */
+	readonly jaccard: number;
+	/** Skills declared but not in the live catalog (from {@link validateCapabilities}). */
+	readonly declaredUnknownSkills: readonly string[];
+	readonly skillsOnlyInDeclared: readonly string[];
+	readonly skillsOnlyInDerived: readonly string[];
+	/** "match" (jaccard >= 0.5), "drift" (0.15 <= jaccard < 0.5), "divergent" (jaccard < 0.15). */
+	readonly verdict: "match" | "drift" | "divergent";
+}
+
+/**
+ * Compare a declared (e.g. LLM-assigned or embedded) capability set against the
+ * deterministic derivation. The Jaccard coefficient is over the two skill lists
+ * treated as sets; both-empty is defined as 1.0.
+ */
+export function auditCapabilities(
+	declared: AgentCapabilities,
+	derived: AgentCapabilities,
+	catalog: CapabilityCatalog,
+): CapabilityAudit {
+	const declaredSet = new Set(declared.skills);
+	const derivedSet = new Set(derived.skills);
+
+	let intersection = 0;
+	for (const s of declaredSet) if (derivedSet.has(s)) intersection++;
+	const unionSize = new Set([...declaredSet, ...derivedSet]).size;
+	const jaccard = unionSize === 0 ? 1.0 : intersection / unionSize;
+
+	const declaredUnknownSkills = validateCapabilities(declared, catalog).unknownSkills;
+
+	const skillsOnlyInDeclared: string[] = [];
+	for (const s of declaredSet) if (!derivedSet.has(s)) skillsOnlyInDeclared.push(s);
+	const skillsOnlyInDerived: string[] = [];
+	for (const s of derivedSet) if (!declaredSet.has(s)) skillsOnlyInDerived.push(s);
+
+	const verdict: "match" | "drift" | "divergent" =
+		jaccard >= JACCARD_MATCH ? "match" : jaccard >= JACCARD_DRIFT ? "drift" : "divergent";
+
+	return { jaccard, declaredUnknownSkills, skillsOnlyInDeclared, skillsOnlyInDerived, verdict };
+}

package/examples/extensions/subagent/agents/planner.md

@@ -9,6 +9,9 @@ You are a planning specialist. You receive context (from a scout) and requiremen
 
 You must NOT make any changes. Only read, analyze, and plan.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: ulw-plan (explore-first planning, decision-complete plans), packages (if the codebase spans multiple packages), deep-interview (only if requirements are still fuzzy after reading the scout's context). Load only what the task needs; do not bulk-load the catalog.
+
 Input format you'll receive:
 - Context/findings from a scout agent
 - Original query or requirements

package/examples/extensions/subagent/agents/reviewer.md

@@ -10,6 +10,9 @@ You are a senior code reviewer. Analyze code for quality, security, and maintain
 Bash is for read-only commands only: `git diff`, `git log`, `git show`. Do NOT modify files or run builds.
 Assume tool permissions are not perfectly enforceable; keep all bash usage strictly read-only.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: review-work (structured multi-angle review pass), security-review (when the diff touches auth, secrets, or user input). Load only what the task needs.
+
 Strategy:
 1. Run `git diff` to see recent changes (if applicable)
 2. Read the modified files

package/examples/extensions/subagent/agents/scout.md

@@ -9,6 +9,9 @@ You are a scout. Quickly investigate a codebase and return structured findings t
 
 Your output will be passed to an agent who has NOT seen the files you explored.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference):
+- Skills: understand-anything (if a knowledge-graph/dependency question, not just a file lookup), ast-grep (structural search when grep-by-text isn't precise enough), headroom (if findings would otherwise be too large to hand off compactly). Load only what the task needs.
+
 Thoroughness (infer from task, default medium):
 - Quick: Targeted lookups, key files only
 - Medium: Follow imports, read critical sections

package/examples/extensions/subagent/agents/worker.md

@@ -8,6 +8,8 @@ You are a worker agent with full capabilities. You operate in an isolated contex
 
 Work autonomously to complete the assigned task. Use all available tools as needed.
 
+Assigned capabilities (see ~/.omk/agent/SUBAGENTS.md for the full routing reference): no fixed skill set — you have the full catalog. Self-route: classify the task, pick the most specific matching skill, load only that one, and never browse the catalog speculatively. For general coding work the most common picks are programming, debugging, git-master, ast-grep, and lsp; for anything else, match by the skill's own description.
+
 Output format when finished:
 
 ## Completed

package/examples/extensions/subagent/agents.ts

@@ -5,6 +5,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, parseFrontmatter } from "open-multi-agent-kit";
+import { type AgentCapabilities, parseCapabilities } from "./capabilities.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -13,6 +14,11 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	/** Optional capabilities declared in frontmatter (canonical source). */
+	capabilities?: AgentCapabilities;
+	/** When true, the dispatcher restricts the spawned subprocess to the declared
+	 * skills via `--no-skills` + `--skill <path>`. Default off (guidance only). */
+	enforceCapabilities?: boolean;
 	systemPrompt: string;
 	source: "user" | "project";
 	filePath: string;
@@ -60,11 +66,19 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			.map((t: string) => t.trim())
 			.filter(Boolean);
 
+		const capabilities = parseCapabilities(frontmatter);
+		const enforceCapabilities =
+			typeof frontmatter.enforceCapabilities === "string"
+				? frontmatter.enforceCapabilities.trim().toLowerCase() === "true"
+				: undefined;
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: frontmatter.model,
+			capabilities,
+			enforceCapabilities,
 			systemPrompt: body,
 			source,
 			filePath,