gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/src/resources/extensions/gsd/watch/header-renderer.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { visibleWidth, truncateToWidth } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { gsdHome } from "../gsd-home.js";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -106,7 +107,7 @@ export function readMcpServerNames(projectRoot: string): string[] {
   const configPaths = [
     join(projectRoot, ".mcp.json"),
     join(projectRoot, ".gsd", "mcp.json"),
-    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+    join(gsdHome(), "mcp.json"),
   ];
   const names: string[] = [];
   const seen = new Set<string>();

package/src/resources/extensions/gsd/workflow-install.ts

@@ -22,12 +22,12 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { extname, join, resolve, sep as pathSep } from "node:path";
 import { createHash } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 
 import { validateDefinition } from "./definition-loader.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
@@ -73,8 +73,7 @@ export interface InstallTarget {
 }
 
 export function globalInstallDir(): string {
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  return join(gsdHome, "workflows");
+  return join(gsdHome(), "workflows");
 }
 
 export function projectInstallDir(basePath: string): string {

package/src/resources/extensions/gsd/workflow-mcp.ts

@@ -207,7 +207,7 @@ function buildWorkflowLaunchEnv(
 
   return {
     ...(explicitEnv ?? {}),
-    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
+    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
     ...(executorModulePath ? { GSD_WORKFLOW_EXECUTORS_MODULE: executorModulePath } : {}),
     ...(writeGateModulePath ? { GSD_WORKFLOW_WRITE_GATE_MODULE: writeGateModulePath } : {}),
     ...(nodeOptions ? { NODE_OPTIONS: nodeOptions } : {}),
@@ -225,7 +225,11 @@ export function detectWorkflowMcpLaunchConfig(
   const explicitArgs = parseJsonEnv<unknown>(env, "GSD_WORKFLOW_MCP_ARGS");
   const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_WORKFLOW_MCP_ENV");
   const explicitCwd = env.GSD_WORKFLOW_MCP_CWD?.trim();
-  const gsdCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+  const gsdCliPath =
+    explicitEnv?.GSD_CLI_PATH?.trim()
+    || explicitEnv?.GSD_BIN_PATH?.trim()
+    || env.GSD_CLI_PATH?.trim()
+    || env.GSD_BIN_PATH?.trim();
   const workflowProjectRoot =
     explicitEnv?.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
     env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
@@ -298,6 +302,12 @@ export function buildWorkflowMcpServers(
 
 export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[] {
   switch (unitType) {
+    case "discuss-project":
+      return ["ask_user_questions", "gsd_summary_save"];
+    case "discuss-requirements":
+      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+    case "research-decision":
+      return ["ask_user_questions"];
     case "discuss-milestone":
       return ["gsd_summary_save", "gsd_plan_milestone"];
     case "discuss-slice":
@@ -320,6 +330,12 @@ export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[
 
 export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[] {
   switch (unitType) {
+    case "discuss-project":
+      return ["ask_user_questions", "gsd_summary_save"];
+    case "discuss-requirements":
+      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+    case "research-decision":
+      return ["ask_user_questions"];
     case "discuss-milestone":
       return ["gsd_summary_save", "gsd_plan_milestone"];
     case "research-milestone":
@@ -358,11 +374,32 @@ export function usesWorkflowMcpTransport(
   return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
 }
 
+function hasAskUserQuestionsTool(activeTools: string[]): boolean {
+  return activeTools.some((toolName) => {
+    if (toolName === "ask_user_questions") return true;
+    if (!toolName.startsWith("mcp__")) return false;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === "ask_user_questions";
+  });
+}
+
+function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
+  return value === "1" || value === "true";
+}
+
 export function supportsStructuredQuestions(
   activeTools: string[],
-  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl"> = {},
+  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl" | "env"> = {},
 ): boolean {
-  if (!activeTools.includes("ask_user_questions")) return false;
+  if (!hasAskUserQuestionsTool(activeTools)) return false;
+  if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) {
+    // Claude Code local workflow-MCP exposes ask_user_questions, but form
+    // elicitation can return an immediate cancel outside GSD's chat turn. Keep
+    // checkpoints in plain chat unless a caller deliberately opts into testing
+    // that transport.
+    return workflowMcpStructuredQuestionsOptIn(options.env);
+  }
 
   return true;
 }

package/src/resources/extensions/gsd/workflow-plugins.ts

@@ -21,10 +21,10 @@ import {
 } from "node:fs";
 import { join, dirname, extname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
 import { parse as parseYaml } from "yaml";
 
 import { loadRegistry, type TemplateEntry, type WorkflowMode } from "./workflow-templates.js";
+import { gsdHome } from "./gsd-home.js";
 
 export type { WorkflowMode } from "./workflow-templates.js";
 
@@ -58,15 +58,14 @@ function resolveBundledDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
   const local = join(moduleDir, "workflow-templates");
   if (existsSync(local)) return local;
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd", "workflow-templates");
+  const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd", "workflow-templates");
   if (existsSync(agentGsdDir)) return agentGsdDir;
   return local;
 }
 
 function globalPluginsDir(): string {
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  return join(gsdHome, "workflows");
+  
+  return join(gsdHome(), "workflows");
 }
 
 function projectPluginsDir(basePath: string): string {

package/src/resources/extensions/gsd/workflow-templates.ts

@@ -8,7 +8,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { gsdHome } from "./gsd-home.js";
 
 const __extensionDir = resolveGsdExtensionDir();
 const registryPath = join(__extensionDir, "workflow-templates", "registry.json");
@@ -17,8 +17,7 @@ const registryPath = join(__extensionDir, "workflow-templates", "registry.json")
 function resolveGsdExtensionDir(): string {
   const moduleDir = dirname(fileURLToPath(import.meta.url));
   if (existsSync(join(moduleDir, "workflow-templates"))) return moduleDir;
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
+  const agentGsdDir = join(gsdHome(), "agent", "extensions", "gsd");
   if (existsSync(join(agentGsdDir, "workflow-templates"))) return agentGsdDir;
   return moduleDir;
 }

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -30,7 +30,7 @@ import { resolveWorktreeProjectRoot } from "./worktree-root.js";
 export interface WorktreeResolverDeps {
   isInAutoWorktree: (basePath: string) => boolean;
   shouldUseWorktreeIsolation: () => boolean;
-  getIsolationMode: () => "worktree" | "branch" | "none";
+  getIsolationMode: (basePath?: string) => "worktree" | "branch" | "none";
   mergeMilestoneToMain: (
     basePath: string,
     milestoneId: string,
@@ -185,7 +185,11 @@ export class WorktreeResolver {
       return;
     }
 
-    const mode = this.deps.getIsolationMode();
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
+    const mode = this.deps.getIsolationMode(basePath);
 
     if (mode === "none") {
       debugLog("WorktreeResolver", {
@@ -204,10 +208,6 @@ export class WorktreeResolver {
       return;
     }
 
-    // Resolve the project root for worktree operations via shared helper.
-    // Handles the case where originalBasePath is falsy and basePath is itself
-    // a worktree path — prevents double-nested worktree paths (#3729).
-    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -404,6 +404,30 @@ export class WorktreeResolver {
   mergeAndExit(milestoneId: string, ctx: NotifyCtx): void {
     this.validateMilestoneId(milestoneId);
 
+    // Anchor cwd at the project root before any merge work. Some merge code
+    // paths (mergeMilestoneToMain, slice-cadence) chdir explicitly; others
+    // (branch-mode, isolation-degraded skip, missing-original-base skip)
+    // do not. If the worktree dir is later torn down while cwd still points
+    // into it, every subsequent process.cwd() throws ENOENT — and after
+    // de73fb43d that surfaces as a session-failed cancel and (in headless
+    // mode) terminates the whole gsd process. Best-effort: silent on
+    // failure so existing test fixtures that use synthetic paths still pass.
+    if (this.s.originalBasePath) {
+      try {
+        // process.cwd() can throw ENOENT when cwd was removed, so attempt
+        // recovery directly.
+        process.chdir(this.s.originalBasePath);
+      } catch (err) {
+        debugLog("WorktreeResolver", {
+          action: "mergeAndExit",
+          phase: "pre-merge-chdir-failed",
+          milestoneId,
+          originalBasePath: this.s.originalBasePath,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     // #4764 — telemetry: record start timestamp so we can emit merge duration.
     const mergeStartedAt = new Date().toISOString();
     const mergeStartMs = Date.now();
@@ -423,7 +447,7 @@ export class WorktreeResolver {
       return;
     }
 
-    const mode = this.deps.getIsolationMode();
+    const mode = this.deps.getIsolationMode(this.s.originalBasePath || this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "mergeAndExit",
       milestoneId,

package/src/resources/extensions/gsd/worktree-root.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { gsdHome } from "./gsd-home.js";
 
 export interface WorktreeSegment {
   gsdIdx: number;
@@ -69,7 +69,9 @@ export function resolveWorktreeProjectRoot(
 function resolveProjectRootFromPath(path: string): string {
   const normalizedPath = path.replaceAll("\\", "/");
   const segment = findWorktreeSegment(normalizedPath);
-  if (!segment) return resolveGitWorkingTreeRoot(path) ?? path;
+  if (!segment) {
+    return resolveNearestBootstrappedGsdRoot(path) ?? resolveGitWorkingTreeRoot(path) ?? path;
+  }
 
   const sepChar = path.includes("\\") ? "\\" : "/";
   const gsdMarker = `${sepChar}.gsd${sepChar}`;
@@ -78,10 +80,10 @@ function resolveProjectRootFromPath(path: string): string {
     ? path.slice(0, markerIdx)
     : path.slice(0, segment.gsdIdx);
 
-  const gsdHome = normalizeWorktreePathForCompare(process.env.GSD_HOME || join(homedir(), ".gsd"));
+  const gsdHomeNorm = normalizeWorktreePathForCompare(gsdHome());
   const candidateGsdPath = normalizeWorktreePathForCompare(join(candidate, ".gsd"));
 
-  if (candidateGsdPath === gsdHome || candidateGsdPath.startsWith(`${gsdHome}/`)) {
+  if (candidateGsdPath === gsdHomeNorm || candidateGsdPath.startsWith(`${gsdHomeNorm}/`)) {
     const realRoot = resolveProjectRootFromGitFile(path);
     return realRoot ?? path;
   }
@@ -89,6 +91,35 @@ function resolveProjectRootFromPath(path: string): string {
   return candidate;
 }
 
+function resolveNearestBootstrappedGsdRoot(path: string): string | null {
+  try {
+    let dir = existsSync(path) && !statSync(path).isDirectory()
+      ? resolve(path, "..")
+      : path;
+
+    for (let i = 0; i < 30; i++) {
+      if (hasGsdBootstrapArtifacts(join(dir, ".gsd"))) return dir;
+
+      const gitPath = join(dir, ".git");
+      if (existsSync(gitPath)) return null;
+
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+    // Non-fatal: callers fall back to git root resolution.
+  }
+  return null;
+}
+
+function hasGsdBootstrapArtifacts(gsdPath: string): boolean {
+  return existsSync(gsdPath) &&
+    (existsSync(join(gsdPath, "PREFERENCES.md")) ||
+      existsSync(join(gsdPath, "preferences.md")) ||
+      existsSync(join(gsdPath, "milestones")));
+}
+
 function resolveGitWorkingTreeRoot(path: string): string | null {
   try {
     let dir = existsSync(path) && !statSync(path).isDirectory()

package/src/resources/extensions/mcp-client/index.ts

@@ -25,10 +25,10 @@ import { Client } from "@modelcontextprotocol/sdk/client";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { readFileSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { buildHttpTransportOpts } from "./auth.js";
 import type { McpHttpAuthConfig } from "./auth.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -104,7 +104,7 @@ function readConfigs(): McpServerConfig[] {
 	const configPaths = [
 		join(process.cwd(), ".mcp.json"),
 		join(process.cwd(), ".gsd", "mcp.json"),
-		join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+		join(gsdHome(), "mcp.json"),
 	];
 
 	for (const configPath of configPaths) {

package/src/resources/extensions/remote-questions/remote-command.ts

@@ -11,6 +11,7 @@ import { getGlobalGSDPreferencesPath, loadEffectiveGSDPreferences } from "../gsd
 import { getRemoteConfigStatus, isValidChannelId, resolveRemoteConfig } from "./config.js";
 import { maskEditorLine, sanitizeError } from "../shared/mod.js";
 import { getLatestPromptSummary } from "./status.js";
+import { gsdHome } from "../gsd/gsd-home.js";
 
 export async function handleRemote(
   subcommand: string,
@@ -300,7 +301,7 @@ async function promptSlackChannelId(ctx: ExtensionCommandContext): Promise<strin
 }
 
 function getAuthStorage(): AuthStorage {
-  const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+  const authPath = join(gsdHome(), "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   return AuthStorage.create(authPath);
 }

package/src/resources/extensions/remote-questions/status.ts

@@ -4,12 +4,8 @@
 
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { readPromptRecord } from "./store.js";
-
-function getGsdHome(): string {
-  return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
+import { gsdHome } from "../gsd/gsd-home.js";
 
 export interface LatestPromptSummary {
   id: string;
@@ -18,7 +14,7 @@ export interface LatestPromptSummary {
 }
 
 export function getLatestPromptSummary(): LatestPromptSummary | null {
-  const runtimeDir = join(getGsdHome(), "runtime", "remote-questions");
+  const runtimeDir = join(gsdHome(), "runtime", "remote-questions");
   if (!existsSync(runtimeDir)) return null;
   const files = readdirSync(runtimeDir).filter((f) => f.endsWith(".json"));
   if (files.length === 0) return null;

package/src/resources/extensions/remote-questions/store.ts

@@ -4,15 +4,11 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { gsdHome } from "../gsd/gsd-home.js";
 import type { RemotePrompt, RemotePromptRecord, RemotePromptRef, RemoteAnswer, RemotePromptStatus } from "./types.js";
 
-function getGsdHome(): string {
-  return process.env.GSD_HOME || join(homedir(), ".gsd");
-}
-
 function runtimeDir(): string {
-  return join(getGsdHome(), "runtime", "remote-questions");
+  return join(gsdHome(), "runtime", "remote-questions");
 }
 
 function recordPath(id: string): string {

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

@@ -10,15 +10,16 @@
  */
 
 import { AuthStorage } from '@gsd/pi-coding-agent'
-import { homedir } from 'os'
 import { join } from 'path'
 import { resolveSearchProviderFromPreferences } from '../gsd/preferences.js'
+import { gsdHome } from "../gsd/gsd-home.js";
 
-// Compute authFilePath locally instead of importing from app-paths.ts,
-// because extensions are copied to ~/.gsd/agent/extensions/ at runtime
-// where the relative import '../../../app-paths.ts' doesn't resolve.
-const gsdHome = process.env.GSD_HOME || join(homedir(), '.gsd')
-const authFilePath = join(gsdHome, 'agent', 'auth.json')
+// Compute authFilePath lazily so GSD_HOME overrides (e.g. in tests) take effect.
+// Imported locally instead of from app-paths.ts because extensions are copied to
+// ~/.gsd/agent/extensions/ at runtime where '../../../app-paths.ts' doesn't resolve.
+function authFilePath(): string {
+  return join(gsdHome(), 'agent', 'auth.json');
+}
 
 export type SearchProvider = 'tavily' | 'brave' | 'ollama'
 export type SearchProviderPreference = SearchProvider | 'auto'
@@ -57,7 +58,7 @@ export function getOllamaApiKey(): string {
  * @param authPath — Override auth.json path (for testing).
  */
 export function getSearchProviderPreference(authPath?: string): SearchProviderPreference {
-  const auth = AuthStorage.create(authPath ?? authFilePath)
+  const auth = AuthStorage.create(authPath ?? authFilePath())
   const cred = auth.get(PREFERENCE_KEY)
   if (cred?.type === 'api_key' && typeof cred.key === 'string' && VALID_PREFERENCES.has(cred.key)) {
     return cred.key as SearchProviderPreference
@@ -73,7 +74,7 @@ export function getSearchProviderPreference(authPath?: string): SearchProviderPr
  * @param authPath — Override auth.json path (for testing).
  */
 export function setSearchProviderPreference(pref: SearchProviderPreference, authPath?: string): void {
-  const auth = AuthStorage.create(authPath ?? authFilePath)
+  const auth = AuthStorage.create(authPath ?? authFilePath())
   auth.remove(PREFERENCE_KEY)
   auth.set(PREFERENCE_KEY, { type: 'api_key', key: pref })
 }

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

@@ -261,13 +261,15 @@ function writePromptToTempFile(agentName: string, prompt: string): { dir: string
 	return { dir: tmpDir, filePath };
 }
 
-function buildSubagentProcessArgs(
+export function buildSubagentProcessArgs(
 	agent: AgentConfig,
 	task: string,
 	tmpPromptPath: string | null,
+	modelOverride?: string,
 ): string[] {
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
-	if (agent.model) args.push("--model", agent.model);
+	const effectiveModel = modelOverride ?? agent.model;
+	if (effectiveModel) args.push("--model", effectiveModel);
 	if (agent.tools && agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
 	if (tmpPromptPath) args.push("--append-system-prompt", tmpPromptPath);
 	args.push(`Task: ${task}`);
@@ -337,6 +339,7 @@ async function runSingleAgent(
 	signal: AbortSignal | undefined,
 	onUpdate: OnUpdateCallback | undefined,
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
+	modelOverride?: string,
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 
@@ -382,7 +385,7 @@ async function runSingleAgent(
 		messages: [],
 		stderr: "",
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-		model: agent.model,
+		model: modelOverride ?? agent.model,
 		step,
 	};
 
@@ -401,7 +404,7 @@ async function runSingleAgent(
 			tmpPromptDir = tmp.dir;
 			tmpPromptPath = tmp.filePath;
 		}
-		const args = buildSubagentProcessArgs(agent, task, tmpPromptPath);
+		const args = buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride);
 		let wasAborted = false;
 
 		const exitCode = await new Promise<number>((resolve) => {
@@ -481,10 +484,11 @@ async function runSingleAgentInCmuxSplit(
 	signal: AbortSignal | undefined,
 	onUpdate: OnUpdateCallback | undefined,
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
+	modelOverride?: string,
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
-		return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
+		return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
 	}
 
 	let tmpPromptDir: string | null = null;
@@ -499,7 +503,7 @@ async function runSingleAgentInCmuxSplit(
 		messages: [],
 		stderr: "",
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
-		model: agent.model,
+		model: modelOverride ?? agent.model,
 		step,
 	};
 
@@ -529,12 +533,12 @@ async function runSingleAgentInCmuxSplit(
 			? await cmuxClient.createSplit(directionOrSurfaceId as "right" | "down" | "left" | "up")
 			: directionOrSurfaceId;
 		if (!cmuxSurfaceId) {
-			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
+			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
 		}
 
 		const bundledPaths = (process.env.GSD_BUNDLED_EXTENSION_PATHS ?? "").split(path.delimiter).map((s) => s.trim()).filter(Boolean);
 		const extensionArgs = bundledPaths.flatMap((p) => ["--extension", p]);
-		const processArgs = [process.env.GSD_BIN_PATH!, ...extensionArgs, ...buildSubagentProcessArgs(agent, task, tmpPromptPath)];
+		const processArgs = [process.env.GSD_BIN_PATH!, ...extensionArgs, ...buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride)];
 		// Normalize all paths to forward slashes before embedding in bash strings.
 		// On Windows, backslashes are interpreted as escape characters by bash,
 		// mangling paths like C:\Users\user into C:Useruser (#1436).
@@ -549,7 +553,7 @@ async function runSingleAgentInCmuxSplit(
 
 		const sent = await cmuxClient.sendSurface(cmuxSurfaceId, `bash -lc ${shellEscape(innerScript)}`);
 		if (!sent) {
-			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails);
+			return runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, modelOverride);
 		}
 
 		const finished = await waitForFile(exitPath, signal);
@@ -596,12 +600,14 @@ const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	model: Type.Optional(Type.String({ description: "Model override for this task (e.g. 'claude-sonnet-4-6')" })),
 });
 
 const ChainItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	model: Type.Optional(Type.String({ description: "Model override for this step (e.g. 'claude-sonnet-4-6')" })),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -619,6 +625,7 @@ const SubagentParams = Type.Object({
 		Type.Boolean({ description: "Prompt before running project-local agents. Default: false.", default: false }),
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
+	model: Type.Optional(Type.String({ description: "Model override for the subagent (e.g. 'claude-sonnet-4-6'). Takes precedence over the agent's frontmatter model." })),
 	isolated: Type.Optional(
 		Type.Boolean({
 			description:
@@ -908,6 +915,7 @@ export default function (pi: ExtensionAPI) {
 						signal,
 						chainUpdate,
 						makeDetails("chain"),
+						step.model || params.model,
 					);
 					results.push(result);
 
@@ -985,6 +993,7 @@ export default function (pi: ExtensionAPI) {
 					: [];
 				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
 					const workerId = registerWorker(t.agent, t.task, index, batchSize, batchId);
+					const taskModel = t.model || params.model;
 					const runTask = () => cmuxSplitsEnabled
 						? runSingleAgentInCmuxSplit(
 							cmuxClient,
@@ -1003,6 +1012,7 @@ export default function (pi: ExtensionAPI) {
 								}
 							},
 							makeDetails("parallel"),
+							taskModel,
 						)
 						: runSingleAgent(
 							ctx.cwd,
@@ -1019,6 +1029,7 @@ export default function (pi: ExtensionAPI) {
 								}
 							},
 							makeDetails("parallel"),
+							taskModel,
 						);
 					let result = await runTask();
 
@@ -1079,6 +1090,7 @@ export default function (pi: ExtensionAPI) {
 							signal,
 							onUpdate,
 							makeDetails("single"),
+							params.model,
 						)
 						: await runSingleAgent(
 							ctx.cwd,
@@ -1090,6 +1102,7 @@ export default function (pi: ExtensionAPI) {
 							signal,
 							onUpdate,
 							makeDetails("single"),
+							params.model,
 						);
 					finalResults = [result];
 

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

@@ -13,6 +13,7 @@ import * as path from "node:path";
 import { promisify } from "node:util";
 
 const execFile = promisify(execFileCb);
+import { gsdHome } from "../gsd/gsd-home.js";
 
 // ============================================================================
 // Types
@@ -59,10 +60,9 @@ export function encodeCwd(cwd: string): string {
 	return Buffer.from(cwd, "utf8").toString("base64url");
 }
 
-const gsdHome = process.env.GSD_HOME || path.join(os.homedir(), ".gsd");
 
 function getIsolationBaseDir(cwd: string, taskId: string): string {
-	return path.join(gsdHome, "wt", encodeCwd(cwd), taskId);
+	return path.join(gsdHome(), "wt", encodeCwd(cwd), taskId);
 }
 
 // Track active isolation dirs for cleanup on exit