@llblab/pi-telegram 0.24.2 → 0.24.4

package/lib/bus-follower.ts

@@ -841,7 +841,9 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
   };
 }
 
-export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowerRegistrationState {
+export function createTelegramBusFollowerRegistrationState(
+  options: { onAvailabilityChanged?: () => void } = {},
+): TelegramBusFollowerRegistrationState {
   let registered = false;
   let target: TelegramTarget | undefined;
   let slot: string | undefined;
@@ -861,11 +863,13 @@ export function createTelegramBusFollowerRegistrationState(): TelegramBusFollowe
       ).sort();
     },
     setRegistered: (next, nextTarget, metadata) => {
+      const availabilityChanged = registered !== next;
       registered = next;
       target = next ? (nextTarget ? { ...nextTarget } : undefined) : undefined;
       slot = next ? metadata?.slot : undefined;
       threadName = next ? metadata?.threadName : undefined;
       generation = next ? metadata?.generation : undefined;
+      if (availabilityChanged) options.onAvailabilityChanged?.();
     },
   };
 }

package/lib/config.ts

@@ -87,6 +87,10 @@ export interface TelegramConfig {
     sendTranscript?: boolean;
   };
   time?: TelegramTimeConfig;
+  threads?: {
+    /** Delete this instance's bound Telegram thread on graceful Pi quit. */
+    automaticCleanup?: boolean;
+  };
   /** Canonical bot/session profiles, including profiles.default. */
   profiles?: Record<string, TelegramBotProfile>;
 }
@@ -140,6 +144,7 @@ export interface TelegramConfigStore {
   getOutboundHandlers: () => TelegramOutboundHandlerConfig[] | undefined;
   setAllowedUserId: (userId: number) => void;
   load: () => Promise<void>;
+  didLastLoadRecoverInvalidConfig: () => boolean;
   persist: (config?: TelegramConfig) => Promise<void>;
 }
 
