gsd-pi 2.78.0 → 2.78.1-dev.84a383f51

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -1,22 +1,14 @@
 import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
-import { getEcosystemReadyPromise } from "../ecosystem/loader.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { buildBeforeAgentStartResult } from "./system-context.js";
-import { handleAgentEnd } from "./agent-end-recovery.js";
-import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
-import { cleanupQuickBranch } from "../quick.js";
-import { getDiscussionMilestoneId } from "../guided-flow.js";
-import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
-import { deriveState } from "../state.js";
-import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
-import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
+import { getAutoRuntimeSnapshot, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
-import { resetAskUserQuestionsCache } from "../../ask-user-questions.js";
 import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
 import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
@@ -24,26 +16,52 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
-import { initHealthWidget } from "../health-widget.js";
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
+async function deriveGsdState(basePath) {
+    const { deriveState } = await import("../state.js");
+    return deriveState(basePath);
+}
+async function getDiscussionMilestoneIdFor(basePath) {
+    const { getDiscussionMilestoneId } = await import("../guided-flow.js");
+    return getDiscussionMilestoneId(basePath);
+}
+async function loadToolApiKeysForSession() {
+    const { loadToolApiKeys } = await import("../commands-config.js");
+    loadToolApiKeys();
+}
+async function resetAskUserQuestionsTurnCache() {
+    const { resetAskUserQuestionsCache } = await import("../../ask-user-questions.js");
+    resetAskUserQuestionsCache();
+}
 async function syncServiceTierStatus(ctx) {
     const { getEffectiveServiceTier, formatServiceTierFooterStatus } = await import("../service-tier.js");
     ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
 }
+async function applyDisabledModelProviderPolicy(ctx) {
+    try {
+        const { resolveDisabledModelProvidersFromPreferences } = await import("../preferences.js");
+        ctx.modelRegistry.setDisabledModelProviders(resolveDisabledModelProvidersFromPreferences());
+    }
+    catch {
+        // Non-fatal: keep default provider visibility if preferences cannot be loaded.
+    }
+}
 export function registerHooks(pi, ecosystemHandlers) {
     pi.on("session_start", async (_event, ctx) => {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
         initNotificationWidget(ctx);
         if (!isAutoActive()) {
+            const { initHealthWidget } = await import("../health-widget.js");
             initHealthWidget(ctx);
         }
         resetWriteGateState();
         resetToolCallLoopGuard();
-        resetAskUserQuestionsCache();
+        await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
+        await applyDisabledModelProviderPolicy(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
         const { isInAutoWorktree } = await import("../auto-worktree.js");
         if (!isInAutoWorktree(process.cwd())) {
@@ -79,7 +97,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
             catch { /* non-fatal */ }
         }
-        loadToolApiKeys();
+        await loadToolApiKeysForSession();
         if (isAutoActive()) {
             ctx.ui.setWidget("gsd-health", undefined);
         }
@@ -89,9 +107,10 @@ export function registerHooks(pi, ecosystemHandlers) {
         installNotifyInterceptor(ctx);
         resetWriteGateState();
         resetToolCallLoopGuard();
-        resetAskUserQuestionsCache();
+        await resetAskUserQuestionsTurnCache();
         clearDiscussionFlowState();
         await syncServiceTierStatus(ctx);
+        await applyDisabledModelProviderPolicy(ctx);
         // Skip MCP auto-prep when running inside an auto-worktree. The worktree
         // already has .mcp.json from createAutoWorktree, and re-running the writer
         // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
@@ -101,20 +120,26 @@ export function registerHooks(pi, ecosystemHandlers) {
             const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
             prepareWorkflowMcpForProject(ctx, process.cwd());
         }
-        loadToolApiKeys();
-        if (isAutoActive()) {
+        await loadToolApiKeysForSession();
+        if (!isAutoActive()) {
+            const { initHealthWidget } = await import("../health-widget.js");
+            initHealthWidget(ctx);
+        }
+        else {
             ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
         // Wait for ecosystem loader to finish (no-op after first turn).
+        const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
         // GSD's own context injection (existing behavior — unchanged).
+        const { buildBeforeAgentStartResult } = await import("./system-context.js");
         const gsdResult = await buildBeforeAgentStartResult(event, ctx);
         // Refresh the snapshot used by ecosystem getPhase()/getActiveUnit().
         // deriveState has its own ~100ms cache so this is cheap on repeat calls.
         try {
-            const state = await deriveState(process.cwd());
+            const state = await deriveGsdState(process.cwd());
             updateSnapshot(state);
         }
         catch {
@@ -148,7 +173,8 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("agent_end", async (event, ctx) => {
         resetToolCallLoopGuard();
-        resetAskUserQuestionsCache();
+        await resetAskUserQuestionsTurnCache();
+        const { handleAgentEnd } = await import("./agent-end-recovery.js");
         await handleAgentEnd(pi, event, ctx);
     });
     // Squash-merge quick-task branch back to the original branch after the
@@ -156,6 +182,7 @@ export function registerHooks(pi, ecosystemHandlers) {
     // quick-return state is pending, so this is safe to call on every turn.
     pi.on("turn_end", async () => {
         try {
+            const { cleanupQuickBranch } = await import("../quick.js");
             cleanupQuickBranch();
         }
         catch {
@@ -172,8 +199,8 @@ export function registerHooks(pi, ecosystemHandlers) {
         const basePath = process.cwd();
         const { ensureDbOpen } = await import("./dynamic-tools.js");
         await ensureDbOpen();
-        const state = await deriveState(basePath);
-        if (!state.activeMilestone || !state.activeSlice || !state.activeTask)
+        const state = await deriveGsdState(basePath);
+        if (!state.activeMilestone || !state.activeSlice)
             return;
         // Write checkpoint for ALL phases, not just "executing" — discuss, research,
         // and planning also carry in-memory state (user answers, gate verification)
@@ -189,21 +216,30 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (await loadFile(legacyContinue))
             return;
         const continuePath = join(sliceDir, `${state.activeSlice.id}-CONTINUE.md`);
+        const taskId = state.activeTask?.id ?? "none";
+        const taskTitle = state.activeTask?.title ?? "";
+        const phaseLabel = state.phase.replace(/-/g, " ");
         await saveFile(continuePath, formatContinue({
             frontmatter: {
                 milestone: state.activeMilestone.id,
                 slice: state.activeSlice.id,
-                task: state.activeTask.id,
+                task: taskId,
                 step: 0,
                 totalSteps: 0,
                 status: "compacted",
                 savedAt: new Date().toISOString(),
             },
-            completedWork: `Task ${state.activeTask.id} (${state.activeTask.title}) was in progress when compaction occurred.`,
-            remainingWork: "Check the task plan for remaining steps.",
+            completedWork: state.activeTask
+                ? `Task ${taskId} (${taskTitle}) was in progress when compaction occurred.`
+                : `Slice ${state.activeSlice.id} was in ${phaseLabel} phase when compaction occurred.`,
+            remainingWork: state.activeTask
+                ? "Check the task plan for remaining steps."
+                : "Continue this slice from the latest planning/research/discussion artifacts.",
             decisions: "Check task summary files for prior decisions.",
             context: "Session was auto-compacted by Pi. Resume with /gsd.",
-            nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
+            nextAction: state.activeTask
+                ? `Resume task ${taskId}: ${taskTitle}.`
+                : `Resume ${phaseLabel} work for slice ${state.activeSlice.id}.`,
         }));
     });
     // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
@@ -225,7 +261,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             const basePath = process.cwd();
             let activeContext = null;
             try {
-                const state = await deriveState(basePath);
+                const state = await deriveGsdState(basePath);
                 if (state.activeMilestone && state.activeSlice && state.activeTask) {
                     activeContext =
                         `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
@@ -242,6 +278,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("session_shutdown", async (_event, ctx) => {
+        const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
             try {
                 await shutdownParallel(process.cwd());
@@ -252,7 +289,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         if (!isAutoActive() && !isAutoPaused())
             return;
-        const dash = getAutoDashboardData();
+        const dash = getAutoRuntimeSnapshot();
         if (dash.currentUnit) {
             saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
         }
@@ -278,7 +315,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // If ask_user_questions was called with a gate ID but hasn't been confirmed,
         // block all non-read-only tool calls to prevent the model from skipping gates.
         if (getPendingGate()) {
-            const milestoneId = getDiscussionMilestoneId(discussionBasePath);
+            const milestoneId = await getDiscussionMilestoneIdFor(discussionBasePath);
             if (isToolCallEventType("bash", event)) {
                 const bashGuard = shouldBlockPendingGateBash(event.input.command, milestoneId, isQueuePhaseActive());
                 if (bashGuard.block)
@@ -309,6 +346,32 @@ export function registerHooks(pi, ecosystemHandlers) {
             if (queueGuard.block)
                 return queueGuard;
         }
+        // ── Planning-unit tools-policy enforcement (#4934): runtime half ─────
+        // The active auto-mode unit's manifest declares a ToolsPolicy. For
+        // planning/docs/read-only modes, deny writes outside .gsd/ (or the
+        // manifest's allowedPathGlobs), bash that isn't read-only, and
+        // subagent dispatch. Closes the b23 bug class where a discuss-milestone
+        // turn used the host Edit tool to modify user source files.
+        const dash = getAutoRuntimeSnapshot();
+        const activeUnitType = dash.currentUnit?.type;
+        if (activeUnitType) {
+            const manifest = resolveManifest(activeUnitType);
+            if (manifest) {
+                let planningInput = "";
+                if (isToolCallEventType("write", event)) {
+                    planningInput = event.input.path;
+                }
+                else if (isToolCallEventType("edit", event)) {
+                    planningInput = event.input.path;
+                }
+                else if (isToolCallEventType("bash", event)) {
+                    planningInput = event.input.command;
+                }
+                const planningGuard = shouldBlockPlanningUnit(event.toolName, planningInput, dash.basePath || discussionBasePath, activeUnitType, manifest.tools);
+                if (planningGuard.block)
+                    return planningGuard;
+            }
+        }
         // ── Single-writer engine: block direct writes to STATE.md ──────────
         // Covers write, edit, and bash tools to prevent bypass vectors.
         if (isToolCallEventType("write", event)) {
@@ -328,7 +391,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         if (!isToolCallEventType("write", event))
             return;
-        const result = shouldBlockContextWrite(event.toolName, event.input.path, getDiscussionMilestoneId(discussionBasePath), isQueuePhaseActive());
+        const result = shouldBlockContextWrite(event.toolName, event.input.path, await getDiscussionMilestoneIdFor(discussionBasePath), isQueuePhaseActive());
         if (result.block)
             return result;
     });
@@ -368,7 +431,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         if (event.toolName !== "ask_user_questions")
             return;
-        const milestoneId = getDiscussionMilestoneId(process.cwd());
+        const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
         const queueActive = isQueuePhaseActive();
         const details = event.details;
         // ── Discussion gate enforcement: handle gate question responses ──
@@ -464,7 +527,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             safetyRecordToolResult(event.toolCallId, event.toolName, event.result, event.isError);
             // Persist evidence to disk after each tool result so it survives a session
             // restart mid-unit (Bug #4385 — non-persisted evidence false positives).
-            const dash = getAutoDashboardData();
+            const dash = getAutoRuntimeSnapshot();
             if (dash.basePath && dash.currentUnit?.type === "execute-task") {
                 const { milestone: pMid, slice: pSid, task: pTid } = parseUnitId(dash.currentUnit.id);
                 if (pMid && pSid && pTid) {

package/dist/resources/extensions/gsd/bootstrap/register-shortcuts.js

@@ -1,12 +1,12 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { Key } from "@gsd/pi-tui";
-import { GSDDashboardOverlay } from "../dashboard-overlay.js";
-import { GSDNotificationOverlay } from "../notification-overlay.js";
-import { ParallelMonitorOverlay } from "../parallel-monitor-overlay.js";
 import { GSD_SHORTCUTS } from "../shortcut-defs.js";
-import { projectRoot } from "../commands/context.js";
 import { shortcutDesc } from "../../shared/mod.js";
+async function getProjectRoot() {
+    const { projectRoot } = await import("../commands/context.js");
+    return projectRoot();
+}
 export function registerShortcuts(pi) {
     const overlayOptions = {
         width: "90%",
@@ -15,7 +15,10 @@ export function registerShortcuts(pi) {
         anchor: "center",
     };
     const openDashboardOverlay = async (ctx) => {
-        const basePath = projectRoot();
+        const [{ GSDDashboardOverlay }, basePath] = await Promise.all([
+            import("../dashboard-overlay.js"),
+            getProjectRoot(),
+        ]);
         if (!existsSync(join(basePath, ".gsd"))) {
             ctx.ui.notify("No .gsd/ directory found. Run /gsd to start.", "info");
             return;
@@ -26,6 +29,7 @@ export function registerShortcuts(pi) {
         });
     };
     const openNotificationsOverlay = async (ctx) => {
+        const { GSDNotificationOverlay } = await import("../notification-overlay.js");
         await ctx.ui.custom((tui, theme, _kb, done) => new GSDNotificationOverlay(tui, theme, () => done(true)), {
             overlay: true,
             overlayOptions: {
@@ -38,12 +42,13 @@ export function registerShortcuts(pi) {
         });
     };
     const openParallelOverlay = async (ctx) => {
-        const basePath = projectRoot();
+        const basePath = await getProjectRoot();
         const parallelDir = join(basePath, ".gsd", "parallel");
         if (!existsSync(parallelDir)) {
             ctx.ui.notify("No parallel workers found. Run /gsd parallel start first.", "info");
             return;
         }
+        const { ParallelMonitorOverlay } = await import("../parallel-monitor-overlay.js");
         await ctx.ui.custom((tui, theme, _kb, done) => new ParallelMonitorOverlay(tui, theme, () => done(true), basePath), {
             overlay: true,
             overlayOptions,

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -12,7 +12,7 @@ import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
-import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
+import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-session-state.js";
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
@@ -177,24 +177,50 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     const subagentModelBlock = subagentModelConfig
         ? `\n\n## Subagent Model\n\nWhen spawning subagents via the \`subagent\` tool, always pass \`model: "${subagentModelConfig.primary}"\` in the tool call parameters. Never omit this — always specify it explicitly.`
         : "";
-    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
+    // memoryBlock is FTS-queried against the user prompt and changes per call.
+    // Removing it from `fullSystem` keeps the system-prompt cache breakpoint
+    // stable across calls — the only scoped goal of this fix. The pi-ai
+    // Anthropic adapter additionally cache-marks the last user turn, so the
+    // memoryBlock injected via the context message may itself be cached up to
+    // that boundary; that's orthogonal and unchanged from prior behavior. The
+    // load-bearing win here is preserving the system+tools cache hit. (#5019)
+    const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${codebaseBlock}${newSkillsBlock}${worktreeBlock}${subagentModelBlock}`;
     stopContextTimer({
         systemPromptSize: fullSystem.length,
         injectionSize: injection?.length ?? forensicsInjection?.length ?? 0,
         hasPreferences: preferenceBlock.length > 0,
         hasNewSkills: newSkillsBlock.length > 0,
     });
-    // Determine which context message to inject (guided execute takes priority)
-    const contextMessage = injection
-        ? { customType: "gsd-guided-context", content: injection, display: false }
-        : forensicsInjection
-            ? { customType: "gsd-forensics", content: forensicsInjection, display: false }
-            : null;
+    const contextMessage = buildContextMessage({ memoryBlock, injection, forensicsInjection });
     return {
         systemPrompt: fullSystem,
         ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
+/**
+ * Route the per-call dynamic blocks (memory, guided-execute, forensics) into a
+ * single user-message context payload so they ride the volatile suffix instead
+ * of the cached system prefix. Priority when both memory and an injection are
+ * present: guided > forensics > memory-only. (#5019)
+ *
+ * Exported for direct unit testing — the surrounding bootstrap has too many
+ * filesystem and DB dependencies to exercise this routing logic in-place.
+ */
+export function buildContextMessage(opts) {
+    const memoryContent = opts.memoryBlock.trim();
+    if (opts.injection) {
+        const content = memoryContent ? `${memoryContent}\n\n${opts.injection}` : opts.injection;
+        return { customType: "gsd-guided-context", content, display: false };
+    }
+    if (opts.forensicsInjection) {
+        const content = memoryContent ? `${memoryContent}\n\n${opts.forensicsInjection}` : opts.forensicsInjection;
+        return { customType: "gsd-forensics", content, display: false };
+    }
+    if (memoryContent) {
+        return { customType: "gsd-memory", content: memoryContent, display: false };
+    }
+    return null;
+}
 /**
  * ADR-013 step 4 — auto-injection parity for the memories table.
  *

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

@@ -441,8 +441,31 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
     };
 }
 // ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+//
+// Runtime half of the declarative ToolsPolicy on UnitContextManifest. The
+// manifest assigns each unit type a tools mode; this predicate is what
+// actually rejects a tool call that violates it.
+//
+// Forensics: a discuss-milestone LLM turn used the host Edit tool to modify
+// index.html in test app b23 (~/Github/test-apps/b23). With this predicate
+// wired into the tool_call hook, the same call returns block=true with a
+// HARD BLOCK reason that the model cannot rationalize past.
+//
+// Activation: the hook supplies the policy resolved from the active unit's
+// manifest. When no unit is active (interactive sessions, unknown unit
+// types), the hook passes null and this predicate is a no-op — falling
+// through to the existing pendingGate / queue-execution / context-write
+// guards.
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+/**
+ * Read-only / planning-safe tools that any non-"all" mode allows. Mirrors
+ * QUEUE_SAFE_TOOLS / GATE_SAFE_TOOLS but is the inclusive default for
+ * planning units (which need their full discussion + research surface).
+ *
+ * gsd_* MCP tools are passed through unconditionally — they have their own
+ * domain validation (e.g. depth-verification gate, single-writer DB).
+ */
 const PLANNING_SAFE_TOOLS = new Set([
     "read", "grep", "find", "ls", "glob",
     "ask_user_questions",
@@ -458,6 +481,7 @@ function matchesAllowedGlob(absPath, basePath, globs) {
     const rel = relative(basePath, absPath);
     if (rel.startsWith("..") || isAbsolute(rel))
         return false;
+    // Normalize Windows separators for minimatch.
     const posix = rel.split(sep).join("/");
     return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
 }
@@ -480,7 +504,12 @@ function blockReason(unitType, mode, what) {
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *
- * `policy` of null means "no manifest resolved" — pass-through.
+ * `pathOrCommand` is the file path for write/edit-shaped tools and the
+ * shell command for bash. Other tools ignore this argument.
+ *
+ * `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.
  */
 export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy) {
     if (!policy)
@@ -488,6 +517,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     if (policy.mode === "all")
         return { block: false };
     const tool = toolName;
+    // Read-only mode: only Read-class tools are permitted.
     if (policy.mode === "read-only") {
         if (PLANNING_SAFE_TOOLS.has(tool))
             return { block: false };
@@ -496,9 +526,10 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
             return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
         }
+        // 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
+    // planning / 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_"))
@@ -519,8 +550,10 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
         }
         const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
+        // Always allow .gsd/ writes — that's where planning artifacts live.
         if (isPathUnderGsd(absPath, basePath))
             return { block: false };
+        // docs mode additionally allows the manifest's allowedPathGlobs.
         if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
             return { block: false };
         }
@@ -529,5 +562,8 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             reason: blockReason(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`),
         };
     }
+    // Unknown tool name — pass through. Other layers (queue, pending-gate,
+    // CONTEXT.md write) catch known mutating shapes; defaulting to allow here
+    // avoids breaking gsd_* MCP tools or future safe additions.
     return { block: false };
 }

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

@@ -1,10 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
-import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -330,6 +329,71 @@ function getExtensionCompletions(prefix, action) {
         return [];
     }
 }
+function normalizePathForCompare(path) {
+    return path.replaceAll("\\", "/").replace(/\/+$/, "");
+}
+function findWorktreeSegment(normalizedPath) {
+    const directMarker = "/.gsd/worktrees/";
+    const directIdx = normalizedPath.indexOf(directMarker);
+    if (directIdx !== -1) {
+        return { gsdIdx: directIdx, afterWorktrees: directIdx + directMarker.length };
+    }
+    const symlinkMatch = normalizedPath.match(/\/\.gsd\/projects\/[a-f0-9]+\/worktrees\//);
+    if (symlinkMatch?.index !== undefined) {
+        return { gsdIdx: symlinkMatch.index, afterWorktrees: symlinkMatch.index + symlinkMatch[0].length };
+    }
+    return null;
+}
+function resolveProjectRootFromGitFile(worktreePath) {
+    try {
+        let dir = worktreePath;
+        for (let i = 0; i < 30; i++) {
+            const gitPath = join(dir, ".git");
+            if (existsSync(gitPath)) {
+                const content = readFileSync(gitPath, "utf8").trim();
+                if (content.startsWith("gitdir: ")) {
+                    const gitDir = resolve(dir, content.slice(8));
+                    const dotGitDir = resolve(gitDir, "..", "..");
+                    if (dotGitDir.endsWith(".git") || dotGitDir.endsWith(".git/") || dotGitDir.endsWith(".git\\")) {
+                        return resolve(dotGitDir, "..");
+                    }
+                    const commonDirPath = join(gitDir, "commondir");
+                    if (existsSync(commonDirPath)) {
+                        const commonDir = readFileSync(commonDirPath, "utf8").trim();
+                        return resolve(resolve(gitDir, commonDir), "..");
+                    }
+                }
+                break;
+            }
+            const parent = resolve(dir, "..");
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // Completion must stay best-effort.
+    }
+    return null;
+}
+function resolveProjectRootForCompletion(basePath) {
+    if (process.env.GSD_PROJECT_ROOT)
+        return process.env.GSD_PROJECT_ROOT;
+    const normalizedPath = normalizePathForCompare(basePath);
+    const segment = findWorktreeSegment(normalizedPath);
+    if (!segment)
+        return basePath;
+    const separator = basePath.includes("\\") ? "\\" : "/";
+    const gsdMarker = `${separator}.gsd${separator}`;
+    const gsdIdx = basePath.indexOf(gsdMarker);
+    const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
+    const normalizedGsdHome = normalizePathForCompare(gsdHome);
+    const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
+    if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
+        return resolveProjectRootFromGitFile(basePath) ?? basePath;
+    }
+    return candidate;
+}
 export function getGsdArgumentCompletions(prefix) {
     const hasTrailingSpace = prefix.endsWith(" ");
     const parts = prefix.trim().split(/\s+/);
@@ -384,7 +448,7 @@ export function getGsdArgumentCompletions(prefix) {
     // Workflow definition-name completion for `workflow run <name>` and `workflow validate <name>`
     if (command === "workflow" && (subcommand === "run" || subcommand === "validate") && parts.length <= 3) {
         try {
-            const defsDir = join(resolveProjectRoot(process.cwd()), ".gsd", "workflow-defs");
+            const defsDir = join(resolveProjectRootForCompletion(process.cwd()), ".gsd", "workflow-defs");
             if (existsSync(defsDir)) {
                 return readdirSync(defsDir)
                     .filter((f) => f.endsWith(".yaml") && f.startsWith(third))
@@ -426,7 +490,7 @@ export function getGsdArgumentCompletions(prefix) {
             catch { /* ignore */ }
         };
         try {
-            const base = resolveProjectRoot(process.cwd());
+            const base = resolveProjectRootForCompletion(process.cwd());
             scanDir(join(base, ".gsd", "workflows"), "project");
             scanDir(join(base, ".gsd", "workflow-defs"), "project-legacy");
             scanDir(join(gsdHome, "workflows"), "global");