pi-subagents 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [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

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

@@ -83,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
@@ -298,12 +302,17 @@ MANAGEMENT (use action field — omit agent/task/chain/tasks):
 			const agents = discoverAgents(ctx.cwd, scope).agents;
 			const runId = randomUUID().slice(0, 8);
 			const shareEnabled = params.share === true;
-			// Session root: explicit param > derived from parent session > temp fallback
-			// Sessions are always enabled now - stored alongside parent session for tracking
+			// 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(params.sessionDir)
-				: path.join(getSubagentSessionRoot(parentSessionFile), runId);
+				? path.resolve(expandTilde(params.sessionDir))
+				: path.join(
+					config.defaultSessionDir
+						? path.resolve(expandTilde(config.defaultSessionDir))
+						: getSubagentSessionRoot(parentSessionFile),
+					runId,
+				);
 			try {
 				fs.mkdirSync(sessionRoot, { recursive: true });
 			} catch {}
@@ -320,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
 			);
@@ -539,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)
 				);
 
@@ -553,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.11.1",
+  "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;
 }