@llblab/pi-telegram 0.16.3 → 0.16.5

package/AGENTS.md

@@ -7,12 +7,15 @@
 - `Boundary Clarity`: Separate Telegram transport concerns, π integration concerns, rendering behavior, and release/documentation state
 - `Progressive Enhancement + Graceful Degradation`: Prefer behavior that upgrades automatically when richer runtime context exists, but always preserves a useful fallback path when it does not
 - `Runtime Safety`: Prefer queue and rendering behavior that fails predictably over clever behavior that can desynchronize the Telegram bridge from π session state
+- `Mobile Companion Boundary`: `pi-telegram` extends a live Pi session for phone use; it is not a remote terminal, PTY supervisor, or process launcher. Do not add terminal-control tricks to make Telegram pretend to be the TUI.
 - `Pi-Native Extensibility`: `pi-telegram` should inherit π's own extension philosophy. It is not only a Telegram adapter; it should become a small, convenient, composable Telegram shell for π extensions, where new capabilities plug into stable contracts instead of forking polling, transport, or menu ownership.
 
 ## 1. Concept
 
 `pi-telegram` is a Telegram runtime adapter for π: a session-local operator console that turns a private Telegram DM into a runtime surface for prompt intake, streaming previews, queue management, model/thinking/settings controls, inbound/outbound handler pipelines, voice/buttons, artifacts, and extension callback interop. Treat it as a Telegram membrane around π, not a narrow message pipe.
 
+The core product loop is mobile continuation: start or supervise work in the terminal, then continue from Telegram while away from the keyboard. Telegram controls should be a safe extension-facing subset of the live session, not a replacement for Pi's interactive TUI.
+
 ## 2. Identity & Naming Contract
 
 - `Telegram turn`: One unit of Telegram input processed by π; this may represent one message or a coalesced media group
@@ -67,6 +70,7 @@
 - Command/menu emoji are fixed UI adornments owned by the `commands` map; do not add a persisted emoji toggle or Settings menu until there is a real setting to own
 - Telegram `reply_to_message` context is prompt-only and must not affect slash-command parsing
 - Long-lived timers, pollers, watchers, and deferred queue dispatch must be session-bound and avoid stale live π contexts after session replacement
+- Do not add Telegram commands that imitate Pi interactive session replacement, navigation, or TUI rendering through private internals, ANSI terminal clearing, raw TTY injection, or a shadow `pi` subprocess. Features such as a real Telegram `/new` require a public Pi API that runs the same session-replacement path as the terminal command.
 - In-flight `/model` switching is limited to Telegram-owned active turns; if a tool call is active, abort is delayed until the tool finishes
 
 ## 5.3 Telegram Delivery Semantics
@@ -75,6 +79,7 @@
 - Real code blocks must stay literal and escaped
 - `telegram_attach` is the canonical outbound file-delivery path for Telegram-originated requests; outside active Telegram turns it may send immediately to the paired/default chat for explicit local/TUI delivery requests only when this π instance owns `/telegram-connect`. `telegram_message` is the first-class direct Telegram Markdown text tool for local/TUI prompts and is also gated by `/telegram-connect`; neither direct tool replaces normal active-turn replies. It reuses top-level `telegram_button` comments for inline buttons; buttons must be attached to a text message, never sent as standalone actions
 - Telegram delivery strips top-level HTML comments from preview/final text; column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks are special outbound comments handled after `agent_end` without requiring agent-side transport tool calls, while comments inside code, quotes, lists, or indented examples stay literal
+- Telegram prompt guidance is layered: unconfigured sessions receive no bridge suffix, local/TUI prompts receive only explicit direct-delivery guidance, and Telegram-originated turns receive the full inbound/phone-width/output-action contract
 - `telegram_voice` and `telegram_button` are not π tools; keep prompts/docs explicit that agents should author markup while voice synthesis provider extensions own TTS/OGG conversion, and pi-telegram owns button routing plus Telegram delivery
 - Voice reply policy and prompt context are owned by pi-telegram's `telegram.json` `voice.replyMode`: missing/invalid config behaves as `manual` but does not add a `[voice]` prompt-context block; only an explicit valid `voice.replyMode` renders context. Render a single voice field as `[voice] reply mode: manual|mirror|always`, and render multiple fields as a `[voice]` list; place voice context after `[outputs]` when handler output exists, otherwise after `[attachments]`; provider prompt contributions are optional provider-specific additions, not the default policy channel
 - Optional `telegram.json` `time` may add `[time] YYYY-MM-DD HH:mm:ss <timezone>` to Telegram-originated prompts for wall-clock context. It is hidden by default, uses `time.injectionMode` values `hidden|always|interval`, stores `time.interval` in milliseconds, uses the system timezone, and should render last after `[attachments]`, `[outputs]`, and `[voice]` sections. The Settings row `🕒 Time injection: hidden|always|interval` controls `time.injectionMode` only.

