gsd-pi 2.76.0-dev.82e249f7b → 2.76.0-dev.fe143342a

package/dist/mcp-server.d.ts

@@ -1,6 +1,11 @@
 /**
  * Minimal tool interface matching GSD's AgentTool shape.
  * Avoids a direct dependency on @gsd/pi-agent-core from this compiled module.
+ *
+ * `details` and `isError` are optional fields that runtime tool implementations
+ * may populate. The MCP transport drops non-standard fields, so the wrapper at
+ * the call site mirrors `details` into `structuredContent` and forwards
+ * `isError` directly. See #4472.
  */
 export interface McpToolDef {
     name: string;
@@ -13,6 +18,8 @@ export interface McpToolDef {
             data?: string;
             mimeType?: string;
         }>;
+        details?: Record<string, unknown>;
+        isError?: boolean;
     }>;
 }
 /**

package/dist/mcp-server.js

@@ -1,3 +1,21 @@
+/**
+ * Strict plain-object guard. True only for object literals and
+ * `Object.create(null)` — not for `Date`, `URL`, `Map`, `Set`, class instances,
+ * or arrays. Used to gate `structuredContent` forwarding so the MCP transport
+ * receives only true JSON objects (the protocol contract). See #4477 review.
+ *
+ * Mirrored in `packages/mcp-server/src/workflow-tools.ts` for the
+ * `adaptExecutorResult` adapter on the workflow path. Keep both copies in
+ * sync if the contract definition needs to evolve.
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
 // MCP SDK subpath imports use wildcard exports (./*) in @modelcontextprotocol/sdk's
 // package.json export map. The wildcard maps "./foo" → "./dist/cjs/foo" (no .js
 // suffix), so bare subpath specifiers like `${MCP_PKG}/server/stdio` resolve to
@@ -83,7 +101,23 @@ export async function startMcpServer(options) {
                 // by stringifying into a text block so clients see the payload.
                 return { type: 'text', text: JSON.stringify(block) };
             });
-            return { content };
+            // Forward a tool's runtime `details` field to MCP's `structuredContent`
+            // channel. The protocol drops non-standard fields on the wire, so tools
+            // that populate `details` for client-side renderers (e.g. save_gate_result)
+            // would otherwise arrive empty on the other side. See #4472.
+            //
+            // Use a strict plain-object guard (prototype-chain check) rather than just
+            // `typeof === 'object' && !Array.isArray()` — Date, URL, Map, Set, and
+            // class instances would otherwise pass through and end up as
+            // `structuredContent`, violating the protocol's JSON-object contract.
+            // The mirror discipline applies in `workflow-tools.ts adaptExecutorResult`.
+            const base = { content };
+            if (isPlainObject(result.details)) {
+                base.structuredContent = result.details;
+            }
+            if (result.isError === true)
+                base.isError = true;
+            return base;
         }
         catch (err) {
             // AbortError from a cancelled tool surfaces as a normal error — MCP

package/dist/resource-loader.d.ts

@@ -21,6 +21,6 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
-export declare function initResources(agentDir: string): void;
+export declare function initResources(agentDir: string, skillsDir?: string): void;
 export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir?: string): boolean;
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -506,7 +506,7 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
-export function initResources(agentDir) {
+export function initResources(agentDir, skillsDir = join(homedir(), '.agents', 'skills')) {
     mkdirSync(agentDir, { recursive: true });
     const currentVersion = getBundledGsdVersion();
     const manifest = readManagedResourceManifest(agentDir);
@@ -538,13 +538,7 @@ export function initResources(agentDir) {
     // Sync bundled resources — overwrite so updates land on next launch.
     syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
-    // Skills are no longer force-synced here. Users install skills via the
-    // skills.sh CLI (`npx skills add <repo>`) into ~/.agents/skills/ which
-    // is the industry-standard Agent Skills ecosystem directory.
-    //
-    // Migration from the legacy ~/.gsd/agent/skills/ directory is handled
-    // above the manifest check so it runs on every launch (including retries
-    // after partial copy failures).
+    syncResourceDir(join(resourcesDir, 'skills'), skillsDir);
     // Sync GSD-WORKFLOW.md to agentDir as a fallback for when GSD_WORKFLOW_PATH
     // env var is not set (e.g. fork/dev builds, alternative entry points).
     const workflowSrc = join(resourcesDir, 'GSD-WORKFLOW.md');

package/dist/resources/extensions/claude-code-cli/stream-adapter.js

@@ -637,6 +637,68 @@ function normalizeToolResultContent(content) {
     }
     return blocks.length > 0 ? blocks : [{ type: "text", text: "" }];
 }
+/**
+ * Extract a `details` payload from an MCP tool-result block.
+ *
+ * MCP's `CallToolResult` carries structured data in `structuredContent` — the
+ * protocol's supported channel for non-text payloads. Claude Code's synthetic
+ * user message may surface that field in one of two shapes depending on SDK
+ * version: as a sibling on the `mcp_tool_result` block itself, or as a
+ * dedicated content sub-block with `type: "structuredContent"`. Snake-case
+ * (`structured_content`) is accepted defensively in case a transport hop
+ * rewrites casing. All other shapes fall back to an empty object so callers
+ * can rely on `details` being present.
+ */
+function extractStructuredDetailsFromBlock(block) {
+    const sibling = block.structuredContent ?? block.structured_content;
+    if (sibling && typeof sibling === "object" && !Array.isArray(sibling)) {
+        return sibling;
+    }
+    if (Array.isArray(block.content)) {
+        for (const item of block.content) {
+            if (!item || typeof item !== "object")
+                continue;
+            const sub = item;
+            if (sub.type !== "structuredContent" && sub.type !== "structured_content")
+                continue;
+            const payload = sub.structuredContent ?? sub.structured_content ?? sub.data ?? sub.value;
+            if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                return payload;
+            }
+        }
+    }
+    // Return undefined (not {}) when no structured payload is present, matching
+    // the pre-#4477 contract where `details` was nullable. An empty-object
+    // sentinel is truthy and breaks downstream consumers that gate on
+    // `if (details)`. `undefined` matches the type of the field these results
+    // flow into (`Record<string, unknown> | undefined`).
+    return undefined;
+}
+/**
+ * True for items that are MCP `structuredContent` pseudo-blocks living inside
+ * a tool-result `content[]` array. These blocks carry the structured payload
+ * (extracted separately by `extractStructuredDetailsFromBlock`) and must NOT
+ * leak into the visible content rendered to the user — otherwise the renderer
+ * stringifies the JSON pseudo-block and shows it next to the actual tool
+ * output. See PR #4477 review (CodeRabbit, post-fix-round).
+ */
+function isStructuredContentPseudoBlock(item) {
+    if (!item || typeof item !== "object")
+        return false;
+    const type = item.type;
+    return type === "structuredContent" || type === "structured_content";
+}
+/**
+ * Strip `structuredContent` pseudo-blocks from a tool-result content array
+ * before normalization. The structured payload is extracted via the sibling
+ * `structuredContent` field (or a dedicated extractor pass on the raw block);
+ * the visible content path must not include the pseudo-block itself.
+ */
+function stripStructuredContentPseudoBlocks(content) {
+    if (!Array.isArray(content))
+        return content;
+    return content.filter((item) => !isStructuredContentPseudoBlock(item));
+}
 /** Extract tool result payloads from an SDK synthetic user message, keyed by tool-use ID. */
 export function extractToolResultsFromSdkUserMessage(message) {
     const extracted = [];
@@ -657,8 +719,8 @@ export function extractToolResultsFromSdkUserMessage(message) {
         extracted.push({
             toolUseId,
             result: {
-                content: normalizeToolResultContent(block.content),
-                details: {},
+                content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(block.content)),
+                details: extractStructuredDetailsFromBlock(block),
                 isError: block.is_error === true,
             },
         });
@@ -672,8 +734,8 @@ export function extractToolResultsFromSdkUserMessage(message) {
                 extracted.push({
                     toolUseId,
                     result: {
-                        content: normalizeToolResultContent(toolResult.content),
-                        details: {},
+                        content: normalizeToolResultContent(stripStructuredContentPseudoBlocks(toolResult.content)),
+                        details: extractStructuredDetailsFromBlock(toolResult),
                         isError: toolResult.is_error === true,
                     },
                 });

package/dist/resources/extensions/gsd/auto-start.js

@@ -30,7 +30,7 @@ import { initRoutingHistory } from "./routing-history.js";
 import { restoreHookState, resetHookState } from "./post-unit-hooks.js";
 import { resetProactiveHealing, setLevelChangeCallback } from "./doctor-proactive.js";
 import { snapshotSkills } from "./skill-discovery.js";
-import { isDbAvailable, getMilestone, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestone, openDatabase, getDbStatus } from "./gsd-db.js";
 import { hideFooter } from "./auto-dashboard.js";
 import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath, } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -247,7 +247,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // the parent git root). See #2393 and related issue.
         const hasLocalGit = existsSync(join(base, ".git"));
         if (!hasLocalGit || isInheritedRepo(base)) {
-            const mainBranch = loadEffectiveGSDPreferences()?.preferences?.git?.main_branch || "main";
+            const mainBranch = loadEffectiveGSDPreferences(base)?.preferences?.git?.main_branch || "main";
             nativeInit(base, mainBranch);
         }
         // Migrate legacy in-project .gsd/ to external state directory.
@@ -263,7 +263,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Ensure .gitignore has baseline patterns.
         // ensureGitignore checks for git-tracked .gsd/ files and skips the
         // ".gsd" pattern if the project intentionally tracks .gsd/ in git.
-        const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git;
+        const gitPrefs = loadEffectiveGSDPreferences(base)?.preferences?.git;
         const manageGitignore = gitPrefs?.manage_gitignore;
         ensureGitignore(base, { manageGitignore });
         if (manageGitignore !== false)
@@ -289,7 +289,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             prepareWorkflowMcpForProject(ctx, base);
         }
         // Initialize GitServiceImpl
