gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.9d08d820b

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,6 +1,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
+import { logWarning } from "../workflow-logger.js";
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
  * and unique M001-abc123 formats. Exported so regex-hardening tests
@@ -458,6 +459,42 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
 // guards.
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+/**
+ * Canonical registry for agents that planning-dispatch may consider. Unit
+ * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
+ */
+const PLANNING_DISPATCH_AGENT_REGISTRY = {
+    scout: { readOnlySpecialist: true },
+    planner: { readOnlySpecialist: true },
+    reviewer: { readOnlySpecialist: true },
+    security: { readOnlySpecialist: true },
+    tester: { readOnlySpecialist: true },
+};
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set(Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId));
+let warnedMissingPlanningDispatchAgentClasses = false;
+function isReadOnlySpecialist(agentId) {
+    const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId];
+    return metadata?.readOnlySpecialist === true;
+}
+function allowedPlanningDispatchAgentsList() {
+    return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}
+function warnMissingPlanningDispatchAgentClasses(unitType, mode, toolName) {
+    if (warnedMissingPlanningDispatchAgentClasses)
+        return;
+    warnedMissingPlanningDispatchAgentClasses = true;
+    // TODO(#5060): Remove this migration shim once all subagent/task callers are verified to forward agent identities.
+    const message = `[write-gate] planning-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
+        `on unit "${unitType}" without agentClasses - stale caller; blocking dispatch.`;
+    console.warn(message);
+    logWarning("intercept", message, {
+        unitType,
+        mode,
+        toolName,
+    });
+}
 /**
  * Read-only / planning-safe tools that any non-"all" mode allows. Mirrors
  * QUEUE_SAFE_TOOLS / GATE_SAFE_TOOLS but is the inclusive default for
@@ -501,6 +538,10 @@ function blockReason(unitType, mode, what) {
  *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
  *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
  *                    bash that isn't read-only, and subagent dispatch.
+ *   - "planning-dispatch"
+ *                  → like "planning", but permits subagent dispatch only
+ *                    when every forwarded agent class is globally allowed
+ *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *
@@ -510,8 +551,13 @@ function blockReason(unitType, mode, what) {
  * `policy` of null means "no manifest resolved" — pass-through. Callers
  * that have no active unit (interactive sessions) pass null and this
  * predicate is a no-op.
+ *
+ * `agentClasses` is supplied by the tool hook for subagent-shaped calls. If
+ * absent, planning-dispatch fails closed so stale callers cannot silently
+ * bypass the agent allowlists. An explicitly supplied-but-empty list is
+ * allowed through so the downstream tool call can reject the malformed input.
  */
-export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy) {
+export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy, agentClasses) {
     if (!policy)
         return { block: false };
     if (policy.mode === "all")
@@ -529,12 +575,48 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         // Unknown tool in read-only mode — block by default.
         return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
     }
-    // planning / docs modes share the same surface for safe tools, bash, and subagent.
+    // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
     if (PLANNING_SAFE_TOOLS.has(tool))
         return { block: false };
     if (tool.startsWith("gsd_"))
         return { block: false };
     if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+        if (policy.mode === "planning-dispatch") {
+            const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
+            const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+            const allowed = new Set(allowedSubagents);
+            // When agentClasses is undefined, the caller has not been updated to extract
+            // agent identities yet. Block and warn so stale callers surface in telemetry
+            // instead of silently bypassing the gate.
+            if (agentClasses === undefined) {
+                warnMissingPlanningDispatchAgentClasses(unitType, policy.mode, tool);
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`),
+                };
+            }
+            // agentClasses was explicitly provided but resolved to an empty list (for
+            // example, a bare tool call with no agent field). Pass through; no agents
+            // to validate means the downstream tool call itself will fail.
+            if (requested.length === 0) {
+                return { block: false };
+            }
+            const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
+            if (globallyDisallowed) {
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`),
+                };
+            }
+            const disallowedByPolicy = requested.find(a => !allowed.has(a));
+            if (disallowedByPolicy) {
+                return {
+                    block: true,
+                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`),
+                };
+            }
+            return { block: false };
+        }
         return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
     }
     if (tool === "bash") {

package/dist/resources/extensions/gsd/commands-config.js

@@ -6,6 +6,7 @@
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { getHomeDir } from "./home-dir.js";
 /**
  * Tool API key configurations.
  * This is the source of truth for tool credentials - used by both the config wizard
@@ -29,7 +30,7 @@ function getStoredToolKey(auth, providerId) {
  */
 export function loadToolApiKeys() {
     try {
-        const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+        const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
         if (!existsSync(authPath))
             return;
         const auth = AuthStorage.create(authPath);
@@ -45,7 +46,7 @@ export function loadToolApiKeys() {
     }
 }
 export function getConfigAuthStorage() {
-    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
     mkdirSync(dirname(authPath), { recursive: true });
     return AuthStorage.create(authPath);
 }

package/dist/resources/extensions/gsd/commands-extensions.js

@@ -10,7 +10,50 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { lockSync, unlockSync } from "proper-lockfile";
-import semver from "semver";
+/**
+ * Strict numeric comparison of two npm-style version strings.
+ *
+ * Returns true when `a` is strictly greater than `b`. Compares the dotted
+ * release components numerically (so `1.10.0` > `1.9.0`) and treats any
+ * prerelease suffix (`-beta.1`, `-rc.2`) as less than the equivalent
+ * release version (`1.0.0` > `1.0.0-beta.1`). Sufficient for npm package
+ * version comparison in the extension installer; we don't need the full
+ * semver range/intersect machinery here.
+ *
+ * Replaces the earlier `import semver from "semver"` — that import broke
+ * `tsc -p tsconfig.json` whenever `@types/semver` failed to install
+ * (Issue #4946) because the file is pulled in transitively despite being
+ * under the `src/resources` exclude.
+ */
+export function isVersionGreater(a, b) {
+    const split = (v) => {
+        const dash = v.indexOf("-");
+        const release = (dash === -1 ? v : v.slice(0, dash))
+            .split(".")
+            .map(part => Number.parseInt(part, 10) || 0);
+        const pre = dash === -1 ? null : v.slice(dash + 1);
+        return { release, pre };
+    };
+    const sa = split(a);
+    const sb = split(b);
+    const len = Math.max(sa.release.length, sb.release.length);
+    for (let i = 0; i < len; i++) {
+        const ai = sa.release[i] ?? 0;
+        const bi = sb.release[i] ?? 0;
+        if (ai !== bi)
+            return ai > bi;
+    }
+    // Release components equal — a release version beats any prerelease,
+    // and prerelease strings are compared lexicographically (good enough
+    // for `beta.1` vs `beta.2`, the only realistic case here).
+    if (sa.pre === null && sb.pre !== null)
+        return true;
+    if (sa.pre !== null && sb.pre === null)
+        return false;
+    if (sa.pre !== null && sb.pre !== null)
+        return sa.pre > sb.pre;
+    return false;
+}
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 // ─── Registry I/O ───────────────────────────────────────────────────────────
 function getRegistryPath() {
@@ -413,7 +456,7 @@ async function updateSingleExtension(id, registry, ctx) {
         ctx.ui.notify(`Could not fetch latest version for "${id}".`, "warning");
         return;
     }
-    if (semver.gt(latest, current)) {
+    if (isVersionGreater(latest, current)) {
         ctx.ui.notify(`Updating "${id}": v${current} → v${latest}...`, "info");
         await handleInstall(packageName, ctx);
     }
@@ -464,7 +507,7 @@ async function updateAllExtensions(registry, ctx) {
             skipped++;
             continue;
         }
-        if (semver.gt(latest, current)) {
+        if (isVersionGreater(latest, current)) {
             ctx.ui.notify(`  ${entry.id}: v${current} → v${latest} (updating)`, "info");
             await handleInstall(packageName, ctx);
             updated++;

package/dist/resources/extensions/gsd/commands-handlers.js

@@ -9,6 +9,7 @@ import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
+import { getHomeDir } from "./home-dir.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import { formatDoctorIssuesForPrompt, formatDoctorReport, formatDoctorReportJson, runGSDDoctor, selectDoctorScope, filterDoctorIssues, } from "./doctor.js";
@@ -60,7 +61,7 @@ async function fetchLatestVersionForCommand() {
     }
 }
 export function dispatchDoctorHeal(pi, scope, reportText, structuredIssues) {
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     const prompt = loadPrompt("doctor-heal", {
         doctorSummary: reportText,
@@ -210,7 +211,7 @@ export async function handleTriage(ctx, pi, basePath) {
         currentPlan: currentPlan || "(no active slice plan)",
         roadmapContext: roadmapContext || "(no active roadmap)",
     });
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     pi.sendMessage({
         customType: "gsd-triage",

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -165,6 +165,12 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 
+- `reactive_execution`: controls automatic parallel task dispatch inside a slice. Reactive execution is enabled by default when omitted; set `enabled: false` to opt out. With default-on behavior, GSD only attempts a reactive batch when at least three ready tasks are available and the task-plan IO graph is non-ambiguous. If you set `enabled: true` explicitly, GSD uses the earlier opt-in threshold of two ready tasks. Keys:
+  - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
+  - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
+  - `isolation_mode`: `"same-tree"` — currently the only supported value.
+  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
   - `channel_id`: string or number — channel ID.

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -16,6 +16,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
+import { getHomeDir } from "./home-dir.js";
 // ── Provider routing constants ────────────────────────────────────────────────
 /**
  * Providers that use external CLI authentication (not API keys).
@@ -158,7 +159,7 @@ function isCliBinaryInPath(providerId) {
     return pathDirs.some(dir => executableNames.some(name => existsSync(join(dir, name))));
 }
 function modelsJsonPaths() {
-    const home = process.env.HOME ?? "~";
+    const home = getHomeDir();
     return [
         join(home, ".gsd", "agent", "models.json"),
         // Keep parity with custom-provider discovery during auto bootstrap.

package/dist/resources/extensions/gsd/forensics.js

@@ -10,7 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { getHomeDir } from "./home-dir.js";
 import { extractTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
 import { MAX_JSONL_BYTES, parseJSONL } from "./jsonl-utils.js";
@@ -135,7 +135,7 @@ export async function handleForensics(args, ctx, pi) {
     // when import.meta.url resolves to the npm-global install path (Windows).
     let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
     if (!existsSync(join(gsdSourceDir, "prompts"))) {
-        const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+        const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
         const fallback = join(gsdHome, "agent", "extensions", "gsd");
         if (existsSync(join(fallback, "prompts")))
             gsdSourceDir = fallback;
@@ -1109,11 +1109,13 @@ function formatReportForPrompt(report) {
 // ─── Redaction ────────────────────────────────────────────────────────────────
 function redactForGitHub(text, basePath) {
     let result = text;
+    // Build regex that matches both / and \ separator variants (Windows)
+    // Normalize to / first, escape for regex, then replace each / with [/\\]
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pathRe = (p) => new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
     // Replace absolute paths
-    result = result.replaceAll(basePath, ".");
-    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-    if (home)
-        result = result.replaceAll(home, "~");
+    result = result.replace(pathRe(basePath), ".");
+    result = result.replace(pathRe(getHomeDir()), "~");
     // Strip API key patterns
     result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");
     result = result.replace(/Bearer\s+\S+/g, "Bearer ***");

package/dist/resources/extensions/gsd/guided-flow.js

@@ -18,6 +18,7 @@ import { clearLock } from "./crash-recovery.js";
 import { assessInterruptedSession, formatInterruptedSessionRunningMessage, formatInterruptedSessionSummary, } from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
+import { getHomeDir } from "./home-dir.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
@@ -495,7 +496,7 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
             removed: currentTools.length - scopedTools.length,
         });
     }
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     pi.sendMessage({
         customType,

package/dist/resources/extensions/gsd/home-dir.js

@@ -0,0 +1,16 @@
+/**
+ * Cross-platform home directory resolution.
+ *
+ * `process.env.HOME` is not set on Windows (CMD/PowerShell).
+ * Falls back to USERPROFILE, then os.homedir(), then throws.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+export function getHomeDir() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    if (!home) {
+        throw new Error("Cannot resolve home directory. Set HOME or USERPROFILE environment variable.");
+    }
+    return home;
+}

package/dist/resources/extensions/gsd/key-manager.js

@@ -9,6 +9,7 @@ import { existsSync, statSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdirSync } from "node:fs";
 import { getErrorMessage } from "./error-utils.js";
+import { getHomeDir } from "./home-dir.js";
 export const PROVIDER_REGISTRY = [
     // LLM Providers
     { id: "anthropic", label: "Anthropic (Claude)", category: "llm", envVar: "ANTHROPIC_API_KEY", prefixes: ["sk-ant-"], hasOAuth: true, dashboardUrl: "console.anthropic.com" },
@@ -98,7 +99,7 @@ export function describeCredential(cred) {
  * Get the auth.json path.
  */
 export function getAuthPath() {
-    return join(process.env.HOME ?? "~", ".gsd", "agent", "auth.json");
+    return join(getHomeDir(), ".gsd", "agent", "auth.json");
 }
 /**
  * Create an AuthStorage instance for key management.

package/dist/resources/extensions/gsd/migrate/command.js

@@ -13,6 +13,7 @@ import { resolve, join, dirname } from "node:path";
 import { gsdRoot } from "../paths.js";
 import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/tui.js";
+import { getHomeDir } from "../home-dir.js";
 import { validatePlanningDirectory, parsePlanningDirectory, transformToGSD, generatePreview, writeGSDDirectory, } from "./index.js";
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview) {
@@ -50,10 +51,10 @@ export async function handleMigrate(args, ctx, pi) {
     // Default to cwd when no args given; expand ~ to HOME
     let rawPath = args.trim() || ".";
     if (rawPath.startsWith("~/")) {
-        rawPath = join(process.env.HOME ?? "~", rawPath.slice(2));
+        rawPath = join(getHomeDir(), rawPath.slice(2));
     }
     else if (rawPath === "~") {
-        rawPath = process.env.HOME ?? "~";
+        rawPath = getHomeDir();
     }
     let sourcePath = resolve(process.cwd(), rawPath);
     if (!sourcePath.endsWith(".planning")) {

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
+- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

package/dist/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.

package/dist/resources/extensions/gsd/prompts/refine-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 ## Your Role in the Pipeline
 
+### Delegate Recon When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate recon and sub-decomposition. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem touched by the sketch → dispatch the **scout** agent and work from its compressed report.
+- A specific area of the refinement needs deeper architectural analysis → dispatch the **planner** agent for a focused sub-plan, then integrate.
+- You need current external information (library docs, API behavior) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) — they would write user source and bypass write isolation. Implementation belongs in `execute-task`.
+
 ### Respect the Sketch Scope
 
 The sketch scope inlined above is a **hard constraint**. Plan within it. If, after exploring the codebase, the scope is too narrow to deliver the goal, surface this as a deviation in the plan's narrative and still produce the plan — do not silently expand the scope.

package/dist/resources/extensions/gsd/unit-context-manifest.js

@@ -73,6 +73,18 @@ const COMMON_BUDGET_SMALL = 250_000; // ~65K tokens
 // allowed-path set for the docs policy lives in one reviewable place.
 const TOOLS_ALL = { mode: "all" };
 const TOOLS_PLANNING = { mode: "planning" };
+// Like TOOLS_PLANNING but permits dispatch to read-only recon/planning
+// specialists. Runtime-enforced by write-gate.ts before the subagent tool runs.
+const TOOLS_PLANNING_DISPATCH_RECON = {
+    mode: "planning-dispatch",
+    allowedSubagents: ["scout", "planner"],
+};
+// Like TOOLS_PLANNING_DISPATCH_RECON, but for closeout units that fan out
+// verification work to review-tier specialists.
+const TOOLS_PLANNING_DISPATCH_REVIEW = {
+    mode: "planning-dispatch",
+    allowedSubagents: ["reviewer", "security", "tester"],
+};
 const TOOLS_DOCS = {
     mode: "docs",
     // Globs are resolved relative to project basePath. The set is intentionally
@@ -177,7 +189,11 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: false,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // planning-dispatch: completion is a high-leverage place to fan out to
+        // reviewer / security / tester subagents. They read the diff and report
+        // findings; they do not write user source. Write isolation to .gsd/ is
+        // preserved.
+        tools: TOOLS_PLANNING_DISPATCH_REVIEW,
         artifacts: {
             // #4780 landed slice-summary as excerpt for this unit; phase 2 of
             // the architecture will read this manifest as the source of truth
@@ -209,7 +225,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: true,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // planning-dispatch: allows subagent dispatch so the planner can fan out
+        // to scout for codebase recon and to planner/decompose-style specialists
+        // for sub-decomposition. Write-isolation to .gsd/ is preserved.
+        tools: TOOLS_PLANNING_DISPATCH_RECON,
         artifacts: {
             inline: ["roadmap", "slice-research", "dependency-summaries", "requirements", "decisions", "templates"],
             excerpt: [],
@@ -223,7 +242,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: true,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // See plan-slice — same rationale: dispatch to scout/planner-style
+        // specialists during refinement is materially better than re-doing recon
+        // inline.
+        tools: TOOLS_PLANNING_DISPATCH_RECON,
         artifacts: {
             inline: ["slice-plan", "slice-research", "dependency-summaries", "templates"],
             excerpt: [],
@@ -251,7 +273,10 @@ export const UNIT_MANIFESTS = {
         memory: "prompt-relevant",
         codebaseMap: false,
         preferences: "active-only",
-        tools: TOOLS_PLANNING,
+        // See complete-milestone — same rationale: dispatch to reviewer / security /
+        // tester subagents to fan out review work without bloating this unit's
+        // context.
+        tools: TOOLS_PLANNING_DISPATCH_REVIEW,
         artifacts: {
             // Phase 3 migration (#4782): matches today's actual
             // buildCompleteSlicePrompt inlining order. Overrides prepend +

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -21,6 +21,7 @@ import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERRO
 import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
+import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -29,6 +30,14 @@ function normalizePathForComparison(path) {
         .replace(/\/+$/, "");
     return process.platform === "win32" ? normalized.toLowerCase() : normalized;
 }
+function normalizeBasePathForWorktreeOps(basePath) {
+    const resolved = resolveWorktreeProjectRoot(basePath);
+    if (isGsdWorktreePath(basePath) &&
+        normalizeWorktreePathForCompare(resolved) === normalizeWorktreePathForCompare(basePath)) {
+        throw new GSDError(GSD_GIT_ERROR, `Cannot resolve project root from worktree path: ${basePath}. Run the command from the project root or set GSD_PROJECT_ROOT.`);
+    }
+    return resolved;
+}
 // ─── resolveGitDir ─────────────────────────────────────────────────────────
 /**
  * Resolve the actual git directory for a given repository path.
@@ -61,7 +70,7 @@ export function resolveGitDir(basePath) {
     return gitPath;
 }
 export function worktreesDir(basePath) {
-    return join(basePath, ".gsd", "worktrees");
+    return join(resolveWorktreeProjectRoot(basePath), ".gsd", "worktrees");
 }
 export function worktreePath(basePath, name) {
     return join(worktreesDir(basePath), name);
@@ -143,6 +152,7 @@ export function resolveCanonicalMilestoneRoot(basePath, milestoneId) {
  * @param opts.branch — override the default `worktree/<name>` branch name
  */
 export function createWorktree(basePath, name, opts = {}) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     // Validate name: alphanumeric, hyphens, underscores only
     if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
         throw new GSDError(GSD_PARSE_ERROR, `Invalid worktree name "${name}". Use only letters, numbers, hyphens, and underscores.`);
@@ -227,6 +237,7 @@ export function createWorktree(basePath, name, opts = {}) {
  * Uses native worktree list and filters to those under .gsd/worktrees/.
  */
 export function listWorktrees(basePath) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const baseVariants = [resolve(basePath)];
     if (existsSync(basePath)) {
         baseVariants.push(realpathSync(basePath));
@@ -366,6 +377,7 @@ export function findNestedGitDirs(rootPath) {
  * If the process is currently inside the worktree, chdir out first.
  */
 export function removeWorktree(basePath, name, opts = {}) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     let wtPath = worktreePath(basePath, name);
     const branch = opts.branch ?? worktreeBranchName(name);
     const { deleteBranch = true, force = true } = opts;
@@ -614,6 +626,7 @@ function parseDiffNameStatus(entries) {
  * Returns a summary of added, modified, and removed GSD artifacts.
  */
 export function diffWorktreeGSD(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch, ".gsd/", true);
@@ -626,6 +639,7 @@ export function diffWorktreeGSD(basePath, name) {
  * content, this correctly returns an empty diff.
  */
 export function diffWorktreeAll(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const entries = nativeDiffNameStatus(basePath, mainBranch, branch);
@@ -636,6 +650,7 @@ export function diffWorktreeAll(basePath, name) {
  * Uses direct diff (not merge-base) so the preview matches the actual merge outcome.
  */
 export function diffWorktreeNumstat(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const rawStats = nativeDiffNumstat(basePath, mainBranch, branch);
@@ -652,6 +667,7 @@ export function diffWorktreeNumstat(basePath, name) {
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeGSDDiff(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, ".gsd/", undefined, true);
@@ -661,6 +677,7 @@ export function getWorktreeGSDDiff(basePath, name) {
  * Returns the raw unified diff for LLM consumption.
  */
 export function getWorktreeCodeDiff(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     return nativeDiffContent(basePath, mainBranch, branch, undefined, ".gsd/", true);
@@ -669,6 +686,7 @@ export function getWorktreeCodeDiff(basePath, name) {
  * Get commit log for the worktree branch since it diverged from main.
  */
 export function getWorktreeLog(basePath, name) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const entries = nativeLogOneline(basePath, mainBranch, branch);
@@ -680,6 +698,7 @@ export function getWorktreeLog(basePath, name) {
  * Returns the merge commit message.
  */
 export function mergeWorktreeToMain(basePath, name, commitMessage) {
+    basePath = normalizeBasePathForWorktreeOps(basePath);
     const branch = worktreeBranchName(name);
     const mainBranch = nativeDetectMainBranch(basePath);
     const current = nativeGetCurrentBranch(basePath);