pi-subagents 0.9.2 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-02-23
+
+### Added
+- **Background mode toggle in clarify TUI**: Press `b` to toggle background/async execution for any mode (single, parallel, chain). Shows `[b]g:ON` in footer when enabled. Previously async execution required programmatic `clarify: false, async: true` — now users can interactively choose background mode after previewing/editing parameters.
+- **`--bg` flag for slash commands**: `/run scout "task" --bg`, `/chain scout "task" -> planner --bg`, `/parallel scout "a" -> scout "b" --bg` now run in background without needing the TUI.
+
+### Fixed
+- Task edits in clarify TUI were lost when launching in background mode if no other behavior (model, output, reads) was modified. The async handoff now always applies the edited template.
+
+## [0.10.0] - 2026-02-23
+
+### Added
+- **Async parallel chain support**: Chains with `{ parallel: [...] }` steps now work in async mode. Previously they were rejected with "Async mode doesn't support chains with parallel steps." The async runner now spawns concurrent pi processes for parallel step groups with configurable `concurrency` and `failFast` options. Inspired by PR #31 from @marcfargas.
+- **Comprehensive test suite**: 85 integration tests and 12 E2E tests covering all execution modes (single, parallel, chain, async), error handling, template resolution, and tool validation. Uses `@marcfargas/pi-test-harness` for subprocess mocking and in-process session testing. Thanks @marcfargas for PR #32.
+- GitHub Actions CI workflow running tests on both Ubuntu and Windows with Node.js 24.
+
+### Changed
+- **BREAKING:** `share` parameter now defaults to `false`. Previously, sessions were silently uploaded to GitHub Gists without user consent. Users who want session sharing must now explicitly pass `share: true`. Added documentation explaining what the feature does and its privacy implications.
+
+### Fixed
+- `mapConcurrent` with `limit=0` returned array of undefined values instead of processing items sequentially. Now clamps limit to at least 1.
+- ANSI background color bleed in truncated text. The `truncLine` function now properly tracks and re-applies all active ANSI styles (bold, colors, etc.) before the ellipsis, preventing style leakage. Also uses `Intl.Segmenter` for correct Unicode/emoji handling. Thanks @monotykamary for identifying the issue.
+- `detectSubagentError` no longer produces false positives when the agent recovers from tool errors. Previously, any error in the last tool result would override exitCode 0→1, even if the agent had already produced complete output. Now only errors AFTER the agent's final text response are flagged. Thanks @marcfargas for the fix and comprehensive test coverage.
+- Parallel mode (`tasks: [...]`) now returns aggregated output from all tasks instead of just a success count. Previously only returned "3/3 succeeded" with actual task outputs lost.
+- Session sharing fallback no longer fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. The fallback now resolves the main entry point and walks up to find the package root instead of trying to resolve `package.json` directly.
+- Skills from globally-installed npm packages (via `pi install npm:...`) are now discoverable by subagents. Previously only scanned local `.pi/npm/node_modules/` paths, missing the global npm root where pi actually installs packages.
+- **Windows compatibility**: Fixed `ENAMETOOLONG` errors when tasks exceed command-line length limits by writing long tasks to temp files using pi's `@file` syntax. Thanks @marcfargas.
+- **Windows compatibility**: Suppressed flashing console windows when spawning async runner processes (`windowsHide: true`).
+- **Windows compatibility**: Fixed pi CLI resolution in async runner by passing `piPackageRoot` through to `getPiSpawnCommand`.
+- **Cross-platform paths**: Replaced `startsWith("/")` checks with `path.isAbsolute()` for correct Windows absolute path detection. Replaced template string path concatenation with `path.join()` for consistent path separators.
+- **Resilience**: Added error handling and auto-restart for the results directory watcher. Previously, if the directory was deleted or became inaccessible, the watcher would die silently.
+- **Resilience**: Added `ensureAccessibleDir` helper that verifies directory accessibility after creation and attempts recovery if the directory has broken ACLs (can happen on Windows with Azure AD/Entra ID after wake-from-sleep).
+
 ## [0.9.2] - 2026-02-19
 
 ### Fixed

package/README.md

@@ -162,6 +162,18 @@ Append `[key=value,...]` to any agent name to override its defaults:
 
 Set `output=false`, `reads=false`, or `skills=false` to explicitly disable.
 
