lsd-pi 1.2.4 → 1.3.2

package/README.md

@@ -1,6 +1,6 @@
 # LSD
 
-**Looks Sort of Done** — a standalone coding-agent CLI built on the Pi SDK. Use all your AI providers and all your loved features from Claude Code, Codex, and Gemini in one place.
+**Looks Sort of Done** — a standalone AI coding-agent CLI built on the Pi SDK. Use all your AI providers and all your loved features from Claude Code, Codex, and Gemini in one place.
 
 ![LSD Screenshot](./lsd.png)
 
@@ -12,24 +12,28 @@ npm install -g lsd-pi@latest
 
 ## What LSD is
 
-LSD is a general-purpose coding agent CLI. It combines:
-
-- **Interactive TUI** inspired by Gemini CLI — including an embedded interactive terminal inside the LSD CLI that both you and the agent can use, so the agent is not blocked by commands or tools that require terminal interaction
-- **Memory system and permission modes** inspired by Claude Code
-- **Sandbox isolation** inspired by Codex
-- **Auto mode** — a classifier-based autonomous execution mode
-- **Remote questions** — relay agent prompts to Telegram, Discord, or Slack so you can respond from your phone
-- **Background subagents, skills, worktrees, sessions, usage tracking, and more**
-
-- **Package:** `lsd-pi`
-- **Binary:** `lsd`
-- **Alt binary:** `lsd-cli`
-- **Project config dir:** `.lsd/`
-- **User config dir:** `~/.lsd/`
+LSD is a general-purpose coding agent that lives in your terminal. It combines:
+
+- **Interactive TUI** with an embedded terminal — both you and the agent can interact with CLI programs, so the agent never gets blocked by interactive commands
+- **Multi-provider LLM support** — Claude, GPT, Gemini, Mistral, Bedrock, Vertex AI, and more
+- **Persistent memory** — remembers your preferences and project context across sessions
+- **Browser automation** — full Playwright integration for web testing and scraping
+- **Code intelligence** — LSP-based navigation (go-to-definition, references, rename) in typed codebases
+- **Auto mode** — classifier-based autonomous execution for low-risk operations
+- **Remote questions** — relay prompts to Telegram, Discord, or Slack so you can respond from your phone
+- **Background subagents** — delegate tasks to isolated workers (scout, reviewer, planner)
+- **Worktrees** — isolated git branches for parallel workstreams
+- **Sessions** — resumable conversation history per project directory
+- **Voice input** — speak your prompts (macOS native, Linux via Groq)
+- **Usage tracking** — token consumption and cost reporting
+- **~25 bundled extensions** — memory, browser-tools, subagent, codex-rotate, search, and more
+- **Sandbox isolation** — restrict filesystem writes to the project directory
+
+**Package:** `lsd-pi` · **Binary:** `lsd` · **Project config:** `.lsd/` · **User config:** `~/.lsd/`
 
 ### Fork lineage
 
-LSD is a fork of **GSD 2**. The GSD-specific project workflow layer was stripped out. LSD is centered on being a general-purpose coding agent CLI — the agent shell, tools, TUI, browser tools, sessions, worktrees, and integrations remain core.
+LSD is a fork of **GSD 2** with the GSD-specific project workflow layer stripped out. The agent shell, tools, TUI, browser automation, sessions, worktrees, and integrations remain core.
 
 ---
 
@@ -675,6 +679,8 @@ See [`docs/`](./docs/) for deeper details:
 - [Skills](./docs/skills.md)
 - [Custom Models](./docs/custom-models.md)
 
+For contributors: [LEARNING.md](./LEARNING.md) is the developer onboarding guide.
+
 ---
 
 ## Development

package/dist/app-paths.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Central path constants for the entire app. Everything resolves off appRoot
+ * (defaults to ~/.lsd, overridable via LSD_HOME / GSD_HOME env vars).
+ */
 export declare const appRoot: string;
 export declare const agentDir: string;
 export declare const sessionsDir: string;

package/dist/app-paths.js

