@desplega.ai/agent-swarm 1.147.0 → 1.149.0

package/src/tools/defer-task.ts

@@ -4,12 +4,14 @@ import * as z from "zod";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import {
   completeTask,
+  createLogEntry,
   createScheduledTask,
   getAgentById,
   getDbClient,
   getTaskById,
   updateAgentStatusFromCapacity,
 } from "@/be/db";
+import { reconcileDeferredTaskWaits } from "@/scheduler/deferred-task-waits";
 import { runTaskTerminalEffects } from "@/tasks/task-terminal-effects";
 import { getTaskOutputValidationError } from "@/tasks/terminal-result-guard";
 import { assertOwnsTask, ownerCtx } from "@/tools/task-tool-ctx";
@@ -32,7 +34,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
       title: "Defer Task",
       annotations: { destructiveHint: false, idempotentHint: false },
       description:
-        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output. A one-off schedule wakes you up later with a child task that carries this task as its parent. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
+        "Completes this task now with status `completed` and books a wake-up for you. Use when the result needs time: a build, a deploy, a reply. The task reaches its final state on this call; the lead sees your summary as its output unless the task has an outputSchema. For a task with an outputSchema, provide output as a JSON string matching that schema; it is stored verbatim as terminal output, while deferral details remain visible in the task log. A one-off schedule wakes you up later with a child task that carries this task as its parent. Optionally provide wakeOn to wake early when another task completes or fails; delayMs or runAt remains required as the ceiling. Provide delayMs or runAt, a summary of what you did, and a note that says what is pending and what to check.",
       inputSchema: z.object({
         taskId: z.string().describe("The ID of the task you are working on."),
         delayMs: z
@@ -46,12 +48,28 @@ export const registerDeferTaskTool = (server: McpServer) => {
           .datetime()
           .optional()
           .describe("Wake up at this ISO datetime (e.g. '2026-03-06T15:00:00Z'). Must be future."),
+        wakeOn: z
+          .object({
+            event: z.enum(["task.completed", "task.failed", "settled"]),
+            taskId: z.string().min(1),
+          })
+          .strict()
+          .optional()
+          .describe(
+            "Wake early on this task event. settled covers completed or failed. Already-terminal tasks are rejected; a delayMs/runAt ceiling is still required.",
+          ),
         summary: z
           .string()
           .min(1)
           .max(4000)
           .describe(
-            "What you did so far and where things stand. This becomes the task's output; the lead and your wake-up run both read it.",
+            "What you did so far and where things stand. Stored in the task log for tasks with an outputSchema; otherwise becomes the task's output.",
+          ),
+        output: z
+          .string()
+          .optional()
+          .describe(
+            "Required when the task has an outputSchema: a JSON string matching that schema, stored verbatim as terminal output. Ignored for tasks without an outputSchema.",
           ),
         note: z
           .string()
@@ -71,7 +89,11 @@ export const registerDeferTaskTool = (server: McpServer) => {
         nextRunAt: z.string().optional(),
       }),
     },
-    async ({ taskId, delayMs, runAt, summary, note, checks }, requestInfo, _meta) => {
+    async (
+      { taskId, delayMs, runAt, wakeOn, summary, output, note, checks },
+      requestInfo,
+      _meta,
+    ) => {
       if (!requestInfo.agentId) {
         return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
@@ -122,26 +144,37 @@ export const registerDeferTaskTool = (server: McpServer) => {
       }
       const nextRunAt = delayMs ? new Date(Date.now() + delayMs).toISOString() : runAt!;
 
+      const wakeDescription = wakeOn
+        ? `on ${wakeOn.event} for task ${wakeOn.taskId}, or by ${nextRunAt}`
+        : `at ${nextRunAt}`;
       const checksBlock = renderChecks(checks);
       const taskTemplate = `Resume task ${taskId}: ${note}${checksBlock}`;
       const createdBy =
         (await resolveTaskAuditUserId(requestInfo.sourceTaskId, requestInfo.agentId)) ?? undefined;
 
-      // The deferral note is written as the task's FINAL output — a task with
-      // an outputSchema must satisfy it on completion (store-progress enforces
-      // the same rule). Validate before creating anything: the real schedule
-      // id isn't known yet, but it never changes whether this prose is valid
-      // JSON against the schema, so a placeholder stands in for it here.
-      const previewOutput = `${summary}\n\nDeferred until ${nextRunAt} (schedule pending). Pending: ${note}${checksBlock}`;
-      const outputValidationError = getTaskOutputValidationError(task.outputSchema, previewOutput);
-      if (outputValidationError) {
-        return toolErr(
-          `Task ${taskId} has an outputSchema; its terminal output must satisfy it, but a deferral note cannot. ${outputValidationError}`,
-        );
+      // Validate before creating the schedule or changing the task.
+      if (task.outputSchema) {
+        if (!output) {
+          return toolErr(
+            `Task ${taskId} has an outputSchema. Call defer-task with output: a JSON string matching that schema. Summary and note are stored separately in the task log.`,
+          );
+        }
+        const outputValidationError = getTaskOutputValidationError(task.outputSchema, output);
+        if (outputValidationError) return toolErr(outputValidationError);
       }
 
       try {
         const committed = await getDbClient().transaction(async () => {
+          if (wakeOn) {
+            if (wakeOn.taskId === taskId)
+              throw new DeferAbortedError("Cannot wake on the task being deferred.");
+            const watched = await getTaskById(wakeOn.taskId);
+            if (!watched) throw new DeferAbortedError(`Watched task ${wakeOn.taskId} not found.`);
+            if (isTerminalTaskStatus(watched.status))
+              throw new DeferAbortedError(
+                `Watched task ${wakeOn.taskId} is already ${watched.status}; read its result instead of deferring.`,
+              );
+          }
           const schedule = await createScheduledTask({
             // Unique name (`getScheduledTaskByName` is a unique lookup). The UUID
             // prevents concurrent deferrals of the same task from colliding.
@@ -165,12 +198,22 @@ export const registerDeferTaskTool = (server: McpServer) => {
             createdBy,
           });
 
-          const output = `${summary}\n\nDeferred until ${nextRunAt} (schedule ${schedule.id}). Pending: ${note}${checksBlock}`;
+          if (wakeOn) {
+            await getDbClient().run(
+              "INSERT INTO deferred_task_waits (scheduleId, taskId, eventName, created_by, updated_by) VALUES (?, ?, ?, ?, ?)",
+              [schedule.id, wakeOn.taskId, wakeOn.event, createdBy ?? null, createdBy ?? null],
+            );
+            getDbClient().afterCommit(() => {
+              void reconcileDeferredTaskWaits(wakeOn.taskId).catch((err) => {
+                console.error("[defer-task] Event wake reconciliation failed:", err);
+              });
+            });
+          }
+
+          const deferralDetails = `${summary}\n\nDeferred until ${nextRunAt} (schedule ${schedule.id}). Pending: ${note}${checksBlock}`;
 
-          // Deliberately NOT running `getTaskOutputValidationError` again here:
-          // already validated above against a placeholder id; re-run would be
-          // redundant since the id never affects JSON-shape validity.
-          const completed = await completeTask(taskId, output);
+          const terminalOutput = task.outputSchema ? output! : deferralDetails;
+          const completed = await completeTask(taskId, terminalOutput);
           if (!completed) {
             // Another writer terminally completed/failed/cancelled this task
             // between our early check and this transaction's write. Abort:
@@ -182,6 +225,15 @@ export const registerDeferTaskTool = (server: McpServer) => {
             );
           }
 
+          if (task.outputSchema) {
+            await createLogEntry({
+              eventType: "task_progress",
+              taskId,
+              agentId: requestInfo.agentId,
+              newValue: deferralDetails,
+            });
+          }
+
           // afterCommit: the transaction can still roll back; business-use must
           // not be told the task completed for a write that never landed.
           getDbClient().afterCommit(() => {
@@ -207,7 +259,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
             await updateAgentStatusFromCapacity(task.agentId);
           }
 
-          return { scheduleId: schedule.id, output, completed };
+          return { scheduleId: schedule.id, output: terminalOutput, completed };
         });
 
         await runTaskTerminalEffects({
@@ -218,7 +270,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
         });
 
         return toolOk(
-          `Task ${taskId} completed and deferred. Wake-up at ${nextRunAt} (schedule ${committed.scheduleId}). This task is final; the wake-up task continues the work.`,
+          `Task ${taskId} completed and deferred. Wake-up ${wakeDescription} (schedule ${committed.scheduleId}). This task is final; the wake-up task continues the work.`,
           {
             data: {
               yourAgentId: requestInfo.agentId,

package/src/tools/memory-get.ts

@@ -80,12 +80,14 @@ export const registerMemoryGetTool = (server: McpServer) => {
       annotations: { readOnlyHint: true },
 
       inputSchema: z.object({
-        memoryId: z.uuid().describe("The ID of the memory to retrieve."),
+        memoryId: z.uuid().optional().describe("The ID of the memory to retrieve (or use id)."),
+        id: z.uuid().optional().describe("Alias for memoryId, matching memory-search results."),
         intent: z
           .string()
           .min(1)
+          .optional()
           .describe(
-            "Why you are retrieving this memory. Required. E.g. 'need full details of the auth fix pattern'.",
+            "Optional reason for retrieving this memory. E.g. 'need full details of the auth fix pattern'.",
           ),
       }),
       outputSchema: swarmToolOutputSchema({
@@ -102,7 +104,12 @@ export const registerMemoryGetTool = (server: McpServer) => {
         rateHint: z.string().optional(),
       }),
     },
-    async ({ memoryId, intent }, requestInfo, _meta) => {
+    async ({ memoryId: requestedMemoryId, id, intent }, requestInfo, _meta) => {
+      if (requestedMemoryId && id && requestedMemoryId !== id) {
+        return toolErr("memoryId and id must identify the same memory; supply only one.");
+      }
+      const memoryId = requestedMemoryId ?? id;
+      if (!memoryId) return toolErr("Supply memoryId (or its alias id) from memory-search.");
       const store = getMemoryStore();
       const memoryForAuth = await store.peek(memoryId);
 

package/src/tools/memory-rate.ts

@@ -42,15 +42,21 @@ export const registerMemoryRateTool = (server: McpServer) => {
         "the swarm learns to surface better memories next time.",
       annotations: { destructiveHint: false },
       inputSchema: z.object({
-        id: z.string().describe("Memory ID returned by memory_search."),
+        id: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Memory ID returned by memory-search (or use memoryId)."),
+        memoryId: z.string().min(1).optional().describe("Alias for id, matching memory-get."),
         useful: z
           .boolean()
           .describe("true = this memory helped solve the task; false = misled or wasted time."),
         note: z
           .string()
-          .max(280)
           .optional()
-          .describe("Short reason. Captured for telemetry; not surfaced to other agents."),
+          .describe(
+            "Reason, stored up to 500 characters for telemetry; not surfaced to other agents.",
+          ),
         referencesSource: z
           .string()
           .min(1)
@@ -60,7 +66,13 @@ export const registerMemoryRateTool = (server: McpServer) => {
       }),
       outputSchema: swarmToolOutputSchema(),
     },
-    async ({ id, useful, note, referencesSource }, requestInfo, _meta) => {
+    async ({ id, memoryId, useful, note, referencesSource }, requestInfo, _meta) => {
+      if (id && memoryId && id !== memoryId) {
+        return toolErr("id and memoryId must identify the same memory; supply only one.");
+      }
+      const resolvedMemoryId = id ?? memoryId;
+      if (!resolvedMemoryId)
+        return toolErr("Supply id (or its alias memoryId) from memory-search.");
       if (!requestInfo.agentId) {
         return toolErr("Agent ID required. Are you registered in the swarm?");
       }
@@ -85,11 +97,11 @@ export const registerMemoryRateTool = (server: McpServer) => {
       const apiKey = getApiKey();
 
       const event = {
-        memoryId: id,
+        memoryId: resolvedMemoryId,
         signal: useful ? 1 : -1,
         weight: 1.0,
         source: "explicit-self" as const,
-        reasoning: note ?? "",
+        reasoning: (note ?? "").slice(0, 500),
         taskId: requestInfo.sourceTaskId,
         ...(cleanedReferencesSource !== undefined
           ? { referencesSource: cleanedReferencesSource }
@@ -129,7 +141,7 @@ export const registerMemoryRateTool = (server: McpServer) => {
           return toolErr(`Memory rating failed (HTTP ${response.status}).`);
         }
 
-        return toolOk(`Memory ${id} rated as ${useful ? "useful" : "not useful"}.`);
+        return toolOk(`Memory ${resolvedMemoryId} rated as ${useful ? "useful" : "not useful"}.`);
       } catch (err) {
         return toolErr(`Memory rating failed: ${(err as Error).message}`);
       }

package/src/tools/memory-search.ts

@@ -84,8 +84,9 @@ export const registerMemorySearchTool = (server: McpServer) => {
         intent: z
           .string()
           .min(1)
+          .optional()
           .describe(
-            "Why you are searching for this memory. Required. E.g. 'looking for auth pattern to fix login bug'.",
+            "Optional reason for searching for this memory. E.g. 'looking for auth pattern to fix login bug'.",
           ),
         scope: z
           .enum(["all", "agent", "swarm"])

package/src/tools/memory-store.ts

@@ -24,14 +24,19 @@ export const registerMemoryStoreTool = (server: McpServer) => {
           .string()
           .min(1)
           .max(200)
-          .describe("Short title, one line, used in search results and the UI."),
+          .optional()
+          .describe(
+            "Short title used in search results and the UI. Defaults to the first non-empty content line (up to 200 characters).",
+          ),
         scope: AgentMemoryScopeSchema.default("agent").describe(
           "'agent' (default): only you can recall it. 'swarm': every agent can recall it.",
         ),
         tags: z
-          .array(z.string())
+          .union([z.array(z.string()), z.string()])
           .optional()
-          .describe("Free-form tags, for example a repo name or a topic."),
+          .describe(
+            "Free-form tags as an array or a comma-separated string, for example a repo name or a topic.",
+          ),
         taskId: z
           .uuid()
           .optional()
@@ -49,7 +54,22 @@ export const registerMemoryStoreTool = (server: McpServer) => {
         queued: z.boolean().optional(),
       }),
     },
-    async ({ content, name, scope, tags, taskId, intent }, requestInfo, _meta) => {
+    async ({ content, name: requestedName, scope, tags, taskId, intent }, requestInfo, _meta) => {
+      const name =
+        requestedName ??
+        content
+          .split(/\r?\n/)
+          .find((line) => line.trim())
+          ?.trim()
+          .slice(0, 200) ??
+        "Untitled memory";
+      const normalizedTags =
+        typeof tags === "string"
+          ? tags
+              .split(",")
+              .map((tag) => tag.trim())
+              .filter(Boolean)
+          : tags;
       if (!requestInfo.agentId) {
         return toolErr("Agent ID required. Are you registered in the swarm?");
       }
@@ -64,7 +84,7 @@ export const registerMemoryStoreTool = (server: McpServer) => {
           scope,
           source: "manual",
           sourceTaskId: taskId ?? null,
-          tags,
+          tags: normalizedTags,
           intent,
         });
 

package/src/tools/send-task.ts

@@ -11,6 +11,7 @@ import {
   getAgentById,
   getDbClient,
   getTaskById,
+  getUserById,
   hasCapacity,
 } from "@/be/db";
 import { repointTrackerSyncBySwarmId } from "@/be/db-queries/tracker";
@@ -30,6 +31,7 @@ import {
   FollowUpConfigSchema,
   ModelTierSchema,
   ReasoningEffortSchema,
+  RoutingReasonSchema,
   splitLegacyModelAlias,
 } from "@/types";
 import { findJsonSchemaShapeErrors } from "@/workflows/json-schema-validator";
@@ -60,6 +62,14 @@ export const sendTaskInputSchema = z
       .string()
       .optional()
       .describe("The agent to assign/offer task to. Omit to create unassigned task for pool."),
+    routingReason: RoutingReasonSchema.optional().describe(
+      "Why this agent was selected. Required when agentId is supplied; omit for pool routing.",
+    ),
+    routingNote: z
+      .string()
+      .max(200)
+      .optional()
+      .describe("Optional routing context (maximum 200 characters)."),
     task: z.string().min(1).describe("The task description to send."),
     key: AssetKeySchema.optional().describe(
       "Logical namespace key. Child tasks inherit their parent namespace when provided.",
@@ -148,10 +158,10 @@ export const sendTaskInputSchema = z
       ),
     requestedByUserId: z
       .string()
-      .uuid()
+      .regex(/^[a-f0-9]{32}$/, "Expected a registry user ID (32 lowercase hexadecimal characters).")
       .optional()
       .describe(
-        "ID of the human user who originally requested this task chain. When omitted, inherited from the caller's current task so the attribution flows through multi-hop delegation automatically.",
+        "Registered requester ID (32 lowercase hexadecimal characters). When omitted, inherited from the caller's current task so the attribution flows through multi-hop delegation automatically.",
       ),
     followUpConfig: FollowUpConfigSchema.optional().describe(
       "Control the lead follow-up created when this task finishes. When to use `followUpConfig`: set `disabled: true` when you'll wait for this task to complete inline and no follow-up is needed; set `onCompleted` / `onFailed` with specific instructions when you need to follow up effectively on a particular outcome of a long-running flow; for normal one-shot tasks, leave it unset because defaults are fine. It is most valuable for long-running / complex flows.",
@@ -173,6 +183,13 @@ export const sendTaskInputSchema = z
         path: [hasChannel ? "slackThreadTs" : "slackChannelId"],
       });
     }
+    if (data.agentId !== undefined && data.routingReason === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "routingReason is required when agentId is supplied.",
+        path: ["routingReason"],
+      });
+    }
     checkOutputSchemaShape(data.outputSchema, ctx);
   });
 
@@ -221,6 +238,8 @@ export async function sendTaskHandler(
   ctx: ToolCtx,
   {
     agentId,
+    routingReason,
+    routingNote,
     task,
     key,
     offerMode,
@@ -246,6 +265,10 @@ export async function sendTaskHandler(
     outputSchema,
   }: SendTaskArgs,
 ): Promise<SwarmToolResult> {
+  // Defense in depth for direct TypeScript callers that bypass MCP schema parsing.
+  if (agentId !== undefined && routingReason === undefined) {
+    return toolErr("routingReason is required when agentId is supplied.");
+  }
   if (ctx.kind === "owner" && !ctx.agentId) {
     return toolErr('Agent ID not found. The MCP client should define the "X-Agent-ID" header.', {
       data: { yourAgentId: ctx.agentId },
@@ -257,6 +280,12 @@ export async function sendTaskHandler(
   const requestedByUserId =
     ctx.kind === "user" ? ctx.userId : (inputRequestedByUserId ?? undefined);
 
+  if (ctx.kind === "owner" && requestedByUserId && !(await getUserById(requestedByUserId))) {
+    return toolErr("requestedByUserId must identify an existing registered user.", {
+      data: { yourAgentId: creatorAgentId },
+    });
+  }
+
   if (ctx.kind === "owner" && agentId === ctx.agentId) {
     return toolErr("Cannot send a task to yourself, are you drunk?", {
       data: { yourAgentId: ctx.agentId },
@@ -332,6 +361,9 @@ export async function sendTaskHandler(
       effectiveAgentId = effectiveParentTask.agentId;
     }
   }
+  const effectiveRoutingReason =
+    agentId !== undefined ? routingReason : effectiveAgentId ? "continuity" : undefined;
+  const effectiveRoutingNote = effectiveRoutingReason ? routingNote : undefined;
 
   // The three dedup guards are pure reads, so they run twice: once here as a
   // fast path (keeping this tool's existing early-exit responses), and once
@@ -463,6 +495,8 @@ export async function sendTaskHandler(
         overrideSlackContext,
         followUpConfig,
         outputSchema,
+        routingReason: effectiveRoutingReason,
+        routingNote: effectiveRoutingNote,
         routingAffinity:
           effectiveLeadOnly || requiredCapabilities?.length
             ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }
@@ -530,6 +564,8 @@ export async function sendTaskHandler(
         overrideSlackContext,
         followUpConfig,
         outputSchema,
+        routingReason: effectiveRoutingReason,
+        routingNote: effectiveRoutingNote,
         routingAffinity:
           effectiveLeadOnly || requiredCapabilities?.length
             ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }
@@ -571,6 +607,8 @@ export async function sendTaskHandler(
       overrideSlackContext,
       followUpConfig,
       outputSchema,
+      routingReason: effectiveRoutingReason,
+      routingNote: effectiveRoutingNote,
       routingAffinity:
         effectiveLeadOnly || requiredCapabilities?.length
           ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }

package/src/tools/skills/skill-publish.ts

@@ -71,6 +71,7 @@ To reject: close this task with a rejection reason.`;
 
       const task = await createTaskExtended(taskDescription, {
         agentId: leadAgent.id,
+        routingReason: "skill",
         creatorAgentId: requestInfo.agentId,
         source: "mcp",
         taskType: "skill-approval",

package/src/tools/store-progress.ts

@@ -29,6 +29,17 @@ import { scrubSecrets } from "@/utils/secret-scrubber";
 // echoed the schema example, producing noise rows keyed `mcp-<taskId>-<ts>`
 // that double-counted alongside the harness's authoritative entry.
 
+// Deliberately narrow and phrase-based (not a bare "wait"/"block" substring
+// match) to under-fire rather than over-fire: measured against 196 real
+// progress rows across all statuses, this matched 0 — see PR body for the
+// full false-positive measurement methodology.
+const BLOCKED_WAITING_PATTERN =
+  /\b(waiting (for|on)|blocked (on|until|by)|still waiting|awaiting)\b/i;
+
+// Below this, two check-ins are close enough together that "blocked" reads as
+// noise and calling defer-task buys nothing over checking in again shortly.
+const BLOCKED_WAITING_MIN_ELAPSED_MS = 3 * 60 * 1000;
+
 export const storeProgressOutputSchema = swarmToolOutputSchema({
   // Bounded confirmation only. The handler keeps the full task row internally
   // for completion memory, raters, and follow-up creation, but never echoes it
@@ -56,6 +67,12 @@ export const storeProgressOutputSchema = swarmToolOutputSchema({
     .describe(
       "True when force: true replaced output and/or failureReason on an already-terminal task without replaying completion side effects.",
     ),
+  blockedWaitingElapsedMs: z
+    .number()
+    .optional()
+    .describe(
+      "Present only when this progress text reads as blocked-waiting: milliseconds since the task's prior update. Drives the store-progress nudge toward defer-task.",
+    ),
 });
 
 export const registerStoreProgressTool = (server: McpServer) => {
@@ -68,12 +85,19 @@ export const registerStoreProgressTool = (server: McpServer) => {
       annotations: { idempotentHint: true },
 
       inputSchema: z.object({
-        taskId: z.uuid().describe("The ID of the task to update progress for."),
+        taskId: z
+          .uuid()
+          .optional()
+          .describe(
+            "Full task UUID. Defaults to the caller-owned task in X-Source-Task-Id; required outside task context.",
+          ),
         progress: z.string().optional().describe("The progress update to store."),
         status: z
-          .enum(["completed", "failed"])
+          .enum(["completed", "failed", "in_progress", "pending"])
           .optional()
-          .describe("Set to 'completed' or 'failed' to finish the task."),
+          .describe(
+            "Set to 'completed' or 'failed' to finish the task. 'in_progress' and 'pending' store progress only and do not change task status.",
+          ),
         output: z
           .string()
           .optional()
@@ -111,7 +135,16 @@ export const registerStoreProgressTool = (server: McpServer) => {
       outputSchema: storeProgressOutputSchema,
     },
     async (
-      { taskId, progress, status, output, failureReason, attachments, persistMemory, force },
+      {
+        taskId: requestedTaskId,
+        progress,
+        status: requestedStatus,
+        output,
+        failureReason,
+        attachments,
+        persistMemory,
+        force,
+      },
       requestInfo,
       _meta,
     ) => {
@@ -119,6 +152,21 @@ export const registerStoreProgressTool = (server: McpServer) => {
         return toolErr('Agent ID not found. The MCP client should define the "X-Agent-ID" header.');
       }
 
+      const taskId = requestedTaskId ?? requestInfo.sourceTaskId;
+      if (!taskId || !z.uuid().safeParse(taskId).success) {
+        return toolErr("Supply taskId as the full task UUID; no valid task context is available.");
+      }
+      if (!requestedTaskId) {
+        const contextTask = await getTaskById(taskId);
+        if (!contextTask || contextTask.agentId !== requestInfo.agentId) {
+          return toolErr("Omitted taskId requires a source task assigned to the calling agent.");
+        }
+      }
+      const status =
+        requestedStatus === "completed" || requestedStatus === "failed"
+          ? requestedStatus
+          : undefined;
+
       // Verify agent-fs pointers before opening the write transaction. The
       // registering agent's resolved config selects both credentials and the
       // exact org/drive; never let the provider fall back to a personal drive.
@@ -220,6 +268,27 @@ export const registerStoreProgressTool = (server: McpServer) => {
 
         let updatedTask = existingTask;
         const isTerminal = isTerminalTaskStatus(existingTask.status);
+        // This call's own status can finish the task even though existingTask
+        // (its state before this call) is not yet terminal — gate on both so a
+        // completing call carrying blocked-waiting-shaped text (e.g. "awaiting
+        // review") never nudges toward defer-task.
+        const goingTerminal = status !== undefined && isTerminalTaskStatus(status);
+
+        // Computed against the task's state as of BEFORE this call's update,
+        // so "elapsed" reads as time since the prior check-in, not zero.
+        let blockedWaitingElapsedMs: number | undefined;
+        if (progress && !isTerminal && !goingTerminal && BLOCKED_WAITING_PATTERN.test(progress)) {
+          const referenceIso = existingTask.lastUpdatedAt ?? existingTask.createdAt;
+          if (referenceIso) {
+            const elapsed = Date.now() - new Date(referenceIso).getTime();
+            // Below the floor, a sub-minute check-in reads as "blocked" purely
+            // from noise, and defer-task buys nothing over just checking in
+            // again shortly — so treat it as not blocked-waiting yet.
+            if (elapsed >= BLOCKED_WAITING_MIN_ELAPSED_MS) {
+              blockedWaitingElapsedMs = elapsed;
+            }
+          }
+        }
 
         // Attachments — pointer-based, append-only. Insert each row inside
         // this transaction; the helper dedups by sha256 (when present) or by
@@ -391,6 +460,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
             ? `Task "${taskId}" marked as ${status}.`
             : `Progress stored for task "${taskId}".`,
           task: updatedTask,
+          blockedWaitingElapsedMs,
         };
       });
 
@@ -432,6 +502,10 @@ export const registerStoreProgressTool = (server: McpServer) => {
         ...("wasForcedOverwrite" in result && result.wasForcedOverwrite
           ? { wasForcedOverwrite: true }
           : {}),
+        ...("blockedWaitingElapsedMs" in result &&
+        typeof result.blockedWaitingElapsedMs === "number"
+          ? { blockedWaitingElapsedMs: result.blockedWaitingElapsedMs }
+          : {}),
       };
       return success ? toolOk(message, { data }) : toolErr(message, { data });
     },

package/src/tools/templates.ts

@@ -197,6 +197,7 @@ Use the crashed agent's identity above as context for who was on it and what kin
 
 Dispatch via \`send-task\` with ALL of:
 - an explicit \`agentId\` (the chosen worker) — REQUIRED. If you omit it, \`send-task\` auto-routes to the original task's agent, which is the dead worker, and the work re-strands.
+- \`routingReason: "reroute_fault"\`
 - \`taskType: "resume"\`
 - the tag \`resume-generation:{{generation_next}}\`
 - \`parentTaskId: {{original_task_id}}\`
@@ -251,7 +252,7 @@ Required capabilities: {{required_capabilities}}{{artifacts_block}}
 
 This task has been sitting unassigned because no currently-registered agent matches its required role/capabilities. Pick an agent to take this work over and RE-DELEGATE it — do NOT execute it yourself.
 
-Dispatch via \`send-task\` with an explicit \`agentId\` (REQUIRED — omitting it re-pools the work under the same affinity tag and it will starve again) and \`parentTaskId: {{original_task_id}}\`.
+Dispatch via \`send-task\` with an explicit \`agentId\` (REQUIRED — omitting it re-pools the work under the same affinity tag and it will starve again), \`routingReason: "overflow"\`, and \`parentTaskId: {{original_task_id}}\`.
 
 This work will NOT fall back to the unassigned pool — you are the only re-delegation path.`,
   variables: [