+### Background Execution
+
+Add `--bg` at the end of any slash command to run in the background:
+
+```
+/run scout "full security audit of the codebase" --bg
+/chain scout "analyze auth system" -> planner "design refactor plan" -> worker --bg
+/parallel scout "scan frontend" -> scout "scan backend" -> scout "scan infra" --bg
+```
+
+Background tasks run asynchronously and notify you when complete. Check status with `subagent_status`.
+
 ## Agents Manager
 
 Press **Ctrl+Shift+A** or type `/agents` to open the Agents Manager overlay — a TUI for browsing, viewing, editing, creating, and launching agents and chains.
@@ -270,10 +282,10 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 | Mode | Async Support | Notes |
 |------|---------------|-------|
 | Single | Yes | `{ agent, task }` - agents with `output` write to temp dir |
-| Chain | Yes* | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
-| Parallel | Sync only | `{ tasks: [{agent, task}...] }` - auto-downgrades if async requested |
+| Chain | Yes | `{ chain: [{agent, task}...] }` with `{task}`, `{previous}`, `{chain_dir}` variables |
+| Parallel | Yes | `{ tasks: [{agent, task}...] }` - via TUI toggle or converted to chain for async |
 
-*Chain defaults to sync with TUI clarification. Use `clarify: false` to enable async (sequential-only chains; parallel-in-chain requires sync mode).
+All modes support background/async execution. For programmatic async, use `clarify: false, async: true`. For interactive async, use `clarify: true` and press `b` in the TUI to toggle background mode before running. Chains with parallel steps (`{ parallel: [...] }`) run concurrently with configurable `concurrency` and `failFast` options.
 
 **Clarify TUI for single/parallel:**
 
@@ -290,13 +302,14 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 **Clarification TUI keybindings:**
 
 *Navigation mode:*
-- `Enter` - Run
+- `Enter` - Run (foreground) or launch in background if `b` is toggled on
 - `Esc` - Cancel
 - `↑↓` - Navigate between steps/tasks (parallel, chain)
 - `e` - Edit task/template (all modes)
 - `m` - Select model (all modes)
 - `t` - Select thinking level (all modes)
 - `s` - Select skills (all modes)
+- `b` - Toggle background/async execution (all modes) — shows `[b]g:ON` when enabled
 - `w` - Edit writes/output file (single, chain only)
 - `r` - Edit reads list (chain only)
 - `p` - Toggle progress tracking (chain only)
@@ -423,6 +436,16 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
     { agent: "worker", task: "Refactor module C" }
   ], concurrency: 2, failFast: true }  // limit concurrency, stop on first failure
 ]}
+
+// Async chain with parallel step (runs in background)
+{ chain: [
+  { agent: "scout", task: "Gather context" },
+  { parallel: [
+    { agent: "worker", task: "Implement feature A based on {previous}" },
+    { agent: "worker", task: "Implement feature B based on {previous}" }
+  ]},
+  { agent: "reviewer", task: "Review all changes from {previous}" }
+], clarify: false, async: true }
 ```
 
 **subagent_status tool:**
@@ -514,7 +537,7 @@ Notes:
 | `maxOutput` | `{bytes?, lines?}` | 200KB, 5000 lines | Truncation limits for final output |
 | `artifacts` | boolean | true | Write debug artifacts |
 | `includeProgress` | boolean | false | Include full progress in result |
-| `share` | boolean | true | Create shareable session log |
+| `share` | boolean | false | Upload session to GitHub Gist (see [Session Sharing](#session-sharing)) |
 | `sessionDir` | string | temp | Directory to store session logs |
 
 **ChainItem** can be either a sequential step or a parallel step:
@@ -608,6 +631,25 @@ Files per task:
 
 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 Sharing
+
+When `share: true` is passed, the extension will:
+
+1. Export the full session (all tool calls, file contents, outputs) to an HTML file
+2. Upload it to a GitHub Gist using your `gh` CLI credentials
+3. Return a shareable URL (`https://shittycodingagent.ai/session/?<gistId>`)
+
+**This is disabled by default.** Session data may contain sensitive information like source code, file paths, environment variables, or credentials that appear in tool outputs.
+
+To enable sharing for a specific run:
+```typescript
+{ agent: "scout", task: "...", share: true }
+```
+
+Requirements:
+- GitHub CLI (`gh`) must be installed and authenticated (`gh auth login`)
+- Gists are created as "secret" (unlisted but accessible to anyone with the URL)
+
 ## Live progress (sync mode)
 
 During sync execution, the collapsed view shows real-time progress for single, chain, and parallel modes.
@@ -686,10 +728,16 @@ Async events:
 ├── artifacts.ts                  # Artifact management
 ├── formatters.ts                 # Output formatting utilities
 ├── schemas.ts                    # TypeBox parameter schemas
