@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/themes/tokens.ts

@@ -0,0 +1,218 @@
+/**
+ * Page theme token contract: the dashboard token names that HTML pages
+ * (design version 2) expose.
+ *
+ * A page's look comes only from these custom properties. Presets, per-page
+ * overrides and imported themes all resolve to this set, so one switch
+ * restyles the whole page. Sidebar, action, peer, type-scale and easing
+ * tokens are dashboard-only and stay out of the contract.
+ */
+
+/** Color tokens: one value per mode. */
+export const PAGE_THEME_COLOR_TOKENS = [
+  "--color-background",
+  "--color-foreground",
+  "--color-card",
+  "--color-card-foreground",
+  "--color-surface",
+  "--color-popover",
+  "--color-popover-foreground",
+  "--color-primary",
+  "--color-primary-foreground",
+  "--color-secondary",
+  "--color-secondary-foreground",
+  "--color-muted",
+  "--color-muted-foreground",
+  "--color-accent",
+  "--color-accent-foreground",
+  "--color-destructive",
+  "--color-destructive-foreground",
+  "--color-border",
+  "--color-border-subtle",
+  "--color-input",
+  "--color-ring",
+  "--color-chart-1",
+  "--color-chart-2",
+  "--color-chart-3",
+  "--color-chart-4",
+  "--color-chart-5",
+  "--color-status-success",
+  "--color-status-success-strong",
+  "--color-status-success-foreground",
+  "--color-status-active",
+  "--color-status-active-strong",
+  "--color-status-active-foreground",
+  "--color-status-error",
+  "--color-status-error-strong",
+  "--color-status-error-foreground",
+  "--color-status-info",
+  "--color-status-info-strong",
+  "--color-status-info-foreground",
+  "--color-status-pending",
+  "--color-status-pending-strong",
+  "--color-status-pending-foreground",
+  "--color-status-warning",
+  "--color-status-warning-strong",
+  "--color-status-warning-foreground",
+  "--color-status-paused",
+  "--color-status-paused-strong",
+  "--color-status-paused-foreground",
+  "--color-status-neutral",
+  "--color-status-neutral-strong",
+  "--color-status-neutral-foreground",
+  "--color-status-success-solid",
+  "--color-status-active-solid",
+] as const;
+
+/** Font and radius tokens: one value for both modes. */
+export const PAGE_THEME_SHARED_TOKENS = [
+  "--font-sans",
+  "--font-mono",
+  "--radius-sm",
+  "--radius-md",
+  "--radius-lg",
+  "--radius-xl",
+] as const;
+
+export const PAGE_THEME_TOKENS = [...PAGE_THEME_COLOR_TOKENS, ...PAGE_THEME_SHARED_TOKENS] as const;
+
+export type PageThemeToken = (typeof PAGE_THEME_TOKENS)[number];
+export type PageThemeTokenValues = Partial<Record<PageThemeToken, string>>;
+export type PageThemeTokens = { light: PageThemeTokenValues; dark: PageThemeTokenValues };
+
+type PageThemeColorToken = (typeof PAGE_THEME_COLOR_TOKENS)[number];
+type PageThemeSharedToken = (typeof PAGE_THEME_SHARED_TOKENS)[number];
+
+/** Hive values from the light `@theme` block of `apps/ui/src/styles/globals.css`. */
+const HIVE_SHARED_TOKENS: Record<PageThemeSharedToken, string> = {
+  "--font-sans": '"Space Grotesk", sans-serif',
+  "--font-mono": '"Space Mono", monospace',
+  "--radius-sm": "0.375rem",
+  "--radius-md": "0.5rem",
+  "--radius-lg": "0.625rem",
+  "--radius-xl": "0.625rem",
+};
+
+const HIVE_LIGHT_COLORS: Record<PageThemeColorToken, string> = {
+  "--color-background": "oklch(1 0 0)",
+  "--color-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-card": "oklch(1 0 0)",
+  "--color-card-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-surface": "oklch(0.985 0.0015 286)",
+  "--color-popover": "oklch(1 0 0)",
+  "--color-popover-foreground": "oklch(0.141 0.005 285.823)",
+  "--color-primary": "oklch(0.555 0.163 48.998)",
+  "--color-primary-foreground": "oklch(0.985 0 0)",
+  "--color-secondary": "oklch(0.967 0.001 286.375)",
+  "--color-secondary-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-muted": "oklch(0.967 0.001 286.375)",
+  "--color-muted-foreground": "oklch(0.552 0.016 285.938)",
+  "--color-accent": "oklch(0.943 0.003 286.375)",
+  "--color-accent-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-destructive": "oklch(0.577 0.245 27.325)",
+  "--color-destructive-foreground": "oklch(0.985 0 0)",
+  "--color-border": "oklch(0.92 0.004 286.32)",
+  "--color-border-subtle": "oklch(0.945 0.003 286)",
+  "--color-input": "oklch(0.92 0.004 286.32)",
+  "--color-ring": "oklch(0.555 0.163 48.998)",
+  "--color-chart-1": "oklch(0.646 0.222 41.116)",
+  "--color-chart-2": "oklch(0.6 0.118 184.704)",
+  "--color-chart-3": "oklch(0.398 0.07 227.392)",
+  "--color-chart-4": "oklch(0.828 0.189 84.429)",
+  "--color-chart-5": "oklch(0.769 0.188 70.08)",
+  "--color-status-success": "oklch(0.74 0.1 163)",
+  "--color-status-success-strong": "oklch(0.5 0.09 163)",
+  "--color-status-success-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-active": "oklch(0.81 0.11 75)",
+  "--color-status-active-strong": "oklch(0.55 0.1 68)",
+  "--color-status-active-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-error": "oklch(0.72 0.12 25)",
+  "--color-status-error-strong": "oklch(0.51 0.14 25)",
+  "--color-status-error-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-info": "oklch(0.74 0.09 235)",
+  "--color-status-info-strong": "oklch(0.5 0.09 240)",
+  "--color-status-info-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-pending": "oklch(0.84 0.1 95)",
+  "--color-status-pending-strong": "oklch(0.55 0.09 90)",
+  "--color-status-pending-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-warning": "oklch(0.76 0.11 55)",
+  "--color-status-warning-strong": "oklch(0.53 0.11 50)",
+  "--color-status-warning-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-paused": "oklch(0.71 0.1 262)",
+  "--color-status-paused-strong": "oklch(0.5 0.1 262)",
+  "--color-status-paused-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-neutral": "oklch(0.62 0.014 286)",
+  "--color-status-neutral-strong": "oklch(0.48 0.014 286)",
+  "--color-status-neutral-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-success-solid": "oklch(0.627 0.194 149.2)",
+  "--color-status-active-solid": "oklch(0.666 0.179 58.318)",
+};
+
+const HIVE_DARK_COLORS: Record<PageThemeColorToken, string> = {
+  "--color-background": "oklch(0.141 0.005 285.823)",
+  "--color-foreground": "oklch(0.985 0 0)",
+  "--color-card": "oklch(0.21 0.006 285.885)",
+  "--color-card-foreground": "oklch(0.985 0 0)",
+  "--color-surface": "oklch(0.185 0.006 286)",
+  "--color-popover": "oklch(0.21 0.006 285.885)",
+  "--color-popover-foreground": "oklch(0.985 0 0)",
+  "--color-primary": "oklch(0.769 0.188 70.08)",
+  "--color-primary-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-secondary": "oklch(0.274 0.006 286.033)",
+  "--color-secondary-foreground": "oklch(0.985 0 0)",
+  "--color-muted": "oklch(0.274 0.006 286.033)",
+  "--color-muted-foreground": "oklch(0.705 0.015 286.067)",
+  "--color-accent": "oklch(0.274 0.006 286.033)",
+  "--color-accent-foreground": "oklch(0.985 0 0)",
+  "--color-destructive": "oklch(0.704 0.191 22.216)",
+  "--color-destructive-foreground": "oklch(0.985 0 0)",
+  "--color-border": "oklch(1 0 0 / 10%)",
+  "--color-border-subtle": "oklch(1 0 0 / 8%)",
+  "--color-input": "oklch(1 0 0 / 15%)",
+  "--color-ring": "oklch(0.769 0.188 70.08)",
+  "--color-chart-1": "oklch(0.488 0.243 264.376)",
+  "--color-chart-2": "oklch(0.696 0.17 162.48)",
+  "--color-chart-3": "oklch(0.769 0.188 70.08)",
+  "--color-chart-4": "oklch(0.627 0.265 303.9)",
+  "--color-chart-5": "oklch(0.645 0.246 16.439)",
+  "--color-status-success": "oklch(0.78 0.1 163)",
+  "--color-status-success-strong": "oklch(0.78 0.1 163)",
+  "--color-status-success-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-active": "oklch(0.84 0.1 80)",
+  "--color-status-active-strong": "oklch(0.84 0.1 80)",
+  "--color-status-active-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-error": "oklch(0.74 0.11 22)",
+  "--color-status-error-strong": "oklch(0.74 0.11 22)",
+  "--color-status-error-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-info": "oklch(0.78 0.09 235)",
+  "--color-status-info-strong": "oklch(0.78 0.09 235)",
+  "--color-status-info-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-pending": "oklch(0.86 0.09 95)",
+  "--color-status-pending-strong": "oklch(0.86 0.09 95)",
+  "--color-status-pending-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-warning": "oklch(0.79 0.1 55)",
+  "--color-status-warning-strong": "oklch(0.79 0.1 55)",
+  "--color-status-warning-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-paused": "oklch(0.74 0.09 260)",
+  "--color-status-paused-strong": "oklch(0.74 0.09 260)",
+  "--color-status-paused-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-neutral": "oklch(0.72 0.012 286)",
+  "--color-status-neutral-strong": "oklch(0.72 0.012 286)",
+  "--color-status-neutral-foreground": "oklch(0.21 0.006 285.885)",
+  "--color-status-success-solid": "oklch(0.723 0.219 149.6)",
+  "--color-status-active-solid": "oklch(0.769 0.188 70.08)",
+};
+
+/**
+ * Full Hive values for every contract token, copied from the light `@theme`
+ * and `.dark` blocks of `apps/ui/src/styles/globals.css` (keep in sync;
+ * `themes-presets.test.ts` fails on drift). The shared font and radius
+ * tokens come from the light block and apply to both modes.
+ */
+export const HIVE_PAGE_TOKENS: {
+  light: Record<PageThemeToken, string>;
+  dark: Record<PageThemeToken, string>;
+} = {
+  light: { ...HIVE_LIGHT_COLORS, ...HIVE_SHARED_TOKENS },
+  dark: { ...HIVE_DARK_COLORS, ...HIVE_SHARED_TOKENS },
+};