package/BACKLOG.md

@@ -1,3 +1,6 @@
 # Project Backlog
 
-No open work.
+- [ ] Track a public Pi session-replacement hook before adding Telegram `/new`.
+  - Context: `pi-telegram` is an extension/mobile companion, not a PTY supervisor. A soft `/new` that mutates session internals or filters context without TUI/runtime parity breaks the product boundary.
+  - Requirement: only add Telegram `/new` when Pi exposes a safe public API that invokes the same session-replacement path as terminal `/new`, including lifecycle, active-run handling, and TUI rerender semantics.
+  - Rejected for this extension: raw TTY injection, ANSI terminal clearing, private TUI container mutation, or running a shadow `pi` subprocess to control the current session.

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+## 0.16.5: Context-Aware Prompt Guidance Hotfix
+
+- `[Prompt Guidance]` Made before-agent-start Telegram guidance context-aware: unconfigured sessions receive no bridge suffix, local/TUI prompts receive only explicit direct-delivery guidance, and Telegram-originated turns keep the full inbound, phone-width, voice, and button contract. Impact: ordinary local replies no longer get raw Telegram action-comment syntax unless the current turn actually comes from Telegram.
+- `[Docs]` Recorded the product boundary that `pi-telegram` is a mobile companion for a live Pi session, not a remote terminal, PTY supervisor, or process launcher. Telegram controls should stay within Pi's extension-facing APIs; true session replacement such as Telegram `/new` should wait for a public Pi hook that preserves interactive runtime and TUI semantics.
+
+## 0.16.4: Follow-Up And Runtime Mode Hotfix
+
+- `[Runtime]` Feature-detect Pi `ctx.mode` and keep `print`/`json` runs passive by blocking polling start/resume in those modes. Impact: CLI/headless sessions can finish local work without inheriting Telegram polling, while `tui`/`rpc` and older Pi runtimes keep existing behavior.
+- `[Queue]` Forward queued Telegram prompts and unknown callback fallbacks to Pi with explicit `followUp` delivery semantics. Impact: Telegram input keeps the existing non-steering queue contract even when Pi's native streaming-message API requires an explicit busy-run policy.
+
 ## 0.16.3: Ownership And Shutdown Hotfix
 
 - `[Ownership]` Lock-gated proactive local/headless final-result push so only the current `/telegram-connect` owner can send non-Telegram agent-end replies to the paired chat, while accepted Telegram turns and queued work still finalize session-locally after polling ownership moves away. Impact: child/headless/non-owner instances no longer leak unrelated local results into Telegram.
@@ -18,7 +30,7 @@
 
 ## 0.16.0: Telegram Extension Commands
 
-- `[API]` Added `registerTelegramCommand()` on the public `/commands` subpath so companion extensions can explicitly provide Telegram-native slash commands without adding workflow-specific commands to core. Built-in bridge commands stay reserved, extension command names must be Bot API safe, duplicate extension names are rejected, commands stay hidden unless `showInMenu` is enabled, visible commands must provide an emoji used in `/start` help and Bot API descriptions, extension-command descriptions are shown in `/start`, visible extension commands are inserted after `/compact` before queue-control commands, prompt-template commands remain separated in `/start`, handler failures are isolated with runtime diagnostics, and routing precedence is built-ins → extension commands → prompt-template aliases. Impact: commands such as fresh-session controls can live in companion extensions while `pi-telegram` remains a lightweight Telegram shell.
+- `[API]` Added `registerTelegramCommand()` on the public `/commands` subpath so companion extensions can explicitly provide Telegram-native slash commands without adding workflow-specific commands to core. Built-in bridge commands stay reserved, extension command names must be Bot API safe, duplicate extension names are rejected, commands stay hidden unless `showInMenu` is enabled, visible commands must provide an emoji used in `/start` help and Bot API descriptions, extension-command descriptions are shown in `/start`, visible extension commands are inserted after `/compact` before queue-control commands, prompt-template commands remain separated in `/start`, handler failures are isolated with runtime diagnostics, and routing precedence is built-ins → extension commands → prompt-template aliases. Impact: workflow-specific controls can live in companion extensions while `pi-telegram` remains a lightweight Telegram shell.
 
 ## 0.15.1: Typing Keepalive Cadence
 

