@openclaw/discord 2026.5.1-beta.1 → 2026.5.2-beta.1

package/openclaw.plugin.json

@@ -193,6 +193,16 @@
           "dangerouslyAllowNameMatching": {
             "type": "boolean"
           },
+          "mentionAliases": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string",
+              "pattern": "^\\d+$"
+            }
+          },
           "groupPolicy": {
             "default": "allowlist",
             "type": "string",
@@ -857,6 +867,16 @@
                 "type": "number",
                 "minimum": 0
               },
+              "spawnSessions": {
+                "type": "boolean"
+              },
+              "defaultSpawnContext": {
+                "type": "string",
+                "enum": [
+                  "isolated",
+                  "fork"
+                ]
+              },
               "spawnSubagentSessions": {
                 "type": "boolean"
               },
@@ -1698,6 +1718,16 @@
                 "dangerouslyAllowNameMatching": {
                   "type": "boolean"
                 },
+                "mentionAliases": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^\\d+$"
+                  }
+                },
                 "groupPolicy": {
                   "default": "allowlist",
                   "type": "string",
@@ -2362,6 +2392,16 @@
                       "type": "number",
                       "minimum": 0
                     },
+                    "spawnSessions": {
+                      "type": "boolean"
+                    },
+                    "defaultSpawnContext": {
+                      "type": "string",
+                      "enum": [
+                        "isolated",
+                        "fork"
+                      ]
+                    },
                     "spawnSubagentSessions": {
                       "type": "boolean"
                     },
@@ -3155,13 +3195,13 @@
           "label": "Discord Thread Binding Max Age (hours)",
           "help": "Optional hard max age in hours for Discord thread-bound sessions. Set 0 to disable hard cap (default: 0). Overrides session.threadBindings.maxAgeHours when set."
         },