package/src/tools/app-upsert.ts

@@ -24,7 +24,7 @@ export const registerAppUpsertTool = (server: McpServer) => {
     {
       title: "Create or update an app",
       description:
-        "Stores a schema-backed app definition with models, queries/actions, pages, reusable elements, optional userConfig fields, and an optional top-level theme (a dashboard preset slug for the app's canvas — hive (stock; omit to inherit the viewer's theme), meadow, iris, rose, cobalt, ember, carbon, plus the classic presets github, vscode, material, solarized, tokyo, monokai, gruvbox, catppuccin; viewers can override it per-user; unknown slugs degrade to the viewer's dashboard theme), then returns its dashboard URL. userConfig is versioned schema only; each user's values are stored separately, survive rollback, and schema changes are always compatible. Pages may bind a declared field read-only at exactly /user/<field>; pure and bound reusable elements must receive that value through a prop. Elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. Zero-model pure-UI apps are valid. Pass appId to update; breaking a referenced export is blocked by the compatibility gate unless forceElementBreak explicitly names it.",
+        "Stores a schema-backed app definition with models, queries/actions, pages, reusable elements, optional userConfig fields, and an optional top-level theme (a dashboard preset slug for the app's canvas: hive (stock; omit to inherit the viewer's theme), meadow, iris, rose, cobalt, ember, carbon, paper (the warm editorial paper look), plus the classic presets github, vscode, material, solarized, tokyo, monokai, gruvbox, catppuccin; viewers can override it per-user; unknown slugs degrade to the viewer's dashboard theme), then returns its dashboard URL. userConfig is versioned schema only; each user's values are stored separately, survive rollback, and schema changes are always compatible. Pages may bind a declared field read-only at exactly /user/<field>; pure and bound reusable elements must receive that value through a prop. Elements are private by default: pure elements read declared props, allow $item/$index inside repeats, may expose one leaf ElementSlot, and cannot invoke actions; bound elements may use the defining app's queries/actions, while exported bound elements cannot navigate. Prop kinds include enum with a required non-empty enum values array. Pages or elements reuse them with literal ElementRef targets, and cross-app refs require export: true. Zero-model pure-UI apps are valid. Pass appId to update; breaking a referenced export is blocked by the compatibility gate unless forceElementBreak explicitly names it.",
       annotations: { destructiveHint: false },
       inputSchema: z.object({
         name: z.string().min(1).describe("Human-readable app name."),

package/src/tools/create-page.ts

@@ -12,6 +12,10 @@
  * the title slugifies to empty (e.g. all symbols), fall back to the
  * generated page id.
  *
+ * Design fields: `theme`, `themeTokens` and `designVersion` set how an HTML
+ * page is styled. A new page gets designVersion 2. On an upsert, an omitted
+ * field keeps the stored value, and `null` clears `theme` / `themeTokens`.
+ *
  * Architecture note: this tool runs on the API server (per
  * `src/server.ts:155`+ pattern) and accesses `src/be/db` directly. The
  * worker-side DB-boundary invariant doesn't apply because `src/tools/*`
@@ -23,9 +27,18 @@ import { authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import { createPage, getPage, getPageBySlug, updatePage } from "@/be/db";
 import { getPageEditCounter } from "@/be/db/page-versions";
+import { classAttributeValues, countColorLiterals } from "@/pages/color-literals";
 import { snapshotPage } from "@/pages/version";
+import { readThemeFields } from "@/themes/page-fields";
+import { PAGE_THEME_COLOR_TOKENS } from "@/themes/tokens";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
-import { AssetKeySchema, PageAuthModeSchema, PageContentTypeSchema } from "@/types";
+import {
+  AssetKeySchema,
+  type Page,
+  PageAuthModeSchema,
+  PageContentTypeSchema,
+  PageThemeTokensInputSchema,
+} from "@/types";
 import { getAppUrl, getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Same slugifier used by the HTTP createPage handler. */
@@ -46,6 +59,26 @@ function getAppBaseUrl(): string {
   return getAppUrl();
 }
 
+/** A `swarm-` primitive class inside one class attribute value. */
+const SWARM_CLASS = /(?:^|\s)swarm-/;
+const COLOR_TOKEN_REFERENCE = /var\(\s*--color-/i;
+const PAGE_COLOR_TOKENS: ReadonlySet<string> = new Set<string>(PAGE_THEME_COLOR_TOKENS);
+
+/** The body uses a `swarm-` class or a `var(--color-...)` token, which only design version 2 styles. */
+function bodyUsesDesignSystem(html: string): boolean {
+  return (
+    COLOR_TOKEN_REFERENCE.test(html) ||
+    classAttributeValues(html).some((value) => SWARM_CLASS.test(value))
+  );
+}
+
+/** The stored overrides set light colors and no dark colors, so dark mode keeps the preset's colors. */
+function hasLightOnlyColors(tokens: Page["themeTokens"]): boolean {
+  if (!tokens) return false;
+  const isColor = (name: string) => PAGE_COLOR_TOKENS.has(name);
+  return Object.keys(tokens.light).some(isColor) && !Object.keys(tokens.dark).some(isColor);
+}
+
 export const registerCreatePageTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "create_page",
@@ -56,7 +89,15 @@ export const registerCreatePageTool = (server: McpServer) => {
         "Calls are upsert-by-(agent, slug): if you previously created a page " +
         "with the same slug, its prior state is snapshotted and the row is " +
         "updated. Use this for static reports, dashboards, or JSON action " +
-        "specs that don't need a long-lived process.",
+        "specs that don't need a long-lived process. " +
+        "HTML pages use the swarm design system (designVersion 2): theme " +
+        "tokens such as var(--color-primary), the swarm-* primitives, and " +
+        "Tailwind v4 utilities such as bg-card and text-muted-foreground. " +
+        "Set `theme` to a preset id or pass `themeTokens` (a token map, or a " +
+        'CSS variable block with format "css") to restyle the whole page. ' +
+        "Do not hardcode colors: inside the dashboard the page follows the " +
+        "viewer's theme and dark mode. Pages created before designVersion 2 " +
+        "keep the old look; pass designVersion: 2 when you rewrite one.",
       annotations: { destructiveHint: false },
       inputSchema: z.object({
         key: AssetKeySchema.optional().describe(
@@ -99,6 +140,27 @@ export const registerCreatePageTool = (server: McpServer) => {
           .describe(
             "Declared credential needs for JSON pages (renderer ignores for v1 — reserved for follow-up).",
           ),
+        theme: z
+          .string()
+          .nullable()
+          .optional()
+          .describe(
+            "Theme preset id that restyles the whole page, for example paper, github or hive. An unknown id returns an error that lists every preset. Omit to follow the viewer's theme (on update, to keep the stored one). Pass null to clear it.",
+          ),
+        themeTokens: PageThemeTokensInputSchema.nullable()
+          .optional()
+          .describe(
+            'Per-page token overrides, applied on top of the preset. Send { light, dark } maps of token name to CSS value (for example { light: { "--color-primary": "oklch(0.55 0.2 260)" } }), or { format: "css", css } with a CSS variable block (:root, .dark, @theme) as shadcn, tweakcn and Tailwind v4 export it. Stored normalized. Names outside the token contract, and values that reference a variable outside it, are ignored and reported in the result. Replaces the stored overrides. Omit to keep them on update. Pass null to clear them.',
+          ),
+        designVersion: z
+          .number()
+          .int()
+          .min(1)
+          .max(2)
+          .optional()
+          .describe(
+            "Design system version. 2 is the swarm design system and the default for new pages. 1 is the original look that older pages keep. Omit on update to keep the stored value.",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
@@ -107,6 +169,11 @@ export const registerCreatePageTool = (server: McpServer) => {
         version: z.number().optional(),
         app_url: z.string().optional(),
         api_url: z.string().optional(),
+        designVersion: z.number().optional(),
+        ignoredTokens: z.array(z.string()).optional(),
+        colorLiteralCount: z.number().optional(),
+        usesDesignSystem: z.boolean().optional(),
+        lightOnlyColors: z.boolean().optional(),
       }),
     },
     async (input, requestInfo, _meta) => {
@@ -115,6 +182,9 @@ export const registerCreatePageTool = (server: McpServer) => {
         return toolErr(msg);
       }
 
+      const themeFields = readThemeFields(input);
+      if ("error" in themeFields) return toolErr(themeFields.error);
+
       const slug = input.slug ?? slugify(input.title);
       const finalSlug = slug || "page"; // Fallback if title slugifies to empty.
 
@@ -167,6 +237,10 @@ export const registerCreatePageTool = (server: McpServer) => {
           passwordHash: passwordHash ?? null,
           body: input.body,
           needsCredentials: needsCredentialsNames ?? null,
+          // Omitted design fields keep the stored values.
+          theme: themeFields.theme,
+          themeTokens: themeFields.themeTokens,
+          designVersion: input.designVersion,
         });
         if (!updated) {
           const msg = `Failed to update existing page ${existing.id}.`;
@@ -188,6 +262,9 @@ export const registerCreatePageTool = (server: McpServer) => {
             passwordHash,
             body: input.body,
             needsCredentials: needsCredentialsNames,
+            theme: themeFields.theme,
+            themeTokens: themeFields.themeTokens,
+            designVersion: input.designVersion,
           });
           id = created.id;
         } catch (err) {
@@ -209,17 +286,46 @@ export const registerCreatePageTool = (server: McpServer) => {
       const appUrl = `${getAppBaseUrl()}/pages/${id}`;
       const version = await getPageEditCounter(id);
 
-      return toolOk(`Page "${input.title}" saved (slug=${finalSlug}, version=${version}).`, {
-        details: `API: ${apiUrl}\n  App: ${appUrl}`,
-        data: {
-          yourAgentId: requestInfo.agentId,
-          id,
-          key: fresh.key,
-          version,
-          app_url: appUrl,
-          api_url: apiUrl,
+      // Judged on the saved page, so an upsert that keeps an older design
+      // version is judged by the version it keeps. The NUDGES entry for this
+      // tool reads these flags. Only HTML pages get the design system head.
+      const designFlags =
+        fresh.contentType === "text/html"
+          ? {
+              usesDesignSystem:
+                typeof input.theme === "string" ||
+                Boolean(input.themeTokens) ||
+                bodyUsesDesignSystem(fresh.body),
+              lightOnlyColors: hasLightOnlyColors(fresh.themeTokens),
+              ...(fresh.designVersion >= 2
+                ? { colorLiteralCount: countColorLiterals(fresh.body) }
+                : {}),
+            }
+          : {};
+      const { ignored } = themeFields;
+
+      return toolOk(
+        `Page "${input.title}" saved (slug=${finalSlug}, version=${version}, designVersion=${fresh.designVersion}).` +
+          (ignored.length > 0
+            ? " Some theme tokens were ignored (outside the page token contract or referencing a variable outside it)."
+            : ""),
+        {
+          details:
+            `API: ${apiUrl}\n  App: ${appUrl}` +
+            (ignored.length > 0 ? `\n  Ignored theme tokens: ${ignored.join(", ")}` : ""),
+          data: {
+            yourAgentId: requestInfo.agentId,
+            id,
+            key: fresh.key,
+            version,
+            app_url: appUrl,
+            api_url: apiUrl,
+            designVersion: fresh.designVersion,
+            ...(ignored.length > 0 ? { ignoredTokens: ignored } : {}),
+            ...designFlags,
+          },
         },
-      });
+      );
     },
   );
 };

package/src/tools/send-task.ts

@@ -5,9 +5,7 @@ import { resolveTaskAuditUserId } from "@/be/audit-user";
 import {
   createTaskExtended,
   extensionAgentAssignmentError,
-  findCompletedTaskInThread,
   findExistingLinearTrackerContextWork,
-  findRecentCancelledTaskInThread,
   getActiveTaskCount,
   getAgentById,
   getDbClient,
@@ -23,6 +21,10 @@ import { repointTrackerSyncBySwarmId } from "@/be/db-queries/tracker";
 import { explicitModelErrorForAgent } from "@/be/model-validation";
 import { applyPreTaskCreate } from "@/extensions/apply-task-create";
 import { can } from "@/rbac";
+import {
+  evaluateFollowUpRedelegation,
+  followUpThreadForSourceTask,
+} from "@/tasks/follow-up-redelegation-guard";
 import { checkSlackRoutingCoherence } from "@/tasks/slack-routing";
 import { findDuplicateTask } from "@/tools/task-dedup";
 import { ownerCtx, type ToolCtx } from "@/tools/task-tool-ctx";
@@ -163,7 +165,13 @@ export const sendTaskInputSchema = z
       .boolean()
       .default(false)
       .describe(
-        "If true, skip duplicate detection and create the task even if a similar one exists.",
+        "If true, skip duplicate detection and create the task even if a similar one exists. Does not bypass the follow-up re-delegation guard; see allowRedelegation.",
+      ),
+    allowRedelegation: z
+      .boolean()
+      .default(false)
+      .describe(
+        "Only matters when you call send-task from a follow-up task in a Slack thread. Such a dispatch is blocked when it repeats a task already completed in that thread (same-work rule, unless a task there was cancelled or failed after that completion), or when you already dispatched 10 tasks into the thread in the last 6 hours (loop-cap rule). Set true to dispatch anyway; the override is logged. Use it only for deliberate re-runs or long chains, never to retry a block you have not read.",
       ),
     slackChannelId: z
       .string()
@@ -292,6 +300,7 @@ export async function sendTaskHandler(
     effort,
     profile,
     allowDuplicate,
+    allowRedelegation,
     slackChannelId,
     slackThreadTs,
     slackUserId,
@@ -316,6 +325,7 @@ export async function sendTaskHandler(
   const requestedLeadOnly = ctx.kind === "user" ? false : leadOnly;
   const requestedCapabilities = ctx.kind === "user" ? undefined : requiredCapabilities;
   const requestedAllowDuplicate = ctx.kind === "user" ? false : allowDuplicate;
+  const requestedAllowRedelegation = ctx.kind === "user" ? false : allowRedelegation;
   const requestedOverrideSlackContext = ctx.kind === "user" ? false : overrideSlackContext;
 
   // Defense in depth for direct TypeScript callers that bypass MCP schema parsing.
@@ -572,7 +582,9 @@ export async function sendTaskHandler(
   // Every read in this handler releases the FIFO lock, so two concurrent
   // send-task calls with the same creator and text otherwise both pass the
   // guards and both create a task (no UNIQUE index arbitrates them).
-  const evaluateDedupGuards = async (): Promise<{
+  const evaluateDedupGuards = async (
+    logOverride: boolean,
+  ): Promise<{
     ok: boolean;
     message: string;
     task?: AgentTask;
@@ -602,59 +614,35 @@ export async function sendTaskHandler(
       }
     }
 
-    // Guard: prevent re-delegation from follow-up tasks
-    // When the source task is a "follow-up" (worker completed/failed notification),
-    // check if there are completed tasks in the same Slack thread recently.
-    // This prevents the cycle: worker completes → follow-up → Lead re-delegates → repeat.
-    //
-    // Exception: if a MORE RECENT task in the same thread was cancelled (exit 130,
-    // status='cancelled', or status='failed' with failureReason containing
-    // "cancelled"), bypass the guard. A cancellation means the work was
-    // interrupted — re-dispatch is the correct response, not a deduped no-op.
-    // Without this bypass, a cancelled worker permanently jams the thread
-    // against re-delegation when an earlier completed sibling exists.
+    // Guard: prevent re-delegation from follow-up tasks (same-work and
+    // loop-cap rules, see src/tasks/follow-up-redelegation-guard.ts).
+    // allowRedelegation bypasses both and is logged.
     //
     // NOTE: `taskType === "resume"` (created by createResumeFollowUp on
     // supersede) is intentionally NOT in this guard — a resume IS the legitimate
     // re-dispatch and bypassing the check is correct. Do not add "resume" here.
-    if (sourceTaskId) {
-      const sourceTask = await getTaskById(sourceTaskId);
-      if (
-        sourceTask?.taskType === "follow-up" &&
-        sourceTask.slackThreadTs &&
-        sourceTask.slackChannelId
-      ) {
-        const recentCompleted = await findCompletedTaskInThread(
-          sourceTask.slackChannelId,
-          sourceTask.slackThreadTs,
-          2880, // 48 hours in minutes
+    const followUpThread = creatorAgentId ? await followUpThreadForSourceTask(sourceTaskId) : null;
+    if (followUpThread && creatorAgentId) {
+      const blocked = await evaluateFollowUpRedelegation({
+        ...followUpThread,
+        creatorAgentId,
+        taskDescription,
+        targetAgentId: taskOptions.agentId ?? taskOptions.offeredTo,
+      });
+      if (blocked && !requestedAllowRedelegation) {
+        return { ok: false, message: blocked.message };
+      }
+      if (blocked && logOverride) {
+        console.log(
+          `[send-task] follow-up re-delegation override: rule=${blocked.rule} creatorAgentId=${creatorAgentId} sourceTaskId=${sourceTaskId} thread=${followUpThread.channelId}/${followUpThread.threadTs}`,
         );
-        if (recentCompleted) {
-          const recentCancelled = await findRecentCancelledTaskInThread(
-            sourceTask.slackChannelId,
-            sourceTask.slackThreadTs,
-            2880,
-          );
-          const cancelledMoreRecent =
-            recentCancelled &&
-            new Date(recentCancelled.lastUpdatedAt).getTime() >
-              new Date(recentCompleted.lastUpdatedAt).getTime();
-          if (!cancelledMoreRecent) {
-            return {
-              ok: false,
-              message: `Blocked: re-delegation from follow-up task in a thread that already has completed work (task ${recentCompleted.id.slice(0, 8)}). The original request was already handled.`,
-            };
-          }
-          // else: fall through — the cancellation is more recent than the
-          // completion, so re-delegation is legitimate.
-        }
       }
     }
 
     return null;
   };
 
-  const guard = await evaluateDedupGuards();
+  const guard = await evaluateDedupGuards(true);
   if (guard) {
     const guardData = {
       yourAgentId: creatorAgentId,
@@ -669,7 +657,7 @@ export async function sendTaskHandler(
     // Authoritative re-check: the reads above are separated from the INSERT by
     // the whole handler, so only a guard inside this transaction can see a
     // concurrent send-task's committed task.
-    const raced = await evaluateDedupGuards();
+    const raced = await evaluateDedupGuards(false);
     if (raced) return { success: raced.ok, message: raced.message, task: raced.task };
 
     // This transaction already checked the tracker key, excluding the caller's

package/src/tools/slack-leave-thread.ts

@@ -94,7 +94,7 @@ export const registerSlackLeaveThreadTool = (server: McpServer) => {
         return toolErr("No Slack thread context available.");
       }
 
-      await leaveSlackThread(slackChannelId, slackThreadTs, agent.id);
+      await leaveSlackThread(slackChannelId, slackThreadTs, { agentId: agent.id });
       return toolOk(
         `Left Slack thread ${slackChannelId}/${slackThreadTs}. Messages there are ignored until someone @mentions the bot.`,
         { data: { channelId: slackChannelId, threadTs: slackThreadTs } },