@oh-my-pi/pi-coding-agent 14.9.3 → 14.9.5

package/src/sdk.ts

@@ -27,7 +27,7 @@ import chalk from "chalk";
 import { AsyncJobManager, isBackgroundJobSupportEnabled } from "./async";
 import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
-import { type Rule, ruleCapability } from "./capability/rule";
+import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { ModelRegistry } from "./config/model-registry";
 import { formatModelString, parseModelPattern, parseModelString, resolveModelRoleValue } from "./config/model-resolver";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "./config/prompt-templates";
@@ -59,30 +59,22 @@ import {
 	type ToolDefinition,
 	wrapRegisteredTools,
 } from "./extensibility/extensions";
-import { loadSkills as loadSkillsInternal, type Skill, type SkillWarning } from "./extensibility/skills";
+import {
+	loadSkills as loadSkillsInternal,
+	type Skill,
+	type SkillWarning,
+	setActiveSkills,
+} from "./extensibility/skills";
 import { type FileSlashCommand, loadSlashCommands as loadSlashCommandsInternal } from "./extensibility/slash-commands";
 import type { HindsightSessionState } from "./hindsight/state";
-import {
-	AgentProtocolHandler,
-	ArtifactProtocolHandler,
-	InternalUrlRouter,
-	JobsProtocolHandler,
-	LocalProtocolHandler,
-	type LocalProtocolOptions,
-	McpProtocolHandler,
-	MemoryProtocolHandler,
-	PiProtocolHandler,
-	RuleProtocolHandler,
-	SkillProtocolHandler,
-} from "./internal-urls";
+import { LocalProtocolHandler, type LocalProtocolOptions } from "./internal-urls";
 import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "./lsp/startup-events";
-import { discoverAndLoadMCPTools, type MCPManager, type MCPToolsLoadResult } from "./mcp";
+import { discoverAndLoadMCPTools, MCPManager, type MCPToolsLoadResult } from "./mcp";
 import {
 	collectDiscoverableMCPTools,
 	formatDiscoverableMCPToolServerSummary,
 	selectDiscoverableMCPToolNamesByServer,
 } from "./mcp/discoverable-tool-metadata";
-import { getMemoryRoot } from "./memories";
 import { resolveMemoryBackend } from "./memory-backend";
 import asyncResultTemplate from "./prompts/tools/async-result.md" with { type: "text" };
 import { AgentRegistry, MAIN_AGENT_ID } from "./registry/agent-registry";
@@ -917,6 +909,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	let agent: Agent;
 	let session!: AgentSession;
 	let hasSession = false;
+	let hasRegistered = false;
 	const enableLsp = options.enableLsp ?? true;
 	const backgroundJobsEnabled = isBackgroundJobSupportEnabled(settings);
 	const asyncMaxJobs = Math.min(100, Math.max(1, settings.get("async.maxJobs") ?? 100));
@@ -942,34 +935,39 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 
 		return preview;
 	};
-	const asyncJobManager = backgroundJobsEnabled
-		? new AsyncJobManager({
-				maxRunningJobs: asyncMaxJobs,
-				onJobComplete: async (jobId, result, job) => {
-					if (!session || asyncJobManager!.isDeliverySuppressed(jobId)) return;
-					const formattedResult = await formatAsyncResultForFollowUp(result);
-					if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
-
-					const message = prompt.render(asyncResultTemplate, { jobId, result: formattedResult });
-					const durationMs = job ? Math.max(0, Date.now() - job.startTime) : undefined;
-					await session.sendCustomMessage(
-						{
-							customType: "async-result",
-							content: message,
-							display: true,
-							attribution: "agent",
-							details: {
-								jobId,
-								type: job?.type,
-								label: job?.label,
-								durationMs,
+	// Only top-level sessions own an AsyncJobManager. Subagents reach the
+	// parent's manager via `AsyncJobManager.instance()` (set below), so creating
+	// a second instance here just to leave it orphaned wastes a constructor and
+	// risks accidental disposal of the parent's manager on subagent teardown.
+	const asyncJobManager =
+		backgroundJobsEnabled && !options.parentTaskPrefix
+			? new AsyncJobManager({
+					maxRunningJobs: asyncMaxJobs,
+					onJobComplete: async (jobId, result, job) => {
+						if (!session || asyncJobManager!.isDeliverySuppressed(jobId)) return;
+						const formattedResult = await formatAsyncResultForFollowUp(result);
+						if (asyncJobManager!.isDeliverySuppressed(jobId)) return;
+
+						const message = prompt.render(asyncResultTemplate, { jobId, result: formattedResult });
+						const durationMs = job ? Math.max(0, Date.now() - job.startTime) : undefined;
+						await session.sendCustomMessage(
+							{
+								customType: "async-result",
+								content: message,
+								display: true,
+								attribution: "agent",
+								details: {
+									jobId,
+									type: job?.type,
+									label: job?.label,
+									durationMs,
+								},
 							},
-						},
-						{ deliverAs: "followUp", triggerTurn: true },
-					);
-				},
-			})
-		: undefined;
+							{ deliverAs: "followUp", triggerTurn: true },
+						);
+					},
+				})
+			: undefined;
 
 	const agentRegistry = options.agentRegistry ?? AgentRegistry.global();
 	const resolvedAgentId = options.agentId ?? options.parentTaskPrefix ?? MAIN_AGENT_ID;
@@ -1055,44 +1053,27 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					return {};
 				}
 			},
