gsd-pi 2.80.0-dev.2be7caf18 → 2.80.0-dev.3065f7bfa

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

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Registers GSD extension runtime hooks and token-saving tool policies.
+
 import { join } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
@@ -25,12 +28,188 @@ 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;
+}
+
+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);
@@ -85,12 +264,56 @@ async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<
   }
 }
 
-export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
-  return resolveWorktreeProjectRoot(cwd);
+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);
 }
@@ -132,29 +355,31 @@ 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) {
@@ -186,11 +411,13 @@ 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);
@@ -199,9 +426,9 @@ export function registerHooks(
     // 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()) {
@@ -213,11 +440,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);
@@ -225,6 +454,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");
@@ -233,7 +463,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);
@@ -275,7 +505,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
@@ -290,8 +524,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);
@@ -358,7 +592,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 {
@@ -367,7 +601,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;
@@ -377,15 +611,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
@@ -396,7 +631,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
       }
@@ -408,8 +643,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>);
@@ -417,6 +652,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.
@@ -586,7 +828,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);
     }
@@ -605,7 +847,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);
 
@@ -811,8 +1053,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;
   });
 }