gsd-pi 2.80.0-dev.cf9433f56 → 2.80.0-dev.d4fc28e6b

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

@@ -1,4 +1,8 @@
-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 { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
@@ -19,10 +23,202 @@ 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";
-// 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;
+import { resolveSkillManifest } from "../skill-manifest.js";
 let approvalQuestionAbortInFlight = false;
+async function loadWelcomeScreenModule() {
+    const candidates = [];
+    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);
+            if (typeof mod.buildWelcomeScreenLines === "function") {
+                return mod;
+            }
+        }
+        catch {
+            // Try the next package layout.
+        }
+    }
+    return undefined;
+}
+async function installWelcomeHeader(ctx) {
+    if (!ctx.hasUI || typeof ctx.ui?.setHeader !== "function")
+        return;
+    try {
+        const welcome = await loadWelcomeScreenModule();
+        if (!welcome)
+            return;
+        let remoteChannel;
+        try {
+            const { resolveRemoteConfig } = await import("../../remote-questions/config.js");
+            const rc = resolveRemoteConfig();
+            if (rc)
+                remoteChannel = rc.channel;
+        }
+        catch { /* non-fatal */ }
+        ctx.ui.setHeader(() => ({
+            render(width) {
+                return welcome.buildWelcomeScreenLines({
+                    version: process.env.GSD_VERSION || "0.0.0",
+                    remoteChannel,
+                    width,
+                });
+            },
+            invalidate() { },
+        }));
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+let deferredApprovalGate = null;
+export const MINIMAL_GSD_TOOL_NAMES = [
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_milestone_status",
+    "gsd_checkpoint_db",
+    "memory_query",
+    "capture_thought",
+];
+export const MINIMAL_AUTO_BASE_TOOL_NAMES = [
+    "ask_user_questions",
+    "bash",
+    "bg_shell",
+    "edit",
+    "glob",
+    "grep",
+    "ls",
+    "read",
+    "write",
+];
+const AUTO_UNIT_SCOPED_TOOLS = {
+    "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) {
+    return name.startsWith("gsd_") || name === "memory_query" || name === "capture_thought" || name === "gsd_graph";
+}
+export function buildMinimalGsdToolSet(activeToolNames) {
+    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, unitType) {
+    const active = new Set(activeToolNames);
+    const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
+    const autoBaseTools = new Set(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) {
+    const active = new Set(activeToolNames);
+    const autoBaseTools = new Set(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, requestCustomMessages) {
+    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() {
+    return process.env.PI_GSD_FULL_TOOLS === "1";
+}
+function isGeneralGsdToolScopingRequested() {
+    return process.env.PI_GSD_MINIMAL_TOOLS === "1";
+}
+function applyMinimalGsdToolSurface(pi) {
+    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, unitType) {
+    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, savedState) {
+    if (!savedState)
+        return;
+    if (savedState.tools)
+        pi.setActiveTools(savedState.tools);
+    if (savedState.restoreVisibleSkills && pi.setVisibleSkills) {
+        pi.setVisibleSkills(savedState.visibleSkills);
+    }
+}
 async function deriveGsdState(basePath) {
     const { deriveState } = await import("../state.js");
     return deriveState(basePath);
@@ -71,11 +267,51 @@ async function applyCompactionThresholdOverride(ctx) {
         // Non-fatal: leave any existing override in place.
     }
 }
-export function resolveNotificationStoreBasePath(cwd = process.cwd()) {
-    return resolveWorktreeProjectRoot(cwd);
+function clearDeferredApprovalGate(basePath) {
+    if (!basePath || deferredApprovalGate?.basePath === basePath) {
+        deferredApprovalGate = null;
+    }
+}
+function deferApprovalGate(gateId, basePath) {
+    deferredApprovalGate = { gateId, basePath };
+}
+function contextBasePath(ctx) {
+    return typeof ctx?.cwd === "string" ? ctx.cwd : process.cwd();
+}
+function activateDeferredApprovalGate(basePath) {
+    if (deferredApprovalGate?.basePath !== basePath)
+        return;
+    setPendingGate(deferredApprovalGate.gateId, basePath);
+    deferredApprovalGate = null;
+}
+function isContextDraftSummarySave(toolName, input) {
+    if (toolName !== "gsd_summary_save" && toolName !== "summary_save")
+        return false;
+    if (!input || typeof input !== "object")
+        return false;
+    return input.artifact_type === "CONTEXT-DRAFT";
+}
+function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
+    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) {
+    return resolveWorktreeProjectRoot(basePath);
 }
 function initSessionNotifications(ctx) {
-    initNotificationStore(resolveNotificationStoreBasePath());
+    initNotificationStore(resolveNotificationStoreBasePath(contextBasePath(ctx)));
     installNotifyInterceptor(ctx);
     initNotificationWidget(ctx);
 }
@@ -109,64 +345,47 @@ async function writeContextModeCompactionSnapshot(basePath) {
 }
 export function registerHooks(pi, ecosystemHandlers) {
     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"));
-                    let remoteChannel;
-                    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);
         }
     });
     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);
@@ -175,9 +394,9 @@ export function registerHooks(pi, ecosystemHandlers) {
         // 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()) {
@@ -189,10 +408,11 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
+        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);
@@ -201,13 +421,14 @@ export function registerHooks(pi, ecosystemHandlers) {
                 markDepthVerified(milestoneId, beforeAgentBasePath);
             clearPendingGate(beforeAgentBasePath);
         }
+        clearDeferredApprovalGate(beforeAgentBasePath);
         // 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 deriveGsdState(process.cwd());
+            const state = await deriveGsdState(beforeAgentBasePath);
             updateSnapshot(state);
         }
         catch {
@@ -244,7 +465,12 @@ export function registerHooks(pi, ecosystemHandlers) {
         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
     // agent turn completes (#2668). cleanupQuickBranch is a no-op when no
@@ -258,8 +484,8 @@ export function registerHooks(pi, ecosystemHandlers) {
             // Best-effort: don't break the turn lifecycle if cleanup fails.
         }
     });
-    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);
@@ -323,7 +549,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         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;
             }
@@ -332,7 +558,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
         if (!unitType) {
-            const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+            const milestoneId = await getDiscussionMilestoneIdFor(contextBasePath(ctx));
             if (milestoneId) {
                 unitType = "discuss-milestone";
                 unitId = milestoneId;
@@ -342,11 +568,12 @@ export function registerHooks(pi, ecosystemHandlers) {
             return;
         const gateId = approvalGateIdForUnit(unitType, unitId);
         if (gateId)
-            setPendingGate(gateId, process.cwd());
+            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
@@ -356,7 +583,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
             try {
-                await shutdownParallel(process.cwd());
+                await shutdownParallel(contextBasePath(ctx));
             }
             catch {
                 // best-effort
@@ -369,14 +596,17 @@ export function registerHooks(pi, ecosystemHandlers) {
             saveActivityLog(ctx, dash.basePath, dash.currentUnit.type, dash.currentUnit.id);
         }
     });
-    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);
         if (loopCheck.block) {
             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.
@@ -515,7 +745,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             }
         }
     });
-    pi.on("tool_result", async (event) => {
+    pi.on("tool_result", async (event, ctx) => {
         if (isAutoActive() && typeof event.toolCallId === "string") {
             markToolEnd(event.toolCallId);
         }
@@ -535,7 +765,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         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);
         const details = event.details;
@@ -737,8 +967,22 @@ export function registerHooks(pi, ecosystemHandlers) {
     // 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;
     });
 }