gsd-pi 2.80.0-dev.96f4d89d5 → 2.80.0-dev.a947d025c

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -1,4 +1,9 @@
-import { join } from "node:path";
+// Project/App: GSD-2
+// File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
@@ -7,7 +12,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, 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 { loadFile, saveFile, formatContinue } from "../files.js";
@@ -25,12 +30,255 @@ import { initNotificationWidget } from "../notification-widget.js";
 import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
+import { resolveSkillManifest } from "../skill-manifest.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;
 let approvalQuestionAbortInFlight = false;
 
+interface DeferredApprovalGate {
+  gateId: string;
+  basePath: string;
+}
+
+type WelcomeScreenModule = {
+  buildWelcomeScreenLines(opts: { version: string; remoteChannel?: string; width?: number }): string[];
+};
+
+async function loadWelcomeScreenModule(): Promise<WelcomeScreenModule | undefined> {
+  const candidates: string[] = [];
+  const gsdBinPath = process.env.GSD_BIN_PATH;
+  if (gsdBinPath) {
+    candidates.push(join(dirname(gsdBinPath), "welcome-screen.js"));
+  }
+
+  const packageRoot = process.env.GSD_PKG_ROOT;
+  if (packageRoot) {
+    candidates.push(join(packageRoot, "dist", "welcome-screen.js"));
+    candidates.push(join(packageRoot, "src", "welcome-screen.ts"));
+  }
+
+  for (const candidate of candidates) {
+    try {
+      if (!existsSync(candidate)) continue;
+      const mod = await import(pathToFileURL(candidate).href) as Partial<WelcomeScreenModule>;
+      if (typeof mod.buildWelcomeScreenLines === "function") {
+        return mod as WelcomeScreenModule;
+      }
+    } catch {
+      // Try the next package layout.
+    }
+  }
+  return undefined;
+}
+
+async function installWelcomeHeader(ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI || typeof ctx.ui?.setHeader !== "function") return;
+
+  try {
+    const welcome = await loadWelcomeScreenModule();
+    if (!welcome) return;
+
+    let remoteChannel: string | undefined;
+    try {
+      const { resolveRemoteConfig } = await import("../../remote-questions/config.js");
+      const rc = resolveRemoteConfig();
+      if (rc) remoteChannel = rc.channel;
+    } catch { /* non-fatal */ }
+
+    ctx.ui.setHeader(() => {
+      let cachedLines: string[] | undefined;
+      let cachedWidth: number | undefined;
+      return {
+        render(width: number): string[] {
+          if (cachedLines !== undefined && cachedWidth === width) return cachedLines;
+          cachedLines = welcome.buildWelcomeScreenLines({
+            version: process.env.GSD_VERSION || "0.0.0",
+            remoteChannel,
+            width,
+          });
+          cachedWidth = width;
+          return cachedLines;
+        },
+        invalidate(): void {
+          cachedLines = undefined;
+          cachedWidth = undefined;
+        },
+      };
+    });
+  } catch {
+    /* non-fatal */
+  }
+}
+
+let deferredApprovalGate: DeferredApprovalGate | null = null;
+
+export const MINIMAL_GSD_TOOL_NAMES = [
+  "gsd_exec",
+  "gsd_exec_search",
+  "gsd_resume",
+  "gsd_milestone_status",
+  "gsd_checkpoint_db",
+  "memory_query",
+  "capture_thought",
+] as const;
+
+export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
+  "ask_user_questions",
+  "bash",
+  "bg_shell",
+  "edit",
+  "glob",
+  "grep",
+  "ls",
+  "read",
+  "write",
+] as const;
+
+const AUTO_UNIT_SCOPED_TOOLS: Record<string, readonly string[]> = {
+  "research-milestone": ["gsd_summary_save", "gsd_decision_save"],
+  "plan-milestone": ["gsd_plan_milestone", "gsd_decision_save", "gsd_requirement_update"],
+  "discuss-milestone": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+  "validate-milestone": ["gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+  "complete-milestone": ["gsd_complete_milestone", "subagent"],
+  "research-slice": ["gsd_summary_save", "gsd_decision_save"],
+  "plan-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+  "refine-slice": ["gsd_plan_slice", "gsd_plan_task", "gsd_decision_save"],
+  "replan-slice": ["gsd_replan_slice", "gsd_plan_task", "gsd_decision_save"],
+  "complete-slice": ["gsd_slice_complete", "gsd_decision_save", "gsd_requirement_update", "subagent"],
+  "reassess-roadmap": ["gsd_reassess_roadmap"],
+  "execute-task": ["gsd_task_complete", "gsd_decision_save"],
+  "execute-task-simple": ["gsd_task_complete", "gsd_decision_save"],
+  "reactive-execute": ["gsd_task_complete", "gsd_decision_save"],
+  "run-uat": ["gsd_summary_save"],
+  "gate-evaluate": ["gsd_save_gate_result"],
+  "rewrite-docs": ["gsd_summary_save", "gsd_decision_save"],
+  "workflow-preferences": ["gsd_summary_save"],
+  "discuss-project": ["gsd_summary_save", "gsd_decision_save", "gsd_requirement_save"],
+  "discuss-requirements": ["gsd_requirement_save", "gsd_summary_save"],
+  "research-decision": ["gsd_summary_save"],
+  "research-project": ["gsd_summary_save", "gsd_decision_save"],
+};
+
+const WORKFLOW_GSD_TOOL_NAMES = [
+  ...MINIMAL_GSD_TOOL_NAMES,
+  ...Object.values(AUTO_UNIT_SCOPED_TOOLS).flat(),
+].filter(isGsdManagedTool);
+
+function isGsdManagedTool(name: string): boolean {
+  return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
+}
+
+export function buildMinimalGsdToolSet(activeToolNames: readonly string[]): string[] {
+  const active = new Set(activeToolNames);
+  const preserved = activeToolNames.filter((name) => !isGsdManagedTool(name));
+  const minimal = MINIMAL_GSD_TOOL_NAMES.filter((name) => active.has(name));
+  return [...new Set([...preserved, ...minimal])];
+}
+
+export function buildMinimalAutoGsdToolSet(
+  activeToolNames: readonly string[],
+  unitType: string | undefined,
+): string[] {
+  const active = new Set(activeToolNames);
+  const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
+  const autoBaseTools = new Set<string>(MINIMAL_AUTO_BASE_TOOL_NAMES);
+  const preserved = activeToolNames.filter((name) => autoBaseTools.has(name));
+  const scoped = [...MINIMAL_GSD_TOOL_NAMES, ...unitTools].filter((name) => active.has(name));
+  return [...new Set([...preserved, ...scoped])];
+}
+
+export function buildMinimalGsdWorkflowToolSet(activeToolNames: readonly string[]): string[] {
+  const active = new Set(activeToolNames);
+  const autoBaseTools = new Set<string>(MINIMAL_AUTO_BASE_TOOL_NAMES);
+  const preserved = activeToolNames.filter((name) => autoBaseTools.has(name));
+  const scoped = WORKFLOW_GSD_TOOL_NAMES.filter((name) => active.has(name));
+  return [...new Set([...preserved, ...scoped])];
+}
+
+export function buildRequestScopedGsdToolSet(
+  activeToolNames: readonly string[],
+  requestCustomMessages: readonly { customType?: string }[] | undefined,
+): string[] | undefined {
+  for (let index = (requestCustomMessages?.length ?? 0) - 1; index >= 0; index--) {
+    const currentCustomType = requestCustomMessages?.[index]?.customType;
+    if (
+      currentCustomType === "gsd-run" ||
+      currentCustomType === "gsd-discuss" ||
+      currentCustomType === "gsd-doctor-heal" ||
+      currentCustomType === "gsd-triage"
+    ) {
+      return buildMinimalGsdWorkflowToolSet(activeToolNames);
+    }
+  }
+  return undefined;
+}
+
+export function isFullGsdToolSurfaceRequested(): boolean {
+  return process.env.PI_GSD_FULL_TOOLS === "1";
+}
+
+function isGeneralGsdToolScopingRequested(): boolean {
+  return process.env.PI_GSD_MINIMAL_TOOLS === "1";
+}
+
+export interface ScopedGsdWorkflowState {
+  tools: string[] | null;
+  visibleSkills: string[] | undefined;
+  restoreVisibleSkills: boolean;
+}
+
+type GsdWorkflowScopeApi = Pick<ExtensionAPI, "getActiveTools" | "setActiveTools"> & Partial<Pick<ExtensionAPI, "getVisibleSkills" | "setVisibleSkills">>;
+
+function applyMinimalGsdToolSurface(pi: ExtensionAPI): void {
+  if (isFullGsdToolSurfaceRequested()) return;
+  const dash = getAutoRuntimeSnapshot();
+  if (dash.active && dash.currentUnit) {
+    pi.setActiveTools(buildMinimalAutoGsdToolSet(pi.getActiveTools(), dash.currentUnit.type));
+    return;
+  }
+  if (!isGeneralGsdToolScopingRequested()) return;
+  pi.setActiveTools(buildMinimalGsdToolSet(pi.getActiveTools()));
+}
+
+export function scopeGsdWorkflowToolsForDispatch(
+  pi: GsdWorkflowScopeApi,
+  unitType?: string,
+): ScopedGsdWorkflowState | null {
+  if (isFullGsdToolSurfaceRequested()) return null;
+  const current = pi.getActiveTools();
+  const scoped = unitType
+    ? buildMinimalAutoGsdToolSet(current, unitType)
+    : buildMinimalGsdWorkflowToolSet(current);
+  const toolsChanged = !(scoped.length === current.length && scoped.every((name, index) => name === current[index]));
+  const skillManifest = resolveSkillManifest(unitType);
+  const canScopeSkills = skillManifest !== null && pi.getVisibleSkills && pi.setVisibleSkills;
+  if (!toolsChanged && !canScopeSkills) {
+    return null;
+  }
+  if (toolsChanged) {
+    pi.setActiveTools(scoped);
+  }
+  const visibleSkills = canScopeSkills ? pi.getVisibleSkills!() : undefined;
+  if (canScopeSkills) {
+    pi.setVisibleSkills!(skillManifest);
+  }
+  return {
+    tools: toolsChanged ? current : null,
+    visibleSkills,
+    restoreVisibleSkills: Boolean(canScopeSkills),
+  };
+}
+
+export function restoreGsdWorkflowTools(
+  pi: Pick<ExtensionAPI, "setActiveTools"> & Partial<Pick<ExtensionAPI, "setVisibleSkills">>,
+  savedState: ScopedGsdWorkflowState | null,
+): void {
+  if (!savedState) return;
+  if (savedState.tools) pi.setActiveTools(savedState.tools);
+  if (savedState.restoreVisibleSkills && pi.setVisibleSkills) {
+    pi.setVisibleSkills(savedState.visibleSkills);
+  }
+}
+
 async function deriveGsdState(basePath: string) {
   const { deriveState } = await import("../state.js");
   return deriveState(basePath);
@@ -65,12 +313,76 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
-export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
-  return resolveWorktreeProjectRoot(cwd);
+/**
+ * Bridge `context_management.compaction_threshold_percent` from GSD preferences
+ * into the agent's runtime compaction settings (#5475). The preference is
+ * validated to (0.5, 0.95) at load time, but defense-in-depth normalization
+ * here protects against a stale or hand-edited prefs file. Calling with
+ * `undefined` clears any prior override so a removed preference does not leak.
+ */
+async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<void> {
+  try {
+    const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+    const prefs = loadEffectiveGSDPreferences();
+    const raw = prefs?.preferences.context_management?.compaction_threshold_percent;
+    const value =
+      typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : undefined;
+    ctx.setCompactionThresholdOverride(value);
+  } catch {
+    // Non-fatal: leave any existing override in place.
+  }
+}
+
+function clearDeferredApprovalGate(basePath?: string): void {
+  if (!basePath || deferredApprovalGate?.basePath === basePath) {
+    deferredApprovalGate = null;
+  }
+}
+
+function deferApprovalGate(gateId: string, basePath: string): void {
+  deferredApprovalGate = { gateId, basePath };
+}
+
+function contextBasePath(ctx?: { cwd?: string }): string {
+  return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
+}
+
+function activateDeferredApprovalGate(basePath: string): void {
+  if (deferredApprovalGate?.basePath !== basePath) return;
+  setPendingGate(deferredApprovalGate.gateId, basePath);
+  deferredApprovalGate = null;
+}
+
+function isContextDraftSummarySave(toolName: string, input: unknown): boolean {
+  if (toolName !== "gsd_summary_save" && toolName !== "summary_save") return false;
+  if (!input || typeof input !== "object") return false;
+  return (input as { artifact_type?: unknown }).artifact_type === "CONTEXT-DRAFT";
+}
+
+function shouldBlockDeferredApprovalTool(
+  toolName: string,
+  input: unknown,
+  basePath: string,
+): { block: boolean; reason?: string } {
+  if (deferredApprovalGate?.basePath !== basePath) return { block: false };
+  if (toolName === "ask_user_questions") return { block: false };
+  if (isContextDraftSummarySave(toolName, input)) return { block: false };
+  return {
+    block: true,
+    reason: [
+      `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
+      `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
+      `Wait for the user's answer before calling additional tools.`,
+    ].join(" "),
+  };
+}
+
+export function resolveNotificationStoreBasePath(basePath: string): string {
+  return resolveWorktreeProjectRoot(basePath);
 }
 
 function initSessionNotifications(ctx: ExtensionContext): void {
-  initNotificationStore(resolveNotificationStoreBasePath());
+  initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
   installNotifyInterceptor(ctx);
   initNotificationWidget(ctx);
 }
@@ -112,52 +424,34 @@ export function registerHooks(
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
   pi.on("session_start", async (_event, ctx) => {
+    const basePath = contextBasePath(ctx);
     initSessionNotifications(ctx);
     if (!isAutoActive()) {
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
     }
-    resetWriteGateState(process.cwd());
+    resetWriteGateState(basePath);
     resetToolCallLoopGuard();
     approvalQuestionAbortInFlight = false;
+    clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(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())) {
+    if (!isInAutoWorktree(basePath)) {
       const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-      prepareWorkflowMcpForProject(ctx, process.cwd());
+      prepareWorkflowMcpForProject(ctx, basePath);
     }
 
     // Apply show_token_cost preference (#1515)
     try {
       const { loadEffectiveGSDPreferences } = await import("../preferences.js");
-      const prefs = loadEffectiveGSDPreferences();
+      const prefs = loadEffectiveGSDPreferences(basePath);
       process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
     } catch { /* non-fatal */ }
-    if (isFirstSession) {
-      isFirstSession = false;
-    } else {
-      try {
-        const gsdBinPath = process.env.GSD_BIN_PATH;
-        if (gsdBinPath) {
-          const { dirname } = await import("node:path");
-          const { printWelcomeScreen } = await import(
-            join(dirname(gsdBinPath), "welcome-screen.js")
-          ) as { printWelcomeScreen: (opts: { version: string; modelName?: string; provider?: string; remoteChannel?: string }) => void };
-
-          let remoteChannel: string | undefined;
-          try {
-            const { resolveRemoteConfig } = await import("../../remote-questions/config.js");
-            const rc = resolveRemoteConfig();
-            if (rc) remoteChannel = rc.channel;
-          } catch { /* non-fatal */ }
-
-          printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0", remoteChannel });
-        }
-      } catch { /* non-fatal */ }
-    }
+    await installWelcomeHeader(ctx);
     await loadToolApiKeysForSession();
     if (isAutoActive()) {
       ctx.ui.setWidget("gsd-health", undefined);
@@ -165,21 +459,24 @@ export function registerHooks(
   });
 
   pi.on("session_switch", async (_event, ctx) => {
+    const basePath = contextBasePath(ctx);
     initSessionNotifications(ctx);
-    resetWriteGateState(process.cwd());
+    resetWriteGateState(basePath);
     resetToolCallLoopGuard();
+    clearDeferredApprovalGate();
     await resetAskUserQuestionsTurnCache();
-    clearDiscussionFlowState(process.cwd());
+    clearDiscussionFlowState(basePath);
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(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
     // CLI path resolution), dirtying the tree and breaking the milestone merge.
     const { isInAutoWorktree } = await import("../auto-worktree.js");
-    if (!isInAutoWorktree(process.cwd())) {
+    if (!isInAutoWorktree(basePath)) {
       const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-      prepareWorkflowMcpForProject(ctx, process.cwd());
+      prepareWorkflowMcpForProject(ctx, basePath);
     }
     await loadToolApiKeysForSession();
     if (!isAutoActive()) {
@@ -191,11 +488,13 @@ export function registerHooks(
   });
 
   pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+    applyMinimalGsdToolSurface(pi);
+
     // Wait for ecosystem loader to finish (no-op after first turn).
     const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
     await getEcosystemReadyPromise();
 
-    const beforeAgentBasePath = process.cwd();
+    const beforeAgentBasePath = contextBasePath(ctx);
     const pendingApprovalGate = getPendingGate(beforeAgentBasePath);
     if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
       markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
@@ -203,6 +502,7 @@ export function registerHooks(
       if (milestoneId) markDepthVerified(milestoneId, beforeAgentBasePath);
       clearPendingGate(beforeAgentBasePath);
     }
+    clearDeferredApprovalGate(beforeAgentBasePath);
 
     // GSD's own context injection (existing behavior — unchanged).
     const { buildBeforeAgentStartResult } = await import("./system-context.js");
@@ -211,7 +511,7 @@ export function registerHooks(
     // 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 deriveGsdState(process.cwd());
+      const state = await deriveGsdState(beforeAgentBasePath);
       updateSnapshot(state);
     } catch {
       updateSnapshot(null);
@@ -253,7 +553,11 @@ export function registerHooks(
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
     const { handleAgentEnd } = await import("./agent-end-recovery.js");
-    await handleAgentEnd(pi, event, ctx);
+    try {
+      await handleAgentEnd(pi, event, ctx);
+    } finally {
+      activateDeferredApprovalGate(contextBasePath(ctx));
+    }
   });
 
   // Squash-merge quick-task branch back to the original branch after the
@@ -268,8 +572,8 @@ export function registerHooks(
     }
   });
 
-  pi.on("session_before_compact", async () => {
-    const basePath = process.cwd();
+  pi.on("session_before_compact", async (_event, ctx) => {
+    const basePath = contextBasePath(ctx);
     // Context Mode is default-on. Write the resumable snapshot before any
     // active-auto cancel return so auto sessions still leave re-entry context.
     await writeContextModeCompactionSnapshot(basePath);
@@ -336,7 +640,7 @@ export function registerHooks(
     if (!unitType) {
       try {
         const { getPendingDeepProjectSetupUnitForContext } = await import("../guided-flow.js");
-        const pending = getPendingDeepProjectSetupUnitForContext(ctx, process.cwd());
+        const pending = getPendingDeepProjectSetupUnitForContext(ctx, contextBasePath(ctx));
         unitType = pending?.unitType;
         unitId = pending?.unitId;
       } catch {
@@ -345,7 +649,7 @@ export function registerHooks(
     }
 
     if (!unitType) {
-      const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+      const milestoneId = await getDiscussionMilestoneIdFor(contextBasePath(ctx));
       if (milestoneId) {
         unitType = "discuss-milestone";
         unitId = milestoneId;
@@ -355,15 +659,16 @@ export function registerHooks(
     if (!shouldPauseForUserApprovalQuestion(unitType, [event.message])) return;
 
     const gateId = approvalGateIdForUnit(unitType, unitId);
-    if (gateId) setPendingGate(gateId, process.cwd());
+    if (gateId) deferApprovalGate(gateId, contextBasePath(ctx));
 
     approvalQuestionAbortInFlight = true;
     ctx.ui.notify(
       `${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`,
       "info",
     );
-    // The pending gate set above blocks subsequent non-read-only tool calls
-    // via the tool_call hook below, so we do not abort the in-flight stream.
+    // The durable pending gate is activated at agent_end so same-turn
+    // CONTEXT-DRAFT persistence can finish after the text boundary streams.
+    // The tool_call hook below still blocks non-draft tools in this turn.
     // Aborting mid-stream eats the model's question text on external CLI
     // providers (Claude Code SDK) because lastTextContent isn't populated
     // from in-flight builder state — the user only ever sees "Claude Code
@@ -374,7 +679,7 @@ export function registerHooks(
     const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
     if (isParallelActive()) {
       try {
-        await shutdownParallel(process.cwd());
+        await shutdownParallel(contextBasePath(ctx));
       } catch {
         // best-effort
       }
@@ -386,8 +691,8 @@ export function registerHooks(
     }
   });
 
-  pi.on("tool_call", async (event) => {
-    const discussionBasePath = process.cwd();
+  pi.on("tool_call", async (event, ctx) => {
+    const discussionBasePath = contextBasePath(ctx);
     const toolName = canonicalToolName(event.toolName);
     // ── Loop guard: block repeated identical tool calls ──
     const loopCheck = checkToolCallLoop(toolName, event.input as Record<string, unknown>);
@@ -395,6 +700,13 @@ export function registerHooks(
       return { block: true, reason: loopCheck.reason };
     }
 
+    const deferredGateGuard = shouldBlockDeferredApprovalTool(
+      toolName,
+      event.input,
+      discussionBasePath,
+    );
+    if (deferredGateGuard.block) return deferredGateGuard;
+
     // ── Discussion gate enforcement: track pending gate questions ─────────
     // Only gate-shaped ask_user_questions calls should block execution.
     // The gate stays pending until the user selects the approval option.
@@ -482,6 +794,22 @@ export function registerHooks(
       }
     }
 
+    // ── Worktree-isolation write gate (#5199) ────────────────────────────
+    // Block planning-write tools from landing code at the project root when
+    // git.isolation=worktree but auto-mode hasn't created the milestone
+    // worktree yet. Without this, writes silently orphan outside git history.
+    if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+      const wtBasePath = resolveWorktreeProjectRoot(dash.basePath ?? discussionBasePath);
+      const wtGuard = shouldBlockWorktreeWrite(
+        event.toolName,
+        event.input.path,
+        wtBasePath,
+        isAutoActive(),
+        dash.currentUnit?.type,
+      );
+      if (wtGuard.block) return wtGuard;
+    }
+
     // ── Single-writer engine: block direct writes to STATE.md ──────────
     // Covers write, edit, and bash tools to prevent bypass vectors.
     if (isToolCallEventType("write", event)) {
@@ -548,7 +876,7 @@ export function registerHooks(
     }
   });
 
-  pi.on("tool_result", async (event) => {
+  pi.on("tool_result", async (event, ctx) => {
     if (isAutoActive() && typeof event.toolCallId === "string") {
       markToolEnd(event.toolCallId);
     }
@@ -567,7 +895,7 @@ export function registerHooks(
     }
     const toolName = canonicalToolName(event.toolName);
     if (toolName !== "ask_user_questions") return;
-    const basePath = process.cwd();
+    const basePath = contextBasePath(ctx);
     const milestoneId = await getDiscussionMilestoneIdFor(basePath);
     const queueActive = isQueuePhaseActive(basePath);
 
@@ -773,8 +1101,21 @@ export function registerHooks(
   // Tool set adaptation hook (ADR-005 Phase 4)
   // Extensions can override tool set after model selection by returning { toolNames: [...] }
   // Return undefined to let the built-in provider compatibility filtering proceed.
-  pi.on("adjust_tool_set", async (_event) => {
-    // Default: no override — let provider capability filtering handle tool set
+  pi.on("adjust_tool_set", async (event) => {
+    if (isFullGsdToolSurfaceRequested()) return undefined;
+    const removed = new Set(event.filteredTools);
+    const providerCompatible = event.activeToolNames.filter((name) => !removed.has(name));
+    const requestScoped = buildRequestScopedGsdToolSet(providerCompatible, event.requestCustomMessages);
+    if (requestScoped) {
+      return { toolNames: requestScoped };
+    }
+    const dash = getAutoRuntimeSnapshot();
+    if (dash.active && dash.currentUnit) {
+      return { toolNames: buildMinimalAutoGsdToolSet(providerCompatible, dash.currentUnit.type) };
+    }
+    if (isGeneralGsdToolScopingRequested()) {
+      return { toolNames: buildMinimalGsdToolSet(providerCompatible) };
+    }
     return undefined;
   });
 }

package/src/resources/extensions/gsd/bootstrap/sanitize-complete-milestone.ts

@@ -39,6 +39,8 @@ function toStrArray(v: unknown): string[] {
  * CompleteMilestoneParams, tolerating type mismatches from LLM JSON quirks.
  */
 export function sanitizeCompleteMilestoneParams(raw: Record<string, unknown>): CompleteMilestoneParams {
+  const actorName = toStr(raw.actorName);
+  const triggerReason = toStr(raw.triggerReason);
   return {
     milestoneId: toStr(raw.milestoneId),
     title: toStr(raw.title),
@@ -53,5 +55,7 @@ export function sanitizeCompleteMilestoneParams(raw: Record<string, unknown>): C
     followUps: toStr(raw.followUps),
     deviations: toStr(raw.deviations),
     verificationPassed: raw.verificationPassed === true || raw.verificationPassed === "true",
+    ...(actorName ? { actorName } : {}),
+    ...(triggerReason ? { triggerReason } : {}),
   };
 }