lsd-pi 1.2.2 → 1.2.3

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -13,7 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { Text } from "@gsd/pi-tui";
 import type {
@@ -1001,7 +1001,52 @@ export class AgentSession {
 		return this.resourceLoader.getSkills().skills.find((skill) => skill.name === skillName);
 	}
 
+	private _findKnownSubagentByName(agentName: string): { name: string; source: string } | undefined {
+		const normalized = agentName.trim().toLowerCase();
+		if (!normalized) return undefined;
+
+		const builtInAgentNames = new Set(["scout", "worker", "reviewer", "planner", "teams-builder", "teams-reviewer"]);
+		if (builtInAgentNames.has(normalized)) {
+			return { name: normalized, source: "bundled" };
+		}
+
+		const userAgentsDir = join(process.env.LSD_CODING_AGENT_DIR || process.env.GSD_CODING_AGENT_DIR || join(process.env.HOME || "", ".lsd", "agent"), "agents");
+		const projectCandidates = [".lsd", ".gsd", ".pi"].map((dir) => join(this._cwd, dir, "agents"));
+		for (const [dirPath, source] of [[userAgentsDir, "user"], ...projectCandidates.map((p) => [p, "project"] as const)]) {
+			if (!existsSync(dirPath)) continue;
+			let entries: string[] = [];
+			try {
+				entries = readdirSync(dirPath);
+			} catch {
+				continue;
+			}
+			for (const entry of entries) {
+				if (!entry.endsWith(".md")) continue;
+				const filePath = join(dirPath, entry);
+				try {
+					if (!statSync(filePath).isFile()) continue;
+					const raw = readFileSync(filePath, "utf-8");
+					const match = raw.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---/);
+					const frontmatter = match?.[1] ?? "";
+					const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+					const name = nameMatch?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+					if (name?.toLowerCase() === normalized) {
+						return { name, source };
+					}
+				} catch {
+					continue;
+				}
+			}
+		}
+
+		return undefined;
+	}
+
 	private _formatMissingSkillMessage(skillName: string): string {
+		const knownSubagent = this._findKnownSubagentByName(skillName);
+		if (knownSubagent) {
+			return `\"${knownSubagent.name}\" is an available subagent (${knownSubagent.source}), not a skill. Use the subagent tool directly with { agent: \"${knownSubagent.name}\", task: \"...\" }.`;
+		}
 		const availableSkills = this.resourceLoader.getSkills().skills.map((skill) => skill.name).join(", ") || "(none)";
 		return `Skill "${skillName}" not found. Available skills: ${availableSkills}`;
 	}
