clawgram 2.14.0 → 2.17.0

package/README.md

@@ -183,6 +183,12 @@ openclaw gateway restart
 openclaw gateway restart
 ```
 
+One restart after installation is enough. From 2.17.0 the plugin declares
+`channels.clawgram` as a hot-reloadable prefix, so later edits under it —
+`allowFrom`, `groups`, `readChats`, proxy — are picked up by the Gateway's
+config watcher and restart only this channel (a few seconds of MTProto
+reconnect), not the whole Gateway.
+
 
 ## Configuration Reference
 
@@ -228,6 +234,7 @@ openclaw gateway restart
 | `groups` | object | `{}` | Allowed groups map keyed by explicit group id or `*` |
 | `proxy` | object | unset | Optional SOCKS4/SOCKS5 proxy for this account — see [Proxy (SOCKS4/SOCKS5)](#proxy-socks4socks5) |
 | `manageChats` | string[] | unset | Chats the assistant may **manage** — see [Chat management](#chat-management). Absent or empty = management off; `["*"]` = every chat |
+| `replyParseMode` | `"html"` \| `"markdown"` \| `"none"` | unset | Outbound format for replies, core-delivered text, captions and `send` calls that omit `parseMode` — see [Message formatting](#message-formatting) |
 | `twoFaPassword` | string \| SecretRef | unset | The account's Telegram 2FA password; read only by `transferOwnership` |
 
 Group config fields:
@@ -237,7 +244,82 @@ Group config fields:
 | `enabled` | boolean | `true` | Enables or disables replies in the group |
 | `groupPolicy` | `"open"` \| `"mention"` | `"mention"` | `open` replies to any group message, `mention` only on @mention or reply-to-self |
 | `allowFrom` | string[] | `["*"]` | Allowed sender IDs/usernames inside that group |
+| `tools` | object | unset | `{ allow?, alsoAllow?, deny? }` — tool policy for this group; see [Per-group tools, skills and system prompt](#per-group-tools-skills-and-system-prompt) |
+| `toolsBySender` | object | unset | Per-sender tool policy inside this group, keys `id:<id>`, `username:<handle>`, `name:<display>` or `*` |
+| `skills` | string[] | unset | Skill allowlist for this group; `[]` = no skills here, unset = the agent's skills |
+| `systemPrompt` | string | unset | Trusted prompt block appended for messages from this group |
+
+### Per-group tools, skills and system prompt
+
+Since 2.17.0 a group entry can narrow what the assistant does *in that chat*
+without touching the agent as a whole. The keys mirror the bundled Telegram
+channel's group config, and `*` works as the default group for them too.
+
+```json
+"groups": {
+  "-1001234567890": {
+    "groupPolicy": "mention",
+    "systemPrompt": "This chat is project BRO. Other projects are out of scope here.",
+    "skills": ["pm-standup", "pm-jira"],
+    "tools": { "deny": ["browser", "cron"] },
+    "toolsBySender": { "id:123456789": { "alsoAllow": ["cron"] } }
+  }
+}
+```
+
+| Key | Effect |
+|---|---|
+| `systemPrompt` | Appended to the system prompt as a trusted block for turns from this group — the place to say what the chat is about and what stays out of it. |
+| `skills` | Skill allowlist for turns from this group. Omit to inherit the agent's skills; `[]` means no skills in this chat. |
+| `tools` / `toolsBySender` | Tool policy resolved by OpenClaw core for this group (`toolsBySender` wins for a matching sender). Keys use core's typed grammar: `id:`, `username:`, `name:`, `channel:clawgram:<id>` or `*`. |
+
+**Limits — read before relying on `tools`.** The policy governs OpenClaw's
+gateway tools (`message`, `sessions_*`, `cron`, `memory_*`, …). Under CLI
+backends such as `claude-cli` those reach the model through the loopback MCP
+tool list and are filtered per group; the backend's own native tools —
+`exec`, `read`, `write`, `edit`, `apply_patch`, `process` — are governed by
+the agent's exec policy, not by the group. If a chat must not have a shell at
+all, bind it to a separate agent without one; the routing is core's, and the
+peer id carries the account prefix this channel uses:
+
+```json
+"agents": {
+  "list": [
+    { "id": "main", "default": true, "workspace": "~/.openclaw/workspace" },
+    {
+      "id": "without-hands",
+      "workspace": "~/.openclaw/workspace-without-hands",
+      "model": "anthropic/claude-sonnet-5",
+      "tools": {
+        "deny": ["exec", "read", "write", "edit", "apply_patch", "process", "browser", "cron"],
+        "message": { "actions": { "allow": ["send"] }, "crossContext": { "allowWithinProvider": false } }
+      }
+    }
+  ]
+},
+"bindings": [
+  { "agentId": "without-hands", "match": { "channel": "clawgram", "peer": { "kind": "group", "id": "default:-1001234567890" } } }
+]
+```
+
+Nothing above changes for a group that does not set these keys.
+
+### Message formatting
+
+`replyParseMode` sets the outbound format for every path that does not name
+one explicitly: replies, core-delivered text, media captions, and `send`
+actions without a `parseMode` parameter. A per-call `parseMode` still wins.
+
+| Mode | Behavior |
+|---|---|
+| `"html"` | **Recommended for agents.** The text is rendered before sending (2.15.0): markdown (`**bold**`, `*italic*`, `` `code` ``, ``` fences, `[text](url)`, `# headings`, `> quotes`, `~~strike~~`, `\|\|spoiler\|\|`) becomes Telegram entities, hand-written Telegram HTML (`<b>`, `<a href>`, `<code>`, …) passes through, structural HTML (`<ul>`, `<p>`, …) is dropped, and stray `<`, `>`, `&` arrive as literal text instead of vanishing into a failed tag. Markdown inside code is never converted. |
+| `"markdown"` | GramJS's own markdown parser: `**`, `__`, `~~`, `` ` ``, ``` ``` ``` only — no links, no single-asterisk emphasis. |
+| `"none"` | No parsing at all: the text is delivered exactly as typed. |
+| unset | GramJS's historical default, which is its markdown parser — **not** plain text. Set `"none"` if you want plain. |
 
