@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

package/src/resources/extensions/search-the-web/native-search.ts

@@ -7,6 +7,7 @@
 
 import { isAnthropicApi } from "@gsd/pi-ai";
 import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
+import { resolveSearchProvider } from "./provider.js";
 
 /** Tool names for the Brave-backed custom search tools */
 export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
@@ -194,11 +195,22 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
         active.filter((t: string) => !CUSTOM_SEARCH_TOOL_NAMES.includes(t))
       );
     } else if (!isAnthropicProvider && wasAnthropic) {
-      // Switching away from Anthropic — re-enable custom search tools (they
-      // were disabled while native search was active). If keys are missing,
-      // user sees the error rather than tools silently vanishing.
+      // Switching away from Anthropic — re-enable custom search tools that were
+      // disabled while native search was active. Only re-add the Brave/Tavily/
+      // Ollama-backed tools when a provider key is actually configured: without
+      // a key they can only return an auth error, and re-adding their names
+      // would advertise a tool the model cannot use (and, when unregistered,
+      // leak a schema-less phantom name into the tool surface). google_search
+      // is owned by its own extension (which now gates its registration on
+      // Gemini creds); re-adding its name here is harmless either way — it
+      // activates if registered, or is dropped as a no-op if not.
       const active = pi.getActiveTools();
-      const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => !active.includes(t));
+      const providerConfigured = resolveSearchProvider() !== null;
+      const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => {
+        if (active.includes(t)) return false;
+        if (BRAVE_TOOL_NAMES.includes(t)) return providerConfigured;
+        return true;
+      });
       if (toAdd.length > 0) {
         pi.setActiveTools([...active, ...toAdd]);
       }
@@ -243,9 +255,11 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
       // Anthropic-only tool never leaks into OpenAI Responses requests.
       isAnthropic = isAnthropicProvider && payloadLooksAnthropic !== false;
     } else {
-      // Last resort: session-restore paths where the SDK doesn't pass model.
-      // The model-name prefix is best-effort and assumes direct Anthropic.
-      isAnthropic = payloadLooksAnthropic === true;
+      // No authoritative provider info available (no event.model, no model_select).
+      // Do NOT inject native web_search — guessing on model name alone causes 400
+      // "unsupported_value" errors when the actual provider (copilot, openrouter,
+      // proxy, etc.) doesn't expose the server-side search tool (#648).
+      isAnthropic = false;
     }
     if (!isAnthropic) return;
 

package/src/resources/extensions/shared/browser-contract.ts

