polygram 0.6.16 → 0.7.1

package/lib/telegram.js

@@ -20,7 +20,13 @@
  */
 
 const crypto = require('crypto');
-const { toTelegramMarkdown } = require('./telegram-format');
+const {
+  toTelegramMarkdown,
+  isHtmlParseError,
+  isMessageNotModifiedError,
+  isRateLimitError,
+  getRetryAfterMs,
+} = require('./telegram-format');
 const { isSafeToRetry, redactBotToken } = require('./net-errors');
 
 // Topic deletion race: a user can delete a forum topic while a turn is in
@@ -112,7 +118,30 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   const text = deriveOutboundText(method, params, meta);
   const tracksMessage = !METHODS_WITHOUT_MSG.has(method);
 
+  // 0.7.0: snapshot the field that applyFormatting will convert and the
+  // current parse_mode state, so the HTML→plain fallback (if Telegram
+  // rejects the converted payload with `400 can't parse entities`) can
+  // restore the raw value and retry without parse_mode. Mirrors the
+  // applyFormatting decision (must run BEFORE applyFormatting mutates).
+  const willFormat = !meta.plainText
+    && FORMATTABLE_METHODS.has(method)
+    && params.parse_mode == null;
+  const formatField = willFormat ? (params.text ? 'text' : (params.caption ? 'caption' : null)) : null;
+  const rawFieldValue = formatField ? params[formatField] : null;
+
   applyFormatting(method, params, meta);
+  const formattingApplied = formatField && params.parse_mode === 'HTML';
+
+  // 0.7.0: per-bot/chat link-preview opt-out. When meta.linkPreview is
+  // explicitly false, suppress Telegram's auto-generated preview cards
+  // for any URL in the body (they clutter chats and add visual noise).
+  // Default (no flag set) preserves Telegram's native preview behavior
+  // — matches OpenClaw's account.config.linkPreview opt-out.
+  if (meta.linkPreview === false
+      && (method === 'sendMessage' || method === 'editMessageText')
+      && params.link_preview_options == null) {
+    params.link_preview_options = { is_disabled: true };
+  }
 
   // Capture which inbound this reply targets so the boot-replay dedupe
   // (`hasOutboundReplyTo`) can match outbound→inbound. Without this every
