@desplega.ai/agent-swarm 1.147.0 → 1.149.0

package/src/be/migrations/152_routing_decisions.sql

@@ -0,0 +1,44 @@
+ALTER TABLE agent_tasks ADD COLUMN routing_reason TEXT
+  CHECK (
+    routing_reason IS NULL OR routing_reason IN (
+      'skill',
+      'continuity',
+      'overflow',
+      'human_pinned',
+      'reroute_fault'
+    )
+  );
+
+ALTER TABLE agent_tasks ADD COLUMN routing_note TEXT
+  CHECK (routing_note IS NULL OR length(routing_note) <= 200);
+
+-- Continuity snapshots run while task creation holds BEGIN IMMEDIATE. Keep
+-- each context lookup filter-first and recency-ordered. SQLite stores rowid as
+-- the implicit final index key, so a reverse scan also satisfies the
+-- createdAt DESC, rowid DESC deterministic tie-break.
+CREATE INDEX idx_agent_tasks_routing_pr_recency
+  ON agent_tasks(vcsRepo, vcsNumber, createdAt);
+
+CREATE INDEX idx_agent_tasks_routing_repo_recency
+  ON agent_tasks(vcsRepo, createdAt);
+
+CREATE INDEX idx_agent_tasks_routing_slack_thread_recency
+  ON agent_tasks(slackChannelId, slackThreadTs, createdAt);
+
+CREATE INDEX idx_agent_tasks_routing_agentmail_thread_recency
+  ON agent_tasks(agentmailThreadId, createdAt);
+
+-- Immutable decision-time telemetry. Agent ids deliberately are not foreign
+-- keys: deleting an agent must not erase which target or candidate was visible
+-- when the task was created.
+CREATE TABLE routing_decisions (
+  task_id                TEXT PRIMARY KEY REFERENCES agent_tasks(id) ON DELETE CASCADE,
+  selected_agent_id      TEXT,
+  captured_at            TEXT NOT NULL,
+  worker_statuses        TEXT NOT NULL
+                         CHECK (json_valid(worker_statuses) AND json_type(worker_statuses) = 'array'),
+  continuity_candidates  TEXT NOT NULL
+                         CHECK (json_valid(continuity_candidates) AND json_type(continuity_candidates) = 'object'),
+  created_by             TEXT,
+  updated_by             TEXT
+);

package/src/be/scripts/typecheck.ts

@@ -35,6 +35,36 @@ export type ScriptScope = "agent" | "global";
 export type ScriptFsMode = "none" | "workspace-rw";
 export type ScriptApiRawOptions = { raw: true };
 export type ScriptApiDefaultOptions = { raw?: false };
