switchroom 0.13.37 → 0.13.39

package/dist/cli/switchroom.js

@@ -47744,8 +47744,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.37";
-var COMMIT_SHA = "623c57e0";
+var VERSION = "0.13.39";
+var COMMIT_SHA = "8681f423";
 
 // src/cli/agent.ts
 init_source();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.37",
+  "version": "0.13.39",
   "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/answer-stream.ts

@@ -244,15 +244,22 @@ export function createAnswerStream(config: AnswerStreamConfig): AnswerStreamHand
    * must clear the draft. Best-effort: a failed clear is logged but
    * not re-thrown — the worst case is a transient stale draft that
    * Telegram's own 30 s draft expiry eventually mops up.
+   *
+   * #1792 — accepts an explicit `targetDraftId` so `forceNewMessage`
+   * can clear the OLD id before bumping the closure's `draftId`. The
+   * default reads the live closure, which is what stop() / retract()
+   * want — clear whatever's current at the time the call lands.
    */
-  async function clearDraftBestEffort(): Promise<void> {
-    if (!usesDraftTransport || draftApi == null || draftId == null) return
+  async function clearDraftBestEffort(
+    targetDraftId: number | undefined = draftId,
+  ): Promise<void> {
+    if (!usesDraftTransport || draftApi == null || targetDraftId == null) return
     try {
       const params: { message_thread_id?: number } = {}
       if (threadId != null) params.message_thread_id = threadId
       await draftApi(
         chatId,
-        draftId,
+        targetDraftId,
         '',
         Object.keys(params).length > 0 ? params : undefined,
       )
@@ -531,6 +538,18 @@ export function createAnswerStream(config: AnswerStreamConfig): AnswerStreamHand
       stopped = false
       materialized = false
       if (usesDraftTransport) {
+        // #1792: clear the OLD draftId BEFORE rotating. Otherwise the
+        // stale content stays in the user's compose box until the 30 s
+        // Telegram draft expiry — the typical caller (gateway.ts mid-
+        // turn rapid-steer path: `forceNewMessage(); stop();`) cleans
+        // up the prior turn's stream, so the prior draft's content is
+        // semantically retracted. Fire-and-forget — forceNewMessage is
+        // sync; the worst-case failure mode is the same 30 s expiry
+        // we'd have had without the call.
+        const staleDraftId = draftId
+        if (staleDraftId != null) {
+          void clearDraftBestEffort(staleDraftId)
+        }
         draftId = allocateDraftId()
       }
       log?.(`answer-stream: forceNewMessage (gen=${generation})`)
@@ -546,6 +565,10 @@ export function createAnswerStream(config: AnswerStreamConfig): AnswerStreamHand
       // #1704: clear the compose-box draft. stop() is sync — fire and
       // forget. A dropped clear falls back on Telegram's own 30 s
       // draft expiry; the worst case is a transient stale preview.
+      // (#1792: the stale-id-after-rotation hazard is owned by
+      // forceNewMessage itself now — it clears its own draftId before
+      // rotating. stop() just clears whatever's current; clearing an
+      // already-cleared or never-used id is a harmless no-op.)
       void clearDraftBestEffort()
     },
 
@@ -563,6 +586,8 @@ export function createAnswerStream(config: AnswerStreamConfig): AnswerStreamHand
       // draft sitting in the user's input area and blocks them from
       // typing until the 30 s draft expiry. Awaited so a follow-up
       // sendMessage on the same chat doesn't race a stale draft edit.
+      // (See #1792 note in stop() — forceNewMessage owns its own stale
+      // id cleanup; retract just clears whatever's current.)
       await clearDraftBestEffort()
       // Delete the preliminary message if one was sent and deleteMessage
       // is wired. Best-effort: failures are logged but not re-thrown.

package/telegram-plugin/bridge/bridge.ts

@@ -431,7 +431,7 @@ const TOOL_SCHEMAS = [
         chat_id: { type: 'string', description: 'Chat to render the approval card in (use the chat_id of the user message that triggered the workflow).' },
         key: { type: 'string', description: 'Vault key the agent wants access to (matches the key shown in the VAULT-BROKER-DENIED error, e.g. `fatsecret/credentials`).' },
         scope: { type: 'string', enum: ['read', 'write'], description: 'Access scope: "read" (default) for `vault:<key>` references; "write" if the agent needs to put new values.' },
-        reason: { type: 'string', description: 'Short human-readable rationale rendered on the card (e.g. "to look up today\'s food log entries"). Helps the operator decide.' },
+        reason: { type: 'string', description: 'REQUIRED in practice — short human-readable rationale rendered on the card (e.g. "to look up today\'s food log entries"). The approval card now renders "why: not provided" when this is omitted, which signals to the operator that the agent skipped its explanation — they will usually Deny. Always supply a one-line rationale.' },
         duration: { type: 'string', description: 'Requested grant TTL, like "30d" or "12h". Default 30d, capped at 90d. Beyond 90d the operator should use the host CLI explicitly.' },
         message_thread_id: { type: 'string', description: 'Forum topic thread ID. Auto-applied from the last inbound message if not specified.' },
       },

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

@@ -24797,7 +24797,7 @@ var TOOL_SCHEMAS = [
         chat_id: { type: "string", description: "Chat to render the approval card in (use the chat_id of the user message that triggered the workflow)." },
         key: { type: "string", description: "Vault key the agent wants access to (matches the key shown in the VAULT-BROKER-DENIED error, e.g. `fatsecret/credentials`)." },
         scope: { type: "string", enum: ["read", "write"], description: 'Access scope: "read" (default) for `vault:<key>` references; "write" if the agent needs to put new values.' },
-        reason: { type: "string", description: `Short human-readable rationale rendered on the card (e.g. "to look up today's food log entries"). Helps the operator decide.` },
+        reason: { type: "string", description: `REQUIRED in practice \u2014 short human-readable rationale rendered on the card (e.g. "to look up today's food log entries"). The approval card now renders "why: not provided" when this is omitted, which signals to the operator that the agent skipped its explanation \u2014 they will usually Deny. Always supply a one-line rationale.` },
         duration: { type: "string", description: 'Requested grant TTL, like "30d" or "12h". Default 30d, capped at 90d. Beyond 90d the operator should use the host CLI explicitly.' },
         message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message if not specified." }
       },

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

@@ -37781,14 +37781,14 @@ function createAnswerStream(config) {
       scheduledTimer = null;
     }
   }
-  async function clearDraftBestEffort() {
-    if (!usesDraftTransport || draftApi == null || draftId == null)
+  async function clearDraftBestEffort(targetDraftId = draftId) {
+    if (!usesDraftTransport || draftApi == null || targetDraftId == null)
       return;
     try {
       const params = {};
       if (threadId != null)
         params.message_thread_id = threadId;
-      await draftApi(chatId, draftId, "", Object.keys(params).length > 0 ? params : undefined);
+      await draftApi(chatId, targetDraftId, "", Object.keys(params).length > 0 ? params : undefined);
     } catch {}
   }
   async function sendDraft(text) {
@@ -38008,6 +38008,10 @@ function createAnswerStream(config) {
       stopped = false;
       materialized = false;
       if (usesDraftTransport) {
+        const staleDraftId = draftId;
+        if (staleDraftId != null) {
+          clearDraftBestEffort(staleDraftId);
+        }
         draftId = allocateDraftId2();
       }
       log?.(`answer-stream: forceNewMessage (gen=${generation})`);
@@ -39638,9 +39642,13 @@ function parseSteerPrefix(body) {
 function escapeXmlAttribute(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
+function decodeXmlEntities(s) {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&");
+}
 function formatPriorAssistantPreview(text, maxChars = 200) {
   const stripped = text.replace(/<[^>]*>/g, "");
-  const collapsed = stripped.replace(/\s+/g, " ").trim();
+  const decoded = decodeXmlEntities(stripped);
+  const collapsed = decoded.replace(/\s+/g, " ").trim();
   const truncated = collapsed.length > maxChars ? collapsed.slice(0, maxChars) : collapsed;
   return escapeXmlAttribute(truncated);
 }
@@ -48305,6 +48313,8 @@ function defaultReadEvents(stateDir) {
 import { basename as basename5 } from "node:path";
 var COMMAND_TITLE_MAX = 40;
 var PATH_TITLE_MAX = 40;
+var DESCRIPTION_LINE_MAX = 240;
+var INPUT_VALUE_MAX = 60;
 var MCP_TOOL_DESCRIPTIONS = {
   "mcp__agent-config__config_get": "Read its own merged config",
   "mcp__agent-config__cron_list": "List its own scheduled tasks",
@@ -48329,15 +48339,17 @@ var MCP_TOOL_DESCRIPTIONS = {
 function summarizeToolForTitle(toolName, inputPreview) {
   if (toolName.startsWith("mcp__")) {
     const curated = MCP_TOOL_DESCRIPTIONS[toolName];
-    if (curated)
-      return curated;
-    const parts = toolName.split("__");
-    if (parts.length >= 3) {
-      const server = parts[1];
-      const verb = parts.slice(2).join("__").replace(/_/g, " ");
-      return `${server}: ${verb}`;
-    }
-    return toolName;
+    const base = curated ? curated : (() => {
+      const parts = toolName.split("__");
+      if (parts.length >= 3) {
+        const server = parts[1];
+        const verb = parts.slice(2).join("__").replace(/_/g, " ");
+        return `${server}: ${verb}`;
+      }
+      return toolName;
+    })();
+    const argHint = firstScalarArgHint(parseInput(inputPreview));
+    return argHint ? `${base} (${argHint})` : base;
   }
   const input = parseInput(inputPreview);
   if (!input)
@@ -48345,7 +48357,13 @@ function summarizeToolForTitle(toolName, inputPreview) {
   switch (toolName) {
     case "Skill": {
       const skill = readString(input, "skill") ?? readString(input, "skill_name") ?? readString(input, "skillName") ?? readString(input, "name") ?? skillBasenameFromPath(input);
-      return skill ? `${toolName} (${skill})` : toolName;
+      if (skill)
+        return `${toolName} (${skill})`;
+      const command = readString(input, "command");
+      if (command)
+        return `${toolName}: ${truncate5(command, COMMAND_TITLE_MAX)}`;
+      const argHint = firstScalarArgHint(input);
+      return argHint ? `${toolName} (${argHint})` : toolName;
     }
     case "Bash": {
       const command = readString(input, "command");
@@ -48373,6 +48391,47 @@ function summarizeToolForTitle(toolName, inputPreview) {
       return toolName;
   }
 }
+function formatPermissionCardBody(opts) {
+  const summary = summarizeToolForTitle(opts.toolName, opts.inputPreview);
+  const lines = [];
+  const agentBit = opts.agentName && opts.agentName.length > 0 ? `<b>${escapeTgHtml(opts.agentName)}</b> \u00b7 ` : "";
+  lines.push(`\uD83D\uDD10 ${agentBit}${escapeTgHtml(summary)}`);
+  const rawWhy = (opts.description ?? "").replace(/\s+/g, " ").trim();
+  const truncatedWhy = rawWhy.length > DESCRIPTION_LINE_MAX ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "\u2026" : rawWhy;
+  if (truncatedWhy.length > 0) {
+    lines.push(`why: <i>${escapeTgHtml(truncatedWhy)}</i>`);
+  } else {
+    lines.push(`why: <i>not provided</i>`);
+  }
+  return lines.join(`
+`);
+}
+function escapeTgHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function firstScalarArgHint(input) {
+  if (!input)
+    return null;
+  const SKIP = new Set([
+    "chat_id",
+    "chatId",
+    "message_thread_id",
+    "messageThreadId",
+    "request_id",
+    "requestId"
+  ]);
+  for (const [key, value] of Object.entries(input)) {
+    if (SKIP.has(key))
+      continue;
+    if (typeof value === "string" && value.length > 0) {
+      return `${key}: ${truncate5(value, INPUT_VALUE_MAX)}`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return `${key}: ${String(value)}`;
+    }
+  }
+  return null;
+}
 function parseInput(raw) {
   if (!raw || typeof raw !== "string")
     return null;
@@ -48671,10 +48730,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.37";
-var COMMIT_SHA = "623c57e0";
-var COMMIT_DATE = "2026-05-25T06:09:28Z";
-var LATEST_PR = 1789;
+var VERSION = "0.13.39";
+var COMMIT_SHA = "8681f423";
+var COMMIT_DATE = "2026-05-25T07:06:31Z";
+var LATEST_PR = 1797;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -50838,14 +50897,22 @@ ${reminder}
     const { requestId, toolName, description, inputPreview } = msg;
     pendingPermissions.set(requestId, { tool_name: toolName, description, input_preview: inputPreview, startedAt: Date.now() });
     const access = loadAccess();
-    const text = `\uD83D\uDD10 Permission: ${summarizeToolForTitle(toolName, inputPreview)}`;
+    const text = formatPermissionCardBody({
+      toolName,
+      inputPreview,
+      description,
+      agentName: _client.agentName
+    });
     const alwaysRule = resolveAlwaysAllowRule(toolName, inputPreview);
     const keyboard = new import_grammy9.InlineKeyboard().text("See more", `perm:more:${requestId}`).text("\u2705 Allow", `perm:allow:${requestId}`).text("\u274C Deny", `perm:deny:${requestId}`);
     if (alwaysRule != null) {
       keyboard.row().text(`\uD83D\uDD01 Always allow ${alwaysRule.label}`, `perm:always:${requestId}`);
     }
     for (const chat_id of access.allowFrom) {
-      bot.api.sendMessage(chat_id, text, { reply_markup: keyboard }).catch((e) => {
+      bot.api.sendMessage(chat_id, text, {
+        parse_mode: "HTML",
+        reply_markup: keyboard
+      }).catch((e) => {
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}
 `);
       });
@@ -52130,6 +52197,8 @@ function renderVaultRequestAccessCard(req) {
   lines.push(`scope: <code>${scopeLabel}</code> \xB7 duration: <code>${durationLabel}</code>`);
   if (req.reason && req.reason.length > 0) {
     lines.push(`why: <i>${escapeHtmlForTg(req.reason)}</i>`);
+  } else {
+    lines.push(`why: <i>not provided</i>`);
   }
   lines.push("");
   lines.push(`<i>Tap Approve to mint a scoped grant token (same flow as <code>switchroom vault grant</code>). Tap Deny to refuse \u2014 the agent will receive a denial result.</i>`);

package/telegram-plugin/dist/server.js

@@ -24492,7 +24492,7 @@ var init_bridge = __esm(async () => {
           chat_id: { type: "string", description: "Chat to render the approval card in (use the chat_id of the user message that triggered the workflow)." },
           key: { type: "string", description: "Vault key the agent wants access to (matches the key shown in the VAULT-BROKER-DENIED error, e.g. `fatsecret/credentials`)." },
           scope: { type: "string", enum: ["read", "write"], description: 'Access scope: "read" (default) for `vault:<key>` references; "write" if the agent needs to put new values.' },
-          reason: { type: "string", description: `Short human-readable rationale rendered on the card (e.g. "to look up today's food log entries"). Helps the operator decide.` },
+          reason: { type: "string", description: `REQUIRED in practice \u2014 short human-readable rationale rendered on the card (e.g. "to look up today's food log entries"). The approval card now renders "why: not provided" when this is omitted, which signals to the operator that the agent skipped its explanation \u2014 they will usually Deny. Always supply a one-line rationale.` },
           duration: { type: "string", description: 'Requested grant TTL, like "30d" or "12h". Default 30d, capped at 90d. Beyond 90d the operator should use the host CLI explicitly.' },
           message_thread_id: { type: "string", description: "Forum topic thread ID. Auto-applied from the last inbound message if not specified." }
         },

package/telegram-plugin/gateway/gateway.ts

@@ -356,7 +356,7 @@ import { maybeRenderUpdateAnnouncement } from './update-announce.js'
 import { createIssuesCardHandle, type IssuesCardHandle } from '../issues-card.js'
 import { startIssuesWatcher, type IssuesWatcherHandle } from '../issues-watcher.js'
 import { list as listIssues, resolve as resolveIssue } from '../../src/issues/index.js'
-import { summarizeToolForTitle } from '../permission-title.js'
+import { summarizeToolForTitle, formatPermissionCardBody } from '../permission-title.js'
 import { resolveAlwaysAllowRule } from '../permission-rule.js'
 import {
   readClaudeJsonOverage,
@@ -3863,10 +3863,18 @@ const ipcServer: IpcServer = createIpcServer({
     const { requestId, toolName, description, inputPreview } = msg
     pendingPermissions.set(requestId, { tool_name: toolName, description, input_preview: inputPreview, startedAt: Date.now() })
     const access = loadAccess()
-    // Lift the most-identifying field into the title so the user can
-    // approve at a glance — e.g. `Skill (mail)` instead of bare `Skill`.
-    // See #186.
-    const text = `🔐 Permission: ${summarizeToolForTitle(toolName, inputPreview)}`
+    // #1790 — multi-line collapsed body so the operator can see what
+    // is being requested and why without tapping "See more". Mirrors
+    // the `vault_request_access` card layout (the gold standard).
+    // The detail (expanded `tool_name` / pretty `input_preview`)
+    // still surfaces on the See-more tap; this is the
+    // collapsed-view fix only. Sent with parse_mode=HTML below.
+    const text = formatPermissionCardBody({
+      toolName,
+      inputPreview,
+      description,
+      agentName: _client.agentName,
+    })
     // Build the keyboard. The "🔁 Always" button only appears when we
     // can synthesize a meaningful allow-rule for this tool — for an
     // unknown tool we'd write a useless rule (or worse, a rule that
@@ -3887,8 +3895,13 @@ const ipcServer: IpcServer = createIpcServer({
         .text(`🔁 Always allow ${alwaysRule.label}`, `perm:always:${requestId}`)
     }
     for (const chat_id of access.allowFrom) {
-      // allow-raw-bot-api: permission-request keyboard fan-out; reply_markup-only opts, no thread_id
-      void bot.api.sendMessage(chat_id, text, { reply_markup: keyboard }).catch(e => {
+      // parse_mode=HTML pairs with formatPermissionCardBody (#1790)
+      // so the <b>/<i> tags render as formatting.
+      // allow-raw-bot-api: permission-request keyboard fan-out; reply_markup + parse_mode only, no thread_id
+      void bot.api.sendMessage(chat_id, text, {
+        parse_mode: 'HTML',
+        reply_markup: keyboard,
+      }).catch(e => {
         process.stderr.write(`telegram gateway: permission_request send to ${chat_id} failed: ${e}\n`)
       })
     }
@@ -5998,8 +6011,17 @@ function renderVaultRequestAccessCard(req: PendingVaultRequestAccess): string {
   lines.push(`🔐 <b>${escapeHtmlForTg(req.agent)}</b> wants vault access`)
   lines.push(`key: <code>${escapeHtmlForTg(req.key)}</code>`)
   lines.push(`scope: <code>${scopeLabel}</code> · duration: <code>${durationLabel}</code>`)
+  // #1790 — always render the why-line, even when the agent omitted
+  // `reason`. Rendering "not provided" makes a missing rationale
+  // visibly an agent-side failure (the tool description nudges the
+  // model to supply one — see executeVaultRequestAccess); skipping
+  // the line silently used to make the omission look like a card-
+  // template choice, which the operator couldn't tell apart from a
+  // legitimate "no reason needed" case.
   if (req.reason && req.reason.length > 0) {
     lines.push(`why: <i>${escapeHtmlForTg(req.reason)}</i>`)
+  } else {
+    lines.push(`why: <i>not provided</i>`)
   }
   lines.push('')
   lines.push(`<i>Tap Approve to mint a scoped grant token (same flow as <code>switchroom vault grant</code>). Tap Deny to refuse — the agent will receive a denial result.</i>`)

package/telegram-plugin/permission-title.ts

@@ -1,21 +1,32 @@
 /**
- * Build a human-readable title for the inline-keyboard permission
- * approval message. Pre-fix the title was always `🔐 Permission:
- * ${toolName}` — for a `Skill` or `Bash` call the user couldn't tell
- * which skill / command was being approved without tapping "See more".
+ * Build the inline-keyboard permission approval message — title + body.
  *
- * The detail surfaces (the expanded view at server.ts/gateway.ts) still
- * render the full description + input_preview block; this helper just
- * lifts the most identifying field into the title so the user can
- * approve at a glance.
+ * Two related concerns:
  *
- * See #186.
+ *   `summarizeToolForTitle` (one line, no escaping) is the bare summary
+ *   used in the always-allow rule label and as the body-builder's
+ *   internal building block. Pre-#186 the title was always `🔐
+ *   Permission: ${toolName}` — for a `Skill` or `Bash` call the user
+ *   couldn't tell which skill / command was being approved without
+ *   tapping "See more".
+ *
+ *   `formatPermissionCardBody` (multi-line, HTML-escaped for
+ *   parse_mode=HTML) is the body of the card itself. Pre-#1790 the
+ *   collapsed card was a single line — operators had to tap "See more"
+ *   to see the agent's stated reason or input preview. This mirrors
+ *   the vault `vault_request_access` card's three-line layout (the
+ *   gold standard) so every approval surface answers "what" + "why"
+ *   without an expand tap.
+ *
+ * See #186 (title) and #1790 (body).
  */
 
 import { basename } from "node:path";
 
 const COMMAND_TITLE_MAX = 40;
 const PATH_TITLE_MAX = 40;
+const DESCRIPTION_LINE_MAX = 240;
+const INPUT_VALUE_MAX = 60;
 
 /**
  * Human-friendly descriptions for switchroom-managed MCP tools. The
@@ -70,17 +81,26 @@ export function summarizeToolForTitle(
   // description (so the card reads "Read its own merged config"
   // instead of "mcp__agent-config__config_get"). Fall through to a
   // generic `<server>: <verb-with-spaces>` shape for unknown MCP
-  // tools and finally to the raw name when even that fails.
+  // tools and finally to the raw name when even that fails. When
+  // we have an input preview, append the first arg-value pair so
+  // the operator sees what's being requested without expanding —
+  // e.g. `Read its own merged config (key: coolify/api-token)`
+  // rather than just `Read its own merged config`. (#1790)
   if (toolName.startsWith("mcp__")) {
     const curated = MCP_TOOL_DESCRIPTIONS[toolName];
-    if (curated) return curated;
-    const parts = toolName.split("__");
-    if (parts.length >= 3) {
-      const server = parts[1]!;
-      const verb = parts.slice(2).join("__").replace(/_/g, " ");
-      return `${server}: ${verb}`;
-    }
-    return toolName;
+    const base = curated
+      ? curated
+      : (() => {
+          const parts = toolName.split("__");
+          if (parts.length >= 3) {
+            const server = parts[1]!;
+            const verb = parts.slice(2).join("__").replace(/_/g, " ");
+            return `${server}: ${verb}`;
+          }
+          return toolName;
+        })();
+    const argHint = firstScalarArgHint(parseInput(inputPreview));
+    return argHint ? `${base} (${argHint})` : base;
   }
 
   const input = parseInput(inputPreview);
@@ -90,17 +110,26 @@ export function summarizeToolForTitle(
     case "Skill": {
       // Claude Code's Skill tool input shape has shifted across versions
       // and skill flavours. Read defensively from every known field
-      // before falling back to the bare tool name — the user reported
-      // a popup that rendered as `🔐 Permission: Skill` (no brackets)
-      // because we'd only checked `skill`. The skill name is the most
-      // identifying field of the prompt; never drop it silently.
+      // before falling back. The skill name is the most identifying
+      // field of the prompt; never drop it silently.
+      //
+      // (#1790) Final fallback added: when no skill-name key matches,
+      // try `command` (some Skill variants pass the invocation under
+      // that key), then the first scalar arg-value pair. Pre-fix the
+      // default returned a bare `Skill` with zero context — operators
+      // saw "🔐 Permission: Skill" with no way to tell what was being
+      // asked without tapping See more.
       const skill =
         readString(input, "skill") ??
         readString(input, "skill_name") ??
         readString(input, "skillName") ??
         readString(input, "name") ??
         skillBasenameFromPath(input);
-      return skill ? `${toolName} (${skill})` : toolName;
+      if (skill) return `${toolName} (${skill})`;
+      const command = readString(input, "command");
+      if (command) return `${toolName}: ${truncate(command, COMMAND_TITLE_MAX)}`;
+      const argHint = firstScalarArgHint(input);
+      return argHint ? `${toolName} (${argHint})` : toolName;
     }
     case "Bash": {
       const command = readString(input, "command");
@@ -129,6 +158,108 @@ export function summarizeToolForTitle(
   }
 }
 
+/**
+ * Build the multi-line collapsed body of an approval card (#1790).
+ *
+ * Pre-fix the card was a single line — `🔐 Permission: <title>` —
+ * and the agent's stated `description` plus the input preview only
+ * surfaced when the operator tapped "See more". For skill / generic
+ * tool prompts the title alone (e.g. `Skill (mail)`) is rarely
+ * enough to approve at a glance; the operator needs to see *why*
+ * before they tap Allow / Deny.
+ *
+ * Layout mirrors the `vault_request_access` card (the gold standard):
+ *
+ *   🔐 <agent> · <tool summary>
+ *   why: <description-or-"not provided">
+ *
+ * The agent line is dropped when `agentName` is null (the
+ * gateway's bridge client may be anonymous during early-boot edge
+ * cases — better to render the title than a misleading blank).
+ *
+ * Output is HTML-escaped and intended for `parse_mode: 'HTML'`
+ * via Telegram's Bot API.
+ */
+export function formatPermissionCardBody(opts: {
+  toolName: string;
+  inputPreview: string | undefined;
+  description: string | undefined;
+  agentName: string | null;
+}): string {
+  const summary = summarizeToolForTitle(opts.toolName, opts.inputPreview);
+  const lines: string[] = [];
+
+  const agentBit = opts.agentName && opts.agentName.length > 0
+    ? `<b>${escapeTgHtml(opts.agentName)}</b> · `
+    : "";
+  lines.push(`🔐 ${agentBit}${escapeTgHtml(summary)}`);
+
+  // The agent's stated reason. Always render the line — when the
+  // agent omitted a `description`, render an explicit
+  // `why: <i>not provided</i>` rather than skip silently, so the
+  // missing-rationale is visible as an agent-side failure (matches
+  // the vault card's #1790 treatment of an omitted `reason`).
+  const rawWhy = (opts.description ?? "").replace(/\s+/g, " ").trim();
+  const truncatedWhy =
+    rawWhy.length > DESCRIPTION_LINE_MAX
+      ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
+      : rawWhy;
+  if (truncatedWhy.length > 0) {
+    lines.push(`why: <i>${escapeTgHtml(truncatedWhy)}</i>`);
+  } else {
+    lines.push(`why: <i>not provided</i>`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Minimal HTML escape for Telegram `parse_mode=HTML`. Mirrors
+ * `escapeHtmlForTg` in gateway.ts; duplicated here to keep
+ * permission-title.ts free of a gateway import (the file is
+ * referenced by both server.ts and gateway.ts).
+ */
+function escapeTgHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Return a `key: value` hint for the first scalar (string / number /
+ * boolean) arg in the input preview. Used as a last-ditch context
+ * line on uncurated MCP tools and Skill calls whose canonical
+ * skill-name fields are all missing.
+ *
+ * Skips obviously-routing keys (`chat_id`, `message_thread_id`,
+ * `request_id`) that aren't useful to a human operator deciding
+ * whether to approve. Returns `null` when nothing scalar remains.
+ */
+function firstScalarArgHint(
+  input: Record<string, unknown> | null,
+): string | null {
+  if (!input) return null;
+  const SKIP = new Set([
+    "chat_id",
+    "chatId",
+    "message_thread_id",
+    "messageThreadId",
+    "request_id",
+    "requestId",
+  ]);
+  for (const [key, value] of Object.entries(input)) {
+    if (SKIP.has(key)) continue;
+    if (typeof value === "string" && value.length > 0) {
+      return `${key}: ${truncate(value, INPUT_VALUE_MAX)}`;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      return `${key}: ${String(value)}`;
+    }
+  }
+  return null;
+}
+
 function parseInput(raw: string | undefined): Record<string, unknown> | null {
   if (!raw || typeof raw !== "string") return null;
   const trimmed = raw.trim();

package/telegram-plugin/steering.ts

@@ -73,22 +73,53 @@ export function escapeXmlAttribute(s: string): string {
     .replace(/'/g, ''')
 }
 
+/**
+ * Decode the small set of HTML / XML entities switchroom emits when it
+ * renders model output as Telegram HTML. Pre-#1791 this function did
+ * not decode and `formatPriorAssistantPreview` then re-escaped the
+ * already-encoded entities, so a turn containing inline `<code>` would
+ * surface to the model on the next inbound as `&amp;amp;lt;…&amp;amp;gt;`
+ * (triple-encoded). The model had to mentally decode three layers to
+ * recover the original characters it wrote — measurably hostile to
+ * comprehension on turns with placeholders, JSX, XML, generics, etc.
+ *
+ * Decoding before re-escape closes that loop: the attribute boundary
+ * stays safe because `escapeXmlAttribute` runs unchanged at the tail.
+ *
+ * Limited to the canonical six entities — there's no general HTML
+ * entity table here, which keeps the surface predictable.
+ */
+function decodeXmlEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    // `&amp;` last so we don't accidentally re-decode `&amp;lt;` → `<` on
+    // a single pass — the order above relies on `&amp;` still being
+    // intact during the prior replaces.
+    .replace(/&amp;/g, '&')
+}
+
 /**
  * Produce a short, safe preview of the last assistant turn for injection
  * as an XML attribute. Strips HTML tags (so `<b>foo</b>` becomes `foo`),
- * collapses all whitespace runs into single spaces, truncates to
- * `maxChars` visible characters, then XML-escapes.
- *
- * We do NOT decode HTML entities — a literal `&amp;` in the source
- * survives as `&amp;amp;` after escape, which is fine: the attribute is
- * for the model's situational awareness, not faithful rendering.
+ * decodes the canonical six XML entities so the model sees the original
+ * characters (not triple-encoded `&amp;amp;lt;` — see #1791), collapses
+ * all whitespace runs into single spaces, truncates to `maxChars` visible
+ * characters, then XML-escapes for safe attribute injection.
  */
 export function formatPriorAssistantPreview(text: string, maxChars = 200): string {
   // Strip HTML tags. Anything angle-bracketed between < and > goes away;
   // this is deliberately liberal (no tag-name whitelist) because the
   // preview is for the model's eyes only.
   const stripped = text.replace(/<[^>]*>/g, '')
-  const collapsed = stripped.replace(/\s+/g, ' ').trim()
+  // #1791: decode entities BEFORE collapse/truncate/re-escape so the
+  // model sees the prose it actually wrote. The re-escape at the tail
+  // preserves attribute-injection safety.
+  const decoded = decodeXmlEntities(stripped)
+  const collapsed = decoded.replace(/\s+/g, ' ').trim()
   const truncated = collapsed.length > maxChars ? collapsed.slice(0, maxChars) : collapsed
   return escapeXmlAttribute(truncated)
 }

package/telegram-plugin/tests/answer-stream.test.ts

@@ -527,6 +527,92 @@ describe('answer-stream — clears sendMessageDraft on terminal paths (#1704)',
   })
 })
 
+// ─── #1792 — forceNewMessage clears the stale draftId before rotating ───
+//
+// Background: `forceNewMessage()` rotates `draftId` to a fresh allocation
+// so the stream can be re-used for a new turn (typical caller: gateway
+// rapid-steer path in `handleSessionEvent` enqueue branch — calls
+// `forceNewMessage(); stop()` on the prior turn's stream before opening
+// the new turn). Pre-#1792, the rotation orphaned the prior turn's
+// draft content in the user's compose box until Telegram's 30 s draft
+// expiry — `stop()`'s fire-and-forget clear closed over the (now-new)
+// `draftId`, so the clear targeted the unused id, not the stale one.
+//
+// Post-fix: `forceNewMessage` itself clears the stale draftId BEFORE
+// rotating. `stop()` continues to clear whatever draftId is current
+// at the time it runs (defensive, also fine: clearing an unused id
+// is a harmless no-op for the user).
+
+describe('answer-stream — forceNewMessage clears the stale draft before rotating (#1792)', () => {
+  it('clears the pre-rotation draftId when forceNewMessage rotates', async () => {
+    const sendMessage = makeSendMessage()
+    const editMessageText = makeEditMessageText()
+    const sendMessageDraft = makeSendMessageDraft()
+    const stream = createAnswerStream({
+      chatId: 'chat1',
+      isPrivateChat: true,
+      throttleMs: 250,
+      sendMessage,
+      editMessageText,
+      sendMessageDraft,
+    })
+
+    // Open the stream — this allocates draftId N and fires sendDraft(N).
+    stream.update('first turn thought')
+    await flushMicrotasks()
+    expect(sendMessageDraft).toHaveBeenCalledTimes(1)
+    const staleDraftId = (sendMessageDraft.mock.calls[0] as unknown as [string, number, string, unknown])[1]
+    sendMessageDraft.mockClear()
+
+    // Rotate. forceNewMessage must enqueue a clear against the OLD
+    // draftId before bumping to the new allocation — pre-fix the
+    // stale content stayed in the compose box for 30 s.
+    stream.forceNewMessage()
+    await flushMicrotasks()
+
+    expect(sendMessageDraft).toHaveBeenCalledTimes(1)
+    const clearedId = (sendMessageDraft.mock.calls[0] as unknown as [string, number, string, unknown])[1]
+    const clearedText = (sendMessageDraft.mock.calls[0] as unknown as [string, number, string, unknown])[2]
+    expect(clearedId).toBe(staleDraftId)
+    expect(clearedText).toBe('')
+  })
+
+  it('the gateway sequence forceNewMessage(); stop() clears the stale draftId', async () => {
+    // Mirrors the only production caller — telegram-plugin/gateway/
+    // gateway.ts:6476-6477 cleans up the prior turn's answer-stream
+    // before opening a new turn (rapid steer / queue path).
+    const sendMessage = makeSendMessage()
+    const editMessageText = makeEditMessageText()
+    const sendMessageDraft = makeSendMessageDraft()
+    const stream = createAnswerStream({
+      chatId: 'chat1',
+      isPrivateChat: true,
+      throttleMs: 250,
+      sendMessage,
+      editMessageText,
+      sendMessageDraft,
+    })
+
+    stream.update('prior turn thought')
+    await flushMicrotasks()
+    const staleDraftId = (sendMessageDraft.mock.calls[0] as unknown as [string, number, string, unknown])[1]
+    sendMessageDraft.mockClear()
+
+    stream.forceNewMessage()
+    stream.stop()
+    await flushMicrotasks()
+
+    // The stale id must have been cleared by ONE of the two calls
+    // (forceNewMessage in this design); the new unused id may also
+    // be cleared by stop() — harmless. The load-bearing invariant
+    // is "the stale id reaches sendMessageDraft('') somewhere".
+    const clearedIds = (sendMessageDraft.mock.calls as unknown as Array<[string, number, string, unknown]>)
+      .filter(c => c[2] === '')
+      .map(c => c[1])
+    expect(clearedIds).toContain(staleDraftId)
+  })
+})
+
 describe('answer-stream — empty / whitespace-only text is a no-op', () => {
   it('update("") does not trigger any transport call', async () => {
     const sendMessage = makeSendMessage()

package/telegram-plugin/tests/permission-title.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest'
-import { summarizeToolForTitle } from '../permission-title.js'
+import { summarizeToolForTitle, formatPermissionCardBody } from '../permission-title.js'
 
 describe('summarizeToolForTitle (#186)', () => {
   test('Skill: surfaces the skill name in brackets', () => {
@@ -49,12 +49,37 @@ describe('summarizeToolForTitle (#186)', () => {
     expect(summarizeToolForTitle('Skill', undefined)).toBe('Skill')
   })
 
-  test('falls back to bare toolName when expected key is missing', () => {
+  test('falls back to bare toolName for non-Skill tools when expected key is missing', () => {
     const input = JSON.stringify({ unrelated: 'x' })
-    expect(summarizeToolForTitle('Skill', input)).toBe('Skill')
+    // Bash has no first-arg fallback (its only identifying field is command).
     expect(summarizeToolForTitle('Bash', input)).toBe('Bash')
   })
 
+  // #1790 — the prior contract was "fall back to bare toolName when no
+  // skill-name key matched"; that produced operator-hostile cards like
+  // `🔐 Permission: Skill` with zero context. The Skill summarizer now
+  // tries `command`, then a first-scalar-arg hint, before giving up.
+  test('Skill: when no skill-name key matches, falls back to command field (#1790)', () => {
+    const input = JSON.stringify({ command: 'gen calendar event' })
+    expect(summarizeToolForTitle('Skill', input)).toBe('Skill: gen calendar event')
+  })
+
+  test('Skill: when no skill-name and no command, surfaces the first scalar arg (#1790)', () => {
+    const input = JSON.stringify({ unrelated: 'x' })
+    expect(summarizeToolForTitle('Skill', input)).toBe('Skill (unrelated: x)')
+  })
+
+  test('Skill: skips routing-only keys when surfacing first scalar arg (#1790)', () => {
+    // chat_id / message_thread_id / request_id never help an operator
+    // decide; the helper skips them and finds the next useful field.
+    const input = JSON.stringify({
+      chat_id: '12345',
+      message_thread_id: '42',
+      topic: 'morning summary',
+    })
+    expect(summarizeToolForTitle('Skill', input)).toBe('Skill (topic: morning summary)')
+  })
+
   test('Bash: collapses internal whitespace before truncating', () => {
     const input = JSON.stringify({
       command: 'echo  \t  hello\nworld',
@@ -134,4 +159,123 @@ describe('summarizeToolForTitle (#186)', () => {
   test('MCP malformed: bare mcp__ prefix without __<server>__<verb> shape is left alone', () => {
     expect(summarizeToolForTitle('mcp__bad', undefined)).toBe('mcp__bad')
   })
+
+  // #1790 — append a `(key: value)` hint when an MCP tool's preview
+  // carries a scalar arg. Gives operators context on curated and
+  // uncurated MCP tools alike without an expand tap.
+  test('MCP curated tool appends first-arg hint when input_preview present (#1790)', () => {
+    const input = JSON.stringify({ key: 'coolify/api-token' })
+    expect(summarizeToolForTitle('mcp__agent-config__config_get', input)).toBe(
+      'Read its own merged config (key: coolify/api-token)',
+    )
+  })
+
+  test('MCP uncurated tool appends first-arg hint (#1790)', () => {
+    const input = JSON.stringify({ folder_id: 'abc123' })
+    expect(summarizeToolForTitle('mcp__google-workspace__list_files', input)).toBe(
+      'google-workspace: list files (folder_id: abc123)',
+    )
+  })
+
+  test('MCP arg hint skips routing-only keys (#1790)', () => {
+    const input = JSON.stringify({ chat_id: '12345', query: 'budget Q3' })
+    expect(summarizeToolForTitle('mcp__hindsight__recall', input)).toBe(
+      'Recall relevant memories (query: budget Q3)',
+    )
+  })
+})
+
+// ──────────────────────────────────────────────────────────────────────
+// #1790 — formatPermissionCardBody: multi-line collapsed-view body
+// for approval cards. Mirrors the vault_request_access card layout.
+// ──────────────────────────────────────────────────────────────────────
+
+describe('formatPermissionCardBody (#1790)', () => {
+  test('renders agent · summary, then a why-line, when both are present', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Skill',
+      inputPreview: JSON.stringify({ skill: 'mail' }),
+      description: 'Compose the morning brief',
+      agentName: 'clerk',
+    })
+    expect(body).toBe(
+      [
+        '🔐 <b>clerk</b> · Skill (mail)',
+        'why: <i>Compose the morning brief</i>',
+      ].join('\n'),
+    )
+  })
+
+  test('renders "why: <i>not provided</i>" when description is missing', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Bash',
+      inputPreview: JSON.stringify({ command: 'ls /tmp' }),
+      description: undefined,
+      agentName: 'gymbro',
+    })
+    expect(body).toBe(
+      ['🔐 <b>gymbro</b> · Bash: ls /tmp', 'why: <i>not provided</i>'].join('\n'),
+    )
+  })
+
+  test('renders "not provided" when description is whitespace-only', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Bash',
+      inputPreview: JSON.stringify({ command: 'ls /tmp' }),
+      description: '   \n  ',
+      agentName: 'gymbro',
+    })
+    expect(body).toContain('why: <i>not provided</i>')
+  })
+
+  test('drops the agent prefix when agentName is null (early-boot edge)', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Skill',
+      inputPreview: JSON.stringify({ skill: 'mail' }),
+      description: 'do the thing',
+      agentName: null,
+    })
+    expect(body).toBe(['🔐 Skill (mail)', 'why: <i>do the thing</i>'].join('\n'))
+  })
+
+  test('HTML-escapes < > & in agentName / summary / description', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Bash',
+      inputPreview: JSON.stringify({ command: 'echo "a < b && c > d"' }),
+      description: 'compare a < b & c > d',
+      agentName: 'agent<test>',
+    })
+    expect(body).toContain('&lt;test&gt;')
+    expect(body).toContain('&amp;')
+    expect(body).not.toContain('<test>')
+    // The literal "<i>not provided</i>" and "<b>...</b>" wrapping tags
+    // around legitimate fields must survive untouched — only the
+    // user-supplied content is escaped.
+    expect(body).toContain('<b>')
+    expect(body).toContain('<i>')
+  })
+
+  test('truncates a very long description with an ellipsis', () => {
+    const longWhy = 'x'.repeat(500)
+    const body = formatPermissionCardBody({
+      toolName: 'Skill',
+      inputPreview: JSON.stringify({ skill: 'mail' }),
+      description: longWhy,
+      agentName: 'clerk',
+    })
+    // 240-char ceiling + trailing ellipsis
+    expect(body).toContain('xxxx…</i>')
+    // First line still intact
+    expect(body.split('\n')[0]).toBe('🔐 <b>clerk</b> · Skill (mail)')
+  })
+
+  test('collapses internal whitespace in description so the layout stays one-line', () => {
+    const body = formatPermissionCardBody({
+      toolName: 'Skill',
+      inputPreview: JSON.stringify({ skill: 'mail' }),
+      description: 'first\n\nsecond\t\t paragraph',
+      agentName: 'clerk',
+    })
+    expect(body).toContain('why: <i>first second paragraph</i>')
+  })
 })

package/telegram-plugin/tests/steering.test.ts

@@ -138,10 +138,43 @@ describe('formatPriorAssistantPreview', () => {
     expect(formatPriorAssistantPreview('a & b < c')).toBe('a &amp; b &lt; c')
   })
 
-  test('does NOT decode HTML entities (documented)', () => {
-    // Entities like &amp; survive as literal "&amp;" through strip and then
-    // get re-escaped to &amp;amp;. Acceptable for a model-facing preview.
-    expect(formatPriorAssistantPreview('a &amp; b')).toBe('a &amp;amp; b')
+  // ─── #1791 — decode entities before re-escape ───────────────────────────
+  // Pre-fix this function did NOT decode, so an already-encoded source
+  // (e.g. the rendered HTML stored in history) was re-escaped on top of
+  // its own encoding. The model saw `&amp;amp;lt;bar&amp;amp;gt;` (triple
+  // encoded) instead of `<bar>`. Decoding before the trim/re-escape pass
+  // closes that loop; the attribute boundary stays safe because
+  // escapeXmlAttribute runs unchanged at the tail.
+
+  test('decodes &amp; before re-escape (single-pass, not triple) — #1791', () => {
+    // Source stored in history as escaped HTML: `a &amp; b`.
+    // Pre-fix output: `a &amp;amp; b`. Post-fix: `a &amp; b` (single).
+    expect(formatPriorAssistantPreview('a &amp; b')).toBe('a &amp; b')
+  })
+
+  test('decodes &lt; / &gt; inside stripped tags — #1791', () => {
+    // The classic #1120 case: model wrote `Path: \`/tmp/foo-<bar>/\``,
+    // markdownToHtml stored it as `<code>/tmp/foo-&lt;bar&gt;/</code>`,
+    // strip removes the <code> tags, decode brings back the angle
+    // brackets, escape re-encodes safely for the attribute.
+    expect(formatPriorAssistantPreview('<code>/tmp/foo-&lt;bar&gt;/</code>'))
+      .toBe('/tmp/foo-&lt;bar&gt;/')
+  })
+
+  test('decodes &quot; / &apos; / &nbsp; — #1791', () => {
+    expect(formatPriorAssistantPreview('say &quot;hi&quot;')).toBe('say &quot;hi&quot;')
+    expect(formatPriorAssistantPreview('it&apos;s here')).toBe("it&apos;s here")
+    expect(formatPriorAssistantPreview('a&nbsp;b')).toBe('a b')
+  })
+
+  test('does not over-decode: bare `&amp;lt;` decodes to `&lt;`, not `<` — #1791', () => {
+    // The decode order (&lt; / &gt; / &quot; / &apos; / &nbsp; first, then
+    // &amp;) ensures a single pass doesn't strip two layers of escape.
+    // A literal `&amp;lt;` in source (i.e. someone deliberately encoded
+    // the word "&lt;") becomes `&lt;` after one decode pass, and then
+    // re-escapes back to `&amp;lt;`. Pin this so the order isn't accidentally
+    // flipped to a re-decode loop.
+    expect(formatPriorAssistantPreview('&amp;lt;')).toBe('&amp;lt;')
   })
 
   test('empty string returns empty', () => {

package/telegram-plugin/uat/scenarios/jtbd-pending-progress-html-dm.test.ts

@@ -0,0 +1,124 @@
+/**
+ * UAT — pending-progress edit preserves HTML formatting (#1698 regression gate).
+ *
+ * Promoted from the one-off `pr1706-pending-progress-html-dm.test.ts`
+ * verification scenario per #1793. The pending-progress / silent-anchor
+ * / answer-stream code family in `telegram-plugin/` all touch the
+ * parse_mode contract on cross-turn edits; the existing UAT suite
+ * (`cross-turn-pending-progress-dm.test.ts`, `jtbd-fast-trivial-dm.test.ts`,
+ * `jtbd-soft-commit-dm.test.ts`) covers cadence / round-trip / pacing
+ * but does NOT pin the parse_mode contract. #1698 shipped to prod and
+ * the existing suite went green throughout — this scenario closes that
+ * blind spot.
+ *
+ * Method:
+ *   1. Ask the agent to send ONE reply with both <b> and <code> via
+ *      the reply tool (default html format).
+ *   2. Dispatch a background bash so the turn ends with pending async.
+ *   3. End turn. Pending-progress activates.
+ *   4. After ~60-90s, observe the first edit. Assert text reads back
+ *      WITHOUT literal `<b>` / `<code>` substrings (Telegram parsed
+ *      under HTML, formatting moved to entities, mtcute Message.text
+ *      returns plain prose). Pre-fix, parse_mode was dropped on the
+ *      edit and the tags would render as literal characters.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp, type ObservedMessage } from "../harness.js";
+
+const SLEEP_SECONDS = 90;
+const OVERALL_DEADLINE_MS = 4 * 60_000;
+
+const PROMPT =
+  `Please run \`sleep ${SLEEP_SECONDS}\` in the background using the ` +
+  `Bash tool with \`run_in_background: true\`. Send exactly ONE reply, ` +
+  `using the reply tool with default html format, containing this text ` +
+  `VERBATIM:\n\n` +
+  `<b>Worker dispatched.</b> Running <code>sleep ${SLEEP_SECONDS}</code> ` +
+  `in background.\n\n` +
+  `Do NOT send any other reply until the sleep finishes. Just dispatch ` +
+  `the bash, send that one HTML reply, end your turn. When it finishes ` +
+  `much later, reply with the single word "done".`;
+
+const SUFFIX_RE = /\n\n— still working \(\d+m\)$/;
+
+describe("uat: pending-progress edit preserves HTML formatting (#1698 regression gate)", () => {
+  it(
+    "first pending-progress edit reads back WITHOUT literal HTML tags",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const startedAt = Date.now();
+        await sc.sendDM(PROMPT);
+
+        let anchorMsgId: number | null = null;
+        let editText: string | null = null;
+        const deadline = startedAt + OVERALL_DEADLINE_MS;
+
+        while (Date.now() < deadline) {
+          try {
+            const msg = await sc.expectMessage(
+              (m: ObservedMessage) => m.fromBot,
+              { from: "bot", timeout: deadline - Date.now() },
+            );
+            const rel = Date.now() - startedAt;
+            console.log(
+              `[jtbd-pending-progress-html] +${(rel / 1000).toFixed(1)}s ` +
+                `${msg.edited ? "EDIT" : "FRESH"} msg=${msg.messageId} ` +
+                `${JSON.stringify(msg.text.slice(0, 120))}`,
+            );
+            if (!msg.edited && anchorMsgId == null) {
+              anchorMsgId = msg.messageId;
+              continue;
+            }
+            if (
+              msg.edited &&
+              anchorMsgId === msg.messageId &&
+              SUFFIX_RE.test(msg.text)
+            ) {
+              editText = msg.text;
+              break;
+            }
+          } catch {
+            break;
+          }
+        }
+
+        expect(
+          anchorMsgId,
+          "agent never sent its initial HTML reply — UAT env issue",
+        ).not.toBeNull();
+        expect(
+          editText,
+          `no pending-progress edit observed within ${OVERALL_DEADLINE_MS / 1000}s — ` +
+            `model may not have dispatched async, or pending-progress is disabled`,
+        ).not.toBeNull();
+
+        // ── THE #1698 REGRESSION GATE ─────────────────────────────────
+        // mtcute's Message.text returns the parsed text — formatting
+        // lives in `entities`. So a working parse_mode=HTML edit shows
+        // clean prose with no literal "<b>" / "<code>" substrings.
+        // Pre-fix the gateway dropped parse_mode on the cross-turn
+        // edit and Telegram stored the tags as plain characters.
+        expect(
+          editText,
+          `#1698 regression: pending-progress edit text contains literal "<b>" — ` +
+            `parse_mode was dropped and Telegram is storing the original HTML tags as plain.`,
+        ).not.toContain("<b>");
+        expect(editText).not.toContain("</b>");
+        expect(editText).not.toContain("<code>");
+        expect(editText).not.toContain("</code>");
+
+        // Sanity — the model's prose is still visible (without tags).
+        expect(editText).toContain("Worker dispatched");
+
+        // Belt-and-braces — the suffix landed (proves the edit was
+        // pending-progress and not some other path).
+        expect(editText).toMatch(SUFFIX_RE);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_DEADLINE_MS + 30_000,
+  );
+});