+Agent-authored messages mix markdown and HTML freely, so `"html"` is the mode
+that renders both. There is no reliable way to prompt a model out of writing
+markdown; rendering it is the deterministic fix.
 
 ### Configuration variant for example
 

package/dist/channel.js

@@ -61,6 +61,9 @@ const reactions_1 = require("./reactions");
 const manage_1 = require("./manage");
 const silent_reaction_1 = require("./silent-reaction");
 const chat_info_1 = require("./chat-info");
+const topics_1 = require("./topics");
+const dialogs_1 = require("./dialogs");
+const group_tool_policy_1 = require("./group-tool-policy");
 const secret_refs_1 = require("./secret-refs");
 const secret_ref_runtime_1 = require("openclaw/plugin-sdk/secret-ref-runtime");
 const group_reply_address_1 = require("./group-reply-address");
@@ -132,6 +135,10 @@ function resolveAccountReadChats(cfg, accountId) {
  * `readChats`, an absent value already means "deny", so there is nothing to
  * tell apart here.
  */
+/** Chat discovery as configured; absent means "deny", like management scope. */
+function resolveAccountDiscoverChats(cfg, accountId) {
+    return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.discoverChats;
+}
 function resolveAccountManageChats(cfg, accountId) {
     return cfg?.channels?.["clawgram"]?.accounts?.[accountId]?.manageChats;
 }
@@ -319,6 +326,20 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
             aliases: ["tguserbot"],
         },
         capabilities: CHANNEL_CAPABILITIES,