@@ -1,3 +1,7 @@
+/**
+ * Central path constants for the entire app. Everything resolves off appRoot
+ * (defaults to ~/.lsd, overridable via LSD_HOME / GSD_HOME env vars).
+ */
 import { homedir } from 'os';
 import { join } from 'path';
 export const appRoot = process.env.LSD_HOME || process.env.GSD_HOME || join(homedir(), '.lsd');

package/dist/bedrock-auth.d.ts

@@ -1,3 +1,7 @@
+/**
+ * AWS Bedrock credential handling — encodes/decodes SSO or access-key credentials
+ * to JSON for storage in auth.json, and hydrates AWS_* env vars at runtime.
+ */
 import type { AuthStorage } from '@gsd/pi-coding-agent';
 export declare const BEDROCK_PROVIDER_ID = "amazon-bedrock";
 export type BedrockCredentialInput = {

package/dist/bedrock-auth.js

@@ -1,3 +1,7 @@
+/**
+ * AWS Bedrock credential handling — encodes/decodes SSO or access-key credentials
+ * to JSON for storage in auth.json, and hydrates AWS_* env vars at runtime.
+ */
 export const BEDROCK_PROVIDER_ID = 'amazon-bedrock';
 export function encodeBedrockCredential(credential) {
     return JSON.stringify({ version: 1, ...credential });

package/dist/bundled-extension-paths.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Serializes/deserializes extension file paths to a delimiter-separated string
+ * so they can be passed via the LSD_BUNDLED_EXTENSIONS env var between loader.ts and cli.ts.
+ */
 export declare function serializeBundledExtensionPaths(paths: readonly string[], pathDelimiter?: ";" | ":"): string;
 export declare function parseBundledExtensionPaths(value: string | undefined, pathDelimiter?: ";" | ":"): string[];

package/dist/bundled-extension-paths.js

@@ -1,3 +1,7 @@
+/**
+ * Serializes/deserializes extension file paths to a delimiter-separated string
+ * so they can be passed via the LSD_BUNDLED_EXTENSIONS env var between loader.ts and cli.ts.
+ */
 import { delimiter } from "node:path";
 export function serializeBundledExtensionPaths(paths, pathDelimiter = delimiter) {
     return paths.filter(Boolean).join(pathDelimiter);

package/dist/cli-theme.d.ts

@@ -3,10 +3,10 @@
  * output (welcome screen, sessions list, worktree CLI, update prompt, onboarding).
  *
  * Colors are read lazily from active theme via getResolvedThemeColors() so
- * that custom user themes propagate to CLI output automatically.
+ * that custom user themes and accent presets propagate to CLI output automatically.
  * Falls back to built-in dark-theme defaults if the theme cannot be loaded.
  */
-/** Returns an accent hex color from the active theme (e.g. `'#4a8cf7'`). */
+/** Returns the accent hex color from the active theme (e.g. `'#4a8cf7'`). */
 export declare function accentHex(): string;
 /** Wrap text in the theme's accent color using raw ANSI 24-bit escapes. */
 export declare const accentAnsi: (s: string) => string;

package/dist/cli-theme.js

@@ -3,27 +3,26 @@
  * output (welcome screen, sessions list, worktree CLI, update prompt, onboarding).
  *
  * Colors are read lazily from active theme via getResolvedThemeColors() so
- * that custom user themes propagate to CLI output automatically.
+ * that custom user themes and accent presets propagate to CLI output automatically.
  * Falls back to built-in dark-theme defaults if the theme cannot be loaded.
  */
 import { getResolvedThemeColors } from '@gsd/pi-coding-agent';
-// ── Lazy theme cache ─────────────────────────────────────────────────────────
-let _colors = null;
+// ── Theme color resolver ──────────────────────────────────────────────────────
+// Not cached — getResolvedThemeColors() reads the globalThis theme instance which
+// is updated whenever initTheme() or setTheme() is called (e.g. by cli.ts before
+// the welcome screen, or by InteractiveMode when the user changes the accent).
 function colors() {
-    if (!_colors) {
-        try {
-            const resolved = getResolvedThemeColors();
-            _colors = resolved ?? { accent: '#4a8cf7', borderAccent: '#4a8cf7', borderMuted: '#1e3a8a' };
-        }
-        catch {
-            // Theme not yet on disk (first run) — use built-in dark defaults
-            _colors = { accent: '#4a8cf7', borderAccent: '#4a8cf7', borderMuted: '#1e3a8a' };
-        }
+    try {
+        const resolved = getResolvedThemeColors();
+        return resolved ?? { accent: '#4a8cf7', borderAccent: '#4a8cf7', borderMuted: '#1e3a8a' };
+    }
+    catch {
+        // Theme not yet initialised (first run) — use built-in dark defaults
+        return { accent: '#4a8cf7', borderAccent: '#4a8cf7', borderMuted: '#1e3a8a' };
     }
-    return _colors;
 }
 // ── Hex accessor (for chalk.hex()) ───────────────────────────────────────────
-/** Returns an accent hex color from the active theme (e.g. `'#4a8cf7'`). */
+/** Returns the accent hex color from the active theme (e.g. `'#4a8cf7'`). */
 export function accentHex() {
     return colors().accent ?? '#4a8cf7';
 }

package/dist/cli.js

@@ -1,4 +1,4 @@
-import { AuthStorage, DefaultResourceLoader, ModelRegistry, runPackageCommand, SettingsManager, SessionManager, createAgentSession, allBuiltInTools, InteractiveMode, resetStdinForTui, runPrintMode, runRpcMode, } from '@gsd/pi-coding-agent';
+import { AuthStorage, DefaultResourceLoader, ModelRegistry, runPackageCommand, SettingsManager, SessionManager, createAgentSession, allBuiltInTools, InteractiveMode, resetStdinForTui, runPrintMode, runRpcMode, initTheme, } from '@gsd/pi-coding-agent';
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -55,6 +55,21 @@ function parseCliArgs(argv) {
         else if (arg === '--no-session') {
             flags.noSession = true;
         }
+        else if (arg === '--parent-session' && i + 1 < args.length) {
+            flags.parentSession = args[++i];
+        }
+        else if (arg === '--subagent-name' && i + 1 < args.length) {
+            flags.subagentName = args[++i];
+        }
+        else if (arg === '--subagent-task' && i + 1 < args.length) {
+            flags.subagentTask = args[++i];
+        }
+        else if (arg === '--subagent-tools' && i + 1 < args.length) {
+            flags.subagentTools = args[++i].split(',').filter(Boolean);
+        }
+        else if (arg === '--subagent-system-prompt-file' && i + 1 < args.length) {
+            flags.subagentSystemPromptFile = args[++i];
+        }
         else if (arg === '--model' && i + 1 < args.length) {
             flags.model = args[++i];
         }
@@ -349,9 +364,29 @@ if (!settingsManager.getCollapseChangelog()) {
 // ---------------------------------------------------------------------------
 if (isPrintMode) {
     await ensureRtkBootstrap();
+    const printCwd = process.cwd();
+    const printSessionsDir = getProjectSessionsDir(printCwd);
     const sessionManager = cliFlags.noSession
-        ? SessionManager.inMemory()
-        : SessionManager.create(process.cwd());
+        ? SessionManager.inMemory(printCwd)
+        : SessionManager.create(printCwd, printSessionsDir);
+    let subagentSystemPrompt;
+    if (cliFlags.subagentSystemPromptFile) {
+        try {
+            subagentSystemPrompt = readFileSync(cliFlags.subagentSystemPromptFile, 'utf-8');
+        }
+        catch {
+            subagentSystemPrompt = undefined;
+        }
+    }
+    if (!cliFlags.noSession && (cliFlags.parentSession || cliFlags.subagentName || subagentSystemPrompt || cliFlags.subagentTools?.length)) {
+        sessionManager.newSession({
+            parentSession: cliFlags.parentSession,
+            subagentName: cliFlags.subagentName,
+            subagentTask: cliFlags.subagentTask,
+            subagentSystemPrompt,
+            subagentTools: cliFlags.subagentTools,
+        });
+    }
     // Read --append-system-prompt file content (subagent writes agent system prompts to temp files)
     let appendSystemPrompt;
     if (cliFlags.appendSystemPrompt) {
@@ -587,6 +622,11 @@ if (!process.stdin.isTTY || !process.stdout.isTTY) {
     process.stderr.write('[lsd]   lsd headless                   Auto-mode without TUI\n');
     process.exit(1);
 }
+// Initialise the theme (including accent preset) before the welcome screen so
+// that accentHex() returns the user's saved accent colour instead of the
+// base-theme default.  InteractiveMode will call initTheme() again with the
+// file-watcher enabled — this early call is intentionally watcher-free.
+initTheme(settingsManager.getTheme() || undefined, false, settingsManager.getThemeAccent());
 // Welcome screen — shown on every fresh interactive session before TUI takes over.
 // Skip when the first-run banner was already printed in loader.ts (prevents double banner).
 if (!process.env.GSD_FIRST_RUN_BANNER) {

package/dist/codex-rotate-settings.d.ts

@@ -1 +1,5 @@
+/**
+ * Checks whether Codex rotation is enabled for a project, reading from
+ * project settings, global settings, or preferences YAML (in that priority order).
+ */
 export declare function isCodexRotateEnabled(basePath?: string): boolean;

package/dist/codex-rotate-settings.js

@@ -1,3 +1,7 @@
+/**
+ * Checks whether Codex rotation is enabled for a project, reading from
+ * project settings, global settings, or preferences YAML (in that priority order).
+ */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { agentDir } from './app-paths.js';

package/dist/help-text.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Help text for every `lsd` subcommand. Rendered by the CLI when the user
+ * passes --help or an unknown subcommand.
+ */
 export declare function printHelp(version: string): void;
 export declare function printSubcommandHelp(subcommand: string, version: string): boolean;

package/dist/help-text.js

@@ -1,3 +1,7 @@
+/**
+ * Help text for every `lsd` subcommand. Rendered by the CLI when the user
+ * passes --help or an unknown subcommand.
+ */
 const SUBCOMMAND_HELP = {
     config: [
         'Usage: lsd config',

package/dist/lsd-brand.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Brand color constants (yellow/blue/pink) and chalk helpers for consistent
+ * terminal theming across the CLI.
+ */
 export declare const LSD_YELLOW = "#facc15";
 export declare const LSD_BLUE = "#3b82f6";
 export declare const LSD_PINK = "#ec4899";

package/dist/lsd-brand.js

@@ -1,3 +1,7 @@
+/**
+ * Brand color constants (yellow/blue/pink) and chalk helpers for consistent
+ * terminal theming across the CLI.
+ */
 import chalk from 'chalk';
 export const LSD_YELLOW = '#facc15';
 export const LSD_BLUE = '#3b82f6';

package/dist/onboarding-llm.d.ts

@@ -1,3 +1,8 @@
+/**
+ * LLM provider registry and onboarding wizard helpers — lists available providers,
+ * presents picker options for browser vs API-key auth flows, and decides whether
+ * the first-run onboarding should trigger.
+ */
 import type { AuthStorage } from '@gsd/pi-coding-agent';
 export { BEDROCK_PROVIDER_ID } from './bedrock-auth.js';
 export type LlmProviderOption = {

package/dist/onboarding-llm.js

@@ -1,3 +1,8 @@
+/**
+ * LLM provider registry and onboarding wizard helpers — lists available providers,
+ * presents picker options for browser vs API-key auth flows, and decides whether
+ * the first-run onboarding should trigger.
+ */
 import { BEDROCK_PROVIDER_ID } from './bedrock-auth.js';
 export { BEDROCK_PROVIDER_ID } from './bedrock-auth.js';
 export const LLM_PROVIDER_IDS = [

package/dist/project-sessions.d.ts

@@ -1 +1,5 @@
+/**
+ * Encodes a project directory path into a safe directory name for per-project
+ * session storage under ~/.lsd/sessions/ (e.g. "/Users/alice/my-app" → "--Users-alice-my-app--").
+ */
 export declare function getProjectSessionsDir(cwd: string, baseSessionsDir?: string): string;

package/dist/project-sessions.js

@@ -1,3 +1,7 @@
+/**
+ * Encodes a project directory path into a safe directory name for per-project
+ * session storage under ~/.lsd/sessions/ (e.g. "/Users/alice/my-app" → "--Users-alice-my-app--").
+ */
 import { join } from "node:path";
 import { sessionsDir as defaultSessionsDir } from "./app-paths.js";
 export function getProjectSessionsDir(cwd, baseSessionsDir = defaultSessionsDir) {

package/dist/resources/agents/generic.md

@@ -12,6 +12,7 @@ Guidelines:
 - Prefer straightforward execution over elaborate planning.
 - If the task clearly belongs to a specialist domain (for example deep codebase recon or web research), you may say so in your notes, but still complete the assigned task when possible.
 - Do **not** spawn additional subagents unless the parent task explicitly tells you to do so.
+- Do **not** call `ask_user_questions`. There is no human available. Make reasonable autonomous decisions.
 - Keep your final handoff concise and actionable.
 
 Output format when finished:

package/dist/resources/agents/scout.md

@@ -1,7 +1,7 @@
 ---
 name: scout
 description: Fast codebase recon that returns compressed context for handoff to other agents
-tools: read, lsp, grep, find, ls, bash
+tools: read, lsp, grep, find, ls
 model: $budget_model
 ---
 
@@ -9,6 +9,13 @@ You are a scout. Quickly investigate a codebase and return structured findings t
 
 Your output will be passed to an agent who has NOT seen the files you explored.
 
+Read-only constraint (strict):
+- You are a **read-only** reconnaissance agent.
+- Never modify files, never run code that writes to disk, and never perform any mutating/refactoring operation.
+- Allowed operations are limited to inspection and navigation.
+- With LSP, use read-only actions only (e.g., symbols, definition, references, hover, diagnostics, incoming/outgoing calls). Do **not** use rename, format, or code actions that apply edits.
+- Do **not** call `ask_user_questions`. There is no human available. Operate fully autonomously.
+
 Scope boundary:
 - Scout is for reconnaissance and mapping only.
 - Do **not** perform full code review, security audit, bug triage, ranking of issues, or final recommendations as if you were the reviewer.

package/dist/resources/agents/worker.md

@@ -8,6 +8,7 @@ You are a worker agent with full capabilities. You operate in an isolated contex
 Work autonomously to complete the assigned task. Use all available tools as needed, with one important restriction:
 
 - Do **not** spawn subagents or act as an orchestrator unless the parent task explicitly instructs you to do so.
+- Do **not** call `ask_user_questions`. There is no human available. Make reasonable autonomous decisions.
 - If the task looks like GSD orchestration, planning, scouting, parallel dispatch, or review routing, stop and report that the caller should use the appropriate specialist agent instead (for example: `gsd-worker`, `gsd-scout`, `gsd-reviewer`, or the top-level orchestrator).
 - In particular, do **not** call `gsd_scout`, `subagent`, `launch_parallel_view`, or `gsd_execute_parallel` on your own initiative.
 

package/dist/resources/extensions/ask-user-questions.js

@@ -18,6 +18,13 @@ const OptionSchema = Type.Object({
     label: Type.String({ description: "User-facing label (1-5 words)" }),
     description: Type.String({ description: "One short sentence explaining impact/tradeoff if selected" }),
 });
+const ShowWhenSchema = Type.Object({
+    questionId: Type.String({ description: "Earlier question id this question depends on" }),
+    selectedAnyOf: Type.Array(Type.String(), {
+        description: "Show this question only when the earlier question selection includes one of these labels",
+        minItems: 1,
+    }),
+});
 const QuestionSchema = Type.Object({
     id: Type.String({ description: "Stable identifier for mapping answers (snake_case)" }),
     header: Type.String({ description: "Short header label shown in the UI (12 or fewer chars)" }),
@@ -28,6 +35,7 @@ const QuestionSchema = Type.Object({
     allowMultiple: Type.Optional(Type.Boolean({
         description: "If true, the user can select multiple options using SPACE to toggle and ENTER to confirm. No 'None of the above' option is added. Default: false.",
     })),
+    showWhen: Type.Optional(ShowWhenSchema),
 });
 const AskUserQuestionsParams = Type.Object({
     questions: Type.Array(QuestionSchema, {
@@ -43,6 +51,34 @@ function errorResult(message, questions = []) {
     };
 }
 /** Convert the shared RoundResult into the JSON the LLM expects. */
+function selectedLabels(answer) {
+    if (!answer)
+        return [];
+    return answer.answers.filter((item) => typeof item === "string" && !item.startsWith("user_note:"));
+}
+function shouldAskQuestion(question, answers) {
+    if (!question.showWhen)
+        return true;
+    const controlling = answers[question.showWhen.questionId];
+    if (!controlling)
+        return false;
+    const selected = selectedLabels(controlling);
+    return selected.some((label) => question.showWhen?.selectedAnyOf.includes(label));
+}
+function selectedRoundLabels(answer) {
+    if (!answer)
+        return [];
+    return (Array.isArray(answer.selected) ? answer.selected : [answer.selected]).filter((item) => typeof item === "string" && item.length > 0);
+}
+function shouldRenderRoundQuestion(question, answers) {
+    if (!question.showWhen)
+        return true;
+    const controlling = answers[question.showWhen.questionId];
+    if (!controlling)
+        return false;
+    const selected = selectedRoundLabels(controlling);
+    return selected.some((label) => question.showWhen?.selectedAnyOf.includes(label));
+}
 function formatForLLM(result) {
     const answers = {};
     for (const [id, answer] of Object.entries(result.answers)) {
@@ -71,6 +107,7 @@ export default function AskUserQuestions(pi) {
             "Keep questions to 1 when possible; never exceed 3.",
             "For single-select: each question must have 2-3 options. Put the recommended option first with '(Recommended)' suffix. Do not include an 'Other' or 'None of the above' option - the client adds one automatically.",
             "For multi-select: set allowMultiple: true. The user can pick any number of options. No 'None of the above' is added.",
+            "For conditional follow-ups, use showWhen.questionId and showWhen.selectedAnyOf on a later question so it only appears after the matching earlier answer.",
         ],
         parameters: AskUserQuestionsParams,
         async execute(_toolCallId, params, signal, _onUpdate, ctx) {
@@ -83,6 +120,32 @@ export default function AskUserQuestions(pi) {
                     return errorResult(`Error: ask_user_questions requires non-empty options for every question (question "${q.id}" has none)`, params.questions);
                 }
             }
+            for (let i = 0; i < params.questions.length; i++) {
+                const q = params.questions[i];
+                if (!q.showWhen)
+                    continue;
+                const controllerIndex = params.questions.findIndex((candidate) => candidate.id === q.showWhen?.questionId);
+                if (controllerIndex < 0 || controllerIndex >= i) {
+                    return errorResult(`Error: question "${q.id}" has invalid showWhen.questionId "${q.showWhen.questionId}" (must reference an earlier question id)`, params.questions);
+                }
+                if (!q.showWhen.selectedAnyOf || q.showWhen.selectedAnyOf.length === 0) {
+                    return errorResult(`Error: question "${q.id}" showWhen.selectedAnyOf must include at least one option label`, params.questions);
+                }
+                const controller = params.questions[controllerIndex];
+                const validLabels = [
+                    ...controller.options.map((option) => option.label),
+                    ...(!controller.allowMultiple ? [OTHER_OPTION_LABEL] : []),
+                ];
+                const invalidLabels = q.showWhen.selectedAnyOf.filter((label) => !validLabels.includes(label));
+                if (invalidLabels.length > 0) {
+                    return errorResult(`Error: question "${q.id}" showWhen.selectedAnyOf contains unknown option labels: ${invalidLabels.join(", ")}`, params.questions);
+                }
+            }
+            // Subagents have no human to respond — fail fast and tell the model to decide autonomously.
+            if (process.argv.includes('--subagent-name')) {
+                return errorResult("Error: ask_user_questions cannot be used inside a subagent. " +
+                    "There is no human available. Make a reasonable autonomous decision and proceed.", params.questions);
+            }
             if (!ctx.hasUI) {
                 return errorResult("Error: UI not available (non-interactive mode)", params.questions);
             }
@@ -94,6 +157,9 @@ export default function AskUserQuestions(pi) {
             if (!result) {
                 const answers = {};
                 for (const q of params.questions) {
+                    if (!shouldAskQuestion(q, answers)) {
+                        continue;
+                    }
                     const options = q.options.map((o) => o.label);
                     if (!q.allowMultiple) {
                         options.push(OTHER_OPTION_LABEL);
@@ -185,6 +251,8 @@ export default function AskUserQuestions(pi) {
                 lines.push(theme.fg("dim", details.channel));
                 if (details.response) {
                     for (const q of questions) {
+                        if (!shouldAskQuestion(q, details.response.answers))
+                            continue;
                         const answer = details.response.answers[q.id];
                         if (!answer) {
                             lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
@@ -205,6 +273,8 @@ export default function AskUserQuestions(pi) {
             }
             const lines = [];
             for (const q of details.questions) {
+                if (!shouldRenderRoundQuestion(q, details.response.answers))
+                    continue;
                 const answer = details.response.answers[q.id];
                 if (!answer) {
                     lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);

package/dist/resources/extensions/bg-shell/bg-shell-tool.js

@@ -23,22 +23,12 @@ export function registerBgShellTool(pi, state) {
             "signal (send OS signal), list (all processes with status), kill (terminate), restart (kill + relaunch), " +
             "group_status (health of a process group), highlights (significant output lines only).",
         promptGuidelines: [
-            "Use bg_shell to start long-running processes (servers, watchers, builds) that should not block the agent.",
-            "After starting a server, use 'wait_for_ready' to efficiently block until it's listening — avoids polling loops entirely.",
-            "Use 'digest' instead of 'output' when you just need status — it returns a structured ~30-token summary instead of ~2000 tokens of raw output.",
-            "Use 'highlights' to see only significant output (errors, URLs, results) — typically 5-15 lines instead of hundreds.",
-            "Use 'output' only when you need raw lines for debugging — add filter:'error|warning' to narrow results.",
-            "The 'output' action returns only new output since the last check (incremental). Repeated calls are cheap on context.",
-            "Set type:'server' and ready_port:3000 for dev servers so readiness detection is automatic.",
-            "Set group:'my-stack' on related processes to manage them together with 'group_status'.",
-            "Use 'run' to execute a command on a persistent shell session and block until it completes — returns structured output + exit code. Shell state (env vars, cwd, virtualenvs) persists across runs.",
-            "Use 'send_and_wait' for interactive CLIs: send input and wait for expected output pattern.",
-            "Use 'env' to check the current working directory and active environment variables of a shell session — useful after cd, source, or export commands.",
-            "Background processes are session-scoped by default: a new session reaps them unless you set persist_across_sessions:true.",
-            "Use 'restart' to kill and relaunch with the same config — preserves restart count.",
-            "Background processes are auto-classified (server/build/test/watcher) based on the command.",
-            "Process crashes and errors are automatically surfaced as alerts at the start of your next turn — you don't need to poll.",
-            "To create a persistent shell session: bg_shell start with type:'shell'. The session stays alive for interactive use with 'send', 'send_and_wait', or 'run'.",
+            "Use bg_shell for long-running processes (servers, watchers, builds). Set type:'server' and ready_port for dev servers.",
+            "Use 'digest' for status (~30 tokens), 'highlights' for key output, 'output' only for raw debugging. All are incremental.",
+            "Use 'run' to execute a command on a persistent shell (state persists). Use 'send_and_wait' for interactive CLIs.",
+            "Use 'wait_for_ready' after starting a server — blocks until the port/pattern matches.",
+            "Use group:'name' to manage related processes together; 'group_status' for health.",
+            "Crashes are auto-surfaced next turn. Use persist_across_sessions:true to survive session restarts.",
         ],
         parameters: Type.Object({
             action: StringEnum([