+			getArtifactManager: () => sessionManager.getArtifactManager(),
 			settings,
 			authStorage,
 			modelRegistry,
-			asyncJobManager,
 		};
 
-		// Initialize internal URL router for internal protocols (agent://, artifact://, memory://, skill://, rule://, mcp://, local://)
-		const internalRouter = new InternalUrlRouter();
+		// Wire process-wide internal URL singletons owned by their real classes.
+		// Top-level sessions install the active snapshots; subagents inherit them.
+		// Artifact and agent-output URLs resolve via `AgentRegistry.global()` —
+		// the protocol handlers walk each ref's `sessionManager.getArtifactsDir()`,
+		// which collapses to the parent's dir for subagents (they adopt the
+		// parent's ArtifactManager) so one lookup hits everything.
 		const getArtifactsDir = () => sessionManager.getArtifactsDir();
-		internalRouter.register(new AgentProtocolHandler({ getArtifactsDir }));
-		internalRouter.register(new ArtifactProtocolHandler({ getArtifactsDir }));
-		internalRouter.register(
-			new MemoryProtocolHandler({
-				getMemoryRoot: () => getMemoryRoot(agentDir, settings.getCwd()),
-			}),
-		);
-		internalRouter.register(
-			new LocalProtocolHandler(
-				options.localProtocolOptions ?? {
-					getArtifactsDir,
-					getSessionId: () => sessionManager.getSessionId(),
-				},
-			),
-		);
-		internalRouter.register(
-			new SkillProtocolHandler({
-				getSkills: () => skills,
-			}),
-		);
-		internalRouter.register(
-			new RuleProtocolHandler({
-				getRules: () => [...rulebookRules, ...alwaysApplyRules],
-			}),
-		);
-		internalRouter.register(new PiProtocolHandler());
-		internalRouter.register(new JobsProtocolHandler({ getAsyncJobManager: () => asyncJobManager }));
-		internalRouter.register(new McpProtocolHandler({ getMcpManager: () => mcpManager }));
-		toolSession.internalRouter = internalRouter;
+		if (!options.parentTaskPrefix) {
+			setActiveSkills(skills);
+			setActiveRules([...rulebookRules, ...alwaysApplyRules]);
+			if (asyncJobManager) AsyncJobManager.setInstance(asyncJobManager);
+		}
+		if (options.localProtocolOptions) {
+			LocalProtocolHandler.setOverride(options.localProtocolOptions);
+		}
 		toolSession.getArtifactsDir = getArtifactsDir;
 		toolSession.agentOutputManager = new AgentOutputManager(
 			getArtifactsDir,
@@ -1141,7 +1122,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				customTools.push(...mcpResult.tools.map(loaded => loaded.tool));
 			}
 		}
-		toolSession.mcpManager = mcpManager;
+		// Only top-level sessions own the global MCPManager. Subagents already
+		// receive the parent's manager via `options.mcpManager`, and reassigning
+		// the singleton to the same value is a no-op \u2014 keep the gate explicit
+		// to mirror the AsyncJobManager ownership rule.
+		if (mcpManager && !options.parentTaskPrefix) MCPManager.setInstance(mcpManager);
 
 		// Add image tools when the active model or configured image providers can generate images.
 		const imageGenTools = await logger.time("getImageGenTools", () => getImageGenTools(modelRegistry, model));
