fix(discord): document mention formatting in agent prompt

docs/channels/discord.md

@@ -579,6 +579,8 @@ Example:
     - configured mention patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
     - implicit reply-to-bot behavior in supported cases
 
+    When writing outbound Discord messages, use `<@USER_ID>` to link a user. Do not use the legacy `<@!USER_ID>` nickname mention form. Use `<#CHANNEL_ID>` for channels and `<@&ROLE_ID>` for roles.
+
     `requireMention` is configured per guild/channel (`channels.discord.guilds...`).
     `ignoreOtherMentions` optionally drops messages that mention another user/role but not the bot (excluding @everyone/@here).
 

extensions/discord/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: link users with `<@USER_ID>` only. Do not use the legacy `<@!USER_ID>` nickname form. Link channels as `<#CHANNEL_ID>` and roles as `<@&ROLE_ID>`.",
+    );
+  });
+
   it("preserves normalized explicit Discord targets for delivery routing", () => {
     const parseExplicitTarget = discordPlugin.messaging?.parseExplicitTarget;
     if (!parseExplicitTarget) {

extensions/discord/src/channel.ts

@@ -213,6 +213,7 @@ export const discordPlugin: ChannelPlugin<ResolvedDiscordAccount, DiscordProbe>
       },
       agentPrompt: {
         messageToolHints: () => [
+          "- Discord mentions: link users with `<@USER_ID>` only. Do not use the legacy `<@!USER_ID>` nickname form. Link channels as `<#CHANNEL_ID>` and roles as `<@&ROLE_ID>`.",
           "- 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.",
         ],