+        // Core plans config hot reloads from these prefixes. Without the
+        // declaration a changed `channels.clawgram.*` path matches no rule and
+        // core restarts the whole Gateway (SIGUSR1, all runs aborted) — measured
+        // 2026-08-13. With it, the same edit restarts only this channel. No
+        // `noopPrefixes`: `groups`/`allowFrom`/`readChats` are read from the cfg
+        // captured in `startAccount`, so a channel restart is exactly what an
+        // edit needs to take effect.
+        reload: { configPrefixes: ["channels.clawgram"] },
+        // Per-group `tools` / `toolsBySender` from the config. Core asks the
+        // channel first because only the channel knows that its group ids carry
+        // an account prefix; see src/group-tool-policy.ts.
+        groups: {
+            resolveToolPolicy: group_tool_policy_1.resolveClawgramGroupToolPolicy,
+        },
         agentPrompt: {
             // Nothing here steers reactions, and that is deliberate. 2.8.0 added a
             // `reactionGuidance` hook and 2.9.0 moved the same text onto these
@@ -337,6 +358,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "For Telegram forum topics, send to the group chat id and pass the topic id separately as `threadId`.",
                 "Use the `react` action to acknowledge a message with an emoji instead of sending a reply; pass an empty `emoji` (or `remove: true`) to take the reaction back.",
                 "Use the `chatInfo` action to learn what a chat is — title, type, member count, description, pinned message — instead of guessing from its id.",
+                "Use the `topics` action to list a forum's topics by name (optional `query` narrows by title); that is where a `threadId` comes from when someone names a topic instead of quoting a message in it.",
+                "Pass that `threadId` to `read` as well: without it a forum read returns every topic interleaved rather than the one that was asked about.",
+                "Use the `dialogs` action to find out which group chats this account is actually in — including ones nobody has configured yet. It reports id, title and type only, never direct chats, and only when the account enables `discoverChats`.",
                 "Use `createGroup` (title, optional about, optional users) to create a new Telegram supergroup; `addMembers`/`removeMember` change who is in a managed chat, `promoteAdmin`/`demoteAdmin` grant or revoke admin rights, `transferOwnership` hands the chat over, `inviteLink` issues an invite link for people Telegram refused to add directly.",
             ],
             messageToolCapabilities: () => [
@@ -345,6 +369,8 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                 "clawgram supports Telegram forum topics via the `threadId` parameter on group sends.",
                 "clawgram can add and clear emoji reactions on messages. A plain Telegram account holds one reaction per message, so a new emoji replaces the previous one.",
                 "clawgram can describe a chat via `chatInfo`: title, type (direct/group/supergroup/channel), member count, description, whether it is a forum, and the pinned message id.",
+                "clawgram can list the topics of a forum supergroup via `topics`: id, title, last message, and whether a topic is closed, hidden or pinned.",
+                "clawgram can list the group chats the account belongs to via `dialogs`, when the account sets discoverChats. Metadata only, no direct chats — it answers \"where am I\", not \"what was said\".",
                 "clawgram can manage chats where the account's manageChats config allows it: create supergroups, add and remove members, promote and demote admins, transfer ownership, and export invite links.",
             ],
         },
@@ -596,7 +622,8 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         const sendTextToConversation = async (args) => {
                             const targets = [conversationTarget, ...conversationFallbackTargets];
                             // Replies have no per-call parseMode slot — the format is an
-                            // account setting (2.3.1); absent keeps plain text.
+                            // account setting (2.3.1); absent keeps the GramJS default
+                            // (its markdown parser — not plain text, see 2.15.0 notes).
                             const replyParseMode = gram.replyParseMode;
                             let lastError;
                             for (const target of targets) {
@@ -751,6 +778,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                 ReplyToIsQuote: normalized.replyIsQuote,
                                 MessageThreadId: normalized.messageThreadId,
                                 NativeChannelId: normalized.chatId,
+                                // Trusted per-group prompt block from `groups.<id>.systemPrompt`.
+                                // Core normalizes it (`normalizeTrustedTextField`) and appends
+                                // it to the system prompt for this turn. Undefined = no block.
+                                GroupSystemPrompt: groupConfig.systemPrompt,
                                 OriginatingChannel: "clawgram",
                                 OriginatingTo: conversationRouteTarget,
                             });
