pi-subagents 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-02-13
+
+### Fixed
+- JSONL artifact files no longer written by default — they duplicated pi's own session files and were the sole cause of `subagent-artifacts` directories growing to 10+ GB. Changed `includeJsonl` default from `true` to `false`. `_output.md` and `_meta.json` still capture the useful data.
+- Artifact cleanup now covers session-based directories, not just the temp dir. Previously `cleanupOldArtifacts` only ran on `os.tmpdir()/pi-subagent-artifacts` at startup, while sync runs (the common path) wrote to `<session-dir>/subagent-artifacts/` which was never cleaned. Now scans all `~/.pi/agent/sessions/*/subagent-artifacts/` dirs on startup and cleans the current session's artifacts dir on session lifecycle events.
+- JSONL writer now enforces a 50 MB size cap (`maxBytes` on `JsonlWriterDeps`) as defense-in-depth for users who opt into JSONL. Silently stops writing at the cap without pausing the source stream, so the progress tracker keeps working.
+
+## [0.8.3] - 2026-02-11
+
+### Added
+- Agent `extensions` frontmatter support for extension sandboxing: absent field keeps default extension discovery, empty value disables all extensions, and comma-separated values create an explicit extension allowlist.
+
+### Fixed
+- Parallel chain aggregation now surfaces step failures and warnings in `{previous}` instead of silently passing empty output.
+- Empty-output warnings are now context-aware: runs that intentionally write to explicit output paths are not flagged as warning-only successes in the renderer.
+- Async execution now respects agent `extensions` sandbox settings, matching sync behavior.
+- Single-mode `output` now resolves explicit paths correctly: absolute paths are used directly, and relative paths resolve against `cwd`.
+- Single-mode output persistence is now caller-side in both sync and async execution, so output files are still written when agents run with read-only tools.
+- Pi process spawning now uses a shared cross-platform helper in sync and async paths; on Windows it prefers direct Node + CLI invocation to avoid `ENOENT` and argument fragmentation.
+- Sync JSONL artifact capture now streams lines directly to disk with backpressure handling, preventing unbounded memory growth in long or parallel runs.
+- Execution now defaults `agentScope` to `both`, aligning run behavior with management `list` so project agents shown in discovery execute without explicit scope overrides.
+- Async completion notifications now dedupe at source and notify layers, eliminating duplicate/triple "Background task completed" messages.
+- Async notifications now standardize on canonical `subagent:started` and `subagent:complete` events (legacy enhanced event emissions removed).
+
+### Changed
+- Reworked `skills.ts` to resolve skills through Pi core skill loading with explicit project-first precedence and support for project/user package and settings skill paths.
+- Skill discovery now normalizes and prioritizes collisions by source so project-scoped skills consistently win over user-scoped skills.
+- Documentation now references `<tmpdir>` instead of hardcoded `/tmp` paths for cross-platform clarity.
+
 ## [0.8.2] - 2026-02-11
 
 ### Added
@@ -10,7 +39,7 @@
 ## [0.8.1] - 2026-02-10
 
 ### Added
-- **`chainDir` param** for persistent chain artifacts — specify a directory to keep artifacts beyond the default 24-hour `/tmp/` cleanup. Relative paths are resolved to absolute via `path.resolve()` for safe use in `{chain_dir}` template substitutions.
+- **`chainDir` param** for persistent chain artifacts — specify a directory to keep artifacts beyond the default 24-hour temp-directory cleanup. Relative paths are resolved to absolute via `path.resolve()` for safe use in `{chain_dir}` template substitutions.
 
 ## [0.8.0] - 2026-02-09
 

package/README.md

@@ -31,7 +31,7 @@ Agents are markdown files with YAML frontmatter that define specialized subagent
 | User | `~/.pi/agent/agents/{name}.md` |
 | Project | `.pi/agents/{name}.md` (searches up directory tree) |
 
-Use `agentScope` parameter to control discovery: `"user"` (default), `"project"`, or `"both"` (project takes priority).
+Use `agentScope` parameter to control discovery: `"user"`, `"project"`, or `"both"` (default; project takes priority).
 
 **Agent frontmatter:**
 