-        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences(base)?.preferences?.git ?? {});
         // ── Debug mode ──
         if (!isDebugEnabled() && process.env.GSD_DEBUG === "1") {
             enableDebug(base);
@@ -322,7 +322,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // was lost due to session ending between completion and teardown.
         // Must run after DB open and before worktree entry.
         try {
-            const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode());
+            const auditResult = auditOrphanedMilestoneBranches(base, getIsolationMode(base));
             for (const msg of auditResult.recovered) {
                 ctx.ui.notify(`Orphan audit: ${msg}`, "info");
             }
@@ -340,7 +340,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         let state = await deriveState(base);
         // Stale worktree state recovery (#654)
         if (state.activeMilestone &&
-            shouldUseWorktreeIsolation() &&
+            shouldUseWorktreeIsolation(base) &&
             !detectWorktreeName(base)) {
             const wtPath = getAutoWorktreePath(base, state.activeMilestone.id);
             if (wtPath) {
@@ -355,7 +355,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         let hasSurvivorBranch = false;
         if (state.activeMilestone &&
             (state.phase === "pre-planning" || state.phase === "complete") &&
-            getIsolationMode() !== "none" &&
+            getIsolationMode(base) !== "none" &&
             !detectWorktreeName(base) &&
             !base.includes(`${pathSep}.gsd${pathSep}worktrees${pathSep}`)) {
             const milestoneBranch = `milestone/${state.activeMilestone.id}`;
@@ -516,7 +516,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         registerSigtermHandler(base);
         // Capture integration branch
         if (s.currentMilestoneId) {
-            if (getIsolationMode() !== "none") {
+            if (getIsolationMode(base) !== "none") {
                 captureIntegrationBranch(base, s.currentMilestoneId);
             }
             setActiveMilestoneId(base, s.currentMilestoneId);
@@ -524,7 +524,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // Guard against stale milestone branch when isolation:none (#3613).
         // A prior session with isolation:branch/worktree may have left HEAD on
         // milestone/<MID>. Auto-checkout back to the integration branch.
-        if (getIsolationMode() === "none" && nativeIsRepo(base)) {
+        if (getIsolationMode(base) === "none" && nativeIsRepo(base)) {
             try {
                 const currentBranch = nativeGetCurrentBranch(base);
                 if (currentBranch.startsWith("milestone/")) {
@@ -552,7 +552,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             return symlinkRe.test(p);
         };
         if (s.currentMilestoneId &&
-            getIsolationMode() !== "none" &&
+            getIsolationMode(base) !== "none" &&
             !detectWorktreeName(base) &&
             !isUnderGsdWorktrees(base)) {
             buildResolver().enterMilestone(s.currentMilestoneId, {
@@ -597,8 +597,21 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // call returns "db_unavailable", triggering artifact-retry which
         // re-dispatches the same task — producing an infinite loop (#2419).
         if (existsSync(gsdDbPath) && !isDbAvailable()) {
-            ctx.ui.notify("SQLite database exists but failed to open. Auto-mode cannot proceed without a working database provider. " +
-                "Check for corrupt gsd.db or missing native SQLite bindings.", "error");
+            const dbStatus = getDbStatus();
+            const phaseHint = dbStatus.lastPhase === "open"
+                ? "The database file could not be opened"
+                : dbStatus.lastPhase === "initSchema"
+                    ? "The database schema could not be initialized"
+                    : dbStatus.lastPhase === "vacuum-recovery"
+                        ? "Corruption recovery (VACUUM) failed"
+                        : dbStatus.attempted
+                            ? "The database could not be opened (phase unknown)"
+                            : "The database provider could not be loaded";
+            const errorDetail = dbStatus.lastError ? ` (${dbStatus.lastError.message})` : "";
+            const providerHint = dbStatus.provider
+                ? ` Provider: ${dbStatus.provider}.`
+                : " No SQLite provider available — check Node >= 22 or install better-sqlite3.";
+            ctx.ui.notify(`SQLite database exists but failed to open: ${gsdDbPath}. ${phaseHint}${errorDetail}.${providerHint}`, "error");
             return releaseLockAndReturn();
         }
         // Initialize metrics
@@ -633,7 +646,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // Snapshot installed skills
-        if (resolveSkillDiscoveryMode() !== "off") {
+        if (resolveSkillDiscoveryMode(base) !== "off") {
             snapshotSkills();
         }
         ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
@@ -661,7 +674,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
         // FlatRateContext used by selectAndApplyModel so user-declared
         // flat-rate providers and externalCli auto-detection are respected.
         const { isFlatRateProvider, buildFlatRateContext } = await import("./auto-model-selection.js");
-        const bannerPrefs = loadEffectiveGSDPreferences()?.preferences;
+        const bannerPrefs = loadEffectiveGSDPreferences(base)?.preferences;
         const effectiveProvider = s.autoModeStartModel?.provider ?? ctx.model?.provider;
         const effectivelyEnabled = routingConfig.enabled
             && (routingConfig.allow_flat_rate_providers

package/dist/resources/extensions/gsd/auto.js

@@ -145,8 +145,8 @@ export function startAutoDetached(ctx, pi, base, verboseMode, options) {
     });
 }
 /** Returns true if the project is configured for `isolation:worktree` mode. */
-export function shouldUseWorktreeIsolation() {
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function shouldUseWorktreeIsolation(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     if (prefs?.isolation === "worktree")
         return true;
     // Default is false — worktree isolation requires explicit opt-in
@@ -215,7 +215,7 @@ export function getAutoDashboardData() {
     const rtkSavings = sessionId && s.basePath
         ? getRtkSessionSavings(s.basePath, sessionId)
         : null;
-    const rtkEnabled = loadEffectiveGSDPreferences()?.preferences.experimental?.rtk === true;
+    const rtkEnabled = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences.experimental?.rtk === true;
     // Pending capture count — lazy check, non-fatal
     let pendingCaptureCount = 0;
     try {
@@ -393,7 +393,7 @@ function clearUnitTimeout() {
 }
 /** Build snapshot metric opts. */
 function buildSnapshotOpts(_unitType, _unitId) {
-    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const prefs = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
     const uokFlags = resolveUokFlags(prefs);
     return {
         ...(s.autoStartTime > 0 ? { autoSessionKey: String(s.autoStartTime) } : {}),
@@ -427,7 +427,7 @@ function handleLostSessionLock(ctx, lockStatus) {
     restoreProjectRootEnv();
     restoreMilestoneLockEnv();
     deregisterSigtermHandler();
-    clearCmuxSidebar(loadEffectiveGSDPreferences()?.preferences);
+    clearCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences);
     const base = lockBase();
     const lockFilePath = base ? join(gsdRoot(base), "auto.lock") : "unknown";
     const recoverySuggestion = "\nTo recover, run: gsd doctor --fix";
@@ -498,7 +498,7 @@ function cleanupAfterLoopExit(ctx) {
 export async function stopAuto(ctx, pi, reason) {
     if (!s.active && !s.paused)
         return;
-    const loadedPreferences = loadEffectiveGSDPreferences()?.preferences;
+    const loadedPreferences = loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences;
     const reasonSuffix = reason ? ` — ${reason}` : "";
     try {
         // ── Step 1: Timers and locks ──
@@ -1164,7 +1164,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         });
         // ── Auto-worktree / branch-mode: re-enter on resume ──
         if (s.currentMilestoneId &&
-            getIsolationMode() !== "none" &&
+            getIsolationMode(s.originalBasePath || s.basePath) !== "none" &&
             s.originalBasePath &&
             !isInAutoWorktree(s.basePath) &&
             !detectWorktreeName(s.basePath) &&
@@ -1197,7 +1197,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         await openProjectDbIfPresent(s.basePath);
         try {
             await rebuildState(s.basePath);
-            syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
+            syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
         }
         catch (e) {
             debugLog("resume-rebuild-state-failed", {
@@ -1227,7 +1227,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         }
         updateSessionLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
         writeLock(lockBase(), "resuming", s.currentMilestoneId ?? "unknown");
-        logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
+        logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "progress");
         captureProjectRootEnv(s.originalBasePath || s.basePath);
         startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
@@ -1253,13 +1253,13 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         return;
     captureProjectRootEnv(s.originalBasePath || s.basePath);
     try {
-        syncCmuxSidebar(loadEffectiveGSDPreferences()?.preferences, await deriveState(s.basePath));
+        syncCmuxSidebar(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, await deriveState(s.basePath));
     }
     catch (err) {
         // Best-effort only — sidebar sync must never block auto-mode startup
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
-    logCmuxEvent(loadEffectiveGSDPreferences()?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
+    logCmuxEvent(loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, requestedStepMode ? "Step-mode started." : "Auto-mode started.", "progress");
     startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
     await runAutoLoopWithUok({

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -19,6 +19,18 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+/**
+ * Read a tool result's structured payload, accommodating MCP's `details` →
+ * `structuredContent` rename (#4472, #4477). In-process executions still
+ * deliver the payload on `result.details`; MCP-routed executions deliver it
+ * on `result.structuredContent` (post `adaptExecutorResult` transform). All
+ * `renderResult` callbacks in this file route through this helper so a future
+ * field rename only needs to be applied in one place.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
+function readDetails(result) {
+    return result?.details ?? result?.structuredContent;
+}
 export function registerDbTools(pi) {
     // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
     const decisionSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
@@ -92,7 +104,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -175,7 +187,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -255,7 +267,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -301,7 +313,7 @@ export function registerDbTools(pi) {
             return new Text(text, 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -382,7 +394,7 @@ export function registerDbTools(pi) {
             return new Text(theme.fg("toolTitle", theme.bold("milestone_generate_id")), 0, 0);
         },
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
                 return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
             }
@@ -967,13 +979,31 @@ export function registerDbTools(pi) {
             text += theme.fg("dim", ` → ${args.verdict ?? ""}`);
             return new Text(text, 0, 0);
         },
+        /**
+         * Render the save_gate_result tool output for the TUI.
+         *
+         * Prefers structured fields, but falls back to `content[0].text` when the
+         * structured payload is empty. Defensive: the structural fix on this
+         * branch plumbs `details` through MCP via `structuredContent`, but older
+         * hosts, a future handler that forgets `structuredContent`, or any drop
+         * of non-standard return fields would otherwise render as
+         * "undefined: undefined". Same fallback applies to error rendering, and
+         * we strip a leading `Error:` from the fallback text to avoid producing
+         * `Error: Error: ...`.
+         */
         renderResult(result, _options, theme) {
-            const d = result.details;
+            const d = readDetails(result);
             if (result.isError || d?.error) {
-                return new Text(theme.fg("error", `Error: ${d?.error ?? "unknown"}`), 0, 0);
+                const rawMsg = d?.error ?? result.content?.[0]?.text ?? "unknown";
+                const msg = rawMsg.replace(/^\s*Error:\s*/i, "");
+                return new Text(theme.fg("error", `Error: ${msg}`), 0, 0);
+            }
+            if (!d?.gateId || !d?.verdict) {
+                const text = result.content?.[0]?.text ?? "Gate result saved";
+                return new Text(theme.fg("success", text), 0, 0);
             }
-            const color = d?.verdict === "flag" ? "warning" : "success";
-            return new Text(theme.fg(color, `${d?.gateId}: ${d?.verdict}`), 0, 0);
+            const color = d.verdict === "flag" ? "warning" : "success";
+            return new Text(theme.fg(color, `${d.gateId}: ${d.verdict}`), 0, 0);
         },
     };
     pi.registerTool(saveGateResultTool);

package/dist/resources/extensions/gsd/bootstrap/exec-tools.js

@@ -0,0 +1,93 @@
+// GSD2 — Exec (context-mode) tool registration.
+//
+// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
+// `context_mode.enabled: true` is set in preferences.
+import { Type } from "@sinclair/typebox";
+import { executeGsdExec } from "../tools/exec-tool.js";
+import { executeExecSearch } from "../tools/exec-search-tool.js";
+import { executeResume } from "../tools/resume-tool.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { logWarning } from "../workflow-logger.js";
+export function registerExecTools(pi) {
+    pi.registerTool({
+        name: "gsd_exec",
+        label: "Exec (Sandboxed)",
+        description: "Run a short script (bash/node/python) in a subprocess. Full stdout/stderr persist to " +
+            ".gsd/exec/<id>.{stdout,stderr,meta.json}; only a short digest returns in context. Use " +
+            "this instead of reading many files or emitting large tool outputs — e.g. have the script " +
+            "count/grep/summarize and log the finding. Enabled by default; opt out via " +
+            "preferences.context_mode.enabled=false.",
+        promptSnippet: "Run a bash/node/python script in a sandbox; full output is saved to disk and only a digest returns",
+        promptGuidelines: [
+            "Prefer gsd_exec for analyses that would otherwise read >3 files or produce large tool output.",
+            "Write scripts that log the finding (counts, matches, summaries) rather than raw dumps.",
+            "The digest is the last ~300 chars of stdout — size your log output accordingly.",
+            "Need the full output? Read the stdout_path returned in details (file on local disk).",
+        ],
+        parameters: Type.Object({
+            runtime: Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], { description: "Interpreter: bash (-c), node (-e), or python3 (-c)." }),
+            script: Type.String({ description: "Script body. Keep output small (log the finding, not the data)." }),
+            purpose: Type.Optional(Type.String({ description: "Short label recorded in meta.json for later review." })),
+            timeout_ms: Type.Optional(Type.Number({
+                description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+                minimum: 1_000,
+                maximum: 600_000,
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            let prefs = null;
+            try {
+                prefs = loadEffectiveGSDPreferences();
+            }
+            catch (err) {
+                logWarning("tool", `gsd_exec could not load preferences: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return executeGsdExec(params, {
+                baseDir: process.cwd(),
+                preferences: prefs?.preferences ?? null,
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_exec_search",
+        label: "Search gsd_exec History",
+        description: "List prior gsd_exec runs (most recent first) from .gsd/exec/*.meta.json. Useful for " +
+            "rediscovering the stdout_path of an earlier run without re-executing it. Read-only.",
+        promptSnippet: "Search prior gsd_exec runs by substring, runtime, or failing-only filter",
+        promptGuidelines: [
+            "Use this before re-running an expensive analysis — the prior run's stdout file may still answer.",
+            "The preview shows the trailing ~300 chars of stdout; read stdout_path for the full transcript.",
+        ],
+        parameters: Type.Object({
+            query: Type.Optional(Type.String({ description: "Substring matched against id and purpose (case-insensitive)." })),
+            runtime: Type.Optional(Type.Union([Type.Literal("bash"), Type.Literal("node"), Type.Literal("python")], {
+                description: "Restrict to one runtime.",
+            })),
+            failing_only: Type.Optional(Type.Boolean({ description: "Only non-zero exit codes and timeouts." })),
+            limit: Type.Optional(Type.Number({ description: "Max results (default 20, cap 200)", minimum: 1, maximum: 200 })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeExecSearch(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+    pi.registerTool({
+        name: "gsd_resume",
+        label: "Resume (Read Snapshot)",
+        description: "Return the contents of .gsd/last-snapshot.md — a ≤2 KB digest of top memories, recent " +
+            "gsd_exec runs, and active context, written automatically on session_before_compact. Use " +
+            "this after compaction or session resume to re-orient quickly.",
+        promptSnippet: "Read the pre-compaction snapshot to re-orient after context loss",
+        promptGuidelines: [
+            "Call this right after a session resumes if you feel you've lost durable context.",
+            "The snapshot is a summary — use memory_query or gsd_exec_search for detail.",
+        ],
+        parameters: Type.Object({}),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            return executeResume(params, {
+                baseDir: process.cwd(),
+            });
+        },
+    });
+}

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

@@ -4,6 +4,7 @@ import { registerWorktreeCommand } from "../worktree-command.js";
 import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerExecTools } from "./exec-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
 import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
@@ -86,6 +87,7 @@ export function registerGsdExtension(pi) {
         ["journal-tools", () => registerJournalTools(pi)],
         ["query-tools", () => registerQueryTools(pi)],
         ["memory-tools", () => registerMemoryTools(pi)],
+        ["exec-tools", () => registerExecTools(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
         ["hooks", () => registerHooks(pi, ecosystemHandlers)],
         ["ecosystem", () => {