pi-subagents 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-03-11
+
+### Fixed
+- `--no-skills` was missing from the async runner (`subagent-runner.ts`). PR #41 added skill scoping to the sync path but the async runner spawns pi through its own code path, so background subagents with explicit skills still got the full `<available_skills>` catalog injected.
+- `defaultSessionDir` and `sessionDir` with `~` paths (e.g. `"~/.pi/agent/sessions/subagent/"`) were not expanded — `path.resolve("~/...")` treats `~` as a literal directory name. Added tilde expansion matching the existing pattern in `skills.ts`.
+- Multiple subagent calls within a session would collide when `defaultSessionDir` was configured, since it wasn't appending a unique `runId`. Both `defaultSessionDir` and parent-session-derived paths now get `runId` appended.
+
+### Removed
+- Removed exported `resolveSessionRoot()` function and `SessionRootInput` interface. These were introduced by PR #46 but never called in production — the inline resolution logic diverged (always-on sessions, `runId` appended) making the function's contract misleading. Associated tests and dead code from PR #47 scaffolding also removed from `path-handling.test.ts`.
+
+## [0.11.1] - 2026-03-08
+
+### Changed
+- **Session persistence**: Subagent sessions are now stored alongside the parent session file instead of in `/tmp`. If the parent session is `~/.pi/agent/sessions/abc123.jsonl`, subagent sessions go to `~/.pi/agent/sessions/abc123/{runId}/run-{N}/`. This enables tracking subagent performance over time, analyzing token usage patterns, and debugging past delegations. Falls back to a unique temp directory when no parent session exists (API/headless mode).
+
 ## [0.11.0] - 2026-02-23
 
 ### Added

package/README.md

