@bahulam/code 0.1.11 → 0.1.13

package/src/plugins/pi-compose.mjs

@@ -0,0 +1,147 @@
+/**
+ * Pi composition helpers.
+ *
+ * This is the contract layer for PRD-102 §13.6.1b. It deliberately does
+ * not install or execute pi packages yet; it gives manifest/preflight/
+ * registry code one normalized shape to test against.
+ */
+
+export const PI_TOOLS_CACHE = '.bahulam-tools.json';
+
+const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const NAMESPACE_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i;
+
+export function parsePiSource(source) {
+  const raw = String(source || '').trim();
+  if (!raw.startsWith('pi:')) return null;
+  const spec = raw.slice(3).trim();
+  if (!spec) return null;
+
+  let packageName = spec;
+  let versionRange = '';
+  if (spec.startsWith('@')) {
+    const slash = spec.indexOf('/');
+    const versionAt = slash >= 0 ? spec.indexOf('@', slash + 1) : -1;
+    if (versionAt > 0) {
+      packageName = spec.slice(0, versionAt);
+      versionRange = spec.slice(versionAt + 1);
+    }
+  } else {
+    const versionAt = spec.lastIndexOf('@');
+    if (versionAt > 0) {
+      packageName = spec.slice(0, versionAt);
+      versionRange = spec.slice(versionAt + 1);
+    }
+  }
+
+  if (!NPM_NAME_RE.test(packageName)) return null;
+  return {
+    kind: 'pi',
+    source: raw,
+    spec,
+    package_name: packageName,
+    packageName,
+    version_range: versionRange || null,
+    versionRange: versionRange || null,
+  };
+}
+
+export function normalizeCompose(composeDef, index = 0) {
+  const source = String(composeDef?.source || '').trim();
+  const parsed = parsePiSource(source);
+  const expose = Array.isArray(composeDef?.expose)
+    ? composeDef.expose.map(item => String(item || '').trim()).filter(Boolean)
+    : [];
+  const namespace = String(composeDef?.as || '').trim();
+
+  return {
+    source,
+    as: namespace || '',
+    expose,
+    verified: composeDef?.verified === true,
+    package_name: parsed?.package_name || '',
+    packageName: parsed?.packageName || '',
+    version_range: parsed?.version_range || null,
+    versionRange: parsed?.versionRange || null,
+    _index: index,
+    _kind: 'pi',
+  };
+}
+
+export function normalizeComposes(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item, index) => normalizeCompose(item, index))
+    .filter(item => item.source || item.expose.length || item.as);
+}
+
+// Anthropic's tool-name regex (`^[a-zA-Z0-9_-]{1,64}$`) forbids dots, and
+// the backend's client-tool sanitizer enforces the same shape. `__` is the
+// convention Claude Code and MCP both use for namespaced tool names, so
+// stay compatible: `namespace__tool`.
+export const COMPOSED_TOOL_SEPARATOR = '__';
+
+export function composedToolName(compose, exposedName) {
+  const name = String(exposedName || '').trim();
+  return compose?.as ? `${compose.as}${COMPOSED_TOOL_SEPARATOR}${name}` : name;
+}
+
+export function validateCompose(compose) {
+  const errors = [];
+  const warnings = [];
+  const label = `Compose #${Number.isInteger(compose?._index) ? compose._index : '?'}`;
+
+  if (!parsePiSource(compose?.source)) {
+    errors.push(`${label}: source must be a pi npm spec, for example pi:@scope/package@^1.0.0`);
+  }
+  if (compose?.as && !NAMESPACE_RE.test(compose.as)) {
+    errors.push(`${label}: as "${compose.as}" must match ${NAMESPACE_RE}`);
+  }
+  if (!Array.isArray(compose?.expose) || compose.expose.length === 0) {
+    errors.push(`${label}: expose must list at least one pi tool`);
+  } else {
+    const seen = new Set();
+    for (const exposed of compose.expose) {
+      if (!TOOL_NAME_RE.test(exposed)) {
+        errors.push(`${label}: expose "${exposed}" must match ${TOOL_NAME_RE}`);
+      }
+      if (seen.has(exposed)) {
+        errors.push(`${label}: duplicate exposed tool "${exposed}"`);
+      }
+      seen.add(exposed);
+    }
+  }
+  if (compose?.verified !== true) {
+    warnings.push(`${label}: ${compose?.source || 'pi package'} is unverified; hosted Studios require verified pi packages`);
+  }
+
+  return { errors, warnings };
+}
+
+export function expandComposedTools(pluginName, pluginDir, composes = []) {
+  const tools = [];
+  for (const compose of composes || []) {
+    for (const exposedName of compose.expose || []) {
+      tools.push({
+        name: composedToolName(compose, exposedName),
+        description: `Composed pi tool ${exposedName} from ${compose.source}`,
+        input_schema: { type: 'object', properties: {} },
+        tool: '',
+        plugin_name: pluginName,
+        _plugin_name: pluginName,
+        _plugin_dir: pluginDir,
+        _composed: {
+          kind: 'pi',
+          source: compose.source,
+          package_name: compose.package_name,
+          version_range: compose.version_range,
+          namespace: compose.as || null,
+          original_name: exposedName,
+          verified: compose.verified === true,
+        },
+      });
+    }
+  }
+  return tools;
+}

