switchroom 0.13.56 → 0.13.58

package/dist/cli/switchroom.js

@@ -48930,8 +48930,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.56";
-var COMMIT_SHA = "821a114e";
+var VERSION = "0.13.58";
+var COMMIT_SHA = "20818078";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.56",
+  "version": "0.13.58",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -31559,6 +31559,109 @@ function isTelegramSurfaceTool(toolName) {
   return suffix === "reply" || suffix === "stream_reply" || suffix === "edit_message" || suffix === "react";
 }
 
+// draft-transport.ts
+var DRAFT_STREAM_STATE_KEY = Symbol.for("switchroom.draftStreamState");
+function getDraftStreamState() {
+  const g = globalThis;
+  let state = g[DRAFT_STREAM_STATE_KEY];
+  if (!state) {
+    state = { nextDraftId: 0 };
+    g[DRAFT_STREAM_STATE_KEY] = state;
+  }
+  return state;
+}
+function allocateDraftId() {
+  const state = getDraftStreamState();
+  state.nextDraftId = state.nextDraftId >= 2147483647 ? 1 : state.nextDraftId + 1;
+  return state.nextDraftId;
+}
+
+// tool-activity-summary.ts
+var READ_VERBS = new Set(["read"]);
+var WRITE_VERBS = new Set(["wrote", "created", "edited"]);
+function makeEmptyActivityState() {
+  return { counts: {}, order: [], firstToolName: null };
+}
+function verbForTool(toolName) {
+  if (!toolName)
+    return null;
+  const mcpMatch = /^mcp__([^_]+)__(.+)$/.exec(toolName);
+  if (mcpMatch && mcpMatch[1] === "switchroom-telegram")
+    return null;
+  const suffix = (mcpMatch ? mcpMatch[2] : toolName).toLowerCase();
+  switch (suffix) {
+    case "read":
+      return "read";
+    case "write":
+      return "created";
+    case "edit":
+    case "multiedit":
+    case "notebookedit":
+      return "edited";
+    case "bash":
+    case "bashoutput":
+    case "killshell":
+      return "ran";
+    case "websearch":
+    case "grep":
+    case "glob":
+      return "searched";
+    case "webfetch":
+      return "fetched";
+    case "task":
+    case "agent":
+      return "dispatched";
+    case "todowrite":
+    case "todoread":
+      return "noted";
+    default:
+      return "used";
+  }
+}
+function register(state, toolName) {
+  const verb = verbForTool(toolName);
+  if (!verb)
+    return false;
+  if (state.firstToolName == null)
+    state.firstToolName = toolName;
+  const prior = state.counts[verb] ?? 0;
+  if (prior === 0)
+    state.order.push(verb);
+  state.counts[verb] = prior + 1;
+  return true;
+}
+var VERB_PHRASE = {
+  read: { singular: "read a file", plural: "read $N files" },
+  edited: { singular: "edited a file", plural: "edited $N files" },
+  created: { singular: "created a file", plural: "created $N files" },
+  ran: { singular: "ran a command", plural: "ran $N commands" },
+  searched: { singular: "ran a search", plural: "ran $N searches" },
+  fetched: { singular: "fetched a URL", plural: "fetched $N URLs" },
+  dispatched: { singular: "dispatched a sub-agent", plural: "dispatched $N sub-agents" },
+  noted: { singular: "updated the todo list", plural: "updated the todo list ($N edits)" },
+  used: { singular: "used a tool", plural: "used $N tools" }
+};
+function formatSummary(state) {
+  const phrases = [];
+  for (const verb of state.order) {
+    const n = state.counts[verb] ?? 0;
+    if (n <= 0)
+      continue;
+    const p = VERB_PHRASE[verb];
+    phrases.push(n === 1 ? p.singular : p.plural.replace("$N", String(n)));
+  }
+  if (phrases.length === 0)
+    return null;
+  const sentence = phrases.join(", ");
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}
+function registerAndRender(state, toolName) {
+  const changed = register(state, toolName);
+  if (!changed)
+    return null;
+  return formatSummary(state);
+}
+
 // tool-labels.ts
 var MAX_LABEL_CHARS = 60;
 var MAX_BASH_CHARS = 40;
@@ -31863,18 +31966,18 @@ function isDraft429(err) {
   const text = typeof err === "string" ? err : err instanceof Error ? err.message : typeof err === "object" && err != null && ("description" in err) ? typeof err.description === "string" ? err.description : "" : "";
   return /sendMessageDraft/i.test(text);
 }