@@ -866,6 +897,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                                     },
                                     replyOptions: {
                                         onModelSelected,
+                                        // `groups.<id>.skills` → core's per-turn skill allowlist.
+                                        // Undefined = inherit the agent's skills; [] = none here.
+                                        skillFilter: groupConfig.skillFilter,
                                     },
                                 });
                                 log?.info?.("clawgram group dispatch completed", {
@@ -1292,7 +1326,7 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     // never sees a way to send the file, announces it in words, and the
                     // file stays on disk. That is exactly what happened on 2026-08-07.
                     actions: [
-                        "send", "read", "participants", "joins", "react", "chatInfo", "upload-file",
+                        "send", "read", "participants", "joins", "react", "chatInfo", "topics", "dialogs", "upload-file",
                         // Chat management (2.12.0) — gated by the account's manageChats
                         // scope; without it every one of these is refused.
                         "createGroup", "addMembers", "removeMember",
@@ -1392,6 +1426,80 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         participants: membership.participants,
                     });
                 }
+                // Topic names. A forum chat is addressed by topic id, and until now an
+                // id could only be lifted off an inbound message — so a topic nobody had
+                // written in yet was unreachable, and one named in words was unfindable.
+                // Titles say what a chat is working on, so the read scope gates them.
+                if (action === "topics" || action === "forumTopics") {
+                    const topicsParams = (0, topics_1.parseTopicsParams)(params);
+                    const topicsAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!topicsAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    if (!(0, history_1.isChatReadable)(topicsParams.target, resolveAccountReadChats(cfg, topicsAccountId))) {
+                        actionLog.warn("clawgram topics refused: chat outside read scope", {
+                            accountId: topicsAccountId,
+                            target: topicsParams.target,
+                        });
+                        throw new Error(`clawgram: not-allowed-chat ${topicsParams.target}`);
+                    }
+                    const topicsGram = runtimes.get(topicsAccountId);
+                    if (!topicsGram) {
+                        throw new Error(`clawgram: runtime not found for account ${topicsAccountId}`);
+                    }
+                    const forum = await topicsGram.listTopics(topicsParams);
+                    actionLog.info("clawgram handleAction topics completed", {
+                        accountId: topicsAccountId,
+                        target: topicsParams.target,
+                        limit: topicsParams.limit,
+                        returned: forum.topics.length,
+                        truncated: forum.truncated,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: topicsAccountId,
+                        chatId: forum.chatId ?? topicsParams.target,
+                        count: forum.topics.length,
+                        truncated: forum.truncated,
+                        topics: forum.topics,
+                    });
+                }
+                // Which chats this account is in. Not gated by `readChats` — the whole
+                // point is to find chats that are not in it yet — so it has a gate of
+                // its own, is metadata only, and never reports direct chats.
+                if (action === "dialogs" || action === "chats") {
+                    const dialogsParams = (0, dialogs_1.parseDialogsParams)(params);
+                    const dialogsAccountId = resolveRuntimeAccountId(cfg, accountId);
+                    if (!dialogsAccountId) {
+                        throw new Error("clawgram: no configured account found");
+                    }
+                    if (!(0, dialogs_1.isChatDiscoveryEnabled)(resolveAccountDiscoverChats(cfg, dialogsAccountId))) {
+                        actionLog.warn("clawgram dialogs refused: chat-discovery is not enabled", {
+                            accountId: dialogsAccountId,
+                        });
+                        throw new Error("clawgram: chat-discovery is not enabled");
+                    }
+                    const dialogsGram = runtimes.get(dialogsAccountId);
+                    if (!dialogsGram) {
+                        throw new Error(`clawgram: runtime not found for account ${dialogsAccountId}`);
+                    }
+                    const found = await dialogsGram.listDialogs(dialogsParams);
+                    // Counts only: which chats a person's account sits in is exactly the
+                    // kind of thing that should not be sitting in a log.
+                    actionLog.info("clawgram handleAction dialogs completed", {
+                        accountId: dialogsAccountId,
+                        limit: dialogsParams.limit,
+                        returned: found.dialogs.length,
+                        truncated: found.truncated,
+                    });
+                    return (0, core_1.jsonResult)({
+                        ok: true,
+                        accountId: dialogsAccountId,
+                        count: found.dialogs.length,
+                        truncated: found.truncated,
+                        dialogs: found.dialogs,
+                    });
+                }
                 // Where this account was recently added, and by whom. Reading the journal
                 // has no scope check of its own: it only ever contains chats this account
                 // was put into, which is exactly what the caller is allowed to learn.
