gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

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

@@ -0,0 +1,309 @@
+// GSD-2 — In-TUI handler for /gsd worktree commands (list, merge, clean, remove).
+//
+// Mirrors the CLI subcommands in src/worktree-cli.ts but emits results via
+// ctx.ui.notify() instead of writing colored output to stderr. Reuses the
+// same extension modules (worktree-manager, native-git-bridge, etc.) so the
+// behavior is identical to the CLI surface.
+import { existsSync } from "node:fs";
+import { projectRoot } from "./commands/context.js";
+import { listWorktrees, removeWorktree, mergeWorktreeToMain, diffWorktreeAll, diffWorktreeNumstat, worktreeBranchName, } from "./worktree-manager.js";
+import { nativeHasChanges, nativeDetectMainBranch, nativeCommitCountBetween, } from "./native-git-bridge.js";
+import { inferCommitType } from "./git-service.js";
+import { autoCommitCurrentBranch } from "./worktree.js";
+import { GSDError, GSD_GIT_ERROR } from "./errors.js";
+// ─── Status helper ─────────────────────────────────────────────────────────
+function getStatus(basePath, name, wtPath) {
+    const diff = diffWorktreeAll(basePath, name);
+    const numstat = diffWorktreeNumstat(basePath, name);
+    const filesChanged = diff.added.length + diff.modified.length + diff.removed.length;
+    let linesAdded = 0;
+    let linesRemoved = 0;
+    for (const s of numstat) {
+        linesAdded += s.added;
+        linesRemoved += s.removed;
+    }
+    let uncommitted = false;
+    try {
+        uncommitted = existsSync(wtPath) && nativeHasChanges(wtPath);
+    }
+    catch {
+        // native check failure → treat as clean for display purposes
+    }
+    let commits = 0;
+    try {
+        const main = nativeDetectMainBranch(basePath);
+        commits = nativeCommitCountBetween(basePath, main, worktreeBranchName(name));
+    }
+    catch {
+        // commit count unavailable → leave at 0
+    }
+    return {
+        name,
+        path: wtPath,
+        branch: worktreeBranchName(name),
+        exists: existsSync(wtPath),
+        filesChanged,
+        linesAdded,
+        linesRemoved,
+        uncommitted,
+        commits,
+    };
+}
+// ─── Formatters (exported for tests) ────────────────────────────────────────
+export function formatWorktreeList(statuses) {
+    if (statuses.length === 0) {
+        return "No worktrees.\n\nCreate one from the CLI: gsd -w <name>";
+    }
+    const lines = [`Worktrees — ${statuses.length}`, ""];
+    for (const s of statuses) {
+        const badge = s.uncommitted
+            ? "(uncommitted)"
+            : s.filesChanged > 0
+                ? "(unmerged)"
+                : "(clean)";
+        lines.push(`  ${s.name} ${badge}`);
+        lines.push(`    branch  ${s.branch}`);
+        lines.push(`    path    ${s.path}`);
+        if (s.filesChanged > 0) {
+            lines.push(`    diff    ${s.filesChanged} file${s.filesChanged === 1 ? "" : "s"}, +${s.linesAdded} -${s.linesRemoved}, ${s.commits} commit${s.commits === 1 ? "" : "s"}`);
+        }
+        lines.push("");
+    }
+    lines.push("Commands:");
+    lines.push("  /gsd worktree merge <name>   Merge into main and clean up");
+    lines.push("  /gsd worktree remove <name>  Remove a worktree (--force to skip safety checks)");
+    lines.push("  /gsd worktree clean          Remove all merged/empty worktrees");
+    return lines.join("\n");
+}
+export function formatCleanKeepReason(status) {
+    if (!status.exists) {
+        return "directory missing — run 'git worktree prune' to unregister";
+    }
+    if (status.filesChanged > 0) {
+        return `${status.filesChanged} changed file${status.filesChanged === 1 ? "" : "s"}${status.uncommitted ? ", uncommitted" : ""}`;
+    }
+    return "uncommitted changes";
+}
+// ─── Subcommand: list ───────────────────────────────────────────────────────
+async function handleList(ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    const statuses = worktrees.map((wt) => getStatus(basePath, wt.name, wt.path));
+    ctx.ui.notify(formatWorktreeList(statuses), "info");
+}
+// ─── Subcommand: merge ──────────────────────────────────────────────────────
+async function handleMerge(args, ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    const trimmed = args.trim();
+    let target = trimmed;
+    if (!target) {
+        if (worktrees.length === 1) {
+            target = worktrees[0].name;
+        }
+        else if (worktrees.length === 0) {
+            ctx.ui.notify("No worktrees to merge.", "info");
+            return;
+        }
+        else {
+            const names = worktrees.map((w) => w.name).join(", ");
+            ctx.ui.notify(`Usage: /gsd worktree merge <name>\n\nWorktrees: ${names}`, "warning");
+            return;
+        }
+    }
+    const wt = worktrees.find((w) => w.name === target);
+    if (!wt) {
+        const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+        ctx.ui.notify(`Worktree "${target}" not found.\n\nAvailable: ${available}`, "error");
+        return;
+    }
+    const status = getStatus(basePath, target, wt.path);
+    if (status.filesChanged === 0 && !status.uncommitted) {
+        try {
+            removeWorktree(basePath, target, { deleteBranch: true });
+            ctx.ui.notify(`Removed empty worktree ${target}.`, "info");
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify(`Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`, "error");
+        }
+        return;
+    }
+    if (status.uncommitted) {
+        try {
+            autoCommitCurrentBranch(wt.path, "worktree-merge", target);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            ctx.ui.notify([
+                `Auto-commit before merge failed: ${msg}`,
+                "",
+                `Commit or stash changes in ${wt.path}, then re-run /gsd worktree merge ${target}.`,
+            ].join("\n"), "error");
+            return;
+        }
+    }
+    const commitType = inferCommitType(target);
+    const mainBranch = nativeDetectMainBranch(basePath);
+    const commitMessage = `${commitType}: merge worktree ${target}\n\nGSD-Worktree: ${target}`;
+    try {
+        mergeWorktreeToMain(basePath, target, commitMessage);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err instanceof GSDError && err.code === GSD_GIT_ERROR) {
+            ctx.ui.notify(`Merge requires the main branch to be checked out: ${msg}\n\nSwitch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then re-run /gsd worktree merge ${target}.`, "error");
+        }
+        else {
+            ctx.ui.notify(`Merge failed: ${msg}\n\nResolve conflicts manually, then run /gsd worktree merge ${target} again.`, "error");
+        }
+        return;
+    }
+    const successLines = [
+        `Merged ${target} → ${mainBranch}`,
+        `  ${status.filesChanged} file${status.filesChanged === 1 ? "" : "s"}, +${status.linesAdded} -${status.linesRemoved}`,
+        `  commit: ${commitMessage.split("\n")[0]}`,
+    ];
+    try {
+        removeWorktree(basePath, target, { deleteBranch: true });
+        ctx.ui.notify(successLines.join("\n"), "info");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const cleanupLines = [
+            ...successLines,
+            "",
+            `Cleanup failed after the merge succeeded: ${msg}`,
+            err instanceof GSDError && err.code === GSD_GIT_ERROR
+                ? `Switch to ${mainBranch} (e.g. 'git checkout ${mainBranch}'), then remove the worktree manually with /gsd worktree remove ${target} --force.`
+                : `Remove the worktree manually with /gsd worktree remove ${target} --force, or run 'git worktree prune' to clean up dangling registrations.`,
+        ];
+        ctx.ui.notify(cleanupLines.join("\n"), "warning");
+    }
+}
+// ─── Subcommand: clean ──────────────────────────────────────────────────────
+async function handleClean(ctx) {
+    const basePath = projectRoot();
+    const worktrees = listWorktrees(basePath);
+    if (worktrees.length === 0) {
+        ctx.ui.notify("No worktrees to clean.", "info");
+        return;
+    }
+    const removed = [];
+    const kept = [];
+    for (const wt of worktrees) {
+        const status = getStatus(basePath, wt.name, wt.path);
+        if (status.filesChanged === 0 && !status.uncommitted) {
+            try {
+                removeWorktree(basePath, wt.name, { deleteBranch: true });
+                removed.push(wt.name);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                kept.push(`${wt.name} (failed: ${msg})`);
+            }
+        }
+        else {
+            const reason = formatCleanKeepReason(status);
+            kept.push(`${wt.name} (${reason})`);
+        }
+    }
+    const lines = [`Cleaned ${removed.length} worktree${removed.length === 1 ? "" : "s"}.`];
+    if (removed.length > 0) {
+        lines.push("", "Removed:");
+        for (const n of removed)
+            lines.push(`  ✓ ${n}`);
+    }
+    if (kept.length > 0) {
+        lines.push("", "Kept:");
+        for (const n of kept)
+            lines.push(`  ─ ${n}`);
+    }
+    ctx.ui.notify(lines.join("\n"), "info");
+}
+// ─── Subcommand: remove ─────────────────────────────────────────────────────
+async function handleRemove(args, ctx) {
+    const basePath = projectRoot();
+    const tokens = args.trim().split(/\s+/).filter(Boolean);
+    const force = tokens.includes("--force");
+    const name = tokens.find((t) => t !== "--force");
+    if (!name) {
+        ctx.ui.notify("Usage: /gsd worktree remove <name> [--force]", "warning");
+        return;
+    }
+    const worktrees = listWorktrees(basePath);
+    const wt = worktrees.find((w) => w.name === name);
+    if (!wt) {
+        const available = worktrees.map((w) => w.name).join(", ") || "(none)";
+        ctx.ui.notify(`Worktree "${name}" not found.\n\nAvailable: ${available}`, "error");
+        return;
+    }
+    const status = getStatus(basePath, name, wt.path);
+    if ((status.filesChanged > 0 || status.uncommitted) && !force) {
+        ctx.ui.notify([
+            `Worktree "${name}" has pending changes (${formatCleanKeepReason(status)}).`,
+            "",
+            `  Merge first:     /gsd worktree merge ${name}`,
+            `  Or force-remove: /gsd worktree remove ${name} --force`,
+        ].join("\n"), "warning");
+        return;
+    }
+    try {
+        removeWorktree(basePath, name, { deleteBranch: true });
+        ctx.ui.notify(`Removed worktree ${name}.`, "info");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Worktree partially removed: ${msg}\n\nRun 'git worktree prune' to clean up any dangling registrations.`, "error");
+    }
+}
+// ─── Help text ──────────────────────────────────────────────────────────────
+const HELP_TEXT = [
+    "Usage: /gsd worktree <command> [args]",
+    "",
+    "Commands:",
+    "  list                       Show all worktrees with status",
+    "  merge [name]               Merge a worktree into main, then remove it",
+    "  remove <name> [--force]    Remove a worktree (refuses unmerged changes without --force)",
+    "  clean                      Remove all merged/empty worktrees",
+    "",
+    "The -w flag (CLI only) creates/resumes worktrees on session start:",
+    "  gsd -w               Auto-name a new worktree, or resume the only active one",
+    "  gsd -w my-feature    Create or resume a named worktree",
+].join("\n");
+// ─── Dispatcher ─────────────────────────────────────────────────────────────
+export async function handleWorktree(args, ctx) {
+    const trimmed = args.trim();
+    const lowered = trimmed.toLowerCase();
+    if (!lowered || lowered === "help" || lowered === "--help" || lowered === "-h") {
+        ctx.ui.notify(HELP_TEXT, "info");
+        return;
+    }
+    try {
+        if (lowered === "list" || lowered === "ls") {
+            await handleList(ctx);
+            return;
+        }
+        if (lowered === "merge" || lowered.startsWith("merge ")) {
+            await handleMerge(trimmed.replace(/^merge\s*/i, ""), ctx);
+            return;
+        }
+        if (lowered === "clean") {
+            await handleClean(ctx);
+            return;
+        }
+        if (lowered === "remove" ||
+            lowered.startsWith("remove ") ||
+            lowered === "rm" ||
+            lowered.startsWith("rm ")) {
+            const stripped = trimmed.replace(/^(remove|rm)\s*/i, "");
+            await handleRemove(stripped, ctx);
+            return;
+        }
+        ctx.ui.notify(`Unknown worktree command: ${trimmed}\n\n${HELP_TEXT}`, "warning");
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Worktree command failed: ${msg}`, "error");
+    }
+}

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 +