@@ -188,6 +193,7 @@ type TelegramMutableConfigStore = Pick<
   "get" | "set" | "persist"
 > & {
   load?: () => Promise<void>;
+  didLastLoadRecoverInvalidConfig?: () => boolean;
 };
 
 function isEmptyTelegramConfig(config: TelegramConfig): boolean {
@@ -498,6 +504,7 @@ export function createTelegramConfigStore(
   let mutationVersion = 0;
   let persistQueue: Promise<void> = Promise.resolve();
   let activeProfileName: string | undefined;
+  let lastLoadRecoveredInvalidConfig = false;
   const agentDir = options.agentDir ?? resolveAgentDir();
   const configPath = options.configPath ?? getConfigPath();
   const getEffectiveConfig = () =>
@@ -556,8 +563,10 @@ export function createTelegramConfigStore(
       setEffectiveConfig(nextConfig);
     },
     load: async () => {
+      lastLoadRecoveredInvalidConfig = false;
       const loadedConfig = await readTelegramConfig(configPath, {
         onInvalidConfig: (recovery) => {
+          lastLoadRecoveredInvalidConfig = true;
           options.recordRuntimeEvent?.("config", recovery.error, {
             phase: "load",
             configPath: recovery.configPath,
@@ -593,6 +602,7 @@ export function createTelegramConfigStore(
       persistedConfig = cloneTelegramConfig(config);
       mutationVersion += 1;
     },
+    didLastLoadRecoverInvalidConfig: () => lastLoadRecoveredInvalidConfig,
     persist: (nextConfig = getEffectiveConfig()) => {
       const profileName = activeProfileName;
       const desiredConfig = storeTelegramEffectiveConfig(
@@ -862,6 +872,41 @@ export function createTelegramProactivePushTargetGetter(deps: {
   };
 }
 
+export function createTelegramAutomaticThreadCleanupChecker(
+  configStore: Pick<TelegramConfigStore, "get">,
+): () => boolean {
+  return () => configStore.get().threads?.automaticCleanup ?? true;
+}
+
+export function createTelegramAutomaticThreadCleanupResolver(
+  configStore: TelegramMutableConfigStore,
+): () => Promise<boolean> {
+  return async () => {
+    await loadLatestTelegramConfig(configStore);
+    if (configStore.didLastLoadRecoverInvalidConfig?.()) {
+      throw new Error(
+        "Automatic thread cleanup setting is unavailable after invalid Telegram config recovery.",
+      );
+    }
+    return createTelegramAutomaticThreadCleanupChecker(configStore)();
+  };
+}
+
+export function createTelegramAutomaticThreadCleanupSetter(
+  configStore: TelegramMutableConfigStore,
+): (enabled: boolean) => Promise<void> {
+  return async (enabled) => {
+    await loadLatestTelegramConfig(configStore);
+    const current = configStore.get();
+    const config = {
+      ...current,
+      threads: { ...current.threads, automaticCleanup: enabled },
+    };
+    configStore.set(config);
+    await configStore.persist(config);
+  };
+}
+
 export function createTelegramConfigControls(
   configStore: TelegramMutableConfigStore,
 ) {
@@ -880,6 +925,12 @@ export function createTelegramConfigControls(
     setVoiceReplyMode: createTelegramVoiceReplyModeSetter(configStore),
     getTimeInjectionMode: createTelegramTimeInjectionModeGetter(configStore),
     setTimeInjectionMode: createTelegramTimeInjectionModeSetter(configStore),
+    isAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupChecker(configStore),
+    resolveAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupResolver(configStore),
+    setAutomaticThreadCleanupEnabled:
+      createTelegramAutomaticThreadCleanupSetter(configStore),
   };
 }
 

package/lib/locks.ts

@@ -1139,6 +1139,7 @@ export interface TelegramLockedPollingRuntimeDeps<
     owner: TelegramLockEntry,
   ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
+  onTransportAvailabilityChanged?: () => void;
   updateStatus: (ctx: TContext) => void;
   recordRuntimeEvent?: (
     category: string,
@@ -1189,6 +1190,7 @@ export function createTelegramLockedPollingRuntime<
   const stopAfterOwnershipLoss = () => {
     if (ownershipStop) return;
     stopOwnershipWatcher();
+    deps.onTransportAvailabilityChanged?.();
     ownershipStop = deps
       .stopPolling()
       .catch((error) =>
@@ -1242,12 +1244,14 @@ export function createTelegramLockedPollingRuntime<
         });
       }
       deps.lock.release();
+      deps.onTransportAvailabilityChanged?.();
       throw error;
     }
     if (deps.lock.owns(ctx)) return true;
     stopOwnershipWatcher();
     if (ownershipStop) await ownershipStop;
     await deps.stopPolling();
+    deps.onTransportAvailabilityChanged?.();
     return false;
   };
   const canStartPolling = (ctx: TContext): boolean =>
@@ -1337,6 +1341,7 @@ export function createTelegramLockedPollingRuntime<
           message: "Telegram leadership changed during polling startup.",
         };
       }
+      deps.onTransportAvailabilityChanged?.();
       deps.updateStatus(ctx);
       const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
       return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
@@ -1344,6 +1349,7 @@ export function createTelegramLockedPollingRuntime<
     stop: async () => {
       await suspendPolling();
       const state = deps.lock.release();
+      deps.onTransportAvailabilityChanged?.();
       if (state.kind === "active-elsewhere") {
         return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
       }
@@ -1391,6 +1397,7 @@ export function createTelegramLockedPollingRuntime<
         if (generation !== sessionAutoStartGeneration) return;
         if (!(await runOwnedPollingStart(ctx, {}))) return;
         if (generation !== sessionAutoStartGeneration) return;
+        deps.onTransportAvailabilityChanged?.();
         deps.updateStatus(ctx);
         deps.recordRuntimeEvent?.("lock", "Telegram auto-start completed", {
           phase: "auto-start-complete",

package/lib/menu-settings.ts

@@ -26,6 +26,7 @@ export interface TelegramSettingsStateDeps {
   getTimeInjectionMode: () => TelegramTimeMode;
   getVoiceReplyMode: () => TelegramVoiceReplyMode;
   isVoiceReplyModeConfigured: () => boolean;
+  isAutomaticThreadCleanupEnabled: () => boolean;
 }
 
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
@@ -38,6 +39,7 @@ export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps
     mode: TelegramVoiceReplyMode | undefined,
   ) => Promise<void>;
   setTimeInjectionMode: (mode: TelegramTimeMode) => Promise<void>;
+  setAutomaticThreadCleanupEnabled: (enabled: boolean) => Promise<void>;
 }
 
 export interface TelegramSettingsMenuOpenDeps<
@@ -99,6 +101,7 @@ export interface TelegramSettingsMenuRuntimeDeps<
   TContext,
   TModel extends MenuModel = MenuModel,
 > extends TelegramSettingsMutationDeps {
+  reloadConfig?: () => Promise<void>;
   getModelMenuState: (
     chatId: number,
     ctx: TContext,
@@ -129,6 +132,8 @@ export interface TelegramSettingsMenuRuntimeDeps<
 }
 
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
+export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
+  "<b>🧹 Automatic thread cleanup:</b>";
 export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
 export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
 export const ASSISTANT_RENDERING_SETTINGS_TITLE =
@@ -158,6 +163,19 @@ export function buildTelegramSettingsMenuText(): string {
   return SETTINGS_MENU_TITLE;
 }
 
+export function buildAutomaticThreadCleanupSettingsText(
+  enabled: boolean,
+): string {
+  return [
+    `${AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
+    "",
+    "Delete this Pi instance's Telegram tab when Pi quits normally.",
+    "",
+    "<code>-</code> <code>on</code> (default): delete the bound thread and release Telegram authority on graceful quit.",
+    "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual /telegram-disconnect still confirms and deletes it.",
+  ].join("\n");
+}
+
 export function buildProactivePushSettingsText(
   proactivePushEnabled: boolean,
 ): string {
@@ -236,6 +254,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
     TelegramTimeMode | TelegramSectionRegistry,
   sectionRegistryOrVoiceReplyModeConfigured?: TelegramSectionRegistry | boolean,
   voiceReplyModeConfigured = true,
+  automaticThreadCleanupEnabled = true,
 ): TelegramSettingsMenuReplyMarkup {
   const hasRenderingMode =
     assistantRenderingModeOrVoiceReplyMode === "rich" ||
@@ -269,6 +288,12 @@ export function buildTelegramSettingsMenuReplyMarkup(
     }
   }
   rows.push(
+    [
+      {
+        text: `🧹 Auto thread cleanup: ${automaticThreadCleanupEnabled ? "on" : "off"}`,
+        callback_data: "settings:open:automatic-thread-cleanup",
+      },
+    ],
     [
       {
         text: `👄 Voice reply: ${getTelegramSettingsStateValueLabel(
@@ -328,6 +353,7 @@ export async function openTelegramSettingsMenu<
       deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
+      deps.isAutomaticThreadCleanupEnabled(),
     ),
   );
   if (messageId === undefined) return;
@@ -336,6 +362,26 @@ export async function openTelegramSettingsMenu<
   deps.storeModelMenuState(state);
 }
 
+export function buildAutomaticThreadCleanupSettingsReplyMarkup(
+  enabled: boolean,
+): TelegramSettingsMenuReplyMarkup {
+  return {
+    inline_keyboard: [
+      [{ text: "⬆️ Back", callback_data: "settings:list" }],
+      [
+        {
+          text: enabled ? "🟢 On" : "⚫️ On",
+          callback_data: "settings:set:automatic-thread-cleanup:on",
+        },
+        {
+          text: enabled ? "⚫️ Off" : "🟡 Off",
+          callback_data: "settings:set:automatic-thread-cleanup:off",
+        },
+      ],
+    ],
+  };
+}
+
 export function buildProactivePushSettingsReplyMarkup(
   proactivePushEnabled: boolean,
 ): TelegramSettingsMenuReplyMarkup {
@@ -443,10 +489,21 @@ export async function updateTelegramSettingsMenuMessage(
       deps.getTimeInjectionMode(),
       sectionRegistry,
       deps.isVoiceReplyModeConfigured(),
+      deps.isAutomaticThreadCleanupEnabled(),
     ),
   );
 }
 
+export async function updateAutomaticThreadCleanupSettingsMessage(
+  deps: TelegramSettingsMenuCallbackDeps,
+): Promise<void> {
+  const enabled = deps.isAutomaticThreadCleanupEnabled();
+  await deps.updateSettingsMessage(
+    buildAutomaticThreadCleanupSettingsText(enabled),
+    buildAutomaticThreadCleanupSettingsReplyMarkup(enabled),
+  );
+}
+
 export async function updateProactivePushSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
@@ -509,6 +566,11 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
+  if (data === "settings:open:automatic-thread-cleanup") {
+    await updateAutomaticThreadCleanupSettingsMessage(deps);
+    await deps.answerCallbackQuery(callbackQueryId);
+    return true;
+  }
   if (data === "settings:open:proactive") {
     await updateProactivePushSettingsMessage(deps);
     await deps.answerCallbackQuery(callbackQueryId);
@@ -598,6 +660,19 @@ export async function handleTelegramSettingsMenuCallbackAction(
       return true;
     }
   }
+  if (
+    data === "settings:set:automatic-thread-cleanup:on" ||
+    data === "settings:set:automatic-thread-cleanup:off"
+  ) {
+    const enabled = data.endsWith(":on");
+    await deps.setAutomaticThreadCleanupEnabled(enabled);
+    await updateAutomaticThreadCleanupSettingsMessage(deps);
+    await deps.answerCallbackQuery(
+      callbackQueryId,
+      `Automatic thread cleanup ${enabled ? "enabled" : "disabled"}`,
+    );
+    return true;
+  }
   if (
     data === "settings:set:proactive:on" ||
     data === "settings:set:proactive:off"
@@ -623,8 +698,9 @@ export function createTelegramSettingsMenuRuntime<
   sectionRegistry?: TelegramSectionRegistry,
 ): TelegramSettingsMenuRuntime<TContext> {
   return {
-    openSettingsMenu: (chatId, _replyToMessageId, ctx) =>
-      openTelegramSettingsMenu(
+    openSettingsMenu: async (chatId, _replyToMessageId, ctx) => {
+      await deps.reloadConfig?.();
+      return openTelegramSettingsMenu(
         {
           getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
           isProactivePushEnabled: deps.isProactivePushEnabled,
@@ -633,6 +709,8 @@ export function createTelegramSettingsMenuRuntime<
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
+          isAutomaticThreadCleanupEnabled:
+            deps.isAutomaticThreadCleanupEnabled,
           sendSettingsMenu: (state, text, replyMarkup) =>
             deps.sendInteractiveMessage(
               state.chatId,
@@ -643,9 +721,11 @@ export function createTelegramSettingsMenuRuntime<
           storeModelMenuState: deps.storeModelMenuState,
         },
         sectionRegistry,
-      ),
-    updateSettingsMenuMessage: (state) =>
-      updateTelegramSettingsMenuMessage(
+      );
+    },
+    updateSettingsMenuMessage: async (state) => {
+      await deps.reloadConfig?.();
+      return updateTelegramSettingsMenuMessage(
         {
           isProactivePushEnabled: deps.isProactivePushEnabled,
           areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
@@ -653,6 +733,8 @@ export function createTelegramSettingsMenuRuntime<
           getVoiceReplyMode: deps.getVoiceReplyMode,
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
+          isAutomaticThreadCleanupEnabled:
+            deps.isAutomaticThreadCleanupEnabled,
           updateSettingsMessage: (text, replyMarkup) =>
             deps.editInteractiveMessage(
               state.chatId,
@@ -663,9 +745,11 @@ export function createTelegramSettingsMenuRuntime<
             ),
         },
         sectionRegistry,
-      ),
+      );
+    },
     handleCallbackQuery: async (query, ctx) => {
       if (!query.data?.startsWith("settings:")) return false;
+      await deps.reloadConfig?.();
       const messageId = query.message?.message_id;
       const chatId = query.message?.chat?.id;
       let state = deps.getStoredModelMenuState(messageId, chatId);
@@ -693,11 +777,15 @@ export function createTelegramSettingsMenuRuntime<
         getVoiceReplyMode: deps.getVoiceReplyMode,
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
+        isAutomaticThreadCleanupEnabled:
+          deps.isAutomaticThreadCleanupEnabled,
         setProactivePushEnabled: deps.setProactivePushEnabled,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setVoiceReplyMode: deps.setVoiceReplyMode,
         setTimeInjectionMode: deps.setTimeInjectionMode,
+        setAutomaticThreadCleanupEnabled:
+          deps.setAutomaticThreadCleanupEnabled,
         updateSettingsMessage: (text, replyMarkup) =>
           deps.editInteractiveMessage(
             state.chatId,

package/lib/outbound-attachments.ts

@@ -10,6 +10,12 @@ import { basename } from "node:path";
 import { Type } from "@sinclair/typebox";
 
 import type { ExtensionAPI } from "./pi.ts";
+import {
+  TELEGRAM_ATTACH_PROMPT_GUIDELINES,
+  TELEGRAM_ATTACH_PROMPT_SNIPPET,
+  TELEGRAM_MESSAGE_PROMPT_GUIDELINES,
+  TELEGRAM_MESSAGE_PROMPT_SNIPPET,
+} from "./prompts.ts";
 import {
   buildTelegramMultipartReplyParameters,
   normalizeTelegramNativeMarkdown,
@@ -432,13 +438,8 @@ export function registerTelegramOutboundAttachmentTool(
     label: "Telegram Attach",
     description:
       "Queue one or more local files for the active Telegram reply, or send them immediately to Telegram when no Telegram turn is active.",
-    promptSnippet:
-      "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.",
-    promptGuidelines: [
-      "When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.",
-      "When a local/TUI user explicitly asks to send a generated file to Telegram, telegram_attach can deliver it to the paired/default Telegram chat even without an active Telegram turn.",
-      "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
-    ],
+    promptSnippet: TELEGRAM_ATTACH_PROMPT_SNIPPET,
+    promptGuidelines: [...TELEGRAM_ATTACH_PROMPT_GUIDELINES],
     parameters: Type.Object({
       paths: Type.Array(
         Type.String({ description: "Local file path to attach" }),
@@ -499,14 +500,8 @@ export function registerTelegramOutboundMessageTool(
     label: "Telegram Message",
     description:
       "Send a Markdown text message directly to the paired/default Telegram chat or an explicit chat_id. Hidden telegram_button comments in the text become attached inline prompt buttons.",
-    promptSnippet:
-      "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.",
-    promptGuidelines: [
-      "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
-      "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
-      "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
-      "Do not use this tool for ordinary Telegram-originated replies; answer normally so the bridge can deliver the active turn reply.",
-    ],
+    promptSnippet: TELEGRAM_MESSAGE_PROMPT_SNIPPET,
+    promptGuidelines: [...TELEGRAM_MESSAGE_PROMPT_GUIDELINES],
     parameters: Type.Object({
       text: Type.String({ description: "Message text to send" }),
       chat_id: Type.Optional(

package/lib/pi.ts

@@ -120,6 +120,8 @@ export interface PiExtensionApiRuntimePorts {
   getCommands: ExtensionAPI["getCommands"];
   getThinkingLevel: ExtensionAPI["getThinkingLevel"];
   setThinkingLevel: ExtensionAPI["setThinkingLevel"];
+  getActiveTools: ExtensionAPI["getActiveTools"];
+  setActiveTools: ExtensionAPI["setActiveTools"];
   setModel: ExtensionAPI["setModel"];
 }
 
@@ -131,6 +133,8 @@ export function createExtensionApiRuntimePorts(
     | "getCommands"
     | "getThinkingLevel"
     | "setThinkingLevel"
+    | "getActiveTools"
+    | "setActiveTools"
     | "setModel"
   >,
 ): PiExtensionApiRuntimePorts {
@@ -141,6 +145,8 @@ export function createExtensionApiRuntimePorts(
     getCommands: () => api.getCommands(),
     getThinkingLevel: () => api.getThinkingLevel(),
     setThinkingLevel: (level) => api.setThinkingLevel(level),
+    getActiveTools: () => api.getActiveTools(),
+    setActiveTools: (names) => api.setActiveTools(names),
     setModel: (model) => api.setModel(model),
   };
 }

package/lib/prompts.ts

@@ -18,6 +18,106 @@ const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
 Telegram turn note: Call \`telegram_help\` if you need the pi-telegram bridge action contract.`;
 
+export const TELEGRAM_ATTACH_PROMPT_SNIPPET =
+  "Queue files for the active Telegram reply; outside Telegram turns, send files directly to Telegram.";
+export const TELEGRAM_ATTACH_PROMPT_GUIDELINES = [
+  "When handling a [telegram] message and the user asked for a file or generated artifact, call telegram_attach with the local path instead of only mentioning the path in text.",
+  "When a local/TUI user explicitly asks to send a generated file to Telegram, telegram_attach can deliver it to the paired/default Telegram chat even without an active Telegram turn.",
+  "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
+] as const;
+export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
+  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
+export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
+  "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
+  "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
+  "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
+  "Do not use this tool for ordinary Telegram-originated replies; answer normally so the bridge can deliver the active turn reply.",
+] as const;
+
+const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
+  "telegram_attach",
+  "telegram_message",
+  "telegram_help",
+]);
+const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(
+  "@llblab/pi-telegram:model-context-suspended-tools",
+);
+
+export interface TelegramModelContextAvailabilityMemory {
+  suspended: boolean;
+  toolNames: Set<string>;
+}
+
+function getTelegramModelContextAvailabilityMemory(): TelegramModelContextAvailabilityMemory {
+  const globals = globalThis as unknown as Record<symbol, unknown>;
+  const existing = globals[TELEGRAM_MODEL_CONTEXT_MEMORY_KEY];
+  if (
+    existing &&
+    typeof existing === "object" &&
+    "toolNames" in existing &&
+    (existing as { toolNames?: unknown }).toolNames instanceof Set
+  ) {
+    return existing as TelegramModelContextAvailabilityMemory;
+  }
+  const memory: TelegramModelContextAvailabilityMemory = {
+    suspended: false,
+    toolNames: new Set<string>(),
+  };
+  globals[TELEGRAM_MODEL_CONTEXT_MEMORY_KEY] = memory;
+  return memory;
+}
+
+export interface TelegramModelContextAvailabilityRuntime {
+  reconcile: () => void;
+}
+
+export function createTelegramModelContextAvailabilityRuntime(deps: {
+  getActiveTools: () => string[];
+  setActiveTools: (names: string[]) => void;
+  isAvailable: () => boolean;
+  canReconcile?: () => boolean;
+  memory?: TelegramModelContextAvailabilityMemory;
+}): TelegramModelContextAvailabilityRuntime {
+  const memory =
+    deps.memory ?? getTelegramModelContextAvailabilityMemory();
+  return {
+    reconcile() {
+      if (deps.canReconcile && !deps.canReconcile()) return;
+      const activeTools = deps.getActiveTools();
+      if (!deps.isAvailable()) {
+        if (!memory.suspended) {
+          memory.toolNames.clear();
+          for (const name of activeTools) {
+            if (TELEGRAM_MODEL_CONTEXT_TOOL_NAMES.has(name)) {
+              memory.toolNames.add(name);
+            }
+          }
+          memory.suspended = true;
+        }
+        const nextTools = activeTools.filter(
+          (name) => !TELEGRAM_MODEL_CONTEXT_TOOL_NAMES.has(name),
+        );
+        if (nextTools.length !== activeTools.length) {
+          deps.setActiveTools(nextTools);
+        }
+        return;
+      }
+      if (!memory.suspended) return;
+      const nextTools = [...activeTools];
+      for (const name of TELEGRAM_MODEL_CONTEXT_TOOL_NAMES) {
+        if (memory.toolNames.has(name) && !nextTools.includes(name)) {
+          nextTools.push(name);
+        }
+      }
+      memory.toolNames.clear();
+      memory.suspended = false;
+      if (nextTools.length !== activeTools.length) {
+        deps.setActiveTools(nextTools);
+      }
+    },
+  };
+}
+
 function buildTelegramHelpText(profileName?: string): string {
   const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
   return `--- TELEGRAM BRIDGE HELP ---
@@ -143,11 +243,25 @@ export function createTelegramBeforeAgentStartHook(
     });
 }
 
+function stripTelegramToolMetadataFromSystemPrompt(
+  systemPrompt: string,
+): string {
+  const telegramLines = new Set([
+    `- telegram_attach: ${TELEGRAM_ATTACH_PROMPT_SNIPPET}`,
+    `- telegram_message: ${TELEGRAM_MESSAGE_PROMPT_SNIPPET}`,
+    ...TELEGRAM_ATTACH_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+    ...TELEGRAM_MESSAGE_PROMPT_GUIDELINES.map((line) => `- ${line}`),
+  ]);
+  return systemPrompt
+    .split("\n")
+    .filter((line) => !telegramLines.has(line))
+    .join("\n");
+}
+
 export interface TelegramProactivePromptHookDeps<TContext> {
   baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
-  isConfigured: () => boolean;
-  isProactivePushEnabled: () => boolean;
-  isCurrentOwner: (ctx: TContext) => boolean;
+  reconcileAvailability?: () => void;
+  isAvailable: (ctx: TContext) => boolean;
 }
 
 export function createTelegramProactiveBeforeAgentStartHook<TContext>(
@@ -158,10 +272,14 @@ export function createTelegramProactiveBeforeAgentStartHook<TContext>(
 ) => Promise<{ systemPrompt: string }> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async (event, ctx) => {
-    if (!deps.isConfigured()) return { systemPrompt: event.systemPrompt };
-    const result = baseHook(event);
-    if (!deps.isProactivePushEnabled()) return result;
-    if (!deps.isCurrentOwner(ctx)) return result;
-    return result;
+    deps.reconcileAvailability?.();
+    if (!deps.isAvailable(ctx)) {
+      return {
+        systemPrompt: stripTelegramToolMetadataFromSystemPrompt(
+          event.systemPrompt,
+        ),
+      };
+    }
+    return baseHook(event);
   };
 }