@@ -538,7 +538,7 @@ Notes:
 | `artifacts` | boolean | true | Write debug artifacts |
 | `includeProgress` | boolean | false | Include full progress in result |
 | `share` | boolean | false | Upload session to GitHub Gist (see [Session Sharing](#session-sharing)) |
-| `sessionDir` | string | temp | Directory to store session logs |
+| `sessionDir` | string | - | Override session log directory (takes precedence over `defaultSessionDir` and parent-session-derived path) |
 
 **ChainItem** can be either a sequential step or a parallel step:
 
@@ -604,11 +604,31 @@ Templates support three variables:
 
 This aggregated output becomes `{previous}` for the next step.
 
-## Chain Directory
+## Extension Configuration
+
+`pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`.
+
+### `defaultSessionDir`
 
+`defaultSessionDir` sets the fallback directory used for session logs. Eg:
+
+```json
+{
+  "defaultSessionDir": "~/.pi/agent/sessions/subagent/"
+}
+```
+
+Session root resolution follows this precedence:
+1. `params.sessionDir` from the `subagent` tool call
+2. `config.defaultSessionDir`
+3. Derived from parent session (stored alongside parent session file)
+
+Sessions are always enabled — every subagent run gets a session directory for tracking.
+
+## Chain Directory
 Each chain run creates `<tmpdir>/pi-chain-runs/{runId}/` containing:
 - `context.md` - Scout/context-builder output
-- `plan.md` - Planner output  
+- `plan.md` - Planner output
 - `progress.md` - Worker/reviewer shared progress
 - `parallel-{stepIndex}/` - Subdirectories for parallel step outputs
   - `0-{agent}/output.md` - First parallel task output
@@ -629,7 +649,7 @@ Files per task:
 
 ## Session Logs
 
-Session files (JSONL) are stored under a per-run session dir (temp by default). The session file path is shown in output. Set `sessionDir` to keep session logs outside `<tmpdir>`.
+Session files (JSONL) are stored under a per-run session directory. Directory selection follows the same precedence as session root resolution: explicit `sessionDir` > `config.defaultSessionDir` > parent-session-derived path. The session file path is shown in output.
 
 ## Session Sharing
 

package/execution.ts

@@ -113,6 +113,13 @@ export async function runSync(
 	const skillNames = options.skills ?? agent.skills ?? [];
 	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkills(skillNames, runtimeCwd);
 
+	// When explicit skills are specified (via options or agent config), disable
+	// pi's own skill discovery so the spawned process doesn't inject the full
+	// <available_skills> catalog.  This mirrors how extensions are scoped above.
+	if (skillNames.length > 0) {
+		args.push("--no-skills");
+	}
+
 	let systemPrompt = agent.systemPrompt?.trim() || "";
 	if (resolvedSkills.length > 0) {
 		const skillInjection = buildSkillInjection(resolvedSkills);

package/index.ts

@@ -57,6 +57,22 @@ import { handleManagementAction } from "./agent-management.js";
 
 // ExtensionConfig is now imported from ./types.js
 
+/**
+ * Derive subagent session base directory from parent session file.
+ * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
+ * returns ~/.pi/agent/sessions/abc123/ as the base.
+ * Callers add runId to create the actual session root: abc123/{runId}/
+ * Falls back to a unique temp directory if no parent session.
+ */
+function getSubagentSessionRoot(parentSessionFile: string | null): string {
+	if (parentSessionFile) {
+		const baseName = path.basename(parentSessionFile, ".jsonl");
+		const sessionsDir = path.dirname(parentSessionFile);
+		return path.join(sessionsDir, baseName);
+	}
+	return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+
 function loadConfig(): ExtensionConfig {
 	const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");
 	try {
@@ -67,6 +83,10 @@ function loadConfig(): ExtensionConfig {
 	return {};
 }
 
+function expandTilde(p: string): string {
+	return p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
 /**
  * Create a directory and verify it is actually accessible.
  * On Windows with Azure AD/Entra ID, directories created shortly after
@@ -277,23 +297,27 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			}
 
 			const scope: AgentScope = resolveExecutionAgentScope(params.agentScope);
-			currentSessionId = ctx.sessionManager.getSessionFile() ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+			const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+			currentSessionId = parentSessionFile ?? `session-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 			const agents = discoverAgents(ctx.cwd, scope).agents;
 			const runId = randomUUID().slice(0, 8);
 			const shareEnabled = params.share === true;
-			const sessionEnabled = shareEnabled || Boolean(params.sessionDir);
-			const sessionRoot = sessionEnabled
-				? params.sessionDir
-					? path.resolve(params.sessionDir)
-					: fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"))
-				: undefined;
-			if (sessionRoot) {
-				try {
-					fs.mkdirSync(sessionRoot, { recursive: true });
-				} catch {}
-			}
+			// Session root precedence: explicit param > config default > parent session derived
+			// Sessions are always enabled - stored alongside parent session for tracking
+			// Include runId to ensure uniqueness across multiple subagent calls
+			const sessionRoot = params.sessionDir
+				? path.resolve(expandTilde(params.sessionDir))
+				: path.join(
+					config.defaultSessionDir
+						? path.resolve(expandTilde(config.defaultSessionDir))
+						: getSubagentSessionRoot(parentSessionFile),
+					runId,
+				);
+			try {
+				fs.mkdirSync(sessionRoot, { recursive: true });
+			} catch {}
 			const sessionDirForIndex = (idx?: number) =>
-				sessionRoot ? path.join(sessionRoot, `run-${idx ?? 0}`) : undefined;
+				path.join(sessionRoot, `run-${idx ?? 0}`);
 
 			const hasChain = (params.chain?.length ?? 0) > 0;
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
@@ -305,7 +329,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			// - Chains default to TUI (clarify: true), so async requires explicit clarify: false
 			// - Single defaults to no TUI, so async is allowed unless clarify: true is passed
 			const effectiveAsync = requestedAsync && !hasTasks && (
-				hasChain 
+				hasChain
 					? params.clarify === false    // chains: only async if TUI explicitly disabled
 					: params.clarify !== true     // single: async unless TUI explicitly enabled
 			);
@@ -315,8 +339,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				enabled: params.artifacts !== false,
 			};
 
-			const sessionFile = ctx.sessionManager.getSessionFile() ?? null;
-			const artifactsDir = effectiveAsync ? tempArtifactsDir : getArtifactsDir(sessionFile);
+			const artifactsDir = effectiveAsync ? tempArtifactsDir : getArtifactsDir(parentSessionFile);
 
 			if (Number(hasChain) + Number(hasTasks) + Number(hasSingle) !== 1) {
 				return {
@@ -525,7 +548,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 				let tasks = params.tasks.map(t => t.task);
 				const modelOverrides: (string | undefined)[] = params.tasks.map(t => (t as { model?: string }).model);
 				// Initialize skill overrides from task-level skill params (may be overridden by TUI)
-				const skillOverrides: (string[] | false | undefined)[] = params.tasks.map(t => 
+				const skillOverrides: (string[] | false | undefined)[] = params.tasks.map(t =>
 					normalizeSkillInput((t as { skill?: string | string[] | boolean }).skill)
 				);
 
@@ -539,7 +562,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 					}));
 
 					// Resolve behaviors with task-level skill overrides for TUI display
-					const behaviors = agentConfigs.map((c, i) => 
+					const behaviors = agentConfigs.map((c, i) =>
 						resolveStepBehavior(c, { skills: skillOverrides[i] })
 					);
 					const availableSkills = discoverAvailableSkills(ctx.cwd);
@@ -1019,12 +1042,16 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 
 	const setupDirectRun = (ctx: ExtensionContext) => {
 		const runId = randomUUID().slice(0, 8);
-		const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+		const parentSessionFile = ctx.sessionManager.getSessionFile() ?? null;
+		const sessionRoot = path.join(getSubagentSessionRoot(parentSessionFile), runId);
+		try {
+			fs.mkdirSync(sessionRoot, { recursive: true });
+		} catch {}
 		return {
 			runId,
 			shareEnabled: false,
 			sessionDirForIndex: (idx?: number) => path.join(sessionRoot, `run-${idx ?? 0}`),
-			artifactsDir: getArtifactsDir(ctx.sessionManager.getSessionFile() ?? null),
+			artifactsDir: getArtifactsDir(parentSessionFile),
 			artifactConfig: { ...DEFAULT_ARTIFACT_CONFIG } as ArtifactConfig,
 		};
 	};
@@ -1085,7 +1112,8 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 						}
 						const id = randomUUID();
 						const asyncCtx = { pi, cwd: ctx.cwd, currentSessionId: ctx.sessionManager.getSessionId() ?? id };
-						const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+						const asyncSessionRoot = getSubagentSessionRoot(ctx.sessionManager.getSessionFile() ?? null);
+						try { fs.mkdirSync(asyncSessionRoot, { recursive: true }); } catch {}
 						executeAsyncChain(id, {
 							chain: r.requestedAsync.chain,
 							agents,
@@ -1094,7 +1122,7 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 							artifactsDir: exec.artifactsDir,
 							artifactConfig: exec.artifactConfig,
 							shareEnabled: false,
-							sessionRoot,
+							sessionRoot: asyncSessionRoot,
 							chainSkills: r.requestedAsync.chainSkills,
 						}).then((asyncResult) => {
 							pi.sendUserMessage(asyncResult.content[0]?.text || "(launched in background)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",

package/parallel-utils.ts

@@ -44,18 +44,24 @@ export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
 	return flat;
 }
 
-/** Run async tasks with bounded concurrency, preserving result order */
+/** Run async tasks with bounded concurrency, preserving result order.
+ *  `staggerMs` adds a small delay between each worker's start to avoid
+ *  file-lock contention when multiple subagents read shared config. */
 export async function mapConcurrent<T, R>(
 	items: T[],
 	limit: number,
 	fn: (item: T, i: number) => Promise<R>,
+	staggerMs = 150,
 ): Promise<R[]> {
 	// Clamp to at least 1; NaN/undefined/0/negative all become 1
 	const safeLimit = Math.max(1, Math.floor(limit) || 1);
 	const results: R[] = new Array(items.length);
 	let next = 0;
 
-	async function worker(): Promise<void> {
+	async function worker(workerIndex: number): Promise<void> {
+		if (staggerMs > 0 && workerIndex > 0) {
+			await new Promise((r) => setTimeout(r, workerIndex * staggerMs));
+		}
 		while (next < items.length) {
 			const i = next++;
 			results[i] = await fn(items[i], i);
@@ -63,7 +69,7 @@ export async function mapConcurrent<T, R>(
 	}
 
 	await Promise.all(
-		Array.from({ length: Math.min(safeLimit, items.length) }, () => worker()),
+		Array.from({ length: Math.min(safeLimit, items.length) }, (_, wi) => worker(wi)),
 	);
 	return results;
 }

package/skills.ts

@@ -347,6 +347,21 @@ export function normalizeSkillInput(
 	if (Array.isArray(input)) {
 		return [...new Set(input.map((s) => s.trim()).filter((s) => s.length > 0))];
 	}
+	// Guard against JSON-encoded arrays arriving as strings (e.g. '["a","b"]').
+	// Models sometimes serialise the skill parameter as a JSON string instead of
+	// a native array, and naively splitting on "," would embed brackets/quotes
+	// into the skill names, causing resolution to silently fail.
+	const trimmed = input.trim();
+	if (trimmed.startsWith("[")) {
+		try {
+			const parsed = JSON.parse(trimmed);
+			if (Array.isArray(parsed)) {
+				return normalizeSkillInput(parsed);
+			}
+		} catch {
+			// Not valid JSON – fall through to comma-split
+		}
+	}
 	return [...new Set(input.split(",").map((s) => s.trim()).filter((s) => s.length > 0))];
 }
 

package/subagent-runner.ts

@@ -304,6 +304,10 @@ async function runSingleStep(
 		for (const extPath of toolExtensionPaths) args.push("--extension", extPath);
 	}
 
+	if (step.skills?.length) {
+		args.push("--no-skills");
+	}
+
 	let tmpDir: string | null = null;
 	if (step.systemPrompt) {
 		tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));

package/types.ts

@@ -217,6 +217,7 @@ export interface RunSyncOptions {
 
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
+	defaultSessionDir?: string;
 }
 
 // ============================================================================

package/utils.ts

@@ -332,20 +332,24 @@ export async function mapConcurrent<T, R>(
 	items: T[],
 	limit: number,
 	fn: (item: T, i: number) => Promise<R>,
+	staggerMs = 150,
 ): Promise<R[]> {
 	// Clamp to at least 1; NaN/undefined/0/negative all become 1
 	const safeLimit = Math.max(1, Math.floor(limit) || 1);
 	const results: R[] = new Array(items.length);
 	let next = 0;
 
-	async function worker(): Promise<void> {
+	async function worker(workerIndex: number): Promise<void> {
+		if (staggerMs > 0 && workerIndex > 0) {
+			await new Promise((r) => setTimeout(r, workerIndex * staggerMs));
+		}
 		while (next < items.length) {
 			const i = next++;
 			results[i] = await fn(items[i], i);
 		}
 	}
 
-	const workers = Array.from({ length: Math.min(safeLimit, items.length) }, () => worker());
+	const workers = Array.from({ length: Math.min(safeLimit, items.length) }, (_, wi) => worker(wi));
 	await Promise.all(workers);
 	return results;
 }