@pi-unipi/unipi 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",

package/packages/autocomplete/src/constants.ts

@@ -104,6 +104,7 @@ export const COMMAND_REGISTRY: Record<string, string> = {
   "unipi:badge-gen":  "utility",
   "unipi:badge-toggle": "utility",
   "unipi:badge-settings": "utility",
+  "unipi:util-settings": "utility",
 
   // ask-user (1 command)
   "unipi:ask-user-settings": "ask-user",
@@ -193,6 +194,7 @@ export const COMMAND_DESCRIPTIONS: Record<string, string> = {
   "unipi:badge-gen":  "Generate session name via background agent",
   "unipi:badge-toggle": "Configure badge settings (autoGen, badgeEnabled, agentTool)",
   "unipi:badge-settings": "Configure badge settings via TUI overlay",
+  "unipi:util-settings": "Unified settings — badge + diff rendering config",
   "unipi:kanboard":        "Start the kanboard visualization server",
   "unipi:kanboard-doctor": "Diagnose and fix kanboard parser issues",
 

package/packages/compactor/src/commands/index.ts

@@ -27,7 +27,7 @@ export interface CommandDeps {
 }
 
 export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
-  pi.registerCommand("compact", {
+  pi.registerCommand("unipi:compact", {
     description: "Trigger manual compaction with stats",
     handler: async (_args: string, ctx: any) => {
       const result = compactTool();
@@ -39,7 +39,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-recall", {
+  pi.registerCommand("unipi:compact-recall", {
     description: "Search session history (BM25 or regex)",
     handler: async (args: string, ctx: any) => {
       const query = args.trim();
@@ -64,7 +64,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-stats", {
+  pi.registerCommand("unipi:compact-stats", {
     description: "Show context savings dashboard",
     handler: async (_args: string, ctx: any) => {
       if (!deps?.sessionDB || !deps?.contentStore) {
@@ -89,7 +89,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-doctor", {
+  pi.registerCommand("unipi:compact-doctor", {
     description: "Run diagnostics checklist",
     handler: async (_args: string, ctx: any) => {
       if (!deps?.sessionDB || !deps?.contentStore) {
@@ -111,7 +111,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-settings", {
+  pi.registerCommand("unipi:compact-settings", {
     description: "Open TUI settings overlay",
     handler: async (_args: string, ctx: any) => {
       try {
@@ -128,7 +128,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-preset", {
+  pi.registerCommand("unipi:compact-preset", {
     description: "Apply quick preset (opencode/balanced/verbose/minimal)",
     handler: async (args: string, ctx: any) => {
       const presetName = parsePreset(args.trim());
@@ -146,7 +146,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-index", {
+  pi.registerCommand("unipi:compact-index", {
     description: "Index current project files into FTS5",
     handler: async (_args: string, ctx: any) => {
       if (!deps?.contentStore) {
@@ -202,7 +202,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-search", {
+  pi.registerCommand("unipi:compact-search", {
     description: "Search indexed content",
     handler: async (args: string, ctx: any) => {
       const query = args.trim();
@@ -230,7 +230,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("compact-purge", {
+  pi.registerCommand("unipi:compact-purge", {
     description: "Wipe all indexed content from FTS5",
     handler: async (_args: string, ctx: any) => {
       if (!deps?.contentStore) {

package/packages/compactor/src/compaction/hooks.ts

@@ -4,7 +4,6 @@
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { convertToLlm } from "@mariozechner/pi-coding-agent";
-import { writeFileSync } from "node:fs";
 import { compile } from "./summarize.js";
 import { loadConfig } from "../config/manager.js";
 import { buildOwnCut } from "./cut.js";
@@ -21,9 +20,11 @@ const formatTokens = (n: number): string => {
   return String(n);
 };
 
-const dbg = (debug: boolean, data: Record<string, unknown>) => {
+const dbg = (debug: boolean, event: string, data?: Record<string, unknown>) => {
   if (!debug) return;
-  try { writeFileSync("/tmp/compactor-debug.json", JSON.stringify(data, null, 2)); } catch {}
+  const ts = new Date().toISOString().slice(11, 23);
+  const details = data ? " " + JSON.stringify(data) : "";
+  console.error(`[compactor:${ts}] ${event}${details}`);
 };
 
 const previewContent = (content: unknown): string => {
@@ -53,11 +54,16 @@ export function registerCompactionHooks(pi: ExtensionAPI): void {
   pi.on("session_before_compact", (event, ctx) => {
     const { preparation, branchEntries, customInstructions } = event;
     const config = loadConfig();
+    dbg(config.debug, "session_before_compact:enter", { entryCount: (branchEntries as any[])?.length, hasPrevSummary: !!preparation?.previousSummary, isCompactor: customInstructions === COMPACTOR_INSTRUCTION });
 
     const isCompactor = customInstructions === COMPACTOR_INSTRUCTION;
-    if (!isCompactor && !config.overrideDefaultCompaction) return;
+    if (!isCompactor && !config.overrideDefaultCompaction) {
+      dbg(config.debug, "session_before_compact:skip", { reason: "not_compactor_and_no_override" });
+      return;
+    }
 
     const ownCut = buildOwnCut(branchEntries as any[]);
+    dbg(config.debug, "buildOwnCut", { ok: ownCut.ok, reason: !ownCut.ok ? (ownCut as any).reason : undefined });
     if (!ownCut.ok) {
       try {
         ctx?.ui?.notify?.(REASON_MESSAGES[ownCut.reason], "warning");
@@ -90,6 +96,7 @@ export function registerCompactionHooks(pi: ExtensionAPI): void {
       keptTokensEst: Math.round(keptChars / 4),
     };
 
+    dbg(config.debug, "compile", { messageCount: messages.length, hasPrevSummary: !!preparation.previousSummary });
     const summary = compile({
       messages,
       previousSummary: preparation.previousSummary,
@@ -99,7 +106,7 @@ export function registerCompactionHooks(pi: ExtensionAPI): void {
       },
     });
 
-    dbg(config.debug, {
+    dbg(config.debug, "compaction_pipeline", {
       usedOwnCut: true,
       messagesToSummarize: agentMessages.length,
       firstKeptEntryId,
@@ -129,6 +136,8 @@ export function registerCompactionHooks(pi: ExtensionAPI): void {
   });
 
   pi.on("session_compact", (event, ctx) => {
+    const config = loadConfig();
+    dbg(config.debug, "session_compact", { fromExtension: event.fromExtension, lastCompactWasCompactor });
     if (!event.fromExtension) return;
     if (lastCompactWasCompactor) return;
     const stats = lastStats;

package/packages/compactor/src/index.ts

@@ -17,6 +17,16 @@ import { normalizeMessages } from "./compaction/normalize.js";
 import { filterNoise } from "./compaction/filter-noise.js";
 import type { NormalizedBlock } from "./types.js";
 
+/** Debug logger — only logs when config.debug === true */
+function createDebugLogger(getConfig: () => { debug: boolean }) {
+  return (event: string, data?: Record<string, unknown>) => {
+    if (!getConfig().debug) return;
+    const ts = new Date().toISOString().slice(11, 23);
+    const details = data ? " " + JSON.stringify(data) : "";
+    console.error(`[compactor:${ts}] ${event}${details}`);
+  };
+}
+
 export default function compactorExtension(pi: ExtensionAPI): void {
   let sessionDB: SessionDB | null = null;
   let contentStore: ContentStore | null = null;
@@ -25,6 +35,8 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   let cachedBlocks: NormalizedBlock[] = [];
   let currentSessionId = "default";
 
+  const debug = createDebugLogger(() => config);
+
   const init = async () => {
     scaffoldConfig();
     config = loadConfig();
@@ -42,14 +54,13 @@ export default function compactorExtension(pi: ExtensionAPI): void {
 
   registerCompactionHooks(pi);
 
-  // Register commands with deps (they need sessionDB/contentStore)
+  // Commands will be registered inside session_start when deps are ready
   const getCommandDeps = () => ({
     sessionDB,
     contentStore,
     getSessionId: () => currentSessionId,
     getBlocks: () => cachedBlocks,
   });
-  registerCommands(pi, getCommandDeps());
 
   pi.on("session_start", async (_event, ctx) => {
     await init();
@@ -60,6 +71,8 @@ export default function compactorExtension(pi: ExtensionAPI): void {
     const fullSessionId = `${sessionId}${suffix}`;
     currentSessionId = fullSessionId;
 
+    debug("session_start", { sessionId: fullSessionId, projectDir });
+
     sessionDB?.ensureSession(fullSessionId, projectDir);
 
     // Register all compactor tools with Pi
@@ -82,6 +95,8 @@ export default function compactorExtension(pi: ExtensionAPI): void {
       tools: Object.values(COMPACTOR_TOOLS),
     });
 
+    debug("MODULE_READY", { commands: Object.values(COMPACTOR_COMMANDS), tools: Object.values(COMPACTOR_TOOLS) });
+
     if (config.fts5Index.mode === "auto" && contentStore) {
       // TODO: index project files
     }
@@ -92,6 +107,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   pi.on("before_agent_start", async (_event, ctx) => {
     config = loadConfig();
     currentSessionId = `${(ctx as any).sessionId ?? "default"}${getWorktreeSuffix()}`;
+    debug("before_agent_start", { sessionId: currentSessionId, configDebug: config.debug });
 
     // Re-cache normalized blocks for vcc_recall
     try {
@@ -106,9 +122,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
 
     if (sessionDB) {
       const snapshot = await injectResumeSnapshot(sessionDB, currentSessionId);
-      if (snapshot) {
-        // Snapshot injected as context
-      }
+      debug("resume_snapshot", { injected: !!snapshot });
     }
   });
 
@@ -117,6 +131,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
       const sessionId = `${(event as any).sessionId ?? "default"}${getWorktreeSuffix()}`;
       const events = sessionDB.getEvents(sessionId, { limit: 1000 });
       const stats = sessionDB.getSessionStats(sessionId);
+      debug("session_before_compact", { sessionId, eventCount: events.length, compactCount: stats?.compact_count ?? 0 });
       const { buildResumeSnapshot } = await import("./session/snapshot.js");
       const snapshot = buildResumeSnapshot(events, {
         compactCount: stats?.compact_count ?? 1,
@@ -129,10 +144,12 @@ export default function compactorExtension(pi: ExtensionAPI): void {
     if (sessionDB) {
       const sessionId = `${(event as any).sessionId ?? "default"}${getWorktreeSuffix()}`;
       sessionDB.incrementCompactCount(sessionId);
+      debug("session_compact", { sessionId });
     }
   });
 
   pi.on("session_shutdown", async (_event, _ctx) => {
+    debug("session_shutdown");
     if (sessionDB) {
       sessionDB.cleanupOldSessions(7);
     }
@@ -144,6 +161,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   pi.on("input", async (event, _ctx) => {
     const toolName = (event as any).toolName ?? "";
     const args = (event as any).args ?? {};
+    debug("input", { toolName, args: JSON.stringify(args).slice(0, 200) });
     if (toolName === "bash" || toolName === "Bash") {
       const cmd = String(args.command ?? "");
       if (/\b(curl|wget|nc|netcat)\b/.test(cmd)) {
@@ -156,6 +174,10 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   pi.on("tool_result", async (event, _ctx) => {
     if (!sessionDB) return;
     const sessionId = `${(event as any).sessionId ?? "default"}${getWorktreeSuffix()}`;
+    const toolNameRaw = (event as any).toolName ?? "";
+    const isError = (event as any).isError ?? false;
+
+    debug("tool_result", { toolName: toolNameRaw, isError, sessionId });
 
     // Extract and store session events
     const toolEvents = extractEventsFromToolResult({
@@ -167,6 +189,7 @@ export default function compactorExtension(pi: ExtensionAPI): void {
 
     for (const ev of toolEvents) {
       sessionDB.insertEvent(sessionId, ev, "PostToolUse");
+      debug("event_stored", { category: ev.category, type: ev.type });
     }
 
     // Apply display overrides for built-in tools
@@ -192,20 +215,25 @@ export default function compactorExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("message_update", async (event, _ctx) => {
-    if ((event as any).message?.thinking) {
-      // Handled by display engine
+    const msg = (event as any).message;
+    if (msg?.thinking) {
+      debug("message_update", { thinking: true, length: String(msg.thinking).length });
     }
   });
 
   pi.on("message_end", async (_event, _ctx) => {
-    // Thinking label persistence
+    debug("message_end");
   });
 
   pi.on("context", async (event, _ctx) => {
     const { sanitizeThinkingArtifacts } = await import("./display/thinking-label.js");
-    const ctx = (event as any).context;
-    if (typeof ctx === "string") {
-      (event as any).context = sanitizeThinkingArtifacts(ctx);
+    const ctxStr = (event as any).context;
+    if (typeof ctxStr === "string") {
+      const sanitized = sanitizeThinkingArtifacts(ctxStr);
+      if (sanitized !== ctxStr) {
+        debug("context", { sanitized: true, beforeLen: ctxStr.length, afterLen: sanitized.length });
+      }
+      (event as any).context = sanitized;
     }
   });
 }

package/packages/compactor/src/session/db.ts

@@ -44,17 +44,16 @@ let sqliteLib: any = null;
 
 async function getSQLite() {
   if (sqliteLib) return sqliteLib;
+  // Try bun:sqlite first (Bun runtime)
   try {
     sqliteLib = await import("bun:sqlite" as any);
     return sqliteLib;
   } catch {
-    try {
-      sqliteLib = await import("node:sqlite" as any);
-      return sqliteLib;
-    } catch {
-      sqliteLib = await import("better-sqlite3");
-      return sqliteLib;
-    }
+    // Skip node:sqlite — its API (DatabaseSync) is incompatible with
+    // better-sqlite3's constructor pattern used by SessionDB.
+    // Go straight to better-sqlite3 which has the expected shape.
+    sqliteLib = await import("better-sqlite3");
+    return sqliteLib;
   }
 }
 
@@ -78,8 +77,10 @@ export class SessionDB {
 
   async init(): Promise<void> {
     const sqlite: any = await getSQLite();
-    // Handle different SQLite API shapes
-    const Database = sqlite.Database ?? sqlite.default?.Database ?? sqlite;
+    // Handle different SQLite API shapes:
+    // - bun:sqlite exports Database as a named export
+    // - better-sqlite3 (CJS) exports the constructor as default when imported via ESM
+    const Database = sqlite.Database ?? sqlite.default?.Database ?? sqlite.default ?? sqlite;
     this.db = new Database(this.dbPath);
     this.db.exec("PRAGMA journal_mode = WAL;");
     this.initSchema();

package/packages/compactor/src/store/db-base.ts

@@ -14,30 +14,27 @@ export function defaultDBPath(name: string): string {
 }
 
 let sqliteLib: any = null;
-let sqliteFlavor: "bun" | "node" | "better-sqlite3" | null = null;
+let sqliteFlavor: "bun" | "better-sqlite3" | null = null;
 
 export async function loadSQLite() {
   if (sqliteLib) return { lib: sqliteLib, flavor: sqliteFlavor! };
 
+  // Try bun:sqlite first (Bun runtime)
   try {
     sqliteLib = await import("bun:sqlite" as any);
     sqliteFlavor = "bun";
     return { lib: sqliteLib, flavor: sqliteFlavor };
   } catch {
+    // Skip node:sqlite — its API (DatabaseSync) is incompatible with
+    // better-sqlite3's constructor pattern (Database class).
     try {
-      sqliteLib = await import("node:sqlite" as any);
-      sqliteFlavor = "node";
+      sqliteLib = await import("better-sqlite3");
+      sqliteFlavor = "better-sqlite3";
       return { lib: sqliteLib, flavor: sqliteFlavor };
     } catch {
-      try {
-        sqliteLib = await import("better-sqlite3");
-        sqliteFlavor = "better-sqlite3";
-        return { lib: sqliteLib, flavor: sqliteFlavor };
-      } catch {
-        sqliteLib = {};
-        sqliteFlavor = "better-sqlite3";
-        return { lib: sqliteLib, flavor: sqliteFlavor };
-      }
+      sqliteLib = {};
+      sqliteFlavor = "better-sqlite3";
+      return { lib: sqliteLib, flavor: sqliteFlavor };
     }
   }
 }

package/packages/compactor/src/store/index.ts

@@ -183,7 +183,10 @@ export class ContentStore {
 
   async init(): Promise<void> {
     const { lib } = await loadSQLite();
-    const Database = lib.Database ?? lib.default?.Database ?? lib;
+    // Handle different SQLite API shapes:
+    // - bun:sqlite exports Database as a named export
+    // - better-sqlite3 (CJS) exports the constructor as default when imported via ESM
+    const Database = lib.Database ?? lib.default?.Database ?? lib.default ?? lib;
     this.db = new Database(this.dbPath);
     applyWALPragmas(this.db);
     this.initSchema();

package/packages/compactor/src/tui/settings-overlay.ts

@@ -40,6 +40,18 @@ interface StrategyItem {
   setMode: (c: CompactorConfig, v: string) => void;
 }
 
+/** Top-level debug toggle that mirrors config.debug */
+const GLOBAL_DEBUG: StrategyItem = {
+  key: "debug",
+  label: "Verbose Debug",
+  description: "Log ALL compaction events to console",
+  modes: ["on", "off"],
+  getEnabled: (c) => c.debug,
+  setEnabled: (c, v) => (c.debug = v),
+  getMode: (c) => (c.debug ? "on" : "off"),
+  setMode: (c, v) => (c.debug = v === "on"),
+};
+
 /** All configurable strategies */
 const STRATEGIES: StrategyItem[] = [
   {
@@ -144,6 +156,9 @@ const STRATEGIES: StrategyItem[] = [
   },
 ];
 
+/** All navigable items: debug toggle first, then strategies */
+const ALL_ITEMS: StrategyItem[] = [GLOBAL_DEBUG, ...STRATEGIES];
+
 const PRESETS: CompactorPreset[] = ["opencode", "balanced", "verbose", "minimal"];
 
 /**
@@ -170,7 +185,7 @@ export class CompactorSettingsOverlay implements Component {
       case "\x1b[A": // Up
       case "k":
         if (this.mode === "strategy") {
-          this.selectedIndex = (this.selectedIndex - 1 + STRATEGIES.length) % STRATEGIES.length;
+          this.selectedIndex = (this.selectedIndex - 1 + ALL_ITEMS.length) % ALL_ITEMS.length;
         } else {
           this.presetIndex = (this.presetIndex - 1 + PRESETS.length) % PRESETS.length;
         }
@@ -178,21 +193,21 @@ export class CompactorSettingsOverlay implements Component {
       case "\x1b[B": // Down
       case "j":
         if (this.mode === "strategy") {
-          this.selectedIndex = (this.selectedIndex + 1) % STRATEGIES.length;
+          this.selectedIndex = (this.selectedIndex + 1) % ALL_ITEMS.length;
         } else {
           this.presetIndex = (this.presetIndex + 1) % PRESETS.length;
         }
         break;
       case " ": // Space - toggle enabled
         if (this.mode === "strategy") {
-          const item = STRATEGIES[this.selectedIndex];
+          const item = ALL_ITEMS[this.selectedIndex];
           item.setEnabled(this.config, !item.getEnabled(this.config));
         }
         break;
       case "\x1b[C": // Right - cycle mode forward
       case "\r": // Enter
         if (this.mode === "strategy") {
-          const strat = STRATEGIES[this.selectedIndex];
+          const strat = ALL_ITEMS[this.selectedIndex];
           const modes = strat.modes;
           const currentIdx = modes.indexOf(strat.getMode(this.config));
           const nextIdx = (currentIdx + 1) % modes.length;
@@ -205,7 +220,7 @@ export class CompactorSettingsOverlay implements Component {
         break;
       case "\x1b[D": // Left - cycle mode backward
         if (this.mode === "strategy") {
-          const strat2 = STRATEGIES[this.selectedIndex];
+          const strat2 = ALL_ITEMS[this.selectedIndex];
           const modes2 = strat2.modes;
           const curIdx = modes2.indexOf(strat2.getMode(this.config));
           const prevIdx = (curIdx - 1 + modes2.length) % modes2.length;
@@ -248,9 +263,9 @@ export class CompactorSettingsOverlay implements Component {
       add("");
       add(`${ansi.dim}↑↓ navigate • Enter apply • p back to strategies • s save • Esc cancel${ansi.reset}`);
     } else {
-      // Strategy list
-      for (let i = 0; i < STRATEGIES.length; i++) {
-        const item = STRATEGIES[i];
+      // Strategy list (GLOBAL_DEBUG at top, then all strategies)
+      for (let i = 0; i < ALL_ITEMS.length; i++) {
+        const item = ALL_ITEMS[i];
         const isSelected = i === this.selectedIndex;
         const enabled = item.getEnabled(this.config);
         const mode = item.getMode(this.config);

package/packages/subagents/src/__tests__/badge-generation.test.ts

@@ -60,9 +60,14 @@ describe("Badge generation — tool availability", () => {
 // ─── Test: Prompt no longer references non-existent tool ───────────
 
 describe("Badge generation — prompt fix", () => {
-  it("prompt asks agent to OUTPUT the title directly (not call a tool)", () => {
+  it("prompt includes conversation context inline", () => {
     const src = readSource("packages/subagents/src/index.ts");
 
+    assert.ok(
+      src.includes("Conversation:"),
+      "Prompt should include conversation context inline",
+    );
+
     assert.ok(
       src.includes("Reply with ONLY the title"),
       "Prompt should ask agent to reply with only the title",
@@ -93,6 +98,56 @@ describe("Badge generation — onComplete callback", () => {
   });
 });
 
+// ─── Test: Agent configuration ────────────────────────────────────
+
+describe("Badge generation — agent configuration", () => {
+  it("badge generation uses 'name-gen' agent type (not 'explore')", () => {
+    const src = readSource("packages/subagents/src/index.ts");
+
+    assert.ok(
+      src.includes('manager.spawn(pi, sessionCtx, "name-gen", prompt'),
+      "Badge generation should spawn a 'name-gen' agent",
+    );
+
+    assert.ok(
+      !src.includes('manager.spawn(pi, sessionCtx, "explore"'),
+      "Should NOT use 'explore' — that type can be overridden by user custom agents",
+    );
+  });
+
+  it("'name-gen' type is defined in BUILTIN_CONFIGS with empty tools", () => {
+    const src = readSource("packages/subagents/src/types.ts");
+
+    assert.ok(
+      src.includes('"name-gen"'),
+      "types.ts should define name-gen agent config",
+    );
+
+    assert.ok(
+      src.includes('builtinToolNames: []'),
+      "name-gen should have empty tool list",
+    );
+  });
+
+  it("background agent is isolated (no extensions, no skills, minimal system prompt)", () => {
+    const src = readSource("packages/subagents/src/index.ts");
+
+    assert.ok(
+      src.includes("isolated: true"),
+      "Should spawn with isolated: true to avoid loading extensions/skills",
+    );
+  });
+
+  it("background agent maxTurns is 1 (single response)", () => {
+    const src = readSource("packages/subagents/src/index.ts");
+
+    assert.ok(
+      src.includes("maxTurns: 1"),
+      "Badge generation agent should have maxTurns: 1",
+    );
+  });
+});
+
 // ─── Test: Cross-module event bus — the critical fix ───────────────
 
 describe("Badge generation — event bus (CRITICAL FIX)", () => {

package/packages/subagents/src/index.ts

@@ -148,6 +148,19 @@ export default function (pi: ExtensionAPI) {
       // Build notification details
       const details = buildNotificationDetails(record, agentActivity.get(record.id));
 
+      // Badge generation: extract name from agent result and set directly.
+      // Mark resultConsumed BEFORE the notification check so the main agent
+      // never sees this subagent.
+      if (record.description === "Generate session name" && record.result && record.status === "completed") {
+        const name = record.result.split("\n")[0]?.trim().slice(0, 50) ?? "";
+        if (name && !name.startsWith("Error") && !name.includes("error")) {
+          try {
+            pi.setSessionName(name);
+          } catch { /* best effort */ }
+        }
+        record.resultConsumed = true;
+      }
+
       // Send styled notification via message renderer
       const status = getStatusLabel(record.status, record.error);
       const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
@@ -179,16 +192,6 @@ export default function (pi: ExtensionAPI) {
         );
       }
 
-      // Badge generation: extract name from agent result and set directly
-      if (record.description === "Generate session name" && record.result && record.status === "completed") {
-        const name = record.result.split("\n")[0]?.trim().slice(0, 50) ?? "";
-        if (name && !name.startsWith("Error") && !name.includes("error")) {
-          try {
-            pi.setSessionName(name);
-          } catch { /* best effort */ }
-        }
-      }
-
       pi.events.emit("subagents:completed", {
         id: record.id,
         type: record.type,
@@ -354,8 +357,8 @@ export default function (pi: ExtensionAPI) {
 
     const summary = event?.conversationSummary ?? "";
     const prompt = summary
-      ? `Generate a concise session title (MAX 5 WORDS) for this conversation:\n\n"${summary}"\n\nReply with ONLY the title. No quotes, no explanation, no punctuation.`
-      : `Generate a concise session title (MAX 5 WORDS) for the current session. Reply with ONLY the title. No quotes, no explanation, no punctuation.`;
+      ? `Based on this conversation, generate a concise session title (MAX 5 WORDS). Reply with ONLY the title. No quotes, no explanation, no punctuation.\n\nConversation:\n${summary}`
+      : `Generate a concise session title (MAX 5 WORDS) for this session. Reply with ONLY the title. No quotes, no explanation, no punctuation.`;
 
     // Try with configured model, fallback to inherit
     let modelInput: string | undefined = undefined;
@@ -382,11 +385,12 @@ export default function (pi: ExtensionAPI) {
       // If result is a string (error), resolvedModel stays undefined → inherit parent
     }
 
-    manager.spawn(pi, sessionCtx, "explore", prompt, {
+    manager.spawn(pi, sessionCtx, "name-gen", prompt, {
       description: "Generate session name",
       model: resolvedModel,
       isBackground: true,
-      maxTurns: 3,
+      isolated: true,
+      maxTurns: 1,
     });
   });
 

package/packages/subagents/src/types.ts

@@ -44,6 +44,17 @@ export const BUILTIN_CONFIGS: Record<string, AgentConfig> = {
     promptMode: "append",
     source: "builtin",
   },
+  "name-gen": {
+    name: "name-gen",
+    displayName: "Name Generator",
+    description: "Minimal agent for generating session names from conversation context.",
+    builtinToolNames: [],
+    extensions: false,
+    skills: false,
+    systemPrompt: "You are a session name generator. Generate concise titles from conversation context. Reply with ONLY the title.",
+    promptMode: "replace",
+    source: "builtin",
+  },
 } as const;
 
 /** Memory scope for persistent agent memory. */

package/packages/workflow/skills/brainstorm/SKILL.md

@@ -61,7 +61,7 @@ Start with:
 2. "Who has this problem and when?" — context changes solutions
 3. "What does success look like?" — outcomes, not features
 
-Prefer multiple choice when natural options exist. Validate assumptions explicitly.
+Use `ask_user` for structured decisions (approach selection, scope tradeoffs) when the tool is available. If `ask_user` is not available, use conversational text with clearly numbered options (e.g., "1. Option A — ... 2. Option B — ... Please pick one."). Use conversational text for open-ended exploration. Prefer multiple choice when natural options exist. Validate assumptions explicitly.
 
 **Exit:** Problem statement clear and reframed. Both agree on what solving.
 
@@ -76,7 +76,7 @@ Propose 2-3 different approaches with trade-offs:
 
 Present conversationally with recommendation and reasoning.
 
-**If open questions emerge:** MUST ask user about each one. Don't assume.
+**If open questions emerge:** MUST ask user about each one. Don't assume. Use `ask_user` with clearly labeled options and descriptions for each approach when available; otherwise present numbered options conversationally.
 
 **Exit:** Approach chosen. User signals decision.
 
@@ -86,7 +86,7 @@ Present conversationally with recommendation and reasoning.
 
 Once approach chosen, present design in sections:
 - Scale each section to complexity (few sentences if straightforward, 200-300 words if nuanced)
-- Ask after each section whether it looks right
+- Ask after each section whether it looks right (use `ask_user` for "approve / needs changes / go back" checkpoints if available; otherwise ask conversationally and wait for response)
 - Cover: architecture, components, data flow, error handling, testing
 - Be ready to go back and clarify