@0xmaxma/claude-gateway 1.3.24 → 1.3.25

package/mcp/tools/telegram/receiver-server.ts

@@ -30,13 +30,12 @@ import { homedir } from 'os'
 import { join, extname, sep } from 'path'
 import { createWorkingStateManager, drainOrphanForwards } from './typing'
 import { initDedupDir, isDuplicate as _isDuplicate, pruneDedup as _pruneDedup } from './dedup'
-import { hasMarkdown, toTelegramHtml } from './pure'
+import { hasMarkdown, toTelegramHtml, migrateAccess } from './pure'
 
 // Standalone fallback: default state dir to ~/.claude/channels/telegram
 const STATE_DIR = process.env.TELEGRAM_STATE_DIR ?? join(homedir(), '.claude', 'channels', 'telegram')
 const ACCESS_FILE = join(STATE_DIR, 'access.json')
 const APPROVED_DIR = join(STATE_DIR, 'approved')
-const AWAITING_OWNER_FILE = join(STATE_DIR, 'awaiting-owner')
 const ENV_FILE = join(STATE_DIR, '.env')
 
 // Load .env fallback when token not injected via env block (standalone mode).
@@ -126,17 +125,27 @@ type PendingEntry = {
   createdAt: number
   expiresAt: number
   replies: number
-}
-
-type GroupPolicy = {
-  requireMention: boolean
-  allowFrom: string[]
+  // Absent ⇒ 'dm'. 'group' entries hold a group id in chatId; approval pushes
+  // it into groupAllowlist (mirrors LINE).
+  kind?: 'dm' | 'group'
 }
 
 type Access = {
-  dmPolicy: 'open' | 'pairing' | 'allowlist' | 'disabled'
+  dmPolicy: 'open' | 'allowlist' | 'disabled'
+  // Orthogonal pairing toggle (mirrors LINE). Only meaningful when
+  // dmPolicy === 'allowlist': true ⇒ unknown senders get a one-time code and
+  // land in pending; false ⇒ silently dropped (pure allowlist).
+  pairing: boolean
   allowFrom: string[]
-  groups: Record<string, GroupPolicy>
+  // Group access tier (mirrors LINE): base policy, allowlisted group ids, and a
+  // single requireMention gate. `pairing` governs group code-minting too.
+  groupPolicy: 'open' | 'allowlist' | 'disabled'
+  groupAllowlist: string[]
+  requireMention: boolean
+  // Migration-only artifact — mirrors pure.ts Access — keep in sync. Enforced
+  // in gate() below so migrating a pre-split file can't silently widen a
+  // group that was previously restricted to specific senders.
+  legacyGroupAllowFrom?: Record<string, string[]>
   pending: Record<string, PendingEntry>
   mentionPatterns?: string[]
   // delivery/UX config — optional, defaults live in the reply handler
@@ -152,9 +161,12 @@ type Access = {
 
 function defaultAccess(): Access {
   return {
-    dmPolicy: 'pairing',
+    dmPolicy: 'allowlist',
+    pairing: true,
     allowFrom: [],
-    groups: {},
+    groupPolicy: 'allowlist',
+    groupAllowlist: [],
+    requireMention: true,
     pending: {},
     ackReaction: '👀',
   }
@@ -181,18 +193,8 @@ function assertSendable(f: string): void {
 function readAccessFile(): Access {
   try {
     const raw = readFileSync(ACCESS_FILE, 'utf8')
-    const parsed = JSON.parse(raw) as Partial<Access>
-    return {
-      dmPolicy: parsed.dmPolicy ?? 'pairing',
-      allowFrom: parsed.allowFrom ?? [],
-      groups: parsed.groups ?? {},
-      pending: parsed.pending ?? {},
-      mentionPatterns: parsed.mentionPatterns,
-      ackReaction: parsed.ackReaction,
-      replyToMode: parsed.replyToMode,
-      textChunkLimit: parsed.textChunkLimit,
-      chunkMode: parsed.chunkMode,
-    }
+    const parsed = JSON.parse(raw) as Partial<Access> & { dmPolicy?: string }
+    return migrateAccess(parsed) as Access
   } catch (err) {
     if ((err as NodeJS.ErrnoException).code === 'ENOENT') return defaultAccess()
     try {
@@ -212,7 +214,7 @@ function loadAccess(): Access {
 function assertAllowedChat(chat_id: string): void {
   const access = loadAccess()
   if (access.allowFrom.includes(chat_id)) return
-  if (chat_id in access.groups) return
+  if (access.groupAllowlist.includes(chat_id)) return
   throw new Error(`chat ${chat_id} is not allowlisted — add via /telegram:access`)
 }
 
@@ -238,47 +240,20 @@ function pruneExpired(a: Access, now?: number): boolean {
 type GateResult =
   | { action: 'deliver'; access: Access }
   | { action: 'drop' }
-  | { action: 'pair'; code: string; isResend: boolean }
+  | { action: 'pair'; code: string; isResend: boolean; isGroup?: boolean }
 
 function gate(ctx: Context): GateResult {
   const access = loadAccess()
   const pruned = pruneExpired(access)
   if (pruned) saveAccess(access)
 
-  if (access.dmPolicy === 'disabled') return { action: 'drop' }
-
   const from = ctx.from
   if (!from) return { action: 'drop' }
   const senderId = String(from.id)
   const chatType = ctx.chat?.type
 
-  // Owner init-pairing sentinel: first private message auto-approves sender as owner.
-  if (chatType === 'private') {
-    try {
-      const stat = statSync(AWAITING_OWNER_FILE)
-      const age = Date.now() - stat.mtimeMs
-      if (age < 10 * 60 * 1000) {
-        // Sentinel is valid — approve this sender as owner
-        if (!access.allowFrom.includes(senderId)) access.allowFrom.push(senderId)
-        saveAccess(access)
-        rmSync(AWAITING_OWNER_FILE, { force: true })
-        // Write approved file so receiver sends confirmation message
-        mkdirSync(APPROVED_DIR, { recursive: true })
-        writeFileSync(join(APPROVED_DIR, senderId), String(ctx.chat!.id))
-        return { action: 'deliver', access }
-      } else {
-        rmSync(AWAITING_OWNER_FILE, { force: true })
-      }
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
-        // Unexpected I/O error — deny to be safe rather than silently allowing
-        return { action: 'drop' }
-      }
-      // ENOENT — no sentinel, continue normal gate logic
-    }
-  }
-
   if (chatType === 'private') {
+    if (access.dmPolicy === 'disabled') return { action: 'drop' }
     if (access.dmPolicy === 'open') {
       if (!access.allowFrom.includes(senderId)) {
         access.allowFrom.push(senderId)
@@ -287,11 +262,13 @@ function gate(ctx: Context): GateResult {
       return { action: 'deliver', access }
     }
     if (access.allowFrom.includes(senderId)) return { action: 'deliver', access }
-    if (access.dmPolicy === 'allowlist') return { action: 'drop' }
+    // Base policy is 'allowlist' ('open'/'disabled' handled above). Pairing is
+    // the orthogonal toggle: off ⇒ pure allowlist (drop strangers, no code).
+    if (!access.pairing) return { action: 'drop' }
 
     // pairing mode — check for existing non-expired code for this sender
     for (const [code, p] of Object.entries(access.pending)) {
-      if (p.senderId === senderId) {
+      if ((p.kind ?? 'dm') === 'dm' && p.senderId === senderId) {
         // Reply twice max (initial + one reminder), then go silent.
         if ((p.replies ?? 1) >= 2) return { action: 'drop' }
         p.replies = (p.replies ?? 1) + 1
@@ -299,8 +276,8 @@ function gate(ctx: Context): GateResult {
         return { action: 'pair', code, isResend: true }
       }
     }
-    // Cap pending at 3. Extra attempts are silently dropped.
-    if (Object.keys(access.pending).length >= 3) return { action: 'drop' }
+    // Cap pending per-kind at 3. Extra attempts are silently dropped.
+    if (countPending(access, 'dm') >= 3) return { action: 'drop' }
 
     const code = randomBytes(3).toString('hex') // 6 hex chars
     const now = Date.now()
@@ -310,6 +287,7 @@ function gate(ctx: Context): GateResult {
       createdAt: now,
       expiresAt: now + 60 * 60 * 1000, // 1h
       replies: 1,
+      kind: 'dm',
     }
     saveAccess(access)
     return { action: 'pair', code, isResend: false }
@@ -317,14 +295,42 @@ function gate(ctx: Context): GateResult {
 
   if (chatType === 'group' || chatType === 'supergroup') {
     const groupId = String(ctx.chat!.id)
-    const policy = access.groups[groupId]
-    if (!policy) return { action: 'drop' }
-    const groupAllowFrom = policy.allowFrom ?? []
-    const requireMention = policy.requireMention ?? true
-    if (groupAllowFrom.length > 0 && !groupAllowFrom.includes(senderId)) {
+    if (access.groupPolicy === 'disabled') return { action: 'drop' }
+
+    if (access.groupPolicy === 'allowlist' && !access.groupAllowlist.includes(groupId)) {
+      // Unknown group. Pairing off ⇒ silent drop. On ⇒ mint a code keyed on the
+      // group id and post it here; a member relays it to the admin (mirrors LINE).
+      if (!access.pairing) return { action: 'drop' }
+      for (const [code, p] of Object.entries(access.pending)) {
+        if (p.kind === 'group' && p.chatId === groupId) {
+          if ((p.replies ?? 1) >= 2) return { action: 'drop' }
+          p.replies = (p.replies ?? 1) + 1
+          saveAccess(access)
+          return { action: 'pair', code, isResend: true, isGroup: true }
+        }
+      }
+      if (countPending(access, 'group') >= 3) return { action: 'drop' }
+      const code = randomBytes(3).toString('hex') // 6 hex chars
+      const now = Date.now()
+      access.pending[code] = {
+        senderId,
+        chatId: groupId,
+        createdAt: now,
+        expiresAt: now + 60 * 60 * 1000, // 1h
+        replies: 1,
+        kind: 'group',
+      }
+      saveAccess(access)
+      return { action: 'pair', code, isResend: false, isGroup: true }
+    }
+
+    // Allowlisted (or open policy) → enforce any legacy per-sender restriction
+    // that survived migration, then the single mention gate.
+    const legacyAllowed = access.legacyGroupAllowFrom?.[groupId]
+    if (legacyAllowed && legacyAllowed.length > 0 && !legacyAllowed.includes(senderId)) {
       return { action: 'drop' }
     }
-    if (requireMention && !isMentioned(ctx, access.mentionPatterns)) {
+    if (access.requireMention !== false && !isMentioned(ctx, access.mentionPatterns)) {
       return { action: 'drop' }
     }
     return { action: 'deliver', access }
@@ -333,6 +339,15 @@ function gate(ctx: Context): GateResult {
   return { action: 'drop' }
 }
 
+/** Count pending entries of a given kind (absent kind ⇒ 'dm'). */
+function countPending(access: Access, kind: 'dm' | 'group'): number {
+  let n = 0
+  for (const p of Object.values(access.pending)) {
+    if ((p.kind ?? 'dm') === kind) n++
+  }
+  return n
+}
+
 function isMentioned(ctx: Context, extraPatterns?: string[]): boolean {
   const entities = ctx.message?.entities ?? ctx.message?.caption_entities ?? []
   const text = ctx.message?.text ?? ctx.message?.caption ?? ''
@@ -750,6 +765,17 @@ type AttachmentMeta = {
   name?: string
 }
 
+// Pairing reply shown to an un-allowlisted sender: their one-time code plus
+// the instruction to report it to the admin. Shared by handleInbound (normal
+// message) and the /start command so both hand the code out identically.
+function pairingReplyText(code: string, isResend: boolean, isGroup = false): string {
+  const lead = isResend ? 'Still waiting for approval.' : 'This bot is private.'
+  const share = isGroup
+    ? 'Share this code with an admin to enable me in this group.'
+    : 'Share this code with the admin to get access.'
+  return `${lead}\n\nPairing code: ${code}\n\n${share}`
+}
+
 async function handleInbound(
   ctx: Context,
   text: string,
@@ -767,10 +793,11 @@ async function handleInbound(
   if (result.action === 'drop') return
 
   if (result.action === 'pair') {
-    const lead = result.isResend ? 'Still pending' : 'Pairing required'
-    await ctx.reply(
-      `${lead} — run in Claude Code:\n\n/telegram:access pair ${result.code}`,
-    )
+    // LINE-style: hand the user their code and let the admin approve it from
+    // the web UI. The user does NOT run any command (they may not have Claude
+    // Code at all) — they just report the code to the admin, who verifies it
+    // matches what's shown in Pending and clicks Approve.
+    await ctx.reply(pairingReplyText(result.code, result.isResend, result.isGroup))
     return
   }
 
@@ -915,18 +942,21 @@ if (!SEND_ONLY) {
 
 bot.command('start', async ctx => {
   if (ctx.chat?.type !== 'private') return
-  const access = loadAccess()
-  if (access.dmPolicy === 'disabled') {
-    await ctx.reply(`This bot isn't accepting new connections.`)
+  // Route /start through the same gate as a first message so a new user gets
+  // their pairing code immediately (LINE-style), instead of an instruction to
+  // send another message. The literal "/start" text is never relayed to Claude.
+  const result = gate(ctx)
+  if (result.action === 'pair') {
+    await ctx.reply(pairingReplyText(result.code, result.isResend))
     return
   }
-  await ctx.reply(
-    `This bot bridges Telegram to a Claude Code session.\n\n` +
-    `To pair:\n` +
-    `1. DM me anything — you'll get a 6-char code\n` +
-    `2. In Claude Code: /telegram:access pair <code>\n\n` +
-    `After that, DMs here reach that session.`
-  )
+  if (result.action === 'deliver') {
+    // Already allowlisted (or an open-policy bot) — nothing to pair.
+    await ctx.reply(`You're paired. Just send me a message and it reaches the assistant.`)
+    return
+  }
+  // drop — dmPolicy disabled, or pure allowlist (pairing off) for an unknown sender.
+  await ctx.reply(`This bot isn't accepting new connections right now.`)
 })
 
 bot.command('help', async ctx => {
@@ -969,7 +999,7 @@ bot.command('status', async ctx => {
   for (const [code, p] of Object.entries(access.pending)) {
     if (p.senderId === senderId) {
       await ctx.reply(
-        `Pending pairing — run in Claude Code:\n\n/telegram:access pair ${code}`
+        `Pending approval.\n\nYour pairing code: ${code}\n\nShare it with the admin to get access.`
       )
       return
     }

package/mcp/tools/telegram/skills/access/SKILL.md

@@ -63,22 +63,58 @@ APPROVED_DIR = {STATE_DIR}/approved
 
 ```json
 {
-  "dmPolicy": "pairing",
+  "dmPolicy": "allowlist",
+  "pairing": true,
   "allowFrom": ["<senderId>", ...],
-  "groups": {
-    "<groupId>": { "requireMention": true, "allowFrom": [] }
-  },
+  "groupPolicy": "allowlist",
+  "groupAllowlist": ["<groupId>", ...],
+  "requireMention": true,
+  "legacyGroupAllowFrom": { "<groupId>": ["<senderId>", ...] },
   "pending": {
     "<6-char-code>": {
       "senderId": "...", "chatId": "...",
-      "createdAt": <ms>, "expiresAt": <ms>
+      "createdAt": <ms>, "expiresAt": <ms>,
+      "kind": "dm"
     }
   },
   "mentionPatterns": ["@mybot"]
 }
 ```
 
-Missing file = `{dmPolicy:"pairing", allowFrom:[], groups:{}, pending:{}}`.
+`dmPolicy` is the base access policy: `open` | `allowlist` | `disabled`.
+`pairing` is an **orthogonal on/off toggle** (mirrors LINE), only meaningful
+when `dmPolicy`/`groupPolicy` is `allowlist`: `true` ⇒ an unknown sender or
+group gets a one-time 6-char code that lands in `pending` for the admin to
+approve; `false` ⇒ silently dropped (pure allowlist).
+
+The **group tier** mirrors LINE: `groupPolicy` (`open` | `allowlist` |
+`disabled`) is the base policy for groups, `groupAllowlist` holds the approved
+group ids (negative numbers, e.g. `-1001234567890`), and `requireMention` (a
+single boolean) gates whether the bot answers in an allowlisted group only when
+@mentioned. A `pending` entry with `"kind": "group"` is a group knock — its
+`chatId` is the group id and `pair`-ing it adds that id to `groupAllowlist`
+(not `allowFrom`). Entries with no `kind` (or `"kind": "dm"`) are DM knocks.
+
+**Group delivery caveat (Telegram Privacy Mode).** Allowlisting a group only
+decides how the gate *responds* — it does nothing if Telegram never delivers the
+message. Bots default to **Privacy Mode ON** (`getMe` →
+`can_read_all_group_messages: false`), so in a group the bot only receives
+`/commands`, @mentions of its username, and replies to its own messages; plain
+messages are filtered out before the gateway sees them. And bot commands are
+DM-only (dropped in groups). So a group can be correctly allowlisted yet stay
+silent, and an unknown group may never mint a pairing code. Tell the user to
+**promote the bot to Admin in the group** (an admin bot receives everything
+regardless of Privacy Mode) or **disable Privacy Mode in BotFather and re-add the
+bot**. This is a Telegram-side setting — `/telegram:access` cannot change it.
+
+`legacyGroupAllowFrom` is a **migration-only artifact**, not a live feature —
+it's how a pre-split file's per-group sender restriction survives migration
+(the old schema could lock a group to specific senders; the current model has
+no per-user group tier). If present, it's enforced silently in addition to
+`requireMention`. Preserve this key as-is whenever you read/rewrite the file —
+never invent, edit, or add entries to it; there is no command for that.
+
+Missing file = `{dmPolicy:"allowlist", pairing:true, allowFrom:[], groupPolicy:"allowlist", groupAllowlist:[], requireMention:true, pending:{}}`.
 
 ---
 
@@ -89,22 +125,27 @@ Parse `$ARGUMENTS` (space-separated). If empty or unrecognized, show status.
 ### No args — status
 
 1. Read `{STATE_DIR}/access.json` (handle missing file).
-2. Show: dmPolicy, allowFrom count and list, pending count with codes +
-   sender IDs + age, groups count.
+2. Show: dmPolicy, the pairing toggle (on/off), allowFrom count and list,
+   pending count with codes + sender IDs + kind (dm/group) + age, groupPolicy,
+   requireMention, and the groupAllowlist count and list.
 
 ### `pair <code>`
 
 1. Read `{STATE_DIR}/access.json`.
 2. Look up `pending[<code>]`. If not found or `expiresAt < Date.now()`,
    tell the user and stop.
-3. Extract `senderId` and `chatId` from the pending entry.
-4. Add `senderId` to `allowFrom` (dedupe).
-5. Delete `pending[<code>]`.
-6. Write the updated access.json.
-7. `mkdir -p {STATE_DIR}/approved` then write
-   `{STATE_DIR}/approved/<senderId>` with `chatId` as the
-   file contents. The channel server polls this dir and sends "you're in".
-8. Confirm: who was approved (senderId).
+3. **Kind-aware.** If the entry's `kind` is `"group"`:
+   - Add its `chatId` (the group id) to `groupAllowlist` (dedupe).
+   - Delete `pending[<code>]`, write access.json. **No** `approved/` file (a
+     group has no single recipient — the bot silently starts answering there).
+   - Confirm which group id was allowed.
+   Otherwise (DM knock, `kind` absent or `"dm"`):
+   - Add `senderId` to `allowFrom` (dedupe).
+   - Delete `pending[<code>]`, write access.json.
+   - `mkdir -p {STATE_DIR}/approved` then write
+     `{STATE_DIR}/approved/<senderId>` with `chatId` as the file contents. The
+     channel server polls this dir and sends "you're in".
+   - Confirm who was approved (senderId).
 
 ### `deny <code>`
 
@@ -123,19 +164,48 @@ Parse `$ARGUMENTS` (space-separated). If empty or unrecognized, show status.
 
 ### `policy <mode>`
 
-1. Validate `<mode>` is one of `pairing`, `allowlist`, `disabled`.
+1. Validate `<mode>` is one of `open`, `allowlist`, `disabled`.
+   (Pairing is no longer a policy value — it's the separate `pairing` toggle
+   below. `allowlist` + `pairing on` is the capture-unknown-users mode.)
 2. Read (create default if missing), set `dmPolicy`, write.
 
-### `group add <groupId>` (optional: `--no-mention`, `--allow id1,id2`)
+### `pairing <on|off>`
+
+Toggle the orthogonal pairing code layer (only affects `dmPolicy: "allowlist"`).
+
+1. Validate `<value>` is `on` or `off`.
+2. Read (create default if missing), set `pairing` to `true`/`false`, write.
+3. Confirm. When `on`: unknown senders receive a one-time code and appear in
+   `pending` for you to `pair`. When `off`: unknown senders are dropped
+   silently (pure allowlist).
+
+### `group policy <mode>`
+
+1. Validate `<mode>` is one of `open`, `allowlist`, `disabled`.
+2. Read (create default if missing), set `groupPolicy`, write.
+   (`allowlist` + `pairing on` is the capture-unknown-groups mode: an unknown
+   group gets a pairing code posted in it.)
+
+### `group allow <groupId>`
 
 1. Read (create default if missing).
-2. Set `groups[<groupId>] = { requireMention: !hasFlag("--no-mention"),
-   allowFrom: parsedAllowList }`.
-3. Write.
+2. Add `<groupId>` to `groupAllowlist` (dedupe). Write.
+   (Group ids are negative numbers, e.g. `-1001234567890`.)
+
+### `group deny <groupId>`
+
+1. Read, filter `groupAllowlist` to exclude `<groupId>`, also delete
+   `legacyGroupAllowFrom[<groupId>]` if present (so a later re-add doesn't
+   resurrect a stale restriction), write.
+
+### `group mention <on|off>`
 
-### `group rm <groupId>`
+Toggle the single group mention gate (`requireMention`).
 
-1. Read, `delete groups[<groupId>]`, write.
+1. Validate `<value>` is `on` or `off`.
+2. Read (create default if missing), set `requireMention` to `true`/`false`, write.
+3. Confirm. When `on`: the bot answers in an allowlisted group only when
+   @mentioned (or replied to). When `off`: it answers every message there.
 
 ### `set <key> <value>`
 

package/mcp/tools/telegram/skills/configure/SKILL.md

@@ -51,46 +51,44 @@ Read both state files and give the user a complete picture:
    (`123456789:...`).
 
 2. **Access** — read `{STATE_DIR}/access.json` (missing file
-   = defaults: `dmPolicy: "pairing"`, empty allowlist). Show:
-   - DM policy and what it means in one line
+   = defaults: `dmPolicy: "allowlist"`, `pairing: true`, empty allowlist). Show:
+   - DM policy (`open`/`allowlist`/`disabled`) and what it means in one line
+   - Pairing toggle (on/off) and what it means in one line
    - Allowed senders: count, and list display names or IDs
    - Pending pairings: count, with codes and display names if any
 
 3. **What next** — end with a concrete next step based on state:
    - No token → *"Run `/telegram:configure <token>` with the token from
      BotFather."*
-   - Token set, policy is pairing, nobody allowed → *"DM your bot on
-     Telegram. It replies with a code; approve with `/telegram:access pair
-     <code>`."*
+   - Token set, `allowlist` + pairing on, nobody allowed → *"DM your bot on
+     Telegram. It replies with a code — approve it from the web Channels card
+     (or run `/telegram:access pair <code>` here)."*
    - Token set, someone allowed → *"Ready. DM your bot to reach the
      assistant."*
 
-**Push toward lockdown — always.** The goal for every setup is `allowlist`
-with a defined list. `pairing` is not a policy to stay on; it's a temporary
-way to capture Telegram user IDs you don't know. Once the IDs are in, pairing
-has done its job and should be turned off.
+**The access model.** The base policy should be `allowlist` — only people on
+the list reach the assistant. **Pairing** is an orthogonal on/off toggle
+(default on) that sits on top of `allowlist`: when on, an unknown sender who
+DMs the bot gets a one-time code that shows up in Pending, and the admin
+approves it (from the web Channels card, or `/telegram:access pair <code>`).
+It's a lightweight identity check, and it's fine to leave on as your standing
+way to let new people in. Turn pairing **off** only if you want a hard
+allowlist where strangers are dropped silently with no code.
 
 Drive the conversation this way:
 
 1. Read the allowlist. Tell the user who's in it.
 2. Ask: *"Is that everyone who should reach you through this bot?"*
-3. **If yes and policy is still `pairing`** → *"Good. Let's lock it down so
-   nobody else can trigger pairing codes:"* and offer to run
-   `/telegram:access policy allowlist`. Do this proactively — don't wait to
-   be asked.
-4. **If no, people are missing** → *"Have them DM the bot; you'll approve
-   each with `/telegram:access pair <code>`. Run this skill again once
-   everyone's in and we'll lock it."*
-5. **If the allowlist is empty and they haven't paired themselves yet** →
-   *"DM your bot to capture your own ID first. Then we'll add anyone else
-   and lock it down."*
-6. **If policy is already `allowlist`** → confirm this is the locked state.
-   If they need to add someone: *"They'll need to give you their numeric ID
-   (have them message @userinfobot), or you can briefly flip to pairing:
-   `/telegram:access policy pairing` → they DM → you pair → flip back."*
-
-Never frame `pairing` as the correct long-term choice. Don't skip the lockdown
-offer.
+3. **If someone's missing** → *"Leave pairing on: have them DM the bot, then
+   approve the code that appears in Pending (web card or `/telegram:access
+   pair <code>`)."*
+4. **If the allowlist is empty and they haven't paired themselves yet** →
+   *"DM your bot to capture your own ID first — approve the code and you're
+   in."*
+5. **If they want a hard lockdown** (no new codes for strangers) → offer to
+   run `/telegram:access pairing off`. This keeps `allowlist` but stops
+   minting codes; add people later by flipping pairing back on, or with
+   `/telegram:access allow <senderId>`.
 
 ### `<token>` — save it
 
@@ -116,3 +114,10 @@ Delete the `TELEGRAM_BOT_TOKEN=` line (or the file if that's the only line).
   or `/reload-plugins`. Say so after saving.
 - `access.json` is re-read on every inbound message — policy changes via
   `/telegram:access` take effect immediately, no restart.
+- **Groups need more than allowlisting.** DMs work over long-polling, but in a
+  group Telegram's default **Privacy Mode** stops the bot from receiving plain
+  messages (it only gets `/commands`, @mentions, and replies), and commands are
+  dropped in groups anyway. To use groups, tell the user to promote the bot to
+  **Admin** in the group (or disable Privacy Mode in BotFather and re-add it),
+  then allowlist the group via `/telegram:access` (pairing code or `group allow
+  <groupId>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xmaxma/claude-gateway",
-  "version": "1.3.24",
+  "version": "1.3.25",
   "description": "Multi-agent gateway for Claude",
   "repository": {
     "type": "git",