@@ -1059,6 +1104,7 @@ export class AgentSession {
 			"Scout-first reconnaissance policy: when you need architecture context across multiple files or folders, do not map the subsystem by reading file-after-file yourself. Launch the scout subagent first, then continue with lsp and targeted reads.",
 			"If your next step would be broad exploration rather than a targeted lookup, prefer scout before doing more read/find/grep sweeps yourself.",
 			"When you choose scout, call subagent directly with valid parameters: { agent, task } for one scout, or { tasks: [{ agent, task }, ...] } for parallel scouts.",
+			"If the user explicitly names a subagent such as scout, worker, reviewer, or planner, invoke the subagent tool directly rather than the Skill tool or ad-hoc discovery.",
 			"Scout is reconnaissance-only. Do not use it as the reviewer, auditor, or final issue-ranker; use it to map files, ownership, and likely hotspots for later evaluation.",
 			"If the work spans multiple loosely-coupled subsystems, prefer parallel scout subagents so each scout maps one area and the parent model reads the summaries instead of the raw files.",
 			"For broad review or audit requests, use scout only as a prep step to map architecture and hotspots; the parent model or a reviewer should make the final judgments.",
@@ -1354,7 +1400,7 @@ export class AgentSession {
 			name: "Skill",
 			label: "Skill",
 			description:
-				"Execute a skill within the main conversation. Use this tool when users ask for a slash command or reference a skill by name. Returns the expanded skill block and appends args after it.",
+				"Execute a listed skill within the main conversation. Use this tool only for actual available skills or explicit /skill:name-style requests — not for launching subagents like scout, worker, reviewer, or planner. Returns the expanded skill block and appends args after it.",
 			parameters: skillSchema,
 			execute: async (_toolCallId, params: unknown) => {
 				const input = params as { skill: string; args?: string };
@@ -2371,7 +2417,9 @@ export class AgentSession {
 
 		const nextActiveToolNames = options?.activeToolNames
 			? [...options.activeToolNames]
-			: [...previousActiveToolNames];
+			: this.settingsManager.getToolProfile() === "full"
+				? Array.from(toolRegistry.keys())
+				: [...previousActiveToolNames];
 
 		if (options?.includeAllExtensionTools) {
 			for (const tool of wrappedExtensionTools) {

package/packages/pi-coding-agent/src/core/sdk.ts

@@ -279,7 +279,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
         ? ["hashline_read", "bash", "hashline_edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent", "ask_user_questions"]
         : ["read", "bash", "edit", "write", "lsp", "bg_shell", "tool_search", "tool_enable", "Skill", "subagent", "await_subagent", "ask_user_questions"];
     const defaultActiveToolNames: string[] = toolProfile === "full"
-        ? Object.keys(allTools)
+        ? []
         : balancedToolNames;
     const initialActiveToolNames: string[] = options.tools
         ? options.tools.map((t) => t.name).filter((n): n is string => typeof n === "string" && n in allTools)

package/packages/pi-coding-agent/src/core/skill-tool.test.ts

@@ -85,6 +85,24 @@ describe("Skill tool", () => {
 		);
 	});
 
+	it("describes Skill as distinct from subagents", async () => {
+		const session = await createSession();
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+		assert.match(tool.description ?? "", /not for launching subagents like scout, worker, reviewer, or planner/i);
+	});
+
+	it("returns a helpful redirect when a known subagent name is passed to Skill", async () => {
+		const session = await createSession();
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should be registered");
+
+		const result = await tool.execute("call-subagent", { skill: "scout" });
+		const message = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(message, /"scout" is an available subagent/i);
+		assert.match(message, /Use the subagent tool directly with \{ agent: "scout", task: "\.\.\." \}\./i);
+	});
+
 	it("returns a helpful error for unknown skills", async () => {
 		writeSkill(testDir, "swift-testing", "Use for Swift Testing assertions and verification patterns.");
 		const session = await createSession();

package/packages/pi-coding-agent/src/core/skills.ts

@@ -324,6 +324,7 @@ export function formatSkillsForPrompt(skills: Skill[]): string {
 	const lines = [
 		"\n\nThe following skills provide specialized instructions for specific tasks.",
 		"Use the Skill tool with the exact skill name from <available_skills> when the task matches its description.",
+		"Use the Skill tool only for listed skills — not for launching subagents like scout, worker, reviewer, or planner.",
 		"If the Skill tool reports an unknown skill, do not guess: use an exact name from <available_skills> or tell the user the skill is unavailable.",
 		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
 		"",

package/packages/pi-coding-agent/src/core/system-prompt.ts

@@ -172,6 +172,9 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		addGuideline(
 			"Call the subagent tool directly. For one scout use { agent, task }. For several scouts use parallel mode with { tasks: [{ agent, task }, ...] }.",
 		);
+		addGuideline(
+			"When the user names a subagent such as scout, worker, reviewer, or planner, invoke the subagent tool directly rather than the Skill tool or ad-hoc search.",
+		);
 		addGuideline(
 			"Scout is for mapping and reconnaissance only — not for final review, audit, or ranked issue lists. Use it to identify relevant files, subsystems, and likely hotspots for later evaluation.",
 		);

package/packages/pi-coding-agent/src/tests/path-display.test.ts

@@ -74,6 +74,7 @@ test("buildSystemPrompt: encourages scout-first reconnaissance when subagent is
 	assert.match(prompt, /multiple scout subagents in parallel/i);
 	assert.match(prompt, /broad review or audit requests, use scout only as a prep step/i);
 	assert.match(prompt, /Skip scout only when the task is clearly narrow/i);
+	assert.match(prompt, /When the user names a subagent such as scout, worker, reviewer, or planner, invoke the subagent tool directly/i);
 });
 
 // ─── Regression: no backslash paths in LLM-visible text ────────────────────

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lsd-pi",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "piConfig": {
     "name": "lsd",
     "configDir": ".lsd"

package/src/resources/extensions/slash-commands/plan.ts

@@ -275,15 +275,21 @@ async function enablePlanModeWithModelSwitch(
   next: Partial<Pick<PlanModeState, "task" | "latestPlanPath" | "approvalStatus" | "previousMode" | "preplanModel" | "targetPermissionMode">> = {},
 ): Promise<void> {
   enablePlanMode(pi, currentModel, next);
-  // Signal that before_agent_start should switch to the reasoning model on next turn
+  // Keep fallback behavior in before_agent_start for restored sessions or when
+  // immediate switching cannot be completed at entry-time.
   reasoningModelSwitchDone = false;
   if (!readAutoSwitchPlanModelSetting()) return;
-  if (!readPlanModeReasoningModel()) {
+
+  const reasoningModel = parseQualifiedModelRef(readPlanModeReasoningModel());
+  if (!reasoningModel) {
     ctx.ui?.notify?.(
       "OpusPlan: set a Plan reasoning model in /settings to auto-switch on entry",
       "info",
     );
+    return;
   }
+
+  reasoningModelSwitchDone = await setModelIfNeeded(pi, ctx, reasoningModel);
 }
 
 function enablePlanMode(
@@ -329,13 +335,14 @@ function leavePlanMode(
   return nextPermissionMode;
 }
 
-async function setModelIfNeeded(pi: ExtensionAPI, ctx: any, modelRef: ModelRef | undefined): Promise<void> {
-  if (!modelRef) return;
+async function setModelIfNeeded(pi: ExtensionAPI, ctx: any, modelRef: ModelRef | undefined): Promise<boolean> {
+  if (!modelRef) return false;
   const currentModel = parseQualifiedModelRef(ctx?.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
-  if (sameModel(currentModel, modelRef)) return;
+  if (sameModel(currentModel, modelRef)) return true;
   const model = resolveModelFromContext(ctx, modelRef);
-  if (!model) return;
+  if (!model) return false;
   await pi.setModel(model, { persist: false });
+  return true;
 }
 
 function buildExecutionKickoffMessage(options: { permissionMode: RestorablePermissionMode; executeWithSubagent?: boolean }): string {
@@ -640,8 +647,7 @@ export default function planCommand(pi: ExtensionAPI) {
       if (!reasoningModelSwitchDone && readAutoSwitchPlanModelSetting()) {
         const reasoningModel = parseQualifiedModelRef(readPlanModeReasoningModel());
         if (reasoningModel) {
-          reasoningModelSwitchDone = true;
-          await setModelIfNeeded(pi, ctx, reasoningModel);
+          reasoningModelSwitchDone = await setModelIfNeeded(pi, ctx, reasoningModel);
         }
       }
       return { systemPrompt: buildPlanModeSystemPrompt() };

package/src/resources/extensions/subagent/agents.ts

@@ -4,6 +4,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@gsd/pi-coding-agent";
 
 const PROJECT_AGENT_DIR_CANDIDATES = [".lsd", ".gsd", ".pi"] as const;
@@ -16,7 +17,7 @@ export interface AgentConfig {
 	tools?: string[];
 	model?: string;
 	systemPrompt: string;
-	source: "user" | "project";
+	source: "bundled" | "user" | "project";
 	filePath: string;
 }
 
@@ -35,7 +36,7 @@ function normalizeAgentModel(model: string | undefined): string | undefined {
 	return parts.length === 2 && parts.every(Boolean) ? trimmed : undefined;
 }
 
-function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+function loadAgentsFromDir(dir: string, source: "bundled" | "user" | "project"): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
 	if (!fs.existsSync(dir)) {
@@ -110,22 +111,35 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
+function getBundledAgentsDir(): string {
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	return path.resolve(here, "../../agents");
+}
+
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
 	const userDir = path.join(getAgentDir(), "agents");
+	const bundledDir = getBundledAgentsDir();
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
+	const bundledAgents = scope === "project" ? [] : loadAgentsFromDir(bundledDir, "bundled");
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 
 	const agentMap = new Map<string, AgentConfig>();
 
+	const addAgents = (items: AgentConfig[]) => {
+		for (const agent of items) agentMap.set(agent.name, agent);
+	};
+
 	if (scope === "both") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+		addAgents(bundledAgents);
+		addAgents(userAgents);
+		addAgents(projectAgents);
 	} else if (scope === "user") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
+		addAgents(bundledAgents);
+		addAgents(userAgents);
 	} else {
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+		addAgents(projectAgents);
 	}
 
 	return { agents: Array.from(agentMap.values()), projectAgentsDir };

package/src/resources/extensions/subagent/index.ts

@@ -25,9 +25,9 @@ import {
     getAgentDir,
     getMarkdownTheme,
 } from "@gsd/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@gsd/pi-tui";
+import { Container, Key, Markdown, Spacer, Text } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { formatTokenCount } from "../shared/mod.js";
+import { formatTokenCount, shortcutDesc } from "../shared/mod.js";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
 import { buildSubagentProcessArgs, getBundledExtensionPathsFromEnv } from "./launch-helpers.js";
 import {
@@ -314,7 +314,7 @@ interface UsageStats {
 
 interface SingleResult {
     agent: string;
-    agentSource: "user" | "project" | "unknown";
+    agentSource: "bundled" | "user" | "project" | "unknown";
     task: string;
     exitCode: number;
     messages: Message[];
@@ -327,6 +327,20 @@ interface SingleResult {
     backgroundJobId?: string;
 }
 
+interface ForegroundSingleRunControl {
+    agentName: string;
+    task: string;
+    cwd: string;
+    abortController: AbortController;
+    resultPromise: Promise<{ summary: string; stderr: string; exitCode: number; model?: string }>;
+    adoptToBackground: (jobId: string) => boolean;
+}
+
+interface ForegroundSingleRunHooks {
+    onStart?: (control: ForegroundSingleRunControl) => void;
+    onFinish?: () => void;
+}
+
 interface SubagentDetails {
     mode: "single" | "parallel" | "chain";
     agentScope: AgentScope;
@@ -501,7 +515,8 @@ async function runSingleAgent(
     parentModel: { provider: string; id: string } | undefined,
     signal: AbortSignal | undefined,
     onUpdate: OnUpdateCallback | undefined,
-    makeDetails: (results: SingleResult[]) => SubagentDetails
+    makeDetails: (results: SingleResult[]) => SubagentDetails,
+    foregroundHooks?: ForegroundSingleRunHooks,
 ): Promise<SingleResult> {
     const agent = agents.find((a) => a.name === agentName);
 
@@ -551,6 +566,27 @@ async function runSingleAgent(
         }
     };
 
+    let wasAborted = false;
+    let deferTempPromptCleanup = false;
+    let tempPromptCleanupDone = false;
+
+    const cleanupTempPromptFiles = () => {
+        if (tempPromptCleanupDone) return;
+        tempPromptCleanupDone = true;
+        if (tmpPromptPath)
+            try {
+                fs.unlinkSync(tmpPromptPath);
+            } catch {
+                /* ignore */
+            }
+        if (tmpPromptDir)
+            try {
+                fs.rmdirSync(tmpPromptDir);
+            } catch {
+                /* ignore */
+            }
+    };
+
     try {
         if (agent.systemPrompt.trim()) {
             const tmp = writePromptToTempFile(agent.name, agent.systemPrompt);
@@ -558,7 +594,6 @@ async function runSingleAgent(
             tmpPromptPath = tmp.filePath;
         }
         const args = buildSubagentProcessArgs(agent, task, tmpPromptPath, inferredModel);
-        let wasAborted = false;
 
         const exitCode = await new Promise<number>((resolve) => {
             const bundledPaths = getBundledExtensionPathsFromEnv();
@@ -581,6 +616,7 @@ async function runSingleAgent(
             let buffer = "";
             let completionSeen = false;
             let resolved = false;
+            let foregroundReleased = false;
             const procAbortController = new AbortController();
             let resolveBackgroundResult: ((value: { summary: string; stderr: string; exitCode: number; model?: string }) => void) | undefined;
             let rejectBackgroundResult: ((reason?: unknown) => void) | undefined;
@@ -595,7 +631,27 @@ async function runSingleAgent(
                 resolve(code);
             };
 
+            const adoptToBackground = (jobId: string): boolean => {
+                if (resolved || foregroundReleased) return false;
+                foregroundReleased = true;
+                deferTempPromptCleanup = true;
+                currentResult.backgroundJobId = jobId;
+                finishForeground(0);
+                return true;
+            };
 
+            backgroundResultPromise.finally(() => {
+                if (deferTempPromptCleanup) cleanupTempPromptFiles();
+            });
+
+            foregroundHooks?.onStart?.({
+                agentName,
+                task,
+                cwd: cwd ?? defaultCwd,
+                abortController: procAbortController,
+                resultPromise: backgroundResultPromise,
+                adoptToBackground,
+            });
 
             proc.stdout.on("data", (data) => {
                 buffer += data.toString();
@@ -631,12 +687,14 @@ async function runSingleAgent(
                     exitCode: finalExitCode,
                     model: currentResult.model,
                 });
+                foregroundHooks?.onFinish?.();
                 finishForeground(finalExitCode);
             });
 
             proc.on("error", (error) => {
                 liveSubagentProcesses.delete(proc);
                 rejectBackgroundResult?.(error);
+                foregroundHooks?.onFinish?.();
                 finishForeground(1);
             });
 
@@ -670,18 +728,7 @@ async function runSingleAgent(
         if (wasAborted) throw new Error("Subagent was aborted");
         return currentResult;
     } finally {
-        if (tmpPromptPath)
-            try {
-                fs.unlinkSync(tmpPromptPath);
-            } catch {
-                /* ignore */
-            }
-        if (tmpPromptDir)
-            try {
-                fs.rmdirSync(tmpPromptDir);
-            } catch {
-                /* ignore */
-            }
+        if (!deferTempPromptCleanup) cleanupTempPromptFiles();
     }
 }
 
@@ -754,6 +801,10 @@ const SubagentParams = Type.Object({
 
 export default function(pi: ExtensionAPI) {
     let bgManager: BackgroundJobManager | null = null;
+    const foregroundSubagentStatusKey = "foreground-subagent";
+    const foregroundSubagentHint = "Ctrl+B: move foreground subagent to background";
+    type ActiveForegroundSubagent = ForegroundSingleRunControl & { claimed: boolean };
+    let activeForegroundSubagent: ActiveForegroundSubagent | null = null;
 
     function getBgManager(): BackgroundJobManager {
         if (!bgManager) throw new Error("BackgroundJobManager not initialized.");
@@ -792,6 +843,7 @@ export default function(pi: ExtensionAPI) {
 
 
     pi.on("session_before_switch", async () => {
+        activeForegroundSubagent = null;
         if (bgManager) {
             for (const job of bgManager.getRunningJobs()) {
                 bgManager.cancel(job.id);
@@ -800,6 +852,7 @@ export default function(pi: ExtensionAPI) {
     });
 
     pi.on("session_shutdown", async () => {
+        activeForegroundSubagent = null;
         await stopLiveSubagents();
         if (bgManager) {
             bgManager.shutdown();
@@ -919,6 +972,49 @@ export default function(pi: ExtensionAPI) {
         },
     });
 
+    pi.registerShortcut(Key.ctrl("b"), {
+        description: shortcutDesc("Move foreground subagent to background", "/subagents list"),
+        handler: async (ctx) => {
+            const running = activeForegroundSubagent;
+            if (!running || running.claimed) return;
+            const manager = bgManager;
+            if (!manager) {
+                ctx.ui.notify("Background subagent manager is not available.", "error");
+                return;
+            }
+
+            running.claimed = true;
+            let jobId: string;
+            try {
+                jobId = manager.adoptRunning(
+                    running.agentName,
+                    running.task,
+                    running.cwd,
+                    running.abortController,
+                    running.resultPromise,
+                );
+            } catch (error) {
+                running.claimed = false;
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+                return;
+            }
+
+            const released = running.adoptToBackground(jobId);
+            if (!released) {
+                running.claimed = false;
+                manager.cancel(jobId);
+                return;
+            }
+
+            activeForegroundSubagent = null;
+            ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
+            ctx.ui.notify(
+                `Moved ${running.agentName} to background as ${jobId}. Use /subagents wait ${jobId}, /subagents output ${jobId}, or /subagents cancel ${jobId}.`,
+                "info",
+            );
+        },
+    });
+
     pi.registerTool({
         name: "await_subagent",
         label: "Await Background Subagent",
@@ -949,13 +1045,15 @@ export default function(pi: ExtensionAPI) {
             "Model selection can be overridden per call, otherwise it is inferred from the agent config, delegated-task preferences, or the current session model.",
             "Modes: single ({ agent, task }), parallel ({ tasks: [{agent, task},...] }), chain ({ chain: [{agent, task},...] } with {previous} placeholder).",
             "Agents are defined as .md files in the configured user agent directory (for LSD this is typically ~/.lsd/agent/agents/) or project-local .lsd/agents/, with legacy support for .gsd/agents/ and .pi/agents/.",
+            "If the user asks for a named subagent such as scout, worker, reviewer, or planner, invoke this tool directly rather than the Skill tool.",
             "Use the /subagent command to list available agents and their descriptions.",
             "Set background: true (single mode only) to run detached — returns immediately with a sa_xxxx job ID. Completion is announced back into the session. Use await_subagent or /subagents to manage background jobs.",
         ].join(" "),
         promptGuidelines: [
             "Use subagent to delegate self-contained tasks that benefit from an isolated context window.",
-            "When scout is the right fit, call the subagent tool directly — do not type '/subagent' as a shell-like command.",
+            "The subagent tool is available directly as a tool call — invoke it programmatically like any other tool, not via a slash command. Do NOT type '/scout' or '/subagent' in the chat; call this tool with the correct parameters instead.",
             "Valid call shapes: single mode uses { agent, task }, parallel mode uses { tasks: [{ agent, task }, ...] }, and chain mode uses { chain: [{ agent, task }, ...] }.",
+            "If the user names a subagent such as scout, worker, reviewer, or planner, use this subagent tool directly rather than the Skill tool or ad-hoc search.",
             "Recon planning rule: use no scout for narrow known-file work, one scout for one broad unfamiliar subsystem, and parallel scouts only when the work spans multiple loosely-coupled subsystems.",
             "Use scout only for broad or unfamiliar codebase reconnaissance before you read many files yourself; save direct reads for targeted lookups once the relevant files are known.",
             "Do not use scout as the reviewer, auditor, or final judge. Scout should map architecture, files, ownership, and likely hotspots for another agent or the parent model to evaluate.",
@@ -1301,8 +1399,27 @@ export default function(pi: ExtensionAPI) {
                         signal,
                         onUpdate,
                         makeDetails("single"),
+                        !isolation
+                            ? {
+                                onStart: (control) => {
+                                    activeForegroundSubagent = { ...control, claimed: false };
+                                    ctx.ui.setStatus(foregroundSubagentStatusKey, foregroundSubagentHint);
+                                },
+                                onFinish: () => {
+                                    activeForegroundSubagent = null;
+                                    ctx.ui.setStatus(foregroundSubagentStatusKey, undefined);
+                                },
+                            }
+                            : undefined,
                     );
 
+                    if (result.backgroundJobId) {
+                        return {
+                            content: [{ type: "text", text: `Moved ${result.agent} to background as **${result.backgroundJobId}**. Use \`await_subagent\`, \`/subagents wait ${result.backgroundJobId}\`, or \`/subagents output ${result.backgroundJobId}\`.` }],
+                            details: makeDetails("single")([result]),
+                        };
+                    }
+
                     // Capture and merge delta if isolated
                     if (isolation) {
                         const patches = await isolation.captureDelta();
@@ -1464,6 +1581,9 @@ export default function(pi: ExtensionAPI) {
                     text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
                     if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
                 }
+                if (!isError && !r.backgroundJobId && !finalOutput) {
+                    text += `\n${theme.fg("muted", "Hint: Ctrl+B to move running foreground subagent to background")}`;
+                }
                 const usageStr = formatUsageStats(r.usage, r.model);
                 if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
                 return new Text(text, 0, 0);