@@ -0,0 +1,66 @@
+// Project/App: gsd-pi
+// File Purpose: Browser Automation Contract — the single source for the canonical
+// Pi-facing browser tool vocabulary. Engine adapters (legacy Playwright, managed
+// gsd-browser), UAT policy, dispatch preflight, and evidence detection all derive
+// their browser tool knowledge from this module instead of re-listing names.
+
+/**
+ * Canonical `browser_*` tool names of the Browser Automation Contract.
+ *
+ * These are the product-level names Units see regardless of which Browser
+ * Automation Engine serves them (ADR-024). Adding a capability here is the
+ * one-line vocabulary change; the engine adapters and presentation surfaces
+ * are typed against this list, so missing coverage fails typecheck.
+ */
+export const BROWSER_CONTRACT_TOOL_NAMES = [
+  "browser_navigate",
+  "browser_click",
+  "browser_type",
+  "browser_fill_form",
+  "browser_click_ref",
+  "browser_fill_ref",
+  "browser_wait_for",
+  "browser_assert",
+  "browser_verify",
+  "browser_screenshot",
+  "browser_snapshot_refs",
+  "browser_find",
+  "browser_get_console_logs",
+  "browser_get_network_logs",
+  "browser_evaluate",
+  "browser_reload",
+  "browser_batch",
+  "browser_act",
+] as const;
+
+export type BrowserContractToolName = (typeof BROWSER_CONTRACT_TOOL_NAMES)[number];
+
+const BROWSER_CONTRACT_TOOL_NAME_SET: ReadonlySet<string> = new Set(BROWSER_CONTRACT_TOOL_NAMES);
+
+export function isBrowserContractToolName(name: string): name is BrowserContractToolName {
+  return BROWSER_CONTRACT_TOOL_NAME_SET.has(name);
+}
+
+/**
+ * Whether a canonical (non-MCP-prefixed) tool name belongs to the browser tool
+ * family. Broader than the contract list on purpose: an External MCP Client or
+ * host integration may supply additional `browser_*` tools that still satisfy
+ * browser-backed UAT.
+ */
+export function hasBrowserContractPrefix(canonicalToolName: string): boolean {
+  return canonicalToolName.startsWith("browser_");
+}
+
+/**
+ * Contract tool names whose appearance in prose marks browser-backed UAT
+ * activity (requirement or evidence language). Consumed by the
+ * browser-evidence regexes so textual detection stays derived from the
+ * contract vocabulary.
+ */
+export const BROWSER_EVIDENCE_SIGNAL_TOOL_NAMES = [
+  "browser_assert",
+  "browser_batch",
+  "browser_find",
+  "browser_verify",
+  "browser_snapshot_refs",
+] as const satisfies readonly BrowserContractToolName[];

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -55,6 +55,32 @@ function parseGsdBrowserVersion(output: string): string | null {
   return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
 
+function splitCommandLine(commandLine: string): string[] {
+  const parts = commandLine.match(/(?:"[^"]*"|'[^']*'|[^\s"']+)/g) ?? [];
+  return parts.map((part) => {
+    const quote = part[0];
+    if ((quote === '"' || quote === "'") && part.endsWith(quote)) {
+      return part.slice(1, -1);
+    }
+    return part;
+  });
+}
+
+function buildPathGsdBrowserVersionInvocation(platform: NodeJS.Platform): { command: string; args: string[] } {
+  if (platform === "win32") {
+    return { command: "cmd", args: ["/d", "/s", "/c", "gsd-browser", "--version"] };
+  }
+  return { command: "gsd-browser", args: ["--version"] };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveExplicitGsdBrowserCliPath(env: NodeJS.ProcessEnv): string | undefined {
+  return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
+
 function resolveBundledGsdBrowserPackageVersion(): string | null {
   try {
     const requireFromHere = createRequire(import.meta.url);
@@ -66,32 +92,74 @@ function resolveBundledGsdBrowserPackageVersion(): string | null {
   }
 }
 
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion: string | null | undefined;
+
 function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
   const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
   if (explicit) return parseGsdBrowserVersion(explicit);
+  if (cachedPathProbeVersion !== undefined) return cachedPathProbeVersion;
 
   try {
-    return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+    const invocation = buildPathGsdBrowserVersionInvocation(process.platform);
+    cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync(invocation.command, invocation.args, {
       encoding: "utf-8",
       env,
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 2000,
     }));
   } catch {
-    return null;
+    cachedPathProbeVersion = null;
+  }
+  return cachedPathProbeVersion;
+}
+
+function resolveGsdBrowserNativeBinaryPath(launcherPath: string, platform: NodeJS.Platform = process.platform): string {
+  const binDir = resolve(launcherPath, "..");
+  const nativeName = platform === "win32" ? "gsd-browser.exe" : "gsd-browser-bin";
+  return resolve(binDir, nativeName);
+}
+
+function isNodeShLauncher(launcherPath: string): boolean {
+  try {
+    return readFileSync(launcherPath, "utf-8").startsWith("#!");
+  } catch {
+    // Non-text launchers (native binaries) are runnable without a sibling shim.
+    return false;
   }
 }
 
+/**
+ * The npm package ships a node launcher that execs `gsd-browser-bin` beside it.
+ * pnpm can skip postinstall, leaving only the launcher — which exits immediately
+ * and surfaces as MCP "Connection closed". Treat that layout as unavailable.
+ */
+function isGsdBrowserPackageLauncherRunnable(launcherPath: string): boolean {
+  if (!existsSync(launcherPath)) return false;
+  const nativePath = resolveGsdBrowserNativeBinaryPath(launcherPath);
+  if (existsSync(nativePath)) return true;
+  return !isNodeShLauncher(launcherPath);
+}
+
 function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
   const pathVersion = resolvePathGsdBrowserVersion(env);
   if (!pathVersion) return false;
 
   const bundledVersion = resolveBundledGsdBrowserPackageVersion();
-  return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
+  if (!bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0) {
+    return true;
+  }
+
+  // Same or newer bundled semver still loses when the package launcher cannot run.
+  const bundledLauncher = resolveBundledGsdBrowserLauncherPath(env);
+  return bundledLauncher !== null && !isGsdBrowserPackageLauncherRunnable(bundledLauncher);
 }
 
-export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
-  const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+function resolveBundledGsdBrowserLauncherPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const explicit = resolveExplicitGsdBrowserCliPath(env);
   if (explicit) return explicit;
 
   try {
@@ -115,6 +183,51 @@ export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process
   return null;
 }
 
+export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const launcher = resolveBundledGsdBrowserLauncherPath(env);
+  if (!launcher || !isGsdBrowserPackageLauncherRunnable(launcher)) return null;
+  return launcher;
+}
+
+export type GsdBrowserCliAvailability =
+  | { available: true; via: "explicit-env" | "bundled" | "path"; detail: string }
+  | { available: false; detail: string };
+
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env: NodeJS.ProcessEnv = process.env): GsdBrowserCliAvailability {
+  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  if (explicitCommand) {
+    return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+  }
+
+  const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+  if (explicitCliPath) {
+    return existsSync(explicitCliPath)
+      ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+      : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+  }
+
+  const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+  if (bundledCliPath) {
+    return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+  }
+
+  const pathVersion = resolvePathGsdBrowserVersion(env);
+  if (pathVersion) {
+    return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+  }
+
+  return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
+
 export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string): string {
   const resolvedProjectRoot = resolve(projectRoot);
   const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -123,6 +236,35 @@ export function buildGsdBrowserSessionName(projectRoot: string, suffix?: string)
   return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
 
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config: unknown): boolean {
+  if (!isRecord(config)) return false;
+
+  const command = typeof config.command === "string" ? config.command : "";
+  if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+    return true;
+  }
+
+  if (isRecord(config.env)) {
+    const env = config.env;
+    if (
+      typeof env.GSD_BROWSER_CLI_PATH === "string"
+      || typeof env.GSD_BROWSER_BIN_PATH === "string"
+      || typeof env.GSD_BROWSER_MCP_COMMAND === "string"
+    ) {
+      return true;
+    }
+  }
+
+  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
+  return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
+
 export function resolveGsdBrowserMcpLaunchConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