@@ -40,6 +40,7 @@ Use `agentScope` parameter to control discovery: `"user"` (default), `"project"`
 name: scout
 description: Fast codebase recon
 tools: read, grep, find, ls, bash, mcp:chrome-devtools  # mcp: requires pi-mcp-adapter
+extensions:                 # absent=all, empty=none, csv=allowlist
 model: claude-haiku-4-5
 thinking: high               # off, minimal, low, medium, high, xhigh
 skill: safe-bash, chrome-devtools  # comma-separated skills to inject
@@ -54,6 +55,27 @@ Your system prompt goes here (the markdown body after frontmatter).
 
 The `thinking` field sets a default extended thinking level for the agent. At runtime it's appended as a `:level` suffix to the model string (e.g., `claude-sonnet-4-5:high`). If the model already has a thinking suffix (from a chain-clarify override), the agent's default is not double-applied.
 
+**Extension sandboxing**
+
+Use `extensions` in frontmatter to control which extensions a subagent can access:
+
+```yaml
+# Field absent: all extensions load (default behavior)
+
+# Empty field: no extensions
+extensions:
+
+# Allowlist specific extensions
+extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts
+```
+
+Semantics:
+- `extensions` absent → all extensions load
+- `extensions:` empty → `--no-extensions`
+- `extensions: a,b` → `--no-extensions --extension a --extension b`
+
+When `extensions` is present, it takes precedence over extension paths implied by `tools` entries.
+
 **MCP Tools**
 
 Agents can use MCP server tools directly (requires the [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) extension). Add `mcp:` prefixed entries to the `tools` field:
@@ -127,7 +149,7 @@ Append `[key=value,...]` to any agent name to override its defaults:
 
 | Key | Example | Description |
 |-----|---------|-------------|
-| `output` | `output=context.md` | Write results to file (relative to chain dir for `/chain`/`/parallel`, temp dir for `/run`) |
+| `output` | `output=context.md` | Write results to file (relative to chain dir for `/chain`/`/parallel`; for `/run`, absolute paths are used as-is and relative paths resolve against cwd) |
 | `reads` | `reads=a.md+b.md` | Read files before executing (`+` separates multiple) |
 | `model` | `model=anthropic/claude-sonnet-4` | Override model for this step |
 | `skills` | `skills=planning+review` | Override skills (`+` separates multiple) |