@@ -1762,6 +1870,10 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                         target: uploadTo,
                         file,
                         caption: caption || undefined,
+                        // Same resolution as the text `send`: per-call value wins, an
+                        // omitted one inherits the account format (2.15.0). A caption is
+                        // the same prose as a message and renders identically.
+                        parseMode: (0, helpers_1.resolveOutboundParseMode)(params, cfg, uploadAccountId),
                         replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(rawUploadTo, uploadReplyToId),
                         messageThreadId: parseOptionalThreadId(uploadThreadId),
                         asVoice,
@@ -2065,6 +2177,9 @@ const createChannelPlugin = (runtimes, pluginRuntime) => {
                     target,
                     file,
                     caption: ctx.caption ?? ctx.text,
+                    // Captions follow the account reply format like every other reply:
+                    // they are the same agent prose, just attached to a file (2.15.0).
+                    parseMode: gram.replyParseMode,
                     replyToMessageId: (0, helpers_1.resolveReplyToMessageIdForTarget)(ctx.to, ctx.replyToId),
                     messageThreadId,
                     asVoice: ctx.audioAsVoice === true,

package/dist/chat-info.js

@@ -17,6 +17,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseChatInfoParams = parseChatInfoParams;
 exports.describeChat = describeChat;
+const helpers_1 = require("./helpers");
 function parseChatInfoParams(params, toolContext) {
     const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat ?? toolContext?.currentChannelId;
     const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
@@ -78,7 +79,9 @@ function describeChat(entity, full) {
         chatId: readId(raw?.id),
         type,
         title: type === "direct" ? resolveUserTitle(raw) : readString(raw?.title),
-        username: readString(raw?.username),
+        // Not `raw.username`: an account or chat holding more than one handle keeps
+        // them in `usernames[]` and leaves the legacy field empty.
+        username: (0, helpers_1.resolveActiveUsername)(raw),
         about: readString(fullChat?.about),
         pinnedMessageId: readId(fullChat?.pinnedMsgId),
     };

package/dist/dialogs.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIALOGS_MAX_LIMIT = exports.DIALOGS_DEFAULT_LIMIT = void 0;
+exports.parseDialogsParams = parseDialogsParams;
+exports.isChatDiscoveryEnabled = isChatDiscoveryEnabled;
+exports.normalizeDialogs = normalizeDialogs;
+/**
+ * Which chats this account is actually in.
+ *
+ * Everything else here answers questions about a chat the caller can already
+ * name. Nothing answered "where am I now" — the assistant learned that from a
+ * service message Telegram sends when somebody adds it, and large supergroups
+ * do not send one. A chat could therefore hold the account for weeks while
+ * every message from it was dropped as "group not present in groups config",
+ * with no trace anywhere that the account was even a member.
+ *
+ * Discovery is metadata only — id, title, type — and never direct chats: a
+ * personal account also sits in family and one-to-one conversations, and
+ * enumerating those is the surveillance the read scope exists to prevent.
+ * It stays off until the account sets `discoverChats`.
+ */
+const normalize_js_1 = require("./normalize.js");
+exports.DIALOGS_DEFAULT_LIMIT = 100;
+exports.DIALOGS_MAX_LIMIT = 500;
+function parseDialogsParams(params) {
+    const rawQuery = params.query ?? params.search ?? params.title;
+    const trimmedQuery = typeof rawQuery === "string" ? rawQuery.trim() : "";
+    const query = trimmedQuery.length > 0 ? trimmedQuery : undefined;
+    const rawLimit = params.limit;
+    if (rawLimit === undefined || rawLimit === null || rawLimit === "") {
+        return { limit: exports.DIALOGS_DEFAULT_LIMIT, query };
+    }
+    const parsed = Number(rawLimit);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("clawgram: dialogs limit must be a positive number");
+    }
+    return { limit: Math.min(Math.floor(parsed), exports.DIALOGS_MAX_LIMIT), query };
+}
+/** Chat discovery is off unless the account asks for it. */
+function isChatDiscoveryEnabled(discoverChats) {
+    return discoverChats === true;
+}
+function resolveDialogType(dialog) {
+    if (dialog.isUser === true)
+        return undefined;
+    const entity = (dialog.entity ?? {});
+    if (dialog.isChannel === true) {
+        // Telegram models supergroups and broadcast channels with one constructor;
+        // `megagroup` is what separates "a group with history" from "a feed".
+        return entity.megagroup === true ? "supergroup" : "channel";
+    }
+    return dialog.isGroup === true ? "group" : undefined;
+}
+function matchesQuery(title, query) {
+    if (!query)
+        return true;
+    if (!title)
+        return false;
+    return title.toLocaleLowerCase().includes(query.toLocaleLowerCase());
+}
+function normalizeDialogs(raw, options = {}) {
+    if (!Array.isArray(raw))
+        return [];
+    const dialogs = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const dialog = entry;
+        const type = resolveDialogType(dialog);
+        if (!type)
+            continue;
+        const chatId = (0, normalize_js_1.toStringId)(dialog.id);
+        if (!chatId)
+            continue;
+        const entity = (dialog.entity ?? {});
+        const rawTitle = dialog.title ?? entity.title;
+        const title = typeof rawTitle === "string" && rawTitle.length > 0 ? rawTitle : undefined;
+        if (!matchesQuery(title, options.query))
+            continue;
+        const summary = { chatId, type };
+        if (title !== undefined)
+            summary.title = title;
+        if (entity.forum === true)
+            summary.isForum = true;
+        dialogs.push(summary);
+    }
+    return dialogs;
+}

