@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -324,6 +324,8 @@ declare module "swarm-sdk" {
       types?: Array<"public" | "private" | "dm" | "mpim">;
       limit?: number;
     }): Promise<unknown>;
+    // --- chat sdk ---
+    chat_readThread(args: { threadId: string; limit?: number }): Promise<unknown>;
     // --- messaging ---
     message_read(args?: {
       channel?: string;
@@ -333,13 +335,6 @@ declare module "swarm-sdk" {
       mentionsOnly?: boolean;
       markAsRead?: boolean;
     }): Promise<unknown>;
-    // --- services ---
-    service_list(args?: {
-      agentId?: string;
-      name?: string;
-      status?: "starting" | "healthy" | "unhealthy" | "stopped";
-      includeOwn?: boolean;
-    }): Promise<unknown>;
     // --- context / profiles ---
     context_history(args?: {
       agentId?: string;
@@ -434,6 +429,7 @@ declare module "swarm-sdk" {
       scope?: "global" | "agent" | "repo";
       scopeId?: string;
       isSecret?: boolean;
+      exportToEnv?: boolean;
     }): Promise<unknown>;
     config_delete(args: { id: string }): Promise<unknown>;
 
@@ -474,20 +470,36 @@ declare module "swarm-sdk" {
     slack_delete(args: { channelId: string; messageTs: string }): Promise<unknown>;
     slack_update(args: { channelId: string; messageTs: string; message: string }): Promise<unknown>;
 
+    // --- write: chat sdk ---
+    chat_reply(args: { text: string }): Promise<unknown>;
+    chat_post(args: {
+      adapter: "telegram" | "slack" | "discord" | "teams";
+      threadId?: string;
+      channelId?: string;
+      text: string;
+    }): Promise<unknown>;
+    chat_openDm(args: {
+      adapter: "telegram" | "slack" | "discord" | "teams";
+      userId: string;
+    }): Promise<unknown>;
+    chat_registerChannel(args: {
+      adapter: "telegram" | "slack" | "discord" | "teams";
+      channelId: string;
+      agentId?: string;
+      workflowId?: string;
+      name?: string;
+    }): Promise<unknown>;
+    chat_unregisterChannel(args: {
+      adapter: "telegram" | "slack" | "discord" | "teams";
+      channelId: string;
+    }): Promise<unknown>;
+
     // --- write: messaging (internal) ---
     message_post(args: { channel?: string; content: string; to?: string }): Promise<unknown>;
 
     // --- write: profiles ---
     profile_update(args: Record<string, unknown>): Promise<unknown>;
 
-    // --- write: services ---
-    service_register(args: Record<string, unknown>): Promise<unknown>;
-    service_unregister(args: { name: string }): Promise<unknown>;
-    service_updateStatus(args: {
-      name: string;
-      status: "starting" | "healthy" | "unhealthy" | "stopped";
-    }): Promise<unknown>;
-
     // --- write: schedules ---
     schedule_create(args: Record<string, unknown>): Promise<unknown>;
     schedule_update(args: Record<string, unknown>): Promise<unknown>;

package/src/server.ts

@@ -6,6 +6,7 @@ import { startPricingRefreshLoop } from "./be/pricing-refresh";
 import { isSteeringEnabled } from "./be/steering";
 import { registerGithubTaskReactions } from "./github/task-reactions";
 import { loadGlobalConfigsIntoEnv } from "./http/core";
+import { isChatSdkEnabled } from "./integrations/chat-sdk/config";
 import { resolveTemplate } from "./prompts/resolver";
 import { isRbacEnabled } from "./rbac";
 import { getSlackConfiguration } from "./slack/config";
@@ -21,6 +22,10 @@ import { registerAppSyncTool } from "./tools/app-sync";
 import { registerAppUpsertTool } from "./tools/app-upsert";
 import { registerCancelApprovalRequestTool } from "./tools/cancel-approval-request";
 import { registerCancelTaskTool } from "./tools/cancel-task";
+import { registerChatOpenDmTool } from "./tools/chat-open-dm";
+import { registerChatPostTool } from "./tools/chat-post";
+import { registerChatReadThreadTool } from "./tools/chat-read-thread";
+import { registerChatReplyTool } from "./tools/chat-reply";
 import { registerContextDiffTool } from "./tools/context-diff";
 import { registerContextHistoryTool } from "./tools/context-history";
 import { registerCreateChannelTool } from "./tools/create-channel";
@@ -54,7 +59,6 @@ import {
 } from "./tools/kv";
 // Messaging capability
 import { registerListChannelsTool } from "./tools/list-channels";
-import { registerListServicesTool } from "./tools/list-services";
 import { registerManageUserTool } from "./tools/manage-user";
 // MCP Servers capability
 import {
@@ -91,12 +95,15 @@ import {
 } from "./tools/prompt-templates";
 import { registerReadMessagesTool } from "./tools/read-messages";
 import { registerRegisterAgentmailInboxTool } from "./tools/register-agentmail-inbox";
+import {
+  registerRegisterChatChannelTool,
+  registerUnregisterChatChannelTool,
+} from "./tools/register-chat-channel";
 import {
   registerRegisterKapsoNumberTool,
   registerUnregisterKapsoNumberTool,
 } from "./tools/register-kapso-number";
 // Services capability
-import { registerRegisterServiceTool } from "./tools/register-service";
 // Repo management tools
 import { registerGetReposTool, registerUpdateRepoTool } from "./tools/repos";
 import { registerRequestHumanInputTool } from "./tools/request-human-input";
@@ -178,10 +185,8 @@ import {
   registerTrackerSyncStatusTool,
   registerTrackerUnlinkTool,
 } from "./tools/tracker";
-import { registerUnregisterServiceTool } from "./tools/unregister-service";
 // Profiles capability
 import { registerUpdateProfileTool } from "./tools/update-profile";
-import { registerUpdateServiceStatusTool } from "./tools/update-service-status";
 import { setPreloadedTools } from "./tools/utils";
 import {
   registerReplyWhatsappMessageTool,
@@ -216,7 +221,6 @@ export const ALL_CAPABILITIES = [
   "prompt-templates",
   "mcp",
   "profiles",
-  "services",
   "scheduling",
   "memory",
   "workflows",
@@ -230,6 +234,7 @@ export const ALL_CAPABILITIES = [
   "repo",
   "agentmail",
   "kapso",
+  "chat-sdk",
   "swarm-x",
 ] as const;
 
@@ -256,12 +261,12 @@ const DEFAULT_CAPABILITIES: string = [
   //
   // Disabled by default
   //
-  // "services",
   // "prompt-templates",
   // "messaging",
   // "swarm-x",
   // "agentmail",
   // "kapso",
+  // "chat-sdk", (added by getEnabledCapabilities when CHAT_SDK_ENABLED is true)
 ].join(",");
 
 // Note: unknown names are kept (they never match hasCapability); workers
@@ -280,11 +285,22 @@ export function hasCapability(cap: CAPABILITIES_T): boolean {
   return getCapabilities().has(cap);
 }
 
+const KNOWN_CAPABILITIES: ReadonlySet<string> = new Set(ALL_CAPABILITIES);
+
 export function getEnabledCapabilities(): CAPABILITIES_T[] {
-  const capabilities = Array.from(getCapabilities());
+  // Only known flags: the register response validates against ALL_CAPABILITIES,
+  // so a retired name still listed in CAPABILITIES (e.g. `services`) would
+  // otherwise turn every agent registration into a 500.
+  const capabilities: CAPABILITIES_T[] = Array.from(getCapabilities()).filter(
+    (capability) => KNOWN_CAPABILITIES.has(capability) && capability !== "chat-sdk",
+  );
+  // The Chat SDK channel follows CHAT_SDK_ENABLED, not the CAPABILITIES list.
+  if (isChatSdkEnabled()) capabilities.push("chat-sdk");
   // Phase 1 has no HTTP receiver. Do not advertise usable Slack tools to
-  // workers when HTTP (or an invalid transport) was selected.
-  return getSlackConfiguration().mode === "socket"
+  // workers when HTTP (or an invalid transport) was selected, or when the
+  // built-in Slack app is off (SLACK_DISABLE, required by the Chat SDK Slack adapter).
+  const slack = getSlackConfiguration();
+  return slack.mode === "socket" && !slack.disabled
     ? capabilities
     : capabilities.filter((capability) => capability !== "slack");
 }
@@ -344,6 +360,13 @@ function applyToolAllowlist(server: McpServer, allowlist: readonly string[]): vo
   }
 }
 
+function removeTools(server: McpServer, names: readonly string[]): void {
+  // oxlint-disable-next-line anti-slop/no-chained-type-assertions -- the MCP SDK keeps its tool registry private.
+  const tools = (server as unknown as { _registeredTools: Record<string, { remove(): void }> })
+    ._registeredTools;
+  for (const name of names) tools[name]?.remove();
+}
+
 export async function createServer(
   opts: {
     scriptsOnly?: boolean;
@@ -351,6 +374,8 @@ export async function createServer(
     preloadedTools?: readonly string[];
     /** Raw SWARM_ENABLED_TOOLS value for this session; defaults to the env. */
     enabledTools?: string;
+    /** Tool names removed from this session after registration (task-context filters). */
+    excludedTools?: readonly string[];
   } = {},
 ) {
   // Reload env
@@ -368,8 +393,12 @@ export async function createServer(
   // fullSurface to register every tool group regardless of CAPABILITIES.
   // An allowlist also registers every group, then prunes to the listed names.
   // This shadows the module-level hasCapability for the registrations below.
+  // `chat-sdk` follows CHAT_SDK_ENABLED (as in getEnabledCapabilities), not
+  // the CAPABILITIES list.
   const hasCapability = (cap: CAPABILITIES_T): boolean =>
-    opts.fullSurface === true || toolAllowlist !== undefined || getCapabilities().has(cap);
+    opts.fullSurface === true ||
+    toolAllowlist !== undefined ||
+    (cap === "chat-sdk" ? isChatSdkEnabled() : getCapabilities().has(cap));
 
   // Initialize database with WAL mode
   // Uses DATABASE_PATH env var for Docker volume compatibility (WAL needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
@@ -677,6 +706,16 @@ export async function createServer(
     registerReplyWhatsappMessageTool(server);
   }
 
+  // Chat SDK capability - Telegram/Slack/Discord/Teams through the Chat SDK channel (reply, post, DM, read, channel routes)
+  if (hasCapability("chat-sdk")) {
+    registerChatReplyTool(server);
+    registerChatPostTool(server);
+    registerChatOpenDmTool(server);
+    registerChatReadThreadTool(server);
+    registerRegisterChatChannelTool(server);
+    registerUnregisterChatChannelTool(server);
+  }
+
   // Swarm-x capability - external command routes mirroring the `agent-swarm x ...` CLI surface
   if (hasCapability("swarm-x")) {
     registerSwarmXTool(server);
@@ -693,15 +732,10 @@ export async function createServer(
     registerDeleteChannelTool(server);
   }
 
-  // Services capability - PM2/background service registry
-  if (hasCapability("services")) {
-    registerRegisterServiceTool(server);
-    registerUnregisterServiceTool(server);
-    registerListServicesTool(server);
-    registerUpdateServiceStatusTool(server);
-  }
-
   if (toolAllowlist) applyToolAllowlist(server, toolAllowlist);
+  if (opts.fullSurface !== true && opts.excludedTools?.length) {
+    removeTools(server, opts.excludedTools);
+  }
 
   return server;
 }

package/src/slack/actions.ts

@@ -1,10 +1,11 @@
 import type { App } from "@slack/bolt";
-import type { ChatUpdateArguments } from "@slack/web-api";
+import type { ChatUpdateArguments, WebClient } from "@slack/web-api";
 import { cancelTask, getAgentById, getLeadAgent, getTaskById } from "../be/db";
 import { slackContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { buildCancelledBlocks, getTaskLink } from "./blocks";
 import { resolveSlackUserId } from "./enrich";
+import { EXTERNAL_CHANNEL_BLOCKED_REPLY, shouldBlockChannel } from "./external-channel";
 import { ignoreSlackInbound, noteSlackInboundSideEffect } from "./inbound-dispatch";
 import { ensureSlackThreadTree, isSlackRenderV2Enabled } from "./render-v2";
 import { getAgentDisplayName, getAgentEmoji } from "./responses";
@@ -14,6 +15,22 @@ type ChatUpdatePayload = ChatUpdateArguments & {
   unfurl_media: false;
 };
 
+async function postExternalChannelNotice(
+  client: WebClient,
+  channelId: string,
+  userId: string,
+): Promise<void> {
+  try {
+    await client.chat.postEphemeral({
+      channel: channelId,
+      user: userId,
+      text: EXTERNAL_CHANNEL_BLOCKED_REPLY,
+    });
+  } catch (error) {
+    console.error("[Slack] Failed to post external channel notice:", error);
+  }
+}
+
 export function registerActionHandlers(app: App): void {
   // "View Full Logs" — URL button, just ack (Slack opens the link automatically)
   app.action("view_task_logs", async ({ ack }) => {
@@ -31,6 +48,12 @@ export function registerActionHandlers(app: App): void {
     const triggerId = "trigger_id" in body ? body.trigger_id : undefined;
     if (!triggerId) return;
 
+    const channelId = "channel" in body ? body.channel?.id : undefined;
+    if (channelId && (await shouldBlockChannel(client, channelId))) {
+      await postExternalChannelNotice(client, channelId, body.user.id);
+      return ignoreSlackInbound("external_channel");
+    }
+
     try {
       await client.views.open({
         trigger_id: triggerId,
@@ -78,6 +101,11 @@ export function registerActionHandlers(app: App): void {
       return ignoreSlackInbound("follow_up_target_missing");
     }
 
+    if (await shouldBlockChannel(client, originalTask.slackChannelId)) {
+      await postExternalChannelNotice(client, originalTask.slackChannelId, body.user.id);
+      return ignoreSlackInbound("external_channel");
+    }
+
     const lead = await getLeadAgent();
     // Resolve via the shared cascade. Sample context = the modal callback ID
     // so operators can see *which* modal-submit triggered an unmapped entry.

package/src/slack/app.ts

@@ -1,8 +1,10 @@
 import { App, LogLevel, SocketModeReceiver } from "@slack/bolt";
 import { emitBuiltInIntegrationConnectedOnce, ensureSlackRenderV2Activation } from "../be/db";
+import { getNodeEnv } from "../utils/node-env";
 import { getSlackConfiguration } from "./config";
 import { type SlackConnectionState, setSlackConnectionState } from "./connection-state";
 import { installSlackEgressScrub } from "./egress-scrub";
+import { installSlackExternalChannelGuard } from "./external-channel-egress";
 import { slackInboundOutcomeMiddleware } from "./inbound-dispatch";
 import { getSlackSocketModeBlockReason, SLACK_DEV_SOCKET_MODE_OPT_IN } from "./socket-mode-guard";
 import { startTaskWatcher, stopTaskWatcher } from "./watcher";
@@ -78,13 +80,15 @@ export async function initSlackApp(): Promise<App | null> {
     return null;
   }
 
-  // Every client Bolt builds from here on scrubs outbound text.
+  // Every client Bolt builds from here on scrubs outbound text and refuses
+  // writes to external channels when SLACK_BLOCK_EXTERNAL_CHANNELS is on.
   installSlackEgressScrub();
+  installSlackExternalChannelGuard();
 
   // SLACK_API_URL points Bolt (Web API and apps.connections.open) at a mock Slack server for e2e tests.
   const slackApiUrl = process.env.SLACK_API_URL;
   const clientOptions = slackApiUrl ? { slackApiUrl } : undefined;
-  const logLevel = process.env.NODE_ENV === "development" ? LogLevel.DEBUG : LogLevel.INFO;
+  const logLevel = getNodeEnv() === "development" ? LogLevel.DEBUG : LogLevel.INFO;
   // Build the receiver ourselves so its SocketModeClient lifecycle events can
   // feed /status. Bolt would otherwise forward clientOptions via installerOptions.
   receiver = new SocketModeReceiver({
@@ -123,6 +127,14 @@ export async function initSlackApp(): Promise<App | null> {
   const { createAssistant } = await import("./assistant");
   app.assistant(createAssistant());
 
+  // Report-only scan for external (Slack Connect) channels the bot is already in.
+  const { isBlockExternalEnabled, scanExternalChannelsOnBoot } = await import("./external-channel");
+  if (isBlockExternalEnabled()) {
+    scanExternalChannelsOnBoot(app.client).catch((error) => {
+      console.error("[Slack] External channel boot scan failed:", error);
+    });
+  }
+
   return app;
 }
 

package/src/slack/assistant.ts

@@ -1,10 +1,12 @@
 import { Assistant } from "@slack/bolt";
+import type { WebClient } from "@slack/web-api";
 import { getAgentWorkingOnThread, getLeadAgent, getMostRecentTaskInThread } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
 import { slackContextKey } from "../tasks/context-key";
 import { ackSlackMessage, reactionName } from "./ack";
 import { resolveSlackUserId, rewriteSlackMentions } from "./enrich";
 import { wasEventSeen } from "./event-dedup";
+import { shouldBlockChannel } from "./external-channel";
 import type { SlackFile } from "./files";
 import {
   ignoreSlackInbound,
@@ -32,9 +34,24 @@ const isAdditiveSlack = () => isEnvFlagEnabled("ADDITIVE_SLACK", false);
 // a different agent (e.g. Devin) rather than our bot.
 let cachedBotUserId: string | null = null;
 
+/** Startup and context callbacks write to the thread, so they get the inbound guard too. */
+async function isExternalAssistantThread(
+  client: WebClient,
+  channelId: string,
+  body: unknown,
+): Promise<boolean> {
+  const envelope = (body as { is_ext_shared_channel?: boolean }).is_ext_shared_channel;
+  if (!(await shouldBlockChannel(client, channelId, envelope))) return false;
+  console.log(`[Slack] Ignoring assistant thread event in external channel ${channelId}`);
+  return true;
+}
+
 export function createAssistant(): Assistant {
   return new Assistant({
-    threadStarted: async ({ say, setSuggestedPrompts, saveThreadContext }) => {
+    threadStarted: async ({ event, body, client, say, setSuggestedPrompts, saveThreadContext }) => {
+      if (await isExternalAssistantThread(client, event.assistant_thread.channel_id, body)) {
+        return ignoreSlackInbound("external_channel");
+      }
       try {
         await saveThreadContext();
 
@@ -57,7 +74,10 @@ export function createAssistant(): Assistant {
       }
     },
 
-    threadContextChanged: async ({ saveThreadContext }) => {
+    threadContextChanged: async ({ event, body, client, saveThreadContext }) => {
+      if (await isExternalAssistantThread(client, event.assistant_thread.channel_id, body)) {
+        return ignoreSlackInbound("external_channel");
+      }
       await saveThreadContext();
     },
 
@@ -71,6 +91,20 @@ export function createAssistant(): Assistant {
         return ignoreSlackInbound("duplicate_event");
       }
 
+      // Block external (Slack Connect) channels when SLACK_BLOCK_EXTERNAL_CHANNELS is on.
+      const externalCheckChannel = (message as { channel?: string }).channel;
+      if (
+        externalCheckChannel &&
+        (await shouldBlockChannel(
+          client,
+          externalCheckChannel,
+          (body as { is_ext_shared_channel?: boolean }).is_ext_shared_channel,
+        ))
+      ) {
+        console.log(`[Slack] Ignoring message in external channel ${externalCheckChannel}`);
+        return ignoreSlackInbound("external_channel");
+      }
+
       // Wrap setStatus/setTitle to swallow all errors gracefully.
       // These calls can fail for various reasons (no_permission when the thread
       // wasn't started by the assistant, network errors, etc.), so we log and continue.

package/src/slack/channel-join.ts

@@ -1,6 +1,5 @@
 import type { WebClient } from "@slack/web-api";
-
-const logger = console;
+import { getChannelExternality } from "./external-channel";
 
 type SlackErrorData = {
   error?: unknown;
@@ -36,20 +35,8 @@ export function slackMissingScopeMessage(error: unknown): string | undefined {
  * are the authoritative org-boundary signal per Slack's API docs.
  */
 async function isKnownExternalChannel(client: WebClient, channelId: string): Promise<boolean> {
-  try {
-    const resp = await client.conversations.info({ channel: channelId });
-    const ch = (resp.channel ?? {}) as {
-      is_ext_shared?: boolean;
-      is_pending_ext_shared?: boolean;
-    };
-    return ch.is_ext_shared === true || ch.is_pending_ext_shared === true;
-  } catch (error) {
-    logger.warn(
-      `[Slack] conversations.info failed for ${channelId}; attempting join fallback:`,
-      error,
-    );
-    return false;
-  }
+  // "unknown" (conversations.info failed) falls through to the join attempt.
+  return (await getChannelExternality(client, channelId)) === "external";
 }
 
 /**

package/src/slack/commands.ts

@@ -1,11 +1,19 @@
 import type { App } from "@slack/bolt";
 import { getAllAgents, getAllTasks } from "../be/db";
 import { isEnvFlagEnabled } from "../utils/env-flag";
+import { EXTERNAL_CHANNEL_BLOCKED_REPLY, shouldBlockChannel } from "./external-channel";
 
 export function registerCommandHandler(app: App): void {
-  app.command("/agent-swarm-status", async ({ ack, respond }) => {
+  app.command("/agent-swarm-status", async ({ ack, respond, command, client }) => {
     await ack();
 
+    // The status reply lists task summaries; never show them in an external channel.
+    if (await shouldBlockChannel(client, command.channel_id)) {
+      console.log(`[Slack] Refusing /agent-swarm-status in external channel ${command.channel_id}`);
+      await respond({ response_type: "ephemeral", text: EXTERNAL_CHANNEL_BLOCKED_REPLY });
+      return;
+    }
+
     const agents = await getAllAgents();
     const tasks = await getAllTasks({ status: "in_progress" });
 

package/src/slack/event-dedup.ts

@@ -18,7 +18,7 @@
  * safe-but-tight bound.
  *
  * Single-pod-only. The API server (which owns the Slack socket) runs as a
- * single PM2 process; if that ever changes, swap this for a DB-backed table.
+ * single API process; if that ever changes, swap this for a DB-backed table.
  */
 
 const DEFAULT_TTL_MS = 300_000; // 5 minutes

package/src/slack/external-channel-egress.ts

@@ -0,0 +1,113 @@
+import { webApi } from "@slack/bolt";
+import type { WebClient } from "@slack/web-api";
+import { type ChannelBlockReason, getChannelBlockReason } from "./external-channel";
+
+/**
+ * Client-level external-channel guard for every outbound Slack write.
+ *
+ * Tools, the watcher, render-v2 streaming, outcome cards, progress edits and
+ * alerts all call `client.chat.*` / `filesUploadV2` directly, so the guard sits
+ * on `WebClient` itself, like `egress-scrub.ts`. The prototype is patched
+ * before any client is built, which covers Bolt's `app.client` and the
+ * per-request clients it hands to listeners. A no-op unless
+ * SLACK_BLOCK_EXTERNAL_CHANNELS is on.
+ */
+
+/** Methods that publish content into a channel, and the argument naming it. */
+const GUARDED_METHODS: Record<string, readonly string[]> = {
+  "chat.postMessage": ["channel"],
+  "chat.postEphemeral": ["channel"],
+  "chat.update": ["channel"],
+  "chat.scheduleMessage": ["channel"],
+  "chat.meMessage": ["channel"],
+  "chat.startStream": ["channel"],
+  "chat.appendStream": ["channel"],
+  "chat.stopStream": ["channel"],
+  "assistant.threads.setStatus": ["channel_id"],
+  "assistant.threads.setSuggestedPrompts": ["channel_id"],
+  "assistant.threads.setTitle": ["channel_id"],
+  "files.completeUploadExternal": ["channel_id", "channels"],
+};
+
+/** Slack-shaped error codes, so delivery code classifies them like platform errors. */
+export const EXTERNAL_CHANNEL_BLOCKED_CODE = "external_channel_blocked";
+export const EXTERNAL_CHANNEL_UNVERIFIED_CODE = "external_channel_unverified";
+
+type Args = Record<string, unknown>;
+
+/** Channel IDs named by a write's arguments (`channels` may be comma-separated). */
+function targetChannels(fields: readonly string[], args: Args | undefined): string[] {
+  if (!args) return [];
+  const out: string[] = [];
+  for (const field of fields) {
+    const value = args[field];
+    if (typeof value !== "string") continue;
+    for (const id of value.split(",")) {
+      const trimmed = id.trim();
+      if (trimmed) out.push(trimmed);
+    }
+  }
+  return out;
+}
+
+function blockedError(method: string, channelId: string, reason: ChannelBlockReason): Error {
+  const code =
+    reason === "external" ? EXTERNAL_CHANNEL_BLOCKED_CODE : EXTERNAL_CHANNEL_UNVERIFIED_CODE;
+  const error = new Error(
+    `An API error occurred: ${code} (${method} to ${channelId} refused by SLACK_BLOCK_EXTERNAL_CHANNELS)`,
+  );
+  return Object.assign(error, {
+    code: webApi.ErrorCode.PlatformError,
+    data: { ok: false, error: code },
+  });
+}
+
+async function assertChannelsAllowed(
+  client: WebClient,
+  method: string,
+  channels: string[],
+): Promise<void> {
+  for (const channelId of channels) {
+    const reason = await getChannelBlockReason(client, channelId);
+    if (reason) {
+      console.warn(`[Slack] Refused ${method} to ${channelId} (${reason})`);
+      throw blockedError(method, channelId, reason);
+    }
+  }
+}
+
+const INSTALLED = Symbol.for("agent-swarm.slack-external-channel-guard");
+
+type PatchableProto = {
+  apiCall: (method: string, options?: Args) => Promise<unknown>;
+  filesUploadV2: (options: Args) => Promise<unknown>;
+  [INSTALLED]?: true;
+};
+
+/**
+ * Route every `WebClient` built after this call through the guard. Idempotent.
+ * Call it before the Bolt `App` (and its receiver) are constructed.
+ */
+export function installSlackExternalChannelGuard(): void {
+  // oxlint-disable-next-line anti-slop/no-chained-type-assertions -- we patch private WebClient prototype methods.
+  const proto = webApi.WebClient.prototype as unknown as PatchableProto;
+  if (proto[INSTALLED]) return;
+  const originalApiCall = proto.apiCall;
+  const originalUpload = proto.filesUploadV2;
+  proto.apiCall = async function (this: WebClient, method: string, options?: Args) {
+    const fields = GUARDED_METHODS[method];
+    if (fields) await assertChannelsAllowed(this, method, targetChannels(fields, options));
+    return originalApiCall.call(this, method, options);
+  };
+  // Check before the bytes leave: completeUploadExternal is guarded too, but by
+  // then the file already sits in Slack storage.
+  proto.filesUploadV2 = async function (this: WebClient, options: Args) {
+    await assertChannelsAllowed(
+      this,
+      "files.uploadV2",
+      targetChannels(["channel_id", "channels"], options),
+    );
+    return originalUpload.call(this, options);
+  };
+  proto[INSTALLED] = true;
+}