@phnx-labs/agents-cli 1.20.50 → 1.20.51

package/dist/lib/session/discover.js

@@ -13,6 +13,7 @@ import * as crypto from 'crypto';
 import * as readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import Database from '../sqlite.js';
 import { getAgentsDir, getHistoryDir } from '../state.js';
 const execFileAsync = promisify(execFile);
 import { AGENTS, agentConfigDirName, getCliVersion } from '../agents.js';
@@ -485,6 +486,7 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             ticketId: scan.ticketId,
             createdTickets: scan.createdTickets,
             spawnedTeam: scan.spawnedTeam,
+            plan: scan.plan,
         };
     }
     else {
@@ -510,6 +512,7 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             ticketId: scan.ticketId,
             createdTickets: scan.createdTickets,
             spawnedTeam: scan.spawnedTeam,
+            plan: scan.plan,
         };
     }
     return { meta, content: scan.contentText || '' };
@@ -1065,20 +1068,29 @@ let cachedOpenCodeAccount;
 async function getOpenCodeAccount() {
     if (cachedOpenCodeAccount !== undefined)
         return cachedOpenCodeAccount || undefined;
+    // Read through the node/bun SQLite wrapper (not the `sqlite3` CLI) so this
+    // works on every OS — the CLI is absent on Windows.
+    let db;
     try {
         if (fs.existsSync(OPENCODE_DB)) {
-            const { stdout } = await execFileAsync('sqlite3', [
-                OPENCODE_DB,
-                'SELECT email FROM control_account WHERE active=1 LIMIT 1;',
-            ], { encoding: 'utf-8' });
-            const out = stdout.trim();
+            db = new Database(OPENCODE_DB);
+            const row = db
+                .prepare('SELECT email FROM control_account WHERE active=1 LIMIT 1;')
+                .get();
+            const out = typeof row?.email === 'string' ? row.email.trim() : '';
             if (out) {
                 cachedOpenCodeAccount = out;
                 return out;
             }
         }
     }
-    catch { /* sqlite3 unavailable or DB locked */ }
+    catch { /* DB not accessible, sqlite module unavailable, or query failed */ }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* best-effort close */ }
+    }
     cachedOpenCodeAccount = '';
     return undefined;
 }
@@ -1101,18 +1113,21 @@ async function scanOpenCodeIncremental() {
     }
     const account = await getOpenCodeAccount();
     const currentVersion = await getCurrentAgentVersion('opencode');
+    // Read through the node/bun SQLite wrapper (not the `sqlite3` CLI) so this
+    // works on every OS — the CLI is absent on Windows.
+    let db;
     try {
         const query = `
       SELECT
-        s.id,
-        s.title,
-        s.directory,
-        s.version,
-        s.time_created,
-        s.time_updated,
-        COALESCE(stats.message_count, 0),
-        stats.token_count,
-        COALESCE(stats.has_token_data, 0)
+        s.id AS id,
+        s.title AS title,
+        s.directory AS directory,
+        s.version AS version,
+        s.time_created AS time_created,
+        s.time_updated AS time_updated,
+        COALESCE(stats.message_count, 0) AS message_count,
+        stats.token_count AS token_count,
+        COALESCE(stats.has_token_data, 0) AS has_token_data
       FROM session s
       LEFT JOIN (
         SELECT
@@ -1133,23 +1148,22 @@ async function scanOpenCodeIncremental() {
       ORDER BY time_created DESC
       LIMIT 1000;
     `.replace(/\n/g, ' ');
-        const { stdout: out } = await execFileAsync('sqlite3', ['-separator', '|||', OPENCODE_DB, query], {
-            encoding: 'utf-8',
-            timeout: 5000,
-            maxBuffer: 32 * 1024 * 1024,
-        });
+        db = new Database(OPENCODE_DB);
+        const rows = db.prepare(query).all();
         const entries = [];
-        for (const line of out.split('\n')) {
-            if (!line.trim())
-                continue;
-            const [id, title, directory, version, timeCreatedStr, timeUpdatedStr, messageCountStr, tokenCountStr, hasTokenDataStr] = line.split('|||');
+        for (const row of rows) {
+            const id = typeof row.id === 'string' ? row.id : '';
             if (!id)
                 continue;
-            const timeCreated = parseInt(timeCreatedStr, 10);
-            const timeUpdated = parseInt(timeUpdatedStr, 10);
-            const messageCount = parseInt(messageCountStr, 10);
-            const tokenCount = parseInt(tokenCountStr, 10);
-            const hasTokenData = hasTokenDataStr === '1';
+            const title = typeof row.title === 'string' ? row.title : '';
+            const directory = typeof row.directory === 'string' ? row.directory : '';
+            const version = typeof row.version === 'string' ? row.version : '';
+            const asInt = (v) => typeof v === 'number' ? v : parseInt(String(v), 10);
+            const timeCreated = asInt(row.time_created);
+            const timeUpdated = asInt(row.time_updated);
+            const messageCount = asInt(row.message_count);
+            const tokenCount = asInt(row.token_count);
+            const hasTokenData = asInt(row.has_token_data) === 1;
             const timestamp = isNaN(timeCreated) ? new Date().toISOString() : new Date(timeCreated).toISOString();
             // OpenCode is one shared DB, not one file per session — its row carries a
             // per-session updated time. Set lastActivity explicitly (falling back to
@@ -1182,6 +1196,12 @@ async function scanOpenCodeIncremental() {
             console.error(`Warning: Could not query OpenCode sessions: ${err.message}`);
         }
     }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* best-effort close */ }
+    }
 }
 // ---------------------------------------------------------------------------
 // OpenClaw
