ocmm 0.5.4 → 0.6.0

package/dist/hooks/config.js

@@ -7,42 +7,80 @@ import { getAgentPrompt, getCategoryPrompt, getDeepworkPrompt, isGpt56Model, pic
 import { buildSkillCommand, DEFAULT_SKILLS_ROOT, loadSharedSkills, loadV1SkillCommands } from "../intent/skill-loader.js";
 import { resolveMcpServers } from "../mcp/index.js";
 import { normalizeAgentShorthand, normalizeShorthand } from "../config/normalize.js";
+import { buildEffectiveModelRoute } from "../routing/effective-route.js";
 import { selectCatalogModel } from "../routing/model-upgrades.js";
+import { resolveEffectiveRequirement } from "../routing/resolver.js";
 import { isRecord, log } from "../shared/logger.js";
+import { expandReviewAgents, isExpandedReviewAgentDisabled } from "../review-agents/expand.js";
+import { isReviewAgentName, parseReviewAgentName } from "../review-agents/names.js";
 const COMPAT_AGENT_ALIASES = [
     { alias: "explore", target: "code-search" },
 ];
+const PRIMARY_COORDINATORS = ["orchestrator", "builder"];
+const UTILITY_LEAF_AGENTS = [
+    "quick",
+    "code-search",
+    "explore",
+    "doc-search",
+    "research",
+    "media-reader",
+];
+const READ_ONLY_UTILITY_AGENTS = [
+    "code-search",
+    "explore",
+    "doc-search",
+    "research",
+    "media-reader",
+];
+const STANDARD_WORKFLOW_SUBAGENTS = [
+    "coding",
+    "normal-task",
+    "frontend",
+    "creative",
+    "hard-reasoning",
+    "documenting",
+];
+const READ_ONLY_WORKFLOW_AGENTS = [
+    "clarifier",
+];
+const LOCAL_COORDINATORS = ["deep", "complex"];
+const SPECIALIST_EXECUTION_AGENTS = [
+    "coding",
+    "frontend",
+    "hard-reasoning",
+    "creative",
+    "documenting",
+];
+const QUESTION_ENABLED_WORKFLOW_AGENTS = ["planner", "deep", "complex", "coding", "normal-task"];
+function taskAllowlist(allowed) {
+    const rules = { "*": "deny" };
+    for (const name of allowed)
+        rules[name] = "allow";
+    return rules;
+}
 const LOCALE_GUIDANCE_TAG = "ocmm-locale-guidance";
 const LOCALE_GUIDANCE_BLOCK = new RegExp(`<${LOCALE_GUIDANCE_TAG}>[\\s\\S]*?<\\/${LOCALE_GUIDANCE_TAG}>\\s*(?:---\\s*)?`, "g");
 function fmtModel(entry) {
     const provider = entry.providers[0] ?? "";
     return provider ? `${provider}/${entry.model}` : entry.model;
 }
-function hasExplicitModelSelection(entry) {
-    if (typeof entry === "string")
-        return true;
-    if (!isRecord(entry))
+function applyAgentEntry(agentMap, agent, override, extras, registration) {
+    const current = agentMap[agent.name];
+    if (isRecord(current) && current.disable === true)
         return false;
-    return ["model", "fallbackModels", "requirement", "alias"].some((key) => entry[key] !== undefined);
-}
-function rawAgentModel(agentMap, name) {
-    const entry = agentMap[name];
-    return isRecord(entry) && typeof entry.model === "string" ? entry.model : undefined;
-}
-function applyAgentEntry(agentMap, agent, override, extras) {
     if (override?.disabled)
-        return;
+        return false;
     let chain = agent.requirement.fallbackChain;
     const description = override?.description ?? agent.description;
     if (override?.requirement?.fallbackChain?.length) {
         chain = override.requirement.fallbackChain;
     }
     if (!chain.length)
-        return;
+        return false;
     const head = chain[0];
     const modelStr = extras?.model ?? fmtModel(head);
-    const existing = isRecord(agentMap[agent.name])
-        ? agentMap[agent.name]
+    const existing = isRecord(current)
+        ? current
         : {};
     if (typeof existing.model !== "string")
         existing.model = modelStr;
@@ -56,9 +94,31 @@ function applyAgentEntry(agentMap, agent, override, extras) {
     if (extras?.promptPrefix && typeof existing.prompt === "string") {
         existing.prompt = prependPromptPrefix(existing.prompt, extras.promptPrefix);
     }
+    if (extras?.promptSuffix) {
+        const basePrompt = typeof existing.prompt === "string" ? existing.prompt : "";
+        existing.prompt = appendPromptSuffix(basePrompt, extras.promptSuffix);
+    }
+    if (registration?.tools) {
+        mergePermission(existing, Object.fromEntries(Object.entries(registration.tools).map(([name, enabled]) => [name, enabled ? "allow" : "deny"])), true);
+    }
     if (override?.permission)
         mergePermission(existing, override.permission, true);
+    if (registration) {
+        for (const key of ["skills", "temperature", "topP", "maxTokens", "thinking", "reasoningEffort"]) {
+            if (existing[key] !== undefined)
+                continue;
+            const value = registration[key];
+            if (value === undefined)
+                continue;
+            existing[key] = Array.isArray(value)
+                ? [...value]
+                : typeof value === "object" && value !== null
+                    ? structuredClone(value)
+                    : value;
+        }
+    }
     agentMap[agent.name] = existing;
+    return true;
 }
 function buildLocaleGuidance(locale) {
     const configuredLocale = locale?.trim();
@@ -86,6 +146,74 @@ function prependPromptPrefix(prompt, prefix) {
     const cleanPrefix = prefix.trim();
     return body ? `${cleanPrefix}\n\n---\n\n${body}` : cleanPrefix;
 }
+const DELEGATION_CONTRACT_TAG = "ocmm-delegation-contract";
+const DELEGATION_CONTRACT_BLOCK = new RegExp(`(?:\\n\\n---\\n\\n)?<${DELEGATION_CONTRACT_TAG}>[\\s\\S]*?<\\/${DELEGATION_CONTRACT_TAG}>\\s*`, "g");
+function appendPromptSuffix(prompt, suffix) {
+    const body = prompt.replace(DELEGATION_CONTRACT_BLOCK, "").trim();
+    const cleanSuffix = suffix.trim();
+    return body ? `${body}\n\n---\n\n${cleanSuffix}` : cleanSuffix;
+}
+const UTILITY_LEAF_AGENT_SET = new Set(UTILITY_LEAF_AGENTS);
+const STANDARD_WORKFLOW_SUBAGENT_SET = new Set(STANDARD_WORKFLOW_SUBAGENTS);
+const READ_ONLY_WORKFLOW_AGENT_SET = new Set(READ_ONLY_WORKFLOW_AGENTS);
+const LOCAL_COORDINATOR_SET = new Set(LOCAL_COORDINATORS);
+function formatTargets(names) {
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+function wrapDelegationContract(lines) {
+    return [
+        `<${DELEGATION_CONTRACT_TAG}>`,
+        "## Delegation Contract (Authoritative)",
+        ...lines,
+        "This contract overrides any skill, model calibration, generated-adapter compatibility text, or other prompt layer that suggests broader delegation.",
+        `</${DELEGATION_CONTRACT_TAG}>`,
+    ].join("\n");
+}
+function delegationContractFor(name) {
+    const readOnlyReviewRole = isReviewAgentName(name) || name === "plan-critic";
+    if (UTILITY_LEAF_AGENT_SET.has(name)) {
+        return wrapDelegationContract([
+            "This role is a utility leaf agent. Do not dispatch any subagent.",
+            "Complete the bounded assignment with direct tools and return the result to the caller.",
+        ]);
+    }
+    if (name === "planner") {
+        return wrapDelegationContract([
+            "Use direct tools first. Delegate only when direct tools are insufficient and a separate bounded research result materially improves completion.",
+            `Allowed utility targets: ${formatTargets(READ_ONLY_UTILITY_AGENTS)}.`,
+            "You may consult exactly the unsuffixed `reviewer` at most once, only for one concrete blocking architecture, security, or performance decision that repository evidence cannot settle. This is not formal plan review or final acceptance.",
+            "`quick` is forbidden. Do not dispatch `plan-critic`, any Reviewer tier (`reviewer-low`, `reviewer-high`, `reviewer-max`), any Oracle profile, implementation agents, or routine reviewer self-checks.",
+            "Return the completed plan to the caller. Formal planner dispatch, the `plan-critic` loop, review dispatch, and final acceptance review are orchestrator-owned.",
+        ]);
+    }
+    if (READ_ONLY_WORKFLOW_AGENT_SET.has(name) || readOnlyReviewRole) {
+        return wrapDelegationContract([
+            "Use direct tools first. Delegate only when direct tools are insufficient and a separate bounded research result materially improves completion.",
+            `Allowed utility targets: ${formatTargets(READ_ONLY_UTILITY_AGENTS)}.`,
+            "`quick` is forbidden because this read-only role must not modify work by proxy. Planning, review, coordination, and implementation workflow agents are also forbidden.",
+            "Return the completed plan or findings to the caller. Formal planner dispatch, the `plan-critic` loop, review dispatch, and final acceptance review are orchestrator-owned.",
+        ]);
+    }
+    if (STANDARD_WORKFLOW_SUBAGENT_SET.has(name)) {
+        return wrapDelegationContract([
+            "Use direct tools first. Delegate only when direct tools are insufficient or a separate bounded utility result materially improves completion.",
+            `Allowed utility targets: ${formatTargets(UTILITY_LEAF_AGENTS)}.`,
+            "Do not dispatch planning, review, coordination, or implementation workflow agents.",
+            "After local verification, return status and evidence to the caller. Formal planner dispatch, the `plan-critic` loop, review dispatch, and final acceptance review are orchestrator-owned.",
+        ]);
+    }
+    if (LOCAL_COORDINATOR_SET.has(name)) {
+        return wrapDelegationContract([
+            "Use direct tools first. Delegate only when the child owns a distinct bounded deliverable that materially improves completion.",
+            "Multiple steps, routine confirmation, or wanting another opinion are not sufficient.",
+            `Allowed utility targets: ${formatTargets(UTILITY_LEAF_AGENTS)}.`,
+            `Allowed specialist targets: ${formatTargets(SPECIALIST_EXECUTION_AGENTS)}.`,
+            "Do not call `orchestrator`, `builder`, `planner`, `clarifier`, `plan-critic`, any Reviewer profile (`reviewer`, `reviewer-low`, `reviewer-high`, `reviewer-max`), any Oracle profile (`oracle`, `oracle-2nd`, configured `oracle-3rd`…`oracle-9th`, and their `low`/`high`/`max` tier variants), `normal-task`, `deep`, or `complex`.",
+            "Integrate and verify child results, then return to the parent. Formal planner dispatch, the `plan-critic` loop, review dispatch, and final acceptance review are orchestrator-owned.",
+        ]);
+    }
+    return "";
+}
 function mergePermission(entry, permission, overwrite) {
     const existing = isRecord(entry.permission) ? entry.permission : {};
     const merged = { ...existing };
@@ -146,23 +274,128 @@ function categoryAsAgent(c, override) {
         requirement: override ?? c.requirement,
     };
 }
+function hasRouteRegistry(args) {
+    return args.routeRegistry !== undefined;
+}
+function requirementSourceForRoute(source) {
+    if (source === "user-config" || source === "agent-default" || source === "category-default") {
+        return source;
+    }
+    throw new Error(`unsupported route requirement source: ${source}`);
+}
+function resolveRouteRequirement(cfg, agentName) {
+    const resolved = resolveEffectiveRequirement({
+        agentName,
+        agentsConfig: cfg.agents,
+        categoriesConfig: cfg.categories,
+        disabledAgents: cfg.disabledAgents,
+    });
+    if (!resolved)
+        return null;
+    return {
+        requirement: resolved.requirement,
+        source: requirementSourceForRoute(resolved.source),
+    };
+}
+function selectRoutePrimary(args) {
+    if (args.existingModel)
+        return { model: args.existingModel, source: "existing-model" };
+    if (args.requirementSource === "user-config") {
+        return { model: fmtModel(args.requirement.fallbackChain[0]), source: "user-requirement" };
+    }
+    const catalogModel = args.allowCatalogUpgrade
+        ? selectCatalogModel(args.target, args.agentName, args.requirement)
+        : undefined;
+    if (catalogModel)
+        return { model: catalogModel, source: "catalog-upgrade" };
+    return { model: fmtModel(args.requirement.fallbackChain[0]), source: "builtin-requirement" };
+}
+function hasExplicitRouteSelection(cfg, name) {
+    return [cfg.agents?.[name], cfg.categories?.[name]].some((entry) => entry !== undefined && ["model", "fallbackModels", "requirement", "alias"].some((field) => Object.prototype.hasOwnProperty.call(entry, field)));
+}
+function hasOwnAgentEntry(cfg, name) {
+    return cfg.agents !== undefined && Object.prototype.hasOwnProperty.call(cfg.agents, name);
+}
+function isCompatAliasDisabled(alias, target, agents) {
+    return [alias, target].some((name) => agents?.[name]?.disabled === true || normalizeAgentShorthand(name, agents)?.disabled === true);
+}
+function cloneAgentMap(agentMap) {
+    return structuredClone(agentMap);
+}
+function allowCatalogUpgrade(args) {
+    if (!args.requested)
+        return false;
+    return args.registryManaged || !hasExplicitRouteSelection(args.cfg, args.agentName);
+}
+function selectedProviderCatalogModels(target, selectedModel) {
+    const separator = selectedModel.indexOf("/");
+    if (separator <= 0 || separator === selectedModel.length - 1)
+        return undefined;
+    const providers = isRecord(target.provider) ? target.provider : undefined;
+    const provider = providers?.[selectedModel.slice(0, separator)];
+    if (!isRecord(provider) || !isRecord(provider.models))
+        return undefined;
+    return new Set(Object.keys(provider.models));
+}
+function registerEffectiveRoute(args) {
+    if (!args.build)
+        return;
+    const route = buildEffectiveModelRoute({
+        selectedModel: args.primary.model,
+        requirement: args.requirement,
+        requirementSource: args.requirementSource,
+        primarySource: args.primary.source,
+        fastMode: args.build.fastMode,
+        fastModels: args.cfg.fastModels,
+        catalogModels: selectedProviderCatalogModels(args.target, args.primary.model),
+    });
+    args.build.nextRoutes.set(args.name, route);
+    const entry = args.agentMap[args.name];
+    if (isRecord(entry))
+        entry.model = route.model;
+}
 export function createConfigHandler(args) {
     return async (rawInput, _output) => {
-        args.registeredAgentModels?.clear();
-        const cfg = args.getConfig();
+        const registryManaged = hasRouteRegistry(args);
+        if (!registryManaged)
+            args.registeredAgentModels?.clear();
+        const compatibilityConfig = registryManaged ? undefined : args.getConfig();
+        const generation = registryManaged ? args.routeRegistry.beginBuild() : undefined;
         if (!isRecord(rawInput))
             return;
         const target = isRecord(rawInput.config) ? rawInput.config : rawInput;
+        const routeBuild = registryManaged
+            ? { fastMode: args.getFastMode(), nextRoutes: new Map() }
+            : undefined;
+        const cfg = compatibilityConfig ?? args.getConfig();
         const registered = registerSkillsAndCommands(target, cfg, args.skillsRoot);
         const registeredMcps = registerMcps(target, cfg, args.cwd);
         if (!cfg.registerBuiltinAgents) {
             log.info(`config: registered ${registered.skills} skills, ${registered.commands} commands, ${registeredMcps} MCPs`);
+            if (registryManaged && routeBuild && generation !== undefined) {
+                args.routeRegistry.publish(generation, routeBuild.nextRoutes);
+            }
             return;
         }
-        if (!isRecord(target.agent))
+        if (!registryManaged && !isRecord(target.agent))
             target.agent = {};
-        const agentMap = target.agent;
+        const agentMap = registryManaged
+            ? cloneAgentMap(isRecord(target.agent) ? target.agent : {})
+            : target.agent;
+        const existingModels = new Map();
+        for (const [name, raw] of Object.entries(agentMap)) {
+            if (isRecord(raw) && typeof raw.model === "string")
+                existingModels.set(name, raw.model);
+        }
         const disabled = new Set(cfg.disabledAgents ?? []);
+        for (const [name, raw] of Object.entries(agentMap)) {
+            const disabledReview = parseReviewAgentName(name) !== null && isExpandedReviewAgentDisabled(name, {
+                agents: cfg.agents,
+                disabledAgents: cfg.disabledAgents,
+            });
+            if ((disabled.has(name) || disabledReview) && isRecord(raw))
+                raw.disable = true;
+        }
         if (cfg.disableOpenCodeBuiltinAgents) {
             for (const name of ["build", "plan"]) {
                 if (!isRecord(agentMap[name]))
@@ -179,6 +412,8 @@ export function createConfigHandler(args) {
             }
         }
         for (const a of BUILTIN_AGENTS) {
+            if (parseReviewAgentName(a.name))
+                continue;
             if (disabled.has(a.name))
                 continue;
             let norm = normalizeAgentShorthand(a.name, cfg.agents);
@@ -186,27 +421,29 @@ export function createConfigHandler(args) {
             // but didn't specify a model (no requirement) and didn't set an explicit
             // alias. If there is no user entry at all, the builtin requirement stands.
             const userEntryForAgent = cfg.agents?.[a.name];
-            let inheritedDefaultAlias = false;
             if (userEntryForAgent !== undefined && !norm?.requirement?.fallbackChain?.length && a.defaultAlias && !userEntryForAgent.alias) {
                 const aliasNorm = normalizeAgentShorthand(a.defaultAlias, cfg.agents);
                 if (aliasNorm?.requirement?.fallbackChain?.length) {
                     norm = { ...norm, requirement: aliasNorm.requirement };
-                    inheritedDefaultAlias = true;
                 }
             }
-            const existingModel = rawAgentModel(agentMap, a.name);
-            const configuredRequirement = norm?.requirement?.fallbackChain?.length
-                ? norm.requirement
-                : undefined;
-            const suppressCatalog = hasExplicitModelSelection(userEntryForAgent) || inheritedDefaultAlias;
-            const catalogModel = !existingModel && !suppressCatalog
-                ? selectCatalogModel(target, a.name, a.requirement)
-                : undefined;
-            const finalModel = existingModel
-                ?? (configuredRequirement ? fmtModel(configuredRequirement.fallbackChain[0]) : undefined)
-                ?? catalogModel
-                ?? fmtModel(a.requirement.fallbackChain[0]);
-            const prompt = promptForBuiltinAgent(a, norm, cfg.workflow, finalModel);
+            const effective = resolveRouteRequirement(cfg, a.name);
+            if (!effective)
+                continue;
+            const primary = selectRoutePrimary({
+                target,
+                agentName: a.name,
+                requirement: effective.requirement,
+                requirementSource: effective.source,
+                existingModel: existingModels.get(a.name),
+                allowCatalogUpgrade: allowCatalogUpgrade({
+                    registryManaged,
+                    cfg,
+                    agentName: a.name,
+                    requested: true,
+                }),
+            });
+            const prompt = promptForBuiltinAgent(a, norm, cfg.workflow, primary.model);
             const mode = a.name === "orchestrator" || a.name === "builder"
                 ? "primary"
                 : a.name === "planner"
@@ -216,35 +453,122 @@ export function createConfigHandler(args) {
             if (prompt)
                 extras.prompt = prompt;
             extras.mode = mode;
-            extras.model = finalModel;
+            extras.model = primary.model;
             if (mode === "primary" || mode === "all") {
                 extras.promptPrefix = buildLocaleGuidance(cfg.locale);
             }
-            applyAgentEntry(agentMap, a, norm, extras);
+            const contract = delegationContractFor(a.name);
+            if (contract)
+                extras.promptSuffix = contract;
+            if (applyAgentEntry(agentMap, a, norm, extras)) {
+                registerEffectiveRoute({
+                    build: routeBuild,
+                    agentMap,
+                    target,
+                    cfg,
+                    name: a.name,
+                    requirement: effective.requirement,
+                    requirementSource: effective.source,
+                    primary,
+                });
+            }
+        }
+        for (const profile of expandReviewAgents({ agents: cfg.agents, disabledAgents: cfg.disabledAgents })) {
+            const synthetic = {
+                name: profile.name,
+                ...(profile.registration.description ? { description: profile.registration.description } : {}),
+                requirement: profile.requirement,
+                promptSource: profile.promptSource,
+            };
+            const effective = resolveRouteRequirement(cfg, profile.name) ?? {
+                requirement: profile.requirement,
+                source: "agent-default",
+            };
+            const primary = selectRoutePrimary({
+                target,
+                agentName: profile.name,
+                requirement: effective.requirement,
+                requirementSource: effective.source,
+                existingModel: existingModels.get(profile.name),
+                allowCatalogUpgrade: allowCatalogUpgrade({
+                    registryManaged,
+                    cfg,
+                    agentName: profile.name,
+                    requested: !profile.suppressCatalogUpgrade,
+                }),
+            });
+            let prompt = promptForBuiltinAgent(synthetic, { requirement: profile.requirement }, cfg.workflow, primary.model);
+            if (profile.registration.promptAppend)
+                prompt = `${prompt}\n\n${profile.registration.promptAppend.trim()}`;
+            const extras = { mode: "subagent", model: primary.model };
+            if (prompt)
+                extras.prompt = prompt;
+            const contract = delegationContractFor(profile.name);
+            if (contract)
+                extras.promptSuffix = contract;
+            if (applyAgentEntry(agentMap, synthetic, {
+                ...(profile.registration.description ? { description: profile.registration.description } : {}),
+                requirement: profile.requirement,
+                ...(profile.registration.permission ? { permission: profile.registration.permission } : {}),
+            }, extras, profile.registration)) {
+                registerEffectiveRoute({
+                    build: routeBuild,
+                    agentMap,
+                    target,
+                    cfg,
+                    name: profile.name,
+                    requirement: effective.requirement,
+                    requirementSource: effective.source,
+                    primary,
+                });
+            }
         }
         for (const c of BUILTIN_CATEGORIES) {
             if (disabled.has(c.name))
                 continue;
             const agentOverride = normalizeAgentShorthand(c.name, cfg.agents);
+            if (registryManaged && hasOwnAgentEntry(cfg, c.name) && !agentOverride?.requirement?.fallbackChain?.length) {
+                continue;
+            }
             const categoryOverride = normalizeShorthand(cfg.categories?.[c.name]);
-            const baseAgent = categoryAsAgent(c, categoryOverride?.requirement);
+            const effective = resolveRouteRequirement(cfg, c.name);
+            if (!effective)
+                continue;
+            const baseAgent = categoryAsAgent(c, effective.requirement);
             const merged = agentOverride ?? categoryOverride;
+            const primary = selectRoutePrimary({
+                target,
+                agentName: c.name,
+                requirement: effective.requirement,
+                requirementSource: effective.source,
+                existingModel: existingModels.get(c.name),
+                allowCatalogUpgrade: allowCatalogUpgrade({
+                    registryManaged,
+                    cfg,
+                    agentName: c.name,
+                    requested: true,
+                }),
+            });
             const extras = { mode: "subagent" };
-            const hasUserSelection = hasExplicitModelSelection(cfg.agents?.[c.name]) || hasExplicitModelSelection(cfg.categories?.[c.name]);
-            const existingModel = rawAgentModel(agentMap, c.name);
-            const configuredRequirement = agentOverride?.requirement ?? categoryOverride?.requirement;
-            const catalogModel = !hasUserSelection && !existingModel
-                ? selectCatalogModel(target, c.name, baseAgent.requirement)
-                : undefined;
-            const finalModel = existingModel
-                ?? (configuredRequirement ? fmtModel(configuredRequirement.fallbackChain[0]) : undefined)
-                ?? catalogModel
-                ?? fmtModel(baseAgent.requirement.fallbackChain[0]);
-            const prompt = promptForBuiltinCategory(c.name, cfg.workflow, finalModel);
+            const prompt = promptForBuiltinCategory(c.name, cfg.workflow, primary.model);
             if (prompt)
                 extras.prompt = prompt;
-            extras.model = finalModel;
-            applyAgentEntry(agentMap, baseAgent, merged, extras);
+            extras.model = primary.model;
+            const contract = delegationContractFor(c.name);
+            if (contract)
+                extras.promptSuffix = contract;
+            if (applyAgentEntry(agentMap, baseAgent, merged, extras)) {
+                registerEffectiveRoute({
+                    build: routeBuild,
+                    agentMap,
+                    target,
+                    cfg,
+                    name: c.name,
+                    requirement: effective.requirement,
+                    requirementSource: effective.source,
+                    primary,
+                });
+            }
         }
         if (cfg.agents) {
             for (const name of Object.keys(cfg.agents)) {
@@ -254,57 +578,211 @@ export function createConfigHandler(args) {
                     continue;
                 if (BUILTIN_CATEGORIES.some((c) => c.name === name))
                     continue;
+                if (parseReviewAgentName(name))
+                    continue;
                 const norm = normalizeAgentShorthand(name, cfg.agents);
                 if (!norm?.requirement?.fallbackChain?.length)
                     continue;
+                const effective = resolveRouteRequirement(cfg, name);
+                if (!effective)
+                    continue;
+                const primary = selectRoutePrimary({
+                    target,
+                    agentName: name,
+                    requirement: effective.requirement,
+                    requirementSource: effective.source,
+                    existingModel: existingModels.get(name),
+                    allowCatalogUpgrade: false,
+                });
                 const synthetic = {
                     name,
                     ...(norm.description ? { description: norm.description } : {}),
                     requirement: norm.requirement,
                 };
-                applyAgentEntry(agentMap, synthetic, norm);
+                const registeredAgent = applyAgentEntry(agentMap, synthetic, norm, { model: primary.model });
+                if (registeredAgent && !COMPAT_AGENT_ALIASES.some((entry) => entry.alias === name)) {
+                    registerEffectiveRoute({
+                        build: routeBuild,
+                        agentMap,
+                        target,
+                        cfg,
+                        name,
+                        requirement: effective.requirement,
+                        requirementSource: effective.source,
+                        primary,
+                    });
+                }
             }
         }
-        registerCompatAgentAliases(agentMap, disabled);
+        if (registryManaged && cfg.categories) {
+            for (const name of Object.keys(cfg.categories)) {
+                if (disabled.has(name))
+                    continue;
+                if (BUILTIN_AGENTS.some((a) => a.name === name))
+                    continue;
+                if (BUILTIN_CATEGORIES.some((c) => c.name === name))
+                    continue;
+                if (hasOwnAgentEntry(cfg, name))
+                    continue;
+                const agentOverride = normalizeAgentShorthand(name, cfg.agents);
+                const categoryOverride = normalizeShorthand(cfg.categories[name]);
+                if (!agentOverride?.requirement?.fallbackChain?.length && !categoryOverride?.requirement?.fallbackChain?.length) {
+                    continue;
+                }
+                const effective = resolveRouteRequirement(cfg, name);
+                if (!effective)
+                    continue;
+                const primary = selectRoutePrimary({
+                    target,
+                    agentName: name,
+                    requirement: effective.requirement,
+                    requirementSource: effective.source,
+                    existingModel: existingModels.get(name),
+                    allowCatalogUpgrade: false,
+                });
+                const synthetic = {
+                    name,
+                    ...(agentOverride?.description ?? categoryOverride?.description
+                        ? { description: agentOverride?.description ?? categoryOverride?.description }
+                        : {}),
+                    requirement: effective.requirement,
+                };
+                const merged = agentOverride?.requirement ? agentOverride : categoryOverride;
+                if (applyAgentEntry(agentMap, synthetic, merged, { mode: "subagent", model: primary.model })) {
+                    registerEffectiveRoute({
+                        build: routeBuild,
+                        agentMap,
+                        target,
+                        cfg,
+                        name,
+                        requirement: effective.requirement,
+                        requirementSource: effective.source,
+                        primary,
+                    });
+                }
+            }
+        }
+        registerCompatAgentAliases(agentMap, disabled, cfg.agents, registryManaged);
         registerDefaultPermissions(target, agentMap);
-        for (const [name, raw] of Object.entries(agentMap)) {
-            if (isRecord(raw) && typeof raw.model === "string") {
-                args.registeredAgentModels?.set(name, raw.model);
+        for (const { alias, target: compatTarget } of COMPAT_AGENT_ALIASES) {
+            if (!routeBuild || disabled.has(alias) || disabled.has(compatTarget) || isCompatAliasDisabled(alias, compatTarget, cfg.agents))
+                continue;
+            const currentTarget = agentMap[compatTarget];
+            const aliasEntry = agentMap[alias];
+            const targetRoute = routeBuild.nextRoutes.get(compatTarget);
+            const effective = resolveRouteRequirement(cfg, alias);
+            if (!isRecord(currentTarget)
+                || currentTarget.disable === true
+                || !isRecord(aliasEntry)
+                || aliasEntry.disable === true
+                || typeof aliasEntry.model !== "string"
+                || !effective)
+                continue;
+            const explicitAliasRequirement = normalizeAgentShorthand(alias, cfg.agents)?.requirement;
+            const primary = existingModels.has(alias)
+                ? { model: aliasEntry.model, source: "existing-model" }
+                : explicitAliasRequirement
+                    ? { model: aliasEntry.model, source: "user-requirement" }
+                    : { model: aliasEntry.model, source: targetRoute?.primarySource ?? "builtin-requirement" };
+            registerEffectiveRoute({
+                build: routeBuild,
+                agentMap,
+                target,
+                cfg,
+                name: alias,
+                requirement: effective.requirement,
+                requirementSource: effective.source,
+                primary,
+            });
+        }
+        if (!registryManaged) {
+            for (const [name, raw] of Object.entries(agentMap)) {
+                if (isRecord(raw) && typeof raw.model === "string") {
+                    args.registeredAgentModels?.set(name, raw.model);
+                }
             }
         }
         log.info(`config: registered ${Object.keys(agentMap).length} agents (built-in + categories + user), ${registered.skills} skills, ${registered.commands} commands, ${registeredMcps} MCPs`);
+        if (registryManaged && routeBuild && generation !== undefined && args.routeRegistry.publish(generation, routeBuild.nextRoutes)) {
+            target.agent = agentMap;
+        }
     };
 }
 function registerDefaultPermissions(target, agentMap) {
     const topLevel = isRecord(target.permission) ? target.permission : {};
     target.permission = topLevel;
     mergePermission(target, { webfetch: "allow", external_directory: "allow", task: "deny" }, false);
-    for (const name of ["orchestrator", "builder", "planner", "deep", "complex", "coding", "normal-task"]) {
+    for (const name of PRIMARY_COORDINATORS) {
         const entry = agentMap[name];
         if (isRecord(entry))
             mergePermission(entry, { task: "allow", question: "allow", "task_*": "allow" }, false);
     }
-    for (const name of ["reviewer", "oracle", "oracle-high", "doc-search", "code-search", "explore", "media-reader", "clarifier", "plan-critic"]) {
+    for (const name of STANDARD_WORKFLOW_SUBAGENTS) {
+        const entry = agentMap[name];
+        if (isRecord(entry))
+            mergePermission(entry, { task: taskAllowlist(UTILITY_LEAF_AGENTS) }, false);
+    }
+    const planner = agentMap.planner;
+    if (isRecord(planner)) {
+        mergePermission(planner, { task: taskAllowlist([...READ_ONLY_UTILITY_AGENTS, "reviewer"]) }, false);
+    }
+    for (const name of READ_ONLY_WORKFLOW_AGENTS) {
+        const entry = agentMap[name];
+        if (isRecord(entry))
+            mergePermission(entry, { task: taskAllowlist(READ_ONLY_UTILITY_AGENTS) }, false);
+    }
+    for (const [name, entry] of Object.entries(agentMap)) {
+        if (isRecord(entry) && (isReviewAgentName(name) || name === "plan-critic")) {
+            mergePermission(entry, { task: taskAllowlist(READ_ONLY_UTILITY_AGENTS) }, false);
+        }
+    }
+    for (const name of LOCAL_COORDINATORS) {
+        const entry = agentMap[name];
+        if (isRecord(entry)) {
+            mergePermission(entry, {
+                task: taskAllowlist([...UTILITY_LEAF_AGENTS, ...SPECIALIST_EXECUTION_AGENTS]),
+            }, false);
+        }
+    }
+    for (const name of UTILITY_LEAF_AGENTS) {
         const entry = agentMap[name];
         if (isRecord(entry))
             mergePermission(entry, { task: "deny" }, false);
     }
+    for (const name of QUESTION_ENABLED_WORKFLOW_AGENTS) {
+        const entry = agentMap[name];
+        if (isRecord(entry))
+            mergePermission(entry, { question: "allow" }, false);
+    }
     const docSearch = agentMap["doc-search"];
     if (isRecord(docSearch))
         mergePermission(docSearch, { "grep_app_*": "allow" }, false);
 }
-function registerCompatAgentAliases(agentMap, disabled) {
+function registerCompatAgentAliases(agentMap, disabled, agents, registryManaged) {
     for (const { alias, target } of COMPAT_AGENT_ALIASES) {
-        if (disabled.has(alias) || disabled.has(target))
+        if (disabled.has(alias) || disabled.has(target) || isCompatAliasDisabled(alias, target, agents)) {
+            if (registryManaged)
+                delete agentMap[alias];
             continue;
+        }
         const source = agentMap[target];
-        if (!isRecord(source))
+        if (!isRecord(source) || source.disable === true) {
+            if (registryManaged)
+                delete agentMap[alias];
             continue;
+        }
         const existing = isRecord(agentMap[alias]) ? agentMap[alias] : {};
+        if (existing.disable === true)
+            continue;
         const aliasEntry = { ...source, ...existing };
         if (typeof aliasEntry.description !== "string") {
             aliasEntry.description = `Compatibility alias for @${target}.`;
         }
+        const contract = delegationContractFor(alias);
+        if (contract) {
+            const basePrompt = typeof aliasEntry.prompt === "string" ? aliasEntry.prompt : "";
+            aliasEntry.prompt = appendPromptSuffix(basePrompt, contract);
+        }
         agentMap[alias] = aliasEntry;
     }
 }