@@ -142,60 +171,151 @@ async function send({ bot, method, params, db = null, meta = {}, logger = consol
   }
 
   let res;
-  const attempt = async (p) => bot.api.raw[method](p);
-  try {
+  const rawAttempt = async (p) => bot.api.raw[method](p);
+
+  // OpenClaw-style fallback layers, composing outermost-to-innermost:
+  //
+  //   withThreadFallback (outer)  — strips message_thread_id and
+  //                                 retries on TOPIC_DELETED / "thread
+  //                                 not found"
+  //   withPreConnectRetry         — single retry on transient pre-
+  //                                 connect errors (DNS flap, TCP
+  //                                 refused, ENETUNREACH); never
+  //                                 retries post-connect errors that
+  //                                 might have landed
+  //   safeAttempt                 — sleeps `retry_after` and retries
+  //                                 once on 429
+  //   tryOnce (innermost)         — handles two per-call recoveries:
+  //                                 (a) MESSAGE_NOT_MODIFIED on
+  //                                 editMessageText → synthetic
+  //                                 success (streamer debounce often
+  //                                 lands on no-op edits, Telegram
+  //                                 returns 400 we don't want to
+  //                                 propagate); (b) HTML parse error
+  //                                 → retry as plain text with the
+  //                                 raw pre-conversion field value
+  //                                 restored
+  //   rawAttempt                  — bot.api.raw[method](params)
+  //
+  // Each layer is a closure built per call; allocation cost is
+  // negligible vs. network RTT.
+  const RETRY_AFTER_CAP_MS = 60_000;
+  const tryOnce = async (p) => {
     try {
-      res = await attempt(params);
+      return await rawAttempt(p);
+    } catch (err) {
+      if (method === 'editMessageText' && isMessageNotModifiedError(err)) {
+        try { db?.logEvent('telegram-edit-skip-not-modified', { chat_id: chatId, message_id: p.message_id }); }
+        catch {}
+        // Synthetic success — message_id known, date best-effort.
+        return { message_id: p.message_id, date: Math.floor(Date.now() / 1000), _notModified: true };
+      }
+      if (formattingApplied && isHtmlParseError(err)) {
+        logger.warn?.(`[telegram] ${method}: HTML parse error, retrying as plain text`);
+        try {
+          db?.logEvent('telegram-html-fallback', {
+            chat_id: chatId, method,
+            error: redactBotToken(err.message)?.slice(0, 200),
+          });
+        } catch {}
+        const plainParams = { ...p };
+        delete plainParams.parse_mode;
+        plainParams[formatField] = rawFieldValue;
+        try {
+          return await rawAttempt(plainParams);
+        } catch (plainErr) {
+          // 0.7.1: if the plain retry also fails, preserve BOTH errors
+          // in the message that propagates. Pre-fix, only `plainErr`
+          // bubbled up — operators investigating from markOutboundFailed
+          // saw e.g. "Forbidden: bot was kicked" and missed that the
+          // ORIGINAL failure was a markdown→HTML parse bug.
+          const origMsg = redactBotToken(err.message)?.slice(0, 200);
+          const wrapped = new Error(`plain-retry failed (after HTML parse error: ${origMsg}): ${plainErr.message}`);
+          if (plainErr.code) wrapped.code = plainErr.code;
+          if (plainErr.parameters) wrapped.parameters = plainErr.parameters;
+          throw wrapped;
+        }
+      }
+      throw err;
+    }
+  };
+  const safeAttempt = async (p) => {
+    try {
+      return await tryOnce(p);
+    } catch (err) {
+      if (!isRateLimitError(err)) throw err;
+      // Sleep retry_after then retry once. Cap at 60s so a misconfigured
+      // value can't park the call indefinitely.
+      const ms = Math.min(getRetryAfterMs(err) ?? 1000, RETRY_AFTER_CAP_MS);
+      logger.warn?.(`[telegram] ${method}: 429 rate-limited, retry-after ${ms}ms`);
+      try { db?.logEvent('telegram-rate-limit', { chat_id: chatId, method, retry_after_ms: ms }); }
+      catch {}
+      await sleep(ms);
+      return await tryOnce(p);
+    }
+  };
+
+  // 0.7.0: pre-connect retry layer (single retry on transient pre-conn
+  // errors). Composes inside thread-fallback so a re-attempt without
+  // thread_id also benefits from the retry.
+  const withPreConnectRetry = async (p) => {
+    try {
+      return await safeAttempt(p);
     } catch (err) {
       // Pre-connect errors (DNS flap, TCP refused, net unreach) never
-      // reached Telegram, so retrying can't double-send. Retry ONCE after
-      // a short delay before treating as fatal. Post-connect errors
-      // (ETIMEDOUT, EPIPE, 5xx) are NOT retried — the message might have
-      // landed server-side.
+      // reached Telegram, so retrying can't double-send. Retry ONCE
+      // after a short delay before treating as fatal. Post-connect
+      // errors (ETIMEDOUT, EPIPE, 5xx) are NOT retried — the message
+      // might have landed server-side.
       if (isSafeToRetry(err)) {
         try { db?.logEvent('telegram-retry', { chat_id: chatId, method, code: err.code, name: err.name }); }
         catch {}
         await sleep(PRE_CONNECT_RETRY_DELAY_MS);
-        res = await attempt(params);
-      } else {
-        throw err;
+        return await safeAttempt(p);
       }
+      throw err;
     }
-  } catch (err) {
-    // Forum topic was deleted mid-turn — retry to chat root rather than
-    // failing the whole reply. Only for methods that accept a thread id
-    // (send*), and only once per call.
-    if (isThreadNotFound(err) && params.message_thread_id != null) {
-      const retryParams = { ...params };
+  };
+
+  // 0.7.0: thread-fallback layer (port of OpenClaw's
+  // withTelegramThreadFallback). On `message thread not found` /
+  // TOPIC_DELETED, retry once with thread_id stripped — the reply
+  // lands in the chat root instead of the deleted topic.
+  const withThreadFallback = async (p) => {
+    try {
+      return await withPreConnectRetry(p);
+    } catch (err) {
+      if (!isThreadNotFound(err) || p.message_thread_id == null) throw err;
+      const retryParams = { ...p };
       delete retryParams.message_thread_id;
+      logger.error?.(`[telegram] ${method}: thread gone, retrying without thread_id`);
       try {
-        logger.error?.(`[telegram] ${method}: thread gone, retrying without thread_id`);
-        res = await bot.api.raw[method](retryParams);
-        try { db?.logEvent('telegram-thread-fallback', { chat_id: chatId, method, original_thread_id: String(params.message_thread_id) }); }
+        const out = await withPreConnectRetry(retryParams);
+        try { db?.logEvent('telegram-thread-fallback', { chat_id: chatId, method, original_thread_id: String(p.message_thread_id) }); }
         catch {}
+        return out;
       } catch (err2) {
-        if (rowId != null && db) {
-          // 0.6.14: redact bot tokens before persisting err.message —
-          // some undici/network error shapes embed the request URL
-          // (which carries `bot${TOKEN}`) into err.message.
-          const safe2 = redactBotToken(err2.message);
-          try { db.markOutboundFailed(rowId, safe2); }
-          catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
-          try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: safe2 }); }
-          catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
-        }
+        // Re-throw with the SECOND error — that's the actually-fatal
+        // one (the thread-fallback retry didn't save us).
         throw err2;
       }
-    } else {
-      if (rowId != null && db) {
-        const safe = redactBotToken(err.message);
-        try { db.markOutboundFailed(rowId, safe); }
-        catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
-        try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: safe }); }
-        catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
-      }
-      throw err;
     }