package/src/plugins/preflight.mjs

@@ -22,6 +22,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
+import { composedToolName, validateCompose } from './pi-compose.mjs';
 
 const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 const AGENT_SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
@@ -86,6 +87,7 @@ export async function preflightPlugin(pluginDir, opts = {}) {
   const views = manifest.spec?.workspace?.views || [];
   const mcpServers = manifest.spec?.mcpServers || {};
   const mcpServerNames = new Set(Object.keys(mcpServers));
+  const composes = manifest.spec?.composes || [];
 
   // MCP server sanity — every server should have EITHER command (stdio)
   // OR url (remote). Anything else is meaningless config.
@@ -101,6 +103,26 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     }
   }
 
+  // Pi composition sanity. Composed tools become part of the agent-visible
+  // tool namespace, but they are not local files and are not imported here.
+  const composedToolNames = new Set();
+  for (const compose of composes) {
+    const validated = validateCompose(compose);
+    errors.push(...validated.errors);
+    warnings.push(...validated.warnings);
+    if (compose.as && mcpServerNames.has(compose.as)) {
+      errors.push(`Compose #${compose._index}: namespace "${compose.as}" collides with an MCP server name`);
+    }
+    for (const exposedName of compose.expose || []) {
+      const fullName = composedToolName(compose, exposedName);
+      if (composedToolNames.has(fullName)) errors.push(`Composed tool "${fullName}": duplicate name`);
+      if (RESERVED_TOOL_NAMES.has(fullName)) {
+        errors.push(`Composed tool "${fullName}": shadows a built-in tool`);
+      }
+      composedToolNames.add(fullName);
+    }
+  }
+
   // 2 + 3 + 4. Tool checks
   const toolNames = new Set();
   for (const [i, tool] of tools.entries()) {
@@ -114,26 +136,29 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     if (RESERVED_TOOL_NAMES.has(tool.name)) {
       errors.push(`Tool "${t}": shadows a built-in tool — pick a different name (built-ins always win)`);
     }
+    if (composedToolNames.has(tool.name)) {
+      errors.push(`Tool "${t}": collides with a composed pi tool`);
+    }
     if (!tool.description || tool.description.length < 8) {
       warnings.push(`Tool "${t}": description is missing or very short (<8 chars) — the model uses this to decide when to call it`);
     }
-    if (!tool.handler) { errors.push(`Tool "${t}": missing handler path`); continue; }
+    if (!tool.tool) { errors.push(`Tool "${t}": missing tool module path (tool: ./tools/<name>.mjs)`); continue; }
 
-    const handlerPath = path.resolve(pluginDir, tool.handler);
+    const toolModulePath = path.resolve(pluginDir, tool.tool);
     // Traversal guard
-    const inside = handlerPath === pluginDir || handlerPath.startsWith(pluginDir + path.sep);
-    if (!inside) errors.push(`Tool "${t}": handler path escapes the plugin directory`);
-    else if (!fs.existsSync(handlerPath)) errors.push(`Tool "${t}": handler file not found: ${tool.handler}`);
+    const inside = toolModulePath === pluginDir || toolModulePath.startsWith(pluginDir + path.sep);
+    if (!inside) errors.push(`Tool "${t}": tool module path escapes the plugin directory`);
+    else if (!fs.existsSync(toolModulePath)) errors.push(`Tool "${t}": tool module not found: ${tool.tool}`);
     else {
       try {
         // Cache-bust because a previous install may have imported an older
         // copy at the same path in this process.
-        const mod = await import(`${pathToFileURL(handlerPath).href}?preflight=${Date.now()}`);
+        const mod = await import(`${pathToFileURL(toolModulePath).href}?preflight=${Date.now()}`);
         if (typeof mod.call !== 'function') {
-          errors.push(`Tool "${t}": handler ${tool.handler} does not export an async \`call\` function`);
+          errors.push(`Tool "${t}": tool module ${tool.tool} does not export an async \`call\` function`);
         }
       } catch (err) {
-        errors.push(`Tool "${t}": handler ${tool.handler} failed to import: ${err.message}`);
+        errors.push(`Tool "${t}": tool module ${tool.tool} failed to import: ${err.message}`);
       }
     }
 
@@ -166,12 +191,12 @@ export async function preflightPlugin(pluginDir, opts = {}) {
       // plugin's mcpServers. The <tool> half is discovered live.
       if (toolRef.includes('.')) {
         const serverName = toolRef.split('.', 1)[0];
-        if (!mcpServerNames.has(serverName)) {
+        if (!mcpServerNames.has(serverName) && !composedToolNames.has(toolRef)) {
           errors.push(`Agent "${slug}": tool "${toolRef}" references MCP server "${serverName}" which is not declared in mcpServers`);
         }
         continue;
       }
-      if (!toolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
+      if (!toolNames.has(toolRef) && !composedToolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
         errors.push(`Agent "${slug}": tool "${toolRef}" is not defined by this plugin and is not a built-in`);
       }
     }

package/src/plugins/registry.mjs

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
+import { expandComposedTools } from './pi-compose.mjs';
 
 const DEFAULT_PLUGIN_DIRS = () => [
   path.join(process.cwd(), '.bahulam', 'plugins'),
@@ -159,6 +160,11 @@ export class PluginRegistry {
           _plugin_dir: plugin._dir,
         });
       }
+      tools.push(...expandComposedTools(
+        plugin.metadata?.name || '',
+        plugin._dir,
+        plugin.spec?.composes || [],
+      ));
     }
     return tools;
   }