package/dist/gramjs-client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GramJsClientManager = void 0;
+exports.buildParticipantsQuery = buildParticipantsQuery;
 exports.buildVoiceNoteParams = buildVoiceNoteParams;
 const telegram_1 = require("telegram");
 const sessions_1 = require("telegram/sessions");
@@ -8,9 +9,12 @@ const sessions_1 = require("telegram/sessions");
 // the package has no `exports` field to forbid it.
 const Password_1 = require("telegram/Password");
 const helpers_1 = require("./helpers");
+const html_render_1 = require("./html-render");
 const proxy_config_1 = require("./proxy-config");
 const secret_refs_1 = require("./secret-refs");
 const history_1 = require("./history");
+const topics_1 = require("./topics");
+const dialogs_1 = require("./dialogs");
 const manage_1 = require("./manage");
 function toStringId(value) {
     if (value === null || value === undefined)
@@ -84,6 +88,22 @@ function parseTargetWithThread(rawTarget) {
         chatId: raw,
     };
 }
+/**
+ * Membership query for `getParticipants`.
+ *
+ * The filter has to arrive as a TL constructor. `getParticipants` accepts an
+ * unknown `filter` value without complaining and falls back to everyone, so a
+ * plain `"admins"` string would return the whole chat under a name promising
+ * otherwise — and an allowFrom rebuilt from that list would open a 1000-person
+ * chat to all of it.
+ */
+function buildParticipantsQuery(args) {
+    const query = { limit: args.limit };
+    if (args.filter === "admins") {
+        query.filter = new telegram_1.Api.ChannelParticipantsAdmins();
+    }
+    return query;
+}
 /**
  * Voice-message option for `sendFile`.
  *
@@ -323,10 +343,20 @@ class GramJsClientManager {
         const messageThreadId = args.messageThreadId ?? resolved.messageThreadId;
         const replyParams = buildForumReplyParams(messageThreadId, args.replyToMessageId);
         return this.client.sendMessage(resolved.peer, {
-            message: args.text,
-            // GramJS accepts "md" | "html"; absent keeps plain text so every
-            // pre-2.3.0 caller behaves exactly as before.
-            ...(args.parseMode ? { parseMode: args.parseMode === "markdown" ? "md" : "html" } : {}),
+            // In html mode the text is rendered first: the agent writes markdown,
+            // Telegram HTML, or both, and GramJS's HTML parser alone would ship
+            // the markdown as literal asterisks (2026-08-12 00:13 UTC, a whole
+            // monthly report of them).
+            message: args.parseMode === "html" ? (0, html_render_1.renderTelegramHtml)(args.text) : args.text,
+            // GramJS accepts "md" | "html". `false` switches parsing off — needed
+            // because an *absent* mode is not plain text: GramJS then applies its
+            // own default markdown parser, and always has. "none" is the honest
+            // spelling of "exactly as typed".
+            ...(args.parseMode === "none"
+                ? { parseMode: false }
+                : args.parseMode
+                    ? { parseMode: args.parseMode === "markdown" ? "md" : "html" }
+                    : {}),
             ...replyParams,
         });
     }
@@ -431,7 +461,13 @@ class GramJsClientManager {
      */
     async listMessages(args) {
         const resolved = await this.resolvePeer(args.target);
-        const query = (0, history_1.buildHistoryQuery)(args);
+        // A topic can be named two ways — `chatId:topic:N` in the target or a
+        // `threadId` parameter beside it. The explicit parameter wins; both used to
+        // be parsed and then dropped before the query was built.
+        const query = (0, history_1.buildHistoryQuery)({
+            ...args,
+            messageThreadId: args.messageThreadId ?? resolved.messageThreadId,
+        });
         const fetched = await this.client.getMessages(resolved.peer, query);
         const raw = Array.isArray(fetched) ? fetched : [];
         return {
@@ -451,37 +487,50 @@ class GramJsClientManager {
      */
     async listParticipants(args) {
         const resolved = await this.resolvePeer(args.target);
-        const fetched = await this.client.getParticipants(resolved.peer, {
-            limit: args.limit,
-        });
+        const fetched = await this.client.getParticipants(resolved.peer, buildParticipantsQuery(args));
         const raw = Array.isArray(fetched) ? fetched : [];
-        const participants = [];
-        for (const entry of raw) {
-            const rawId = entry?.id;
-            if (rawId === undefined || rawId === null) {
-                continue;
-            }
-            const username = typeof entry?.username === "string" && entry.username.length > 0
-                ? entry.username
-                : undefined;
-            const member = {
-                userId: String(rawId),
-                username,
-                isBot: entry?.bot === true,
-            };
-            // Display names are personal data, so they are opt-in: only the identity
-            // linking flow asks for them, and it discards them once a link is made.
-            if (args.includeNames) {
-                if (typeof entry?.firstName === "string" && entry.firstName.length > 0)
-                    member.firstName = entry.firstName;
-                if (typeof entry?.lastName === "string" && entry.lastName.length > 0)
-                    member.lastName = entry.lastName;
-            }
-            participants.push(member);
-        }
         return {
             chatId: resolved.chatId,
-            participants,
+            participants: (0, history_1.normalizeParticipants)(raw, { includeNames: args.includeNames }),
+            truncated: raw.length >= args.limit,
+        };
+    }
+    /**
+     * The group chats this account belongs to.
+     *
+     * Deliberately thin: `getDialogs` also returns every private conversation,
+     * and `normalizeDialogs` drops them before anything else sees the list.
+     */
+    async listDialogs(args) {
+        const fetched = await this.client.getDialogs({ limit: args.limit });
+        const raw = Array.isArray(fetched) ? fetched : [];
+        return {
+            dialogs: (0, dialogs_1.normalizeDialogs)(raw, { query: args.query }),
+            truncated: raw.length >= args.limit,
+        };
+    }
+    /**
+     * Topics of a forum supergroup, by name.
+     *
+     * `q` is passed to Telegram when the caller narrows the list, and the same
+     * text is applied again to the result: the server-side search is not
+     * guaranteed to be there on every layer, and a filter that silently does
+     * nothing is worse than one that runs twice.
+     */
+    async listTopics(args) {
+        const resolved = await this.resolvePeer(args.target, { kind: "channel" });
+        const result = await this.client.invoke(new telegram_1.Api.channels.GetForumTopics({
+            channel: resolved.peer,
+            ...(args.query ? { q: args.query } : {}),
+            offsetDate: 0,
+            offsetId: 0,
+            offsetTopic: 0,
+            limit: args.limit,
+        }));
+        const raw = Array.isArray(result?.topics) ? result.topics : [];
+        return {
+            chatId: resolved.chatId,
+            topics: (0, topics_1.normalizeForumTopics)(raw, { query: args.query }),
             truncated: raw.length >= args.limit,
         };
     }
@@ -561,7 +610,18 @@ class GramJsClientManager {
         const replyParams = buildForumReplyParams(messageThreadId, args.replyToMessageId);
         return this.client.sendFile(resolved.peer, {
             file: args.file,
-            caption: args.caption,
+            // Captions are agent prose too — the outbound path sends `caption ??
+            // text` — so they render exactly like sendText does. Before 2.15.0
+            // captions carried no mode at all, which meant GramJS's default
+            // markdown pass, a third rendering behavior nobody chose.
+            caption: args.parseMode === "html" && args.caption
+                ? (0, html_render_1.renderTelegramHtml)(args.caption)
+                : args.caption,
+            ...(args.parseMode === "none"
+                ? { parseMode: false }
+                : args.parseMode
+                    ? { parseMode: args.parseMode === "markdown" ? "md" : "html" }
+                    : {}),
             ...replyParams,
             ...buildVoiceNoteParams(args.asVoice),
         });

package/dist/group-tool-policy.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClawgramGroupToolPolicy = resolveClawgramGroupToolPolicy;
+const channel_policy_1 = require("openclaw/plugin-sdk/channel-policy");
+const constants_1 = require("./constants");
+const helpers_1 = require("./helpers");
+/**
+ * `groups.resolveToolPolicy` — core calls this before its own lookup when a
+ * message from a group session runs. The only thing this channel adds is the
+ * id translation: core passes the scoped peer id (`<accountId>:<chatId>`),
+ * the config is keyed by the bare chat id. Everything else — per-account vs
+ * top-level `groups`, the `*` default, `toolsBySender` by id/username/name —
+ * is the SDK's `resolveChannelGroupToolsPolicy`, the same function the
+ * bundled Telegram channel delegates to.
+ *
+ * What the returned policy governs: gateway tools (message, sessions_*,
+ * cron, memory_*, …) — under CLI backends via the loopback MCP tool list.
+ * Not the CLI backend's own exec/read/write; those are per agent, not per
+ * group, and only a separate agent bound to the chat restricts them.
+ */
+function resolveClawgramGroupToolPolicy(ctx) {
+    const groupId = (0, helpers_1.stripAccountScopedGroupId)(ctx.groupId, ctx.accountId);
+    if (!groupId) {
+        return undefined;
+    }
+    return (0, channel_policy_1.resolveChannelGroupToolsPolicy)({
+        cfg: ctx.cfg,
+        channel: constants_1.CHANNEL_ID,
+        groupId,
+        accountId: ctx.accountId ?? "default",
+        senderId: ctx.senderId,
+        senderName: ctx.senderName,
+        senderUsername: ctx.senderUsername,
+        senderE164: ctx.senderE164,
+    });
+}