package/README.md

@@ -6,6 +6,8 @@
 
 `pi-telegram` turns a private Telegram DM into a session-local operator console for π. It admits work, preserves context, streams readable replies, keeps busy sessions usable through queues, lets other extensions share one bot, and turns assistant-authored intent into native Telegram artifacts. It is also a voice-provider platform: companion extensions can supply Telegram transcription and synthesis providers while `pi-telegram` keeps ownership of transport, queueing, and reply policy.
 
+The product shape is a mobile companion for a live Pi session: start work in the terminal, then continue from Telegram on the couch or outside. It is not a remote terminal, PTY supervisor, or process launcher, and it intentionally avoids pretending to own Pi's interactive TUI.
+
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
 ## Install
@@ -47,7 +49,7 @@ Paste your bot token when prompted. If a bot token is already saved in `~/.pi/ag
 /telegram-connect
 ```
 
-The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, inherited child sessions do not start polling unless they take ownership, and `/new` plus same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
+The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, inherited child sessions do not start polling unless they take ownership, and same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
 
 ### 4. Pair your Telegram account
 
@@ -72,6 +74,7 @@ Once paired, chat with your bot in Telegram. Text, images, files, replies, edits
 
 What it feels like:
 
+- Start work in the terminal, walk away, and keep supervising the same live π session from Telegram.
 - Open `/start` and get a Telegram control panel for the running π session: status, prompt templates, model, thinking, settings, and queue.
 - Fire off three tasks while π is busy. They become visible queue items instead of terminal noise.
 - Open Queue from the menu, inspect waiting work, delete stale prompts, or move important work forward.
@@ -82,7 +85,7 @@ What it feels like:
 
 ### Telegram controls
 
-Use these inside the Telegram DM with your bot. The main entrypoint is `/start`: it opens the operator menu and exposes many of the important agent controls that normally live in the CLI, adapted for Telegram.
+Use these inside the Telegram DM with your bot. The main entrypoint is `/start`: it opens the operator menu and exposes many of the important agent controls that can be safely adapted through Pi's extension APIs. The bot does not forward arbitrary terminal slash commands or emulate TUI-only session controls.
 
 - **`/start`**: Pair the first Telegram user when needed, register bot commands, and open the inline application menu with command help, prompt-template commands, status rows, model controls, thinking controls, settings, and queue controls.
 - **`/compact`**: Ask for inline confirmation, then start session compaction when the session is idle; Telegram shows the native typing indicator while manual or automatic compaction is running.
@@ -170,6 +173,8 @@ A practical voice setup is simple: Telegram `.ogg` arrives, STT runs locally or
 
 Assistant replies can include hidden outbound blocks. `telegram_voice` and `telegram_button` are not π tools; they are assistant-authored HTML comments that the adapter removes from Telegram text and handles after `agent_end`. Recognized blocks must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples. Do not use JSON button specs, inline comments after visible text, or standalone button tool calls; write normal Markdown plus hidden comments, and add visible parent text if buttons would otherwise be the only output.
 