@@ -1552,6 +1537,21 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			});
 		}
 
+		// Pre-register in the global agent registry BEFORE building the system prompt,
+		// so that subagents launched in the same parallel batch can see each other in
+		// their initial `# IRC Peers` block (rendered inside `rebuildSystemPrompt`).
+		// The session reference is attached after construction below.
+		agentRegistry.register({
+			id: resolvedAgentId,
+			displayName: resolvedAgentDisplayName,
+			kind: (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main",
+			parentId: options.parentTaskPrefix,
+			session: null,
+			sessionFile: sessionManager.getSessionFile() ?? null,
+			status: "running",
+		});
+		hasRegistered = true;
+
 		const { systemPrompt } = await logger.time(
 			"buildSystemPrompt",
 			rebuildSystemPrompt,
@@ -1708,6 +1708,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			sessionManager,
 			settings,
 			evalKernelOwnerId,
+			// Defined only for top-level sessions (creation is gated above).
+			// AgentSession uses this to decide whether it may dispose the global
+			// AsyncJobManager on teardown; subagents inherit the parent's and
+			// **MUST NOT** tear it down.
+			ownedAsyncJobManager: asyncJobManager,
 			scopedModels: options.scopedModels,
 			promptTemplates,
 			slashCommands,
@@ -1744,24 +1749,16 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			defaultSelectedMCPServerNames: [...discoveryDefaultServers],
 			ttsrManager,
 			obfuscator,
-			asyncJobManager,
 			agentId: resolvedAgentId,
 			agentRegistry,
 			providerSessionId: options.providerSessionId,
 		});
 		hasSession = true;
 