package/src/terminal/agents.mjs

@@ -113,7 +113,7 @@ const TOOL_ALIASES = new Map([
   ['grep', 'search_code'],
 ]);
 
-function canonicalToolName(value) {
+export function canonicalToolName(value) {
   const key = String(value || '').trim().toLowerCase();
   return TOOL_ALIASES.get(key) || key;
 }
@@ -133,7 +133,7 @@ function normalizeScopedArgs(toolName, args = {}, { projectRoot = null } = {}) {
   return next;
 }
 
-function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
+export function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
   const tools = Array.isArray(agent.tools) ? agent.tools : [];
   const allowed = new Set(tools.map(canonicalToolName).filter(Boolean));
   if (!allowed.size) return baseExecutor;
@@ -152,7 +152,11 @@ function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } =
         baseExecutor,
         toolName,
         normalizeScopedArgs(toolName, args, { projectRoot }),
-        options,
+        {
+          ...options,
+          internal: true,
+          subAgent: agent.slug || agent.command || agent.name || true,
+        },
       );
     },
   };
@@ -317,6 +321,7 @@ export async function runAgentDefinition(agentDefinition, instruction, ctx, sess
     token: creds.token,
     toolExecutor,
     approvalManager: agentApproval,
+    pluginRegistry: options.pluginRegistry || ctx.pluginRegistry || null,
   });
 
   session.turns++;

