@oh-my-pi/pi-coding-agent 17.2.4 → 17.2.5

package/src/session/session-paths.ts

@@ -2,10 +2,17 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { getTerminalId } from "@oh-my-pi/pi-tui";
-import { getSessionsDir, getTerminalSessionsDir, isEnoent, logger, resolveEquivalentPath } from "@oh-my-pi/pi-utils";
+import {
+	getSessionsDir,
+	getTerminalSessionsDir,
+	isEnoent,
+	isRecord,
+	logger,
+	resolveEquivalentPath,
+} from "@oh-my-pi/pi-utils";
 import type { SessionStorage } from "./session-storage";
 
-const migratedSessionRoots = new Set<string>();
+const SESSION_HEADER_PREFIX_BYTES = 4096;
 
 /**
  * Merge or rename a legacy session directory into its canonical target.
@@ -35,12 +42,16 @@ function encodeLegacyAbsoluteSessionDirName(cwd: string): string {
 	return `--${resolvedCwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
 }
 
-function encodeRelativeSessionDirName(prefix: string, relative: string): string {
+function encodeLegacyRelativeSessionDirName(prefix: string, relative: string): string {
 	const encoded = relative.replace(/[/\\:]/g, "-");
 	return encoded ? (prefix.endsWith("-") ? `${prefix}${encoded}` : `${prefix}-${encoded}`) : prefix;
 }
 
-function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolvedCwd: string } {
+function getDefaultSessionDirName(cwd: string): {
+	encodedDirName: string;
+	legacyRelativeDirName: string | undefined;
+	resolvedCwd: string;
+} {
 	const resolvedCwd = path.resolve(cwd);
 	const canonicalCwd = resolveEquivalentPath(resolvedCwd);
 	const home = os.homedir();
@@ -49,72 +60,111 @@ function getDefaultSessionDirName(cwd: string): { encodedDirName: string; resolv
 	const canonicalTempRoot = resolveEquivalentPath(tempRoot);
 	const homeRelative = path.relative(canonicalHome, canonicalCwd);
 	const tempRelative = path.relative(canonicalTempRoot, canonicalCwd);
-	const encodedDirName =
-		homeRelative === "" || (!homeRelative.startsWith("..") && !path.isAbsolute(homeRelative))
-			? encodeRelativeSessionDirName("-", homeRelative)
-			: tempRelative === "" || (!tempRelative.startsWith("..") && !path.isAbsolute(tempRelative))
-				? encodeRelativeSessionDirName("-tmp", tempRelative)
-				: encodeLegacyAbsoluteSessionDirName(canonicalCwd);
-	return { encodedDirName, resolvedCwd };
-}
 
-/**
- * Migrate old `--<home-encoded>-*--` session dirs to the new `-*` format.
- * Runs once per sessions root on first access, best-effort.
- */
-function migrateHomeSessionDirs(sessionsRoot: string): void {
-	if (migratedSessionRoots.has(sessionsRoot)) return;
-	migratedSessionRoots.add(sessionsRoot);
+	let scope: "home" | "tmp" | "abs";
+	let legacyRelativeDirName: string | undefined;
+	if (homeRelative === "" || (!homeRelative.startsWith("..") && !path.isAbsolute(homeRelative))) {
+		scope = "home";
+		legacyRelativeDirName = encodeLegacyRelativeSessionDirName("-", homeRelative);
+	} else if (tempRelative === "" || (!tempRelative.startsWith("..") && !path.isAbsolute(tempRelative))) {
+		scope = "tmp";
+		legacyRelativeDirName = encodeLegacyRelativeSessionDirName("-tmp", tempRelative);
+	} else {
+		scope = "abs";
+	}
 
-	const home = os.homedir();
-	const homeEncoded = home.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-");
-	const oldPrefix = `--${homeEncoded}-`;
-	const oldExact = `--${homeEncoded}--`;
+	const normalized = canonicalCwd.replaceAll("\\", "/");
+	const readable = path
+		.basename(canonicalCwd)
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(-80);
+	const digest = Bun.SHA256.hash(normalized, "hex");
+	const encodedDirName = `${scope}-${readable || "project"}-${digest}`;
+	return { encodedDirName, legacyRelativeDirName, resolvedCwd };
+}
 
