pi-cohort 7.5.0 → 7.6.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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

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.5.0",
+  "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/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";
@@ -608,6 +609,7 @@ function writeRunLog(
 
 /** Internal context for one detached-runner leaf. */
 export interface SingleStepContext {
+	jobCwd?: string;
 	previousOutput: string;
 	outputs?: ChainOutputMap;
 	trees?: TreeRegistry;
@@ -666,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) {
@@ -1961,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,
@@ -2102,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;
@@ -2132,11 +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: config.worktreeTeardownHook
-							? { hookPath: config.worktreeTeardownHook, timeoutMs: config.worktreeTeardownHookTimeoutMs }
+						teardownHook: groupConfig.worktreeTeardownHook
+							? { hookPath: groupConfig.worktreeTeardownHook, timeoutMs: groupConfig.worktreeTeardownHookTimeoutMs }
 							: undefined,
 					});
 				} catch (error) {
@@ -2218,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,
@@ -2400,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,
@@ -423,6 +426,7 @@ interface ChainExecutionParams {
 	worktreeTeardownHook?: string;
 	worktreeTeardownHookTimeoutMs?: number;
 	forwardedFlags?: string[];
+	resolveConfig?: (cwd: string) => ExtensionConfig;
 }
 
 interface ChainExecutionResult {
@@ -645,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)}`,
@@ -659,11 +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: params.worktreeTeardownHook
-								? { hookPath: params.worktreeTeardownHook, timeoutMs: params.worktreeTeardownHookTimeoutMs }
+							teardownHook: groupConfig.worktreeTeardownHook
+								? { hookPath: groupConfig.worktreeTeardownHook, timeoutMs: groupConfig.worktreeTeardownHookTimeoutMs }
 								: undefined,
 						});
 					} catch (error) {
@@ -703,6 +709,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						runId,
 						globalTaskIndex,
 						forwardedFlags: params.forwardedFlags,
+						resolveConfig: params.resolveConfig,
 						sessionDirForIndex,
 						sessionFileForIndex,
 						shareEnabled,
@@ -714,7 +721,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 						allProgress,
 						outputs,
 						trees,
-						stepCwd: step.cwd,
+						stepCwd: parallelCwd,
 						chainAgents,
 						chainSteps,
 						totalSteps,
@@ -912,6 +919,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					runId,
 					globalTaskIndex,
 					forwardedFlags: params.forwardedFlags,
+					resolveConfig: params.resolveConfig,
 					sessionDirForIndex,
 					sessionFileForIndex,
 					shareEnabled,
@@ -1131,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,10 +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,
-		worktreeTeardownHook: input.deps.config.worktreeTeardownHook,
-		worktreeTeardownHookTimeoutMs: input.deps.config.worktreeTeardownHookTimeoutMs,
+		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,
@@ -980,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,
@@ -1162,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,
@@ -1208,6 +1210,7 @@ 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,
@@ -1288,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;
@@ -1481,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),
@@ -1547,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,
@@ -1807,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));
@@ -1867,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,
@@ -2132,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,
@@ -2145,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;
 	}
@@ -2156,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/shared/types.ts

@@ -859,6 +859,7 @@ interface ExtensionChainConfig {
 	};
 }
 
+/** Sparse extension settings resolved from settings.json#subagents. */
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;

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 {};
-}