-var DRAFT_STREAM_STATE_KEY = Symbol.for("switchroom.draftStreamState");
-function getDraftStreamState() {
+var DRAFT_STREAM_STATE_KEY2 = Symbol.for("switchroom.draftStreamState");
+function getDraftStreamState2() {
   const g = globalThis;
-  let state = g[DRAFT_STREAM_STATE_KEY];
+  let state = g[DRAFT_STREAM_STATE_KEY2];
   if (!state) {
     state = { nextDraftId: 0 };
-    g[DRAFT_STREAM_STATE_KEY] = state;
+    g[DRAFT_STREAM_STATE_KEY2] = state;
   }
   return state;
 }
-function allocateDraftId() {
-  const state = getDraftStreamState();
+function allocateDraftId2() {
+  const state = getDraftStreamState2();
   state.nextDraftId = state.nextDraftId >= 2147483647 ? 1 : state.nextDraftId + 1;
   return state.nextDraftId;
 }
@@ -31904,7 +32007,7 @@ function createDraftStream(send, edit, config = {}) {
     warn?.('draft-stream: previewTransport="auto" with sendMessageDraft but isPrivateChat undefined \u2014 defaulting to message transport');
   }
   let usesDraftTransport = prefersDraft && draftApi != null;
-  let draftId = usesDraftTransport ? allocateDraftId() : undefined;
+  let draftId = usesDraftTransport ? allocateDraftId2() : undefined;
   if (prefersDraft && !usesDraftTransport) {
     warn?.("draft-stream: sendMessageDraft unavailable; falling back to sendMessage/editMessageText");
   }
@@ -32012,7 +32115,7 @@ function createDraftStream(send, edit, config = {}) {
           const newMsgId = await send(chunk);
           messageId = newMsgId;
           persistedTextLen = textToSend.length;
-          draftId = allocateDraftId();
+          draftId = allocateDraftId2();
           currentChunkStartedAt = null;
           persistChainFires++;
           sendFires++;
@@ -38328,7 +38431,7 @@ function isSilentFlushMarker(text) {
 var MIN_INITIAL_CHARS = 50;
 var DEFAULT_THROTTLE_MS = 1000;
 var TELEGRAM_MAX_CHARS2 = 4096;
-var allocateDraftId2 = allocateDraftId;
+var allocateDraftId3 = allocateDraftId2;
 function createAnswerStream(config) {
   const {
     chatId,
@@ -38351,7 +38454,7 @@ function createAnswerStream(config) {
   const effectiveThrottle = Math.max(250, throttleMs);
   const preferDraft = isPrivateChat && draftApi != null;
   let usesDraftTransport = preferDraft;
-  let draftId = preferDraft ? allocateDraftId2() : undefined;
+  let draftId = preferDraft ? allocateDraftId3() : undefined;
   let streamMsgId;
   let pendingText = null;
   let lastSentText = "";
@@ -38600,7 +38703,7 @@ function createAnswerStream(config) {
         if (staleDraftId != null) {
           clearDraftBestEffort(staleDraftId);
         }
-        draftId = allocateDraftId2();
+        draftId = allocateDraftId3();
       }
       log?.(`answer-stream: forceNewMessage (gen=${generation})`);
     },
@@ -49624,10 +49727,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.56";
-var COMMIT_SHA = "821a114e";
-var COMMIT_DATE = "2026-05-27T20:20:37Z";
-var LATEST_PR = 1923;
+var VERSION = "0.13.58";
+var COMMIT_SHA = "20818078";
+var COMMIT_DATE = "2026-05-27T22:11:23Z";
+var LATEST_PR = 1928;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -53601,6 +53704,74 @@ function closeProgressLane(chatId, threadId) {
     }
   }
 }
+async function drainActivitySummary(turn) {
+  try {
+    while (turn.activityPendingRender !== turn.activityLastSentRender) {
+      const target = turn.activityPendingRender;
+      if (target == null)
+        break;
+      const html = `<i>${target}</i>`;
+      const chat = turn.sessionChatId;
+      const thread = turn.sessionThreadId;
+      const useDraft = turn.isDm && thread == null && sendMessageDraftFn != null;
+      try {
+        if (useDraft) {
+          if (turn.activityDraftId == null) {
+            turn.activityDraftId = allocateDraftId();
+          }
+          const draftId = turn.activityDraftId;
+          await sendMessageDraftFn(chat, draftId, html, undefined);
+        } else if (turn.activityMessageId == null) {
+          const sent = await robustApiCall(() => bot.api.sendMessage(chat, html, {
+            ...thread != null ? { message_thread_id: thread } : {},
+            parse_mode: "HTML",
+            disable_notification: true
+          }), { chat_id: chat, ...thread != null ? { threadId: thread } : {}, verb: "activity-summary.send" });
+          turn.activityMessageId = sent.message_id;
+        } else {
+          const id = turn.activityMessageId;
+          await robustApiCall(() => bot.api.editMessageText(chat, id, html, { parse_mode: "HTML" }), { chat_id: chat, ...thread != null ? { threadId: thread } : {}, verb: "activity-summary.edit" });
+        }
+        turn.activityLastSentRender = target;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!msg.includes("message is not modified")) {
+          process.stderr.write(`telegram gateway: activity-summary drain failed: ${msg}
+`);
+        }
+        turn.activityLastSentRender = target;
+      }
+    }
+  } finally {
+    turn.activityInFlight = null;
+  }
+}
+function clearActivitySummary(turn) {
+  const chat = turn.sessionChatId;
+  const thread = turn.sessionThreadId;
+  const inFlight = turn.activityInFlight ?? Promise.resolve();
+  inFlight.then(async () => {
+    if (turn.activityDraftId != null && sendMessageDraftFn != null) {
+      const draftId = turn.activityDraftId;
+      turn.activityDraftId = null;
+      try {
+        await sendMessageDraftFn(chat, draftId, "", undefined);
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary draft-clear failed: ${err}
+`);
+      }
+    } else if (turn.activityMessageId != null) {
+      const id = turn.activityMessageId;
+      turn.activityMessageId = null;
+      try {
+        await robustApiCall(() => bot.api.deleteMessage(chat, id), { chat_id: chat, ...thread != null ? { threadId: thread } : {}, verb: "activity-summary.delete" });
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary delete failed: ${err}
+`);
+      }
+    }
+  });
+}
 function handleSessionEvent(ev) {
   switch (ev.kind) {
     case "enqueue": {
@@ -53634,6 +53805,12 @@ function handleSessionEvent(ev) {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
+          toolActivity: makeEmptyActivityState(),
+          activityMessageId: null,
+          activityDraftId: null,
+          activityInFlight: null,
+          activityPendingRender: null,
+          activityLastSentRender: null,
           answerStream: null,
           isDm: isDmChatId(ev.chatId)
         };
@@ -53693,11 +53870,30 @@ function handleSessionEvent(ev) {
       const ctrl = activeStatusReactions.get(statusKey(turn.sessionChatId, turn.sessionThreadId));
       const name = ev.toolName;
       if (isTelegramReplyTool(name)) {
+        const wasFirstReply = !turn.replyCalled;
         turn.replyCalled = true;
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId);
           turn.orphanedReplyTimeoutId = null;
         }
+        if (wasFirstReply) {
+          clearActivitySummary(turn);
+        }
+      }
+      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = registerAndRender(turn.toolActivity, name);
+        if (rendered != null) {
+          try {
+            markAckSent();
+          } catch (err) {
+            process.stderr.write(`telegram gateway: activity-summary markAckSent failed: ${err}
+`);
+          }
+          turn.activityPendingRender = rendered;
+          if (turn.activityInFlight == null) {
+            turn.activityInFlight = drainActivitySummary(turn);
+          }
+        }
       }
       if (!ctrl)
         return;

package/telegram-plugin/gateway/gateway.ts

@@ -53,6 +53,12 @@ import { OutboundDedupCache } from '../recent-outbound-dedup.js'
 import { createInboundCoalescer, inboundCoalesceKey } from './inbound-coalesce.js'
 import { StatusReactionController } from '../status-reactions.js'
 import { isTelegramReplyTool, isTelegramSurfaceTool } from '../tool-names.js'
+import { allocateDraftId } from '../draft-transport.js'
+import {
+  makeEmptyActivityState,
+  registerAndRender,
+  type ActivityState,
+} from '../tool-activity-summary.js'
 import { toolLabel } from '../tool-labels.js'
 import { createTypingWrapper } from '../typing-wrap.js'
 import { type DraftStreamHandle } from '../draft-stream.js'
@@ -1291,6 +1297,39 @@ type CurrentTurn = {
   // Phase 1 of #332: count of tool_use events in the current turn, for
   // the tool_call_count column in the turns registry.
   toolCallCount: number
+  // Tool-activity summary — mirrors Claude Code's native chat-UI
+  // rendering ("Ran 5 commands, read a file"). Counters are
+  // incremented in `case 'tool_use'`; `activityMessageId` holds the
+  // Telegram message id we send/edit so a single message accumulates
+  // the summary in place. Stops updating once `replyCalled` flips —
+  // the model's own reply lands below the summary as the actual
+  // content.
+  //
+  // Parallel-tool-use coalescing (PR #1926 review): modern Claude
+  // emits multiple tool_uses in a tight synchronous loop (e.g. 3
+  // parallel Reads). Without coalescing, each would see
+  // `activityMessageId == null` and fire its own sendMessage,
+  // producing N messages instead of one editable summary. Pattern
+  // mirrors `telegram-plugin/answer-stream.ts`:
+  //   - `activityInFlight` — promise that resolves when the current
+  //     send/edit settles. While set, NEW tool_uses just update
+  //     `activityState` and `activityPendingRender` and return.
+  //   - When the in-flight resolves, it picks the latest
+  //     `activityPendingRender`, fires the next send/edit, and
+  //     repeats until the pending matches the last-sent.
+  // Result: at most one Telegram call in flight at a time; the
+  // final state always lands.
+  toolActivity: ActivityState
+  activityMessageId: number | null
+  // Draft-transport id when the activity summary is streamed via
+  // sendMessageDraft (DM-only, no thread). Each call to
+  // sendMessageDraft(chat, draftId, text) REPLACES the draft text —
+  // simpler than send+edit. Cleared by `clearActivitySummary` (which
+  // sends an empty draft) when the model's reply takes over.
+  activityDraftId: number | null
+  activityInFlight: Promise<void> | null
+  activityPendingRender: string | null
+  activityLastSentRender: string | null
   // Issue #195 — answer-lane streaming. Lazily created on the first text
   // event of a turn (once enough text has accumulated, the stream itself
   // gates on minInitialChars). Materialized and cleared at turn_end.
@@ -6767,6 +6806,120 @@ function closeProgressLane(chatId: string, threadId: number | undefined): void {
   }
 }
 
+/**
+ * Drain the tool-activity summary's pending render queue. Single-flight
+ * by construction (caller assigns the returned promise to
+ * `turn.activityInFlight`; while set, new tool_uses only update
+ * `turn.activityPendingRender` and return).
+ *
+ * Transport priority (mirrors the existing answer-stream pattern):
+ *
+ *   1. DM with no thread AND sendMessageDraft API available →
+ *      DRAFT TRANSPORT. Each call REPLACES the draft text (no
+ *      edit-in-place needed); the user sees a live preview in their
+ *      Telegram compose area as the agent works. When the model's
+ *      reply tool lands, `clearActivitySummary` sends an empty draft
+ *      to wipe it — only the real reply persists.
+ *
+ *   2. Anything else (forum topic, draft API absent) → fall through
+ *      to sendMessage + editMessageText. The activity message is a
+ *      real chat message; `clearActivitySummary` deletes it when the
+ *      reply tool takes over.
+ *
+ * The drain holds a reference to `turn`, so a turn-swap mid-drain
+ * doesn't corrupt the next turn's atom — late writes land on the
+ * captured `turn` (already-completed turn, harmless).
+ */
+async function drainActivitySummary(turn: CurrentTurn): Promise<void> {
+  try {
+    while (turn.activityPendingRender !== turn.activityLastSentRender) {
+      const target = turn.activityPendingRender
+      if (target == null) break
+      const html = `<i>${target}</i>`
+      const chat = turn.sessionChatId
+      const thread = turn.sessionThreadId
+      // sendMessageDraft doesn't support forum threads.
+      const useDraft = turn.isDm && thread == null && sendMessageDraftFn != null
+      try {
+        if (useDraft) {
+          if (turn.activityDraftId == null) {
+            turn.activityDraftId = allocateDraftId()
+          }
+          const draftId = turn.activityDraftId
+          await sendMessageDraftFn!(chat, draftId, html, undefined)
+        } else if (turn.activityMessageId == null) {
+          const sent = await robustApiCall(
+            () => bot.api.sendMessage(chat, html, {
+              ...(thread != null ? { message_thread_id: thread } : {}),
+              parse_mode: 'HTML',
+              disable_notification: true,
+            }),
+            { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.send' },
+          )
+          turn.activityMessageId = sent.message_id
+        } else {
+          const id = turn.activityMessageId
+          await robustApiCall(
+            () => bot.api.editMessageText(chat, id, html, { parse_mode: 'HTML' }),
+            { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.edit' },
+          )
+        }
+        turn.activityLastSentRender = target
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        if (!msg.includes('message is not modified')) {
+          process.stderr.write(`telegram gateway: activity-summary drain failed: ${msg}\n`)
+        }
+        // Mark as sent so we don't infinite-loop on a stuck render.
+        turn.activityLastSentRender = target
+      }
+    }
+  } finally {
+    turn.activityInFlight = null
+  }
+}
+
+/**
+ * Clear the activity summary when the model's reply tool takes over
+ * as the authoritative surface. Awaits any in-flight render so we
+ * don't race a stale write against the clear, then either sends an
+ * empty draft (clears the compose-area preview) or deletes the
+ * persisted message. Idempotent + best-effort — failure stderr-logs
+ * but does not block.
+ *
+ * Called from `case 'tool_use'` the moment we see a Telegram reply
+ * tool fire, so the user sees the real reply land in the same beat
+ * the summary disappears.
+ */
+function clearActivitySummary(turn: CurrentTurn): void {
+  const chat = turn.sessionChatId
+  const thread = turn.sessionThreadId
+  const inFlight = turn.activityInFlight ?? Promise.resolve()
+  void inFlight.then(async () => {
+    if (turn.activityDraftId != null && sendMessageDraftFn != null) {
+      const draftId = turn.activityDraftId
+      turn.activityDraftId = null
+      try {
+        // Empty text → Telegram clears the draft.
+        await sendMessageDraftFn(chat, draftId, '', undefined)
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary draft-clear failed: ${err}\n`)
+      }
+    } else if (turn.activityMessageId != null) {
+      const id = turn.activityMessageId
+      turn.activityMessageId = null
+      try {
+        await robustApiCall(
+          () => bot.api.deleteMessage(chat, id),
+          { chat_id: chat, ...(thread != null ? { threadId: thread } : {}), verb: 'activity-summary.delete' },
+        )
+      } catch (err) {
+        process.stderr.write(`telegram gateway: activity-summary delete failed: ${err}\n`)
+      }
+    }
+  })
+}
+
 function handleSessionEvent(ev: SessionEvent): void {
   switch (ev.kind) {
     case 'enqueue': {
@@ -6832,6 +6985,12 @@ function handleSessionEvent(ev: SessionEvent): void {
           lastAssistantMsgId: null,
           lastAssistantDone: false,
           toolCallCount: 0,
+          toolActivity: makeEmptyActivityState(),
+          activityMessageId: null,
+          activityDraftId: null,
+          activityInFlight: null,
+          activityPendingRender: null,
+          activityLastSentRender: null,
           answerStream: null,
           isDm: isDmChatId(ev.chatId),
         }
@@ -6943,11 +7102,57 @@ function handleSessionEvent(ev: SessionEvent): void {
       // Phase tracking removed in #553 PR 5 — phases only fed the
       // placeholder-heartbeat label, which has been retired.
       if (isTelegramReplyTool(name)) {
+        const wasFirstReply = !turn.replyCalled
         turn.replyCalled = true
         if (turn.orphanedReplyTimeoutId != null) {
           clearTimeout(turn.orphanedReplyTimeoutId)
           turn.orphanedReplyTimeoutId = null
         }
+        // The model's real reply takes over as the authoritative
+        // surface. Clear the activity summary — for drafts, send an
+        // empty draft to wipe the compose-area preview; for persisted
+        // messages, delete. The user sees the real reply land in the
+        // same beat the summary disappears.
+        if (wasFirstReply) {
+          clearActivitySummary(turn)
+        }
+      }
+      // Tool-intent surface — companion to the PreToolUse ack-first gate
+      // (#1921). On the FIRST non-reply tool_use of a turn AND only when
+      // Tool-activity summary — same shape Claude Code natively renders
+      // in its CLI/chat UI ("Ran 5 commands, read a file"). The gateway
+      // accumulates non-reply tool_use events into `turn.toolActivity`
+      // and sends ONE Telegram message that edits in place as more tools
+      // land. Stops editing once the model calls `reply` — the summary
+      // line stays as the final state. No model-side prompting; no per-
+      // tool labels. Just surface what's already in the stream.
+      //
+      // Single-flight coalescing (PR #1926 review): modern Claude emits
+      // multiple tool_uses in a synchronous burst (parallel Reads,
+      // Bashes, etc.). All would otherwise race past the message-id
+      // capture and produce N messages. Pattern mirrors answer-stream:
+      // update `activityPendingRender` synchronously here; a single
+      // worker promise drains the pending state, sending or editing
+      // exactly once at a time and re-running until pending matches
+      // the last-sent. Captures `turn` so a late drain after turn-swap
+      // can't corrupt the next turn's atom.
+      if (!turn.replyCalled && !isTelegramSurfaceTool(name)) {
+        const rendered = registerAndRender(turn.toolActivity, name)
+        if (rendered != null) {
+          // Mark the ack-flag synchronously so a PreToolUse hook firing
+          // concurrently for THIS tool call (#1921) sees the flag set
+          // and allows the tool through. The drain runs async; failure
+          // is logged but does not block the model.
+          try {
+            markAckSent()
+          } catch (err) {
+            process.stderr.write(`telegram gateway: activity-summary markAckSent failed: ${err}\n`)
+          }
+          turn.activityPendingRender = rendered
+          if (turn.activityInFlight == null) {
+            turn.activityInFlight = drainActivitySummary(turn)
+          }
+        }
       }
       if (!ctrl) return
       if (isTelegramSurfaceTool(name)) return

package/telegram-plugin/tests/tool-activity-summary.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vitest";
+import {
+  makeEmptyActivityState,
+  register,
+  formatSummary,
+  registerAndRender,
+  verbForTool,
+} from "../tool-activity-summary.js";
+
+describe("verbForTool — tool name → past-tense verb", () => {
+  it("maps standard CLI tools to readable verbs", () => {
+    expect(verbForTool("Read")).toBe("read");
+    expect(verbForTool("Write")).toBe("created");
+    expect(verbForTool("Edit")).toBe("edited");
+    expect(verbForTool("MultiEdit")).toBe("edited");
+    expect(verbForTool("NotebookEdit")).toBe("edited");
+    expect(verbForTool("Bash")).toBe("ran");
+    expect(verbForTool("BashOutput")).toBe("ran");
+    expect(verbForTool("WebSearch")).toBe("searched");
+    expect(verbForTool("Grep")).toBe("searched");
+    expect(verbForTool("Glob")).toBe("searched");
+    expect(verbForTool("WebFetch")).toBe("fetched");
+    expect(verbForTool("Task")).toBe("dispatched");
+    expect(verbForTool("Agent")).toBe("dispatched");
+    expect(verbForTool("TodoWrite")).toBe("noted");
+  });
+
+  it("skips user-facing switchroom-telegram tools (those ARE the surface)", () => {
+    expect(verbForTool("mcp__switchroom-telegram__reply")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__stream_reply")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__edit_message")).toBeNull();
+    expect(verbForTool("mcp__switchroom-telegram__react")).toBeNull();
+  });
+
+  it("returns 'used' for unknown / non-switchroom MCP tools", () => {
+    expect(verbForTool("mcp__google-workspace__list_files")).toBe("used");
+    expect(verbForTool("mcp__notion__query_database")).toBe("used");
+    expect(verbForTool("SomeFutureUnknownTool")).toBe("used");
+  });
+
+  it("returns null for empty toolName (defensive)", () => {
+    expect(verbForTool("")).toBeNull();
+  });
+});
+
+describe("register + formatSummary — Claude Code-style summary", () => {
+  it("formats a single Read as 'Read a file'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    expect(formatSummary(s)).toBe("Read a file");
+  });
+
+  it("formats multiple Reads as 'Read N files'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Read");
+    expect(formatSummary(s)).toBe("Read 3 files");
+  });
+
+  it("formats single Bash as 'Ran a command'", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Bash");
+    expect(formatSummary(s)).toBe("Ran a command");
+  });
+
+  it("formats multiple Bash as 'Ran N commands'", () => {
+    const s = makeEmptyActivityState();
+    for (let i = 0; i < 5; i++) register(s, "Bash");
+    expect(formatSummary(s)).toBe("Ran 5 commands");
+  });
+
+  it("joins multiple verb-classes with commas (first-occurrence order)", () => {
+    const s = makeEmptyActivityState();
+    // Tools fire in this order: Read → Bash → Edit
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Edit");
+    // The summary renders chronologically: read, ran, edited.
+    expect(formatSummary(s)).toBe("Read a file, ran a command, edited a file");
+  });
+
+  it("matches the Claude Code screenshot examples", () => {
+    // "Ran 5 commands, read a file"
+    const s1 = makeEmptyActivityState();
+    for (let i = 0; i < 5; i++) register(s1, "Bash");
+    register(s1, "Read");
+    expect(formatSummary(s1)).toBe("Ran 5 commands, read a file");
+
+    // "Edited a file, read a file, ran a command"
+    const s2 = makeEmptyActivityState();
+    register(s2, "Edit");
+    register(s2, "Read");
+    register(s2, "Bash");
+    expect(formatSummary(s2)).toBe("Edited a file, read a file, ran a command");
+
+    // "Created a file, ran a command"
+    const s3 = makeEmptyActivityState();
+    register(s3, "Write");
+    register(s3, "Bash");
+    expect(formatSummary(s3)).toBe("Created a file, ran a command");
+  });
+
+  it("returns null when state is empty", () => {
+    expect(formatSummary(makeEmptyActivityState())).toBeNull();
+  });
+
+  it("ignores user-facing tools (reply/stream_reply etc.)", () => {
+    const s = makeEmptyActivityState();
+    register(s, "mcp__switchroom-telegram__reply");
+    register(s, "mcp__switchroom-telegram__stream_reply");
+    expect(formatSummary(s)).toBeNull(); // nothing tracked
+  });
+
+  it("includes generic 'used' for unknown MCP tools", () => {
+    const s = makeEmptyActivityState();
+    register(s, "mcp__google-workspace__list_files");
+    expect(formatSummary(s)).toBe("Used a tool");
+    register(s, "mcp__google-workspace__create_file");
+    expect(formatSummary(s)).toBe("Used 2 tools");
+  });
+
+  it("tracks firstToolName for forensic / telemetry use", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Bash");
+    expect(s.firstToolName).toBe("Read");
+  });
+});
+
+describe("parallel-tool-use coalescing — render only reflects accumulated state", () => {
+  it("synchronous burst of N tool_uses produces the right summary at each step", () => {
+    // Modern Claude emits parallel tool_uses in a tight sync loop. The
+    // gateway calls register() N times before any async drain runs.
+    // After N registers, the rendered string should reflect ALL of them
+    // — so when the drain fires once with the latest pendingRender, the
+    // sent text is correct and complete.
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Bash");
+    expect(formatSummary(s)).toBe("Read 3 files, ran 2 commands");
+  });
+
+  it("ordering is preserved across a chronological burst", () => {
+    const s = makeEmptyActivityState();
+    // Simulates: Bash, then Read, then Bash, then Read, then Edit
+    register(s, "Bash");
+    register(s, "Read");
+    register(s, "Bash");
+    register(s, "Read");
+    register(s, "Edit");
+    // Bash was first, then Read, then Edit. Counts: bash 2, read 2, edit 1.
+    expect(formatSummary(s)).toBe(
+      "Ran 2 commands, read 2 files, edited a file",
+    );
+  });
+
+  it("registerAndRender returns null on user-facing tools (no race contribution)", () => {
+    const s = makeEmptyActivityState();
+    register(s, "Read");
+    // A reply tool fires concurrently — should not enter the activity state.
+    expect(
+      registerAndRender(s, "mcp__switchroom-telegram__reply"),
+    ).toBeNull();
+    // State still reflects only the Read.
+    expect(formatSummary(s)).toBe("Read a file");
+  });
+});
+
+describe("registerAndRender — ergonomic full-pipeline call", () => {
+  it("returns the updated rendered text on a real tool (chronological)", () => {
+    const s = makeEmptyActivityState();
+    expect(registerAndRender(s, "Read")).toBe("Read a file");
+    // Bash fires AFTER Read — chronological order shows read first.
+    expect(registerAndRender(s, "Bash")).toBe(
+      "Read a file, ran a command",
+    );
+  });
+
+  it("returns null on a surface tool (no-op)", () => {
+    const s = makeEmptyActivityState();
+    expect(
+      registerAndRender(s, "mcp__switchroom-telegram__reply"),
+    ).toBeNull();
+    // State unchanged
+    expect(s.firstToolName).toBeNull();
+  });
+});

package/telegram-plugin/tool-activity-summary.ts

@@ -0,0 +1,164 @@
+/**
+ * Tool-activity summary — Claude Code-style natural-language progress
+ * line that batches tool_use events for a turn into a single Telegram
+ * message that updates in place.
+ *
+ * Replaces the per-tool intent surface (#1924). The screenshot from
+ * Claude Code's own UI shows lines like:
+ *
+ *   "Ran 5 commands, read a file"
+ *   "Edited a file, read a file, ran a command"
+ *
+ * Past tense, comma-joined, singular/plural-aware. One message per
+ * "phase" (turn start → first reply), progressively edited as tools
+ * accumulate. NOT raw tool calls — descriptions of what the agent has
+ * been doing.
+ *
+ * Why this beats per-tool labels:
+ *   - One Telegram message per phase (low signal-to-noise vs N
+ *     messages on a heavy turn)
+ *   - The user sees ACCUMULATED work in a glanceable form, not a flood
+ *   - Plays nicely with the existing answer-lane stream that handles
+ *     the actual reply text
+ *
+ * Tracking shape: per-turn counters keyed by `verb` (the action class
+ * derived from tool name). One counter per verb so the summary line
+ * collapses neatly regardless of which specific Read/Bash/WebSearch
+ * the model chose. `register()` increments the counter; `formatSummary()`
+ * renders the current state.
+ */
+
+const READ_VERBS = new Set(["read"]);
+const WRITE_VERBS = new Set(["wrote", "created", "edited"]);
+
+export type ActivityVerb =
+  | "read"
+  | "edited"
+  | "created"
+  | "ran"
+  | "searched"
+  | "fetched"
+  | "dispatched"
+  | "noted"
+  | "used"; // generic fallback
+
+/** Object form so `register()` can mutate; pure functions inside the
+ *  module work against this shape (easier to unit-test than a Map). */
+export interface ActivityState {
+  counts: Partial<Record<ActivityVerb, number>>;
+  /** Order verbs were first observed this turn. The summary renders in
+   *  this order so the line reads as a chronological natural-language
+   *  account: "edited a file, read a file, ran a command" matches the
+   *  agent's actual sequence of actions. Stable — once a verb is added
+   *  to this list, it never moves. */
+  order: ActivityVerb[];
+  /** First non-trivial tool name observed this turn (for telemetry / future
+   *  "what kicked this off" forensic). Not used in the rendered summary. */
+  firstToolName: string | null;
+}
+
+export function makeEmptyActivityState(): ActivityState {
+  return { counts: {}, order: [], firstToolName: null };
+}
+
+/** Map a tool name → verb. Mirrors the existing `tool-intent-surface.ts`
+ *  verb table but in past tense. Tools that don't map (or surface tools
+ *  like reply/stream_reply) return null — the caller skips them. */
+export function verbForTool(toolName: string): ActivityVerb | null {
+  if (!toolName) return null;
+  const mcpMatch = /^mcp__([^_]+)__(.+)$/.exec(toolName);
+  // Skip user-facing Telegram-plugin tools entirely — those ARE the
+  // surface, never to be summarised.
+  if (mcpMatch && mcpMatch[1] === "switchroom-telegram") return null;
+  const suffix = (mcpMatch ? mcpMatch[2] : toolName).toLowerCase();
+  switch (suffix) {
+    case "read":
+      return "read";
+    case "write":
+      return "created";
+    case "edit":
+    case "multiedit":
+    case "notebookedit":
+      return "edited";
+    case "bash":
+    case "bashoutput":
+    case "killshell":
+      return "ran";
+    case "websearch":
+    case "grep":
+    case "glob":
+      return "searched";
+    case "webfetch":
+      return "fetched";
+    case "task":
+    case "agent":
+      return "dispatched";
+    case "todowrite":
+    case "todoread":
+      return "noted";
+    default:
+      return "used";
+  }
+}
+
+/** Mutates `state` to record one tool_use of `toolName`. Returns true
+ *  iff the activity state changed (so the caller knows to refresh the
+ *  rendered summary). */
+export function register(state: ActivityState, toolName: string): boolean {
+  const verb = verbForTool(toolName);
+  if (!verb) return false;
+  if (state.firstToolName == null) state.firstToolName = toolName;
+  const prior = state.counts[verb] ?? 0;
+  if (prior === 0) state.order.push(verb);
+  state.counts[verb] = prior + 1;
+  return true;
+}
+
+interface VerbPhrase {
+  singular: string;
+  plural: string;
+}
+
+const VERB_PHRASE: Record<ActivityVerb, VerbPhrase> = {
+  read: { singular: "read a file", plural: "read $N files" },
+  edited: { singular: "edited a file", plural: "edited $N files" },
+  created: { singular: "created a file", plural: "created $N files" },
+  ran: { singular: "ran a command", plural: "ran $N commands" },
+  searched: { singular: "ran a search", plural: "ran $N searches" },
+  fetched: { singular: "fetched a URL", plural: "fetched $N URLs" },
+  dispatched: { singular: "dispatched a sub-agent", plural: "dispatched $N sub-agents" },
+  noted: { singular: "updated the todo list", plural: "updated the todo list ($N edits)" },
+  used: { singular: "used a tool", plural: "used $N tools" },
+};
+
+/** Render the activity state as a single natural-language line.
+ *  Verbs are rendered in `state.order` — first-occurrence order — so
+ *  the line reads chronologically ("edited a file, read a file, ran
+ *  a command" mirrors the agent's actual action sequence). Returns
+ *  null when the state is empty (nothing to show yet). */
+export function formatSummary(state: ActivityState): string | null {
+  const phrases: string[] = [];
+  for (const verb of state.order) {
+    const n = state.counts[verb] ?? 0;
+    if (n <= 0) continue;
+    const p = VERB_PHRASE[verb];
+    phrases.push(n === 1 ? p.singular : p.plural.replace("$N", String(n)));
+  }
+  if (phrases.length === 0) return null;
+  // Capitalize first letter so the sentence reads as a statement.
+  const sentence = phrases.join(", ");
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}
+
+/** Convenience: ergonomic full pipeline for callers that just want
+ *  "given the new tool name and prior state, give me the updated rendered
+ *  text or null if nothing changed". Returns null when the tool is a
+ *  surface tool / no-op (so the caller can skip the Telegram edit). */
+export function registerAndRender(
+  state: ActivityState,
+  toolName: string,
+): string | null {
+  const changed = register(state, toolName);
+  if (!changed) return null;
+  return formatSummary(state);
+}