-├── utils.ts                      # Shared utility functions
+├── utils.ts                      # Shared utility functions (mapConcurrent, readStatus, etc.)
 ├── types.ts                      # Shared types and constants
 ├── subagent-runner.ts            # Async runner (detached process)
+├── parallel-utils.ts             # Parallel execution utilities for async runner
+├── pi-spawn.ts                   # Cross-platform pi CLI spawning
+├── single-output.ts              # Solo agent output file handling
 ├── notify.ts                     # Async completion notifications
+├── completion-dedupe.ts          # Completion deduplication for notifications
+├── file-coalescer.ts             # Debounced file write coalescing
+├── jsonl-writer.ts               # JSONL event stream writer
 ├── agent-manager.ts              # Overlay orchestrator, screen routing, CRUD
 ├── agent-manager-list.ts         # List screen (search, multi-select, progressive footer)
 ├── agent-manager-detail.ts       # Detail screen (resolved prompt, runs, fields)
@@ -698,6 +746,8 @@ Async events:
 ├── agent-manager-chain-detail.ts # Chain detail screen (flow visualization)
 ├── agent-management.ts           # Management action handlers (list, get, create, update, delete)
 ├── agent-serializer.ts           # Serialize agents to markdown frontmatter
+├── agent-scope.ts                # Agent scope resolution utilities
+├── agent-selection.ts            # Agent selection state management
 ├── agent-templates.ts            # Agent/chain creation templates
 ├── render-helpers.ts             # Shared pad/row/header/footer helpers
 ├── run-history.ts                # Per-agent run recording (JSONL)

package/async-execution.ts

@@ -12,7 +12,8 @@ import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agents.js";
 import { applyThinkingSuffix } from "./execution.js";
 import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import { isParallelStep, resolveStepBehavior, type ChainStep, type ParallelStep, type SequentialStep, type StepOverrides } from "./settings.js";
+import type { RunnerStep } from "./parallel-utils.js";
 import { resolvePiPackageRoot } from "./pi-spawn.js";
 import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
 import {
@@ -105,6 +106,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string): number | undefin
 		cwd,
 		detached: true,
 		stdio: "ignore",
+		windowsHide: true,
 	});
 	proc.unref();
 	return proc.pid;