+  };
+
+  try {
+    res = await withThreadFallback(params);
+  } catch (err) {
+    if (rowId != null && db) {
+      // 0.6.14: redact bot tokens before persisting err.message —
+      // some undici/network error shapes embed the request URL
+      // (which carries `bot${TOKEN}`) into err.message.
+      const safe = redactBotToken(err.message);
+      try { db.markOutboundFailed(rowId, safe); }
+      catch (e) { logger.error(`[telegram] markOutboundFailed: ${e.message}`); }
+      try { db.logEvent('telegram-api-error', { chat_id: chatId, method, error: safe }); }
+      catch (e) { logger.error(`[telegram] logEvent: ${e.message}`); }
+    }
+    throw err;
   }
 
   if (rowId != null && db) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.6.16",
+  "version": "0.7.1",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc-client.js",
   "bin": {

package/polygram.js

@@ -32,6 +32,9 @@ const { parseBotArg, parseDbArg, filterConfigToBot } = require('./lib/config-sco
 const { createStore: createPairingsStore, parseTtl: parsePairingTtl } = require('./lib/pairings');
 const { transcribe: transcribeVoice, isVoiceAttachment } = require('./lib/voice');
 const { createStreamer } = require('./lib/stream-reply');
+const { chunkMarkdownText } = require('./lib/telegram-chunk');
+const { deliverReplies } = require('./lib/deliver');
+const { announce, shouldAnnounce } = require('./lib/announces');
 const { isAbortRequest } = require('./lib/abort-detector');
 const { startTyping } = require('./lib/typing-indicator');
 const { redactBotToken } = require('./lib/net-errors');
@@ -909,22 +912,6 @@ function parseResponse(text) {
   return { text: trimmed, sticker: null, stickerLabel: null, reaction: null };
 }
 
-// ─── Reply chunking ─────────────────────────────────────────────────
-
-function chunkText(text, maxLen = TG_MAX_LEN) {
-  if (text.length <= maxLen) return [text];
-  const chunks = [];
-  let remaining = text;
-  while (remaining.length > 0) {
-    if (remaining.length <= maxLen) { chunks.push(remaining); break; }
-    let splitAt = remaining.lastIndexOf('\n', maxLen);
-    if (splitAt < maxLen * 0.3) splitAt = maxLen;
-    chunks.push(remaining.slice(0, splitAt));
-    remaining = remaining.slice(splitAt).replace(/^\n/, '');
-  }
-  return chunks;
-}
-
 // ─── Cron/IPC send ─────────────────────────────────────────────────
 
 // Allowlist of Telegram Bot API methods external callers (cron) may invoke.
@@ -1663,11 +1650,18 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   });
 
   const botCfg = config.bot || {};
