gsd-pi 2.79.0 → 2.80.0-dev.c5f2443b3

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd-build/mcp-server",
-  "version": "2.79.0",
+  "version": "2.80.0",
   "description": "MCP server exposing GSD orchestration tools for Claude Code, Cursor, and other MCP clients",
   "license": "MIT",
   "gsd": {
@@ -34,8 +34,9 @@
     "test": "npm run build:test && node --test dist/mcp-server.test.js dist/remote-questions.test.js"
   },
   "dependencies": {
+    "@gsd-build/contracts": "^2.80.0",
+    "@gsd-build/rpc-client": "^2.80.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@gsd-build/rpc-client": "^2.79.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/packages/mcp-server/src/mcp-server.test.ts

@@ -882,6 +882,144 @@ describe('createMcpServer tool registration', () => {
     );
   });
 
+  it('ask_user_questions persists confirmed depth gates for local answers', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M003_confirm',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    const calls: string[] = [];
+    const writeGate = {
+      isGateQuestionId(questionId: string) {
+        return questionId.startsWith('depth_verification_');
+      },
+      isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>) {
+        return selected === options?.[0]?.label;
+      },
+      setPendingGate(gateId: string, basePath: string) {
+        calls.push(`pending:${gateId}:${basePath}`);
+      },
+      markApprovalGateVerified(gateId?: string | null, basePath?: string) {
+        calls.push(`approval:${gateId}:${basePath}`);
+      },
+      markDepthVerified(milestoneId?: string | null, basePath?: string) {
+        calls.push(`depth:${milestoneId}:${basePath}`);
+      },
+      clearPendingGate(basePath: string) {
+        calls.push(`clear:${basePath}`);
+      },
+      extractDepthVerificationMilestoneId(questionId: string) {
+        return questionId.match(/_(M\d+)_/)?.[1] ?? null;
+      },
+    };
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        return {
+          action: 'accept',
+          content: {
+            depth_verification_M003_confirm: 'Yes, you got it (Recommended)',
+          },
+        };
+      },
+      isRemoteConfigured() {
+        return false;
+      },
+      async tryRemoteQuestions() {
+        throw new Error('should not be called');
+      },
+      writeGate,
+      writeGateBasePath: '/tmp/gsd-project',
+    });
+
+    assert.equal('isError' in result && result.isError, false);
+    assert.deepEqual(calls, [
+      'pending:depth_verification_M003_confirm:/tmp/gsd-project',
+      'approval:depth_verification_M003_confirm:/tmp/gsd-project',
+      'depth:M003:/tmp/gsd-project',
+      'clear:/tmp/gsd-project',
+    ]);
+  });
+
+  it('ask_user_questions persists confirmed depth gates for remote answers', async () => {
+    const questions = [
+      {
+        id: 'depth_verification_M003_confirm',
+        header: 'Depth Check',
+        question: 'Did I capture the depth right?',
+        options: [
+          { label: 'Yes, you got it (Recommended)', description: 'Continue with the current summary.' },
+          { label: 'Not quite', description: 'I need to clarify the depth further.' },
+        ],
+      },
+    ];
+    const calls: string[] = [];
+    const writeGate = {
+      isGateQuestionId(questionId: string) {
+        return questionId.startsWith('depth_verification_');
+      },
+      isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>) {
+        return selected === options?.[0]?.label;
+      },
+      setPendingGate(gateId: string, basePath: string) {
+        calls.push(`pending:${gateId}:${basePath}`);
+      },
+      markApprovalGateVerified(gateId?: string | null, basePath?: string) {
+        calls.push(`approval:${gateId}:${basePath}`);
+      },
+      markDepthVerified(milestoneId?: string | null, basePath?: string) {
+        calls.push(`depth:${milestoneId}:${basePath}`);
+      },
+      clearPendingGate(basePath: string) {
+        calls.push(`clear:${basePath}`);
+      },
+      extractDepthVerificationMilestoneId(questionId: string) {
+        return questionId.match(/_(M\d+)_/)?.[1] ?? null;
+      },
+    };
+
+    const result = await askUserQuestionsHandler(questions, undefined, {
+      async elicitInput() {
+        return { action: 'cancel' };
+      },
+      isRemoteConfigured() {
+        return true;
+      },
+      async tryRemoteQuestions() {
+        return {
+          content: [{ type: 'text', text: 'remote response' }],
+          details: {
+            response: {
+              endInterview: false,
+              answers: {
+                depth_verification_M003_confirm: {
+                  selected: 'Yes, you got it (Recommended)',
+                  notes: '',
+                },
+              },
+            },
+          },
+        };
+      },
+      writeGate,
+      writeGateBasePath: '/tmp/gsd-project',
+    });
+
+    assert.equal('isError' in result && result.isError, false);
+    assert.deepEqual(calls, [
+      'pending:depth_verification_M003_confirm:/tmp/gsd-project',
+      'approval:depth_verification_M003_confirm:/tmp/gsd-project',
+      'depth:M003:/tmp/gsd-project',
+      'clear:/tmp/gsd-project',
+    ]);
+  });
+
   it('ask_user_questions falls back to remote when local elicitation is cancelled', async () => {
     const questions = [
       {

package/packages/mcp-server/src/server.ts

@@ -15,6 +15,7 @@ import { readFile, readdir } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
 import { z } from 'zod';
 import type { SessionManager } from './session-manager.js';
 import { isRemoteConfigured, tryRemoteQuestions } from './remote-questions.js';
@@ -355,6 +356,16 @@ interface AskUserQuestionsStructuredContent {
   cancelled: boolean;
 }
 
+interface AskUserQuestionsWriteGateModule {
+  isGateQuestionId(questionId: string): boolean;
+  isDepthConfirmationAnswer(selected: unknown, options?: Array<{ label?: string }>): boolean;
+  setPendingGate(gateId: string, basePath: string): void;
+  markApprovalGateVerified(gateId?: string | null, basePath?: string): void;
+  markDepthVerified(milestoneId?: string | null, basePath?: string): void;
+  clearPendingGate(basePath: string): void;
+  extractDepthVerificationMilestoneId(questionId: string): string | null;
+}
+
 const OTHER_OPTION_LABEL = 'None of the above';
 
 function normalizeAskUserQuestionsNote(value: AskUserQuestionsContentValue | undefined): string {
@@ -499,6 +510,90 @@ interface AskUserQuestionsHandlerDeps {
   elicitInput(params: AskUserQuestionsElicitRequest): Promise<AskUserQuestionsElicitResult>;
   isRemoteConfigured(): boolean;
   tryRemoteQuestions(questions: AskUserQuestion[], signal?: AbortSignal): Promise<RemoteToolResult | null>;
+  writeGate?: AskUserQuestionsWriteGateModule | null;
+  writeGateBasePath?: string;
+}
+
+let askUserQuestionsWriteGateModulePromise: Promise<AskUserQuestionsWriteGateModule | null> | null = null;
+
+function isAskUserQuestionsWriteGateModule(value: unknown): value is AskUserQuestionsWriteGateModule {
+  if (!value || typeof value !== 'object') return false;
+  const module = value as Record<string, unknown>;
+  return (
+    typeof module['isGateQuestionId'] === 'function' &&
+    typeof module['isDepthConfirmationAnswer'] === 'function' &&
+    typeof module['setPendingGate'] === 'function' &&
+    typeof module['markApprovalGateVerified'] === 'function' &&
+    typeof module['markDepthVerified'] === 'function' &&
+    typeof module['clearPendingGate'] === 'function' &&
+    typeof module['extractDepthVerificationMilestoneId'] === 'function'
+  );
+}
+
+async function loadAskUserQuestionsWriteGateModule(): Promise<AskUserQuestionsWriteGateModule | null> {
+  if (!askUserQuestionsWriteGateModulePromise) {
+    askUserQuestionsWriteGateModulePromise = (async () => {
+      const modulePath = process.env.GSD_WORKFLOW_WRITE_GATE_MODULE?.trim();
+      if (!modulePath) return null;
+      try {
+        if (/^[a-z]{2,}:/i.test(modulePath) && !modulePath.startsWith('file:')) {
+          throw new Error('GSD_WORKFLOW_WRITE_GATE_MODULE only supports file: URLs or filesystem paths.');
+        }
+        const baseRoot = process.env.GSD_WORKFLOW_PROJECT_ROOT?.trim() || process.cwd();
+        const specifier = modulePath.startsWith('file:') ? modulePath : pathToFileURL(resolve(baseRoot, modulePath)).href;
+        const loaded = await import(specifier);
+        return isAskUserQuestionsWriteGateModule(loaded) ? loaded : null;
+      } catch (err) {
+        console.warn(`[gsd:mcp] ask_user_questions write-gate integration unavailable: ${formatErrorMessage(err)}`);
+        return null;
+      }
+    })();
+  }
+  return askUserQuestionsWriteGateModulePromise;
+}
+
+function askUserQuestionsWriteGateBasePath(deps: AskUserQuestionsHandlerDeps): string {
+  return deps.writeGateBasePath ?? process.env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ?? process.cwd();
+}
+
+async function resolveAskUserQuestionsWriteGate(deps: AskUserQuestionsHandlerDeps): Promise<AskUserQuestionsWriteGateModule | null> {
+  if (deps.writeGate !== undefined) return deps.writeGate;
+  return loadAskUserQuestionsWriteGateModule();
+}
+
+async function recordAskUserQuestionsPendingGate(
+  questions: AskUserQuestion[],
+  deps: AskUserQuestionsHandlerDeps,
+): Promise<void> {
+  const writeGate = await resolveAskUserQuestionsWriteGate(deps);
+  if (!writeGate) return;
+
+  const basePath = askUserQuestionsWriteGateBasePath(deps);
+  for (const question of questions) {
+    if (writeGate.isGateQuestionId(question.id)) {
+      writeGate.setPendingGate(question.id, basePath);
+    }
+  }
+}
+
+async function recordAskUserQuestionsGateResult(
+  structured: AskUserQuestionsStructuredContent,
+  deps: AskUserQuestionsHandlerDeps,
+): Promise<void> {
+  if (structured.cancelled || !structured.response) return;
+  const writeGate = await resolveAskUserQuestionsWriteGate(deps);
+  if (!writeGate) return;
+
+  const basePath = askUserQuestionsWriteGateBasePath(deps);
+  for (const question of structured.questions) {
+    if (!writeGate.isGateQuestionId(question.id)) continue;
+    const selected = structured.response.answers[question.id]?.selected;
+    if (!writeGate.isDepthConfirmationAnswer(selected, question.options)) continue;
+
+    writeGate.markApprovalGateVerified(question.id, basePath);
+    writeGate.markDepthVerified(writeGate.extractDepthVerificationMilestoneId(question.id), basePath);
+    writeGate.clearPendingGate(basePath);
+  }
 }
 
 function isLocalElicitFallbackError(err: unknown): boolean {
@@ -539,6 +634,7 @@ export async function askUserQuestionsHandler(
   try {
     const validationError = validateAskUserQuestionsPayload(questions);
     if (validationError) return errorContent(validationError);
+    await recordAskUserQuestionsPendingGate(questions, deps);
 
     // Local-first: try the MCP host's elicitation channel (Claude Code,
     // Cursor, etc.) before any configured remote channel. A misconfigured
@@ -556,6 +652,7 @@ export async function askUserQuestionsHandler(
           response: buildAskUserQuestionsRoundResult(questions, elicitation),
           cancelled: false,
         };
+        await recordAskUserQuestionsGateResult(structured, deps);
         return {
           content: [{ type: 'text' as const, text: formatAskUserQuestionsElicitResult(questions, elicitation) }],
           structuredContent: structured as unknown as Record<string, unknown>,
@@ -612,11 +709,12 @@ export async function askUserQuestionsHandler(
               response: details!['response'] as AskUserQuestionsRoundResult,
               cancelled: false,
             }
-          : {
+            : {
               questions,
               response: null,
               cancelled: true,
             };
+        await recordAskUserQuestionsGateResult(acceptedStructured, deps);
         return {
           content: [{ type: 'text' as const, text: remoteResult.content[0]?.text ?? '' }],
           structuredContent: acceptedStructured as unknown as Record<string, unknown>,

package/packages/mcp-server/src/session-manager.ts

@@ -9,7 +9,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { resolve, join, delimiter } from 'node:path';
 import { RpcClient } from '@gsd-build/rpc-client';
-import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
+import type { SdkAgentEvent, RpcInitResult, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/contracts';
 import type {
   ManagedSession,
   ExecuteOptions,
@@ -391,7 +391,7 @@ function extractBlocker(event: SdkAgentEvent): PendingBlocker {
   const uiEvent = event as unknown as RpcExtensionUIRequest;
   return {
     id: String(uiEvent.id ?? ''),
-    method: String(uiEvent.method ?? ''),
+    method: uiEvent.method,
     message: String((uiEvent as Record<string, unknown>).title ?? (uiEvent as Record<string, unknown>).message ?? ''),
     event: uiEvent,
   };

package/packages/mcp-server/src/types.ts

@@ -2,7 +2,12 @@
  * MCP Server types — session lifecycle and orchestration.
  */
 
-import type { RpcClient, SdkAgentEvent, RpcCostUpdateEvent, RpcExtensionUIRequest } from '@gsd-build/rpc-client';
+import type { RpcClient } from '@gsd-build/rpc-client';
+import type {
+  McpPendingBlocker as PendingBlocker,
+  RpcCostUpdateEvent,
+  SdkAgentEvent,
+} from '@gsd-build/contracts';
 
 // ---------------------------------------------------------------------------
 // Session Status
@@ -46,23 +51,7 @@ export interface ManagedSession {
   unsubscribe?: () => void;
 }
 
-// ---------------------------------------------------------------------------
-// Pending Blocker
-// ---------------------------------------------------------------------------
-
-export interface PendingBlocker {
-  /** The extension_ui_request id */
-  id: string;
-
-  /** The request method (e.g. 'select', 'confirm', 'input') */
-  method: string;
-
-  /** Human-readable message or title */
-  message: string;
-
-  /** Full event payload for inspection */
-  event: RpcExtensionUIRequest;
-}
+export type { PendingBlocker };
 
 // ---------------------------------------------------------------------------
 // Cost Accumulator (K004 — cumulative-max)

package/packages/mcp-server/src/workflow-tools.test.ts

@@ -132,6 +132,122 @@ describe("workflow MCP tools", () => {
     }
   });
 
+  it("gsd_exec runs by default, preserves cwd, and returns structured metadata", async () => {
+    const base = makeTmpBase();
+    const originalCwd = process.cwd();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_exec");
+      assert.ok(tool, "exec tool should be registered");
+
+      const result = await tool!.handler({
+        projectDir: base,
+        runtime: "node",
+        script: "console.log(process.cwd()); console.log('context mode default on');",
+        purpose: "default-on smoke",
+      });
+
+      const record = result as any;
+      assert.equal(record.isError, false);
+      assert.match(record.content[0].text as string, /context mode default on/);
+      assert.equal(record.structuredContent.operation, "gsd_exec");
+      assert.equal(record.structuredContent.runtime, "node");
+      assert.ok(existsSync(record.structuredContent.stdout_path), "stdout should be persisted");
+      assert.equal(process.cwd(), originalCwd, "gsd_exec must not mutate process.cwd");
+      assert.match(
+        readFileSync(record.structuredContent.stdout_path, "utf-8"),
+        new RegExp(base.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+        "script should run relative to the requested projectDir",
+      );
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_exec returns an MCP error when context mode is disabled", async () => {
+    const base = makeTmpBase();
+    try {
+      writeFileSync(
+        join(base, ".gsd", "PREFERENCES.md"),
+        "---\ncontext_mode:\n  enabled: false\n---\n",
+        "utf-8",
+      );
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_exec");
+      assert.ok(tool, "exec tool should be registered");
+
+      const result = await tool!.handler({
+        projectDir: base,
+        runtime: "bash",
+        script: "echo should-not-run",
+      });
+
+      assertToolError(result, /context_mode\.enabled: false/);
+      assert.equal((result as any).structuredContent.error, "context_mode_disabled");
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_exec_search finds a prior gsd_exec run", async () => {
+    const base = makeTmpBase();
+    try {
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const execTool = server.tools.find((t) => t.name === "gsd_exec");
+      const searchTool = server.tools.find((t) => t.name === "gsd_exec_search");
+      assert.ok(execTool, "exec tool should be registered");
+      assert.ok(searchTool, "exec search tool should be registered");
+
+      await execTool!.handler({
+        projectDir: base,
+        runtime: "bash",
+        script: "printf 'needle-output\\n'",
+        purpose: "find-me-later",
+      });
+
+      const result = await searchTool!.handler({
+        projectDir: base,
+        query: "find-me",
+      });
+
+      assert.match((result as any).content[0].text as string, /find-me-later/);
+      assert.equal((result as any).structuredContent.operation, "gsd_exec_search");
+      assert.equal((result as any).structuredContent.matches, 1);
+      assert.match((result as any).structuredContent.results[0].stdout_path, /\.gsd[\\/]exec[\\/].*\.stdout$/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
+  it("gsd_resume reads the context snapshot", async () => {
+    const base = makeTmpBase();
+    try {
+      writeFileSync(
+        join(base, ".gsd", "last-snapshot.md"),
+        "# GSD context snapshot\n\nResume from here.\n",
+        "utf-8",
+      );
+      const server = makeMockServer();
+      registerWorkflowTools(server as any);
+      const tool = server.tools.find((t) => t.name === "gsd_resume");
+      assert.ok(tool, "resume tool should be registered");
+
+      const result = await tool!.handler({ projectDir: base });
+
+      assert.match((result as any).content[0].text as string, /Resume from here/);
+      assert.deepEqual((result as any).structuredContent, {
+        operation: "gsd_resume",
+        found: true,
+        bytes: Buffer.byteLength("# GSD context snapshot\n\nResume from here.\n", "utf-8"),
+      });
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("gsd_summary_save supports root-level PROJECT artifacts without milestone_id", async () => {
     const base = makeTmpBase();
     try {
@@ -147,10 +263,21 @@ describe("workflow MCP tools", () => {
         "workflow MCP schema must advertise milestone_id as optional for root artifacts",
       );
 
+      const projectFixture = [
+        "# Project",
+        "",
+        "Root artifact",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "",
+      ].join("\n");
+
       const result = await tool!.handler({
         projectDir: base,
         artifact_type: "PROJECT",
-        content: "# Project\n\nRoot artifact",
+        content: projectFixture,
       });
 
       const text = (result as any).content[0].text as string;
@@ -161,7 +288,7 @@ describe("workflow MCP tools", () => {
       );
       assert.equal(
         readFileSync(join(base, ".gsd", "PROJECT.md"), "utf-8"),
-        "# Project\n\nRoot artifact",
+        projectFixture,
       );
     } finally {
       cleanup(base);

package/packages/mcp-server/src/workflow-tools.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
+import { WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES } from "@gsd-build/contracts";
 
 import { logAliasUsage } from "./alias-telemetry.js";
 
@@ -662,43 +663,7 @@ interface McpToolServer {
   ): unknown;
 }
 
-export const WORKFLOW_TOOL_NAMES = [
-  "gsd_decision_save",
-  "gsd_save_decision",
-  "gsd_requirement_update",
-  "gsd_update_requirement",
-  "gsd_requirement_save",
-  "gsd_save_requirement",
-  "gsd_milestone_generate_id",
-  "gsd_generate_milestone_id",
-  "gsd_plan_milestone",
-  "gsd_plan_slice",
-  "gsd_plan_task",
-  "gsd_task_plan",
-  "gsd_replan_slice",
-  "gsd_slice_replan",
-  "gsd_slice_complete",
-  "gsd_complete_slice",
-  "gsd_skip_slice",
-  "gsd_complete_milestone",
-  "gsd_milestone_complete",
-  "gsd_validate_milestone",
-  "gsd_milestone_validate",
-  "gsd_reassess_roadmap",
-  "gsd_roadmap_reassess",
-  "gsd_save_gate_result",
-  "gsd_summary_save",
-  "gsd_task_complete",
-  "gsd_complete_task",
-  "gsd_milestone_status",
-  "gsd_journal_query",
-  // ADR-013 step 3: memory-store tools exposed to external MCP clients.
-  // gsd_memory_graph is namespaced to avoid collision with the existing
-  // gsd_graph tool (project knowledge graph from .gsd/ artifacts).
-  "gsd_capture_thought",
-  "gsd_memory_query",
-  "gsd_memory_graph",
-] as const;
+export const WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 
 const DEFAULT_WORKFLOW_OP_TIMEOUT_MS = 5 * 60 * 1000;
 
@@ -1426,6 +1391,30 @@ const journalQueryParams = {
 };
 const journalQuerySchema = z.object(journalQueryParams);
 
+const execRuntimeSchema = z.enum(["bash", "node", "python"]);
+const execParams = {
+  projectDir: projectDirParam,
+  runtime: execRuntimeSchema.describe("Interpreter: bash (-c), node (-e), or python3 (-c)."),
+  script: nonEmptyString("script").describe("Script body. Keep output small; full stdout/stderr are persisted under .gsd/exec."),
+  purpose: z.string().optional().describe("Short label recorded in meta.json for later review."),
+  timeout_ms: z.number().int().min(1_000).max(600_000).optional().describe("Per-invocation timeout in milliseconds."),
+};
+const execSchema = z.object(execParams);
+
+const execSearchParams = {
+  projectDir: projectDirParam,
+  query: z.string().optional().describe("Substring matched against id and purpose, case-insensitive."),
+  runtime: execRuntimeSchema.optional().describe("Restrict to one runtime."),
+  failing_only: z.boolean().optional().describe("Only non-zero exit codes and timeouts."),
+  limit: z.number().int().min(1).max(200).optional().describe("Max results (default 20, cap 200)."),
+};
+const execSearchSchema = z.object(execSearchParams);
+
+const resumeParams = {
+  projectDir: projectDirParam,
+};
+const resumeSchema = z.object(resumeParams);
+
 /**
  * Wrap a real McpToolServer so every handler we register catches thrown
  * errors and returns a structured `{isError: true, content: [...]}` MCP
@@ -1882,6 +1871,60 @@ export function registerWorkflowTools(realServer: McpToolServer): void {
     },
   );
 
+  server.tool(
+    "gsd_exec",
+    "Run a short bash/node/python script in the project directory. Full stdout/stderr persist under .gsd/exec; only a digest returns to MCP.",
+    execParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(execSchema, args);
+      await enforceWorkflowWriteGate("gsd_exec", projectDir);
+      const [{ executeGsdExec }, { loadEffectiveGSDPreferences }] = await Promise.all([
+        importLocalModule<any>("../../../src/resources/extensions/gsd/tools/exec-tool.js"),
+        importLocalModule<any>("../../../src/resources/extensions/gsd/preferences.js"),
+      ]);
+      let prefs: { preferences?: unknown } | null = null;
+      try {
+        prefs = loadEffectiveGSDPreferences(projectDir);
+      } catch {
+        prefs = null;
+      }
+      return adaptExecutorResult(
+        await runSerializedWorkflowOperation(() =>
+          executeGsdExec(params, {
+            baseDir: projectDir,
+            preferences: (prefs?.preferences ?? null) as unknown,
+          }),
+        ),
+      );
+    },
+  );
+
+  server.tool(
+    "gsd_exec_search",
+    "Search prior gsd_exec runs from .gsd/exec/*.meta.json without re-running them.",
+    execSearchParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(execSearchSchema, args);
+      const { executeExecSearch } = await importLocalModule<any>(
+        "../../../src/resources/extensions/gsd/tools/exec-search-tool.js",
+      );
+      return adaptExecutorResult(executeExecSearch(params, { baseDir: projectDir }));
+    },
+  );
+
+  server.tool(
+    "gsd_resume",
+    "Read .gsd/last-snapshot.md so agents can re-orient after compaction or session resume.",
+    resumeParams,
+    async (args: Record<string, unknown>) => {
+      const { projectDir, ...params } = parseWorkflowArgs(resumeSchema, args);
+      const { executeResume } = await importLocalModule<any>(
+        "../../../src/resources/extensions/gsd/tools/resume-tool.js",
+      );
+      return adaptExecutorResult(executeResume(params, { baseDir: projectDir }));
+    },
+  );
+
   // ─── ADR-013 step 3 — memory-store tools for external MCP clients ────────
   //
   // The same three tools the LLM sees in-process as `capture_thought`,