+Prompt guidance is context-aware: unconfigured sessions receive no Telegram suffix, local/TUI prompts only get explicit direct-delivery guidance, and Telegram-originated turns get the full phone-width output and action-comment contract.
+
 ```md
 Full technical answer stays readable as text.
 
@@ -209,7 +214,7 @@ Unknown inline-button callbacks are forwarded to π as `[callback] <data>` when
 
 ### Extension Sections
 
-Ordinary pi extensions can register Telegram-native slash commands, structured UI sections, and compact status lines without owning a second polling loop. Slash commands use explicit opt-in registration from `@llblab/pi-telegram/commands`, so workflow-specific commands such as a fresh-session control can live in companion extensions instead of expanding the core bridge command set. UI sections appear in the main Telegram menu and Settings submenu, while status lines allow widgets such as quota indicators to appear beside Status, Usage, Cost, and Context only when relevant to the active model. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
+Ordinary pi extensions can register Telegram-native slash commands, structured UI sections, and compact status lines without owning a second polling loop. Slash commands use explicit opt-in registration from `@llblab/pi-telegram/commands`, so workflow-specific commands can live in companion extensions instead of expanding the core bridge command set. UI sections appear in the main Telegram menu and Settings submenu, while status lines allow widgets such as quota indicators to appear beside Status, Usage, Cost, and Context only when relevant to the active model. Each section gets a narrow typed context with `edit`, `open`, `enqueuePrompt`, `answerCallback`, and `callbackData()` — enough to build interactive Telegram-native surfaces while `pi-telegram` owns transport, callback routing, navigation hierarchy, and diagnostics.
 
 Import `registerTelegramSection()` from `@llblab/pi-telegram/sections` and return a disposer on shutdown. Sections can send interactive messages directly into the chat via `ctx.open()` — confirmation dialogs, approve/deny gates, and multi-step forms live outside the menu hierarchy while callbacks route through the same typed handler. See [`@llblab/pi-telegram-extension-demo`](https://github.com/llblab/pi-telegram-extension-demo) for a working reference and the [Extension Sections Standard](./docs/sections.md) for the full contract.
 

package/docs/architecture.md

@@ -9,6 +9,8 @@
 - Stream previews and deliver final π responses back to Telegram.
 - Provide Telegram-native controls for queueing, model/thinking/settings menus, compaction, abort/stop, prompt templates, reactions, and outbound artifacts.
 
+The bridge is a mobile companion for a live Pi session, not a remote terminal. It should let an operator start work in the TUI and continue supervising from Telegram, while staying inside Pi's extension-facing contracts.
+
 This document is the architectural map. Focused behavior standards live in sibling docs:
 
 - [Public API](./public-api.md) — stable commands, config, package entrypoints, assistant markup, extension APIs, and compatibility boundaries.
@@ -23,6 +25,17 @@ This document is the architectural map. Focused behavior standards live in sibli
 
 `index.ts` is the only composition root. It wires live π ports, Telegram Bot API ports, session-local stores, lifecycle hooks, and domain runtimes. Reusable logic lives in flat `/lib/*.ts` domain modules rather than a deep local module tree.
 
+### Extension Boundary Vs Supervisor Control
+
+`pi-telegram` runs inside the current Pi process as an extension. That gives it safe access to public extension APIs such as aborting work, compacting, sending follow-up prompts, observing lifecycle events, and rendering Telegram-native controls. It does not own the terminal, the interactive-mode chat transcript, or the process lifecycle.
+
+Keep this boundary explicit:
+
+- Do not use raw TTY injection, ANSI terminal clearing, private TUI container mutation, or a shadow `pi` subprocess to simulate interactive commands.
+- Do not treat Telegram as a generic remote shell for every Pi slash command.
+- Commands that require interactive session replacement or TUI rerendering, such as a true Telegram `/new`, need a public Pi API that invokes the same runtime path as the terminal command.
+- A separate PTY supervisor or daemon could choose to own those risks, but that would be a different product mode rather than this extension's runtime contract.
+
 The repository uses a **Flat Domain DAG**:
 
 - Local imports must form a directed acyclic graph.
@@ -88,6 +101,7 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Polling ownership l
 - `/telegram-connect` acquires or moves singleton polling ownership before polling starts.
 - `/telegram-disconnect` stops polling and releases ownership.
 - Session start resumes polling only when the existing lock already points at the current `pid`/`cwd`, or when a stale same-`cwd` lock can be safely replaced after process restart.
+- Pi `print`/`json` run modes stay passive: they do not start or resume Telegram polling even if a lock is present. Older Pi runtimes without `ctx.mode` keep the previous compatibility behavior.
 - Inherited child sessions that see the same `telegram.json` but do not own the `pid`/`cwd` lock must not auto-start polling or call `getUpdates` unless the operator force-takes ownership.
 - Session replacement suspends polling/watchers without releasing ownership so the next session-start hook in the same process can resume.
 - Live polling owners require explicit takeover confirmation.
@@ -140,7 +154,7 @@ Dispatch requires:
 
 A dispatched prompt remains queued until `agent_start` consumes it. This keeps the active Telegram turn bound for previews, attachments, aborts, and final replies.
 
-Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere.
+Post-agent-end queue dispatch uses a session-bound deferred dispatcher. It is activated on session start, clears timers on shutdown, and skips callbacks from older generations before touching `ExtensionContext`. Dispatch stays session-bound after polling ownership moves elsewhere. When a queued Telegram prompt is forwarded into Pi, it uses Pi's explicit `followUp` delivery option so Telegram input preserves the existing non-steering queue contract even if Pi is still settling active work.
 
 ### Controls And Menus
 
@@ -229,7 +243,7 @@ Queue reactions are shortcut controls for waiting turns. Promotion reactions (`
 
 When proactive push is enabled and this instance owns the Telegram lock, successful local non-Telegram final replies are sent to the paired chat. Non-owners skip proactive delivery and record a runtime diagnostic. Local prompt text is not mirrored because the bot does not own terminal user messages.
 
-Telegram prompt guidance asks assistants to keep dense mobile-visible text around 37 display cells where possible, because emoji and wide Unicode make raw character counts misleading.
+Telegram prompt guidance is context-aware. Unconfigured sessions receive no bridge suffix. Local/TUI prompts receive only explicit direct-delivery guidance so ordinary terminal replies do not learn raw Telegram action-comment syntax. Telegram-originated turns receive the full inbound context, phone-width output, and native action contract, including the 37-display-cell mobile readability hint.
 
 ## In-Flight Model Switching
 

package/docs/outbound.md

@@ -132,12 +132,14 @@ Buttons are built in and do not need a command template because they are pure Te
 
 ## Prompt Contract
 
-The extension injects Telegram-specific system prompt guidance so agents know the fast path:
+The extension injects prompt guidance by context:
 
-- Write the full technical answer as normal Markdown.
+- If no bot token is configured, no Telegram bridge suffix is injected.
+- For ordinary local/TUI prompts, the agent only sees explicit direct-delivery guidance: use `telegram_attach` or `telegram_message` when the user asks to send something to Telegram, and otherwise answer locally as normal.
+- For Telegram-originated turns, write the full technical answer as normal Markdown.
 - Add `telegram_voice` when a Telegram-native voice message is useful; use body text, `text="..."`, or colon shorthand for the text to synthesize. A companion summary is optional, no specific summary format is required.
 - Add `telegram_button: ...` when label equals prompt, `telegram_button label="..." prompt="..."` for one-line prompts, or `telegram_button label="..."` with a body for multiline prompts. If the reply contains only button/voice comment blocks, add a short visible marker (for example `Choose one:`) before them so Telegram always has a visible parent message for attachment.
 - For ordinary Telegram-turn replies, do not call transport tools for voice or buttons; the bridge owns delivery, while registered voice synthesis providers own TTS and OGG/Opus conversion. For explicit local/TUI direct sends, `telegram_message` may include top-level `telegram_button` comments in its Markdown text because those buttons are attached to that text message.
 - Never send buttons without visible parent text. If the answer would contain only hidden comments, add a compact line such as `Choose one:` first.
 
-This keeps the agent focused on semantics and lets the bridge handle low-latency Telegram adaptation.
+This keeps the agent focused on semantics, prevents Telegram action syntax from leaking into normal local replies, and lets the bridge handle low-latency Telegram adaptation.

package/docs/public-api.md

@@ -53,6 +53,8 @@ Stable commands inside the paired Telegram DM:
 
 Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings`.
 
+This command surface is a mobile companion subset, not a raw terminal-command bridge. Commands that depend on Pi's interactive runtime owning session replacement, TUI transcript clearing, or arbitrary slash-command dispatch stay out of the stable Telegram API unless Pi exposes a safe public extension hook for them.
+
 ### Tools and assistant-authored actions
 
 - `telegram_attach(paths, chat_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; outside Telegram turns it sends files directly to the paired/default chat or explicit `chat_id` when this π instance owns `/telegram-connect`.
@@ -60,6 +62,8 @@ Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `
 - `telegram_voice` hidden comments request Telegram-native voice delivery.
 - `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit JSON button specs or standalone button actions.
 
+Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
+
 See [Outbound Handlers](./outbound.md) for exact markup forms.
 
 ## Configuration API
@@ -143,12 +147,12 @@ Import from `@llblab/pi-telegram/commands`. This registers Telegram slash comman
 
 ```ts
 const off = registerTelegramCommand({
-  name: "new",
-  description: "Start fresh",
+  name: "review",
+  description: "Review queued work",
   showInMenu: true,
-  emoji: "🆕",
+  emoji: "🧩",
   handler: async (ctx) => {
-    await ctx.reply("Starting a fresh session is handled by my extension.");
+    await ctx.enqueuePrompt(`Review this work: ${ctx.args}`);
   },
 });
 ```

package/index.ts

@@ -386,6 +386,8 @@ export default function (pi: Pi.ExtensionAPI) {
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
     hasBotToken: configStore.hasBotToken,
+    canStartPolling: Pi.canStartPollingInExtensionContext,
+    formatStartBlockedMessage: Pi.formatPollingStartBlockedByRunMode,
     startPolling: pollingRuntime.start,
     stopPolling: pollingRuntime.stop,
     updateStatus,

package/lib/bindings.ts

@@ -113,7 +113,10 @@ interface TelegramLifecycleBindingDeps {
     Lifecycle.TelegramLifecycleRegistrationDeps,
     "onSessionStart" | "onSessionShutdown" | "onModelSelect"
   >;
-  configStore: Pick<Config.TelegramConfigStore, "getOutboundHandlers">;
+  configStore: Pick<
+    Config.TelegramConfigStore,
+    "getOutboundHandlers" | "hasBotToken"
+  >;
   abort: Runtime.TelegramRuntimeAbortPort;
   typing: Runtime.TelegramRuntimeTypingPort;
   lifecycle: Runtime.TelegramRuntimeLifecyclePort;
@@ -317,6 +320,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     onSessionCompact: compactionObserver.onSessionCompact,
     onAgentStart: agentStartWithDedupReset,
     onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
+      isConfigured: configStore.hasBotToken,
       isProactivePushEnabled,
       isCurrentOwner: lockOwnershipGuard.ownsContext,
     }),

package/lib/locks.ts

@@ -101,6 +101,8 @@ export interface TelegramLockedPollingRuntimeDeps<
 > {
   lock: TelegramLockRuntime<TContext>;
   hasBotToken: () => boolean;
+  canStartPolling?: (ctx: TContext) => boolean;
+  formatStartBlockedMessage?: (ctx: TContext) => string;
   startPolling: (ctx: TContext) => void | Promise<void>;
   stopPolling: () => Promise<void>;
   updateStatus: (ctx: TContext) => void;
@@ -309,10 +311,18 @@ export function createTelegramLockedPollingRuntime<
     }, ownershipCheckMs);
     ownershipInterval.unref?.();
   };
+  const canStartPolling = (ctx: TContext): boolean =>
+    deps.canStartPolling?.(ctx) ?? true;
+  const formatStartBlockedMessage = (ctx: TContext): string =>
+    deps.formatStartBlockedMessage?.(ctx) ??
+    "Telegram polling is unavailable in this π run mode.";
   return {
     start: async (ctx, options = {}) => {
       if (!deps.hasBotToken())
         return { ok: false, message: "Telegram bot is not configured." };
+      if (!canStartPolling(ctx)) {
+        return { ok: false, message: formatStartBlockedMessage(ctx) };
+      }
       const acquired = deps.lock.acquire(ctx, options);
       if (!acquired.ok) {
         return {
@@ -341,6 +351,7 @@ export function createTelegramLockedPollingRuntime<
     suspend: suspendPolling,
     onSessionStart: async (_event, ctx) => {
       if (!deps.hasBotToken()) return;
+      if (!canStartPolling(ctx)) return;
       const ownsCurrentLock = deps.lock.owns(ctx);
       const state = ownsCurrentLock ? undefined : deps.lock.getState();
       const canResumeStaleSameCwd =

package/lib/pi.ts

@@ -41,6 +41,44 @@ export interface PiSettingsManager {
 }
 
 export type PiSlashCommandInfo = SlashCommandInfo;
+export type PiRunMode = "tui" | "rpc" | "json" | "print";
+
+function isPiRunMode(value: unknown): value is PiRunMode {
+  return (
+    value === "tui" ||
+    value === "rpc" ||
+    value === "json" ||
+    value === "print"
+  );
+}
+
+export function getExtensionContextMode(ctx: unknown): PiRunMode | undefined {
+  const mode =
+    typeof ctx === "object" && ctx !== null
+      ? (ctx as { mode?: unknown }).mode
+      : undefined;
+  return isPiRunMode(mode) ? mode : undefined;
+}
+
+export function isExtensionContextPassiveRunMode(ctx: unknown): boolean {
+  const mode = getExtensionContextMode(ctx);
+  return mode === "print" || mode === "json";
+}
+
+export function canStartPollingInExtensionContext(ctx: unknown): boolean {
+  return !isExtensionContextPassiveRunMode(ctx);
+}
+
+export function formatPollingStartBlockedByRunMode(ctx: unknown): string {
+  const mode = getExtensionContextMode(ctx);
+  return mode
+    ? `Telegram polling is unavailable in π ${mode} mode. Use /telegram-connect from a long-lived π session.`
+    : "Telegram polling is unavailable in this π run mode.";
+}
+
+export type PiSendUserMessageOptions = NonNullable<
+  Parameters<ExtensionAPI["sendUserMessage"]>[1]
+>;
 
 export interface PiExtensionApiRuntimePorts {
   sendUserMessage: ExtensionAPI["sendUserMessage"];
@@ -63,7 +101,7 @@ export function createExtensionApiRuntimePorts(
   >,
 ): PiExtensionApiRuntimePorts {
   return {
-    sendUserMessage: (content) => api.sendUserMessage(content),
+    sendUserMessage: (content, options) => api.sendUserMessage(content, options),
     exec: (command, args, options) => api.exec(command, args, options),
     getCommands: () => api.getCommands(),
     getThinkingLevel: () => api.getThinkingLevel(),

package/lib/prompts.ts

@@ -7,11 +7,19 @@
 import type { BeforeAgentStartEvent } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
-const SYSTEM_PROMPT_SUFFIX = `
+const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge extension is active.
+Telegram bridge extension is available.
 
-Inbound context:
+Local/TUI Telegram delivery:
+- Answer ordinary local prompts normally; do not add Telegram action comments unless the user explicitly asks for Telegram delivery.
+- For explicit Telegram file delivery, call \`telegram_attach(local_path)\`. For explicit Telegram text delivery, call \`telegram_message(...)\`.
+- Direct local/TUI Telegram delivery requires this π instance to own \`/telegram-connect\`; if ownership is elsewhere, connect/take over first instead of bypassing the lock.
+`;
+
+const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
+
+Telegram-originated turn context:
 - \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
 - \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
 - \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
@@ -27,7 +35,7 @@ Telegram-visible output:
 
 Native outbound actions:
 - Use normal Markdown for visible text. Use top-level column-zero hidden Markdown comments outside code, quotes, and lists only for native actions; the bridge strips them after agent_end and turns them into Telegram-native artifacts/reply_markup. Do not render button JSON, do not invent standalone button tools, and do not call/register transport/TTS/text-to-OGG tools for ordinary Telegram-turn voice/buttons.
-- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line voice, or \`<!-- telegram_voice: Short summary -->\` for one-line voice with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
+- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line text, or \`<!-- telegram_voice: Short summary -->\` for one-line text with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
 - \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts. Do not put button comments inline after visible text, inside code fences, block quotes, lists, or indented examples; those are literal Markdown, not buttons.
 - If only hidden action comments would remain, add visible parent text like "Choose one:" so Telegram has a message to attach buttons to.
 `;
@@ -36,19 +44,25 @@ export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
   systemPrompt: string;
   telegramPrefix?: string;
-  systemPromptSuffix: string;
+  localSystemPromptSuffix: string;
+  telegramTurnSystemPromptSuffix: string;
 }): { systemPrompt: string } {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
-  const suffix = options.prompt.trimStart().startsWith(telegramPrefix)
-    ? `${options.systemPromptSuffix}\n- The current user message came from Telegram.`
-    : options.systemPromptSuffix;
-  return { systemPrompt: options.systemPrompt + suffix };
+  const telegramTurn = options.prompt.trimStart().startsWith(telegramPrefix);
+  const telegramSuffix = telegramTurn
+    ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
+    : "";
+  return {
+    systemPrompt:
+      options.systemPrompt + options.localSystemPromptSuffix + telegramSuffix,
+  };
 }
 
 export function createTelegramBeforeAgentStartHook(
   options: {
     telegramPrefix?: string;
-    systemPromptSuffix?: string;
+    localSystemPromptSuffix?: string;
+    telegramTurnSystemPromptSuffix?: string;
   } = {},
 ): (event: BeforeAgentStartEvent) => { systemPrompt: string } {
   return (event) =>
@@ -56,12 +70,17 @@ export function createTelegramBeforeAgentStartHook(
       prompt: event.prompt,
       systemPrompt: event.systemPrompt,
       telegramPrefix: options.telegramPrefix,
-      systemPromptSuffix: options.systemPromptSuffix ?? SYSTEM_PROMPT_SUFFIX,
+      localSystemPromptSuffix:
+        options.localSystemPromptSuffix ?? LOCAL_SYSTEM_PROMPT_SUFFIX,
+      telegramTurnSystemPromptSuffix:
+        options.telegramTurnSystemPromptSuffix ??
+        TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX,
     });
 }
 
 export interface TelegramProactivePromptHookDeps<TContext> {
   baseHook?: (event: BeforeAgentStartEvent) => { systemPrompt: string };
+  isConfigured: () => boolean;
   isProactivePushEnabled: () => boolean;
   isCurrentOwner: (ctx: TContext) => boolean;
 }
@@ -74,6 +93,7 @@ export function createTelegramProactiveBeforeAgentStartHook<TContext>(
 ) => Promise<{ systemPrompt: string }> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async function onBeforeAgentStart(event, ctx) {
+    if (!deps.isConfigured()) return { systemPrompt: event.systemPrompt };
     const result = baseHook(event);
     if (!deps.isProactivePushEnabled()) return result;
     if (!deps.isCurrentOwner(ctx)) return result;

package/lib/queue.ts

@@ -1820,6 +1820,14 @@ export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
 
 // --- Dispatch Runtime ---
 
+export interface TelegramPromptDeliveryOptions {
+  deliverAs: "followUp";
+}
+
+export const TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY = {
+  deliverAs: "followUp",
+} as const satisfies TelegramPromptDeliveryOptions;
+
 export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
   executeControlItem: (
     item: Extract<
@@ -1833,6 +1841,7 @@ export interface TelegramDispatchRuntimeDeps<TContext = unknown> {
       TelegramQueueDispatchAction,
       { kind: "prompt" }
     >["item"]["content"],
+    options?: TelegramPromptDeliveryOptions,
   ) => void;
   onPromptDispatchFailure: (message: string) => void;
   onIdle: () => void;
@@ -1870,7 +1879,7 @@ export function executeTelegramQueueDispatchPlan<TContext = unknown>(
   }
   deps.onPromptDispatchStart(plan.item.chatId);
   try {
-    deps.sendUserMessage(plan.item.content);
+    deps.sendUserMessage(plan.item.content, TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY);
   } catch (error) {
     const message = getTelegramQueueErrorMessage(error);
     deps.onPromptDispatchFailure(message);

package/lib/routing.ts

@@ -122,7 +122,10 @@ export interface TelegramInboundRouteRuntimeDeps<
     ctx: TContext,
   ) => Promise<void>;
   setModel: (model: TModel) => Promise<boolean>;
-  sendUserMessage?: (message: string) => void;
+  sendUserMessage?: (
+    message: string,
+    options?: Queue.TelegramPromptDeliveryOptions,
+  ) => void;
   isIdle: (ctx: TContext) => boolean;
   hasPendingMessages: (ctx: TContext) => boolean;
   compact: (
@@ -315,7 +318,10 @@ export function createTelegramInboundRouteRuntime<
       callbackData &&
       !isTelegramOwnedCallbackData(callbackData)
     ) {
-      deps.sendUserMessage(`[callback] ${callbackData}`);
+      deps.sendUserMessage(
+        `[callback] ${callbackData}`,
+        Queue.TELEGRAM_PROMPT_FOLLOW_UP_DELIVERY,
+      );
       await deps.answerCallbackQuery(query.id);
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.16.3",
+  "version": "0.16.5",
   "private": false,
   "publishConfig": {
     "access": "public"