-		// Register this session in the global agent registry so other agents can
-		// address it via the irc tool. Wrap dispose to unregister on teardown.
-		agentRegistry.register({
-			id: resolvedAgentId,
-			displayName: resolvedAgentDisplayName,
-			kind: (options.taskDepth ?? 0) > 0 || options.parentTaskPrefix ? "sub" : "main",
-			parentId: options.parentTaskPrefix,
-			session,
-			sessionFile: sessionManager.getSessionFile() ?? null,
-			status: "running",
-		});
+		// Attach the live session to the pre-registered ref so peers can route IRC
+		// messages here. Refresh sessionFile in case it was unavailable at pre-register
+		// time. The dispose wrapper below unregisters on teardown.
+		agentRegistry.attachSession(resolvedAgentId, session, sessionManager.getSessionFile() ?? null);
 		{
 			const originalDispose = session.dispose.bind(session);
 			session.dispose = async () => {
@@ -1908,6 +1905,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (hasSession) {
 				await session.dispose();
 			} else {
+				if (hasRegistered) agentRegistry.unregister(resolvedAgentId);
 				await disposeKernelSessionsByOwner(evalKernelOwnerId);
 			}
 		} catch (cleanupError) {

package/src/session/agent-session.ts

@@ -55,7 +55,7 @@ import {
 } from "@oh-my-pi/pi-ai";
 import { MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
 import { abortableSleep, getAgentDbPath, isEnoent, logger, prompt, Snowflake } from "@oh-my-pi/pi-utils";
-import type { AsyncJob, AsyncJobManager } from "../async";
+import { type AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
 import {
@@ -225,8 +225,6 @@ export interface AgentSessionConfig {
 	agent: Agent;
 	sessionManager: SessionManager;
 	settings: Settings;
-	/** Async background jobs launched by tools */
-	asyncJobManager?: AsyncJobManager;
 	/** Models to cycle through with Ctrl+P (from --models flag) */
 	scopedModels?: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
 	/** Initial session thinking selector. */
@@ -285,6 +283,12 @@ export interface AgentSessionConfig {
 	obfuscator?: SecretObfuscator;
 	/** Logical owner for retained Python kernels created by this session. */
 	evalKernelOwnerId?: string;
+	/**
+	 * AsyncJobManager that this session installed as the process-global instance.
+	 * Only set for top-level sessions; subagents inherit the parent's manager and
+	 * **MUST NOT** dispose it on their own teardown.
+	 */
+	ownedAsyncJobManager?: AsyncJobManager;
 	/** Agent identity (registry id like "0-Main" or "3-Alice") used for IRC routing. */
 	agentId?: string;
 	/** Shared agent registry (for forwarding IRC observations to the main session UI). */
@@ -507,7 +511,6 @@ export class AgentSession {
 
 	readonly configWarnings: string[] = [];
 
-	#asyncJobManager: AsyncJobManager | undefined = undefined;
 	#scopedModels: Array<{ model: Model; thinkingLevel?: ThinkingLevel }>;
 	#thinkingLevel: ThinkingLevel | undefined;
 	#promptTemplates: PromptTemplate[];
@@ -558,6 +561,11 @@ export class AgentSession {
 	// Python execution state
 	#evalAbortControllers = new Set<AbortController>();
 	#evalKernelOwnerId: string;
+	/**
+	 * AsyncJobManager owned by this session (top-level only). Subagents leave
+	 * this undefined and **MUST NOT** dispose the global instance on teardown.
+	 */
+	readonly #ownedAsyncJobManager: AsyncJobManager | undefined;
 	#pendingPythonMessages: PythonExecutionMessage[] = [];
 	#activeEvalExecutions = new Set<Promise<unknown>>();
 	#evalExecutionDisposing = false;
@@ -704,8 +712,8 @@ export class AgentSession {
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;
 		// Power assertions are taken per turn (see #beginInFlight); nothing acquired here.
-		this.#asyncJobManager = config.asyncJobManager;
 		this.#evalKernelOwnerId = config.evalKernelOwnerId ?? `agent-session:${Snowflake.next()}`;
+		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
 		this.#scopedModels = config.scopedModels ?? [];
 		this.#thinkingLevel = config.thinkingLevel;
 		this.#promptTemplates = config.promptTemplates ?? [];
@@ -848,15 +856,16 @@ export class AgentSession {
 	}
 
 	getAsyncJobSnapshot(options?: { recentLimit?: number }): AsyncJobSnapshot | null {
-		if (!this.#asyncJobManager) return null;
-		const running = this.#asyncJobManager.getRunningJobs().map(job => ({
+		const manager = AsyncJobManager.instance();
+		if (!manager) return null;
+		const running = manager.getRunningJobs().map(job => ({
 			id: job.id,
 			type: job.type,
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
 		}));
-		const recent = this.#asyncJobManager.getRecentJobs(options?.recentLimit ?? 5).map(job => ({
+		const recent = manager.getRecentJobs(options?.recentLimit ?? 5).map(job => ({
 			id: job.id,
 			type: job.type,
 			status: job.status,
@@ -866,6 +875,17 @@ export class AgentSession {
 		return { running, recent };
 	}
 
+	/**
+	 * Cancel async jobs registered by *this* agent only. Used by lifecycle
+	 * transitions (newSession, switchSession, handoff, dispose) so a subagent
+	 * cleans up its own background work without touching its parent's jobs.
+	 * No-op when no manager is installed or this session has no agent id.
+	 */
+	#cancelOwnAsyncJobs(): void {
+		if (!this.#agentId) return;
+		AsyncJobManager.instance()?.cancelAll({ ownerId: this.#agentId });
+	}
+
 	// =========================================================================
 	// Event Subscription
 	// =========================================================================
@@ -1739,7 +1759,6 @@ export class AgentSession {
 	}
 
 	#preCacheStreamingEditFile(event: AgentEvent): void {
-		if (!this.settings.get("edit.streamingAbort")) return;
 		if (this.#streamingEditAbortTriggered) return;
 		if (event.type !== "message_update") return;
 
@@ -1755,6 +1774,9 @@ export class AgentSession {
 		const streamingEdit = this.#getStreamingEditToolCall(event);
 		if (!streamingEdit) return;
 
+		// The auto-generated guard runs unconditionally: editing a generated file
+		// is never the user's intent, and the cost of a false-positive abort is one
+		// wasted turn vs. silently corrupting a regenerated source.
 		const shouldCheckAutoGenerated =
 			!streamingEdit.toolCall.id || !this.#streamingEditPrecheckedToolCallIds.has(streamingEdit.toolCall.id);
 		if (shouldCheckAutoGenerated) {
@@ -1768,7 +1790,12 @@ export class AgentSession {
 			);
 		}
 
-		this.#ensureFileCache(streamingEdit.resolvedPath);
+		// File-cache priming feeds #maybeAbortStreamingEdit's removed-lines check,
+		// which is the optional patch-preview verification gated by
+		// edit.streamingAbort. Skip the read when the setting is off.
+		if (this.settings.get("edit.streamingAbort")) {
+			this.#ensureFileCache(streamingEdit.resolvedPath);
+		}
 	}
 
 	#ensureFileCache(resolvedPath: string): void {
@@ -2149,10 +2176,21 @@ export class AgentSession {
 		}
 		await this.#cancelPostPromptTasks();
 		this.#clearTodoClearTimers();
-		const drained = await this.#asyncJobManager?.dispose({ timeoutMs: 3_000 });
-		const deliveryState = this.#asyncJobManager?.getDeliveryState();
-		if (drained === false && deliveryState) {
-			logger.warn("Async job completion deliveries still pending during dispose", { ...deliveryState });
+		// Cancel jobs this agent registered so a subagent's teardown doesn't
+		// leak its background bash/task work into the parent's manager. Only
+		// the session that owns the manager goes on to dispose it (which itself
+		// nukes any leftover jobs and pending deliveries).
+		this.#cancelOwnAsyncJobs();
+		const ownedAsyncManager = this.#ownedAsyncJobManager;
+		if (ownedAsyncManager) {
+			const drained = await ownedAsyncManager.dispose({ timeoutMs: 3_000 });
+			const deliveryState = ownedAsyncManager.getDeliveryState();
+			if (drained === false && deliveryState) {
+				logger.warn("Async job completion deliveries still pending during dispose", { ...deliveryState });
+			}
+			if (AsyncJobManager.instance() === ownedAsyncManager) {
+				AsyncJobManager.setInstance(undefined);
+			}
 		}
 		const pythonExecutionsSettled = await this.#prepareEvalExecutionsForDispose();
 		if (!pythonExecutionsSettled) {
@@ -3948,7 +3986,7 @@ export class AgentSession {
 
 		this.#disconnectFromAgent();
 		await this.abort();
-		this.#asyncJobManager?.cancelAll();
+		this.#cancelOwnAsyncJobs();
 		this.#closeAllProviderSessions("new session");
 		this.agent.reset();
 		if (options?.drop && previousSessionFile) {
@@ -4756,7 +4794,7 @@ export class AgentSession {
 			// Start a new session
 			const previousSessionFile = this.sessionFile;
 			await this.sessionManager.flush();
-			this.#asyncJobManager?.cancelAll();
+			this.#cancelOwnAsyncJobs();
 			await this.sessionManager.newSession(previousSessionFile ? { parentSession: previousSessionFile } : undefined);
 			this.agent.reset();
 			this.#syncAgentSessionId();
@@ -6675,7 +6713,7 @@ export class AgentSession {
 		const incomingRecord: CustomMessage = {
 			role: "custom",
 			customType: "irc:incoming",
-			content: `[IRC \`${args.from}\` \u2192 you]\n\n${args.message}`,
+			content: `[IRC \`${args.from}\` → you]\n\n${args.message}`,
 			display: true,
 			details: { from: args.from, message: args.message },
 			attribution: "agent",
@@ -6707,7 +6745,7 @@ export class AgentSession {
 		const replyRecord: CustomMessage = {
 			role: "custom",
 			customType: "irc:autoreply",
-			content: `[IRC you \u2192 \`${args.from}\` (auto)]\n\n${replyText}`,
+			content: `[IRC you → \`${args.from}\` (auto)]\n\n${replyText}`,
 			display: true,
 			details: { to: args.from, reply: replyText },
 			attribution: "agent",
@@ -6746,7 +6784,7 @@ export class AgentSession {
 		const mainRef = registry.get(MAIN_AGENT_ID);
 		const mainSession = mainRef?.session;
 		if (!mainSession || mainSession === this) return;
-		const arrow = args.kind === "reply" ? "\u2192 (auto)" : "\u2192";
+		const arrow = args.kind === "reply" ? "→ (auto)" : "→";
 		const relayRecord: CustomMessage = {
 			role: "custom",
 			customType: "irc:relay",
@@ -7149,7 +7187,7 @@ export class AgentSession {
 
 		// Flush pending writes before branching
 		await this.sessionManager.flush();
-		this.#asyncJobManager?.cancelAll();
+		this.#cancelOwnAsyncJobs();
 
 		if (!selectedEntry.parentId) {
 			await this.sessionManager.newSession({ parentSession: previousSessionFile });

package/src/session/artifacts.ts

@@ -12,6 +12,10 @@ import * as path from "node:path";
  *
  * Artifacts are stored with sequential IDs in the session's artifact directory.
  * The directory is created lazily on first write.
+ *
+ * Subagents do not own their own `ArtifactManager`. The parent's instance is
+ * adopted via `SessionManager.adoptArtifactManager`, so the whole parent +
+ * subagent tree shares one ID space and one directory.
  */
 export class ArtifactManager {
 	#nextId = 0;
@@ -20,11 +24,10 @@ export class ArtifactManager {
 	#initialized = false;
 
 	/**
-	 * @param sessionFile Path to the session .jsonl file
+	 * @param dir Directory that will hold artifact files. Created lazily on first save.
 	 */
-	constructor(sessionFile: string) {
-		// Artifact directory is session file path without .jsonl extension
-		this.#dir = sessionFile.slice(0, -6);
+	constructor(dir: string) {
+		this.#dir = dir;
 	}
 
 	/**

package/src/session/session-manager.ts

@@ -275,6 +275,7 @@ export type ReadonlySessionManager = Pick<
 	| "getSessionFile"
 	| "getSessionName"
 	| "getArtifactsDir"
+	| "getArtifactManager"
 	| "allocateArtifactPath"
 	| "saveArtifact"
 	| "getArtifactPath"
@@ -1622,6 +1623,10 @@ export class SessionManager {
 	#persistErrorReported = false;
 	#artifactManager: ArtifactManager | null = null;
 	#artifactManagerSessionFile: string | null = null;
+	// When set, take precedence over the lazily-derived per-session manager.
+	// Subagents adopt the parent's manager so artifact IDs are unique across the
+	// whole agent tree and all files land in the parent's artifacts dir.
+	#adoptedArtifactManager: ArtifactManager | null = null;
 	// In-memory artifact fallback for non-persistent sessions (persist=false).
 	// Keyed by sequential numeric ID string; mirrors the file-based ArtifactManager ID scheme.
 	#inMemoryArtifacts: Map<string, string> | null = null;
@@ -1675,6 +1680,7 @@ export class SessionManager {
 		this.#persistErrorReported = false;
 		this.#artifactManager = null;
 		this.#artifactManagerSessionFile = null;
+		this.#adoptedArtifactManager = null;
 		this.#buildIndex();
 		if (this.#sessionFile) {
 			writeTerminalBreadcrumb(this.cwd, this.#sessionFile);
@@ -2120,17 +2126,40 @@ export class SessionManager {
 	/**
 	 * Returns the session artifacts directory path (session file path without .jsonl).
 	 * Returns null when the session is not persisted to a file.
+	 * When this session has adopted an external ArtifactManager (subagent case),
+	 * returns that manager's directory so reads/writes land in the shared parent
+	 * dir instead of a private (non-existent) subdir.
 	 */
 	getArtifactsDir(): string | null {
+		if (this.#adoptedArtifactManager) return this.#adoptedArtifactManager.dir;
 		const sessionFile = this.#sessionFile;
 		return sessionFile ? sessionFile.slice(0, -6) : null;
 	}
 
+	/**
+	 * Adopt an externally-owned ArtifactManager. Used by subagents to share
+	 * the parent session's artifact directory and ID counter.
+	 */
+	adoptArtifactManager(manager: ArtifactManager): void {
+		this.#adoptedArtifactManager = manager;
+	}
+
+	/**
+	 * Returns the ArtifactManager this session writes through. Lazily creates
+	 * one bound to the current session file unless an external manager was
+	 * adopted via `adoptArtifactManager`. Returns null only for non-persistent
+	 * sessions with no adopted manager.
+	 */
+	getArtifactManager(): ArtifactManager | null {
+		return this.#getOrCreateArtifactManager();
+	}
+
 	/**
 	 * Returns an artifact manager bound to the current session file.
 	 * Recreates the manager when the active session file changes.
 	 */
 	#getOrCreateArtifactManager(): ArtifactManager | null {
+		if (this.#adoptedArtifactManager) return this.#adoptedArtifactManager;
 		const sessionFile = this.#sessionFile;
 		if (!sessionFile) {
 			this.#artifactManager = null;
@@ -2142,7 +2171,7 @@ export class SessionManager {
 			return this.#artifactManager;
 		}
 
-		const manager = new ArtifactManager(sessionFile);
+		const manager = new ArtifactManager(sessionFile.slice(0, -6));
 		this.#artifactManager = manager;
 		this.#artifactManagerSessionFile = sessionFile;
 		return manager;

package/src/ssh/connection-manager.ts

@@ -15,6 +15,11 @@ export interface SSHConnectionTarget {
 
 export type SSHHostOs = "windows" | "linux" | "macos" | "unknown";
 export type SSHHostShell = "cmd" | "powershell" | "bash" | "zsh" | "sh" | "unknown";
+export type SshPlatform = typeof process.platform;
+
+export function supportsSshControlMaster(platform: SshPlatform = process.platform): boolean {
+	return platform !== "win32";
+}
 
 export interface SSHHostInfo {
 	version: number;
@@ -33,6 +38,10 @@ const activeHosts = new Map<string, SSHConnectionTarget>();
 const pendingConnections = new Map<string, Promise<void>>();
 const hostInfoCache = new Map<string, SSHHostInfo>();
 
+interface SSHArgsOptions {
+	platform?: SshPlatform;
+}
+
 function ensureControlDir() {
 	fs.mkdirSync(CONTROL_DIR, { recursive: true, mode: 0o700 });
 	try {
@@ -66,20 +75,14 @@ async function validateKeyPermissions(keyPath?: string): Promise<void> {
 	}
 }
 
-function buildCommonArgs(host: SSHConnectionTarget): string[] {
-	const args = [
-		"-n",
-		"-o",
-		"ControlMaster=auto",
-		"-o",
-		`ControlPath=${CONTROL_PATH}`,
-		"-o",
-		"ControlPersist=3600",
-		"-o",
-		"BatchMode=yes",
-		"-o",
-		"StrictHostKeyChecking=accept-new",
-	];
+function buildCommonArgs(host: SSHConnectionTarget, options?: SSHArgsOptions): string[] {
+	const args = ["-n"];
+
+	if (supportsSshControlMaster(options?.platform)) {
+		args.push("-o", "ControlMaster=auto", "-o", `ControlPath=${CONTROL_PATH}`, "-o", "ControlPersist=3600");
+	}
+
+	args.push("-o", "BatchMode=yes", "-o", "StrictHostKeyChecking=accept-new");
 
 	if (host.port) {
 		args.push("-p", String(host.port));
@@ -357,9 +360,13 @@ export async function ensureHostInfo(host: SSHConnectionTarget): Promise<SSHHost
 	return probeHostInfo(host);
 }
 
-export async function buildRemoteCommand(host: SSHConnectionTarget, command: string): Promise<string[]> {
+export async function buildRemoteCommand(
+	host: SSHConnectionTarget,
+	command: string,
+	options?: SSHArgsOptions,
+): Promise<string[]> {
 	await validateKeyPermissions(host.keyPath);
-	return [...buildCommonArgs(host), buildSshTarget(host.username, host.host), command];
+	return [...buildCommonArgs(host, options), buildSshTarget(host.username, host.host), command];
 }
 
 let registered = false;
@@ -385,6 +392,14 @@ export async function ensureConnection(host: SSHConnectionTarget): Promise<void>
 		}
 
 		const target = buildSshTarget(host.username, host.host);
+		if (!supportsSshControlMaster()) {
+			activeHosts.set(key, host);
+			if (!hostInfoCache.has(key) && !(await loadHostInfoFromDisk(host))) {
+				await probeHostInfo(host);
+			}
+			return;
+		}
+
 		const check = await runSshSync(["-O", "check", ...buildCommonArgs(host), target]);
 		if (check.exitCode === 0) {
 			activeHosts.set(key, host);
@@ -415,6 +430,7 @@ export async function ensureConnection(host: SSHConnectionTarget): Promise<void>
 }
 
 async function closeConnectionInternal(host: SSHConnectionTarget): Promise<void> {
+	if (!supportsSshControlMaster()) return;
 	const target = buildSshTarget(host.username, host.host);
 	await runSshSync(["-O", "exit", ...buildCommonArgs(host), target]);
 }