-        "threadBindings.spawnSubagentSessions": {
-          "label": "Discord Thread-Bound Subagent Spawn",
-          "help": "Allow subagent spawns with thread=true to auto-create and bind Discord threads (default: false; opt-in). Set true to enable thread-bound subagent spawns for this account/channel."
+        "threadBindings.spawnSessions": {
+          "label": "Discord Thread-Bound Session Spawn",
+          "help": "Allow sessions_spawn(thread=true) and ACP thread spawns to auto-create and bind Discord threads (default: true). Set false to disable for this account/channel."
         },
-        "threadBindings.spawnAcpSessions": {
-          "label": "Discord Thread-Bound ACP Spawn",
-          "help": "Allow /acp spawn to auto-create and bind Discord threads for ACP sessions (default: false; opt-in). Set true to enable thread-bound ACP spawns for this account/channel."
+        "threadBindings.defaultSpawnContext": {
+          "label": "Discord Thread Spawn Context",
+          "help": "Default native subagent context for thread-bound spawns. \"fork\" starts from the requester transcript; \"isolated\" starts clean. Default: \"fork\"."
         },
         "ui.components.accentColor": {
           "label": "Discord Component Accent Color",
@@ -3275,6 +3315,10 @@
           "label": "Discord Allow Bot Messages",
           "help": "Allow bot-authored messages to trigger Discord replies (default: false). Set \"mentions\" to only accept bot messages that mention the bot."
         },
+        "mentionAliases": {
+          "label": "Discord Mention Aliases",
+          "help": "Map outbound @handle text to stable Discord user IDs before sending. Set per account via channels.discord.accounts.<id>.mentionAliases."
+        },
         "token": {
           "label": "Discord Bot Token",
           "help": "Discord bot token used for gateway and REST API authentication for this provider account. Keep this secret out of committed config and rotate immediately after any leak.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/discord",
-  "version": "2026.5.1-beta.1",
+  "version": "2026.5.2-beta.1",
   "description": "OpenClaw Discord channel plugin",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "openclaw": "workspace:*"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.4.25"
+    "openclaw": ">=2026.5.2-beta.1"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -43,6 +43,7 @@
       "blurb": "very well supported right now.",
       "systemImage": "bubble.left.and.bubble.right",
       "markdownCapable": true,
+      "preferSessionLookupForAnnounceTarget": true,
       "commands": {
         "nativeCommandsAutoEnabled": true,
         "nativeSkillsAutoEnabled": true
@@ -63,10 +64,10 @@
       "minHostVersion": ">=2026.4.10"
     },
     "compat": {
-      "pluginApi": ">=2026.4.25"
+      "pluginApi": ">=2026.5.2-beta.1"
     },
     "build": {
-      "openclawVersion": "2026.5.1-beta.1"
+      "openclawVersion": "2026.5.2-beta.1"
     },
     "release": {
       "publishToClawHub": true,

package/src/actions/handle-action.test.ts

@@ -125,6 +125,127 @@ describe("handleDiscordMessageAction", () => {
     );
   });
 
+  it("maps upload-file to Discord sendMessage with media read context", async () => {
+    const mediaReadFile = vi.fn(async () => Buffer.from("image"));
+    const mediaAccess = {
+      localRoots: ["/tmp/agent-root"],
+      readFile: mediaReadFile,
+    };
+
+    await handleDiscordMessageAction({
+      action: "upload-file",
+      params: {
+        target: "channel:123",
+        filePath: "/tmp/agent-root/image.png",
+        message: "caption",
+        filename: "image.png",
+        replyTo: "message-1",
+        silent: true,
+        __sessionKey: "session-1",
+        __agentId: "agent-1",
+      },
+      cfg: {
+        channels: { discord: { token: "tok" } },
+      } as OpenClawConfig,
+      mediaAccess,
+      mediaLocalRoots: ["/tmp/agent-root"],
+      mediaReadFile,
+    });
+
+    expect(handleDiscordActionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "channel:123",
+        content: "caption",
+        mediaUrl: "/tmp/agent-root/image.png",
+        filename: "image.png",
+        replyTo: "message-1",
+        silent: true,
+        __sessionKey: "session-1",
+        __agentId: "agent-1",
+      }),
+      expect.any(Object),
+      {
+        mediaAccess,
+        mediaLocalRoots: ["/tmp/agent-root"],
+        mediaReadFile,
+      },
+    );
+  });
+
+  it("falls back to Discord toolContext.currentChannelId for upload-file", async () => {
+    await handleDiscordMessageAction({
+      action: "upload-file",
+      params: {
+        path: "/tmp/agent-root/image.png",
+      },
+      cfg: {
+        channels: { discord: { token: "tok" } },
+      } as OpenClawConfig,
+      toolContext: {
+        currentChannelProvider: "discord",
+        currentChannelId: "channel:123",
+      },
+    });
+
+    expect(handleDiscordActionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "channel:123",
+        content: "",
+        mediaUrl: "/tmp/agent-root/image.png",
+      }),
+      expect.any(Object),
+      expect.any(Object),
+    );
+  });
+
+  it("requires a file path for upload-file", async () => {
+    await expect(
+      handleDiscordMessageAction({
+        action: "upload-file",
+        params: {
+          to: "channel:123",
+        },
+        cfg: {
+          channels: { discord: { token: "tok" } },
+        } as OpenClawConfig,
+      }),
+    ).rejects.toThrow(/upload-file requires filePath, path, or media/i);
+
+    expect(handleDiscordActionMock).not.toHaveBeenCalled();
+  });
+
+  it("forwards top-level components on sends", async () => {
+    const components = { blocks: [{ type: "text", text: "Pick one" }] };
+
+    await handleDiscordMessageAction({
+      action: "send",
+      params: {
+        message: "hello",
+        components,
+      },
+      cfg: {
+        channels: { discord: { token: "tok" } },
+      } as OpenClawConfig,
+      toolContext: {
+        currentChannelProvider: "discord",
+        currentChannelId: "channel:123",
+      },
+    });
+
+    expect(handleDiscordActionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "sendMessage",
+        to: "channel:123",
+        content: "hello",
+        components,
+      }),
+      expect.any(Object),
+      expect.any(Object),
+    );
+  });
+
   it("does not use another provider's current target for Discord sends", async () => {
     await expect(
       handleDiscordMessageAction({

package/src/actions/handle-action.ts

@@ -66,32 +66,37 @@ export async function handleDiscordMessageAction(
     return target;
   };
   const resolveChannelId = () => resolveDiscordChannelId(readTarget());
-
-  if (action === "send") {
-    const to =
+  const readSendTarget = () => {
+    const target =
       readStringParam(params, "to") ??
       readStringParam(params, "target") ??
       readCurrentDiscordTarget(ctx.toolContext);
-    if (!to) {
+    if (!target) {
       throw new Error("Discord channel target is required (use channel:<id>).");
     }
+    return target;
+  };
+
+  if (action === "send") {
+    const to = readSendTarget();
     const asVoice = readBooleanParam(params, "asVoice") === true;
     const rawComponents =
+      params.components ??
       buildDiscordPresentationComponents(normalizeMessagePresentation(params.presentation)) ??
       buildDiscordInteractiveComponents(normalizeInteractiveReply(params.interactive));
     const hasComponents =
       Boolean(rawComponents) &&
       (typeof rawComponents === "function" || typeof rawComponents === "object");
     const components = hasComponents ? rawComponents : undefined;
-    const content = readStringParam(params, "message", {
-      required: !asVoice && !hasComponents,
-      allowEmpty: true,
-    });
     // Support media, path, and filePath for media URL
     const mediaUrl =
       readStringParam(params, "media", { trim: false }) ??
       readStringParam(params, "path", { trim: false }) ??
       readStringParam(params, "filePath", { trim: false });
+    const content = readStringParam(params, "message", {
+      required: !asVoice && !hasComponents && !mediaUrl,
+      allowEmpty: true,
+    });
     const filename = readStringParam(params, "filename");
     const replyTo = readStringParam(params, "replyTo");
     const rawEmbeds = params.embeds;
@@ -104,7 +109,7 @@ export async function handleDiscordMessageAction(
         action: "sendMessage",
         accountId: accountId ?? undefined,
         to,
-        content,
+        content: content ?? "",
         mediaUrl: mediaUrl ?? undefined,
         filename: filename ?? undefined,
         replyTo: replyTo ?? undefined,
@@ -120,6 +125,41 @@ export async function handleDiscordMessageAction(
     );
   }
 
+  if (action === "upload-file") {
+    const to = readSendTarget();
+    const mediaUrl =
+      readStringParam(params, "filePath", { trim: false }) ??
+      readStringParam(params, "path", { trim: false }) ??
+      readStringParam(params, "media", { trim: false });
+    if (!mediaUrl) {
+      throw new Error("upload-file requires filePath, path, or media.");
+    }
+    const content =
+      readStringParam(params, "message", { allowEmpty: true }) ??
+      readStringParam(params, "content", { allowEmpty: true });
+    const filename = readStringParam(params, "filename");
+    const replyTo = readStringParam(params, "replyTo");
+    const silent = readBooleanParam(params, "silent") === true;
+    const sessionKey = readStringParam(params, "__sessionKey");
+    const agentId = readStringParam(params, "__agentId");
+    return await handleDiscordAction(
+      {
+        action: "sendMessage",
+        accountId: accountId ?? undefined,
+        to,
+        content: content ?? "",
+        mediaUrl,
+        filename: filename ?? undefined,
+        replyTo: replyTo ?? undefined,
+        silent,
+        __sessionKey: sessionKey ?? undefined,
+        __agentId: agentId ?? undefined,
+      },
+      cfg,
+      actionOptions,
+    );
+  }
+
   if (action === "poll") {
     const to = readStringParam(params, "to", { required: true });
     const question = readStringParam(params, "pollQuestion", {

package/src/actions/runtime.messaging.send.ts

@@ -78,14 +78,14 @@ export async function handleDiscordMessageSendAction(ctx: DiscordMessagingAction
         Array.isArray(rawComponents) || typeof rawComponents === "function"
           ? (rawComponents as DiscordSendComponents)
           : undefined;
-      const content = readStringParam(ctx.params, "content", {
-        required: !asVoice && !componentSpec && !components,
-        allowEmpty: true,
-      });
       const mediaUrl =
         readStringParam(ctx.params, "mediaUrl", { trim: false }) ??
         readStringParam(ctx.params, "path", { trim: false }) ??
         readStringParam(ctx.params, "filePath", { trim: false });
+      const content = readStringParam(ctx.params, "content", {
+        required: !asVoice && !componentSpec && !components && !mediaUrl,
+        allowEmpty: true,
+      });
       const filename = readStringParam(ctx.params, "filename");
       const replyTo = readStringParam(ctx.params, "replyTo");
       const rawEmbeds = ctx.params.embeds;
@@ -117,6 +117,9 @@ export async function handleDiscordMessageSendAction(ctx: DiscordMessagingAction
             agentId: agentId ?? undefined,
             mediaUrl: mediaUrl ?? undefined,
             filename: filename ?? undefined,
+            mediaAccess: ctx.options?.mediaAccess,
+            mediaLocalRoots: ctx.options?.mediaLocalRoots,
+            mediaReadFile: ctx.options?.mediaReadFile,
           },
         );
         return jsonResult({ ok: true, result, components: true });
@@ -144,6 +147,7 @@ export async function handleDiscordMessageSendAction(ctx: DiscordMessagingAction
 
       const result = await discordMessagingActionRuntime.sendMessageDiscord(to, content ?? "", {
         ...ctx.withOpts(),
+        mediaAccess: ctx.options?.mediaAccess,
         mediaUrl,
         filename: filename ?? undefined,
         mediaLocalRoots: ctx.options?.mediaLocalRoots,

package/src/actions/runtime.messaging.shared.ts

@@ -12,6 +12,11 @@ import { discordMessagingActionRuntime } from "./runtime.messaging.runtime.js";
 import { createDiscordActionOptions } from "./runtime.shared.js";
 
 export type DiscordMessagingActionOptions = {
+  mediaAccess?: {
+    localRoots?: readonly string[];
+    readFile?: (filePath: string) => Promise<Buffer>;
+    workspaceDir?: string;
+  };
   mediaLocalRoots?: readonly string[];
   mediaReadFile?: (filePath: string) => Promise<Buffer>;
 };

package/src/actions/runtime.test.ts

@@ -93,6 +93,11 @@ function handleMessagingAction(
   isActionEnabled: (key: keyof DiscordActionConfig) => boolean,
   cfg: OpenClawConfig = DISCORD_TEST_CFG,
   options?: {
+    mediaAccess?: {
+      localRoots?: readonly string[];
+      readFile?: (filePath: string) => Promise<Buffer>;
+      workspaceDir?: string;
+    };
     mediaLocalRoots?: readonly string[];
     mediaReadFile?: (filePath: string) => Promise<Buffer>;
   },
@@ -463,6 +468,8 @@ describe("handleDiscordMessagingAction", () => {
 
   it("forwards trusted mediaLocalRoots into sendMessageDiscord", async () => {
     sendMessageDiscord.mockClear();
+    const mediaReadFile = vi.fn(async () => Buffer.from("image"));
+    const mediaAccess = { localRoots: ["/tmp/agent-root"], readFile: mediaReadFile };
     await handleMessagingAction(
       "sendMessage",
       {
@@ -472,11 +479,35 @@ describe("handleDiscordMessagingAction", () => {
       },
       enableAllActions,
       DISCORD_TEST_CFG,
-      { mediaLocalRoots: ["/tmp/agent-root"] },
+      { mediaAccess, mediaLocalRoots: ["/tmp/agent-root"], mediaReadFile },
     );
     expect(sendMessageDiscord).toHaveBeenCalledWith(
       "channel:123",
       "hello",
+      expect.objectContaining({
+        mediaAccess,
+        mediaUrl: "/tmp/image.png",
+        mediaLocalRoots: ["/tmp/agent-root"],
+        mediaReadFile,
+      }),
+    );
+  });
+
+  it("allows media-only message sends", async () => {
+    sendMessageDiscord.mockClear();
+    await handleMessagingAction(
+      "sendMessage",
+      {
+        to: "channel:123",
+        mediaUrl: "/tmp/image.png",
+      },
+      enableAllActions,
+      DISCORD_TEST_CFG,
+      { mediaLocalRoots: ["/tmp/agent-root"] },
+    );
+    expect(sendMessageDiscord).toHaveBeenCalledWith(
+      "channel:123",
+      "",
       expect.objectContaining({
         mediaUrl: "/tmp/image.png",
         mediaLocalRoots: ["/tmp/agent-root"],

package/src/actions/runtime.ts

@@ -58,7 +58,13 @@ export async function handleDiscordAction(
   params: Record<string, unknown>,
   cfg: OpenClawConfig,
   options?: {
+    mediaAccess?: {
+      localRoots?: readonly string[];
+      readFile?: (filePath: string) => Promise<Buffer>;
+      workspaceDir?: string;
+    };
     mediaLocalRoots?: readonly string[];
+    mediaReadFile?: (filePath: string) => Promise<Buffer>;
   },
 ): Promise<AgentToolResult<unknown>> {
   const action = readStringParam(params, "action", { required: true });

package/src/channel-actions.test.ts

@@ -55,7 +55,15 @@ describe("discordMessageActions", () => {
     expect(discovery?.capabilities).toEqual(["presentation"]);
     expect(discovery?.schema).toBeUndefined();
     expect(discovery?.actions).toEqual(
-      expect.arrayContaining(["send", "poll", "react", "reactions", "emoji-list", "permissions"]),
+      expect.arrayContaining([
+        "send",
+        "upload-file",
+        "poll",
+        "react",
+        "reactions",
+        "emoji-list",
+        "permissions",
+      ]),
     );
     expect(discovery?.actions).not.toContain("channel-create");
     expect(discovery?.actions).not.toContain("role-add");
@@ -144,13 +152,35 @@ describe("discordMessageActions", () => {
     });
 
     expect(defaultDiscovery?.actions).toEqual(expect.arrayContaining(["send", "poll"]));
+    expect(defaultDiscovery?.actions).toContain("upload-file");
     expect(defaultDiscovery?.actions).not.toContain("react");
     expect(workDiscovery?.actions).toEqual(
-      expect.arrayContaining(["send", "react", "reactions", "emoji-list"]),
+      expect.arrayContaining(["send", "upload-file", "react", "reactions", "emoji-list"]),
     );
     expect(workDiscovery?.actions).not.toContain("poll");
   });
 
+  it("hides upload-file when Discord message actions are disabled", () => {
+    const discovery = discordMessageActions.describeMessageTool?.({
+      cfg: {
+        channels: {
+          discord: {
+            token: "Bot token-main",
+            actions: {
+              messages: false,
+            },
+          },
+        },
+      } as OpenClawConfig,
+    });
+
+    expect(discovery?.actions).toContain("send");
+    expect(discovery?.actions).not.toContain("upload-file");
+    expect(discovery?.actions).not.toContain("read");
+    expect(discovery?.actions).not.toContain("edit");
+    expect(discovery?.actions).not.toContain("delete");
+  });
+
   it("does not expose Discord-native message tool schema", () => {
     const discovery = discordMessageActions.describeMessageTool?.({
       cfg: {
@@ -170,7 +200,7 @@ describe("discordMessageActions", () => {
     );
   });
 
-  it.each(["send", "edit", "delete", "react", "pin", "poll"])(
+  it.each(["send", "upload-file", "edit", "delete", "react", "pin", "poll"])(
     "routes %s actions through local execution mode",
     (action) => {
       expect(discordMessageActions.resolveExecutionMode?.({ action: action as never })).toBe(
@@ -210,6 +240,11 @@ describe("discordMessageActions", () => {
     const toolContext: ChannelMessageActionContext["toolContext"] = {
       currentChannelProvider: "discord",
     };
+    const mediaReadFile = vi.fn(async () => Buffer.from("image"));
+    const mediaAccess: NonNullable<ChannelMessageActionContext["mediaAccess"]> = {
+      localRoots: ["/tmp/media"],
+      readFile: mediaReadFile,
+    };
     const mediaLocalRoots = ["/tmp/media"];
 
     await discordMessageActions.handleAction?.({
@@ -220,7 +255,9 @@ describe("discordMessageActions", () => {
       accountId: "ops",
       requesterSenderId: "user-1",
       toolContext,
+      mediaAccess,
       mediaLocalRoots,
+      mediaReadFile,
     });
 
     expect(handleDiscordMessageActionMock).toHaveBeenCalledWith({
@@ -230,7 +267,9 @@ describe("discordMessageActions", () => {
       accountId: "ops",
       requesterSenderId: "user-1",
       toolContext,
+      mediaAccess,
       mediaLocalRoots,
+      mediaReadFile,
     });
   });
 });

package/src/channel-actions.ts

@@ -86,6 +86,7 @@ function describeDiscordMessageTool({
     actions.add("emoji-list");
   }
   if (discovery.isEnabled("messages")) {
+    actions.add("upload-file");
     actions.add("read");
     actions.add("edit");
     actions.add("delete");
@@ -181,7 +182,9 @@ export const discordMessageActions: ChannelMessageActionAdapter = {
     accountId,
     requesterSenderId,
     toolContext,
+    mediaAccess,
     mediaLocalRoots,
+    mediaReadFile,
   }) => {
     return await (
       await loadDiscordChannelActionsRuntime()
@@ -192,7 +195,9 @@ export const discordMessageActions: ChannelMessageActionAdapter = {
       accountId,
       requesterSenderId,
       toolContext,
+      mediaAccess,
       mediaLocalRoots,
+      mediaReadFile,
     });
   },
 };

package/src/channel-api.ts

@@ -18,6 +18,7 @@ const DISCORD_CHANNEL_META = {
   blurb: "very well supported right now.",
   systemImage: "bubble.left.and.bubble.right",
   markdownCapable: true,
+  preferSessionLookupForAnnounceTarget: true,
 } as const;
 
 export function getChatChannelMeta(id: string) {

package/src/channel.test.ts

@@ -119,6 +119,14 @@ describe("discordPlugin outbound", () => {
     expect(discordPlugin.outbound?.preferFinalAssistantVisibleText).toBe(true);
   });
 
+  it("adds Discord mention formatting to agent prompt hints", () => {
+    const hints = discordPlugin.agentPrompt?.messageToolHints?.({} as never) ?? [];
+
+    expect(hints).toContain(
+      "- Discord mentions: use canonical outbound syntax: users `<@USER_ID>`, channels `<#CHANNEL_ID>`, and roles `<@&ROLE_ID>`. Do not use the legacy `<@!USER_ID>` nickname form.",
+    );
+  });
+
   it("preserves normalized explicit Discord targets for delivery routing", () => {
     const parseExplicitTarget = discordPlugin.messaging?.parseExplicitTarget;
     if (!parseExplicitTarget) {

package/src/channel.ts

@@ -213,6 +213,7 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount, DiscordProbe>
       },
       agentPrompt: {
         messageToolHints: () => [
+          "- Discord mentions: use canonical outbound syntax: users `<@USER_ID>`, channels `<#CHANNEL_ID>`, and roles `<@&ROLE_ID>`. Do not use the legacy `<@!USER_ID>` nickname form.",
           "- Discord components: set `components` when sending messages to include buttons, selects, or v2 containers.",
           "- Forms: add `components.modal` (title, fields). OpenClaw adds a trigger button and routes submissions as new messages.",
         ],

package/src/client.ts

@@ -61,13 +61,6 @@ function resolveToken(params: { accountId: string; fallbackToken?: string }) {
   return fallback;
 }
 
-export function resolveDiscordProxyFetch(
-  opts: Pick<DiscordClientOpts, "cfg" | "accountId">,
-  runtime?: Pick<RuntimeEnv, "error">,
-): typeof fetch | undefined {
-  return resolveDiscordClientAccountContext(opts, runtime).proxyFetch;
-}
-
 function resolveRest(
   token: string,
   account: ResolvedDiscordAccount,

package/src/config-ui-hints.ts

@@ -113,13 +113,13 @@ export const discordChannelConfigUiHints = {
     label: "Discord Thread Binding Max Age (hours)",
     help: "Optional hard max age in hours for Discord thread-bound sessions. Set 0 to disable hard cap (default: 0). Overrides session.threadBindings.maxAgeHours when set.",
   },
-  "threadBindings.spawnSubagentSessions": {
-    label: "Discord Thread-Bound Subagent Spawn",
-    help: "Allow subagent spawns with thread=true to auto-create and bind Discord threads (default: false; opt-in). Set true to enable thread-bound subagent spawns for this account/channel.",
+  "threadBindings.spawnSessions": {
+    label: "Discord Thread-Bound Session Spawn",
+    help: "Allow sessions_spawn(thread=true) and ACP thread spawns to auto-create and bind Discord threads (default: true). Set false to disable for this account/channel.",
   },
-  "threadBindings.spawnAcpSessions": {
-    label: "Discord Thread-Bound ACP Spawn",
-    help: "Allow /acp spawn to auto-create and bind Discord threads for ACP sessions (default: false; opt-in). Set true to enable thread-bound ACP spawns for this account/channel.",
+  "threadBindings.defaultSpawnContext": {
+    label: "Discord Thread Spawn Context",
+    help: 'Default native subagent context for thread-bound spawns. "fork" starts from the requester transcript; "isolated" starts clean. Default: "fork".',
   },
   "ui.components.accentColor": {
     label: "Discord Component Accent Color",