@@ -228,7 +250,7 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 - **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
 - **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`)
-- **Chain Artifacts**: Shared directory at `/tmp/pi-chain-runs/{runId}/` for inter-step files
+- **Chain Artifacts**: Shared directory at `<tmpdir>/pi-chain-runs/{runId}/` for inter-step files
 - **Solo Agent Output**: Agents with `output` write to temp dir and return path to caller
 - **Live Progress Display**: Real-time visibility during sync execution showing current tool, recent output, tokens, and duration
 - **Output Truncation**: Configurable byte/line limits via `maxOutput`
@@ -310,9 +332,13 @@ Single and parallel modes also support the clarify TUI for previewing/editing pa
 
 Skills are specialized instructions loaded from SKILL.md files and injected into the agent's system prompt.
 
-**Skill locations:**
-- Project: `.pi/skills/{name}/SKILL.md` (higher priority)
+**Skill locations (project-first precedence):**
+- Project: `.pi/skills/{name}/SKILL.md`
+- Project packages: `.pi/npm/node_modules/*` via `package.json -> pi.skills`
+- Project settings: `.pi/settings.json -> skills`
 - User: `~/.pi/agent/skills/{name}/SKILL.md`
+- User packages: `~/.pi/agent/npm/node_modules/*` via `package.json -> pi.skills`
+- User settings: `~/.pi/agent/settings.json -> skills`
 
 **Usage:**
 ```typescript
@@ -397,7 +423,7 @@ Skills are specialized instructions loaded from SKILL.md files and injected into
 **subagent_status tool:**
 ```typescript
 { id: "a53ebe46" }
-{ dir: "/tmp/pi-async-subagent-runs/a53ebe46-..." }
+{ dir: "<tmpdir>/pi-async-subagent-runs/a53ebe46-..." }
 ```
 
 ## Management Actions
@@ -421,6 +447,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
   systemPrompt: "You are a code scout...",
   model: "anthropic/claude-sonnet-4",
   tools: "read, bash, mcp:github/search_repositories",
+  extensions: "", // empty = no extensions
   skills: "parallel-scout",
   thinking: "high",
   output: "context.md",
@@ -457,7 +484,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
 Notes:
 - `create` uses `config.scope` (`"user"` or `"project"`), not `agentScope`.
 - `update`/`delete` use `agentScope` only for scope disambiguation when the same name exists in both scopes.
-- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, and `tools` supports `mcp:` entries that map to direct MCP tools.
+- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, and `tools` supports `mcp:` entries that map to direct MCP tools.
 - To clear any optional field, set it to `false` or `""` (e.g., `{ model: false }` or `{ skills: "" }`). Both work for all string-typed fields.
 
 ## Parameters
@@ -469,14 +496,14 @@ Notes:
 | `action` | string | - | Management action: `list`, `get`, `create`, `update`, `delete` |
 | `chainName` | string | - | Chain name for management get/update/delete |
 | `config` | object | - | Agent or chain config for management create/update |
-| `output` | `string \| false` | agent default | Override output file for single agent |
+| `output` | `string \| false` | agent default | Override output file for single agent (absolute path as-is, relative path resolved against cwd) |
 | `skill` | `string \| string[] \| false` | agent default | Override skills (comma-separated string, array, or false to disable) |
 | `model` | string | agent default | Override model for single agent |
 | `tasks` | `{agent, task, cwd?, skill?}[]` | - | Parallel tasks (sync only) |
 | `chain` | ChainItem[] | - | Sequential steps with behavior overrides (see below) |
-| `chainDir` | string | `/tmp/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
+| `chainDir` | string | `<tmpdir>/pi-chain-runs/` | Persistent directory for chain artifacts (default auto-cleaned after 24h) |
 | `clarify` | boolean | true (chains) | Show TUI to preview/edit chain; implies sync mode |
-| `agentScope` | `"user" \| "project" \| "both"` | `user` | Agent discovery scope |
+| `agentScope` | `"user" \| "project" \| "both"` | `both` | Agent discovery scope (project wins on name collisions) |
 | `async` | boolean | false | Background execution (requires `clarify: false` for chains) |
 | `cwd` | string | - | Override working directory |
 | `maxOutput` | `{bytes?, lines?}` | 200KB, 5000 lines | Truncation limits for final output |
@@ -551,7 +578,7 @@ This aggregated output becomes `{previous}` for the next step.
 
 ## Chain Directory
 
-Each chain run creates `/tmp/pi-chain-runs/{runId}/` containing:
+Each chain run creates `<tmpdir>/pi-chain-runs/{runId}/` containing:
 - `context.md` - Scout/context-builder output
 - `plan.md` - Planner output  
 - `progress.md` - Worker/reviewer shared progress
@@ -564,7 +591,7 @@ Directories older than 24 hours are cleaned up on extension startup.
 
 ## Artifacts
 
-Location: `{sessionDir}/subagent-artifacts/` or `/tmp/pi-subagent-artifacts/`
+Location: `{sessionDir}/subagent-artifacts/` or `<tmpdir>/pi-subagent-artifacts/`
 
 Files per task:
 - `{runId}_{agent}_input.md` - Task prompt
@@ -574,7 +601,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 `/tmp`.
+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>`.
 
 ## Live progress (sync mode)
 
@@ -616,7 +643,7 @@ export PI_SUBAGENT_MAX_DEPTH=0   # disable the subagent tool entirely
 Async runs write a dedicated observability folder:
 
 ```
-/tmp/pi-async-subagent-runs/<id>/
+<tmpdir>/pi-async-subagent-runs/<id>/
   status.json
   events.jsonl
   subagent-log-<id>.md
@@ -627,7 +654,7 @@ Async runs write a dedicated observability folder:
 
 ```typescript
 subagent_status({ id: "<id>" })
-subagent_status({ dir: "/tmp/pi-async-subagent-runs/<id>" })
+subagent_status({ dir: "<tmpdir>/pi-async-subagent-runs/<id>" })
 ```
 
 ## Events
@@ -636,9 +663,7 @@ Async events:
 - `subagent:started`
 - `subagent:complete`
 
-Legacy events (still emitted):
-- `subagent_enhanced:started`
-- `subagent_enhanced:complete`
+`notify.ts` consumes `subagent:complete` as the canonical completion channel.
 
 ## Files
 

package/agent-management.ts

@@ -203,6 +203,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.skills === "string") { const skills = parseCsv(cfg.skills); target.skills = skills.length ? skills : undefined; }
 		else return "config.skills must be a comma-separated string or false when provided.";
 	}
+	if (hasKey(cfg, "extensions")) {
+		if (cfg.extensions === false) target.extensions = undefined;
+		else if (cfg.extensions === "") target.extensions = [];
+		else if (typeof cfg.extensions === "string") target.extensions = parseCsv(cfg.extensions);
+		else return "config.extensions must be a comma-separated string, empty string, or false when provided.";
+	}
 	if (hasKey(cfg, "thinking")) {
 		if (cfg.thinking === false || cfg.thinking === "") target.thinking = undefined;
 		else if (typeof cfg.thinking === "string") target.thinking = cfg.thinking.trim() || undefined;
@@ -273,6 +279,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.model) lines.push(`Model: ${agent.model}`);
 	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
 	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
+	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);

package/agent-manager-detail.ts

@@ -64,6 +64,10 @@ function buildDetailLines(
 	lines.push(renderFieldLine("Tools:", tools, contentWidth, theme));
 	lines.push(renderFieldLine("MCP:", mcp, contentWidth, theme));
 	lines.push(renderFieldLine("Skills:", skillsList, contentWidth, theme));
+	const extensionsList = agent.extensions !== undefined
+		? (agent.extensions.length > 0 ? agent.extensions.join(", ") : "(none)")
+		: "(all)";
+	lines.push(renderFieldLine("Extensions:", extensionsList, contentWidth, theme));
 	lines.push(renderFieldLine("Output:", output, contentWidth, theme));
 	lines.push(renderFieldLine("Reads:", reads, contentWidth, theme));
 	lines.push(renderFieldLine("Progress:", progress, contentWidth, theme));

package/agent-manager-edit.ts

@@ -16,7 +16,7 @@ export interface EditState {
 export interface EditInputResult { action?: "save" | "discard"; nextScreen?: EditScreen; }
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
-const FIELD_ORDER = ["name", "description", "model", "thinking", "tools", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
+const FIELD_ORDER = ["name", "description", "model", "thinking", "tools", "extensions", "skills", "output", "reads", "progress", "interactive", "prompt"] as const;
 type EditField = typeof FIELD_ORDER[number];
 type ThinkingLevel = typeof THINKING_LEVELS[number];
 const PROMPT_VIEWPORT_HEIGHT = 16;
@@ -29,7 +29,7 @@ function parseCommaList(value: string): string[] | undefined { const items = val
 
 export function createEditState(draft: AgentConfig, isNew: boolean, models: ModelInfo[], skills: SkillInfo[]): EditState {
 	return {
-		draft: { ...draft, tools: draft.tools ? [...draft.tools] : undefined, mcpDirectTools: draft.mcpDirectTools ? [...draft.mcpDirectTools] : undefined, skills: draft.skills ? [...draft.skills] : undefined, defaultReads: draft.defaultReads ? [...draft.defaultReads] : undefined, extraFields: draft.extraFields ? { ...draft.extraFields } : undefined },
+		draft: { ...draft, tools: draft.tools ? [...draft.tools] : undefined, mcpDirectTools: draft.mcpDirectTools ? [...draft.mcpDirectTools] : undefined, skills: draft.skills ? [...draft.skills] : undefined, extensions: draft.extensions ? [...draft.extensions] : draft.extensions, defaultReads: draft.defaultReads ? [...draft.defaultReads] : undefined, extraFields: draft.extraFields ? { ...draft.extraFields } : undefined },
 		isNew, fieldIndex: 0, fieldMode: null, fieldEditor: createEditorState(), promptEditor: createEditorState(draft.systemPrompt ?? ""),
 		modelSearchQuery: "", modelCursor: 0, filteredModels: [...models], thinkingCursor: 0, skillSearchQuery: "", skillCursor: 0, filteredSkills: [...skills], skillSelected: new Set(draft.skills ?? []),
 	};
@@ -43,6 +43,7 @@ function renderFieldValue(field: EditField, state: EditState): string {
 		case "model": return draft.model ?? "default";
 		case "thinking": return draft.thinking ?? "off";
 		case "tools": return formatTools(draft);
+		case "extensions": return draft.extensions !== undefined ? (draft.extensions.length > 0 ? draft.extensions.join(", ") : "") : "(all)";
 		case "skills": return draft.skills && draft.skills.length > 0 ? draft.skills.join(", ") : "";
 		case "output": return draft.output ?? "";
 		case "reads": return draft.defaultReads && draft.defaultReads.length > 0 ? draft.defaultReads.join(", ") : "";
@@ -59,6 +60,7 @@ function applyFieldValue(field: EditField, state: EditState, value: string): voi
 		case "description": draft.description = value.trim(); break;
 		case "model": draft.model = value.trim() || undefined; break;
 		case "tools": { const parsed = parseTools(value); draft.tools = parsed.tools; draft.mcpDirectTools = parsed.mcp; break; }
+		case "extensions": { const trimmed = value.trim(); draft.extensions = trimmed === "(all)" ? undefined : parseCommaList(trimmed) ?? []; break; }
 		case "skills": draft.skills = parseCommaList(value); break;
 		case "output": { const trimmed = value.trim(); draft.output = trimmed.length > 0 ? trimmed : undefined; break; }
 		case "reads": draft.defaultReads = parseCommaList(value); break;

package/agent-scope.ts

@@ -0,0 +1,6 @@
+import type { AgentScope } from "./agents.js";
+
+export function resolveExecutionAgentScope(scope: unknown): AgentScope {
+	if (scope === "user" || scope === "project" || scope === "both") return scope;
+	return "both";
+}

package/agent-selection.ts

@@ -0,0 +1,20 @@
+import type { AgentScope, AgentConfig } from "./agents.js";
+
+export function mergeAgentsForScope(
+	scope: AgentScope,
+	userAgents: AgentConfig[],
+	projectAgents: AgentConfig[],
+): AgentConfig[] {
+	const agentMap = new Map<string, AgentConfig>();
+
+	if (scope === "both") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	} else if (scope === "user") {
+		for (const agent of userAgents) agentMap.set(agent.name, agent);
+	} else {
+		for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	}
+
+	return Array.from(agentMap.values());
+}

package/agent-serializer.ts

@@ -9,6 +9,7 @@ export const KNOWN_FIELDS = new Set([
 	"thinking",
 	"skill",
 	"skills",
+	"extensions",
 	"output",
 	"defaultReads",
 	"defaultProgress",
@@ -39,6 +40,11 @@ export function serializeAgent(config: AgentConfig): string {
 	const skillsValue = joinComma(config.skills);
 	if (skillsValue) lines.push(`skills: ${skillsValue}`);
 
+	if (config.extensions !== undefined) {
+		const extensionsValue = joinComma(config.extensions);
+		lines.push(`extensions: ${extensionsValue ?? ""}`);
+	}
+
 	if (config.output) lines.push(`output: ${config.output}`);
 
 	const readsValue = joinComma(config.defaultReads);

package/agents.ts

@@ -7,6 +7,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { KNOWN_FIELDS } from "./agent-serializer.js";
 import { parseChain } from "./chain-serializer.js";
+import { mergeAgentsForScope } from "./agent-selection.js";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -21,6 +22,7 @@ export interface AgentConfig {
 	source: "user" | "project";
 	filePath: string;
 	skills?: string[];
+	extensions?: string[];
 	// Chain behavior fields
 	output?: string;
 	defaultReads?: string[];
@@ -145,6 +147,14 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			.map((s) => s.trim())
 			.filter(Boolean);
 
+		let extensions: string[] | undefined;
+		if (frontmatter.extensions !== undefined) {
+			extensions = frontmatter.extensions
+				.split(",")
+				.map((e) => e.trim())
+				.filter(Boolean);
+		}
+
 		const extraFields: Record<string, string> = {};
 		for (const [key, value] of Object.entries(frontmatter)) {
 			if (!KNOWN_FIELDS.has(key)) extraFields[key] = value;
@@ -161,6 +171,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			source,
 			filePath,
 			skills: skills && skills.length > 0 ? skills : undefined,
+			extensions,
 			// Chain behavior fields
 			output: frontmatter.output,
 			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
@@ -235,19 +246,9 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 
 	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+	const agents = mergeAgentsForScope(scope, userAgents, projectAgents);
 
-	const agentMap = new Map<string, AgentConfig>();
-
-	if (scope === "both") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
-	} else if (scope === "user") {
-		for (const agent of userAgents) agentMap.set(agent.name, agent);
-	} else {
-		for (const agent of projectAgents) agentMap.set(agent.name, agent);
-	}
-
-	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+	return { agents, projectAgentsDir };
 }
 
 export function discoverAgentsAll(cwd: string): {

package/artifacts.ts

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import type { ArtifactPaths } from "./types.js";
 
-const TEMP_ARTIFACTS_DIR = "/tmp/pi-subagent-artifacts";
+const TEMP_ARTIFACTS_DIR = path.join(os.tmpdir(), "pi-subagent-artifacts");
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 
 export function getArtifactsDir(sessionFile: string | null): string {
@@ -68,3 +69,24 @@ export function cleanupOldArtifacts(dir: string, maxAgeDays: number): void {
 
 	fs.writeFileSync(markerPath, String(now));
 }
+
+export function cleanupAllArtifactDirs(maxAgeDays: number): void {
+	cleanupOldArtifacts(TEMP_ARTIFACTS_DIR, maxAgeDays);
+
+	const sessionsBase = path.join(os.homedir(), ".pi", "agent", "sessions");
+	if (!fs.existsSync(sessionsBase)) return;
+
+	let dirs: string[];
+	try {
+		dirs = fs.readdirSync(sessionsBase);
+	} catch {
+		return;
+	}
+
+	for (const dir of dirs) {
+		const artifactsDir = path.join(sessionsBase, dir, "subagent-artifacts");
+		try {
+			cleanupOldArtifacts(artifactsDir, maxAgeDays);
+		} catch {}
+	}
+}

package/async-execution.ts

@@ -11,6 +11,7 @@ import { createRequire } from "node:module";
 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 { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
 import {
@@ -61,6 +62,7 @@ export interface AsyncSingleParams {
 	shareEnabled: boolean;
 	sessionRoot?: string;
 	skills?: string[];
+	output?: string | false;
 }
 
 export interface AsyncExecutionResult {
@@ -153,6 +155,7 @@ export function executeAsyncChain(
 			cwd: s.cwd,
 			model: applyThinkingSuffix(s.model ?? a.model, a.thinking),
 			tools: a.tools,
+			extensions: a.extensions,
 			mcpDirectTools: a.mcpDirectTools,
 			systemPrompt,
 			skills: resolvedSkills.map((r) => r.name),
@@ -181,15 +184,6 @@ export function executeAsyncChain(
 
 	if (pid) {
 		const firstAgent = chain[0] as SequentialStep;
-		ctx.pi.events.emit("subagent_enhanced:started", {
-			id,
-			pid,
-			agent: firstAgent.agent,
-			task: firstAgent.task?.slice(0, 50),
-			chain: chain.map((s) => (s as SequentialStep).agent),
-			cwd: runnerCwd,
-			asyncDir,
-		});
 		ctx.pi.events.emit("subagent:started", {
 			id,
 			pid,
@@ -231,19 +225,23 @@ export function executeAsyncSingle(
 	} catch {}
 
 	const runnerCwd = cwd ?? ctx.cwd;
+	const outputPath = resolveSingleOutputPath(params.output, ctx.cwd, cwd);
+	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
 	const pid = spawnRunner(
 		{
 			id,
 			steps: [
 				{
 					agent,
-					task,
+					task: taskWithOutputInstruction,
 					cwd,
 					model: applyThinkingSuffix(agentConfig.model, agentConfig.thinking),
 					tools: agentConfig.tools,
+					extensions: agentConfig.extensions,
 					mcpDirectTools: agentConfig.mcpDirectTools,
 					systemPrompt,
 					skills: resolvedSkills.map((r) => r.name),
+					outputPath,
 				},
 			],
 			resultPath: path.join(RESULTS_DIR, `${id}.json`),
@@ -262,14 +260,6 @@ export function executeAsyncSingle(
 	);
 
 	if (pid) {
-		ctx.pi.events.emit("subagent_enhanced:started", {
-			id,
-			pid,
-			agent,
-			task: task?.slice(0, 50),
-			cwd: runnerCwd,
-			asyncDir,
-		});
 		ctx.pi.events.emit("subagent:started", {
 			id,
 			pid,

package/chain-execution.ts

@@ -376,13 +376,21 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			}
 
 			// Aggregate outputs for {previous}
-			const taskResults: ParallelTaskResult[] = parallelResults.map((r, i) => ({
-				agent: r.agent,
-				taskIndex: i,
-				output: getFinalOutput(r.messages),
-				exitCode: r.exitCode,
-				error: r.error,
-			}));
+			const taskResults: ParallelTaskResult[] = parallelResults.map((r, i) => {
+				const outputTarget = parallelBehaviors[i]?.output;
+				const outputTargetPath = typeof outputTarget === "string"
+					? (path.isAbsolute(outputTarget) ? outputTarget : path.join(chainDir, outputTarget))
+					: undefined;
+				return {
+					agent: r.agent,
+					taskIndex: i,
+					output: getFinalOutput(r.messages),
+					exitCode: r.exitCode,
+					error: r.error,
+					outputTargetPath,
+					outputTargetExists: outputTargetPath ? fs.existsSync(outputTargetPath) : undefined,
+				};
+			});
 			prev = aggregateParallelOutputs(taskResults);
 		} else {
 			// === SEQUENTIAL STEP EXECUTION ===

package/completion-dedupe.ts

@@ -0,0 +1,63 @@
+interface CompletionDataLike {
+	id?: unknown;
+	agent?: unknown;
+	timestamp?: unknown;
+	sessionId?: unknown;
+	taskIndex?: unknown;
+	totalTasks?: unknown;
+	success?: unknown;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function asFiniteNumber(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	return Number.isFinite(value) ? value : undefined;
+}
+
+export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
+	const id = asNonEmptyString(data.id);
+	if (id) return `id:${id}`;
+	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
+	const agent = asNonEmptyString(data.agent) ?? "unknown";
+	const timestamp = asFiniteNumber(data.timestamp);
+	const taskIndex = asFiniteNumber(data.taskIndex);
+	const totalTasks = asFiniteNumber(data.totalTasks);
+	const success = typeof data.success === "boolean" ? (data.success ? "1" : "0") : "?";
+	return [
+		"meta",
+		sessionId,
+		agent,
+		timestamp !== undefined ? String(timestamp) : "no-ts",
+		taskIndex !== undefined ? String(taskIndex) : "-",
+		totalTasks !== undefined ? String(totalTasks) : "-",
+		success,
+		fallback,
+	].join(":");
+}
+
+export function pruneSeenMap(seen: Map<string, number>, now: number, ttlMs: number): void {
+	for (const [key, ts] of seen.entries()) {
+		if (now - ts > ttlMs) seen.delete(key);
+	}
+}
+
+export function markSeenWithTtl(seen: Map<string, number>, key: string, now: number, ttlMs: number): boolean {
+	pruneSeenMap(seen, now, ttlMs);
+	if (seen.has(key)) return true;
+	seen.set(key, now);
+	return false;
+}
+
+export function getGlobalSeenMap(storeKey: string): Map<string, number> {
+	const globalStore = globalThis as Record<string, unknown>;
+	const existing = globalStore[storeKey];
+	if (existing instanceof Map) return existing as Map<string, number>;
+	const map = new Map<string, number>();
+	globalStore[storeKey] = map;
+	return map;
+}