+export type RoutingReason = "skill" | "continuity" | "overflow" | "human_pinned" | "reroute_fault";
+export type TaskSendArgs = Record<string, unknown> & {
+  task: string;
+  routingNote?: string;
+} & (
+  | { agentId: string; routingReason: RoutingReason }
+  | { agentId?: never; routingReason?: never }
+);
+export type AgentTaskStepConfig = {
+  template?: string;
+  task?: string;
+  agentId?: string;
+  routingReason?: RoutingReason;
+  routingNote?: string;
+  tags?: string[];
+  priority?: number;
+  offerMode?: boolean;
+  dir?: string;
+  vcsRepo?: string;
+  model?: string;
+  parentTaskId?: string;
+  requestedByUserId?: string;
+  outputSchema?: Record<string, unknown>;
+  /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
+  waitForCompletion?: boolean;
+  /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
+  timeoutMs?: number;
+  /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
+  failOnTaskFailure?: boolean;
+};
 
 export interface ScriptApiRawResult {
   ok: boolean;
@@ -138,7 +168,7 @@ export interface SwarmSdk {
   task_list(args?: Record<string, unknown>): Promise<unknown>;
   task_get(args: { taskId: string }): Promise<unknown>;
   task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
-  task_defer(args: { taskId: string; delayMs?: number; runAt?: string; summary: string; note: string; checks?: string[] }): Promise<unknown>;
+  task_defer(args: { taskId: string; delayMs?: number; runAt?: string; wakeOn?: { event: "task.completed" | "task.failed" | "settled"; taskId: string }; summary: string; note: string; checks?: string[] }): Promise<unknown>;
   task_poll(args?: Record<string, unknown>): Promise<unknown>;
   // --- kv ---
   kv_get<T = unknown>(args: { key: string; namespace?: string }): Promise<KvSdkResponse<KvEntry<T>>>;
@@ -219,7 +249,7 @@ export interface SwarmSdk {
   inject_learning(args: { content: string; name?: string; scope?: "agent" | "swarm"; source?: string; tags?: string[] }): Promise<unknown>;
 
   // --- write: tasks ---
-  task_send(args: Record<string, unknown>): Promise<unknown>;
+  task_send(args: TaskSendArgs): Promise<unknown>;
   task_cancel(args: { taskId: string }): Promise<unknown>;
   task_steer(args: { taskId: string; message: string; mode?: "steer" | "queue"; onUnsupported?: "degrade" | "fail" }): Promise<unknown>;
   task_action(args: Record<string, unknown>): Promise<unknown>;
@@ -374,26 +404,7 @@ export interface ScriptWorkflowSteps {
   ): Promise<unknown>;
   agentTask(
     label: string,
-    config: {
-      template?: string;
-      task?: string;
-      agentId?: string;
-      tags?: string[];
-      priority?: number;
-      offerMode?: boolean;
-      dir?: string;
-      vcsRepo?: string;
-      model?: string;
-      parentTaskId?: string;
-      requestedByUserId?: string;
-      outputSchema?: Record<string, unknown>;
-      /** Wait for the dispatched task to reach a terminal status before resolving. Default: true. */
-      waitForCompletion?: boolean;
-      /** Max ms to wait for a terminal status before throwing. Default: 2h. Only used when waitForCompletion is true. */
-      timeoutMs?: number;
-      /** Throw when the task ends failed/cancelled/superseded (default), or resolve with {taskId,status,error} when false. */
-      failOnTaskFailure?: boolean;
-    },
+    config: AgentTaskStepConfig,
   ): Promise<unknown>;
   swarmScript(
     label: string,

package/src/be/seed-scripts/catalog/delegate.ts

@@ -2,6 +2,8 @@ import { z } from "zod";
 
 export const argsSchema = z.object({
   agentName: z.string().describe("Target agent's name (case-insensitive) — resolved to its id"),
+  routingReason: z.enum(["skill", "continuity", "overflow", "human_pinned", "reroute_fault"]),
+  routingNote: z.string().max(200).optional(),
   task: z.string().describe("Full task prompt for the target agent"),
   parentTaskId: z
     .string()
@@ -15,7 +17,7 @@ export const argsSchema = z.object({
 export default async function delegate(args: any, ctx: any) {
   const parsed = argsSchema.safeParse(args);
   if (!parsed.success) return { ok: false, error: "invalid args: " + parsed.error.message };
-  const { agentName, task, parentTaskId, priority, tags } = parsed.data;
+  const { agentName, task, routingReason, routingNote, parentTaskId, priority, tags } = parsed.data;
 
   const res: any = await ctx.swarm.swarm_get({ includeFull: true });
   const agents: any[] = res?.data?.agents ?? res?.agents ?? [];
@@ -26,6 +28,8 @@ export default async function delegate(args: any, ctx: any) {
 
   const sent: any = await ctx.swarm.task_send({
     agentId: agent.id,
+    routingReason,
+    routingNote,
     task,
     ...(parentTaskId ? { parentTaskId } : {}),
     ...(priority != null ? { priority } : {}),

package/src/be/seed-skills/bundled-files.generated.json

@@ -23,6 +23,16 @@
       "content": "---\ndate: [Current date and time with timezone in ISO format]\nauthor: [Author name]\ntopic: \"[Topic]\"\ntags: [brainstorm, relevant-tags]\nstatus: in-progress\nexploration_type: [problem|idea|comparison|workflow|other]\nlast_updated: [Current date in YYYY-MM-DD format]\nlast_updated_by: [Author name]\n---\n\n# [Topic] — Brainstorm\n\n## Context\n\n[Initial framing: what we know, what prompted this exploration, any existing context or constraints]\n\n## Exploration\n\n[Q&A pairs accumulate here during the session]\n\n## Synthesis\n\n### Key Decisions\n- [Filled after exploration — includes \"Deferred: X, defaulting to Y\" entries for consciously parked decisions]\n\n### Open Questions\n- [Fact-shaped questions only (answerable by /research) — undecided decisions don't belong here]\n\n### Constraints Identified\n- [Filled after exploration]\n\n### Core Requirements\n- [Filled after exploration]\n\n## Next Steps\n\n- [Handoff decision: research, plan, or parked]\n"
     }
   ],
+  "comms": [
+    {
+      "path": "references/ste-rules.md",
+      "content": "# Precise mode — ASD-STE100 rules\n\nCondensed from [asd-ste100-skill](https://github.com/desplega-ai/asd-ste100-skill) (MIT), which encodes the rule categories of ASD-STE100 Issue 9 (Jan 2025).\n\nThis encodes the standard's rule *categories*, not ASD's ~900-word approved dictionary (free to obtain, not free to redistribute). Structural rules are checkable from the description alone — apply them with confidence. Lexical rules depend on the dictionary — apply them as a direction of travel, and never imply dictionary compliance.\n\n## Structural rules — apply these\n\n| Rule | Do | Don't |\n|---|---|---|\n| Active voice | \"The agent deletes the file.\" | \"The file is deleted (by the agent).\" — unless the actor is genuinely unknown or irrelevant |\n| No phrasal verbs | \"Remove the panel.\" / \"Start the job.\" | \"Take off the panel.\" / \"Spin up the job.\" |\n| One instruction per sentence | \"Open the file. Read line 3.\" | \"Open the file and read line 3, then check if it matches.\" |\n| Sentence length | ≤20 words for instructions, ≤25 for descriptions | Long compound/subordinate-clause sentences |\n| No semicolons | Split into separate sentences | Any semicolon at all |\n| Noun clusters | ≤3 words stacked as a noun phrase | 4+ word noun stacks (\"high pressure fuel pump inlet valve assembly\") |\n| No ellipsis | Keep subject, verb, and article explicit | Drop words to save space (\"Files not backed up will be lost\" → ambiguous which files) |\n| Keep modality | \"The request **may have** failed.\" stays \"may have\" | Promote a hedge to a fact, or invent a certainty the source did not state |\n| Paragraph limits | One topic per paragraph, ≤6 sentences | Multi-topic paragraphs |\n| Lists for sequences | Numbered/bulleted list for 3+ steps or conditions | A sequence buried in one prose sentence |\n\n## Lexical rules — direction of travel only\n\n| Rule | Do | Don't |\n|---|---|---|\n| One word, one meaning | Pick one verb for one action and reuse it every time | Rotate synonyms (\"check\"/\"verify\"/\"confirm\") for the same action |\n| One part of speech per word | \"Apply oil to the valve\" (oil = noun) | \"Oil the valve\" (oil = verb) |\n| Verb, not noun | \"Analyze the log.\" | \"Perform an analysis of the log.\" |\n| Domain terms | Keep needed technical terms; define each once if not common English | Jargon never defined |\n\n## Simple tenses — one exception\n\nSTE permits infinitive, imperative, simple present, simple past, simple future, and past participle as adjective. It excludes present perfect: \"we received the report\", not \"we have received the report\". Exception: where the compound form carries information the simple form cannot — current relevance (\"the job has completed\" = output available now), or a hedge like \"may have failed\" — keep it and flag the departure.\n\n## Scan checklist\n\nScan for all six before rewriting. Each is mechanical — you can point at the exact word that breaks it.\n\n1. **Synonym rotation** — the same thing has several names (\"the user\", \"the customer\", \"the client\"). Fix: one name, every time.\n2. **Hedge stacking** — qualifiers pile up until nothing is asserted (\"it is important to note that this may potentially help to improve\"). Fix: state the claim or delete it.\n3. **Nominalization** — an action frozen into a noun (\"perform an analysis of\"). Fix: use the verb.\n4. **Marketing adjectives** — seamless, robust, powerful, blazing-fast. Fix: delete, or replace with the measurement that earns the claim.\n5. **Run-on sentences** — ideas joined by semicolons or em dashes. Fix: one idea per sentence.\n6. **Soft phrasal verbs** — spin up, reach out, dive into, kick off. Fix: the single plain verb (start, contact, read, begin).\n\n## Process\n\n1. Pick the sub-mode (Strict or STE-flavored). Keep the choice internal unless asked.\n2. Read the input once for meaning before rewriting anything.\n3. Walk it sentence by sentence; flag every violation. In STE-flavored, flag lexical rules but do not enforce them.\n4. Rewrite each flagged sentence, preserving the original meaning exactly. If a rewrite would drop necessary precision (a safety condition, scope qualifier, number), keep the longer phrasing and flag it. Check modality before committing — a shorter sentence that upgrades a hedge to a fact is a different claim. Never add a fact the source did not state.\n5. Output the rewritten text alone. If the input already complies, say so — do not force changes.\n\n## Diff table format (on request)\n\nWhen asked to \"show the diff\" / \"which rules did it break\" / \"before/after\":\n\n```markdown\n| Rule violated | Original | Simplified |\n|---|---|---|\n| Present perfect tense | \"We have received your request.\" | \"We received your request.\" |\n| Noun cluster (4+ words) | \"the agent task queue priority handler\" | \"the handler that sets task-queue priority\" |\n\nMode: Strict. 7 violations found.\n```\n\nFollow with one line naming anything deliberately not simplified, and why.\n\n## Boundaries\n\n- Not a certified STE authoring tool — a clarity tool inspired by the standard. For aerospace-grade compliance, check word-by-word against the official dictionary from [asd-ste100.org](https://www.asd-ste100.org/STE_downloads.html).\n- Fixes form, not substance: a hollow paragraph rewritten under these rules is a clean hollow paragraph. Say so instead of polishing it.\n- Stop when the sentence is unambiguous, not when it is shortest.\n"
+    },
+    {
+      "path": "references/visual-shapes.md",
+      "content": "# Visual mode — example shapes\n\nConcrete examples for each view the Visual mode can produce. Source: the show-me skill (bundled into this skill).\n\nLogic or an algorithm as pseudocode:\n\n```text\non(save)\n  if content is unchanged\n    return cached result\n  write new content\n  return fresh result\n```\n\nRuntime control flow as a call tree:\n\n```text\nsubmitForm\n  createSession\n    persistPrompt\n    launchAgent\n  navigateToSession\n```\n\nUI structure as a component tree, including state and module boundaries that matter:\n\n```tsx\n<SessionPage> (apps/example/src/routes/session.tsx)\n  useSessionEvents()\n  <SessionToolbar>\n    <RunSkillButton> (packages/ui)\n```\n\nFile responsibility or a broad refactor as a shallow file tree:\n\n```text\nsrc/\n├── commands/       # parses user actions\n├── sessions/       # owns session state\n└── transport/      # sends API requests\n```\n\nComponent interaction, control flow, or data flow with Mermaid:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant UI\n    participant Daemon\n    User->>UI: choose command\n    UI->>Daemon: send expanded prompt\n    Daemon-->>UI: stream result\n```\n\n`diff` shapes — match the diff to the topic.\n\nComponent change:\n\n```diff\n <SessionPage>\n   useSessionEvents()\n   <SessionToolbar>\n+    <RunSkillButton />\n   <SessionTimeline>\n+    <SkillResultCard />\n```\n\nFile-layout change:\n\n```diff\n src/\n ├── commands/\n+│   └── show-me.ts       # expands the slash command\n ├── sessions/\n-└── transport.ts\n+└── transport/\n+    ├── client.ts\n+    └── stream.ts\n```\n\nCall-tree change:\n\n```diff\n submitForm\n   createSession\n     persistPrompt\n+    expandSkillMention\n     launchAgent\n-  navigateToSession\n+  navigateToSession\n+    subscribeToEvents\n```\n\nState or control-flow change:\n\n```diff\n on(save)\n-  write content\n+  if content is unchanged\n+    return cached result\n+  write new content\n+  invalidate cache\n```\n\nWhole block when most of it is new or a copyable target shape is needed:\n\n```ts\nfunction expandSkill(command: string): string {\n  const skillName = command.slice(1)\n  return `use the ${skillName} skill`\n}\n```\n"
+    }
+  ],
   "delegate-work": [
     {
       "path": "scripts/codex-exec.sh",

package/src/be/seed-skills/index.ts

@@ -50,6 +50,8 @@ import codeReviewingConfig from "../../../templates/skills/code-reviewing/config
 import codeReviewingContent from "../../../templates/skills/code-reviewing/content.md" with {
   type: "text",
 };
+import commsConfig from "../../../templates/skills/comms/config.json" with { type: "text" };
+import commsContent from "../../../templates/skills/comms/content.md" with { type: "text" };
 import composioConfig from "../../../templates/skills/composio/config.json" with { type: "text" };
 import composioContent from "../../../templates/skills/composio/content.md" with { type: "text" };
 import composioGmailConfig from "../../../templates/skills/composio-gmail/config.json" with {
@@ -318,6 +320,7 @@ const BUILT_IN_SKILL_SOURCES = [
   { config: brainstormingConfig, body: brainstormingContent },
   { config: codeQualityConfig, body: codeQualityContent },
   { config: codeReviewingConfig, body: codeReviewingContent },
+  { config: commsConfig, body: commsContent },
   { config: composioConfig, body: composioContent },
   { config: composioGmailConfig, body: composioGmailContent },
   { config: composioGoogleCalendarConfig, body: composioGoogleCalendarContent },

package/src/be/steering.ts

@@ -75,6 +75,7 @@ export async function promoteSteeringToTask(
 ): Promise<AgentTask> {
   return await createTaskExtended(message.body, {
     agentId: task.agentId,
+    routingReason: task.agentId ? "continuity" : undefined,
     creatorAgentId: message.createdByAgentId,
     source: message.source === "script" ? "api" : message.source,
     taskType: "follow-up",

package/src/be/swarm-config-guard.ts

@@ -1,5 +1,6 @@
 import { normalizeSlackReactionShortcode } from "../slack/reaction-shortcode";
 import { ProviderNameSchema } from "../types";
+import { parseTaskToolManifest } from "../utils/task-tool-manifest";
 
 /**
  * Guards against storing reserved keys in the swarm_config table.
@@ -163,6 +164,15 @@ function validateFloatRange(
 }
 
 const VALIDATED_KEYS: Record<string, ConfigValidator> = {
+  TASK_TOOL_MANIFESTS: (value) => {
+    try {
+      if (typeof value !== "string") throw new Error("Expected JSON string");
+      parseTaskToolManifest(value);
+      return null;
+    } catch {
+      return "Invalid TASK_TOOL_MANIFESTS (expected JSON with taskTypes and/or schedules maps, each selecting at most 16 known swarm tools)";
+    }
+  },
   FEEDBACK_ENDPOINT: (value) => {
     if (typeof value !== "string") {
       return "Invalid FEEDBACK_ENDPOINT (must use HTTPS, or HTTP on a loopback host)";
@@ -252,6 +262,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "HEARTBEAT_PIN_CRASH_RESUME",
     "POOL_AFFINITY_ENFORCEMENT",
     "SCRIPTS_ONLY_MCP",
+    "TASK_TOOL_PRELOAD_ENABLED",
     "SLACK_DISABLE",
     "SLACK_RENDER_V2",
     "SLACK_RENDER_V2_DELEGATION",

package/src/commands/onboard/steps/post-task.tsx

@@ -57,6 +57,7 @@ export function PostTaskStep({ state, addLog, goToNext }: StepProps) {
                   body: JSON.stringify({
                     task,
                     agentId: leadAgentId || undefined,
+                    routingReason: leadAgentId ? "skill" : undefined,
                   }),
                 });
                 if (!res.ok) {

package/src/github/handlers.ts

@@ -257,6 +257,7 @@ export async function handlePullRequest(
 
     const task = await createTaskWithSiblingAwareness(result.text, {
       agentId: lead?.id ?? "",
+      routingReason: lead ? "skill" : undefined,
       source: "github",
       vcsProvider: "github",
       taskType: "github-pr",
@@ -370,6 +371,7 @@ export async function handlePullRequest(
 
     const task = await createTaskWithSiblingAwareness(result.text, {
       agentId: lead?.id ?? "",
+      routingReason: lead ? "skill" : undefined,
       source: "github",
       vcsProvider: "github",
       taskType: "github-pr",
@@ -478,6 +480,7 @@ export async function handlePullRequest(
 
     const task = await createTaskWithSiblingAwareness(result.text, {
       agentId: lead?.id ?? "",
+      routingReason: lead ? "skill" : undefined,
       source: "github",
       vcsProvider: "github",
       taskType: "github-pr",
@@ -573,6 +576,7 @@ export async function handlePullRequest(
   // Create task (assigned to lead if available, otherwise unassigned)
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "github",
     vcsProvider: "github",
     taskType: "github-pr",
@@ -657,6 +661,7 @@ export async function handleIssue(
 
     const task = await createTaskWithSiblingAwareness(result.text, {
       agentId: lead?.id ?? "",
+      routingReason: lead ? "skill" : undefined,
       source: "github",
       vcsProvider: "github",
       taskType: "github-issue",
@@ -758,6 +763,7 @@ export async function handleIssue(
 
     const task = await createTaskWithSiblingAwareness(result.text, {
       agentId: lead?.id ?? "",
+      routingReason: lead ? "skill" : undefined,
       source: "github",
       vcsProvider: "github",
       taskType: "github-issue",
@@ -835,6 +841,7 @@ export async function handleIssue(
   // Create task (assigned to lead if available, otherwise unassigned)
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "github",
     vcsProvider: "github",
     taskType: "github-issue",
@@ -946,6 +953,7 @@ export async function handleComment(
   // Create task (assigned to lead if available, otherwise unassigned)
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "github",
     vcsProvider: "github",
     taskType: "github-comment",
@@ -1260,6 +1268,7 @@ export async function handlePullRequestReview(
   // Create task (assigned to lead if available, otherwise unassigned)
   const task = await createTaskWithSiblingAwareness(result.text, {
     agentId: lead?.id ?? "",
+    routingReason: lead ? "skill" : undefined,
     source: "github",
     vcsProvider: "github",
     taskType: "github-review",

package/src/gitlab/handlers.ts

@@ -175,6 +175,7 @@ export async function handleMergeRequest(
 
       const task = await createTaskWithSiblingAwareness(result.text, {
         agentId: lead?.id ?? null,
+        routingReason: lead ? "skill" : undefined,
         source: "gitlab",
         vcsProvider: "gitlab",
         taskType: "gitlab-mr",
@@ -282,6 +283,7 @@ export async function handleIssue(
 
       const task = await createTaskWithSiblingAwareness(result.text, {
         agentId: lead?.id ?? null,
+        routingReason: lead ? "skill" : undefined,
         source: "gitlab",
         vcsProvider: "gitlab",
         taskType: "gitlab-issue",
@@ -385,6 +387,7 @@ export async function handleNote(event: NoteEvent): Promise<{ created: boolean;
 
   const task = await createTaskWithSiblingAwareness(noteResult.text, {
     agentId: lead?.id ?? null,
+    routingReason: lead ? "skill" : undefined,
     source: "gitlab",
     vcsProvider: "gitlab",
     taskType: "gitlab-comment",
@@ -465,6 +468,7 @@ export async function handlePipeline(
 
   const task = await createTaskWithSiblingAwareness(pipelineResult.text, {
     agentId: lead?.id ?? null,
+    routingReason: lead ? "skill" : undefined,
     source: "gitlab",
     vcsProvider: "gitlab",
     taskType: "gitlab-ci",

package/src/heartbeat/heartbeat.ts

@@ -760,6 +760,12 @@ export async function runRebootSweep(): Promise<void> {
           const retryTask = await createTaskExtended(task.task, {
             parentTaskId: task.id,
             agentId: preferredAgentId,
+            routingReason:
+              preferredAgentId === undefined
+                ? undefined
+                : preferredAgentId === task.agentId
+                  ? "continuity"
+                  : "reroute_fault",
             tags,
             priority: task.priority,
             source: task.source,
@@ -1368,6 +1374,7 @@ export async function checkHeartbeatChecklist(): Promise<void> {
 
   await createTaskExtended(result.text, {
     agentId: lead.id,
+    routingReason: "skill",
     taskType: "heartbeat-checklist",
     tags: ["checklist", "auto-generated"],
     priority: 60,
@@ -1584,6 +1591,7 @@ export async function createBootTriageTask(): Promise<void> {
 
   await createTaskExtended(result.text, {
     agentId: lead.id,
+    routingReason: "skill",
     taskType: "boot-triage",
     tags: ["boot", "triage", "auto-generated"],
     priority: 70, // Higher than regular checklist (60)

package/src/http/approval-requests.ts

@@ -385,6 +385,7 @@ export async function handleApprovalRequests(
 
         await createTaskExtended(taskText, {
           agentId: sourceTask.agentId,
+          routingReason: sourceTask.agentId ? "continuity" : undefined,
           parentTaskId: updated.sourceTaskId,
           source: "system",
           taskType: "hitl-follow-up",

package/src/http/apps.ts

@@ -1413,6 +1413,7 @@ export async function handleApps(
     const task = await createTaskWithSiblingAwareness(taskPrompt.text, {
       source: "api",
       agentId: action.agentId ?? lead?.id,
+      routingReason: action.agentId ? "human_pinned" : lead ? "skill" : undefined,
       // App-spawned tasks group under the app's asset namespace so a
       // swarm-tasks source can pull them back via config.assetKey.
       key: normalizeAssetKey(`shared/app:${app.id}/action:${parsed.params.name}/`),

package/src/http/config.ts

@@ -48,11 +48,19 @@ function singleHeader(req: IncomingMessage, name: string): string | undefined {
   return Array.isArray(raw) ? raw[0] : raw;
 }
 
-async function userMayReadSecrets(req: IncomingMessage): Promise<boolean> {
+async function requestMayReadSecrets(req: IncomingMessage): Promise<boolean> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator") return true;
-  // Agent/no-user HTTP reads keep their pre-RBAC behavior; MCP get-config has
-  // the per-agent config.read.secrets gate.
+  if (auth?.kind === "agent") {
+    const agent = await getAgentById(auth.agentId);
+    return can({
+      principal: { kind: "agent", agentId: auth.agentId, isLead: agent?.isLead ?? false },
+      verb: "config.read.secrets",
+      resource: { kind: "none" },
+      source: "http",
+    }).allow;
+  }
+  // Preserve legacy reads without a user or session-token principal.
   if (auth?.kind !== "user") return true;
   if (!isRbacEnabled()) return true;
 
@@ -61,7 +69,7 @@ async function userMayReadSecrets(req: IncomingMessage): Promise<boolean> {
 }
 
 async function resolveSecretsRead(req: IncomingMessage, includeSecrets: boolean) {
-  if (!includeSecrets || (await userMayReadSecrets(req))) {
+  if (!includeSecrets || (await requestMayReadSecrets(req))) {
     return { effectiveIncludeSecrets: includeSecrets, secretsNote: "" };
   }
   return { effectiveIncludeSecrets: false, secretsNote: SECRETS_FORCE_MASK_NOTE };
@@ -75,7 +83,8 @@ async function resolveSecretsRead(req: IncomingMessage, includeSecrets: boolean)
  * operator/user-before-agent ordering used by fs.ts (Appendix A row 36). This
  * preserves every existing HTTP caller (dashboard, codex-oauth token refresh,
  * devin playbook cache — all operate as operator). Only an agent-context
- * principal (X-Agent-ID without operator/user request auth) is gated to lead;
+ * principal is gated to lead, using the authenticated session identity ahead
+ * of the legacy X-Agent-ID fallback;
  * the real per-agent enforcement lives on the MCP set-config/delete-config
  * tools, where the principal is always an agent.
  *
@@ -89,7 +98,7 @@ async function ensureConfigAdmin(
 ): Promise<boolean> {
   const auth = getRequestAuth(req);
   if (auth?.kind === "operator" || auth?.kind === "user") return true;
-  const agentId = singleHeader(req, "x-agent-id");
+  const agentId = auth?.kind === "agent" ? auth.agentId : singleHeader(req, "x-agent-id");
   const agent = agentId ? await getAgentById(agentId) : undefined;
   const decision = can({
     principal: { kind: "agent", agentId: agentId ?? "", isLead: agent?.isLead ?? false },

package/src/http/mcp.ts

@@ -2,10 +2,12 @@ import { randomUUID } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
-import { getAgentById, getResolvedConfig } from "@/be/db";
+import { getAgentById, getResolvedConfig, getTaskById } from "@/be/db";
 import { createServer } from "@/server";
+import { parseEnvFlag } from "@/utils/env-flag";
 import { getRequestAuth } from "@/utils/request-auth-context";
 import { resolveScriptsOnlyMode } from "@/utils/scripts-only-mode";
+import { parseTaskToolManifest, selectTaskTools } from "@/utils/task-tool-manifest";
 
 export type McpTransportActivity = Record<string, number>;
 export type McpSessionAgents = Record<string, string>;
@@ -196,10 +198,35 @@ export async function handleMcp(
         }
       };
 
-      const configValue = (await getResolvedConfig(agentId)).find(
-        (config) => config.key === "SCRIPTS_ONLY_MCP",
-      )?.value;
+      const configs = await getResolvedConfig(agentId);
+      const configValue = configs.find((config) => config.key === "SCRIPTS_ONLY_MCP")?.value;
+      const preloadEnabled = parseEnvFlag(
+        configs.find((config) => config.key === "TASK_TOOL_PRELOAD_ENABLED")?.value ??
+          process.env.TASK_TOOL_PRELOAD_ENABLED,
+        false,
+      );
+      let preloadedTools: string[] = [];
+      if (preloadEnabled) {
+        const taskId = headerValue(req.headers["x-source-task-id"]);
+        const task = taskId ? await getTaskById(taskId) : undefined;
+        // Never select a manifest using another agent's task. Session-token
+        // identity is also checked above, before any MCP session is created.
+        if (task?.agentId === agentId) {
+          const manifestValue =
+            configs.find((config) => config.key === "TASK_TOOL_MANIFESTS")?.value ??
+            process.env.TASK_TOOL_MANIFESTS ??
+            "{}";
+          try {
+            preloadedTools = selectTaskTools(parseTaskToolManifest(manifestValue), task);
+          } catch {
+            // An invalid deployment value must not prevent tool discovery.
+            // Avoid logging its contents, which may contain misfiled secrets.
+            console.warn("[MCP] Invalid TASK_TOOL_MANIFESTS; using ordinary tool discovery");
+          }
+        }
+      }
       const server = await createServer({
+        preloadedTools,
         scriptsOnly: resolveScriptsOnlyMode({
           env: process.env.SCRIPTS_ONLY_MCP,
           configValue,

package/src/http/script-runs.ts

@@ -30,6 +30,7 @@ import {
 } from "../script-workflows/supervisor";
 import {
   AgentTaskStatusSchema,
+  RoutingReasonSchema,
   ScriptRunJournalEntrySchema,
   ScriptRunListItemSchema,
   ScriptRunSchema,
@@ -92,6 +93,8 @@ const agentTaskBodySchema = z.object({
   template: z.string().optional(),
   task: z.string().optional(),
   agentId: z.string().optional(),
+  routingReason: RoutingReasonSchema.optional(),
+  routingNote: z.string().max(200).optional(),
   tags: z.array(z.string()).optional(),
   priority: z.number().int().min(0).max(100).optional(),
   offerMode: z.boolean().optional(),
@@ -619,6 +622,9 @@ export async function handleScriptRuns(
         parsed.body.template ?? parsed.body.task ?? parsed.body.stepKey,
         {
           agentId: parsed.body.agentId,
+          routingReason:
+            parsed.body.routingReason ?? (parsed.body.agentId ? "human_pinned" : undefined),
+          routingNote: parsed.body.routingNote,
           tags: parsed.body.tags,
           priority: parsed.body.priority,
           offeredTo: parsed.body.offerMode ? parsed.body.agentId : undefined,

package/src/http/tasks.ts

@@ -59,6 +59,7 @@ import {
   ProviderNameSchema,
   ReasoningEffortSchema,
   ResumeReasonSchema,
+  RoutingReasonSchema,
   SteeringMessageSchema,
   SteeringSourceSchema,
   SteerModeSchema,
@@ -216,33 +217,45 @@ const createTask = route({
   pattern: ["api", "tasks"],
   summary: "Create a new task",
   tags: ["Tasks"],
-  body: z.object({
-    task: z.string().min(1),
-    agentId: z.string().optional(),
-    taskType: z.string().optional(),
-    tags: z.array(z.string()).optional(),
-    priority: z.number().int().min(0).max(100).optional(),
-    dependsOn: z.array(z.string()).optional(),
-    offeredTo: z.string().optional(),
-    dir: z.string().optional(),
-    parentTaskId: z.string().optional(),
-    key: AssetKeySchema.optional(),
-    source: AgentTaskSourceSchema.optional(),
-    outputSchema: z.record(z.string(), z.unknown()).optional(),
-    contextKey: z.string().optional(),
-    requestedByUserId: z.string().optional(),
-    model: z.string().optional(),
-    modelTier: ModelTierSchema.optional(),
-    effort: ReasoningEffortSchema.optional(),
-    /**
-     * Create in `draft` status instead of the normal pending/unassigned/offered
-     * status (#1240) — the task exists and is visible to its owner, but is not
-     * dispatch-eligible. Used by the UI composer while attachments are still
-     * uploading; the caller MUST promote it via `POST /api/tasks/{id}/promote-draft`
-     * once the upload batch settles (or it self-promotes on a timeout).
-     */
-    draft: z.boolean().optional(),
-  }),
+  body: z
+    .object({
+      task: z.string().min(1),
+      agentId: z.string().optional(),
+      routingReason: RoutingReasonSchema.optional(),
+      routingNote: z.string().max(200).optional(),
+      taskType: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      priority: z.number().int().min(0).max(100).optional(),
+      dependsOn: z.array(z.string()).optional(),
+      offeredTo: z.string().optional(),
+      dir: z.string().optional(),
+      parentTaskId: z.string().optional(),
+      key: AssetKeySchema.optional(),
+      source: AgentTaskSourceSchema.optional(),
+      outputSchema: z.record(z.string(), z.unknown()).optional(),
+      contextKey: z.string().optional(),
+      requestedByUserId: z.string().optional(),
+      model: z.string().optional(),
+      modelTier: ModelTierSchema.optional(),
+      effort: ReasoningEffortSchema.optional(),
+      /**
+       * Create in `draft` status instead of the normal pending/unassigned/offered
+       * status (#1240) — the task exists and is visible to its owner, but is not
+       * dispatch-eligible. Used by the UI composer while attachments are still
+       * uploading; the caller MUST promote it via `POST /api/tasks/{id}/promote-draft`
+       * once the upload batch settles (or it self-promotes on a timeout).
+       */
+      draft: z.boolean().optional(),
+    })
+    .superRefine((body, ctx) => {
+      if ((body.agentId !== undefined || body.offeredTo !== undefined) && !body.routingReason) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "routingReason is required when agentId or offeredTo is supplied.",
+          path: ["routingReason"],
+        });
+      }
+    }),
   responses: {
     201: { description: "Task created", schema: AgentTaskSchema },
     400: { description: "Validation error" },
@@ -804,11 +817,12 @@ export async function handleTasks(
       if (lead) defaultAgentId = lead.id;
     }
 
+    const parentTask = parsed.body.parentTaskId
+      ? await getTaskById(parsed.body.parentTaskId)
+      : null;
     let assetKey: string | undefined;
     try {
-      const inheritedKey = parsed.body.parentTaskId
-        ? (await getTaskById(parsed.body.parentTaskId))?.key
-        : undefined;
+      const inheritedKey = parentTask?.key;
       const requestedKey = parsed.body.key ?? inheritedKey;
       assetKey = requestedKey
         ? await authorizeAssetKeyWrite(requestedKey, trustedUserId)
@@ -825,6 +839,14 @@ export async function handleTasks(
       const task = await createTaskWithSiblingAwareness(parsed.body.task, {
         key: assetKey,
         agentId: defaultAgentId,
+        routingReason:
+          parsed.body.routingReason ??
+          (defaultAgentId
+            ? parentTask?.agentId === defaultAgentId
+              ? "continuity"
+              : "skill"
+            : undefined),
+        routingNote: parsed.body.routingNote,
         creatorAgentId: myAgentId || undefined,
         taskType: parsed.body.taskType || undefined,
         tags: parsed.body.tags || undefined,