@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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

@@ -23,6 +23,10 @@ const DEFAULT_KNOWLEDGE_MAX_CHARS = 12_000;
 const DEFAULT_CODEBASE_MAX_CHARS = 8_000;
 const MIN_CONTEXT_MESSAGE_MAX_CHARS = 1_000;
 const MIN_KNOWLEDGE_MAX_CHARS = 1_000;
+const CONTEXT_MAINTENANCE_KEY_SEPARATOR = "\0";
+const contextMaintenanceCompletedForSession = new Set();
+const contextMaintenanceInFlightBySession = new Map();
+const deferredContextMaintenanceBySession = new Map();
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -65,6 +69,24 @@ export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
     { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
+/**
+ * Remove the volatile lines from a CODEBASE.md map before it is injected into
+ * the cached system-prompt prefix: the human-readable `Generated: <timestamp>`
+ * header and the `<!-- gsd:codebase-meta {...} -->` comment. Both carry a
+ * per-regeneration timestamp (and fingerprint) that change whenever the map is
+ * refreshed, which would otherwise invalidate the provider KV cache prefix on
+ * every turn even when the underlying file structure is identical. (#847)
+ */
+export function stripVolatileCodebaseMetadata(content) {
+    return content
+        .split("\n")
+        .filter((line) => {
+        const trimmed = line.trimStart();
+        return !trimmed.startsWith("Generated:") && !trimmed.startsWith("<!-- gsd:codebase-meta");
+    })
+        .join("\n")
+        .trim();
+}
 function warnDeprecatedAgentInstructions() {
     const paths = [
         join(gsdHome(), "agent-instructions.md"),
@@ -78,45 +100,93 @@ function warnDeprecatedAgentInstructions() {
         }
     }
 }
-export async function buildBeforeAgentStartResult(event, ctx) {
-    if (!existsSync(join(process.cwd(), ".gsd")))
-        return undefined;
-    const stopContextTimer = debugTime("context-inject");
-    const systemContent = loadPrompt("system", {
-        templatesDir: getTemplatesDir(),
-        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
-        shortcutShell: formatShortcut("Ctrl+Alt+B"),
-    });
-    let loadedPreferences = loadEffectiveGSDPreferences();
-    try {
-        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
-        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-            markCmuxPromptShown();
-            if (autoEnableCmuxPreferences()) {
-                loadedPreferences = loadEffectiveGSDPreferences();
-                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
-            }
+async function runSessionStartupMaintenanceOnce(basePath, ctx) {
+    const maintenanceKey = getContextMaintenanceKey(basePath, ctx);
+    if (contextMaintenanceCompletedForSession.has(maintenanceKey)) {
+        // Backfills are session-once, but memory queries and other DB-backed
+        // prompt assembly still need an active adapter on every turn.
+        try {
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen(basePath);
         }
+        catch (e) {
+            logWarning("bootstrap", `project DB open failed: ${e.message}`);
+        }
+        return false;
+    }
+    const existing = contextMaintenanceInFlightBySession.get(maintenanceKey);
+    const isInitiator = !existing;
+    // Use a definite Promise<boolean> so `await inFlight` has a known return type.
+    let inFlight;
+    if (isInitiator) {
+        inFlight = performSessionStartupMaintenance(basePath, ctx, maintenanceKey);
+        contextMaintenanceInFlightBySession.set(maintenanceKey, inFlight);
+        void inFlight.finally(() => {
+            if (contextMaintenanceInFlightBySession.get(maintenanceKey) === inFlight) {
+                contextMaintenanceInFlightBySession.delete(maintenanceKey);
+            }
+        });
+    }
+    else {
+        inFlight = existing;
+    }
+    const result = await inFlight;
+    return isInitiator ? result : false;
+}
+async function performSessionStartupMaintenance(basePath, ctx, maintenanceKey) {
+    // DB-backed memory backfills run below. On a cold session the database file
+    // may exist without an active in-process adapter, so open the canonical
+    // project DB before those best-effort operations inspect it.
+    let dbOpen = false;
+    try {
+        const { ensureDbOpen } = await import("./dynamic-tools.js");
+        dbOpen = await ensureDbOpen(basePath);
     }
     catch (e) {
-        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+        logWarning("bootstrap", `project DB open failed before memory projection: ${e.message}`);
+    }
+    if (!dbOpen)
+        return false;
+    // These backfills are independent idempotent migrations. Keep them on the
+    // startup path because their rows can affect the MEMORY block for this turn,
+    // but do not make their import/IO latencies add serially.
+    await Promise.allSettled([
+        runDecisionsMemoryBackfill(ctx),
+        runKnowledgeMemoryBackfill(basePath, ctx),
+    ]);
+    // Mark session complete before scheduling deferred work so any concurrent
+    // caller that observes the completed state does not re-enter maintenance.
+    contextMaintenanceCompletedForSession.add(maintenanceKey);
+    scheduleDeferredContextMaintenance(basePath, maintenanceKey);
+    return true;
+}
+function getContextMaintenanceKey(basePath, ctx) {
+    return `${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}${getContextSessionPart(ctx)}`;
+}
+function getContextSessionPart(ctx) {
+    const sessionManager = ctx.sessionManager;
+    try {
+        const sessionId = sessionManager?.getSessionId?.();
+        if (typeof sessionId === "string" && sessionId.length > 0)
+            return `id:${sessionId}`;
     }
-    const ctxProjectRoot = ctx.projectRoot;
-    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
-        ? ctxProjectRoot
-        : process.cwd();
-    let preferenceBlock = "";
-    if (loadedPreferences) {
-        const cwd = basePath;
-        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
-        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
-        if (report.warnings.length > 0) {
-            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
-        }
+    catch (e) {
+        logWarning("bootstrap", `session-id fetch failed: ${e.message}`);
+    }
+    try {
+        const sessionFile = sessionManager?.getSessionFile?.();
+        if (typeof sessionFile === "string" && sessionFile.length > 0)
+            return `file:${sessionFile}`;
     }
+    catch (e) {
+        logWarning("bootstrap", `session-file fetch failed: ${e.message}`);
+    }
+    return "process";
+}
+async function runDecisionsMemoryBackfill(ctx) {
     // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
     // and best-effort — first run absorbs the existing decisions table into
-    // the memory store; subsequent runs are a single sentinel SELECT.
+    // the memory store; repeated turns skip this session-once maintenance.
     try {
         const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
         const written = backfillDecisionsToMemories();
@@ -127,10 +197,11 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
-    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
-    // re-render the hybrid projection (manual Rules + projected Patterns +
-    // projected Lessons). Both are idempotent and best-effort — failures here
-    // can't block agent startup.
+}
+async function runKnowledgeMemoryBackfill(basePath, ctx) {
+    // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill. Idempotent
+    // and best-effort — first run migrates rows into memories; repeated turns
+    // skip this session-once maintenance.
     try {
         const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
         const writtenK = backfillKnowledgeToMemories(basePath);
@@ -141,6 +212,32 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${e.message}`);
     }
+}
+function scheduleDeferredContextMaintenance(basePath, maintenanceKey) {
+    if (deferredContextMaintenanceBySession.has(maintenanceKey))
+        return;
+    const task = new Promise((resolve) => {
+        setTimeout(() => {
+            void runDeferredContextMaintenance(basePath).finally(resolve);
+        }, 0);
+    });
+    deferredContextMaintenanceBySession.set(maintenanceKey, task);
+    void task.finally(() => {
+        if (deferredContextMaintenanceBySession.get(maintenanceKey) === task) {
+            deferredContextMaintenanceBySession.delete(maintenanceKey);
+        }
+    });
+}
+async function runDeferredContextMaintenance(basePath) {
+    // Projection rendering and consolidation-gap reporting do not contribute to
+    // the returned system prompt. Run them after startup context is assembled so
+    // their DB/file scans do not block the first response.
+    await Promise.allSettled([
+        renderKnowledgeProjectionDeferred(basePath),
+        reportConsolidationGapsDeferred(basePath),
+    ]);
+}
+async function renderKnowledgeProjectionDeferred(basePath) {
     try {
         const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
         renderKnowledgeProjection(basePath);
@@ -148,9 +245,8 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${e.message}`);
     }
-    // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
-    // yet in the memories table. Read-only; never throws. Runs after the two
-    // backfills above so the gap report reflects post-backfill state.
+}
+async function reportConsolidationGapsDeferred(basePath) {
     try {
         const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
         reportConsolidationGaps(basePath);
@@ -158,6 +254,52 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     catch (e) {
         logWarning("bootstrap", `memory consolidation scan failed: ${e.message}`);
     }
+}
+export async function _flushDeferredContextMaintenanceForTest(basePath) {
+    const tasks = basePath
+        ? [...deferredContextMaintenanceBySession.entries()]
+            .filter(([key]) => key.startsWith(`${basePath}${CONTEXT_MAINTENANCE_KEY_SEPARATOR}`))
+            .map(([, task]) => task)
+        : [...deferredContextMaintenanceBySession.values()];
+    await Promise.allSettled(tasks);
+}
+export async function buildBeforeAgentStartResult(event, ctx) {
+    if (!existsSync(join(process.cwd(), ".gsd")))
+        return undefined;
+    const stopContextTimer = debugTime("context-inject");
+    const systemContent = loadPrompt("system", {
+        templatesDir: getTemplatesDir(),
+        shortcutDashboard: formatShortcut("Ctrl+Alt+G"),
+        shortcutShell: formatShortcut("Ctrl+Alt+B"),
+    });
+    let loadedPreferences = loadEffectiveGSDPreferences();
+    try {
+        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            if (autoEnableCmuxPreferences()) {
+                loadedPreferences = loadEffectiveGSDPreferences();
+                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+            }
+        }
+    }
+    catch (e) {
+        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    }
+    const ctxProjectRoot = ctx.projectRoot;
+    const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+        ? ctxProjectRoot
+        : process.cwd();
+    let preferenceBlock = "";
+    if (loadedPreferences) {
+        const cwd = basePath;
+        const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
+        preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions, { includeResolvedPaths: false })}`;
+        if (report.warnings.length > 0) {
+            ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
+        }
+    }
+    await runSessionStartupMaintenanceOnce(basePath, ctx);
     const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
@@ -180,16 +322,21 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     const rawCodebase = readCodebaseMap(process.cwd());
     if (existsSync(codebasePath) && rawCodebase) {
         try {
-            const rawContent = rawCodebase.trim();
+            // Strip the volatile `Generated: <timestamp>` header line and the
+            // machine-readable `gsd:codebase-meta` comment before injecting. Both
+            // embed a per-regeneration timestamp/fingerprint; because this block
+            // rides the cached system-prompt prefix, leaving the timestamp in would
+            // invalidate the provider KV cache on every map refresh even when the
+            // file structure is unchanged. The full map (with timestamp) remains at
+            // .gsd/CODEBASE.md. (#847)
+            const rawContent = stripVolatileCodebaseMetadata(rawCodebase.trim());
             if (rawContent) {
                 // Cap injection size to ~2 000 tokens to avoid bloating every request.
                 // Full map is always available at .gsd/CODEBASE.md.
-                const generatedMatch = rawContent.match(/Generated: (\S+)/);
-                const generatedAt = generatedMatch?.[1] ?? "unknown";
                 const content = rawContent.length > DEFAULT_CODEBASE_MAX_CHARS
                     ? rawContent.slice(0, DEFAULT_CODEBASE_MAX_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
                     : rawContent;
-                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
+                codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
             }
         }
         catch (e) {

package/dist/resources/extensions/gsd/bootstrap/tool-call-loop-guard.js

@@ -1,25 +1,57 @@
 /**
  * Tool-call loop guard.
  *
- * Detects when a model calls the same tool with identical arguments
- * repeatedly within a single agent turn. Works in both auto-mode and
- * interactive sessions by hooking into the `tool_call` event, which
- * fires before execution and can block the call.
+ * Detects when a model repeats tool calls within a single Agent Turn.
+ * Works in both auto-mode and interactive sessions by hooking into the
+ * native engine's `tool_call` event, which fires before execution and can
+ * block the call.
  *
- * The guard uses a sliding window: it tracks the last N tool signatures
- * and blocks when the same signature appears more than MAX_CONSECUTIVE
- * times in a row. Resets on each agent turn (session_start, agent_end)
- * and when a different tool call breaks the streak.
+ * The guard has two independent checks: a sliding window for identical
+ * tool signatures, and a per-tool-name cap for repeated calls with varied
+ * arguments. State resets at Agent Turn boundaries (session_start,
+ * agent_end) and the identical-signature streak also resets when a
+ * different tool call breaks the streak. Block messages instruct the model
+ * to stop tooling for the rest of that turn and answer in text.
+ *
+ * The per-tool-name check (#783 Brief C) tracks call counts within a
+ * turn regardless of args, decaying after successful state-mutating tools.
+ * This catches improvisation
+ * loops where the model attempts the same missing workflow tool through
+ * varied surfaces (bash → `node -e` → CLI), each with a different
+ * signature, so the identical-args streak never trips, while allowing
+ * tool-heavy turns that are making file-mutation progress. Whichever guard
+ * trips first blocks.
  */
 import { createHash } from "node:crypto";
+import { INHERENTLY_REPEATABLE_TOOL_SET } from "./core-session-tools.js";
+import { hasBrowserContractPrefix } from "../../shared/browser-contract.js";
+import { canonicalToolName } from "../engine-hook-contract.js";
 const MAX_CONSECUTIVE_IDENTICAL_CALLS = 4;
 /** Interactive/user-facing tools where even 1 duplicate is confusing. */
 const STRICT_LOOP_TOOLS = new Set(["ask_user_questions"]);
 const MAX_CONSECUTIVE_STRICT = 1;
+/**
+ * Per-turn cap on calls to the SAME tool name, regardless of args (#783).
+ *
+ * General-purpose execution tools are routinely called many times per turn
+ * (touching multiple files, running several commands), so they get a higher
+ * ceiling. Everything else — workflow one-shot tools (e.g. gsd_complete_milestone)
+ * and any non-allowlisted tool — gets the default cap. The default is generous
+ * enough to absorb legitimate retries but catches the reported improvisation
+ * loop (~51 calls) well before a cost spike.
+ */
+const PER_TOOL_DEFAULT_CAP = 6;
+const PER_TOOL_REPEATABLE_CAP = 15;
+const PER_TOOL_CAP_EXEMPT_TOOLS = new Set(["find", "glob", "grep", "ls", "read", "search_and_read"]);
+const STATE_MUTATING_TOOL_SET = new Set(["edit", "write", "multi_edit", "notebook_edit"]);
 let consecutiveCount = 0;
 let lastSignature = "";
 let lastToolName = "";
 let enabled = true;
+/** Per-tool-name call counts within the current turn (#783 Brief C). */
+const perToolCounts = new Map();
+let mutationEpoch = 0;
+const perToolLastMutationEpoch = new Map();
 /** Hash tool name + args into a compact signature for comparison. */
 function hashToolCall(toolName, args) {
     const h = createHash("sha256");
@@ -38,6 +70,13 @@ function hashToolCall(toolName, args) {
  *
  * Returns `{ block: false }` for allowed calls.
  * Returns `{ block: true, reason }` when the loop threshold is exceeded.
+ *
+ * Two independent guards run; whichever trips first blocks:
+ *  1. Identical-signature streak (MAX_CONSECUTIVE_IDENTICAL_CALLS, strict for
+ *     ask_user_questions).
+ *  2. Per-tool-name cap (PER_TOOL_DEFAULT_CAP / PER_TOOL_REPEATABLE_CAP),
+ *     independent of args, reset after file-mutation progress — catches
+ *     improvisation loops (#783).
  */
 export function checkToolCallLoop(toolName, args) {
     if (!enabled)
@@ -51,26 +90,71 @@ export function checkToolCallLoop(toolName, args) {
         lastSignature = sig;
         lastToolName = toolName;
     }
+    // ── Guard 1: identical-signature streak ──
     const threshold = STRICT_LOOP_TOOLS.has(toolName)
         ? MAX_CONSECUTIVE_STRICT
         : MAX_CONSECUTIVE_IDENTICAL_CALLS;
     if (consecutiveCount > threshold) {
         return {
             block: true,
-            reason: `Tool loop detected: ${toolName} called ${consecutiveCount} times ` +
+            reason: `Tool loop detected (identical args): ${toolName} called ${consecutiveCount} times ` +
                 `with identical arguments. Blocking to prevent infinite loop. ` +
-                `Try a different approach or modify your arguments.`,
+                `Do not retry this tool or call other tools this turn — stop and respond to the user in text.`,
             count: consecutiveCount,
         };
     }
+    // ── Guard 2: per-tool-name cap, independent of args (#783 Brief C) ──
+    // Catches improvisation loops where the same tool is invoked many times with
+    // varied args (e.g. retrying a missing workflow tool via bash/node -e/CLI).
+    const priorPerToolCount = (perToolLastMutationEpoch.get(toolName) ?? mutationEpoch) < mutationEpoch
+        ? 0
+        : (perToolCounts.get(toolName) ?? 0);
+    const perToolCount = priorPerToolCount + 1;
+    perToolCounts.set(toolName, perToolCount);
+    perToolLastMutationEpoch.set(toolName, mutationEpoch);
+    // Read-only navigation tools are normal context gathering; Guard 1 still
+    // catches true reread loops with identical arguments. Browser Automation
+    // Contract tools (browser_*) are the same shape: a browser-backed UAT makes
+    // many distinct-arg calls (read a message, count edits, inspect a card, …),
+    // so the arg-independent per-tool cap misfires on legitimate verification;
+    // Guard 1's identical-signature streak still catches a genuinely stuck
+    // browser loop.
+    if (PER_TOOL_CAP_EXEMPT_TOOLS.has(toolName) ||
+        hasBrowserContractPrefix(canonicalToolName(toolName))) {
+        return { block: false, count: consecutiveCount };
+    }
+    const perToolCap = INHERENTLY_REPEATABLE_TOOL_SET.has(toolName)
+        ? PER_TOOL_REPEATABLE_CAP
+        : PER_TOOL_DEFAULT_CAP;
+    if (perToolCount > perToolCap) {
+        return {
+            block: true,
+            reason: `Tool loop detected (repeated tool): ${toolName} called ${perToolCount} times ` +
+                `this turn (cap ${perToolCap}). Blocking to prevent infinite loop. ` +
+                `The tool may be unavailable or failing repeatedly. ` +
+                `Do not retry this tool or pivot to other tools this turn — stop and respond to the user in text.`,
+            count: perToolCount,
+        };
+    }
     return { block: false, count: consecutiveCount };
 }
+/** Record successful mutation progress so Guard 2 can decay on the next count. */
+export function recordToolCallLoopMutation(toolName) {
+    if (!enabled)
+        return;
+    if (!STATE_MUTATING_TOOL_SET.has(toolName))
+        return;
+    mutationEpoch++;
+}
 /** Reset the guard state. Call at agent turn boundaries. */
 export function resetToolCallLoopGuard() {
     consecutiveCount = 0;
     lastSignature = "";
     lastToolName = "";
     enabled = true;
+    perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Disable the guard (e.g. during shutdown). */
 export function disableToolCallLoopGuard() {
@@ -78,8 +162,18 @@ export function disableToolCallLoopGuard() {
     consecutiveCount = 0;
     lastSignature = "";
     lastToolName = "";
+    perToolCounts.clear();
+    mutationEpoch = 0;
+    perToolLastMutationEpoch.clear();
 }
 /** Get current consecutive count for diagnostics. */
 export function getToolCallLoopCount() {
     return consecutiveCount;
 }
+/**
+ * Get the per-tool-name call count for the current turn (#783 Brief C).
+ * Returns 0 for tools not yet called. Diagnostic only.
+ */
+export function getToolCallCountForTool(toolName) {
+    return perToolCounts.get(toolName) ?? 0;
+}

package/dist/resources/extensions/gsd/bootstrap/tool-search-shim.js

@@ -26,8 +26,27 @@ export function registerToolSearchShim(pi) {
             return new Text(theme.fg("warning", text), 0, 0);
         },
     });
-    const active = pi.getActiveTools();
-    if (!active.includes("ToolSearch")) {
-        pi.setActiveTools([...active, "ToolSearch"]);
+    // Ensure the shim is part of the active tool set. registerTool() is valid
+    // during extension loading, but getActiveTools()/setActiveTools() are stubs
+    // that throw "Extension runtime not initialized" until runner.bindCore() runs
+    // (after all registerExtension() calls return). When the throw was hit, the
+    // catch in register-extension.ts swallowed it — leaving the whole bootstrap
+    // partially failed and, under Claude Code CLI, the workflow tools could end
+    // up missing from the model's surface, which traps plan-milestone in a
+    // finalize-retry loop with no gsd_plan_milestone available.
+    //
+    // The activation here is also redundant post-bind: ToolSearch is in
+    // MINIMAL_AUTO_BASE_TOOL_NAMES, so buildMinimalAutoGsdToolSet adds it during
+    // adjust_tool_set (before_agent_start). Tolerate the loading-stub throw so
+    // the shim always registers; activation is completed by post-bind scoping.
+    try {
+        const active = pi.getActiveTools();
+        if (!active.includes("ToolSearch")) {
+            pi.setActiveTools([...active, "ToolSearch"]);
+        }
+    }
+    catch {
+        // Pre-bind runtime: getActiveTools/setActiveTools are not yet wired.
+        // The tool is registered; activation happens at adjust_tool_set.
     }
 }