package/src/terminal/main.mjs

@@ -24,7 +24,7 @@ const subcommand = process.argv[2];
 const subcommandArgs = process.argv.slice(3);
 
 const PLUGIN_MANAGEMENT_COMMANDS = new Set([
-  'install', 'validate', 'check', 'lint',
+  'validate', 'check', 'lint',
   'list', 'ls', 'remove', 'rm', 'uninstall',
   'enable', 'disable', 'info', 'update', 'upgrade',
 ]);
@@ -63,8 +63,7 @@ function parsePluginArgs(argv) {
   }
   if (positional.length && PLUGIN_MANAGEMENT_COMMANDS.has(positional[0].toLowerCase())) {
     parsed.action = positional.shift().toLowerCase();
-    if (parsed.action === 'install') parsed.source = positional.shift() || null;
-    else if (['validate', 'check', 'lint'].includes(parsed.action)) {
+    if (['validate', 'check', 'lint'].includes(parsed.action)) {
       // Accepts either a directory path or an installed plugin name.
       const arg = positional.shift() || null;
       if (arg && (arg.includes('/') || fs.existsSync?.(arg))) parsed.source = arg;
@@ -279,7 +278,28 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'pull') {
+    const { handlePullCommand } = await import('../commands/install.mjs');
+    await handlePullCommand(subcommandArgs, { cwd: process.cwd() });
+    return;
+  }
+
+  if (subcommand === 'install') {
+    const { handleInstallCommand } = await import('../commands/install.mjs');
+    await handleInstallCommand(subcommandArgs, { cwd: process.cwd() });
+    return;
+  }
+
   if (subcommand === 'plugin' || subcommand === 'plugins') {
+    // `install`/`pull` moved to top-level. Detect the old form and redirect.
+    if (subcommandArgs[0] === 'install' || subcommandArgs[0] === 'pull') {
+      const verb = subcommandArgs[0];
+      const rest = subcommandArgs.slice(1);
+      process.stderr.write(`\x1b[33m!\x1b[0m \`bahulam plugin ${verb}\` moved to top-level. Use:\n`);
+      process.stderr.write(`    \x1b[36mbahulam install ${rest.join(' ')}\x1b[0m   (pack — scaffolds around pi:, installs git/tarball/local)\n`);
+      process.stderr.write(`    \x1b[36mbahulam pull ${rest.join(' ')}\x1b[0m      (ingredient only — pi: sources)\n`);
+      process.exit(2);
+    }
     const args = parsePluginArgs(subcommandArgs);
     if (args.action && args.action !== 'open') {
       const { handlePluginManagementCommand } = await import('../commands/plugin-manage.mjs');
@@ -306,6 +326,8 @@ async function main() {
   \x1b[1mUsage:\x1b[0m
     bahulam                        Start interactive REPL
     bahulam "instruction"          Run a single instruction
+    bahulam --agent <slug> -p "x"  Run a named agent (local deterministic graph)
+    bahulam --workflow <name> -p   Run a named workflow (local deterministic graph)
     bahulam --headless -p "x"      Non-interactive: auto-approve, JSONL output
     bahulam --headless -p "x" --vision screenshot.png
                               Attach an image via the vision analysis pipeline
@@ -330,8 +352,14 @@ async function main() {
     bahulam workspace list         List recent local workspace sessions
     bahulam local open [path]      Alias for workspace open
 
-  \x1b[1mPlugins:\x1b[0m
-    bahulam plugin <name> [path]   Open a workspace with a named plugin
+  \x1b[1mPacks & ingredients:\x1b[0m
+    bahulam pull pi:<name>         Pull a pi ingredient (composable, not runnable on its own)
+    bahulam install pi:<name>      Pull ingredient + scaffold a full Bahulam pack around it
+    bahulam install <git-url>      Install a hand-authored pack from git
+    bahulam install <local-path>   Install a hand-authored pack from disk
+    bahulam plugin list            List installed packs and pi ingredients
+    bahulam plugin remove <name>   Remove an installed pack
+    bahulam plugin <name> [path]   Open a workspace with an installed pack
 
   \x1b[1mAnalytics:\x1b[0m
     bahulam sessions               List recent local sessions
@@ -360,7 +388,7 @@ async function main() {
     /architect <query>      Spawn architecture planning agent
     /agents create <name>   Create project-local user-defined agent YAML
     /agents edit <name>     Open a local agent YAML in your editor
-    /agents sync [name]     Sync all or one local agent to Supabase
+    /agents sync [name]     Optionally publish local agents to backend/account
     /attach <image-path>    Attach an image to next prompt
     /attach clipboard       Attach image copied to macOS/Windows clipboard
     /exit                   Exit the REPL
@@ -480,7 +508,9 @@ async function main() {
   const daemonSpawned = process.env.BAHULAM_DAEMON_SPAWNED === '1';
   const daemonPrompt = daemonSpawned ? (process.env.BAHULAM_DAEMON_INITIAL_PROMPT || '').trim() : '';
   const effectivePrompt = args.prompt || (daemonSpawned && daemonPrompt) || '';
-  if (effectivePrompt && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY)) {
+  const hasGraphTarget = Boolean(args.agent || args.workflow);
+  if ((effectivePrompt || hasGraphTarget)
+      && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY || hasGraphTarget)) {
     const { runHeadless } = await import('../core/headless.mjs');
     await runHeadless({
       instruction: effectivePrompt,
@@ -490,6 +520,8 @@ async function main() {
       cacheReport: args.cacheReport,
       local: args.local,
       vision: args.vision,
+      agent: args.agent,
+      workflow: args.workflow,
     });
     return;
   }

package/src/terminal/paste-input.mjs

@@ -0,0 +1,23 @@
+export function isRawMultilinePasteChunk(text) {
+  const value = String(text || '');
+  if (!value) return false;
+  if (!/[\r\n]/.test(value)) return false;
+
+  const withoutLineBreaks = value.replace(/[\r\n]/g, '');
+  if (!withoutLineBreaks.length) return false;
+
+  // A single printable char followed by Enter can be delivered in one chunk
+  // by some terminals; keep that as normal line submission.
+  return withoutLineBreaks.length > 1 || value.split(/\r?\n|\r/).length > 2;
+}
+
+export function normalizePastedText(text) {
+  return String(text || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+export function pastedTextLabel(text) {
+  const value = normalizePastedText(text);
+  const lines = value ? value.split('\n').length : 0;
+  if (lines > 1) return `[text copied · ${lines} lines]`;
+  return '[text copied]';
+}

package/src/terminal/repl-render.mjs

@@ -34,8 +34,8 @@ import * as queue from '../ui/render-queue.mjs';
 // queue active) → coalesced last-wins status that can never interleave
 // with content. Legacy dock path and bare-TTY inPlace stay as fallbacks
 // until their write-sites migrate onto the queue too.
-// Max inner-tool lines shown under the spinner during a sub-agent run.
-const SUB_AGENT_WINDOW_ROWS = 7;
+// Max live-window lines under the spinner during a sub-agent run.
+const SUB_AGENT_WINDOW_ROWS = 8;
 
 function statusWidth() {
   return Math.max(8, (process.stderr.columns || process.stdout.columns || 120) - 1);
@@ -49,6 +49,18 @@ function fitStatusLines(lines) {
   return (Array.isArray(lines) ? lines : [lines]).map(fitStatusLine);
 }
 
+function subAgentWindowLines(win) {
+  if (win?.groups instanceof Map && win.groups.size) {
+    const lines = [];
+    for (const group of win.groups.values()) {
+      if (group?.header) lines.push(group.header);
+      for (const line of group?.lines || []) lines.push(line);
+    }
+    return lines;
+  }
+  return (win?.lines || []).slice(-SUB_AGENT_WINDOW_ROWS);
+}
+
 function presentStatus(rendered) {
   // Watch panel override: when active, render the watch panel entries as a
   // multi-line status block instead of the normal spinner/status line.
@@ -69,10 +81,11 @@ function presentStatus(rendered) {
   const fitted = fitStatusLine(rendered);
   if (queue.isActive()) {
     const win = runtime.subAgentWindow;
-    if (win?.active && win.lines.length) {
+    const subAgentLines = subAgentWindowLines(win);
+    if (win?.active && subAgentLines.length) {
       queue.statusBlock([
         fitted,
-        ...fitStatusLines(win.lines.slice(-SUB_AGENT_WINDOW_ROWS).map(l => `    ${c.dim(l)}`)),
+        ...fitStatusLines(subAgentLines.map(l => `    ${c.dim(l)}`)),
       ]);
       return;
     }
@@ -95,7 +108,7 @@ export function pushSubAgentWindowLine(line) {
 }
 
 export function setSubAgentWindowActive(active) {
-  runtime.subAgentWindow = { active: Boolean(active), lines: [] };
+  runtime.subAgentWindow = { active: Boolean(active), lines: [], groups: new Map() };
 }
 
 /**
@@ -109,6 +122,25 @@ export function rebuildSubAgentWindow(lines) {
   const win = runtime.subAgentWindow;
   if (!win?.active) return;
   win.lines = Array.isArray(lines) ? lines.slice() : [];
+  win.groups = new Map();
+  repaintSpinnerStatus();
+}
+
+export function rebuildSubAgentWindowGroups(groups) {
+  const win = runtime.subAgentWindow;
+  if (!win?.active) return;
+  win.groups = new Map();
+  win.lines = [];
+  for (const group of Array.isArray(groups) ? groups : []) {
+    const key = group?.runId || group?.key || group?.label;
+    if (!key) continue;
+    win.groups.set(key, {
+      runId: group.runId || null,
+      label: group.label || 'sub-agent',
+      header: group.header || group.label || 'sub-agent',
+      lines: Array.isArray(group.lines) ? group.lines.slice() : [],
+    });
+  }
   repaintSpinnerStatus();
 }
 
@@ -308,11 +340,27 @@ export function renderToolCall(data) {
   const args = data?.args || {};
   const indent = subAgentIndent();
   const callId = data?.call_id || data?._callId || `${tool}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const fromSubAgent = Boolean(data?.internal || data?.sub_agent || data?.sub_agent_label || data?.sub_agent_run_id);
 
   // If a previous head is still pending (no result yet), flush it as a
   // regular two-line shape before starting the next one.
   flushPendingHead();
 
+  // Sub-agent live window (queue mode): inner tool calls stream into the
+  // fixed-height status block instead of appending transcript lines. Keep
+  // this ahead of explore-collapse so parallel explores do not merge into
+  // one global read/search spinner.
+  if (fromSubAgent && queue.isActive() && runtime.subAgentWindow?.active) {
+    recordCard({ id: callId, tool, args, startedAt: Date.now() });
+    session.toolCounts[tool] = (session.toolCounts[tool] || 0) + 1;
+    const label = readToolLabel(tool, { args });
+    const runId = data?.run_id || data?.sub_agent_run_id || '';
+    const runSuffix = runId ? ` run ${String(runId).slice(0, 8)}` : '';
+    const lane = data?.sub_agent_label ? `[${data.sub_agent_label}${runSuffix}] ` : '';
+    pushSubAgentWindowLine(label ? `${lane}→ ${tool} · ${label}` : `${lane}→ ${tool}`);
+    return; // the spinner tick paints the window block
+  }
+
   // ── Explore-run collapse ────────────────────────────────────────────────
   // For list/read/search/index tools, skip the per-call head entirely and
   // update a single animated summary spinner. The transcript stays clean;
@@ -328,9 +376,8 @@ export function renderToolCall(data) {
     return;
   }
 
-  // Sub-agent live window (queue mode): inner tool calls stream into the
-  // fixed-height status block instead of appending transcript lines. The
-  // card is still recorded so /expand, /last, and `d` show full detail.
+  // Legacy sub-agent live window fallback for events without explicit
+  // sub-agent metadata.
   if (queue.isActive() && runtime.subAgentWindow?.active && inSubAgentBlock()) {
     recordCard({ id: callId, tool, args, startedAt: Date.now() });
     session.toolCounts[tool] = (session.toolCounts[tool] || 0) + 1;
@@ -410,6 +457,14 @@ export function renderToolResult(data, eventType = 'tool_result') {
     indent: gutter,
     columns: process.stderr.columns || 120,
   });
+  const fromSubAgent = Boolean(data?.internal || data?.sub_agent || data?.sub_agent_label || data?.sub_agent_run_id);
+
+  // Sub-agent live window: the call line is already streaming in the
+  // status block; the result stays card-only (close card summarizes). This
+  // must run before explore-collapse for read/search tools used by explores.
+  if (fromSubAgent && queue.isActive() && runtime.subAgentWindow?.active) {
+    return;
+  }
 
   // Explore tools: the call already updated the summary spinner. Refresh
   // the "latest" hint with the result's file if we have one, and skip the
@@ -421,8 +476,8 @@ export function renderToolResult(data, eventType = 'tool_result') {
     return;
   }
 
-  // Sub-agent live window: the call line is already streaming in the
-  // status block; the result stays card-only (close card summarizes).
+  // Legacy sub-agent live window fallback for events without explicit
+  // sub-agent metadata.
   if (queue.isActive() && runtime.subAgentWindow?.active && inSubAgentBlock()) {
     return;
   }

package/src/terminal/repl-state.mjs

@@ -43,7 +43,8 @@ export const runtime = {
 
   // Explore-run collapse (read/list/search/index bursts as concise progress).
   exploreRun: { counts: {}, recent: [], lineActive: false, lastPrintedSummary: '', lastPrintedTotal: 0, lastPrintedAt: 0 },
-  foldedSubAgentTools: null, // { agentType, entries, startedAt } for default/quiet folded sub-agent tools
+  foldedSubAgentTools: null, // current folded sub-agent tool bucket
+  foldedSubAgentToolMap: new Map(), // run-aware buckets for parallel sub-agents
 
   // Animated spinner state (single shared interval; text/frame drive inPlace).
   spinInterval: null,
@@ -61,7 +62,7 @@ export const runtime = {
   // its inner tool calls stream into a fixed-height status block (last
   // N lines under the spinner) instead of appending to the transcript.
   // Full detail stays on the recorded cards (/expand, /last, `d`).
-  subAgentWindow: { active: false, lines: [] },
+  subAgentWindow: { active: false, lines: [], groups: new Map() },
 
   // PRD-092: Watch panel — toggled by /watch. When active, the spinner
   // area renders a compact agent-activity summary instead of the spinner.
@@ -106,6 +107,7 @@ export const session = {
   lastTurnDuration: 0,
   toolCounts: {},      // per-tool histogram (mission report)
   subAgentCounts: {},  // per-sub-agent histogram (mission report)
+  activeSubAgentRuns: new Map(), // run_id -> active sub-agent lane
   savedUsd: 0,         // total sub-agent cost (for "saved by routing")
   lastTask: '',        // most recent user prompt (mission report title)
   lastReasoning: '',   // captured from agent for /why