@@ -132,8 +274,9 @@ export function resolveGsdBrowserMcpLaunchConfig(
   const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
   const explicitArgs = parseJsonEnv<unknown>(env, "GSD_BROWSER_MCP_ARGS");
   const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_BROWSER_MCP_ENV");
-  const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-  const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+  const explicitCommandLine = env.GSD_BROWSER_MCP_COMMAND?.trim();
+  const [explicitCommand, ...explicitCommandArgs] = explicitCommandLine ? splitCommandLine(explicitCommandLine) : [];
+  const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
   const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
   const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
     ? resolveBundledGsdBrowserCliPath(env)
@@ -144,6 +287,10 @@ export function resolveGsdBrowserMcpLaunchConfig(
   // profile/cookies persist across pi sessions for the same project. gsd-browser
   // rejects --identity-scope unless --identity-key is also supplied.
   const identityKey = env.GSD_BROWSER_IDENTITY_KEY?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
+  // identity-project must be a safe identifier (no path separators); full paths
+  // cause daemon startup to fail with "invalid name".
+  const identityProject =
+    env.GSD_BROWSER_IDENTITY_PROJECT?.trim() || buildGsdBrowserSessionName(resolvedProjectRoot);
   const command =
     explicitCommand
     || explicitCliPath
@@ -153,6 +300,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
   const args = Array.isArray(explicitArgs) && explicitArgs.length > 0
     ? explicitArgs.map(String)
     : [
+        ...explicitCommandArgs,
         ...(bundledCliPath ? [bundledCliPath] : []),
         "mcp",
         "--session",
@@ -162,7 +310,7 @@ export function resolveGsdBrowserMcpLaunchConfig(
         "--identity-key",
         identityKey,
         "--identity-project",
-        resolvedProjectRoot,
+        identityProject,
       ];
   const cwd = env.GSD_BROWSER_MCP_CWD?.trim() || resolvedProjectRoot;
 
@@ -176,3 +324,29 @@ export function resolveGsdBrowserMcpLaunchConfig(
     sessionName,
   };
 }
+
+/**
+ * CLI invocation that starts the gsd-browser session daemon with the same
+ * session and identity flags as {@link resolveGsdBrowserMcpLaunchConfig}, so
+ * browser UAT can warm Chrome/CDP before the first MCP navigation.
+ */
+export function resolveGsdBrowserDaemonStartInvocation(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+  options: GsdBrowserMcpLaunchOptions = {},
+): Pick<GsdBrowserMcpLaunchConfig, "command" | "args" | "cwd" | "env"> {
+  const launch = resolveGsdBrowserMcpLaunchConfig(projectRoot, env, options);
+  const mcpIndex = launch.args.indexOf("mcp");
+  if (mcpIndex < 0) {
+    throw new Error("gsd-browser launch config is missing mcp subcommand");
+  }
+
+  const prefix = launch.args.slice(0, mcpIndex);
+  const sessionFlags = launch.args.slice(mcpIndex + 1);
+  return {
+    command: launch.command,
+    args: [...prefix, "daemon", "start", ...sessionFlags],
+    cwd: launch.cwd,
+    ...(launch.env ? { env: launch.env } : {}),
+  };
+}

package/src/resources/extensions/shared/interview-ui.ts

@@ -62,6 +62,13 @@ export interface RoundResult {
 	/** Always false — end is handled by showWrapUpScreen, not per-question */
 	endInterview: false;
 	answers: Record<string, { selected: string | string[]; notes: string }>;
+	/**
+	 * Set to true only when the round ended because the external AbortSignal
+	 * fired (e.g. a system/host teardown), as distinct from a deliberate user
+	 * dismissal. Consumers use this to avoid laundering a system teardown into a
+	 * clean user-declined cancel. Additive/optional — native consumers ignore it.
+	 */
+	interrupted?: boolean;
 }
 
 export interface WrapUpResult {
@@ -97,6 +104,12 @@ export interface InterviewRoundOptions {
 	 * Defaults to "end interview".
 	 */
 	exitLabel?: string;
+	/**
+	 * Render as a floating overlay instead of replacing the editor. Use when the
+	 * interview must stay visible during an in-flight agent stream (e.g. claude-code-cli
+	 * MCP elicitation).
+	 */
+	overlay?: boolean;
 }
 
 export interface WrapUpOptions {
@@ -240,7 +253,7 @@ export async function showInterviewRound(
 
 		// External cancellation (e.g. remote channel won the race)
 		if (opts.signal) {
-			const onAbort = () => finish({ endInterview: false, answers: {} });
+			const onAbort = () => finish({ endInterview: false, answers: {}, interrupted: true });
 			if (opts.signal.aborted) { onAbort(); }
 			else {
 				opts.signal.addEventListener("abort", onAbort, { once: true });
@@ -845,5 +858,5 @@ export async function showInterviewRound(
 			invalidate: () => { cachedLines = undefined; },
 			handleInput,
 		};
-	});
+	}, opts.overlay ? { overlay: true } : undefined);
 }

package/src/resources/extensions/subagent/index.ts

@@ -45,6 +45,7 @@ import {
 	type SubagentContextMode,
 	type SubagentSessionArgs,
 } from "./launch.js";
+import { resolveSubagentWorktreeCwd } from "./worktree-cwd.js";
 import {
 	SubagentRunStore,
 	createInitialRunRecord,
@@ -1003,16 +1004,19 @@ export default function (pi: ExtensionAPI) {
 					: hasTasks && taskParams.some((task) => (task.context ?? contextMode) === "fork")
 						? "fork"
 						: contextMode;
-			const dispatchChildren = dispatchAgents.map((agent, index) => ({
-				agent,
-				trackingName: dispatchTrackingNames[index],
-				task: dispatchTasks[index] ?? "",
-				cwd: hasChain
+			const dispatchChildren = dispatchAgents.map((agent, index) => {
+				const rawCwd = hasChain
 					? chainParams[index]?.cwd
 					: hasTasks
 						? taskParams[index]?.cwd
-						: params.cwd,
-			}));
+						: params.cwd;
+				return {
+					agent,
+					trackingName: dispatchTrackingNames[index],
+					task: dispatchTasks[index] ?? "",
+					cwd: resolveSubagentWorktreeCwd(ctx.cwd, rawCwd),
+				};
+			});
 			try {
 				runStore.create(createInitialRunRecord({
 					runId: dispatchId,
@@ -1240,7 +1244,7 @@ export default function (pi: ExtensionAPI) {
 				void (async () => {
 					let isolation: IsolationEnvironment | null = null;
 					try {
-						const effectiveCwd = params.cwd ?? ctx.cwd;
+						const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
 						if (useIsolation) {
 							const taskId = crypto.randomUUID();
 							isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
@@ -1250,7 +1254,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent!,
 							params.task!,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							undefined,
 							(partial) => {
@@ -1321,12 +1325,13 @@ export default function (pi: ExtensionAPI) {
 						}
 					};
 
+					const stepCwd = resolveSubagentWorktreeCwd(ctx.cwd, step.cwd);
 					const result = await runSingleAgent(
 						ctx.cwd,
 						agents,
 						step.agent,
 						taskWithContext,
-						step.cwd,
+						stepCwd,
 						i + 1,
 						signal,
 						chainUpdate,
@@ -1464,14 +1469,14 @@ export default function (pi: ExtensionAPI) {
 							);
 					const runTask = async () => {
 						let isolation: IsolationEnvironment | null = null;
-						const effectiveCwd = t.cwd ?? ctx.cwd;
+						const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, t.cwd);
 						try {
 							if (useIsolation) {
 								const taskId = crypto.randomUUID();
 								isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
 							}
 
-							const result = await executeOnce(isolation ? isolation.workDir : t.cwd);
+							const result = await executeOnce(isolation ? isolation.workDir : effectiveCwd);
 							if (isolation && result.exitCode === 0) {
 								const patches = await isolation.captureDelta();
 								const mergeResult = patches.length > 0
@@ -1530,7 +1535,7 @@ export default function (pi: ExtensionAPI) {
 				let isolation: IsolationEnvironment | null = null;
 				let mergeResult: MergeResult | undefined;
 				try {
-					const effectiveCwd = params.cwd ?? ctx.cwd;
+					const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
 
 					if (useIsolation) {
 						const taskId = crypto.randomUUID();
@@ -1549,7 +1554,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent,
 							params.task,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							signal,
 							singleUpdate,
@@ -1566,7 +1571,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent,
 							params.task,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							signal,
 							singleUpdate,

package/src/resources/extensions/subagent/tests/worktree-cwd.test.ts

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for subagent cwd pinning inside milestone worktrees.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveSubagentWorktreeCwd } from "../worktree-cwd.js";
+
+test("resolveSubagentWorktreeCwd defaults to parent when task cwd is omitted in worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	try {
+		mkdirSync(worktree, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree), worktree);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd pins project-root cwd to parent worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	try {
+		mkdirSync(worktree, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree, root), worktree);
+		assert.equal(resolveSubagentWorktreeCwd(worktree, join(root, "app.js")), worktree);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd allows relative paths inside the worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	const nested = join(worktree, "src");
+	try {
+		mkdirSync(nested, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree, "src"), nested);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd leaves non-worktree parents unchanged", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const nested = join(root, "packages", "app");
+	try {
+		mkdirSync(nested, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(root), root);
+		assert.equal(resolveSubagentWorktreeCwd(root, "packages/app"), nested);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});

package/src/resources/extensions/subagent/worktree-cwd.ts

@@ -0,0 +1,35 @@
+// Project/App: gsd-pi
+// File Purpose: Pin subagent cwd to the parent milestone worktree so parallel
+// reactive-execute children cannot spawn at the project root.
+
+import path from "node:path";
+
+import { isGsdWorktreePath } from "../gsd/worktree-root.js";
+
+function pathInside(parent: string, target: string): boolean {
+	const parentWithSep = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+	return target === parent || target.startsWith(parentWithSep);
+}
+
+/**
+ * Resolve the cwd for a subagent child. When the parent is already inside a GSD
+ * milestone worktree, children must stay in that worktree — even if the model
+ * omits `cwd` or passes the project root (the root-write leak vector for
+ * reactive-execute).
+ */
+export function resolveSubagentWorktreeCwd(parentCwd: string, taskCwd?: string): string {
+	const resolvedParent = path.resolve(parentCwd);
+	if (!isGsdWorktreePath(resolvedParent)) {
+		return taskCwd ? path.resolve(resolvedParent, taskCwd) : resolvedParent;
+	}
+	if (!taskCwd) {
+		return resolvedParent;
+	}
+	const resolvedTask = path.isAbsolute(taskCwd)
+		? path.resolve(taskCwd)
+		: path.resolve(resolvedParent, taskCwd);
+	if (pathInside(resolvedParent, resolvedTask)) {
+		return resolvedTask;
+	}
+	return resolvedParent;
+}