+  // 0.7.0: per-chat / per-bot link-preview opt-out (port from OpenClaw).
+  // chat-level wins over bot-level. Default (both undefined) preserves
+  // Telegram's native auto-preview behavior.
+  const linkPreview = chatConfig.linkPreview != null
+    ? chatConfig.linkPreview
+    : botCfg.linkPreview;
   const outMetaBase = {
     source: 'bot-reply-stream',
     botName: BOT_NAME,
     model: chatConfig.model,
     effort: chatConfig.effort,
+    ...(linkPreview === false ? { linkPreview: false } : {}),
   };
 
   // Streaming is unconditional as of 0.4.0 — matches OpenClaw's model and
@@ -1710,6 +1704,21 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         throw err;
       }
     },
+    deleteMessage: async (messageId) => {
+      // 0.7.0: route preview-discard through tg() so the action is
+      // visible in the events log and gets the same retry/network
+      // protections as other API calls. Failure is non-fatal: stale
+      // bubble at chat top is acceptable when the actual reply has
+      // already been redelivered as fresh chunks.
+      try {
+        await tg(bot, 'deleteMessage', {
+          chat_id: chatId, message_id: messageId,
+        }, { source: 'bot-reply-stream-discard', botName: BOT_NAME });
+      } catch (err) {
+        console.error(`[${label}] discard preview failed: ${err.message}`);
+        throw err;
+      }
+    },
     minChars: botCfg.streamMinChars,
     throttleMs: botCfg.streamThrottleMs,
     logger: { error: (m) => console.error(`[${label}] ${m}`) },
@@ -1739,12 +1748,13 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
   // at which point we flip to THINKING (🤔).
   reactor.setState('QUEUED');
 
-  // Mark the inbound row terminal so boot replay doesn't pick it up again.
-  // Must fire down EVERY non-throwing exit path (early returns for error/
-  // NO_REPLY, streamed-reply early return, regular reply at end). 0.5.4
-  // hardened this — earlier versions only marked at the bottom of try, so
-  // streamed replies (which return at line ~1477) left handler_status
-  // stuck at 'dispatched' forever, causing replay loops on every restart.
+  // Mark the inbound row terminal so boot replay doesn't pick it up
+  // again. Must fire down EVERY non-throwing exit path (early returns
+  // for error / NO_REPLY, streamed-reply preview-becomes-final, the
+  // discard+redeliver branch, regular reply at end). Earlier versions
+  // only marked at the bottom of try, so streamed-reply early returns
+  // left handler_status stuck at 'dispatched' forever and the next
+  // boot replayed every long turn.
   const markReplied = () => dbWrite(() => db.setInboundHandlerStatus({
     chat_id: chatId, msg_id: msg.message_id, status: 'replied',
   }), 'set handler_status=replied');
@@ -1782,34 +1792,117 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
       reactor.clear().catch(() => {});
     }
 
-    if (!result.text || result.text === 'NO_REPLY') { markReplied(); return; }
+    // 0.7.0: empty-response fallback (port from OpenClaw —
+    // EMPTY_RESPONSE_FALLBACK at reply-CdjLMJxg.js:40323). When
+    // Claude finishes WITHOUT producing any text (e.g. only tool
+    // calls, or aborted before writing the assistant message), send
+    // a placeholder so the user doesn't see silence with no reaction.
+    // NO_REPLY is an explicit "stay silent" signal from the agent —
+    // those still markReplied silently.
+    if (result.text === 'NO_REPLY') { markReplied(); return; }
+    if (!result.text) {
+      // 0.7.1: if the fallback send itself fails, throw rather than
+      // silently markReplied — the user gets nothing AND the inbound
+      // is marked replied so boot replay won't redispatch. Same
+      // anti-pattern that caused msg-10794. Promote to a thrown error
+      // so dispatchHandleMessage's catch branches correctly:
+      //   shutdown   → 'replay-pending' (boot replay retries)
+      //   runtime    → 'failed' + user-visible apology via errorReplyText
+      try {
+        await tg(bot, 'sendMessage', {
+          chat_id: chatId,
+          text: 'No response generated. Please try again.',
+          ...(threadId && { message_thread_id: threadId }),
+          reply_parameters: { message_id: msg.message_id, allow_sending_without_reply: true },
+        }, { ...outMetaBase, source: 'empty-response-fallback' });
+      } catch (err) {
+        reactor.setState('ERROR');
+        logEvent('telegram-empty-response-fallback-failed', {
+          chat_id: chatId, msg_id: msg.message_id, bot: BOT_NAME,
+          error: err.message?.slice(0, 200),
+        });
+        throw new Error(`empty-response fallback send failed: ${err.message}`);
+      }
+      logEvent('telegram-empty-response-fallback', {
+        chat_id: chatId, msg_id: msg.message_id, bot: BOT_NAME,
+      });
+      markReplied();
+      return;
+    }
 
     const parsed = parseResponse(result.text);
     const outMeta = { ...outMetaBase, sessionId: result.sessionId, costUsd: result.cost };
 
