clawgram 2.15.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
 
@@ -238,6 +244,65 @@ 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
 

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.",
             ],
         },
@@ -752,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,
                             });
@@ -867,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", {
@@ -1293,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",
@@ -1393,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.

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");
@@ -12,6 +13,8 @@ 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)
@@ -85,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`.
  *
@@ -442,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 {
@@ -462,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,
         };
     }

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,
+    });
+}

package/dist/helpers.js

@@ -10,6 +10,7 @@ exports.inferOutboundTargetKind = inferOutboundTargetKind;
 exports.routeKindFromChatType = routeKindFromChatType;
 exports.buildConversationTarget = buildConversationTarget;
 exports.buildScopedGroupPeerId = buildScopedGroupPeerId;
+exports.stripAccountScopedGroupId = stripAccountScopedGroupId;
 exports.stripReplyDirectiveTags = stripReplyDirectiveTags;
 exports.readLatestAssistantFallbackFromTranscript = readLatestAssistantFallbackFromTranscript;
 exports.resolveActionTarget = resolveActionTarget;
@@ -21,6 +22,7 @@ exports.resolveAllowFrom = resolveAllowFrom;
 exports.resolveGroupPolicy = resolveGroupPolicy;
 exports.resolveGroups = resolveGroups;
 exports.resolveGroupConfig = resolveGroupConfig;
+exports.resolveGroupPromptSettings = resolveGroupPromptSettings;
 exports.resolveActiveUsername = resolveActiveUsername;
 exports.normalizeAllowEntry = normalizeAllowEntry;
 exports.isSenderAllowed = isSenderAllowed;
@@ -89,6 +91,20 @@ function buildScopedGroupPeerId(accountId, chatId) {
     const scopedAccountId = (accountId ?? "default").trim() || "default";
     return `${scopedAccountId}:${chatId}`;
 }
+/**
+ * Inverse of `buildScopedGroupPeerId`. Core derives group ids from the session
+ * key, so a channel hook receives `<accountId>:<chatId>` while `groups` in the
+ * config is keyed by the bare chat id. Only this account's prefix is stripped;
+ * anything else passes through untouched.
+ */
+function stripAccountScopedGroupId(groupId, accountId) {
+    const raw = typeof groupId === "string" ? groupId.trim() : "";
+    if (!raw) {
+        return undefined;
+    }
+    const prefix = `${(accountId ?? "default").trim() || "default"}:`;
+    return raw.startsWith(prefix) ? raw.slice(prefix.length) : raw;
+}
 function stripReplyDirectiveTags(text) {
     return text
         .replace(/\[\[\s*reply_to_current\s*\]\]/gi, " ")
@@ -258,6 +274,28 @@ function resolveAllowFrom(value) {
 function resolveGroupPolicy(value) {
     return value === "open" ? "open" : "mention";
 }
+/**
+ * Per-group `skills` → core `replyOptions.skillFilter`, `systemPrompt` →
+ * `GroupSystemPrompt`. An empty `skills` array is kept as `[]` — "no skills
+ * in this chat" is an answer, the same one core gives `agents.list[].skills: []`
+ * — while a blank `systemPrompt` is unset rather than an empty trusted block.
+ */
+function resolveGroupPromptSettings(groupConfig) {
+    const settings = {};
+    if (!groupConfig) {
+        return settings;
+    }
+    if (Array.isArray(groupConfig.skills)) {
+        settings.skillFilter = groupConfig.skills
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+    }
+    if (typeof groupConfig.systemPrompt === "string" && groupConfig.systemPrompt.trim()) {
+        settings.systemPrompt = groupConfig.systemPrompt.trim();
+    }
+    return settings;
+}
 function resolveGroups(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return {};
@@ -273,6 +311,7 @@ function resolveGroups(value) {
                 enabled: groupConfig.enabled !== false,
                 groupPolicy: resolveGroupPolicy(groupConfig.groupPolicy),
                 allowFrom: resolveAllowFrom(groupConfig.allowFrom),
+                ...resolveGroupPromptSettings(groupConfig),
             },
         ];
     }).filter(([groupId]) => Boolean(groupId)));

package/dist/history.js

@@ -16,6 +16,7 @@ exports.parseTimeBoundary = parseTimeBoundary;
 exports.parseLimit = parseLimit;
 exports.parseMessageId = parseMessageId;
 exports.parseListMessagesParams = parseListMessagesParams;
+exports.normalizeParticipants = normalizeParticipants;
 exports.parseListParticipantsParams = parseListParticipantsParams;
 exports.buildHistoryQuery = buildHistoryQuery;
 exports.normalizeChatKey = normalizeChatKey;
@@ -26,6 +27,7 @@ exports.collectHistoryWindow = collectHistoryWindow;
 exports.HISTORY_DEFAULT_LIMIT = 100;
 exports.HISTORY_MAX_LIMIT = 500;
 const media_1 = require("./media");
+const helpers_1 = require("./helpers");
 /**
  * Matches `normalize.ts` and `gramjs-client.ts` deliberately.
  *
@@ -119,6 +121,7 @@ function parseListMessagesParams(params) {
     if (since !== undefined && until !== undefined && since > until) {
         throw new Error("clawgram: since must not be later than until");
     }
+    const rawThreadId = params.threadId ?? params.topicId ?? params.messageThreadId ?? params.topic;
     return {
         target,
         limit: parseLimit(params.limit),
@@ -126,10 +129,61 @@ function parseListMessagesParams(params) {
         until,
         minId: parseMessageId(params.after, "after"),
         maxId: parseMessageId(params.before, "before"),
+        messageThreadId: parseMessageId(rawThreadId, "threadId"),
     };
 }
 exports.PARTICIPANTS_DEFAULT_LIMIT = 200;
 exports.PARTICIPANTS_MAX_LIMIT = 1000;
+/**
+ * Membership as the caller sees it.
+ *
+ * The handle comes through `resolveActiveUsername`, not off the raw field:
+ * once an account holds more than one username — several handles, or a
+ * collectible one — Telegram moves them into `usernames[]` and leaves the
+ * legacy `username` EMPTY. Reading the raw field is why the owner of this
+ * deployment appeared in every generated table as "(без тэга)" beside a bare
+ * numeric id, the only person without a handle in chats of 23, 9, 7 and 3.
+ */
+function normalizeParticipants(raw, options) {
+    if (!Array.isArray(raw))
+        return [];
+    const participants = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const candidate = entry;
+        const userId = toStringId(candidate.id);
+        if (!userId)
+            continue;
+        const member = {
+            userId,
+            username: (0, helpers_1.resolveActiveUsername)(candidate),
+            isBot: candidate.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 (options.includeNames) {
+            if (typeof candidate.firstName === "string" && candidate.firstName.length > 0) {
+                member.firstName = candidate.firstName;
+            }
+            if (typeof candidate.lastName === "string" && candidate.lastName.length > 0) {
+                member.lastName = candidate.lastName;
+            }
+        }
+        participants.push(member);
+    }
+    return participants;
+}
+function parseParticipantsFilter(params) {
+    if (params.admins === true)
+        return "admins";
+    const raw = params.filter;
+    if (raw === undefined || raw === null || raw === "")
+        return "all";
+    if (raw === "all" || raw === "admins")
+        return raw;
+    throw new Error('clawgram: participants filter must be "all" or "admins"');
+}
 /**
  * Membership is asked for by chat, so a target is required. `limit` is clamped
  * for the same reason it is clamped when reading history: a large group must
@@ -142,15 +196,16 @@ function parseListParticipantsParams(params) {
         throw new Error("clawgram: participants requires a chatId");
     }
     const includeNames = params.includeNames === true || params.includeNames === "true";
+    const filter = parseParticipantsFilter(params);
     const rawLimit = params.limit;
     if (rawLimit === undefined || rawLimit === null || rawLimit === "") {
-        return { target, limit: exports.PARTICIPANTS_DEFAULT_LIMIT, includeNames };
+        return { target, limit: exports.PARTICIPANTS_DEFAULT_LIMIT, includeNames, filter };
     }
     const parsed = Number(rawLimit);
     if (!Number.isFinite(parsed) || parsed <= 0) {
         throw new Error("clawgram: participants limit must be a positive number");
     }
-    return { target, limit: Math.min(Math.floor(parsed), exports.PARTICIPANTS_MAX_LIMIT), includeNames };
+    return { target, limit: Math.min(Math.floor(parsed), exports.PARTICIPANTS_MAX_LIMIT), includeNames, filter };
 }
 /**
  * Builds the GramJS query for a window.
@@ -164,6 +219,11 @@ function parseListParticipantsParams(params) {
  */
 function buildHistoryQuery(args) {
     const query = { limit: args.limit };
+    // GramJS turns `replyTo` into messages.GetReplies, which is Telegram's way of
+    // asking for one forum topic rather than the whole chat.
+    if (args.messageThreadId !== undefined) {
+        query.replyTo = args.messageThreadId;
+    }
     if (args.until !== undefined) {
         query.offsetDate = args.until + 1;
     }

package/dist/normalize.js

@@ -4,6 +4,7 @@ exports.toStringId = toStringId;
 exports.toPeerChatId = toPeerChatId;
 exports.toPeerChannelId = toPeerChannelId;
 exports.normalizeTelegramEvent = normalizeTelegramEvent;
+const helpers_1 = require("./helpers");
 function toStringId(value) {
     if (value === null || value === undefined)
         return undefined;
@@ -106,11 +107,10 @@ function normalizeTelegramEvent(event, accountId) {
             ? msg.text
             : undefined;
     const chatType = inferTelegramChatType(msg, chatId);
-    const senderUsername = typeof msg.sender?.username === "string"
-        ? msg.sender.username
-        : typeof msg._sender?.username === "string"
-            ? msg._sender.username
-            : undefined;
+    // Not the raw field: a sender holding several handles (or a collectible one)
+    // keeps them in `usernames[]` and leaves `username` empty, so an allowFrom
+    // entry written as `@handle` would silently never match that person.
+    const senderUsername = (0, helpers_1.resolveActiveUsername)(msg.sender) ?? (0, helpers_1.resolveActiveUsername)(msg._sender);
     const senderDisplay = typeof msg.sender?.firstName === "string"
         ? [msg.sender.firstName, msg.sender.lastName].filter(Boolean).join(" ").trim()
         : typeof msg._sender?.firstName === "string"

package/dist/topics.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOPICS_MAX_LIMIT = exports.TOPICS_DEFAULT_LIMIT = void 0;
+exports.parseTopicsParams = parseTopicsParams;
+exports.normalizeForumTopics = normalizeForumTopics;
+/**
+ * Forum topics — the names a supergroup organises itself by.
+ *
+ * A forum chat addresses replies by topic, and `chatInfo` can only say *that*
+ * a chat is a forum. Everything else about a topic reached the assistant as a
+ * bare number lifted off an inbound message, so a person could ask it to work
+ * in "Визитка - представление" and it had no way to turn that name into an id —
+ * or to know the topic existed before somebody wrote in it.
+ *
+ * Parsing and shaping are pure so they can be tested without a Telegram
+ * client; the transport lives in `GramJsClientManager.listTopics`.
+ */
+const normalize_js_1 = require("./normalize.js");
+exports.TOPICS_DEFAULT_LIMIT = 100;
+exports.TOPICS_MAX_LIMIT = 500;
+function parseTopicsParams(params) {
+    const rawTarget = params.chatId ?? params.target ?? params.to ?? params.chat;
+    const target = typeof rawTarget === "string" ? rawTarget.trim() : "";
+    if (!target) {
+        throw new Error("clawgram: topics requires a chatId");
+    }
+    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 { target, limit: exports.TOPICS_DEFAULT_LIMIT, query };
+    }
+    const parsed = Number(rawLimit);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error("clawgram: topics limit must be a positive number");
+    }
+    return { target, limit: Math.min(Math.floor(parsed), exports.TOPICS_MAX_LIMIT), query };
+}
+/** Telegram sends flags only when they are set; an absent flag is not `false`. */
+function optionalFlag(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function matchesQuery(title, query) {
+    if (!query)
+        return true;
+    return title.toLocaleLowerCase().includes(query.toLocaleLowerCase());
+}
+/**
+ * `channels.getForumTopics` returns live topics and tombstones in one list.
+ * A `ForumTopicDeleted` carries an id and nothing else: it cannot be named,
+ * so it is dropped rather than surfaced as a topic with a blank title.
+ */
+function normalizeForumTopics(raw, options = {}) {
+    if (!Array.isArray(raw))
+        return [];
+    const topics = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const candidate = entry;
+        const title = typeof candidate.title === "string" ? candidate.title : undefined;
+        const topicId = (0, normalize_js_1.toStringId)(candidate.id);
+        if (!title || !topicId)
+            continue;
+        if (!matchesQuery(title, options.query))
+            continue;
+        const topic = { topicId, title };
+        const topMessageId = (0, normalize_js_1.toStringId)(candidate.topMessage);
+        if (topMessageId !== undefined)
+            topic.topMessageId = topMessageId;
+        const closed = optionalFlag(candidate.closed);
+        if (closed !== undefined)
+            topic.closed = closed;
+        const hidden = optionalFlag(candidate.hidden);
+        if (hidden !== undefined)
+            topic.hidden = hidden;
+        const pinned = optionalFlag(candidate.pinned);
+        if (pinned !== undefined)
+            topic.pinned = pinned;
+        topics.push(topic);
+    }
+    return topics;
+}

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "clawgram",
   "name": "Clawgram",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -69,6 +69,69 @@
                       }
                     ]
                   }
+                },
+                "tools": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "allow": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "alsoAllow": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "deny": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                },
+                "toolsBySender": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string"
+                  },
+                  "additionalProperties": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "properties": {
+                      "allow": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "alsoAllow": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "deny": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                },
+                "skills": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "systemPrompt": {
+                  "type": "string"
                 }
               }
             }
@@ -311,6 +374,69 @@
                             }
                           ]
                         }
+                      },
+                      "tools": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                          "allow": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "alsoAllow": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "deny": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          }
+                        }
+                      },
+                      "toolsBySender": {
+                        "type": "object",
+                        "propertyNames": {
+                          "type": "string"
+                        },
+                        "additionalProperties": {
+                          "type": "object",
+                          "additionalProperties": false,
+                          "properties": {
+                            "allow": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
+                            "alsoAllow": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            },
+                            "deny": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          }
+                        }
+                      },
+                      "skills": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "systemPrompt": {
+                        "type": "string"
                       }
                     }
                   }
@@ -329,6 +455,10 @@
                   },
                   "description": "Chat ids the account may MANAGE (2.12.0): add/remove members, promote/demote admins, transfer ownership, export invite links; a non-empty list also unlocks createGroup. Opposite default to readChats: absent or empty means chat management is off, [\"*\"] allows every chat."
                 },
+                "discoverChats": {
+                  "type": "boolean",
+                  "description": "Allow the `dialogs` action (2.16.0) to list the group chats this account belongs to — id, title and type only, never direct chats and never message content. Off unless set: it is the one read that deliberately reaches past readChats, because its job is to find chats nobody has configured yet."
+                },
                 "twoFaPassword": {
                   "description": "The account's Telegram 2FA (cloud) password — needed only by transferOwnership, which Telegram guards with an SRP proof. Literal value, or a SecretRef resolved at account start-up.",
                   "anyOf": [
@@ -403,6 +533,26 @@
           "help": "Chat ids the assistant may manage (create groups, add/remove members, admins, ownership, invite links). Leave empty to keep chat management off; use * to allow every chat.",
           "advanced": true
         },
+        "accounts.*.groups.*.tools": {
+          "label": "Group Tool Policy",
+          "help": "Tool allow/alsoAllow/deny for this group. Applies to gateway tools (message, sessions_*, cron, memory_*, …). Under CLI backends such as claude-cli the native exec/read/write tools are not filtered per group — bind the group to a separate agent for that.",
+          "advanced": true
+        },
+        "accounts.*.groups.*.toolsBySender": {
+          "label": "Group Tool Policy by Sender",
+          "help": "Per-sender tool policy inside this group. Keys use core's typed grammar: id:<telegram id>, username:<handle>, name:<display name>, or * as the fallback.",
+          "advanced": true
+        },
+        "accounts.*.groups.*.skills": {
+          "label": "Group Skills",
+          "help": "Skill allowlist for this group. Omit to inherit the agent's skills; [] means no skills in this group.",
+          "advanced": true
+        },
+        "accounts.*.groups.*.systemPrompt": {
+          "label": "Group System Prompt",
+          "help": "Trusted prompt block appended for messages from this group — the place to state what this chat is about and what stays out of it.",
+          "advanced": true
+        },
         "accounts.*.twoFaPassword": {
           "label": "2FA Password",
           "help": "The account's Telegram two-step verification password. Only needed for ownership transfer.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawgram",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Clawgram — personal Telegram (MTProto userbot) channel for OpenClaw. Your AI assistant reads and responds as you.",
   "main": "./dist/index.js",
   "scripts": {