-	let entries: string[];
+function readSessionCwd(sessionFile: string, buffer: Buffer): string | undefined {
+	let descriptor: number | undefined;
 	try {
-		entries = fs.readdirSync(sessionsRoot);
+		descriptor = fs.openSync(sessionFile, "r");
+		const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, 0);
+		const prefix = buffer.toString("utf8", 0, bytesRead);
+		for (const line of prefix.split(/\r?\n/, 3)) {
+			try {
+				const record: unknown = JSON.parse(line);
+				if (isRecord(record) && record.type === "session" && typeof record.cwd === "string") {
+					return record.cwd;
+				}
+			} catch {
+				// Ignore title slots or truncated/corrupt headers.
+			}
+		}
 	} catch {
-		return;
+		// Best-effort migration leaves unreadable sessions in the current bucket.
+	} finally {
+		if (descriptor !== undefined) fs.closeSync(descriptor);
 	}
+	return undefined;
+}
 
+function moveSessionBundle(sourceDir: string, targetDir: string, sessionName: string, entries: string[]): void {
+	fs.mkdirSync(targetDir, { recursive: true });
+	const artifactsName = path.basename(sessionName, ".jsonl");
 	for (const entry of entries) {
-		let remainder: string;
-		if (entry === oldExact) {
-			remainder = "";
-		} else if (entry.startsWith(oldPrefix) && entry.endsWith("--")) {
-			remainder = entry.slice(oldPrefix.length, -2);
+		if (entry !== sessionName && entry !== artifactsName && !entry.startsWith(`${sessionName}.`)) continue;
+		const source = path.join(sourceDir, entry);
+		if (!fs.existsSync(source)) continue;
+		const target = path.join(targetDir, entry);
+		const existing = fs.statSync(target, { throwIfNoEntry: false });
+		if (!existing) {
+			fs.renameSync(source, target);
+		} else if (existing.isDirectory() && fs.statSync(source).isDirectory()) {
+			migrateSessionDirPath(source, target);
 		} else {
-			continue;
-		}
-
-		const newName = remainder ? `-${remainder}` : "-";
-		const oldPath = path.join(sessionsRoot, entry);
-		const newPath = path.join(sessionsRoot, newName);
-
-		try {
-			migrateSessionDirPath(oldPath, newPath);
-		} catch {
-			// Best effort
+			fs.rmSync(source, { recursive: true, force: true });
 		}
 	}
 }
 
-function migrateLegacyAbsoluteSessionDir(cwd: string, sessionDir: string, sessionsRoot: string): void {
-	const legacyDir = path.join(sessionsRoot, encodeLegacyAbsoluteSessionDirName(cwd));
-	if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) return;
-
-	try {
-		migrateSessionDirPath(legacyDir, sessionDir);
-	} catch {
-		// Best effort
+function rerouteCollidingSessions(
+	cwd: string,
+	legacyDir: string,
+	sessionsRoot: string,
+	kind: "relative" | "absolute",
+): void {
+	const entries = fs.readdirSync(legacyDir);
+	const currentCwd = resolveEquivalentPath(path.resolve(cwd));
+	const buffer = Buffer.allocUnsafe(SESSION_HEADER_PREFIX_BYTES);
+	for (const entry of entries) {
+		if (!entry.endsWith(".jsonl")) continue;
+		const recordedCwd = readSessionCwd(path.join(legacyDir, entry), buffer);
+		if (!recordedCwd) continue;
+		const recordedCanonical = resolveEquivalentPath(path.resolve(recordedCwd));
+		if (
+			recordedCanonical === currentCwd ||
+			!fs.statSync(recordedCanonical, { throwIfNoEntry: false })?.isDirectory()
+		) {
+			continue;
+		}
+		const recordedNames = getDefaultSessionDirName(recordedCanonical);
+		const recordedLegacyName =
+			kind === "relative"
+				? recordedNames.legacyRelativeDirName
+				: encodeLegacyAbsoluteSessionDirName(recordedCanonical);
+		if (recordedLegacyName !== path.basename(legacyDir)) continue;
+		moveSessionBundle(legacyDir, path.join(sessionsRoot, recordedNames.encodedDirName), entry, entries);
 	}
 }
 
 export function resolveManagedSessionRoot(sessionDir: string, cwd: string): string | undefined {
 	const currentDirName = path.basename(sessionDir);
-	const { encodedDirName } = getDefaultSessionDirName(cwd);
-	if (currentDirName !== encodedDirName && currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)) {
+	const { encodedDirName, legacyRelativeDirName } = getDefaultSessionDirName(cwd);
+	if (
+		currentDirName !== encodedDirName &&
+		currentDirName !== legacyRelativeDirName &&
+		currentDirName !== encodeLegacyAbsoluteSessionDirName(cwd)
+	) {
 		return undefined;
 	}
 	return path.dirname(sessionDir);
@@ -130,10 +180,23 @@ export function computeDefaultSessionDir(
 	storage: SessionStorage,
 	sessionsRoot: string = getSessionsDir(),
 ): string {
-	const { encodedDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
-	migrateHomeSessionDirs(sessionsRoot);
+	const { encodedDirName, legacyRelativeDirName, resolvedCwd } = getDefaultSessionDirName(cwd);
 	const sessionDir = path.join(sessionsRoot, encodedDirName);
-	migrateLegacyAbsoluteSessionDir(resolvedCwd, sessionDir, sessionsRoot);
+	const legacyDirs: Array<{ kind: "relative" | "absolute"; name: string | undefined }> = [
+		{ kind: "relative", name: legacyRelativeDirName },
+		{ kind: "absolute", name: encodeLegacyAbsoluteSessionDirName(resolvedCwd) },
+	];
+	for (const legacy of legacyDirs) {
+		if (!legacy.name) continue;
+		const legacyDir = path.join(sessionsRoot, legacy.name);
+		if (legacyDir === sessionDir || !fs.existsSync(legacyDir)) continue;
+		try {
+			rerouteCollidingSessions(resolvedCwd, legacyDir, sessionsRoot, legacy.kind);
+			migrateSessionDirPath(legacyDir, sessionDir);
+		} catch {
+			// Best effort
+		}
+	}
 	storage.ensureDirSync(sessionDir);
 	return sessionDir;
 }

package/src/session/session-stats.ts

@@ -34,6 +34,11 @@ export interface SessionStatsTrackerHost {
 	sessionId(): string;
 }
 
+function correctedPromptTokens(assistant: AssistantMessage): number {
+	const providerPromptTokens = assistant.contextSnapshot?.promptTokens ?? calculatePromptTokens(assistant.usage);
+	return Math.max(0, providerPromptTokens - (assistant.contextSnapshot?.historyRewriteTokensRemoved ?? 0));
+}
+
 /** Computes session totals and tracks the in-flight context estimate. */
 export class SessionStatsTracker {
 	readonly #host: SessionStatsTrackerHost;
@@ -160,8 +165,7 @@ export class SessionStatsTracker {
 		const useAnchor =
 			anchorAssistant !== undefined && anchorIndex !== -1 && (!pending || anchorIndex >= pending.cutoffCount);
 		if (useAnchor && anchorAssistant) {
-			const promptTokens =
-				anchorAssistant.contextSnapshot?.promptTokens ?? calculatePromptTokens(anchorAssistant.usage);
+			const promptTokens = correctedPromptTokens(anchorAssistant);
 			const nonMessageTokens =
 				anchorAssistant.contextSnapshot?.nonMessageTokens ?? computeNonMessageTokens(this.#host.session);
 			anchored = true;
@@ -199,7 +203,7 @@ export class SessionStatsTracker {
 				) {
 					continue;
 				}
-				const promptTokens = message.contextSnapshot?.promptTokens ?? calculatePromptTokens(message.usage);
+				const promptTokens = correctedPromptTokens(message);
 				const nonMessageTokens =
 					message.contextSnapshot?.nonMessageTokens ?? computeNonMessageTokens(this.#host.session);
 				let tailTokens = 0;
@@ -256,6 +260,47 @@ export class SessionStatsTracker {
 		return this.#pendingContextSnapshot?.nonMessageTokens;
 	}
 
+	/**
+	 * Apply an estimated prompt-prefix reduction to the current provider anchor.
+	 *
+	 * History after the anchor is estimated live by {@link getContextBreakdown};
+	 * callers must pass only savings from entries already included in the
+	 * anchor's provider-reported prompt. Persisting the correction on the
+	 * assistant snapshot keeps reloads accurate, and the next successful
+	 * assistant response naturally replaces it with a fresh provider anchor.
+	 */
+	recordAnchoredHistoryRewrite(tokensRemoved: number): void {
+		if (!Number.isFinite(tokensRemoved) || tokensRemoved <= 0) return;
+
+		const branchEntries = this.#host.sessionManager.getBranch();
+		const latestCompaction = getLatestCompactionEntry(branchEntries);
+		const compactionIndex = latestCompaction ? branchEntries.lastIndexOf(latestCompaction) : -1;
+		for (let index = branchEntries.length - 1; index > compactionIndex; index--) {
+			const entry = branchEntries[index];
+			if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+			const assistant = entry.message;
+			if (
+				assistant.stopReason === "aborted" ||
+				assistant.stopReason === "error" ||
+				!assistant.usage ||
+				!hasContextTokenUsage(assistant.usage)
+			) {
+				continue;
+			}
+
+			if (!assistant.contextSnapshot) {
+				assistant.contextSnapshot = {
+					promptTokens: calculatePromptTokens(assistant.usage),
+					nonMessageTokens: computeNonMessageTokens(this.#host.session),
+				};
+			}
+			const snapshot = assistant.contextSnapshot;
+			snapshot.historyRewriteTokensRemoved = (snapshot.historyRewriteTokensRemoved ?? 0) + Math.floor(tokensRemoved);
+			this.#contextUsageRevision++;
+			return;
+		}
+	}
+
 	/** Sets or clears the in-flight context snapshot. */
 	setPendingSnapshot(snapshot: PendingContextSnapshot | undefined): void {
 		this.#pendingContextSnapshot = snapshot;

package/src/session/session-storage.ts

@@ -14,13 +14,25 @@ export interface SessionStorageStat {
 
 export interface SessionStorageWriter {
 	/**
-	 * Append one newline-terminated line. File storage batches same-turn appends
-	 * until its microtask boundary; memory storage updates in-body; indexed
-	 * backends queue in call order.
+	 * Append one newline-terminated line.
+	 *
+	 * File and memory storage apply the line synchronously before the returned
+	 * promise settles, so a software crash after `append` returns (or after a
+	 * fire-and-forget call begins) still sees the entry on disk / in body. No
+	 * `fsync` — power loss may still drop the last page. Indexed backends update
+	 * the local index immediately and queue the remote publish in call order.
 	 *
 	 * `line` MUST include the trailing newline.
 	 */
 	append(line: string): Promise<void>;
+	/**
+	 * Synchronous append when the backend can apply the line before return.
+	 * File and memory implement this so {@link SessionManager} can latch the
+	 * first write failure before the appending call returns (surfaced by a later
+	 * flushSync/close/next append — the turn loop does not throw from append).
+	 * Indexed backends update the local index immediately and queue remote I/O.
+	 */
+	appendSync?(line: string): void;
 	/** Resolve once all queued appends complete. No fsync. */
 	flush(): Promise<void>;
 	/** Drain synchronously flushable queued work when the backend supports it. No fsync. */
@@ -93,8 +105,6 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 	#closed = false;
 	#error: Error | undefined;
 	#onError: ((err: Error) => void) | undefined;
-	#pending = "";
-	#flushScheduled = false;
 
 	constructor(fpath: string, options?: { flags?: "a" | "w"; onError?: (err: Error) => void }) {
 		this.#onError = options?.onError;
@@ -129,34 +139,29 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
-	#flushPendingNow(): void {
-		this.#flushScheduled = false;
-		if (this.#pending.length === 0) return;
-		const pending = this.#pending;
-		this.#pending = "";
+	appendSync(line: string): void {
+		if (this.#closed) throw new Error("Writer closed");
+		if (this.#error) throw this.#error;
+		// Write in-body so software crash after the call still sees the entry.
+		// Microtask batching used to leave completed transcript lines only in
+		// memory until the next event-loop turn; process crash then lost every
+		// post-checkpoint event. flush/flushSync remain no-op drains (no fsync).
 		try {
-			this.#writeNow(pending);
+			this.#writeNow(line);
 		} catch (err) {
-			this.#recordError(err);
+			throw this.#recordError(err);
 		}
 	}
 
 	async append(line: string): Promise<void> {
-		if (this.#closed) throw new Error("Writer closed");
-		if (this.#error) throw this.#error;
-		this.#pending += line;
-		if (this.#flushScheduled) return;
-		this.#flushScheduled = true;
-		queueMicrotask(() => this.#flushPendingNow());
+		this.appendSync(line);
 	}
 
 	async flush(): Promise<void> {
-		this.#flushPendingNow();
 		if (this.#error) throw this.#error;
 	}
 
 	flushSync(): void {
-		this.#flushPendingNow();
 		if (this.#error) throw this.#error;
 	}
 
@@ -166,7 +171,6 @@ class FileSessionStorageWriter implements SessionStorageWriter {
 
 	async close(): Promise<void> {
 		if (this.#closed) return;
-		this.#flushPendingNow();
 		this.#closed = true;
 		// Unregister from finalization - we're closing properly
 		writerRegistry.unregister(this);
@@ -487,7 +491,7 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		return error;
 	}
 
-	async append(line: string): Promise<void> {
+	appendSync(line: string): void {
 		if (this.#closed) throw new Error("Writer closed");
 		if (this.#error) throw this.#error;
 		try {
@@ -498,6 +502,10 @@ class MemorySessionStorageWriter implements SessionStorageWriter {
 		}
 	}
 
+	async append(line: string): Promise<void> {
+		this.appendSync(line);
+	}
+
 	async flush(): Promise<void> {
 		if (this.#error) throw this.#error;
 	}

package/src/session/stream-guards.ts

@@ -164,7 +164,7 @@ export class StreamingEditGuard {
 		const toolCall = messageContent[contentIndex] as ToolCall;
 		if (toolCall.name !== "edit") return undefined;
 		const args = toolCall.arguments;
-		if (!args || typeof args !== "object" || Array.isArray(args) || "old_text" in args || "new_text" in args) {
+		if (!args || typeof args !== "object" || Array.isArray(args) || "old_string" in args || "new_string" in args) {
 			return undefined;
 		}
 		const filePath = typeof args.path === "string" ? args.path : undefined;

package/src/slash-commands/builtin-registry.ts

@@ -102,39 +102,42 @@ function formatFastModeStatus(session: AgentSession): string {
 }
 
 /** Detailed, session-effective `/computer status` diagnostics. */
-function formatComputerUseStatus(session: AgentSession): string {
+async function formatComputerUseStatus(session: AgentSession): Promise<string> {
 	const enabled = session.settings.get("computer.enabled");
 	const active = session.getEnabledToolNames().includes("computer");
 	const model = session.model;
 	const modelName = model ? formatModelString(model) : "none";
-	const exposure = !enabled || !active ? "not exposed" : computerExposureMode(model);
-	const toolState = active ? "active" : enabled ? "unavailable" : "inactive";
+	const exposure = !enabled
+		? "not exposed (disabled)"
+		: !active
+			? "not exposed (tool inactive)"
+			: computerExposureMode(model);
 	const configured = {
-		backend: session.settings.get("computer.backend"),
 		display: session.settings.get("computer.display"),
 		maxWidth: session.settings.get("computer.maxWidth"),
 		maxHeight: session.settings.get("computer.maxHeight"),
 	};
-	const computerTool = session.getToolByName("computer") as Pick<ComputerTool, "effectiveConfiguration"> | undefined;
-	const effective = computerTool?.effectiveConfiguration ?? configured;
-	const configurationChanged =
-		effective.backend !== configured.backend ||
-		effective.display !== configured.display ||
-		effective.maxWidth !== configured.maxWidth ||
-		effective.maxHeight !== configured.maxHeight;
+	const computerTool = active
+		? (session.getToolByName("computer") as Pick<ComputerTool, "capabilities"> | undefined)
+		: undefined;
+	const capabilities = await computerTool?.capabilities();
+	const capabilityStatus = capabilities
+		? [
+				`backend=${capabilities.backend}${capabilities.displayServer ? `/${capabilities.displayServer}` : ""}`,
+				`capture=${capabilities.capture} (${capabilities.capturePermission})`,
+				`input=${capabilities.input} (${capabilities.inputPermission})`,
+				`ax=${capabilities.ax} (${capabilities.axPermission})`,
+				`backgroundWindowInput=${capabilities.backgroundWindowInput}`,
+				`deliveryModes=${capabilities.deliveryModes.join(",") || "none"}`,
+			].join(", ")
+		: "session not started";
 	return [
 		`Computer use: ${enabled ? "enabled" : "disabled"}`,
-		`tool: ${toolState}`,
-		`backend: ${effective.backend}`,
-		`display: ${effective.display}`,
-		`capture: ${effective.maxWidth}×${effective.maxHeight}`,
-		...(configurationChanged
-			? [
-					`next-session settings: backend=${configured.backend}, display=${configured.display}, capture=${configured.maxWidth}×${configured.maxHeight}`,
-				]
-			: []),
-		`model: ${modelName}`,
+		`tool: ${active ? "active" : "inactive"}`,
 		`exposure: ${exposure}`,
+		`model: ${modelName}`,
+		`configured: display=${configured.display}, maxWidth=${configured.maxWidth}, maxHeight=${configured.maxHeight}`,
+		`capabilities: ${capabilityStatus}`,
 	].join(" · ");
 }
 
@@ -151,7 +154,7 @@ async function applyComputerUseToggle(session: AgentSession, enable: boolean): P
 	}
 	session.settings.override("computer.enabled", enable);
 	return enable
-		? `Computer use enabled for this session. ${formatComputerUseStatus(session)}`
+		? `Computer use enabled for this session. ${await formatComputerUseStatus(session)}`
 		: "Computer use disabled for this session.";
 }
 
@@ -673,7 +676,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		handle: async (command, runtime) => {
 			const arg = command.args.trim().toLowerCase();
 			if (arg === "status") {
-				await runtime.output(formatComputerUseStatus(runtime.session));
+				await runtime.output(await formatComputerUseStatus(runtime.session));
 				return commandConsumed();
 			}
 			if (!arg || arg === "toggle" || arg === "on" || arg === "off") {
@@ -686,7 +689,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		handleTui: async (command, runtime) => {
 			const arg = command.args.trim().toLowerCase();
 			if (arg === "status") {
-				runtime.ctx.showStatus(formatComputerUseStatus(runtime.ctx.session));
+				runtime.ctx.showStatus(await formatComputerUseStatus(runtime.ctx.session));
 				runtime.ctx.editor.setText("");
 				return;
 			}

package/src/system-prompt.ts

@@ -498,7 +498,8 @@ export interface BuildSystemPromptOptions {
 	/**
 	 * Whether provider-native tool calling is active (no owned/in-band syntax).
 	 * When true and `inlineToolDescriptors` is false, the inventory renders as a
-	 * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
+	 * compact tool-name list; otherwise it renders the full Harmony-style
+	 * `namespace functions { … }` catalog. Default: true
 	 */
 	nativeTools?: boolean;
 	/** Skills settings for discovery. */
@@ -525,6 +526,9 @@ export interface BuildSystemPromptOptions {
 	taskMaxConcurrency?: number;
 	/** Whether IRC-backed parallel coordination can be included in delegation policy. */
 	taskIrcEnabled?: boolean;
+	/** Whether the read-only `scout` subagent is spawnable (not disabled, allowed by spawn policy). Defaults to true. */
+	scoutAvailable?: boolean;
+
 	/** Rules with alwaysApply=true — their full content is injected into the prompt. */
 	alwaysApplyRules?: AlwaysApplyRule[];
 	/** Whether secret obfuscation is active. When true, explains the redaction format in the prompt. */
@@ -599,6 +603,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		taskIrcEnabled = false,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
+		scoutAvailable = true,
 		memoryRootEnabled = false,
 		securityEnabled = false,
 		model,
@@ -793,7 +798,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 
 	// List mode shows a compact tool-name list; it only applies when descriptors
 	// stay in provider-native tool schemas AND native tool calling is active.
-	// Otherwise render full `# Tool:` sections inline in the system prompt.
+	// Otherwise render the full functions-namespace catalog in the system prompt.
 	const toolListMode = !inlineToolDescriptors && nativeTools;
 	// Build tool descriptions for system prompt rendering.
 	const toolPromptNames = new Map<string, string>(toolNames.map(name => [name, tools?.get(name)?.wireName ?? name]));
@@ -826,7 +831,6 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 						examples: meta?.examples,
 					};
 				}),
-				model ?? "",
 			);
 
 	// Filter skills for the rendered system prompt:
@@ -879,6 +883,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		eagerTasksAlways,
 		taskBatch,
 		MAX_CONCURRENCY: normalizeConcurrencyLimit(taskMaxConcurrency),
+		scoutAvailable,
 		taskIrcEnabled,
 		secretsEnabled,
 		hasMemoryRoot: memoryRootEnabled,

package/src/task/index.ts

@@ -27,7 +27,7 @@ import { TASK_EFFORTS, type TaskEffort } from "../thinking";
 import { truncateForPrompt } from "../tools/approval";
 import { isIrcEnabled } from "../tools/hub";
 import { formatBytes, formatDuration } from "../tools/render-utils";
-import { resolveSpawnPolicy } from "./spawn-policy";
+import { isScoutSpawnable, resolveSpawnPolicy } from "./spawn-policy";
 import {
 	type AgentDefinition,
 	type AgentProgress,
@@ -188,8 +188,10 @@ function renderDescription(options: TaskDescriptionOptions): string {
 		readOnly: isReadOnlyAgent(agent),
 		blocking: agent.blocking === true,
 	}));
+	const scoutAvailable = isScoutSpawnable(options.disabledAgents, options.parentSpawns);
 	return prompt.render(taskDescriptionTemplate, {
 		agents: renderedAgents,
+		scoutAvailable,
 		spawningDisabled,
 		defaultAgent: spawnPolicy.defaultAgent,
 		isolationEnabled: options.isolationEnabled,
@@ -398,15 +400,19 @@ const GENERIC_SPAWN_AGENTS: ReadonlySet<string> = new Set(["task", "sonic"]);
  * (DepthCapacity: it currently has the `task` tool). `agentNames` are the
  * per-item resolved agent types. Returns undefined when no nudge applies.
  */
-export function buildSpecializationAdvisory(agentNames: string[], depthCapacity: boolean): string | undefined {
+export function buildSpecializationAdvisory(
+	agentNames: string[],
+	depthCapacity: boolean,
+	scoutAvailable = true,
+): string | undefined {
 	if (!depthCapacity) return undefined;
 	const generics = agentNames.filter(name => GENERIC_SPAWN_AGENTS.has(name));
 	if (generics.length < 2) return undefined;
-	return (
-		`Tip: this call spawned ${generics.length} generic \`${generics[0]}\` workers. ` +
-		`Check the agent list for a closer specialist type — e.g. read-only research belongs on ` +
-		`\`agent: "scout"\`, which runs on a faster model.`
-	);
+	const specialist = scoutAvailable
+		? `Check the agent list for a closer specialist type — e.g. read-only research belongs on ` +
+			`\`agent: "scout"\`, which runs on a faster model.`
+		: `Check the agent list for a closer specialist type.`;
+	return `Tip: this call spawned ${generics.length} generic \`${generics[0]}\` workers. ${specialist}`;
 }
 
 /**
@@ -443,10 +449,11 @@ export function composeSpawnAdvisory(args: {
 	depthCapacity: boolean;
 	ircEnabled: boolean;
 	willRunAsync: boolean;
+	scoutAvailable?: boolean;
 }): string | undefined {
 	return (
 		[
-			buildSpecializationAdvisory(args.agents, args.depthCapacity),
+			buildSpecializationAdvisory(args.agents, args.depthCapacity, args.scoutAvailable),
 			args.willRunAsync ? buildCoordinationAdvisory(args.items, args.depthCapacity, args.ircEnabled) : undefined,
 		]
 			.filter(Boolean)
@@ -751,6 +758,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						depthCapacity,
 						ircEnabled,
 						willRunAsync: false,
+						scoutAvailable: isScoutSpawnable(
+							this.session.settings.get("task.disabledAgents") as string[] | undefined,
+							this.session.getSessionSpawns?.() ?? "*",
+						),
 					});
 			const result = await this.#executeSyncFanout(
 				toolCallId,
@@ -784,6 +795,10 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					depthCapacity,
 					ircEnabled,
 					willRunAsync: asyncItems.length > 0,
+					scoutAvailable: isScoutSpawnable(
+						this.session.settings.get("task.disabledAgents") as string[] | undefined,
+						this.session.getSessionSpawns?.() ?? "*",
+					),
 				});
 		// Returns a fresh result (copied content array, copied text part) rather
 		// than mutating the caller's — task results are short-lived here, but an

package/src/task/spawn-policy.ts

@@ -56,3 +56,17 @@ export function resolveSpawnPolicy(parentSpawns: string | boolean | null | undef
 		allowedPromptText: allowedAgents.map(agent => `\`${agent}\``).join(", "),
 	};
 }
+
+/**
+ * Whether the `scout` agent is spawnable in a session: not disabled via
+ * `task.disabledAgents`, and permitted by the session spawn policy.
+ */
+export function isScoutSpawnable(
+	disabledAgents: readonly string[] | undefined,
+	spawns: string | boolean | null | undefined,
+): boolean {
+	if (disabledAgents?.includes("scout")) return false;
+	const policy = resolveSpawnPolicy(spawns);
+	if (!policy.enabled) return false;
+	return policy.allowedAgents === null || policy.allowedAgents.includes("scout");
+}