-    // Streamed text path: finalise the live-edit and, if the full response
-    // overflows Telegram's 4096 cap, send remainder as follow-up chunks.
+    // OpenClaw's preview-becomes-final flow:
+    //
+    //   1. flushDraft() — drain any pending throttled edit so the
+    //      bubble's visible state is up-to-date before deciding.
+    //   2. finalize(parsed.text) — try to bring the bubble to the
+    //      final body. Returns rich result describing whether the
+    //      preview can stand as the final reply.
+    //   3a. finalEditOk:true        → preview IS final, done.
+    //   3b. overflow OR !finalEditOk → discard preview, redeliver
+    //      via deliverReplies(chunkMarkdownText(...)). The bubble
+    //      couldn't render the full body (size or parse error), so
+    //      we delete it cleanly and send the proper chunks fresh at
+    //      chat bottom — no content lost, no stranded bubble.
     if (parsed.text) {
+      await streamer.flushDraft();
       const fin = await streamer.finalize(parsed.text);
       if (fin.streamed) {
-        if (parsed.text.length > TG_MAX_LEN) {
-          const rest = parsed.text.slice(TG_MAX_LEN - 3);
-          for (const chunk of chunkText(rest)) {
-            try {
-              await tg(bot, 'sendMessage', {
-                chat_id: chatId, text: chunk,
-                ...(threadId && { message_thread_id: threadId }),
-              }, outMeta);
-            } catch (err) {
-              console.error(`[${label}] overflow sendMessage failed: ${err.message}`);
-            }
+        if (fin.finalEditOk) {
+          // Preview was successfully edited to the final text.
+          // No follow-up messages needed.
+          console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | streamed | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
+          markReplied();
+          return;
+        }
+        // Preview can't hold the final body (overflow OR last edit
+        // failed even after our HTML→plain fallback). Delete it and
+        // send the body as proper chunks.
+        try { await streamer.discard(); }
+        catch (err) { console.error(`[${label}] discard failed: ${err.message}`); }
+        const chunks = chunkMarkdownText(parsed.text, TG_MAX_LEN);
+        const r = await deliverReplies({
+          bot,
+          send: (b, method, params, m) => tg(b, method, params, m),
+          chatId,
+          threadId,
+          chunks,
+          replyToMessageId: msg.message_id,
+          meta: outMeta,
+          logger: { error: (m) => console.error(`[${label}] ${m}`) },
+        });
+        const reason = fin.overflow ? 'overflow' : 'edit-failed';
+        logEvent('telegram-stream-redeliver', {
+          chat_id: chatId, msg_id: msg.message_id,
+          reason, chunks: chunks.length,
+          delivered: r.sent.length, failed: r.failed.length,
+          bot: BOT_NAME,
+        });
+        // 0.7.1: surface partial-failure to the user. Without this,
+        // a chunk-3-of-5 failure leaves a coherent-looking reply with
+        // a silent gap (the user reads chunks 1, 2, 4, 5 unaware
+        // that chunk 3 was dropped). Append a warning + flip the
+        // reactor to ERROR so something visible signals "look here".
+        if (r.failed.length > 0) {
+          reactor.setState('ERROR');
+          try {
+            await tg(bot, 'sendMessage', {
+              chat_id: chatId,
+              text: `⚠️ ${r.failed.length} of ${chunks.length} message parts failed to deliver. The reply may be incomplete — please retry.`,
+              ...(threadId && { message_thread_id: threadId }),
+            }, { ...outMetaBase, source: 'partial-delivery-warning' });
+          } catch (warnErr) {
+            console.error(`[${label}] partial-delivery warning failed: ${warnErr.message}`);
           }
         }
-        console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | streamed | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
+        console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | streamed-redeliver(${reason}, ${chunks.length} chunks${r.failed.length ? `, ${r.failed.length} failed` : ''}) | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
         markReplied();
         return;
       }
-      // Not streamed (response too short) — fall through to normal path.
+      // Not streamed (response too short — never crossed minChars).
+      // Fall through to the normal send path below.
     }
 
     if (parsed.reaction) {
@@ -1829,19 +1922,20 @@ async function handleMessage(sessionKey, chatId, msg, bot) {
         console.error(`[${label}] sendSticker failed: ${err.message}`);
       });
     } else if (parsed.text) {
-      const chunks = chunkText(parsed.text);
-      for (let i = 0; i < chunks.length; i++) {
-        const params = {
-          chat_id: chatId, text: chunks[i],
-          ...(threadId && { message_thread_id: threadId }),
-        };
-        if (i === 0) params.reply_parameters = { message_id: msg.message_id };
-        try {
-          await tg(bot, 'sendMessage', params, outMeta);
-        } catch (err) {
-          console.error(`[${label}] sendMessage failed (chunk ${i + 1}/${chunks.length}): ${err.message}`);
-        }
-      }
+      // 0.7.0: use markdown-aware chunker + deliverReplies primitive.
+      // The old chunkText was newline/byte-only; chunkMarkdownText also
+      // respects code-fence boundaries (closes + reopens across chunks).
+      const chunks = chunkMarkdownText(parsed.text, TG_MAX_LEN);
+      await deliverReplies({
+        bot,
+        send: (b, method, params, m) => tg(b, method, params, m),
+        chatId,
+        threadId,
+        chunks,
+        replyToMessageId: msg.message_id,
+        meta: outMeta,
+        logger: { error: (m) => console.error(`[${label}] ${m}`) },
+      });
     }
 
     console.log(`[${label}] ${elapsed}s | ${result.text.length} chars | ${chatConfig.model}/${chatConfig.effort} | $${result.cost?.toFixed(4) || '?'}`);
@@ -2480,6 +2574,38 @@ async function main() {
       const head = entry.pendingQueue?.[0];
       const r = head?.context?.reactor;
       if (r) r.setState(classifyToolName(toolName));
+      // 0.7.0 (Phase J): opt-in subagent announce. When Claude uses
+      // the Task tool to spawn a subagent, post a brief informational
+      // message to the chat so the user knows a heavier turn is in
+      // progress. Off by default (per-bot or per-chat
+      // `announceSubagents: true` opts in). Per-chat debounce 30s
+      // prevents announce-storms in tool-heavy turns.
+      const chatCfg = config.chats[entry.chatId] || {};
+      const optIn = chatCfg.announceSubagents != null
+        ? chatCfg.announceSubagents
+        : config.bot?.announceSubagents;
+      if (toolName === 'Task' && optIn === true) {
+        if (shouldAnnounce(entry.chatId)) {
+          announce({
+            send: (b, method, params, m) => tg(b, method, params, m),
+            bot, chatId: entry.chatId,
+            threadId: head?.context?.threadId ?? null,
+            text: '🤖 Spawning subagent…',
+            meta: { botName: BOT_NAME, source: 'subagent-announce' },
+            logger: { error: (m) => console.error(`[${entry.label}] ${m}`) },
+          });
+        }
+      }
+    },
+    // 0.7.0 (Phase F): each new top-level assistant message gets its
+    // own bubble. When Claude emits text, then tool_use, then more
+    // text in a NEW assistant message (typical of tool-heavy turns),
+    // the previous bubble's content stays visible as a "thinking out
+    // loud" intermediate; the new message starts fresh below.
+    onAssistantMessageStart: (sessionKey, entry) => {
+      const head = entry.pendingQueue?.[0];
+      const s = head?.context?.streamer;
+      if (s) s.forceNewMessage();
     },
     // Fires after a graceful /model or /effort drain has actually
     // swapped to the new settings. Post a confirmation back to the