@@ -1770,6 +1790,9 @@ export async function scanClaudeSession(filePath) {
     const createdTickets = new Set();
     const pendingTicketTools = new Set();
     let spawnedTeam;
+    // The LAST ExitPlanMode plan wins so a re-planned session surfaces its most
+    // recent plan, matching the semantic the extension's re-parser relied on.
+    let plan;
     try {
         for await (const line of rl) {
             if (!line.trim())
@@ -1802,6 +1825,14 @@ export async function scanClaudeSession(filePath) {
                     if (typeof b?.id === 'string' && isTicketCreateTool(b?.name, b?.input?.command)) {
                         pendingTicketTools.add(b.id);
                     }
+                    // ExitPlanMode plan markdown — last one wins so a re-planned session
+                    // reports its most recent plan (the semantic parsePlanFromClaudeJsonl
+                    // implemented in the extension).
+                    if (b?.name === 'ExitPlanMode' && typeof b?.input?.plan === 'string') {
+                        const p = b.input.plan.trim();
+                        if (p)
+                            plan = b.input.plan;
+                    }
                 }
             }
             if (pendingTicketTools.size > 0 && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
@@ -1949,6 +1980,7 @@ export async function scanClaudeSession(filePath) {
         ticketId: ticket?.id,
         createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
         spawnedTeam,
+        plan,
     };
 }
 /** Stream a Codex JSONL file and extract scan-level metadata (session ID, cwd, topic, tokens). */
@@ -2152,25 +2184,6 @@ function getOpenClawWorkspaceMap() {
 // ---------------------------------------------------------------------------
 // Utilities
 // ---------------------------------------------------------------------------
-/** Read up to maxLines non-empty lines from the beginning of a file. */
-export function readFirstLines(filePath, maxLines) {
-    return new Promise((resolve) => {
-        const lines = [];
-        const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
-        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-        rl.on('line', (line) => {
-            if (line.trim()) {
-                lines.push(line);
-            }
-            if (lines.length >= maxLines) {
-                rl.close();
-                stream.destroy();
-            }
-        });
-        rl.on('close', () => resolve(lines));
-        rl.on('error', () => resolve(lines));
-    });
-}
 /** Compute the SHA-256 hex digest of a string. */
 function sha256(input) {
     return crypto.createHash('sha256').update(input).digest('hex');

package/dist/lib/session/parse.js

@@ -6,8 +6,8 @@
  * objects suitable for rendering, filtering, and summarization.
  */
 import * as fs from 'fs';
+import { truncate } from '../format.js';
 import * as path from 'path';
-import { execFileSync } from 'child_process';
 import Database from '../sqlite.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
@@ -218,10 +218,6 @@ export function summarizeToolUse(tool, args) {
         }
     }
 }
-/** Truncate a string to n characters, appending '...' if shortened. */
-function truncate(s, n) {
-    return s.length <= n ? s : s.slice(0, n - 3) + '...';
-}
 /** Replace the home directory prefix with ~ for display. */
 function shortenPath(p) {
     const home = process.env.HOME || '';
@@ -1006,45 +1002,50 @@ export function parseOpenCode(filePath) {
     if (!dbPath || !sessionId)
         return [];
     const events = [];
+    // Read through the node/bun SQLite wrapper (not the `sqlite3` CLI) so this
+    // works on every OS — the CLI is absent on Windows.
+    let rows;
+    let db;
     try {
-        // Query messages with their parts, ordered chronologically.
-        // Each row: msg_role ||| part_type ||| part_data (truncated for tool output) ||| msg_time
+        // Query messages with their parts, ordered chronologically. Tool parts are
+        // truncated to keep large tool outputs from bloating memory; the session id
+        // is bound as a parameter rather than interpolated.
         const query = `
       SELECT
-        json_extract(m.data, '$.role'),
-        json_extract(p.data, '$.type'),
+        json_extract(m.data, '$.role') AS role,
+        json_extract(p.data, '$.type') AS part_type,
         CASE
           WHEN json_extract(p.data, '$.type') = 'tool'
           THEN substr(p.data, 1, 2000)
           ELSE p.data
-        END,
-        m.time_created
+        END AS part_data,
+        m.time_created AS time_created
       FROM message m
       JOIN part p ON p.message_id = m.id AND p.session_id = m.session_id
-      WHERE m.session_id = '${sessionId.replace(/'/g, "''")}'
+      WHERE m.session_id = ?
       ORDER BY m.time_created ASC, p.time_created ASC;
     `.replace(/\n/g, ' ');
-        const out = execFileSync('sqlite3', ['-separator', '|||', dbPath, query], {
-            encoding: 'utf-8',
-            timeout: 10000,
-            maxBuffer: 32 * 1024 * 1024,
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        for (const line of out.split('\n')) {
-            if (!line.trim())
-                continue;
-            const sepIdx1 = line.indexOf('|||');
-            if (sepIdx1 === -1)
-                continue;
-            const sepIdx2 = line.indexOf('|||', sepIdx1 + 3);
-            if (sepIdx2 === -1)
-                continue;
-            const sepIdx3 = line.lastIndexOf('|||');
-            const role = line.slice(0, sepIdx1);
-            const partType = line.slice(sepIdx1 + 3, sepIdx2);
-            const partDataStr = line.slice(sepIdx2 + 3, sepIdx3);
-            const timeStr = line.slice(sepIdx3 + 3);
-            const timeMs = parseInt(timeStr, 10);
+        db = new Database(dbPath);
+        rows = db.prepare(query).all(sessionId);
+    }
+    catch {
+        /* DB not accessible, sqlite module unavailable, or query failed */
+        return events;
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* best-effort close */
+        }
+    }
+    try {
+        for (const row of rows) {
+            const role = typeof row.role === 'string' ? row.role : '';
+            const partType = typeof row.part_type === 'string' ? row.part_type : '';
+            const partDataStr = typeof row.part_data === 'string' ? row.part_data : '';
+            const timeMs = typeof row.time_created === 'number' ? row.time_created : parseInt(String(row.time_created), 10);
             const timestamp = isNaN(timeMs) ? new Date().toISOString() : new Date(timeMs).toISOString();
             let partData;
             try {
@@ -1112,7 +1113,7 @@ export function parseOpenCode(filePath) {
         }
     }
     catch {
-        /* DB not accessible or query failed */
+        /* malformed row payload — return what we parsed so far */
     }
     return events;
 }

package/dist/lib/session/render.d.ts

@@ -6,7 +6,7 @@
  * errors, final message). The markdown renderer emits a full conversation
  * transcript. Filtering by role and turn slicing is handled here as well.
  */
-import type { SessionEvent } from './types.js';
+import type { SessionEvent, SessionMeta } from './types.js';
 /**
  * Return absPath relative to cwd; fall back to ~/… then absolute.
  */
@@ -103,7 +103,11 @@ export interface RenderConversationMarkdownOptions {
 }
 export declare function renderConversationMarkdown(events: SessionEvent[], opts?: RenderConversationMarkdownOptions): string;
 /**
- * Render session as JSON (normalized events).
+ * Render one session's JSON output — the shape `agents sessions <id> --json`
+ * emits. When `meta` is provided (the standard path), returns a
+ * `{ session, events }` wrapper so top-level fields (`plan`, `prUrl`, …) that
+ * live on `SessionMeta` are visible without re-parsing events. Legacy
+ * callers that pass no meta still get a bare `SessionEvent[]` array.
  */
-export declare function renderJson(events: SessionEvent[]): string;
+export declare function renderJson(events: SessionEvent[], meta?: SessionMeta): string;
 export {};

package/dist/lib/session/render.js

@@ -7,6 +7,7 @@
  * transcript. Filtering by role and turn slicing is handled here as well.
  */
 import chalk from 'chalk';
+import { truncate } from '../format.js';
 import { summarizeToolUse } from './parse.js';
 import { cleanSessionPrompt, extractSessionTopic } from './prompt.js';
 import { renderMarkdown } from '../markdown.js';
@@ -336,14 +337,14 @@ function renderCommandsSection(cmds, lines) {
                 if (catEntry.signal === 'mid') {
                     // Mid signal: display the bucket key (e.g. ssh→openclaw browser) with aggregate count
                     const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-                    lines.push(`    ${chalk.cyan(truncateCmd(key, 80))}${countSuffix}`);
+                    lines.push(`    ${chalk.cyan(truncate(key, 80))}${countSuffix}`);
                 }
                 else {
                     // High signal: display distinct raw sample commands
                     const distinctSamples = pickDistinct(v.samples, 3);
                     for (const sample of distinctSamples) {
                         const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-                        lines.push(`    ${chalk.cyan(truncateCmd(sample, 80))}${countSuffix}`);
+                        lines.push(`    ${chalk.cyan(truncate(sample, 80))}${countSuffix}`);
                     }
                 }
                 shown++;
@@ -354,7 +355,7 @@ function renderCommandsSection(cmds, lines) {
         lines.push(`  ${chalk.dim('Other')} ${chalk.gray(`(${otherCount})`)}`);
         for (const [, v] of Array.from(otherKeys.entries()).slice(0, 5)) {
             const countSuffix = v.count > 1 ? chalk.gray(` × ${v.count}`) : '';
-            lines.push(`    ${chalk.cyan(truncateCmd(v.samples[0] ?? '', 80))}${countSuffix}`);
+            lines.push(`    ${chalk.cyan(truncate(v.samples[0] ?? '', 80))}${countSuffix}`);
         }
     }
     lines.push('');
@@ -372,9 +373,6 @@ function pickDistinct(samples, max) {
     }
     return result.length > 0 ? result : samples.slice(0, max);
 }
-function truncateCmd(cmd, max) {
-    return cmd.length <= max ? cmd : cmd.slice(0, max - 1) + '…';
-}
 // ── File grouping ─────────────────────────────────────────────────────────────
 /** Group file paths by their parent directory, relative to cwd. */
 function groupByParentDir(paths, cwd) {
@@ -916,10 +914,18 @@ export function renderConversationMarkdown(events, opts = {}) {
     return parts.join('\n\n');
 }
 /**
- * Render session as JSON (normalized events).
+ * Render one session's JSON output — the shape `agents sessions <id> --json`
+ * emits. When `meta` is provided (the standard path), returns a
+ * `{ session, events }` wrapper so top-level fields (`plan`, `prUrl`, …) that
+ * live on `SessionMeta` are visible without re-parsing events. Legacy
+ * callers that pass no meta still get a bare `SessionEvent[]` array.
  */
-export function renderJson(events) {
-    return JSON.stringify(events, null, 2);
+export function renderJson(events, meta) {
+    if (!meta)
+        return JSON.stringify(events, null, 2);
+    // Strip internal-only bookkeeping fields the listing --json path also strips.
+    const { _matchedTerms, _bm25Score, _remote, ...session } = meta;
+    return JSON.stringify({ session, events }, null, 2);
 }
 /** Replace the home directory prefix with ~ for trace display. */
 function shortenPathTrace(p) {

package/dist/lib/session/state.d.ts

@@ -17,6 +17,30 @@
 import type { SessionEvent } from './types.js';
 export type SessionActivity = 'working' | 'waiting_input' | 'idle';
 export type AwaitingReason = 'question' | 'plan_review' | 'permission';
+/** One discrete choice the agent offered the user. */
+export interface QuestionOption {
+    /** The choice label — also what a free-text reply channel sends back. */
+    label: string;
+    /** Optional longer description shown under the label. */
+    description?: string;
+    /**
+     * Selection keystroke for an interactive TUI prompt (AskUserQuestion / plan /
+     * permission are select-lists, not text inputs): a digit ('1'), or 'esc' to
+     * cancel/deny. Absent for a plain prose question, which takes free text.
+     */
+    key?: string;
+}
+/**
+ * The decision an agent handed back to the user, extracted at the SOURCE so every
+ * consumer (Factory panel, teams, cloud) gets the real question + options instead
+ * of re-deriving them from a truncated preview line. `reason` mirrors
+ * {@link AwaitingReason}; `options` is present when the agent offered discrete choices.
+ */
+export interface StructuredQuestion {
+    text: string;
+    reason: AwaitingReason;
+    options?: QuestionOption[];
+}
 export interface DetectedPr {
     url: string;
     number?: number;
@@ -40,6 +64,21 @@ export interface SessionState {
     lastEventKind?: SessionEvent['type'];
     /** Single-line description of the latest turn (message text or tool action). */
     preview?: string;
+    /**
+     * The structured decision the agent is waiting on (question / plan / permission),
+     * with its options when it offered any. Set only when activity is waiting_input.
+     */
+    question?: StructuredQuestion;
+    /**
+     * The plan markdown from the most recent `ExitPlanMode` tool call, surfaced
+     * when `awaitingReason === 'plan_review'`. The state engine detects the
+     * handoff off the same tool event; carrying the plan text alongside it lets
+     * consumers (the Factory NEEDS-YOU panel, `agents sessions <id> --json`)
+     * render the actual plan without re-parsing the transcript.
+     */
+    plan?: string;
+    /** Last few assistant turns (most-recent last), one line each — panel context. */
+    tail?: string[];
     lastActivityMs?: number;
     pr?: DetectedPr;
     worktree?: DetectedWorktree;
@@ -85,6 +124,22 @@ export declare function isTicketCreateTool(name?: string, command?: string): boo
  * take `#<number>`. Returns undefined when neither shape is present.
  */
 export declare function extractCreatedTicket(text?: string): string | undefined;
+/**
+ * Pull the plan markdown out of an `ExitPlanMode` tool_use event's args. The
+ * Claude tool schema is `{ plan: string }`; the transcript parser already
+ * lifts `input` onto `event.args`. Returns undefined for a missing/empty plan
+ * so consumers can rely on `plan?: string` truthiness.
+ */
+export declare function extractPlanText(args?: Record<string, any>): string | undefined;
+/**
+ * Structured question from a Claude `AskUserQuestion` tool call. Its input is
+ * `{ questions: [{ question, header, options: [{label, description}] }] }` and the
+ * whole thing is already parsed onto `event.args` by the transcript parser — this
+ * surfaces the first question + its options (instead of collapsing to a generic
+ * "Asked you a question"). The prompt is a select-list, so each option carries its
+ * 1-based selection digit as `key`.
+ */
+export declare function structuredQuestionFromAsk(args?: Record<string, any>): StructuredQuestion | undefined;
 /**
  * Infer live activity + a preview from a chronological event slice. `pr` /
  * `ticket` / `worktree` are attached by `inferSessionState`; this focuses on the

package/dist/lib/session/state.js

@@ -130,6 +130,69 @@ export function extractCreatedTicket(text) {
         return `#${gh[1]}`;
     return undefined;
 }
+/**
+ * Pull the plan markdown out of an `ExitPlanMode` tool_use event's args. The
+ * Claude tool schema is `{ plan: string }`; the transcript parser already
+ * lifts `input` onto `event.args`. Returns undefined for a missing/empty plan
+ * so consumers can rely on `plan?: string` truthiness.
+ */
+export function extractPlanText(args) {
+    const plan = args?.plan;
+    if (typeof plan !== 'string')
+        return undefined;
+    const trimmed = plan.trim();
+    return trimmed ? plan : undefined;
+}
+/**
+ * Structured question from a Claude `AskUserQuestion` tool call. Its input is
+ * `{ questions: [{ question, header, options: [{label, description}] }] }` and the
+ * whole thing is already parsed onto `event.args` by the transcript parser — this
+ * surfaces the first question + its options (instead of collapsing to a generic
+ * "Asked you a question"). The prompt is a select-list, so each option carries its
+ * 1-based selection digit as `key`.
+ */
+export function structuredQuestionFromAsk(args) {
+    const q = Array.isArray(args?.questions) ? args.questions[0] : undefined;
+    if (!q)
+        return undefined;
+    const text = oneLine(String(q.question ?? q.header ?? '')) || 'Asked you a question';
+    const raw = Array.isArray(q.options) ? q.options : [];
+    const options = [];
+    for (const o of raw) {
+        const label = typeof o === 'string' ? oneLine(o) : o?.label != null ? oneLine(String(o.label)) : '';
+        if (!label)
+            continue;
+        const description = typeof o === 'object' && o?.description != null ? oneLine(String(o.description)) : undefined;
+        options.push({ label, description, key: String(options.length + 1) });
+    }
+    return { text, reason: 'question', options: options.length ? options : undefined };
+}
+/**
+ * Canonical approve/deny choices for an interactive prompt that carries no
+ * agent-supplied option list: Claude's plan-review and permission dialogs. Approve
+ * is reliably option 1; deny/keep-planning maps to ESC, which cancels the prompt in
+ * every variant (2- or 3-option) — safer than guessing a digit that could differ.
+ */
+function planReviewQuestion() {
+    return {
+        text: 'Plan ready — review it',
+        reason: 'plan_review',
+        options: [
+            { label: 'Approve plan', key: '1' },
+            { label: 'Keep planning', key: 'esc' },
+        ],
+    };
+}
+function permissionQuestion(preview) {
+    return {
+        text: preview ? `Permission — ${preview}` : 'Waiting on a permission prompt',
+        reason: 'permission',
+        options: [
+            { label: 'Approve', key: '1' },
+            { label: 'Deny', key: 'esc' },
+        ],
+    };
+}
 /** Does an assistant message read as a question directed at the user? */
 function looksLikeQuestion(text) {
     const t = text.trim();
@@ -177,18 +240,27 @@ export function inferActivity(events, ctx = {}) {
     const lastToolUse = lastOf(meaningful, e => e.type === 'tool_use');
     // The most informative recent line: a message or tool call as-is, but for a
     // trailing tool_result/thinking show the tool *call* that produced it (its
-    // command) rather than a bare "↳ Bash".
+    // command), or — failing that — the last assistant message, rather than a bare
+    // "↳ Bash" or a content-free "thinking…". This is what stops a trailing thinking
+    // block from masking the real turn (the defect behind the "Thinking…" panel).
     const previewSource = !last
         ? undefined
         : last.type === 'message' || last.type === 'tool_use'
             ? last
-            : (lastToolUse ?? last);
+            : (lastToolUse ?? lastMsg ?? last);
+    // Last few assistant turns, most-recent last — context for the decision panel.
+    const tail = meaningful
+        .filter(e => e.type === 'message' && e.role === 'assistant' && e.content)
+        .slice(-3)
+        .map(e => oneLine(e.content ?? ''))
+        .filter(Boolean);
     const base = {
         activity: 'idle',
         lastRole: lastMsg?.role,
         lastEventKind: last?.type,
         lastActivityMs: ctx.mtimeMs,
         preview: previewSource ? describeEvent(previewSource) : undefined,
+        tail: tail.length ? tail : undefined,
     };
     if (!last)
         return base;
@@ -196,12 +268,15 @@ export function inferActivity(events, ctx = {}) {
     // tool and nothing has come after it.
     const lastPlanOrAsk = lastOf(meaningful, e => e.type === 'tool_use' && (e.tool === PLAN_TOOL || e.tool === ASK_TOOL));
     if (lastPlanOrAsk && meaningful.indexOf(lastPlanOrAsk) === meaningful.length - 1) {
-        return {
-            ...base,
-            activity: 'waiting_input',
-            awaitingReason: lastPlanOrAsk.tool === PLAN_TOOL ? 'plan_review' : 'question',
-            preview: lastPlanOrAsk.tool === PLAN_TOOL ? 'Plan ready — awaiting your review' : 'Asked you a question',
-        };
+        if (lastPlanOrAsk.tool === PLAN_TOOL) {
+            const question = planReviewQuestion();
+            const plan = extractPlanText(lastPlanOrAsk.args);
+            return { ...base, activity: 'waiting_input', awaitingReason: 'plan_review', preview: question.text, question, plan };
+        }
+        // AskUserQuestion: surface the real question + options (they're on `args`),
+        // not the generic "Asked you a question" that discarded them.
+        const question = structuredQuestionFromAsk(lastPlanOrAsk.args) ?? { text: 'Asked you a question', reason: 'question' };
+        return { ...base, activity: 'waiting_input', awaitingReason: 'question', preview: question.text, question };
     }
     // Pending tool call (tool_use with no following tool_result): mid-turn.
     if (last.type === 'tool_use') {
@@ -209,7 +284,7 @@ export function inferActivity(events, ctx = {}) {
             return { ...base, activity: 'working' };
         // Alive but the file hasn't moved — likely blocked on a permission prompt.
         if (ctx.pidAlive)
-            return { ...base, activity: 'waiting_input', awaitingReason: 'permission' };
+            return { ...base, activity: 'waiting_input', awaitingReason: 'permission', question: permissionQuestion(base.preview) };
         return { ...base, activity: 'idle' };
     }
     // Thinking or a tool result just landed → agent is mid-turn if recently active.
@@ -223,8 +298,10 @@ export function inferActivity(events, ctx = {}) {
             return { ...base, activity: canWork ? 'working' : 'idle' };
         }
         // Assistant spoke last and stopped. A trailing question → waiting; else idle.
+        // A prose question takes a free-text reply (no select-list), so no options/keys.
         if (looksLikeQuestion(last.content ?? '')) {
-            return { ...base, activity: 'waiting_input', awaitingReason: 'question' };
+            const text = oneLine(last.content ?? '');
+            return { ...base, activity: 'waiting_input', awaitingReason: 'question', question: { text, reason: 'question' } };
         }
         return { ...base, activity: 'idle' };
     }

package/dist/lib/session/types.d.ts

@@ -97,6 +97,15 @@ export interface SessionMeta {
      * `isTeamOrigin` (which marks sessions spawned BY a team).
      */
     spawnedTeam?: string;
+    /**
+     * The plan markdown from the LAST `ExitPlanMode` tool call in the transcript
+     * (Claude sessions only), captured at scan time. Present whenever the session
+     * ever entered plan-review; consumers can pair it with a live
+     * `awaitingReason === 'plan_review'` to decide whether it is still pending.
+     * Fills the gap that forced the Factory extension to re-read raw JSONL to
+     * recover the plan text — the CLI now carries it on the metadata row.
+     */
+    plan?: string;
     /**
      * True when the session was spawned programmatically (SDK entrypoint) rather
      * than by a human at the Claude CLI. Captured at scan time from the JSONL

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 25;
+export declare const SHIM_SCHEMA_VERSION = 26;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -145,8 +145,14 @@ export declare function removeShim(agent: AgentId): boolean;
  *        editor opens the script and the agent never launches. The `.cmd` is
  *        now the only Windows artifact and carries this alias marker so
  *        staleness checks read it directly.
- */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 12;
+ *  v13 — grok aliases resolve the binary from the versioned home's
+ *        .grok/downloads first, then fall back to the global ~/.grok/downloads.
+ *        The old template checked only the global dir, so a `grok@<version>`
+ *        alias failed with "not installed" whenever the binary was staged into
+ *        the versioned home (installer run with GROK_HOME set, or grok
+ *        self-update under the shim).
+ */
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary