switchroom 0.13.36 → 0.13.38

package/dist/cli/switchroom.js

@@ -23247,6 +23247,9 @@ function emitAgentService(lines, a, imageTag, buildMode, buildContext, homePrefi
   if (existsSync12(`${hostHomeForChecks}/.switchroom/skills`)) {
     lines.push(`      - ${homePrefix}/.switchroom/skills:${homePrefix}/.switchroom/skills:ro`);
   }
+  if (existsSync12(`${hostHomeForChecks}/.switchroom/mcp-launchers`)) {
+    lines.push(`      - ${homePrefix}/.switchroom/mcp-launchers:${homePrefix}/.switchroom/mcp-launchers:ro`);
+  }
   if (existsSync12(`${hostHomeForChecks}/.switchroom/credentials/${a.name}`)) {
     lines.push(`      - ${homePrefix}/.switchroom/credentials/${a.name}:${homePrefix}/.switchroom/credentials:ro`);
   }
@@ -29681,6 +29684,7 @@ __export(exports_doctor, {
   deriveEd25519PublicKeyBytes: () => deriveEd25519PublicKeyBytes,
   classifyReadError: () => classifyReadError,
   checkVaultBrokerSocketPairs: () => checkVaultBrokerSocketPairs,
+  checkUserDeclaredMcps: () => checkUserDeclaredMcps,
   checkTelegram: () => checkTelegram,
   checkStartShStale: () => checkStartShStale,
   checkSkillsPrerequisites: () => checkSkillsPrerequisites,
@@ -29978,6 +29982,33 @@ function checkConfig(config, configPath) {
   });
   return results;
 }
+function checkUserDeclaredMcps(name, agentConfig, config, renderedMcpServers) {
+  const resolved = resolveAgentConfig(config.defaults, config.profiles, agentConfig);
+  const declaredMcp = resolved.mcp_servers ?? {};
+  const declaredKeys = Object.entries(declaredMcp).filter(([, v]) => v !== false).map(([k]) => k);
+  const renderedKeys = Object.keys(renderedMcpServers);
+  const missing = declaredKeys.filter((k) => !renderedKeys.includes(k));
+  if (declaredKeys.length === 0) {
+    return {
+      name: `${name}: user-declared MCPs`,
+      status: "skip",
+      detail: "no user-declared mcp_servers in switchroom.yaml"
+    };
+  }
+  if (missing.length === 0) {
+    return {
+      name: `${name}: user-declared MCPs`,
+      status: "ok",
+      detail: `${declaredKeys.length} declared, all in .mcp.json (${declaredKeys.join(", ")})`
+    };
+  }
+  return {
+    name: `${name}: user-declared MCPs`,
+    status: "warn",
+    detail: `${missing.length}/${declaredKeys.length} declared but missing from .mcp.json: ${missing.join(", ")}`,
+    fix: `Run \`switchroom agent reconcile ${name} --restart\`. If the entry still doesn't appear, check switchroom.yaml shape (defaults.mcp_servers.<key> or agents.${name}.mcp_servers.<key>).`
+  };
+}
 function checkLegacyState() {
   const results = [];
   const h = process.env.HOME ?? "/root";
@@ -30739,6 +30770,7 @@ function checkAgents(config, configPath) {
               detail: memoryEnabled ? "switchroom-telegram + hindsight" : "switchroom-telegram"
             });
           }
+          results.push(checkUserDeclaredMcps(name, agentConfig, config, mcp.mcpServers ?? {}));
         } catch (err) {
           results.push({
             name: `${name}: .mcp.json`,
@@ -31354,6 +31386,7 @@ var init_doctor = __esm(() => {
   init_doctor_status();
   init_vault();
   init_loader();
+  init_merge();
   init_paths();
   init_helpers();
   init_lifecycle();
@@ -47711,8 +47744,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.36";
-var COMMIT_SHA = "73e8bb05";
+var VERSION = "0.13.38";
+var COMMIT_SHA = "faca4736";
 
 // src/cli/agent.ts
 init_source();
@@ -49460,6 +49493,14 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
         mcpServers[gdrive.key] = gdrive.value;
       }
     }
+    if (agentConfig.mcp_servers) {
+      const filtered = filterMcpServers(agentConfig.mcp_servers);
+      if (filtered) {
+        for (const [key, value] of Object.entries(filtered)) {
+          mcpServers[key] = value;
+        }
+      }
+    }
     writeIfChanged(mcpJsonPath, () => JSON.stringify({ mcpServers }, null, 2) + `
 `, created, skipped, 384);
     mcpServerKeysToTrust = Object.keys(mcpServers);
@@ -50504,6 +50545,14 @@ ${body}
         mcpServers[gdrive.key] = gdrive.value;
       }
     }
+    if (agentConfig.mcp_servers) {
+      const filtered = filterMcpServers(agentConfig.mcp_servers);
+      if (filtered) {
+        for (const [key, value] of Object.entries(filtered)) {
+          mcpServers[key] = value;
+        }
+      }
+    }
     const mcpJson = { mcpServers };
     const after = JSON.stringify(mcpJson, null, 2) + `
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.36",
+  "version": "0.13.38",
   "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/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

@@ -48305,6 +48305,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 +48331,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 +48349,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 +48383,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 +48722,10 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.13.36";
-var COMMIT_SHA = "73e8bb05";
-var COMMIT_DATE = "2026-05-25T03:53:49Z";
-var LATEST_PR = 1785;
+var VERSION = "0.13.38";
+var COMMIT_SHA = "faca4736";
+var COMMIT_DATE = "2026-05-25T06:37:08Z";
+var LATEST_PR = 1795;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -50838,14 +50889,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 +52189,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/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>')
+  })
 })