polygram 0.12.0-rc.29 → 0.12.0-rc.30

package/lib/db.js

@@ -19,7 +19,7 @@ const Database = require('better-sqlite3');
 // SCHEMA_VERSION; the early-return on line ~42 then skipped the
 // migration loop on any DB already at user_version=8 → turn_metrics
 // table never created → INSERT prepare at startup crashed polygram.
-const SCHEMA_VERSION = 11;
+const SCHEMA_VERSION = 12;
 
 // Sentinel `error` value for outbound rows whose API call may or may not
 // have reached Telegram. markStalePending writes it; hasOutboundReplyTo

package/lib/handlers/questions.js

@@ -0,0 +1,287 @@
+/**
+ * Interactive-question handlers (0.12 ask feature) — the integration glue between
+ * the pure state machine (lib/questions/questions.js), the store
+ * (lib/questions/store.js), Telegram, and the bridge answer write-back.
+ *
+ *   renderAsk            — claude called `ask`: issue a row, send the keyboard.
+ *   handleQuestionCallback — a `q:` button tap: validate, mutate, advance/resolve.
+ *   tryConsumeAsAnswer   — dispatcher hook: a typed message while a question is
+ *                          open (free-text "Other", or a nudge for the wrong user).
+ *   expireQuestion       — timeout sweep / cancel: answer {timedout}/{cancelled}, strip.
+ *
+ * Security (review): per-row 128-bit token in callback_data + claim-on-first-tap
+ * respondent authz + plain-text body (no parse_mode) for agent content.
+ *
+ * Anti-hang invariant (review-hardened): claude's `ask` tool call must be answered
+ * EXACTLY once and never hang. Therefore every terminal path hands the result to
+ * claude *first* (guarded) and only then marks the row terminal — `finalize()`. If
+ * the write-back THROWS, the row is LEFT pending so the timeout sweep can recover
+ * with {timedout} (never resolved-but-hung). If the write-back is an undelivered
+ * NO-OP (returns false — session gone / no live bridge), it is surfaced loudly and
+ * the row is still resolved (a dead session can't be delivered; the bridge's own
+ * 20-min ceiling backstops the rare live-proc case). A failed Telegram send is also
+ * hang-safe: we answer {cancelled} rather than leaving a pending row with no
+ * on-screen keyboard. renderAsk that throws BEFORE issuing a row answers {cancelled}
+ * itself (no row exists for the sweep to find); tryConsumeAsAnswer never throws out
+ * of the dispatcher (a store error degrades to "not an answer", never a dropped msg).
+ */
+
+'use strict';
+
+const Q = require('../questions/questions');
+const { tokensEqual } = require('../questions/store');
+
+function createQuestionHandlers({
+  questions,        // store (lib/questions/store.js)
+  tg,
+  bot,
+  botName,
+  logEvent = () => {},
+  answerQuestion,   // (sessionKey, toolCallId, result) → write question_answer to the bridge
+  logger = console,
+} = {}) {
+
+  function strip(chatId, msgId, threadId, text) {
+    if (msgId == null) return Promise.resolve();
+    return tg(bot, 'editMessageText', {
+      chat_id: chatId, message_id: msgId, text,
+      ...(threadId && { message_thread_id: threadId }),
+    }, { source: 'question-edit', botName })
+      .catch((e) => logger.error?.(`[${botName}] question strip failed: ${e.message}`));
+  }
+
+  async function sendCurrent(row, state) {
+    const view = Q.renderCurrent(state, `q:${row.id}:${row.callback_token}`);
+    if (!view) return null;
+    // PLAIN-TEXT (no parse_mode): option labels/descriptions are agent-authored.
+    const sent = await tg(bot, 'sendMessage', {
+      chat_id: row.chat_id, text: view.text, reply_markup: view.reply_markup,
+      ...(row.thread_id && { message_thread_id: row.thread_id }),
+    }, { source: 'question', botName }).catch((e) => {
+      logger.error?.(`[${botName}] question send failed: ${e.message}`);
+      return null;
+    });
+    return sent?.message_id ?? null;
+  }
+
+  /**
+   * Hand the result to claude FIRST (guarded), then mark the row terminal. On
+   * write-back failure: leave the row pending (the timeout sweep recovers it) and
+   * return false — NEVER resolved-but-hung. Returns true when claude was answered.
+   */
+  function finalize(row, result, status = 'answered') {
+    let delivered;
+    try {
+      delivered = answerQuestion?.(row.session_key, row.tool_call_id, result);
+    } catch (e) {
+      logger.error?.(`[${botName}] answerQuestion failed for ${row.tool_call_id}: ${e.message}`);
+      return false;   // threw → leave the row pending; the timeout sweep recovers it
+    }
+    // A *false* return is a silent no-op (session gone / no live bridge), NOT a
+    // throw. Surface it loudly and still resolve: a dead session can never be
+    // delivered, so leaving it pending would have the 30s sweep re-strip +
+    // re-answer it forever. The rare live-proc-but-unwritable-bridge case is
+    // backstopped by the bridge's own 20-min answer ceiling.
+    if (delivered === false) {
+      logger.error?.(`[${botName}] answerQuestion undelivered (session gone / no bridge) for ${row.tool_call_id}`);
+      logEvent('question-answer-undelivered', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+    }
+    questions.resolve(row.id, status);
+    return true;
+  }
+
+  // ── claude called ask → render the first question ──────────────────
+  async function renderAsk({ sessionKey, chatId, threadId = null, turnId = null, toolCallId, questions: qs }) {
+    let row = null;
+    try {
+      // Idempotency: a bridge retry of the same tool_call_id must not double-render.
+      if (questions.getByToolCallId(toolCallId)) return null;
+
+      if (!Array.isArray(qs) || qs.length === 0) {
+        try { answerQuestion?.(sessionKey, toolCallId, { answers: [] }); } catch (e) {
+          logger.error?.(`[${botName}] answerQuestion(empty) failed: ${e.message}`);
+        }
+        return null;
+      }
+      // One open question per session: cancel + unblock any prior open ask first.
+      const prior = questions.getOpenForSession(sessionKey);
+      if (prior) {
+        finalize(prior, { cancelled: true }, 'cancelled');
+        const pIds = JSON.parse(prior.message_ids_json || '[]');
+        if (pIds[0]) strip(prior.chat_id, pIds[0], prior.thread_id, 'This question was replaced.');
+      }
+      const state = Q.initState(qs);
+      row = questions.issue({
+        bot_name: botName, session_key: sessionKey, chat_id: chatId, thread_id: threadId,
+        turn_id: turnId, tool_call_id: toolCallId, questions: qs, state,
+      });
+      const msgId = await sendCurrent(row, state);
+      if (msgId == null) {
+        // Couldn't deliver the keyboard — don't strand claude on a pending row.
+        finalize(row, { cancelled: true, error: 'failed to deliver the question' }, 'cancelled');
+        logEvent('question-send-failed', { session_key: sessionKey, tool_call_id: toolCallId, phase: 'first' });
+        return null;
+      }
+      questions.setMessageIds(row.id, [msgId]);
+      logEvent('question-asked', { session_key: sessionKey, chat_id: chatId, tool_call_id: toolCallId, count: qs.length });
+      return row;
+    } catch (e) {
+      logger.error?.(`[${botName}] renderAsk failed for ${toolCallId}: ${e.message}`);
+      // Anti-hang: a throw BEFORE the row was issued (store error, etc.) leaves
+      // claude blocked with no row for the sweep to recover → answer {cancelled}
+      // now. If the row WAS issued (throw in a later step), it is pending and the
+      // timeout sweep will recover it with {timedout}.
+      if (!row) {
+        try { answerQuestion?.(sessionKey, toolCallId, { cancelled: true, error: 'failed to render question' }); } catch (e2) {
+          logger.error?.(`[${botName}] renderAsk fallback answer failed for ${toolCallId}: ${e2.message}`);
+        }
+      }
+      return null;
+    }
+  }
+
+  // ── a `q:<id>:<token>:<action>` button tap ─────────────────────────
+  async function handleQuestionCallback(ctx) {
+    const data = ctx.callbackQuery?.data || '';
+    const m = String(data).match(/^q:(\d+):([^:]+):(.+)$/);
+    if (!m) return;
+    const id = parseInt(m[1], 10);
+    const token = m[2];
+    const actionStr = m[3];
+
+    const row = questions.getById(id);
+    if (!row) { await ack(ctx, 'This question expired.', true); return; }
+    if (!tokensEqual(row.callback_token, token)) {
+      logEvent('question-token-mismatch', { id, from_user: ctx.from?.id });
+      await ack(ctx, 'Bad token.', true); return;
+    }
+    if (row.status !== 'pending') { await ack(ctx, `Already ${row.status}.`, true); return; }
+
+    // Respondent authorization: first tapper claims the question; others rejected.
+    const auth = questions.claimOrCheck(id, ctx.from?.id);
+    if (!auth.ok) {
+      logEvent('question-foreign-responder', { id, from_user: ctx.from?.id, owner: row.from_id });
+      await ack(ctx, 'This question is for someone else.', true); return;
+    }
+
+    const state = JSON.parse(row.state_json);
+    const res = Q.applyTap(state, Q.parseAction(actionStr));
+    const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
+
+    if (res.kind === 'reject') { await ack(ctx, res.message, true); return; }
+
+    if (res.kind === 'toggled') {
+      questions.updateState(id, res.state, false);
+      const view = Q.renderCurrent(res.state, `q:${id}:${token}`);
+      await tg(bot, 'editMessageReplyMarkup', {
+        chat_id: row.chat_id, message_id: msgId, reply_markup: view.reply_markup,
+        ...(row.thread_id && { message_thread_id: row.thread_id }),
+      }, { source: 'question-edit', botName })
+        .catch((e) => logger.error?.(`[${botName}] toggle re-render failed (q ${id}): ${e.message}`));
+      await ack(ctx);
+      return;
+    }
+
+    if (res.kind === 'awaiting-other') {
+      questions.updateState(id, res.state, true);
+      await strip(row.chat_id, msgId, row.thread_id, 'Send your answer as a message.');
+      await ack(ctx, 'Type your answer ↓');
+      return;
+    }
+
+    // advanced — record + receipt, then next question or finish.
+    await advance(ctx, row, res, false);
+  }
+
+  // ── a typed message while a question is open (Other / nudge) ────────
+  async function tryConsumeAsAnswer({ sessionKey, fromId, text }) {
+    try {
+      const row = questions.getOpenForSession(sessionKey);
+      if (!row) return { consumed: false };
+      // Only an in-progress free-text capture diverts typed messages. A question
+      // awaiting a BUTTON tap does not swallow ordinary chatter (review: do not eat
+      // every group member's message for the whole question lifetime).
+      if (!row.awaiting_other) return { consumed: false };
+      // /stop, /new and other commands are never consumed as a free-text answer.
+      if (/^\/(stop|new|reset|cancel|abort)\b/i.test(String(text || '').trim())) return { consumed: false };
+      // Identity: only the claimed owner supplies the free-text answer.
+      const auth = questions.claimOrCheck(row.id, fromId);
+      if (!auth.ok) {
+        tg(bot, 'sendMessage', { chat_id: row.chat_id, text: 'Please answer the open question above first.',
+          ...(row.thread_id && { message_thread_id: row.thread_id }) }, { source: 'question-nudge', botName })
+          .catch((e) => logger.error?.(`[${botName}] question nudge failed: ${e.message}`));
+        return { consumed: true };
+      }
+      const state = JSON.parse(row.state_json);
+      const res = Q.applyFreeText(state, text);
+      if (res.kind !== 'advanced') return { consumed: false };
+      await advance({ from: { id: fromId } }, row, res, true);
+      return { consumed: true };
+    } catch (e) {
+      // Never throw out of the message dispatcher: a store/parse error here must
+      // degrade to "not an answer" so the user's message still reaches normal
+      // dispatch instead of being silently dropped.
+      logger.error?.(`[${botName}] tryConsumeAsAnswer failed: ${e.message}`);
+      return { consumed: false };
+    }
+  }
+
+  // Does `fromId` own an open free-text ("Other") capture for this session? The
+  // dispatcher uses this to let the owner's typed answer bypass a group's mention
+  // gate — only the claimed owner, never a bystander.
+  function isAwaitingOtherFrom(sessionKey, fromId) {
+    if (fromId == null) return false;
+    try {
+      const row = questions.getOpenForSession(sessionKey);
+      return !!(row && row.awaiting_other && row.from_id != null && Number(row.from_id) === Number(fromId));
+    } catch { return false; }
+  }
+
+  // ── timeout sweep / external cancel ────────────────────────────────
+  async function expireQuestion(row, { status = 'timeout', message = 'This question timed out.' } = {}) {
+    const ids = JSON.parse(row.message_ids_json || '[]');
+    if (ids[0]) await strip(row.chat_id, ids[0], row.thread_id, message);
+    const result = status === 'cancelled' ? { cancelled: true } : { timedout: true };
+    finalize(row, result, status);
+    logEvent('question-expired', { session_key: row.session_key, tool_call_id: row.tool_call_id, status });
+  }
+
+  // shared: record an advanced result, post a receipt, then next-Q or resolve.
+  async function advance(ctx, row, res, fromText) {
+    const msgId = (JSON.parse(row.message_ids_json || '[]'))[0];
+    if (!fromText) {
+      await strip(row.chat_id, msgId, row.thread_id, `✓ ${res.receipt}`);
+      await ack(ctx, 'Recorded');
+    }
+
+    if (res.done) {
+      questions.updateState(row.id, res.state, false);
+      // Answer claude FIRST (guarded), THEN mark answered. If the write-back
+      // throws, leave the row pending → the timeout sweep recovers it.
+      if (!finalize(row, Q.assemble(res.state), 'answered')) {
+        logEvent('question-answer-writeback-failed', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+        return;
+      }
+      logEvent('question-answered', { session_key: row.session_key, tool_call_id: row.tool_call_id });
+      return;
+    }
+    // next question → new message; on send failure, don't strand claude.
+    const nextMsgId = await sendCurrent(row, res.state);
+    if (nextMsgId == null) {
+      finalize(row, { cancelled: true, error: 'failed to deliver the next question' }, 'cancelled');
+      logEvent('question-send-failed', { session_key: row.session_key, tool_call_id: row.tool_call_id, phase: 'next', q_index: res.state.qIndex });
+      return;
+    }
+    questions.updateState(row.id, res.state, false);
+    questions.setMessageIds(row.id, [nextMsgId]);
+  }
+
+  function ack(ctx, text, alert = false) {
+    if (!ctx || typeof ctx.answerCallbackQuery !== 'function') return Promise.resolve();
+    return ctx.answerCallbackQuery(text ? { text, show_alert: alert } : undefined).catch(() => {});
+  }
+
+  return { renderAsk, handleQuestionCallback, tryConsumeAsAnswer, expireQuestion, isAwaitingOtherFrom };
+}
+
+module.exports = { createQuestionHandlers };

package/lib/process/channels-bridge-protocol.js

@@ -50,7 +50,12 @@ const ToolCallMessageSchema = z.object({
   kind: z.literal('tool'),
   session: NonEmptyString,
   tool_call_id: ToolCallId,
-  name: z.enum(['reply', 'react', 'edit_message']),
+  // 'ask' (0.12 interactive questions): a blocking tool whose answer rides back
+  // on a `question_answer` daemon→bridge message (NOT the fast `tool_ack`); its
+  // args are {chat_id, turn_id?, questions:[...]}, not reply-shaped. _dispatchToolCall
+  // branches on the name so the reply-only paths (chat_id-mismatch, content-dedup,
+  // reply-turn-binding) don't run for it.
+  name: z.enum(['reply', 'react', 'edit_message', 'ask']),
   args: z.object({}).passthrough(),
 }).passthrough();
 
@@ -118,6 +123,16 @@ const ToolAckMessageSchema = z.object({
   error: z.string().optional(),
 }).passthrough();
 
+// 0.12 interactive questions: carries the user's answer back for an `ask` tool
+// call. Separate from `tool_ack` (which has no payload field and resolves the
+// fast reply round-trip) so a blocking question can return a structured result.
+// `result` is one of {answers:[...]} | {cancelled:true} | {timedout:true}.
+const QuestionAnswerMessageSchema = z.object({
+  kind: z.literal('question_answer'),
+  tool_call_id: ToolCallId,
+  result: z.object({}).passthrough(),
+}).passthrough();
+
 const PingMessageSchema = z.object({
   kind: z.literal('ping'),
 }).passthrough();
@@ -128,6 +143,7 @@ const AnyDaemonToBridgeMessage = z.discriminatedUnion('kind', [
   UserMessageSchema,
   PermVerdictMessageSchema,
   ToolAckMessageSchema,
+  QuestionAnswerMessageSchema,
   PingMessageSchema,
 ]);
 
@@ -170,6 +186,7 @@ module.exports = {
   UserMessageSchema,
   PermVerdictMessageSchema,
   ToolAckMessageSchema,
+  QuestionAnswerMessageSchema,
   PingMessageSchema,
   AnyDaemonToBridgeMessage,
   // helpers

package/lib/process/channels-bridge.mjs

@@ -116,6 +116,31 @@ function resolveToolAck(toolCallId, ok, error) {
   ok ? p.resolve() : p.reject(new Error(error || 'daemon rejected delivery'))
 }
 
+// ─── 0.12 interactive questions: `ask` blocks for the user's answer ──
+// Separate from tool_ack: a question can take MINUTES (the daemon-side 8-min
+// question timeout resolves it with {timedout} well before this hard ceiling).
+const pendingQuestions = new Map() // tool_call_id → { resolve, timer }
+const QUESTION_ANSWER_TIMEOUT_MS = 20 * 60 * 1000
+
+function awaitQuestionAnswer(toolCallId) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingQuestions.delete(toolCallId)
+      resolve({ timedout: true })   // never reject — the agent gets a clean result
+    }, QUESTION_ANSWER_TIMEOUT_MS)
+    timer.unref?.()   // a pending answer must not, by itself, hold the event loop open
+    pendingQuestions.set(toolCallId, { resolve, timer })
+  })
+}
+
+function resolveQuestionAnswer(toolCallId, result) {
+  const p = pendingQuestions.get(toolCallId)
+  if (!p) return
+  pendingQuestions.delete(toolCallId)
+  clearTimeout(p.timer)
+  p.resolve(result ?? { cancelled: true })
+}
+
 // ─── Socket: connect, handshake, then bidirectional JSON-lines ──
 const sock = connect(SOCK)
 
@@ -213,6 +238,10 @@ function handleDaemonMessage(msg) {
       resolveToolAck(msg.tool_call_id, msg.ok, msg.error)
       break
 
+    case 'question_answer':
+      resolveQuestionAnswer(msg.tool_call_id, msg.result)
+      break
+
     case 'ping':
       // R5: ping is the ONLY signal that proves the daemon's ping-loop is
       // healthy. Update watchdog timestamp here, not on the generic 'data'
@@ -283,15 +312,70 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       required: ['chat_id', 'text'],
     },
+  }, {
+    // 0.12 interactive questions: ask the Telegram user a multiple-choice question
+    // as tap-to-answer inline buttons. USE THIS instead of any interactive menu —
+    // it returns the user's selection(s) as the tool result. Blocks until answered.
+    name: 'ask',
+    description: 'Ask the Telegram user a multiple-choice question (rendered as inline ' +
+                 'keyboard buttons; supports multiSelect + a free-text "Other"). Use this ' +
+                 'for ANY choice/confirmation — never present a numbered list and wait, and ' +
+                 'never use a terminal selection menu. Blocks until the user answers; returns ' +
+                 '{answers:[{header,selected:[label...],other?}]} (or {cancelled}/{timedout}).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chat_id: { type: 'string', description: 'Echo of chat_id from inbound channel meta.' },
+        turn_id: { type: 'string', description: 'Echo of turn_id from inbound channel meta.' },
+        questions: {
+          type: 'array', description: 'Up to 4 questions, asked one at a time.',
+          items: {
+            type: 'object',
+            properties: {
+              header:      { type: 'string', description: 'Short chip label (≤12 chars).' },
+              question:    { type: 'string', description: 'The question text.' },
+              multiSelect: { type: 'boolean', description: 'Allow selecting several options (checkboxes).' },
+              allowOther:  { type: 'boolean', description: 'Offer a free-text "type my own" answer (default true).' },
+              options: {
+                type: 'array', description: '2–4 options.',
+                items: { type: 'object', properties: {
+                  label:       { type: 'string', description: 'Button label (≤40 chars).' },
+                  description: { type: 'string', description: 'Shown in the message body.' },
+                } },
+              },
+            },
+            required: ['question', 'options'],
+          },
+        },
+      },
+      required: ['chat_id', 'questions'],
+    },
   }],
   }
 })
 
 mcp.setRequestHandler(CallToolRequestSchema, async req => {
-  if (req.params.name !== 'reply') {
+  if (req.params.name !== 'reply' && req.params.name !== 'ask') {
     return { content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }], isError: true }
   }
   const toolCallId = randomUUID()
+
+  // `ask` blocks for the user's answer (question_answer), NOT a fast tool_ack.
+  if (req.params.name === 'ask') {
+    const answerP = awaitQuestionAnswer(toolCallId)
+    try {
+      sock.write(JSON.stringify({
+        kind: 'tool', session: SESSION_KEY, tool_call_id: toolCallId, name: 'ask', args: req.params.arguments,
+      }) + '\n')
+    } catch (e) {
+      // The daemon never received the ask → no row, no sweep. Resolve the awaiter
+      // now (clears the 20-min timer) instead of stranding the agent on it.
+      resolveQuestionAnswer(toolCallId, { cancelled: true, error: `bridge write failed: ${e?.message || e}` })
+    }
+    const result = await answerP
+    return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+  }
+
   const ackP = awaitToolAck(toolCallId)
   sock.write(JSON.stringify({
     kind: 'tool',

package/lib/process/cli-process.js

@@ -300,6 +300,11 @@ class CliProcess extends Process {
 
     // pending turn(s): turn_id → { resolve, reject, replies: [], quietTimer, hardTimer, startedAt }
     this.pendingTurns = new Map();
+    // 0.12 interactive questions: tool_call_ids of `ask` calls awaiting an answer.
+    // While non-empty, the keep-alive interval resets the turn's idle ceiling (an
+    // idle `ask` fires no tool hooks, so _extendQuietOnToolActivity wouldn't run).
+    this._openQuestions = new Set();
+    this._questionKeepAliveTimer = null;
 
     // File-send outbound cap (bot → user). Safe cloud default; overwritten in
     // _spawnTmuxClaude with the backend/chat-resolved value before any turn.
@@ -702,9 +707,11 @@ class CliProcess extends Process {
       'see or navigate — it silently wedges the entire session until it is manually',
       'cleared. (Rich tap-to-answer choices are coming; until then this is a hard rule.)',
       '',
-      'To ask a multiple-choice question, write the options as a numbered list',
-      'inside your `mcp__polygram-bridge__reply` text and ask the user to reply with',
-      'the number (or free text). Do the same for yes/no and any selection.',
+      'To ask a multiple-choice question, a confirmation, or yes/no, call the',
+      '`mcp__polygram-bridge__ask` tool — it renders tap-to-answer inline buttons',
+      '(supports multiSelect via `multiSelect:true` and a free-text answer via',
+      '`allowOther:true`) and returns the user\'s selection(s) as the tool result.',
+      'Prefer `ask` over a typed numbered list whenever you are offering choices.',
       '',
       '### Sending FILES (tracks, images, docs) to the user',
       '',
@@ -1004,6 +1011,31 @@ class CliProcess extends Process {
       return;
     }
 
+    // 0.12 interactive questions: `ask` is a BLOCKING tool whose answer rides back
+    // on a `question_answer` message (NOT tool_ack). Skip the reply-only paths
+    // (content-dedup, rate-limit, the reply dispatcher) — just guard chat_id and
+    // emit so polygram renders the keyboard; the answer is written later via
+    // writeQuestionAnswer(). claude is now idle waiting on the result, so start a
+    // keep-alive that resets the turn's idle ceiling (no tool hooks fire meanwhile).
+    if (msg.name === 'ask') {
+      if (this.chatId != null && args.chat_id != null && String(args.chat_id) !== String(this.chatId)) {
+        this._writeToBridge({ kind: 'question_answer', tool_call_id: msg.tool_call_id, result: { cancelled: true, error: 'chat_id mismatch' } });
+        return;
+      }
+      this._openQuestions.add(msg.tool_call_id);
+      this._startQuestionKeepAlive();
+      this.emit('question-asked', {
+        sessionKey: this.sessionKey,
+        chatId: this.chatId,
+        threadId: this.threadId,
+        turnId: args.turn_id || null,
+        toolCallId: msg.tool_call_id,
+        questions: Array.isArray(args.questions) ? args.questions : [],
+        backend: this.backend,
+      });
+      return;
+    }
+
     // Review F#16: secondary content-hash dedup catches retries that come in
     // with a NEW tool_call_id (Claude regenerates the id on each retry after
     // an isError ack). Window-based so legit repeat sends eventually pass.
@@ -2174,6 +2206,11 @@ class CliProcess extends Process {
     this.pendingTurns.clear();
     this.pendingQueue.length = 0;
     this.inFlight = false;
+    // 0.12: drop the interactive-question keep-alive here too, for parity with
+    // _doKill — pm reacts to 'bridge-disconnected' by killing us anyway, but don't
+    // depend on that ordering to stop the 60s interval / clear the open set.
+    this._stopQuestionKeepAlive();
+    this._openQuestions.clear();
     this.emit('bridge-disconnected');
     this._logEvent('bridge-disconnected', { reason });
   }
@@ -2182,6 +2219,9 @@ class CliProcess extends Process {
     this.closed = true;
     this.inFlight = false;
 
+    this._stopQuestionKeepAlive();   // 0.12: drop the interactive-question keep-alive
+    this._openQuestions.clear();
+
     if (this.pingTimer) {
       clearInterval(this.pingTimer);
       this.pingTimer = null;
@@ -2542,6 +2582,34 @@ class CliProcess extends Process {
     this._writeToBridge({ kind: 'perm_verdict', request_id: requestId, behavior });
   }
 
+  // ─── interactive questions (0.12 ask) ─────────────────────────────
+
+  /**
+   * Hand a question's answer back to the blocking `ask` tool call. `result` is
+   * {answers:[...]} | {cancelled:true} | {timedout:true}. Stops the keep-alive
+   * once no questions remain open. Called by pm.answerQuestion (from the handler).
+   */
+  writeQuestionAnswer(toolCallId, result) {
+    this._openQuestions.delete(toolCallId);
+    if (this._openQuestions.size === 0) this._stopQuestionKeepAlive();
+    return this._writeToBridge({ kind: 'question_answer', tool_call_id: toolCallId, result: result ?? {} });
+  }
+
+  _startQuestionKeepAlive() {
+    if (this._questionKeepAliveTimer) return;
+    this._questionKeepAliveTimer = setInterval(() => {
+      if (this._openQuestions.size === 0) { this._stopQuestionKeepAlive(); return; }
+      // claude is idle waiting on the answer → no tool hooks → reset the idle
+      // ceiling (and reply-quiet window) so the turn isn't killed mid-question.
+      this._extendQuietOnToolActivity();
+    }, 60_000);
+    this._questionKeepAliveTimer.unref?.();
+  }
+
+  _stopQuestionKeepAlive() {
+    if (this._questionKeepAliveTimer) { clearInterval(this._questionKeepAliveTimer); this._questionKeepAliveTimer = null; }
+  }
+
   // ─── socket plumbing ──────────────────────────────────────────────
 
   _writeToBridge(obj) {
@@ -2649,6 +2717,12 @@ class CliProcess extends Process {
   async _pollMidTurnDialogs() {
     if (this.closed) return;
     if (this.pendingTurns.size === 0) return;        // no work to do when idle
+    // 0.12 interactive questions: while an `ask` is open claude sits idle at the
+    // prompt waiting on the tool result — so the pane shows no "esc to interrupt"
+    // and the question's own echoed text (a "?"/numbered list/"Yes/No") would
+    // false-trip the unknown-prompt heuristic + starve the STALL heartbeat. The
+    // keyboard lives on Telegram; suppress the pane watchdog while a question is open.
+    if (this._openQuestions.size > 0) return;
     if (!this.tmuxSession) return;                   // pre-spawn / post-kill
     if (typeof this.runner?.captureWide !== 'function') return;
 

package/lib/process-manager.js

@@ -53,6 +53,11 @@ const CALLBACK_TO_EVENT = {
   // posts/edits a "⏳ working in background" status message so a long job reads as
   // working, not stuck. See docs/0.12.0-background-work-lifecycle-plan.md.
   onBgWorkStatus:               'bg-work-status',
+  // 0.12 interactive questions: CliProcess emits 'question-asked'
+  // {sessionKey, chatId, threadId, turnId, toolCallId, questions} when claude calls
+  // the `ask` tool. The callback (polygram) renders the Telegram inline keyboard;
+  // the user's tap/typed answer routes back via pm.answerQuestion → writeQuestionAnswer.
+  onQuestionAsked:              'question-asked',
   onQueueDrop:                  'queue-drop',
   onThinking:                   'thinking',
   // Tmux backend: TUI shows in-pane approval prompt. SDK backend
@@ -458,6 +463,14 @@ class ProcessManager {
     return p.injectUserMessage(opts);
   }
 
+  // 0.12 interactive questions: hand an answer back to a blocking `ask` tool call.
+  // Returns false if the session is gone (claude is dead → nothing to answer).
+  answerQuestion(sessionKey, toolCallId, result) {
+    const p = this.procs.get(sessionKey);
+    if (!p || p.closed || typeof p.writeQuestionAnswer !== 'function') return false;
+    return p.writeQuestionAnswer(toolCallId, result);
+  }
+
   steer(sessionKey, text, opts) {
     const p = this.procs.get(sessionKey);
     if (!p || p.closed) return false;

package/lib/questions/questions.js

@@ -0,0 +1,183 @@
+/**
+ * Interactive-question state machine + Telegram rendering (0.12 ask feature).
+ *
+ * Pure, I/O-free: given an `ask` tool call's questions and the accumulated state,
+ * produce the Telegram message body + inline keyboard for the CURRENT question,
+ * apply a button tap or a free-text reply, and assemble the final answer payload.
+ * All Telegram sends / DB writes / bridge writes live in the callers
+ * (lib/handlers/questions.js, callbacks.js, cli-process.js) — this module is the
+ * testable core.
+ *
+ * Design: docs/0.12.0-interactive-questions-design.md. Sequential, one question
+ * at a time (P1–P2: single-select, multiSelect, free-text "Other"). Body is
+ * rendered PLAIN-TEXT (no parse_mode) because option labels/descriptions are
+ * agent-authored and must not reach the Markdown→HTML pipeline (security finding).
+ */
+
+'use strict';
+
+const MAX_LABEL = 40;       // Telegram button labels truncate ~64; keep well under
+const MAX_OTHER = 1000;     // cap on the user's free-text answer entering claude's context
+const MAX_PREVIEW = 500;
+
+function truncLabel(label) {
+  const s = String(label ?? '');
+  return s.length > MAX_LABEL ? s.slice(0, MAX_LABEL - 1) + '…' : s;
+}
+
+/** Initial state for an ask call's questions array. */
+function initState(questions) {
+  return {
+    questions: Array.isArray(questions) ? questions : [],
+    qIndex: 0,
+    answers: [],          // accumulated: [{ header, selected:[label...], other? }]
+    toggles: {},          // current multiSelect question: { '<optIndex>': true }
+    awaitingOther: false, // current question is in free-text capture mode
+  };
+}
+
+function currentQuestion(state) {
+  return state.questions[state.qIndex] || null;
+}
+
+function isDone(state) {
+  return state.qIndex >= state.questions.length;
+}
+
+/**
+ * Render the CURRENT question as { text, reply_markup }. callbackBase is the
+ * `q:<qid>:<token>` prefix; actions append `:opt:<i>` / `:submit` / `:other`.
+ * Returns null when the set is already done.
+ */
+function renderCurrent(state, callbackBase) {
+  const q = currentQuestion(state);
+  if (!q) return null;
+  const multi = q.multiSelect === true;
+  const total = state.questions.length;
+  const opts = Array.isArray(q.options) ? q.options : [];
+
+  const lines = [];
+  if (total > 1) lines.push(`Question ${state.qIndex + 1} of ${total}`);
+  if (q.header) lines.push(String(q.header));
+  lines.push(String(q.question ?? ''));
+  lines.push('');
+  opts.forEach((o, i) => {
+    const mark = multi && state.toggles[i] ? '☑️ ' : '• ';
+    lines.push(`${mark}${truncLabel(o.label)}${o.description ? ` — ${o.description}` : ''}`);
+    if (o.preview) lines.push(String(o.preview).slice(0, MAX_PREVIEW));
+  });
+  if (multi) lines.push('\nTap options to toggle, then Submit.');
+
+  const rows = opts.map((o, i) => ([{
+    text: `${multi && state.toggles[i] ? '☑️ ' : ''}${truncLabel(o.label)}`,
+    callback_data: `${callbackBase}:opt:${i}`,
+  }]));
+  if (multi) {
+    const any = Object.values(state.toggles).some(Boolean);
+    rows.push([{
+      text: any ? '✅ Submit' : '✅ Submit (pick at least one)',
+      callback_data: `${callbackBase}:submit`,
+    }]);
+  }
+  if (q.allowOther !== false) {
+    rows.push([{ text: '✏️ Type my own', callback_data: `${callbackBase}:other` }]);
+  }
+
+  return { text: lines.join('\n'), reply_markup: { inline_keyboard: rows } };
+}
+
+/** Parse the action suffix of a callback (everything after `q:<qid>:<token>:`). */
+function parseAction(suffix) {
+  const s = String(suffix ?? '');
+  if (s === 'submit') return { type: 'submit' };
+  if (s === 'other') return { type: 'other' };
+  const m = s.match(/^opt:(\d+)$/);
+  if (m) return { type: 'opt', i: Number(m[1]) };
+  return { type: 'unknown' };
+}
+
+function recordAndAdvance(state, answer) {
+  const next = {
+    ...state,
+    answers: [...state.answers, answer],
+    qIndex: state.qIndex + 1,
+    toggles: {},
+    awaitingOther: false,
+  };
+  return next;
+}
+
+/**
+ * Apply a button tap. Returns:
+ *   { state, kind:'toggled' }                 — multiSelect toggle, re-render
+ *   { state, kind:'awaiting-other' }          — user wants to type their own
+ *   { state, kind:'reject', message }         — invalid (e.g. submit with none)
+ *   { state, kind:'advanced', receipt, done } — answer recorded; done if set complete
+ */
+function applyTap(state, action) {
+  const q = currentQuestion(state);
+  if (!q) return { state, kind: 'reject', message: 'No active question.' };
+  const opts = Array.isArray(q.options) ? q.options : [];
+  const multi = q.multiSelect === true;
+
+  if (action.type === 'other') {
+    if (q.allowOther === false) return { state, kind: 'reject', message: 'Free text not allowed here.' };
+    return { state: { ...state, awaitingOther: true }, kind: 'awaiting-other' };
+  }
+
+  if (action.type === 'opt') {
+    if (action.i < 0 || action.i >= opts.length) {
+      return { state, kind: 'reject', message: 'Unknown option.' };
+    }
+    if (multi) {
+      const toggles = { ...state.toggles };
+      if (toggles[action.i]) delete toggles[action.i]; else toggles[action.i] = true;
+      return { state: { ...state, toggles }, kind: 'toggled' };
+    }
+    // single-select: record + advance
+    const label = opts[action.i].label;
+    const next = recordAndAdvance(state, { header: q.header, selected: [label] });
+    return { state: next, kind: 'advanced', receipt: label, done: isDone(next) };
+  }
+
+  if (action.type === 'submit') {
+    if (!multi) return { state, kind: 'reject', message: 'Nothing to submit.' };
+    const picked = Object.keys(state.toggles).filter(k => state.toggles[k]).map(Number).sort((a, b) => a - b);
+    if (picked.length === 0) return { state, kind: 'reject', message: 'Pick at least one option.' };
+    const labels = picked.map(i => opts[i].label);
+    const next = recordAndAdvance(state, { header: q.header, selected: labels });
+    return { state: next, kind: 'advanced', receipt: labels.join(', '), done: isDone(next) };
+  }
+
+  return { state, kind: 'reject', message: 'Unknown action.' };
+}
+
+/**
+ * Apply a free-text reply (the user's "Other" answer). Only valid when the
+ * current question is in awaitingOther mode. Returns the same advanced shape.
+ */
+function applyFreeText(state, text) {
+  const q = currentQuestion(state);
+  if (!q || !state.awaitingOther) return { state, kind: 'reject', message: 'Not awaiting a typed answer.' };
+  const other = String(text ?? '').slice(0, MAX_OTHER);
+  const next = recordAndAdvance(state, { header: q.header, selected: [], other });
+  return { state: next, kind: 'advanced', receipt: other, done: isDone(next) };
+}
+
+/** Final tool result once the set is done. */
+function assemble(state) {
+  return { answers: state.answers };
+}
+
+module.exports = {
+  initState,
+  currentQuestion,
+  isDone,
+  renderCurrent,
+  parseAction,
+  applyTap,
+  applyFreeText,
+  assemble,
+  MAX_LABEL,
+  MAX_OTHER,
+};

package/lib/questions/store.js

@@ -0,0 +1,100 @@
+/**
+ * pending_questions store — persistence for the 0.12 interactive-question flow.
+ *
+ * Mirrors lib/approvals/store.js: per-row 128-bit callback token, status
+ * lifecycle, audit-kept rows (never deleted; 'pending' at boot → 'expired').
+ * One OPEN question per session at a time. The answer routes back to claude on
+ * tool_call_id (a `question_answer` bridge message).
+ */
+
+'use strict';
+
+const { newToken, tokensEqual } = require('../approvals/store');
+
+const DEFAULT_TIMEOUT_MS = 8 * 60 * 1000;   // under the 10-min idle / 30-min absolute turn caps
+
+function createQuestionStore(rawDb, now = () => Date.now()) {
+  const insertStmt = rawDb.prepare(`
+    INSERT INTO pending_questions (
+      bot_name, session_key, chat_id, thread_id, turn_id, tool_call_id,
+      callback_token, questions_json, state_json, created_ts, timeout_ts
+    ) VALUES (
+      @bot_name, @session_key, @chat_id, @thread_id, @turn_id, @tool_call_id,
+      @callback_token, @questions_json, @state_json, @created_ts, @timeout_ts
+    )
+  `);
+  const getByIdStmt        = rawDb.prepare(`SELECT * FROM pending_questions WHERE id = ?`);
+  const getOpenForSessStmt = rawDb.prepare(`
+    SELECT * FROM pending_questions WHERE session_key = ? AND status = 'pending'
+     ORDER BY created_ts DESC LIMIT 1`);
+  const getByToolCallStmt  = rawDb.prepare(`SELECT * FROM pending_questions WHERE tool_call_id = ? LIMIT 1`);
+  const setMsgIdsStmt      = rawDb.prepare(`UPDATE pending_questions SET message_ids_json = ? WHERE id = ?`);
+  const updateStateStmt    = rawDb.prepare(`
+    UPDATE pending_questions SET state_json = @state_json, awaiting_other = @awaiting_other
+     WHERE id = @id AND status = 'pending'`);
+  const claimStmt          = rawDb.prepare(`
+    UPDATE pending_questions SET from_id = @from_id
+     WHERE id = @id AND from_id IS NULL AND status = 'pending'`);
+  const resolveStmt        = rawDb.prepare(`
+    UPDATE pending_questions SET status = @status, answered_ts = @answered_ts
+     WHERE id = @id AND status = 'pending'`);
+  const listTimedOutStmt   = rawDb.prepare(`SELECT * FROM pending_questions WHERE status = 'pending' AND timeout_ts < ?`);
+  const listOpenStmt       = rawDb.prepare(`SELECT * FROM pending_questions WHERE bot_name = ? AND status = 'pending'`);
+
+  return {
+    issue({ bot_name, session_key, chat_id, thread_id = null, turn_id = null, tool_call_id, questions, state, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+      if (!bot_name || !session_key || !chat_id || !tool_call_id) {
+        throw new Error('issue: bot_name, session_key, chat_id, tool_call_id required');
+      }
+      const created_ts = now();
+      const res = insertStmt.run({
+        bot_name,
+        session_key,
+        chat_id: String(chat_id),
+        thread_id: thread_id != null ? String(thread_id) : null,
+        turn_id,
+        tool_call_id,
+        callback_token: newToken(),
+        questions_json: JSON.stringify(questions ?? []),
+        state_json: JSON.stringify(state ?? {}),
+        created_ts,
+        timeout_ts: created_ts + timeoutMs,
+      });
+      return getByIdStmt.get(res.lastInsertRowid);
+    },
+
+    getById(id) { return getByIdStmt.get(id); },
+    getOpenForSession(session_key) { return getOpenForSessStmt.get(session_key); },
+    getByToolCallId(tool_call_id) { return getByToolCallStmt.get(tool_call_id); },
+    setMessageIds(id, ids) { return setMsgIdsStmt.run(JSON.stringify(ids ?? []), id).changes; },
+
+    updateState(id, state, awaitingOther = false) {
+      return updateStateStmt.run({ id, state_json: JSON.stringify(state ?? {}), awaiting_other: awaitingOther ? 1 : 0 }).changes;
+    },
+
+    /**
+     * Authorize a responder. Claim-on-first-tap: if no from_id is recorded yet,
+     * the first interacting user claims the question; thereafter only that user
+     * may answer. Returns { ok, claimed }.
+     */
+    claimOrCheck(id, from_id) {
+      if (from_id == null) return { ok: false, claimed: false };
+      const claimed = claimStmt.run({ id, from_id }).changes > 0;
+      if (claimed) return { ok: true, claimed: true };
+      const row = getByIdStmt.get(id);
+      return { ok: row && Number(row.from_id) === Number(from_id), claimed: false };
+    },
+
+    resolve(id, status) {
+      if (!['answered', 'cancelled', 'timeout', 'expired'].includes(status)) {
+        throw new Error(`bad status: ${status}`);
+      }
+      return resolveStmt.run({ id, status, answered_ts: now() }).changes;
+    },
+
+    sweepTimedOut() { return listTimedOutStmt.all(now()); },
+    listOpen(bot_name) { return listOpenStmt.all(bot_name); },
+  };
+}
+
+module.exports = { createQuestionStore, tokensEqual, DEFAULT_TIMEOUT_MS };

package/lib/sdk/callbacks.js

@@ -50,6 +50,9 @@ function createSdkCallbacks({
   chunkMarkdownText,
   deliverReplies,
   processAndDeliverAgentText,
+  // 0.12 interactive questions: (payload) => renders the Telegram keyboard when
+  // claude calls the `ask` tool. Optional — omitted in tests / SDK-only callers.
+  renderQuestion,
   logger = console,
 } = {}) {
   // rc.9: typing-indicator state for autosteer NEW-TURN extraction.
@@ -345,6 +348,19 @@ function createSdkCallbacks({
     // status message and edit it to done — so a long job reads as working, not
     // stuck. Direct tg send (NOT via claude — this is a bot status indicator),
     // keyed by sessionKey so the cleared/close paths can find it to edit.
+    // 0.12 interactive questions: claude called the `ask` tool. Render the
+    // Telegram inline keyboard via the question handler (late-bound from polygram).
+    // payload: {chatId, threadId, turnId, toolCallId, questions}. The handler
+    // itself is anti-hang (answers claude {cancelled} on any send failure).
+    onQuestionAsked: async (sessionKey, payload) => {
+      try {
+        if (typeof renderQuestion !== 'function') return;
+        await renderQuestion({ sessionKey, ...payload });
+      } catch (err) {
+        logger.error?.(`[${botName}] onQuestionAsked failed: ${err.message}`);
+      }
+    },
+
     onBgWorkStatus: async (sessionKey, payload) => {
       try {
         if (!bot) return;

package/migrations/012-pending-questions.sql

@@ -0,0 +1,30 @@
+-- 0.12 interactive questions: AskUserQuestion → Telegram inline keyboards.
+-- Mirrors pending_approvals (per-row 128-bit callback token, status lifecycle,
+-- audit-kept rows). One OPEN question per session at a time (idx_pq_open).
+-- The answer routes back to claude on tool_call_id via a question_answer message.
+
+CREATE TABLE pending_questions (
+  id                INTEGER PRIMARY KEY AUTOINCREMENT,
+  bot_name          TEXT NOT NULL,
+  session_key       TEXT NOT NULL,     -- chat:thread that asked (claude session)
+  chat_id           TEXT NOT NULL,
+  thread_id         TEXT,
+  turn_id           TEXT,              -- echoed for routing
+  tool_call_id      TEXT NOT NULL,     -- the question_answer routes back on this
+  from_id           INTEGER,           -- Telegram user_id allowed to answer; claimed on first tap
+  callback_token    TEXT NOT NULL,     -- 128-bit; defeats forged/guessed callback_data
+  questions_json    TEXT NOT NULL,     -- the ask call's questions array
+  state_json        TEXT NOT NULL,     -- the question-state machine state
+  message_ids_json  TEXT,              -- Telegram msg_id(s) of the keyboard message to edit/strip
+  awaiting_other    INTEGER NOT NULL DEFAULT 0,  -- 1 while capturing a free-text "Other"
+  status            TEXT NOT NULL
+    CHECK(status IN ('pending','answered','cancelled','timeout','expired'))
+    DEFAULT 'pending',
+  created_ts        INTEGER NOT NULL,
+  timeout_ts        INTEGER NOT NULL,
+  answered_ts       INTEGER
+);
+
+CREATE INDEX idx_pq_open      ON pending_questions(session_key, status) WHERE status = 'pending';
+CREATE INDEX idx_pq_timeout   ON pending_questions(status, timeout_ts)  WHERE status = 'pending';
+CREATE INDEX idx_pq_tool_call ON pending_questions(tool_call_id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polygram",
-  "version": "0.12.0-rc.29",
+  "version": "0.12.0-rc.30",
   "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
   "main": "lib/ipc/client.js",
   "bin": {

package/polygram.js

@@ -56,6 +56,8 @@ const { sweepTmuxOrphans } = require('./lib/tmux/orphan-sweep');
 const { createAutosteeredRefs } = require('./lib/autosteered-refs');
 const { createBuildSdkOptions } = require('./lib/sdk/build-options');
 const { createSdkCallbacks } = require('./lib/sdk/callbacks');
+const { createQuestionStore } = require('./lib/questions/store');
+const { createQuestionHandlers } = require('./lib/handlers/questions');
 const { createTranscribeVoiceAttachments } = require('./lib/handlers/voice');
 const { createDownloadAttachments } = require('./lib/handlers/download');
 const { createHandleConfigCallback } = require('./lib/handlers/config-callback');
@@ -644,6 +646,9 @@ let maybeInjectEditCorrection = null;
 // approvals store are available.
 let makeCanUseTool = null;
 let handleApprovalCallback = null;
+// 0.12 interactive questions — assigned in main() once db.raw + pm exist; the
+// createSdkCallbacks onQuestionAsked closure + the callback router read it late.
+let questionHandlers = null;
 let resolveApprovalWaiter = null;
 let startApprovalSweeper = null;
 let cancelAllWaiters = null;
@@ -1854,14 +1859,29 @@ function createBot(token) {
       return;
     }
 
-    if (!shouldHandle(msg, chatConfig, botUsername)) return;
+    const threadId = msg.message_thread_id?.toString();
+    const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+
+    // 0.12 interactive questions: the owner's free-text "Other" answer arrives
+    // WITHOUT an @mention, so in a mention-gated group shouldHandle would reject
+    // it and the "Other" flow would silently dead-end. Let the claimed owner's
+    // typed answer bypass the gate (owner-only; bystanders still respect it).
+    const ownsOpenOther = questionHandlers
+      ? questionHandlers.isAwaitingOtherFrom(sessionKey, msg.from?.id)
+      : false;
+    if (!ownsOpenOther && !shouldHandle(msg, chatConfig, botUsername)) return;
 
     if (botUsername) {
       msg.text = cleanText;
     }
 
-    const threadId = msg.message_thread_id?.toString();
-    const sessionKey = getSessionKey(chatId, threadId, chatConfig);
+    // A typed message while a question is in free-text capture for this
+    // session+user becomes the answer (not a new turn). Only an in-progress
+    // "Other" diverts; ordinary chatter and /commands fall through.
+    if (questionHandlers) {
+      const r = await questionHandlers.tryConsumeAsAnswer({ sessionKey, fromId: msg.from?.id, text: cleanText });
+      if (r.consumed) return;
+    }
     dispatchHandleMessage(sessionKey, chatId, msg, bot);
   };
 
@@ -1975,6 +1995,8 @@ function createBot(token) {
       const data = ctx.callbackQuery.data;
       if (data.startsWith('cfg:')) {
         await handleConfigCallback(ctx);
+      } else if (data.startsWith('q:')) {
+        if (questionHandlers) await questionHandlers.handleQuestionCallback(ctx);
       } else {
         await handleApprovalCallback(ctx);
       }
@@ -2234,6 +2256,9 @@ async function main() {
     // `[react:EMOJI]`, `No response requested.` all leaked as literal text.
     parseResponse, sanitizeAssistantReply, chunkMarkdownText, deliverReplies,
     processAndDeliverAgentText,
+    // 0.12 interactive questions: 'question-asked' (claude called the ask tool)
+    // → render the Telegram keyboard. Late-bound; questionHandlers is assigned below.
+    renderQuestion: (payload) => questionHandlers?.renderAsk(payload),
     logger: console,
   });
   // 0.10.0: sdkCallbacks (the polygram-side lifecycle handlers — status
@@ -2253,6 +2278,23 @@ async function main() {
     config, db, bot, botName: BOT_NAME, tg, logEvent,
     approvals, getChatIdFromKey, logger: console,
   }));
+
+  // 0.12 interactive questions: store + handlers + timeout sweep. answerQuestion
+  // is late-bound to pm (a tap can land minutes later, pm is live by then).
+  const questionStore = createQuestionStore(db.raw);
+  questionHandlers = createQuestionHandlers({
+    questions: questionStore, tg, bot, botName: BOT_NAME, logEvent,
+    answerQuestion: (sk, tc, result) => pm.answerQuestion(sk, tc, result),
+    logger: console,
+  });
+  // Resolve expired questions with {timedout} so claude never hangs on an ignored ask.
+  setInterval(() => {
+    try {
+      for (const row of questionStore.sweepTimedOut()) {
+        questionHandlers.expireQuestion(row).catch((e) => console.error(`[${BOT_NAME}] question expire: ${e.message}`));
+      }
+    } catch (e) { console.error(`[${BOT_NAME}] question sweep: ${e.message}`); }
+  }, 30_000).unref?.();
   buildSdkOptions = createBuildSdkOptions({
     config,
     botName: BOT_NAME,