@phnx-labs/agents-cli 1.20.50 → 1.20.52

package/dist/lib/session/db.js

@@ -13,7 +13,7 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 const SESSIONS_DIR = getSessionsDir();
 const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. */
-const SCHEMA_VERSION = 10;
+const SCHEMA_VERSION = 11;
 /**
  * Canonicalize a file path for use as a scan_ledger key. The same physical
  * session file is reachable via multiple aliases — `~/.claude/projects/x.jsonl`
@@ -64,7 +64,8 @@ CREATE TABLE IF NOT EXISTS sessions (
   pr_url TEXT,
   pr_number INTEGER,
   worktree_slug TEXT,
-  ticket_id TEXT
+  ticket_id TEXT,
+  plan TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_sessions_timestamp ON sessions(timestamp DESC);
 CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);
@@ -213,6 +214,16 @@ function migrateSchema(db, fromVersion) {
             db.exec(`ALTER TABLE sessions DROP COLUMN name`);
         }
     }
+    if (fromVersion < 11) {
+        // v10 → v11: the Claude scanner now captures the ExitPlanMode plan markdown
+        // at scan time so `agents sessions --json` can surface it without forcing
+        // consumers (the Factory NEEDS-YOU panel) to re-read raw JSONL. Additive
+        // column; rescan to backfill.
+        const cols = db.prepare(`PRAGMA table_info(sessions)`).all();
+        if (!cols.some(c => c.name === 'plan'))
+            db.exec(`ALTER TABLE sessions ADD COLUMN plan TEXT`);
+        db.exec(`DELETE FROM scan_ledger;`);
+    }
 }
 /** Open (or return the cached) sessions database, applying migrations as needed. */
 export function getDB() {
@@ -429,13 +440,13 @@ const upsertSessionStmt = (db) => db.prepare(`
     project, cwd, git_branch, topic, label, message_count, token_count,
     cost_usd, duration_ms,
     file_path, file_mtime_ms, file_size, scanned_at, is_team_origin,
-    pr_url, pr_number, worktree_slug, ticket_id
+    pr_url, pr_number, worktree_slug, ticket_id, plan
   ) VALUES (
     @id, @short_id, @agent, @version, @account, @timestamp, @last_activity,
     @project, @cwd, @git_branch, @topic, @label, @message_count, @token_count,
     @cost_usd, @duration_ms,
     @file_path, @file_mtime_ms, @file_size, @scanned_at, @is_team_origin,
-    @pr_url, @pr_number, @worktree_slug, @ticket_id
+    @pr_url, @pr_number, @worktree_slug, @ticket_id, @plan
   )
   ON CONFLICT(id) DO UPDATE SET
     short_id = excluded.short_id,
@@ -461,7 +472,8 @@ const upsertSessionStmt = (db) => db.prepare(`
     pr_url = excluded.pr_url,
     pr_number = excluded.pr_number,
     worktree_slug = excluded.worktree_slug,
-    ticket_id = excluded.ticket_id
+    ticket_id = excluded.ticket_id,
+    plan = excluded.plan
 `);
 const deleteTextStmt = (db) => db.prepare(`DELETE FROM session_text WHERE session_id = ?`);
 const insertTextStmt = (db) => db.prepare(`INSERT INTO session_text (session_id, label, topic, project, content) VALUES (?, ?, ?, ?, ?)`);
@@ -509,6 +521,7 @@ export function upsertSession(meta, content, scan) {
         pr_number: meta.prNumber ?? null,
         worktree_slug: meta.worktreeSlug ?? null,
         ticket_id: meta.ticketId ?? null,
+        plan: meta.plan ?? null,
     };
     const txn = db.transaction(() => {
         upsert.run(row);
@@ -597,6 +610,7 @@ export function upsertSessionsBatch(entries) {
                     pr_number: meta.prNumber ?? null,
                     worktree_slug: meta.worktreeSlug ?? null,
                     ticket_id: meta.ticketId ?? null,
+                    plan: meta.plan ?? null,
                 });
                 delText.run(meta.id);
                 insText.run(meta.id, meta.label ?? '', meta.topic ?? '', meta.project ?? '', content ?? '');
@@ -769,6 +783,7 @@ function rowToMeta(row) {
         prNumber: row.pr_number ?? undefined,
         worktreeSlug: row.worktree_slug ?? undefined,
         ticketId: row.ticket_id ?? undefined,
+        plan: row.plan ?? undefined,
     };
 }
 /**
@@ -954,26 +969,6 @@ export function topSessionsByCost(n, options = {}) {
         durationMs: r.duration_ms ?? 0,
     }));
 }
-/** Return the set of all file paths currently tracked in the sessions table. */
-export function getAllFilePaths() {
-    const db = getDB();
-    const rows = db.prepare(`SELECT file_path FROM sessions`).all();
-    return new Set(rows.map(r => r.file_path));
-}
-/** Look up sessions by their source file paths. */
-export function getSessionsByFilePaths(paths) {
-    if (paths.length === 0)
-        return new Map();
-    const db = getDB();
-    const placeholders = paths.map(() => '?').join(',');
-    const rows = db
-        .prepare(`SELECT * FROM sessions WHERE file_path IN (${placeholders})`)
-        .all(...paths);
-    const result = new Map();
-    for (const row of rows)
-        result.set(row.file_path, rowToMeta(row));
-    return result;
-}
 /** Look up a single session by its unique ID. */
 export function getSessionById(id) {
     const db = getDB();

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

@@ -68,6 +68,8 @@ interface ClaudeSessionScan {
     createdTickets?: string[];
     /** Team name this session SPAWNED via `agents teams create/add` (not team-of-origin). */
     spawnedTeam?: string;
+    /** Plan markdown from the last ExitPlanMode tool call (Claude sessions only). */
+    plan?: string;
 }
 /**
  * Discover sessions. Scans only files whose (mtime, size) have changed since
@@ -152,8 +154,6 @@ export declare function readCodexMeta(filePath: string, resolveAccount?: () => s
 } | null>;
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 export declare function scanClaudeSession(filePath: string): Promise<ClaudeSessionScan>;
-/** Read up to maxLines non-empty lines from the beginning of a file. */
-export declare function readFirstLines(filePath: string, maxLines: number): Promise<string[]>;
 /** Parse a single Kimi session state.json file to extract session metadata. */
 export declare function readKimiMeta(filePath: string): {
     meta: SessionMeta;

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,13 @@ 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.
+                    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 +1979,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 +2183,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