@@ -119,28 +121,20 @@ export function executeAsyncChain(
 ): AsyncExecutionResult {
 	const { chain, agents, ctx, cwd, maxOutput, artifactsDir, artifactConfig, shareEnabled, sessionRoot } = params;
 	const chainSkills = params.chainSkills ?? [];
-	
-	// Async mode doesn't support parallel steps (v1 limitation)
-	const hasParallelInChain = chain.some(isParallelStep);
-	if (hasParallelInChain) {
-		return {
-			content: [{ type: "text", text: "Async mode doesn't support chains with parallel steps. Use clarify: true (sync mode) for parallel-in-chain." }],
-			isError: true,
-			details: { mode: "chain" as const, results: [] },
-		};
-	}
-
-	// At this point, all steps are sequential
-	const seqSteps = chain as SequentialStep[];
 
 	// Validate all agents exist before building steps
-	for (const s of seqSteps) {
-		if (!agents.find((x) => x.name === s.agent)) {
-			return {
-				content: [{ type: "text", text: `Unknown agent: ${s.agent}` }],
-				isError: true,
-				details: { mode: "chain" as const, results: [] },
-			};
+	for (const s of chain) {
+		const stepAgents = isParallelStep(s)
+			? s.parallel.map((t) => t.agent)
+			: [(s as SequentialStep).agent];
+		for (const agentName of stepAgents) {
+			if (!agents.find((x) => x.name === agentName)) {
+				return {
+					content: [{ type: "text", text: `Unknown agent: ${agentName}` }],
+					isError: true,
+					details: { mode: "chain" as const, results: [] },
+				};
+			}
 		}
 	}
 
@@ -149,7 +143,8 @@ export function executeAsyncChain(
 		fs.mkdirSync(asyncDir, { recursive: true });
 	} catch {}
 
-	const steps = seqSteps.map((s) => {
+	/** Build a resolved runner step from a SequentialStep */
+	const buildSeqStep = (s: SequentialStep) => {
 		const a = agents.find((x) => x.name === s.agent)!;
 		const stepSkillInput = normalizeSkillInput(s.skill);
 		const stepOverrides: StepOverrides = { skills: stepSkillInput };
@@ -162,9 +157,15 @@ export function executeAsyncChain(
 			const injection = buildSkillInjection(resolvedSkills);
 			systemPrompt = systemPrompt ? `${systemPrompt}\n\n${injection}` : injection;
 		}
+
+		// Resolve output path and inject instruction into task
+		// Use step's cwd if specified, otherwise fall back to chain-level cwd
+		const outputPath = resolveSingleOutputPath(s.output, ctx.cwd, s.cwd ?? cwd);
+		const task = injectSingleOutputInstruction(s.task ?? "{previous}", outputPath);
+
 		return {
 			agent: s.agent,
-			task: s.task ?? "{previous}",
+			task,
 			cwd: s.cwd,
 			model: applyThinkingSuffix(s.model ?? a.model, a.thinking),
 			tools: a.tools,
@@ -172,7 +173,28 @@ export function executeAsyncChain(
 			mcpDirectTools: a.mcpDirectTools,
 			systemPrompt,
 			skills: resolvedSkills.map((r) => r.name),
+			outputPath,
 		};
+	};
+
+	// Build runner steps — sequential steps become flat objects,
+	// parallel steps become { parallel: [...], concurrency?, failFast? }
+	const steps: RunnerStep[] = chain.map((s) => {
+		if (isParallelStep(s)) {
+			return {
+				parallel: s.parallel.map((t) => buildSeqStep({
+					agent: t.agent,
+					task: t.task,
+					cwd: t.cwd,
+					skill: t.skill,
+					model: t.model,
+					output: t.output,
+				})),
+				concurrency: s.concurrency,
+				failFast: s.failFast,
+			};
+		}
+		return buildSeqStep(s as SequentialStep);
 	});
 
 	const runnerCwd = cwd ?? ctx.cwd;
@@ -197,22 +219,34 @@ export function executeAsyncChain(
 	);
 
 	if (pid) {
-		const firstAgent = chain[0] as SequentialStep;
+		const firstStep = chain[0];
+		const firstAgents = isParallelStep(firstStep)
+			? firstStep.parallel.map((t) => t.agent)
+			: [(firstStep as SequentialStep).agent];
 		ctx.pi.events.emit("subagent:started", {
 			id,
 			pid,
-			agent: firstAgent.agent,
-			task: firstAgent.task?.slice(0, 50),
-			chain: chain.map((s) => (s as SequentialStep).agent),
+			agent: firstAgents[0],
+			task: isParallelStep(firstStep)
+				? firstStep.parallel[0]?.task?.slice(0, 50)
+				: (firstStep as SequentialStep).task?.slice(0, 50),
+			chain: chain.map((s) =>
+				isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+			),
 			cwd: runnerCwd,
 			asyncDir,
 		});
 	}
 
+	// Build chain description with parallel groups shown as [agent1+agent2]
+	const chainDesc = chain
+		.map((s) =>
+			isParallelStep(s) ? `[${s.parallel.map((t) => t.agent).join("+")}]` : (s as SequentialStep).agent,
+		)
+		.join(" -> ");
+
 	return {
-		content: [
-			{ type: "text", text: `Async chain: ${chain.map((s) => (s as SequentialStep).agent).join(" -> ")} [${id}]` },
-		],
+		content: [{ type: "text", text: `Async chain: ${chainDesc} [${id}]` }],
 		details: { mode: "chain", results: [], asyncId: id, asyncDir },
 	};
 }

package/chain-clarify.ts

@@ -42,6 +42,8 @@ export interface ChainClarifyResult {
 	templates: string[];
 	/** User-modified behavior overrides per step (undefined = no changes) */
 	behaviorOverrides: (BehaviorOverride | undefined)[];
+	/** User requested background/async execution */
+	runInBackground?: boolean;
 }
 
 type EditMode = "template" | "output" | "reads" | "model" | "thinking" | "skills";
@@ -88,6 +90,8 @@ export class ChainClarifyComponent implements Component {
 	private saveMessageTimer: ReturnType<typeof setTimeout> | null = null;
 	private saveChainNameState: TextEditorState = createEditorState();
 	private savingChain = false;
+	/** Run in background (async) mode */
+	private runInBackground = false;
 
 	constructor(
 		private tui: TUI,
@@ -463,7 +467,7 @@ export class ChainClarifyComponent implements Component {
 			for (let i = 0; i < this.agentConfigs.length; i++) {
 				overrides.push(this.behaviorOverrides.get(i));
 			}
-			this.done({ confirmed: true, templates: this.templates, behaviorOverrides: overrides });
+			this.done({ confirmed: true, templates: this.templates, behaviorOverrides: overrides, runInBackground: this.runInBackground });
 			return;
 		}
 
@@ -539,6 +543,13 @@ export class ChainClarifyComponent implements Component {
 			return;
 		}
 
+		// 'b' to toggle background/async execution (all modes)
+		if (data === "b") {
+			this.runInBackground = !this.runInBackground;
+			this.tui.requestRender();
+			return;
+		}
+
 		if (data === "S") {
 			this.saveOverridesToAgent();
 			return;
@@ -1179,13 +1190,14 @@ export class ChainClarifyComponent implements Component {
 
 	/** Get footer text based on mode */
 	private getFooterText(): string {
+		const bgLabel = this.runInBackground ? '[b]g:ON' : '[b]g';
 		switch (this.mode) {
 			case 'single':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [w]rite [s]kill [S]ave ';
+				return ` [Enter] Run • [Esc] Cancel • e m t w s ${bgLabel} S `;
 			case 'parallel':
-				return ' [Enter] Run • [Esc] Cancel • [e]dit [m]odel [t]hink [s]kill [S]ave • ↑↓ Nav ';
+				return ` [Enter] Run • [Esc] Cancel • e m t s ${bgLabel} S • ↑↓ Nav `;
 			case 'chain':
-				return ' [Enter] Run • [Esc] Cancel • e m t w r p s S W • ↑↓ Nav ';
+				return ` [Enter] Run • [Esc] Cancel • e m t w r p s ${bgLabel} S W • ↑↓ Nav `;
 		}
 	}
 

package/chain-execution.ts

@@ -83,6 +83,11 @@ export interface ChainExecutionResult {
 	content: Array<{ type: "text"; text: string }>;
 	details: Details;
 	isError?: boolean;
+	/** User requested async execution via TUI - caller should dispatch to executeAsyncChain */
+	requestedAsync?: {
+		chain: ChainStep[];
+		chainSkills: string[];
+	};
 }
 
 /**
@@ -210,6 +215,31 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				details: { mode: "chain", results: [] },
 			};
 		}
+
+		// User requested background execution - return early so caller can dispatch to async
+		if (result.runInBackground) {
+			removeChainDir(chainDir); // Will be recreated by async runner
+			// Apply TUI edits (templates + behavior overrides) to chain steps
+			const updatedChain = chainSteps.map((step, i) => {
+				if (isParallelStep(step)) return step; // Parallel steps unchanged (TUI skipped for parallel chains)
+				const override = result.behaviorOverrides[i];
+				return {
+					...step,
+					task: result.templates[i] as string, // Always use edited template
+					...(override?.model ? { model: override.model } : {}),
+					...(override?.output !== undefined ? { output: override.output } : {}),
+					...(override?.reads !== undefined ? { reads: override.reads } : {}),
+					...(override?.progress !== undefined ? { progress: override.progress } : {}),
+					...(override?.skills !== undefined ? { skill: override.skills } : {}),
+				};
+			});
+			return {
+				content: [{ type: "text", text: "Launching in background..." }],
+				details: { mode: "chain", results: [] },
+				requestedAsync: { chain: updatedChain as ChainStep[], chainSkills },
+			};
+		}
+
 		// Update templates from TUI result
 		templates = result.templates;
 		// Store behavior overrides from TUI (used below in sequential step execution)
@@ -493,7 +523,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			// Validate expected output file was created
 			if (behavior.output && r.exitCode === 0) {
 				try {
-					const expectedPath = behavior.output.startsWith("/") 
+					const expectedPath = path.isAbsolute(behavior.output)
 						? behavior.output 
 						: path.join(chainDir, behavior.output);
 					if (!fs.existsSync(expectedPath)) {

package/execution.ts

@@ -4,6 +4,8 @@
 
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { Message } from "@mariozechner/pi-ai";
 import type { AgentConfig } from "./agents.js";
 import {
@@ -123,7 +125,20 @@ export async function runSync(
 		tmpDir = tmp.dir;
 		args.push("--append-system-prompt", tmp.path);
 	}
-	args.push(`Task: ${task}`);
+
+	// When the task is too long for a CLI argument (Windows ENAMETOOLONG),
+	// write it to a temp file and use pi's @file syntax instead.
+	const TASK_ARG_LIMIT = 8000;
+	if (task.length > TASK_ARG_LIMIT) {
+		if (!tmpDir) {
+			tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-"));
+		}
+		const taskFilePath = path.join(tmpDir, "task.md");
+		fs.writeFileSync(taskFilePath, `Task: ${task}`, { mode: 0o600 });
+		args.push(`@${taskFilePath}`);
+	} else {
+		args.push(`Task: ${task}`);
+	}
 
 	const result: SingleResult = {
 		agent: agentName,