pi-cohort 7.4.5 → 7.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [7.6.0] - 2026-10-26
+
+### Breaking
+- All extension settings now come only from `settings.json#subagents`: the profile is below project levels, and the nearest defined value wins. Move the legacy configuration object's keys under `subagents` in the profile's `settings.json` or project `.pi/settings.json`; the old file is ignored and triggers one top-level session-start migration warning. Hooks and backend selection follow each execution unit's effective cwd, including detached runs. (#29)
+
+## [7.5.0] - 2026-10-26
+
+### Added
+- `worktreeTeardownHook` and `worktreeTeardownHookTimeoutMs` let consumers clean up external resources before task checkout removal, including setup rollback; failures produce best-effort warnings without changing task results. (#27)
+
+### Fixed
+- The Tests workflow passes on Windows again: the fanout extension-inheritance integration test hands its preload to `--import` as a `file://` URL instead of a bare drive-letter path.
+
 ## [7.4.5] - 2026-10-23
 
 ### Fixed

package/README.md

@@ -186,7 +186,7 @@ Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-a
 
 ## Configuration
 
-Most installs need zero configuration. Full env/JSON reference: [doc/configuration.md](doc/configuration.md).
+Most installs need zero configuration. Set options under `subagents` in the profile's `settings.json` or project `.pi/settings.json`; project levels override the profile, nearest wins. See the [settings reference and migration guide](doc/configuration.md) for defaults, whole-object replacement, and moving legacy configuration.
 
 Run history lives under the pinned profile's `pi-cohort/` root and has no automatic age expiry. Status listings can grow without bound as history accumulates. To remove history manually, delete only a terminal top-level run directory after confirming its entire subtree has stopped; never delete queued or running state, individual nested records, or shared route files. This removes that directory's status and resume lookup, not separately stored session files or shared routes. Keep those sessions if you need their context; deleting a run directory is not a complete session purge. Storage details: [doc/observability.md](doc/observability.md#files-logs-and-observability).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.4.5",
+  "version": "7.6.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/agents/agents.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AcceptanceInput, OutputMode, StopCondition } from "../shared/types.ts";
+import type { AcceptanceInput, ExtensionConfig, OutputMode, StopCondition } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
@@ -114,12 +114,29 @@ export interface AgentConfig {
 	override?: BuiltinAgentOverrideInfo;
 }
 
-interface SubagentSettings {
+interface SubagentSettings extends ExtensionConfig {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	disableBuiltins?: boolean;
 	executionBackend?: string;
 }
 
+const EXTENSION_SETTING_TYPES = {
+	asyncByDefault: "boolean",
+	forceTopLevelAsync: "boolean",
+	defaultSessionDir: "string",
+	maxSubagentDepth: "depth",
+	control: "object",
+	parallel: "object",
+	chain: "object",
+	worktreeSetupHook: "string",
+	worktreeSetupHookTimeoutMs: "timeout",
+	worktreeTeardownHook: "string",
+	worktreeTeardownHookTimeoutMs: "timeout",
+	showRosterOnStart: "boolean",
+	forwardParentFlags: "boolean",
+	executionBackend: "backend",
+} as const;
+
 const EMPTY_SUBAGENT_SETTINGS: SubagentSettings = { overrides: {} };
 
 export interface ChainStepConfig {
@@ -475,16 +492,28 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 		executionBackend = trimmed;
 	}
 
+	const extension: Record<string, unknown> = {};
+	for (const [key, type] of Object.entries(EXTENSION_SETTING_TYPES)) {
+		if (type === "backend" || !(key in subagentsObject)) continue;
+		const value = subagentsObject[key];
+		const valid = type === "timeout"
+			|| (type === "depth" ? typeof value === "number" && Number.isInteger(value) && value >= 0
+				: type === "object" ? value !== null && typeof value === "object" && !Array.isArray(value)
+					: typeof value === type);
+		if (valid) extension[key] = value;
+		else console.warn(`Subagent settings in '${filePath}' have invalid '${key}'; expected ${type}.`);
+	}
+
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
 	const agentOverrides = subagentsObject.agentOverrides;
 	if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-		return { overrides: parsed, disableBuiltins, executionBackend };
+		return { ...extension, overrides: parsed, disableBuiltins, executionBackend };
 	}
 	for (const [name, value] of Object.entries(agentOverrides)) {
 		const override = parseBuiltinOverrideEntry(name, value, filePath);
 		if (override) parsed[name] = override;
 	}
-	return { overrides: parsed, disableBuiltins, executionBackend };
+	return { ...extension, overrides: parsed, disableBuiltins, executionBackend };
 }
 
 // Merge project .pi/settings.json across every enumerated level, farthest-first
@@ -498,7 +527,7 @@ function readMergedProjectSubagentSettings(cwd: string): SubagentSettings {
 
 	const overrides: Record<string, BuiltinAgentOverrideConfig> = {};
 	let disableBuiltins: boolean | undefined;
-	let executionBackend: string | undefined;
+	const extension: ExtensionConfig = {};
 	for (const level of levels) {
 		const settingsPath = path.join(level, ".pi", "settings.json");
 		let levelSettings: SubagentSettings;
@@ -519,16 +548,25 @@ function readMergedProjectSubagentSettings(cwd: string): SubagentSettings {
 		if (levelSettings.disableBuiltins !== undefined) {
 			disableBuiltins = levelSettings.disableBuiltins;
 		}
-		if (levelSettings.executionBackend !== undefined) {
-			executionBackend = levelSettings.executionBackend;
-		}
+		Object.assign(extension, projectExtensionSettings(levelSettings));
 	}
-	return { overrides, disableBuiltins, executionBackend };
+	return { ...extension, overrides, disableBuiltins };
 }
 
-export function readProjectExecutionBackend(cwd: string): string | undefined {
-	const merged = readMergedProjectSubagentSettings(cwd);
-	return merged.executionBackend;
+function projectExtensionSettings(settings: SubagentSettings): ExtensionConfig {
+	return Object.fromEntries(
+		Object.keys(EXTENSION_SETTING_TYPES)
+			.filter((key) => settings[key as keyof ExtensionConfig] !== undefined)
+			.map((key) => [key, settings[key as keyof ExtensionConfig]]),
+	);
+}
+
+export function resolveExtensionConfig(cwd: string): ExtensionConfig {
+	const profile = readSubagentSettings(getUserAgentSettingsPath());
+	return {
+		...projectExtensionSettings(profile),
+		...projectExtensionSettings(readMergedProjectSubagentSettings(cwd)),
+	};
 }
 
 function composeOverrideTools(

package/src/execution-backend/configured-selection.ts

@@ -1,5 +1,4 @@
 import { selectExecutionBackend } from "./selection.ts";
-import { readProjectExecutionBackend } from "../agents/agents.ts";
 import type { ExtensionConfig } from "../shared/types.ts";
 import type { ExecutionBackendPreparation, ExecutionBackendSelectionResult } from "./selection.ts";
 
@@ -13,7 +12,6 @@ export interface ConfiguredSelectionInput {
 export async function selectConfiguredExecutionBackend(
 	input: ConfiguredSelectionInput,
 ): Promise<ExecutionBackendSelectionResult> {
-	const projectPreference = readProjectExecutionBackend(input.cwd);
-	const preference = projectPreference ?? input.userConfig.executionBackend ?? "auto";
+	const preference = input.userConfig.executionBackend ?? "auto";
 	return selectExecutionBackend(preference, input.preparation);
 }

package/src/extension/fanout-child.ts

@@ -2,14 +2,12 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { discoverAgents } from "../agents/agents.ts";
+import { resolveExtensionConfig, discoverAgents } from "../agents/agents.ts";
 import { getArtifactsDir } from "../shared/artifacts.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
 import { SubagentParams } from "./schemas.ts";
-import { loadConfig } from "./config.ts";
-import { deriveForwardedFlags } from "../runs/shared/forward-flags.ts";
 import { RUN_STATE_ROOT_DIR, type Details, type SubagentState } from "../shared/types.ts";
 import { emptyGrandTotal } from "./grand-total.ts";
 
@@ -126,18 +124,15 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 	if (registeredApis.has(pi)) return;
 	registeredApis.add(pi);
 
-	const config = loadConfig();
 	const state = createChildSafeState();
 	const executor = createSubagentExecutor({
 		pi,
 		state,
-		config,
-		asyncByDefault: config.asyncByDefault === true,
+		resolveConfig: resolveExtensionConfig,
 		tempArtifactsDir: getArtifactsDir(null),
 		getSubagentSessionRoot,
 		expandTilde,
 		discoverAgents,
-		forwardedFlags: deriveForwardedFlags(process.argv, config),
 		allowMutatingManagementActions: false,
 	});
 

package/src/extension/index.ts

@@ -6,10 +6,18 @@
  * - Async: Background execution, emits events when done
  *
  * Modes: single (agent + task), parallel (tasks[]), chain (chain[] with {previous})
- * Toggle: async parameter (default: false, configurable via config.json)
+ * Toggle: async parameter (default: false, configurable via settings.json#subagents)
  *
- * Config file: ~/.pi/agent/extensions/pi-cohort/config.json
- *   { "asyncByDefault": true, "forceTopLevelAsync": true, "maxSubagentDepth": 1, "showRosterOnStart": true, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
+ * Settings: settings.json#subagents (profile or project .pi/settings.json)
+ *   { "subagents": {
+ *     "asyncByDefault": true, "forceTopLevelAsync": true,
+ *     "defaultSessionDir": "./sessions", "maxSubagentDepth": 1,
+ *     "control": {}, "parallel": { "maxTasks": 8 },
+ *     "chain": { "dynamicFanout": { "maxItems": 8 } },
+ *     "worktreeSetupHook": "./scripts/setup-worktree.mjs", "worktreeSetupHookTimeoutMs": 30000,
+ *     "worktreeTeardownHook": "./scripts/teardown-worktree.mjs", "worktreeTeardownHookTimeoutMs": 30000,
+ *     "showRosterOnStart": true, "forwardParentFlags": true, "executionBackend": "auto"
+ *   } }
  */
 
 import * as fs from "node:fs";
@@ -18,7 +26,7 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
-import { discoverAgents, discoverAgentsAll } from "../agents/agents.ts";
+import { resolveExtensionConfig, discoverAgents, discoverAgentsAll } from "../agents/agents.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
@@ -36,8 +44,7 @@ import { inspectSubagentStatus } from "../runs/background/run-status.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
 import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
-import { loadConfig } from "./config.ts";
-import { deriveForwardedFlags } from "../runs/shared/forward-flags.ts";
+import { getAgentDir } from "../shared/utils.ts";
 import {
 	type Details,
 	type SubagentState,
@@ -61,8 +68,6 @@ import {
 	type SubagentControlMessageDetails,
 } from "./control-notices.ts";
 
-export { loadConfig } from "./config.ts";
-
 /**
  * Derive subagent session base directory from parent session file.
  * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
@@ -250,8 +255,6 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	ensureAccessibleDir(ASYNC_DIR, true);
 	cleanupOldChainDirs();
 
-	const config = loadConfig();
-	const asyncByDefault = config.asyncByDefault === true;
 	const tempArtifactsDir = getArtifactsDir(null);
 	cleanupAllArtifactDirs(DEFAULT_ARTIFACT_CONFIG.cleanupDays);
 
@@ -290,13 +293,11 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const executor = createSubagentExecutor({
 		pi,
 		state,
-		config,
-		asyncByDefault,
+		resolveConfig: resolveExtensionConfig,
 		tempArtifactsDir,
 		getSubagentSessionRoot,
 		expandTilde,
 		discoverAgents,
-		forwardedFlags: deriveForwardedFlags(process.argv, config),
 	});
 
 	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
@@ -542,6 +543,13 @@ DIAGNOSTICS:
 
 	pi.on("session_start", (_event, ctx) => {
 		resetSessionState(ctx);
+		const config = resolveExtensionConfig(ctx.cwd);
+		const legacyConfigPath = path.join(getAgentDir(), "extensions", "pi-cohort", "config.json");
+		if (fs.existsSync(legacyConfigPath)) {
+			const message = `${legacyConfigPath}: pi-cohort no longer reads this file; move its keys under \`subagents\` in \`settings.json\`.`;
+			if (ctx.hasUI) ctx.ui.notify(message, "warning");
+			else console.warn(message);
+		}
 		if (ctx.hasUI && config.showRosterOnStart !== false) {
 			const roster = formatSubagentRoster(ctx.cwd);
 			// Posted to scrollback at start (alongside [Skills]/[Extensions]). Safe to

package/src/runs/background/async-execution.ts

@@ -80,6 +80,8 @@ interface AsyncChainParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	nestedRoute?: NestedRouteInfo;
 	forwardedFlags?: string[];
@@ -115,6 +117,8 @@ interface AsyncSingleParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	nestedRoute?: NestedRouteInfo;
 	forwardedFlags?: string[];
@@ -376,6 +380,8 @@ export function executeAsyncChain(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs,
 		controlConfig,
 		nestedRoute,
 		forwardedFlags,
@@ -630,6 +636,8 @@ export function executeAsyncChain(
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				resultMode,
 				executionBackends: detachedExecutionBackends(ctx.executionBackend),
@@ -748,6 +756,8 @@ export function executeAsyncSingle(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs,
 		controlConfig,
 		nestedRoute,
 		forwardedFlags,
@@ -840,6 +850,8 @@ export function executeAsyncSingle(
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				resultMode: "single",
 				executionBackends: detachedExecutionBackends(ctx.executionBackend),

package/src/runs/background/subagent-runner.ts

@@ -1,5 +1,6 @@
 import { spawn, spawnSync } from "node:child_process";
 import { PINNED_AGENT_DIR_OVERRIDE } from "../../shared/agent-dir.ts";
+import { resolveExtensionConfig } from "../../agents/agents.ts";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -120,6 +121,8 @@ interface SubagentRunConfig {
 	forwardedFlags?: string[];
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	resultMode?: SubagentRunMode;
 	dynamicFanoutMaxItems?: number;
@@ -606,6 +609,7 @@ function writeRunLog(
 
 /** Internal context for one detached-runner leaf. */
 export interface SingleStepContext {
+	jobCwd?: string;
 	previousOutput: string;
 	outputs?: ChainOutputMap;
 	trees?: TreeRegistry;
@@ -664,9 +668,13 @@ export async function runSingleStep(
 	}
 	let backendSelection: import("../../execution-backend/selection.ts").ExecutionBackendSelectionResult;
 	try {
+		const unitConfig = resolveExtensionConfig(childCwd);
+		const jobPreference = path.resolve(childCwd) === path.resolve(ctx.jobCwd ?? ctx.cwd)
+			? ctx.executionBackendConfig?.userPreference
+			: undefined;
 		backendSelection = await selectConfiguredExecutionBackend({
 			cwd: childCwd,
-			userConfig: { executionBackend: ctx.executionBackendConfig?.userPreference },
+			userConfig: { executionBackend: unitConfig.executionBackend ?? jobPreference },
 			preparation: ctx.executionBackendCoordinator,
 		});
 	} catch (error) {
@@ -1959,6 +1967,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				writeStatusPayload();
 				appendJsonl(eventsPath, JSON.stringify({ type: "subagent.step.started", ts: taskStartTime, runId: id, stepIndex: fi, agent: task.agent }));
 				const singleResult = await runSingleStep(task, {
+					jobCwd: config.cwd,
 					previousOutput, placeholder, cwd, sessionEnabled,
 					outputs,
 					trees,
@@ -2100,8 +2109,37 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 		}
 
 		if (isParallelGroup(step)) {
-			const group = step;
-			const groupCwd = group.cwd?.includes("{outputs.") ? group.cwd : resolveChildCwd(cwd, group.cwd);
+			let group = step;
+			let groupCwd = group.cwd?.includes("{outputs.") ? group.cwd : resolveChildCwd(cwd, group.cwd);
+			let groupConfig: ReturnType<typeof resolveExtensionConfig> = {};
+			if (group.worktree) {
+				try {
+					groupCwd = resolveChildCwd(cwd, resolveOutputReferences(group.cwd ?? cwd, outputs, trees));
+					group = {
+						...group,
+						parallel: group.parallel.map((task) => ({
+							...task,
+							cwd: task.cwd === undefined ? undefined : resolveChildCwd(cwd, resolveOutputReferences(task.cwd, outputs, trees)),
+						})),
+					};
+					const resolved = resolveExtensionConfig(groupCwd);
+					const fallback = path.resolve(groupCwd) === path.resolve(config.cwd) ? config : {};
+					groupConfig = {
+						worktreeSetupHook: resolved.worktreeSetupHook ?? fallback.worktreeSetupHook,
+						worktreeSetupHookTimeoutMs: resolved.worktreeSetupHookTimeoutMs === undefined ? fallback.worktreeSetupHookTimeoutMs : resolved.worktreeSetupHookTimeoutMs,
+						worktreeTeardownHook: resolved.worktreeTeardownHook ?? fallback.worktreeTeardownHook,
+						worktreeTeardownHookTimeoutMs: resolved.worktreeTeardownHookTimeoutMs === undefined ? fallback.worktreeTeardownHookTimeoutMs : resolved.worktreeTeardownHookTimeoutMs,
+					};
+				} catch (error) {
+					markParallelGroupSetupFailure({
+						statusPayload, results, group, groupStartFlatIndex: flatIndex,
+						setupError: error instanceof Error ? error.message : String(error), failedAt: Date.now(),
+						statusPath, eventsPath, asyncDir, runId: id, stepIndex,
+					});
+					flatIndex += group.parallel.length;
+					break;
+				}
+			}
 			const concurrency = group.concurrency ?? MAX_PARALLEL_CONCURRENCY;
 			const failFast = group.failFast ?? false;
 			const groupStartFlatIndex = flatIndex;
@@ -2130,8 +2168,11 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				try {
 					worktreeSetup = createWorktrees(groupCwd, `${id}-s${stepIndex}`, group.parallel.length, {
 						agents: group.parallel.map((task) => task.agent),
-						setupHook: config.worktreeSetupHook
-							? { hookPath: config.worktreeSetupHook, timeoutMs: config.worktreeSetupHookTimeoutMs }
+						setupHook: groupConfig.worktreeSetupHook
+							? { hookPath: groupConfig.worktreeSetupHook, timeoutMs: groupConfig.worktreeSetupHookTimeoutMs }
+							: undefined,
+						teardownHook: groupConfig.worktreeTeardownHook
+							? { hookPath: groupConfig.worktreeTeardownHook, timeoutMs: groupConfig.worktreeTeardownHookTimeoutMs }
 							: undefined,
 					});
 				} catch (error) {
@@ -2213,9 +2254,10 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 						const taskSessionDir = config.sessionDir
 							? path.join(config.sessionDir, `parallel-${fi}`)
 							: undefined;
-						const { taskForRun, taskCwd } = prepareParallelTaskRun(task, cwd, worktreeSetup, taskIdx, group.cwd);
+						const { taskForRun, taskCwd } = prepareParallelTaskRun(task, cwd, worktreeSetup, taskIdx, groupCwd);
 
 						const singleResult = await runSingleStep(taskForRun, {
+							jobCwd: config.cwd,
 							previousOutput, placeholder, cwd: taskCwd, sessionEnabled,
 							outputs,
 							trees,
@@ -2395,6 +2437,7 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 			}));
 
 			const singleResult = await runSingleStep(seqStep, {
+				jobCwd: config.cwd,
 				previousOutput, placeholder, cwd, sessionEnabled,
 				outputs,
 				trees,

package/src/runs/foreground/chain-execution.ts

@@ -31,6 +31,7 @@ import {
 	type ResolvedTemplates,
 } from "../../shared/settings.ts";
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
+import type { ExtensionConfig } from "../../shared/types.ts";
 import { runSync } from "./execution.ts";
 import type { PiRuntimeIdentity } from "../shared/pi-spawn.ts";
 import { buildChainSummary, buildChainOutputsSection, buildChainStopSection, type ChainSummaryOptions } from "../../shared/formatters.ts";
@@ -142,6 +143,7 @@ interface ParallelChainRunInput {
 	maxSubagentDepth: number;
 	nestedRoute?: NestedRouteInfo;
 	forwardedFlags?: string[];
+	resolveConfig?: (cwd: string) => ExtensionConfig;
 }
 
 function buildChainExecutionDetails(input: ChainExecutionDetailsInput): Details {
@@ -295,6 +297,7 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 			const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
 				runtime: input.runtime,
 				cwd: taskCwd,
+				executionBackend: input.resolveConfig?.(taskCwd).executionBackend,
 				signal: input.signal,
 				interruptSignal: interruptController.signal,
 				runId: input.runId,
@@ -420,7 +423,10 @@ interface ChainExecutionParams {
 	nestedRoute?: NestedRouteInfo;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	forwardedFlags?: string[];
+	resolveConfig?: (cwd: string) => ExtensionConfig;
 }
 
 interface ChainExecutionResult {
@@ -643,10 +649,12 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 
 			if (isParallelStep(step)) {
 				const parallelTemplates = stepTemplates as string[];
-				const parallelCwd = resolveChildCwd(cwd ?? ctx.cwd, step.cwd);
+				const parallelCwd = resolveChildCwd(cwd ?? ctx.cwd, step.cwd === undefined ? undefined : resolveOutputReferences(step.cwd, outputs, trees));
 				let worktreeSetup: WorktreeSetup | undefined;
 				if (step.worktree) {
-					const worktreeTaskCwdConflict = findWorktreeTaskCwdConflict(step.parallel, parallelCwd);
+					const groupConfig = params.resolveConfig?.(parallelCwd) ?? params;
+					const resolvedTasks = step.parallel.map((task) => ({ ...task, cwd: task.cwd === undefined ? undefined : resolveOutputReferences(task.cwd, outputs, trees) }));
+					const worktreeTaskCwdConflict = findWorktreeTaskCwdConflict(resolvedTasks, parallelCwd);
 					if (worktreeTaskCwdConflict) {
 						return buildChainExecutionErrorResult(
 							`parallel chain step ${stepIndex + 1}: ${formatWorktreeTaskCwdConflict(worktreeTaskCwdConflict, parallelCwd)}`,
@@ -657,8 +665,11 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					try {
 						worktreeSetup = createWorktrees(parallelCwd, `${runId}-s${stepIndex}`, step.parallel.length, {
 							agents: step.parallel.map((task) => task.agent),
-							setupHook: params.worktreeSetupHook
-								? { hookPath: params.worktreeSetupHook, timeoutMs: params.worktreeSetupHookTimeoutMs }
+							setupHook: groupConfig.worktreeSetupHook
+								? { hookPath: groupConfig.worktreeSetupHook, timeoutMs: groupConfig.worktreeSetupHookTimeoutMs }
+								: undefined,
+							teardownHook: groupConfig.worktreeTeardownHook
+								? { hookPath: groupConfig.worktreeTeardownHook, timeoutMs: groupConfig.worktreeTeardownHookTimeoutMs }
 								: undefined,
 						});
 					} catch (error) {
@@ -698,6 +709,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						runId,
 						globalTaskIndex,
 						forwardedFlags: params.forwardedFlags,
+						resolveConfig: params.resolveConfig,
 						sessionDirForIndex,
 						sessionFileForIndex,
 						shareEnabled,
@@ -709,7 +721,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						allProgress,
 						outputs,
 						trees,
-						stepCwd: step.cwd,
+						stepCwd: parallelCwd,
 						chainAgents,
 						chainSteps,
 						totalSteps,
@@ -907,6 +919,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					runId,
 					globalTaskIndex,
 					forwardedFlags: params.forwardedFlags,
+					resolveConfig: params.resolveConfig,
 					sessionDirForIndex,
 					sessionFileForIndex,
 					shareEnabled,
@@ -1126,6 +1139,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 					runtime: params.runtime,
 					cwd: stepCwd,
+					executionBackend: params.resolveConfig?.(stepCwd).executionBackend,
 					signal,
 					interruptSignal: interruptController.signal,
 					runId,

package/src/runs/foreground/subagent-executor.ts

@@ -8,6 +8,7 @@ import type { AgentConfig, AgentScope } from "../../agents/agents.ts";
 import { getArtifactsDir } from "../../shared/artifacts.ts";
 import { ChainClarifyComponent, type ChainClarifyResult } from "./chain-clarify.ts";
 import { parentModelFullId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { deriveForwardedFlags } from "../shared/forward-flags.ts";
 import { executeChain } from "./chain-execution.ts";
 import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import { handleManagementAction } from "../../agents/agent-management.ts";
@@ -137,9 +138,7 @@ interface ExecutorDeps {
 	captureRuntime?: () => PiRuntimeIdentity;
 	pi: ExtensionAPI;
 	state: SubagentState;
-	config: ExtensionConfig;
-	forwardedFlags: string[];
-	asyncByDefault: boolean;
+	resolveConfig: (cwd: string) => ExtensionConfig;
 	tempArtifactsDir: string;
 	getSubagentSessionRoot: (parentSessionFile: string | null) => string;
 	expandTilde: (p: string) => string;
@@ -147,6 +146,8 @@ interface ExecutorDeps {
 	allowMutatingManagementActions?: boolean;
 }
 
+type CallExecutorDeps = ExecutorDeps & { config: ExtensionConfig; forwardedFlags: string[]; asyncByDefault: boolean };
+
 interface ExecutionContextData {
 	runtime: PiRuntimeIdentity;
 	params: SubagentParamsLike;
@@ -205,7 +206,7 @@ function formatForegroundActivity(control: SubagentState["foregroundControls"] e
 	return [`active ${seconds}s ago`, ...facts].join(" | ");
 }
 
-function nestedResolutionScopeForExecutor(deps: ExecutorDeps): NestedRunResolutionScope | undefined {
+function nestedResolutionScopeForExecutor(deps: CallExecutorDeps): NestedRunResolutionScope | undefined {
 	if (deps.allowMutatingManagementActions !== false) return undefined;
 	const route = resolveInheritedNestedRouteFromEnv();
 	const address = route ? resolveNestedParentAddressFromEnv() : undefined;
@@ -215,7 +216,7 @@ function nestedResolutionScopeForExecutor(deps: ExecutorDeps): NestedRunResoluti
 	};
 }
 
-function buildAsyncContext(ctx: ExtensionContext, deps: ExecutorDeps, cwd: string, runtime: PiRuntimeIdentity) {
+function buildAsyncContext(ctx: ExtensionContext, deps: CallExecutorDeps, cwd: string, runtime: PiRuntimeIdentity) {
 	return {
 		runtime,
 		pi: deps.pi,
@@ -581,7 +582,7 @@ async function resumeAsyncRun(input: {
 	params: SubagentParamsLike;
 	requestCwd: string;
 	ctx: ExtensionContext;
-	deps: ExecutorDeps;
+	deps: CallExecutorDeps;
 }): Promise<AgentToolResult<Details>> {
 	const followUp = (input.params.message ?? input.params.task ?? "").trim();
 	if (!followUp) {
@@ -627,6 +628,7 @@ async function resumeAsyncRun(input: {
 
 	input.deps.state.currentSessionId = resolveCurrentSessionId(input.ctx.sessionManager);
 	const effectiveCwd = target.cwd ?? input.requestCwd;
+	const unitConfig = effectiveCwd === input.requestCwd ? input.deps.config : input.deps.resolveConfig(effectiveCwd);
 	const scope: AgentScope = resolveExecutionAgentScope(input.params.agentScope);
 	const discoveredAgents = input.deps.discoverAgents(effectiveCwd, scope).agents;
 	const agentConfig = discoveredAgents.find((agent) => agent.name === target.agent);
@@ -649,7 +651,7 @@ async function resumeAsyncRun(input: {
 		agent: target.agent,
 		task: buildRevivedAsyncTask(target, followUp),
 		agentConfig,
-		ctx: buildAsyncContext(input.ctx, input.deps, input.requestCwd, target.runtime),
+		ctx: { ...buildAsyncContext(input.ctx, input.deps, input.requestCwd, target.runtime), executionBackend: unitConfig.executionBackend },
 		cwd: effectiveCwd,
 		maxOutput: input.params.maxOutput,
 		artifactsDir: input.deps.tempArtifactsDir,
@@ -663,8 +665,10 @@ async function resumeAsyncRun(input: {
 		originSessionRoot: originalRoot,
 		sessionFile: target.sessionFile,
 		maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
-		worktreeSetupHook: input.deps.config.worktreeSetupHook,
-		worktreeSetupHookTimeoutMs: input.deps.config.worktreeSetupHookTimeoutMs,
+		worktreeSetupHook: unitConfig.worktreeSetupHook,
+		worktreeSetupHookTimeoutMs: unitConfig.worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook: unitConfig.worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs: unitConfig.worktreeTeardownHookTimeoutMs,
 		controlConfig: resolveControlConfig(input.deps.config.control, input.params.control),
 		availableModels,
 		forwardedFlags: input.deps.forwardedFlags,
@@ -978,7 +982,7 @@ function wrapChainTasksForFork(chain: ChainStep[], context: SubagentParamsLike["
 	});
 }
 
-function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentToolResult<Details> | null {
+function runAsyncPath(data: ExecutionContextData, deps: CallExecutorDeps): AgentToolResult<Details> | null {
 	const {
 		params,
 		effectiveCwd,
@@ -1073,6 +1077,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1102,6 +1108,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1144,6 +1152,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			acceptance: params.acceptance,
@@ -1154,7 +1164,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 	return null;
 }
 
-async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runChainPath(data: ExecutionContextData, deps: CallExecutorDeps): Promise<AgentToolResult<Details>> {
 	const {
 		params,
 		effectiveCwd,
@@ -1200,10 +1210,13 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		nestedRoute: foregroundControl?.nestedRoute,
 		chainSkills,
 		chainDir: params.chainDir,
+		resolveConfig: deps.resolveConfig,
 		dynamicFanoutMaxItems: deps.config.chain?.dynamicFanout?.maxItems,
 		maxSubagentDepth: currentMaxSubagentDepth,
 		worktreeSetupHook: deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook: deps.config.worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 		forwardedFlags: deps.forwardedFlags,
 	});
 
@@ -1237,6 +1250,8 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute: data.nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1276,7 +1291,7 @@ interface ForegroundParallelRunInput {
 	onControlEvent?: (event: ControlEvent) => void;
 	foregroundControl?: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never;
 	concurrencyLimit: number;
-	executionBackend?: string;
+	resolveConfig: (cwd: string) => ExtensionConfig;
 	liveResults: (SingleResult | undefined)[];
 	liveProgress: (AgentProgress | undefined)[];
 	onUpdate?: (r: AgentToolResult<Details>) => void;
@@ -1299,6 +1314,8 @@ function createParallelWorktreeSetup(
 	tasks: TaskParam[],
 	setupHook: ExtensionConfig["worktreeSetupHook"],
 	setupHookTimeoutMs: ExtensionConfig["worktreeSetupHookTimeoutMs"],
+	teardownHook: ExtensionConfig["worktreeTeardownHook"],
+	teardownHookTimeoutMs: ExtensionConfig["worktreeTeardownHookTimeoutMs"],
 ): { setup?: WorktreeSetup; errorResult?: AgentToolResult<Details> } {
 	if (!enabled) return {};
 	try {
@@ -1308,6 +1325,9 @@ function createParallelWorktreeSetup(
 				setupHook: setupHook
 					? { hookPath: setupHook, timeoutMs: setupHookTimeoutMs }
 					: undefined,
+				teardownHook: teardownHook
+					? { hookPath: teardownHook, timeoutMs: teardownHookTimeoutMs }
+					: undefined,
 			}),
 		};
 	} catch (error) {
@@ -1464,7 +1484,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			signal: input.signal,
 			interruptSignal: interruptController.signal,
 			runId: input.runId,
-			executionBackend: input.executionBackend,
+			executionBackend: input.resolveConfig(taskCwd).executionBackend,
 			index,
 			sessionDir: input.sessionDirForIndex(index),
 			sessionFile: input.sessionFileForIndex(index),
@@ -1530,7 +1550,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 	});
 }
 
-async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runParallelPath(data: ExecutionContextData, deps: CallExecutorDeps): Promise<AgentToolResult<Details>> {
 	const {
 		params,
 		effectiveCwd,
@@ -1691,6 +1711,8 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				maxSubagentDepth: currentMaxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook: deps.config.worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				forwardedFlags: deps.forwardedFlags,
 			});
@@ -1709,6 +1731,8 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		tasks,
 		deps.config.worktreeSetupHook,
 		deps.config.worktreeSetupHookTimeoutMs,
+		deps.config.worktreeTeardownHook,
+		deps.config.worktreeTeardownHookTimeoutMs,
 	);
 	if (errorResult) return errorResult;
 
@@ -1786,7 +1810,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			onUpdate: onUpdateWithCost,
 			worktreeSetup,
 			forwardedFlags: deps.forwardedFlags,
-			executionBackend: deps.config.executionBackend,
+			resolveConfig: deps.resolveConfig,
 		});
 		if (foregroundControl) updateForegroundNestedProjection(foregroundControl);
 		recordSyncCost(deps.state.grandTotal, runId, results.reduce((sum, r) => sum + r.usage.cost, 0) + sumNestedCost(foregroundControl?.nestedChildren));
@@ -1846,7 +1870,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 	}
 }
 
-async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Promise<AgentToolResult<Details>> {
+async function runSinglePath(data: ExecutionContextData, deps: CallExecutorDeps): Promise<AgentToolResult<Details>> {
 	const {
 		params,
 		effectiveCwd,
@@ -1952,6 +1976,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				maxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook: deps.config.worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				forwardedFlags: deps.forwardedFlags,
 			});
@@ -2109,7 +2135,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	};
 }
 
-export function createSubagentExecutor(deps: ExecutorDeps): {
+export function createSubagentExecutor(services: ExecutorDeps): {
 	execute: (
 		id: string,
 		params: SubagentParamsLike,
@@ -2122,7 +2148,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 	let runtimeError: unknown;
 	try {
 		// SDK hosts are not launched through Pi's CLI; the installation this extension was loaded from is the fallback.
-		runtime = (deps.captureRuntime ?? (() => capturePiRuntime({ installRoot: getPackageDir() })))();
+		runtime = (services.captureRuntime ?? (() => capturePiRuntime({ installRoot: getPackageDir() })))();
 	} catch (error) {
 		runtimeError = error;
 	}
@@ -2133,11 +2159,13 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 		onUpdate: ((r: AgentToolResult<Details>) => void) | undefined,
 		ctx: ExtensionContext,
 	): Promise<AgentToolResult<Details>> => {
+		const requestCwd = resolveRequestedCwd(ctx.cwd, params.cwd);
+		const config = services.resolveConfig(requestCwd);
+		const deps: CallExecutorDeps = { ...services, config, forwardedFlags: deriveForwardedFlags(process.argv, config), asyncByDefault: config.asyncByDefault === true };
 		deps.state.baseCwd = ctx.cwd;
 		deps.state.foregroundRuns ??= new Map();
 		deps.state.foregroundControls ??= new Map();
 		deps.state.lastForegroundControlId ??= null;
-		const requestCwd = resolveRequestedCwd(ctx.cwd, params.cwd);
 		const paramsWithResolvedCwd = params.cwd === undefined ? params : { ...params, cwd: requestCwd };
 		if (params.action) {
 			if (params.action === "doctor") {

package/src/runs/shared/chain-outputs.ts

@@ -81,9 +81,6 @@ export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutCon
 		}
 		for (const { template, cwd } of taskTemplatesForStep(step)) {
 			for (const match of template.matchAll(OUTPUT_REF_PATTERN)) {
-				if (cwd && isParallelStep(step) && step.worktree) {
-					throw new ChainOutputValidationError(`Chain step ${stepIndex + 1}: cwd output references cannot be combined with worktree: true.`);
-				}
 				const rawReference = match[0];
 				const parsed = parseOutputReference(match[1]!);
 				if (!parsed) {

package/src/runs/shared/worktree.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
+import fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -10,6 +10,8 @@ export interface WorktreeSetup {
 }
 
 interface WorktreeInfo {
+	hookInput: WorktreeSetupHookInput;
+	teardownHook?: ResolvedWorktreeTeardownHook;
 	path: string;
 	agentCwd: string;
 	branch: string;
@@ -41,7 +43,18 @@ interface WorktreeSetupHookConfig {
 	timeoutMs?: number;
 }
 
+interface WorktreeTeardownHookConfig {
+	hookPath: string;
+	timeoutMs?: number;
+}
+
+interface ResolvedWorktreeTeardownHook {
+	hookPath: string;
+	timeoutMs: number;
+}
+
 interface CreateWorktreesOptions {
+	teardownHook?: WorktreeTeardownHookConfig;
 	agents?: string[];
 	setupHook?: WorktreeSetupHookConfig;
 }
@@ -229,6 +242,43 @@ function resolveWorktreeSetupHook(
 	};
 }
 
+function resolveWorktreeTeardownHook(
+	repoRoot: string,
+	config: WorktreeTeardownHookConfig | undefined,
+): ResolvedWorktreeTeardownHook | undefined {
+	if (!config) return undefined;
+	const hookPath = config.hookPath.trim();
+	if (!hookPath) {
+		throw new Error("worktree teardown hook path cannot be empty");
+	}
+
+	const expandedHookPath = hookPath.startsWith("~/") ? path.join(os.homedir(), hookPath.slice(2)) : hookPath;
+	let resolvedPath: string;
+	if (path.isAbsolute(expandedHookPath)) {
+		resolvedPath = expandedHookPath;
+	} else if (expandedHookPath.includes("/") || expandedHookPath.includes("\\")) {
+		resolvedPath = path.resolve(repoRoot, expandedHookPath);
+	} else {
+		throw new Error("worktree teardown hook must be an absolute path or a repo-relative path");
+	}
+
+	if (!fs.existsSync(resolvedPath)) {
+		throw new Error(`worktree teardown hook not found: ${resolvedPath}`);
+	}
+	if (fs.statSync(resolvedPath).isDirectory()) {
+		throw new Error(`worktree teardown hook must be a file, got directory: ${resolvedPath}`);
+	}
+
+	const timeoutMs = config.timeoutMs === undefined ? 30000 : config.timeoutMs;
+	if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+		throw new Error("worktree teardown hook timeout must be an integer greater than 0");
+	}
+	return {
+		hookPath: resolvedPath,
+		timeoutMs: timeoutMs,
+	};
+}
+
 function normalizeSyntheticPath(worktreePath: string, rawPath: string): string {
 	const trimmed = rawPath.trim();
 	if (!trimmed) throw new Error("synthetic path cannot be empty");
@@ -313,6 +363,40 @@ function runWorktreeSetupHook(
 	return [...uniquePaths];
 }
 
+function warnWorktreeCleanup(message: string): void {
+	try { fs.write(2, message + "\n", () => {}); } catch {}
+}
+
+function runWorktreeTeardownHook(
+	hook: ResolvedWorktreeTeardownHook | undefined,
+	input: WorktreeSetupHookInput,
+): void {
+	if (!hook) return;
+	try {
+		const result = spawnSync(hook.hookPath, [], {
+			cwd: input.worktreePath,
+			encoding: "utf-8",
+			input: JSON.stringify(input),
+			timeout: hook.timeoutMs,
+			killSignal: "SIGKILL",
+			shell: false,
+			stdio: ["pipe", "ignore", "pipe"],
+		});
+		let cause: string;
+		if (result.error) {
+			cause = "code" in result.error && result.error.code === "ETIMEDOUT"
+				? `timed out after ${hook.timeoutMs}ms`
+				: result.error.message;
+		} else if (result.status !== 0) {
+			cause = result.signal ? `signal ${result.signal}` : `exit code ${result.status}`;
+		} else return;
+		const stderr = result.stderr?.trim();
+		warnWorktreeCleanup(`worktree teardown hook failed for '${input.worktreePath}': ${cause}${stderr ? `: ${stderr}` : ""}`);
+	} catch (error) {
+		warnWorktreeCleanup(`worktree teardown hook failed for '${input.worktreePath}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 function createSingleWorktree(
 	toplevel: string,
 	cwdRelative: string,
@@ -320,6 +404,7 @@ function createSingleWorktree(
 	index: number,
 	baseCommit: string,
 	setupHook: ResolvedWorktreeSetupHook | undefined,
+	teardownHook: ResolvedWorktreeTeardownHook | undefined,
 	agent: string | undefined,
 ): WorktreeInfo {
 	const branch = buildWorktreeBranch(runId, index);
@@ -331,27 +416,22 @@ function createSingleWorktree(
 	}
 
 	const agentCwd = cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
+	const hookInput: WorktreeSetupHookInput = {
+		version: 1, repoRoot: toplevel, worktreePath, agentCwd, branch, index, runId, baseCommit, agent,
+	};
 	try {
 		const nodeModulesLinked = linkNodeModulesIfPresent(toplevel, worktreePath);
 		const syntheticPaths = nodeModulesLinked ? ["node_modules"] : [];
 
 		if (setupHook) {
-			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, {
-				version: 1,
-				repoRoot: toplevel,
-				worktreePath,
-				agentCwd,
-				branch,
-				index,
-				runId,
-				baseCommit,
-				agent,
-			});
+			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, hookInput);
 			syntheticPaths.push(...hookSyntheticPaths);
 		}
 
 		return {
 			path: worktreePath,
+			hookInput,
+			teardownHook,
 			agentCwd,
 			branch,
 			index,
@@ -359,11 +439,12 @@ function createSingleWorktree(
 			syntheticPaths,
 		};
 	} catch (error) {
-		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
+		runWorktreeTeardownHook(teardownHook, hookInput);
+		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch (cleanupError) {
+			warnWorktreeCleanup(`worktree remove failed for '${worktreePath}': ${cleanupError}`);
 		}
-		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
+		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch (cleanupError) {
+			warnWorktreeCleanup(`branch -D '${branch}' failed for '${worktreePath}': ${cleanupError}`);
 		}
 		throw error;
 	}
@@ -477,11 +558,12 @@ function writeEmptyPatch(patchPath: string): void {
 }
 
 function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+	runWorktreeTeardownHook(worktree.teardownHook, worktree.hookInput);
+	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch (error) {
+		warnWorktreeCleanup(`worktree remove failed for '${worktree.path}': ${error}`);
 	}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch (error) {
+		warnWorktreeCleanup(`branch -D '${worktree.branch}' failed for '${worktree.path}': ${error}`);
 	}
 }
 
@@ -498,6 +580,7 @@ export function patchPathForDiff(diff: WorktreeDiff): string | undefined {
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	const repo = resolveRepoState(cwd);
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+	const teardownHook = resolveWorktreeTeardownHook(repo.toplevel, options?.teardownHook);
 	const worktrees: WorktreeInfo[] = [];
 
 	try {
@@ -509,6 +592,7 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 				index,
 				repo.baseCommit,
 				setupHook,
+				teardownHook,
 				options?.agents?.[index],
 			));
 		}

package/src/shared/types.ts

@@ -859,6 +859,7 @@ interface ExtensionChainConfig {
 	};
 }
 
+/** Sparse extension settings resolved from settings.json#subagents. */
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
@@ -869,6 +870,8 @@ export interface ExtensionConfig {
 	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	/** Print a roster of discovered subagents/chains into chat at session start. Default: true. */
 	showRosterOnStart?: boolean;
 	/** Forward the parent pi's extension CLI flags (e.g. --no-autofix) into spawned children. Default: true. */

package/src/extension/config.ts

@@ -1,16 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionConfig } from "../shared/types.ts";
-import { getAgentDir } from "../shared/utils.ts";
-
-export function loadConfig(): ExtensionConfig {
-	const configPath = path.join(getAgentDir(), "extensions", "pi-cohort", "config.json");
-	try {
-		if (fs.existsSync(configPath)) {
-			return JSON.parse(fs.readFileSync(configPath, "utf-8")) as ExtensionConfig;
-		}
-	} catch (error) {
-		console.error(`Failed to load pi-cohort config from '${configPath}':`, error);
-	}
-	return {};
-}