Clarify MCP result projection guidance and coverage

Author: GlitterKill

SDL.md

@@ -4,6 +4,8 @@ Use this file as the repository fallback for the `sdl-mcp-agent-workflow` skill.
 
 SDL-MCP is the normal repository interface. Native filesystem and shell tools are fallback-only when SDL-MCP is unavailable, or when accessing agent memory and other internal client data outside the indexed repository.
 
+When a client bridge returns the raw MCP result, prefer `structuredContent`; use text `content` only as a fallback for older servers. Do not emit both or return the whole MCP response envelope to the agent.
+
 ---
 
 ## 1. Start Every Task
@@ -175,7 +177,7 @@ Use this when you need likely files and symbols before choosing `symbol.edit` or
 
 Use the cheapest rung that answers the task. Static price tags in `sdl.manual` and `sdl.action.search` are release-time estimates, not live telemetry; use them to choose the first probe, then use `usage.stats` and `signalDensity` only when you need a savings or waste report.
 
-- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`.
+- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`. Do not guess `runtimeQueryOutput` arguments; replay a returned action unchanged or call focused `sdl.manual` for `runtime.queryOutput` first.
   ```json
   {
     "fn": "runtimeExecute",

docs/feature-deep-dives/code-mode.md

@@ -38,7 +38,7 @@ Code Mode keeps those flows inside SDL-MCP:
 
 ## Output Surfaces
 
-Code Mode tool output is human-first. The first MCP `content` text block is concise terminal-friendly text, while task-relevant machine-readable data is carried in `structuredContent`. Agents should read the visible text for the human-facing summary and use `structuredContent` for follow-up identifiers such as `etag`, handles, file paths, symbol IDs, references, summaries, errors, and next-action hints.
+Raw Code Mode MCP results retain a concise human-readable `content` text block beside task-relevant `structuredContent`. Agent bridges should pass through `structuredContent` when it is present, use text `content` only as a compatibility fallback for older servers, and avoid exposing both or the whole MCP response envelope to the agent. Follow-up identifiers such as `etag`, handles, file paths, symbol IDs, references, summaries, errors, and next-action hints remain in `structuredContent`.
 
 SDL-MCP internal bookkeeping is not duplicated into model-visible output by default. Timing diagnostics, packed-wire stats, raw-context baselines, action traces, precondition snapshots, backup paths, and retrieval-debug details stay in logs or diagnostics surfaces. Set `includeDiagnostics: true` or the relevant retrieval-evidence option only when the task actually needs those details; even then, the normal visible text stays concise.
 

src/mcp/server-instructions.ts

@@ -2,14 +2,15 @@ export const SDL_MCP_SERVER_INSTRUCTIONS = [
   "At session start, load and follow `sdl-mcp-agent-workflow` when skills are available; otherwise use these instructions. The index-refresh authorization rules below govern if other guidance conflicts.",
   "",
   "Required SDL-MCP workflow:",
+  "Raw MCP result handling: When a client bridge returns the raw MCP result, prefer `structuredContent`; use text `content` only as a fallback for older servers. Do not emit both or return the whole MCP response envelope to the agent.",
   '1. Confirm `repo.status` through `sdl.workflow` with `fn: "repoStatus"` and `args: {}`.',
   "2. If the correct action is unclear, use `sdl.action.search`; load `sdl.manual` only for the focused schema needed to compose a non-obvious request.",
   '3. Gather task evidence via `sdl.context` with `budget.maxTokens` and flat `focusPaths`, `focusSymbols`, or `chatMentions`; never send `options`, `contextMode`, or `answerFirst`. Use `sdl.retrieve` for one-step `symbolSearch`, `symbolGetCard`, `sliceBuild`, `codeSkeleton`, `codeHotPath`, or bounded `codeNeedWindow` retrieval.',
   '4. Use `responseMode: "auto"` for potentially large responses. When a result returns a canonical `response.get` continuation (`nextAction` or `action`) for `sdl.retrieve` with `op: "responseGet"`, replay its returned action and arguments unchanged; outer `repoId` owns trusted dispatch, `detail` and `includeDiagnostics` stay outer controls, and nested `args.repoId` is invalid. Use workflow `responseGet` only when direct `sdl.retrieve` is unavailable or an existing multi-step workflow needs it.',
   '5. Reuse `{ ref, unchanged: true }` responses and session short ids (`sN`); pass `refsMode: "off"` only when full content is required.',
   "6. Use `sdl.workflow` for multi-step pipelines, runtime execution, data transforms, batch operations, mutations, or result piping between steps; do not wrap a single `sdl.context` call.",
   '7. Use `sdl.file` with `op: "read"`; `file.read` only for non-indexed files and prefer targeted reads. `op: "write"` (`file.write`) supports targeted single-file writes, including indexed files with live reconciliation; prefer `op: "symbolEditPreview"`/`op: "symbolEditApply"` (`symbol.edit` preview/apply) for one-symbol indexed edits and `op: "searchEditPreview"`/`op: "searchEditApply"` for cross-file edits.',
-  '8. runtimeExecute executes repository tooling. Permitted uses include build, test, lint, compiler, named scripts, and targeted edit scripts. Do not use it to inspect, search, or print repository files. Use `sdl.context` or `sdl.retrieve` for indexed source and `sdl.file` with `op="read"` for other files. For permitted tooling, use workflow `runtimeExecute` with an explicit `timeoutMs`: use `outputMode: "minimal"` for quiet probes, `outputMode: "digest"` for noisy commands, or `outputMode: "intent"` when exact terms are known; set `persistOutput: true` when logs may need focused `runtimeQueryOutput` queries.',
+  '8. runtimeExecute executes repository tooling. Permitted uses include build, test, lint, compiler, named scripts, and targeted edit scripts. Do not use it to inspect, search, or print repository files. Use `sdl.context` or `sdl.retrieve` for indexed source and `sdl.file` with `op="read"` for other files. For permitted tooling, use workflow `runtimeExecute` with an explicit `timeoutMs`: use `outputMode: "minimal"` for quiet probes, `outputMode: "digest"` for noisy commands, or `outputMode: "intent"` when exact terms are known; set `persistOutput: true` when logs may need focused `runtimeQueryOutput` queries. Do not guess `runtimeQueryOutput` arguments; replay a returned action unchanged or call focused `sdl.manual` for `runtime.queryOutput` first.',
   "9. Use memory tools only when `memory.enabled: true`.",
   "10. Never call `index.refresh`, directly, through `sdl.workflow`, or via `sdl-mcp index`, without explicit user approval in the current turn.",
   '11. `derivedState.structuralStale` and `derivedState.semanticStale` report separate readiness classes. If only `summariesDirty` or `embeddingsDirty` is set, continue with available retrieval lanes; do not refresh the index. These flags, `graphIntegrityState: "verifying"`, `PARSER_FILE_STATE_MISSING`, parser-state warnings, parser-provenance warnings, and refresh recommendations are diagnostics, not approval.',

templates/SDL.md

@@ -4,6 +4,8 @@ Use this file as the repository fallback for the `sdl-mcp-agent-workflow` skill.
 
 SDL-MCP is the normal repository interface. Native filesystem and shell tools are fallback-only when SDL-MCP is unavailable, or when accessing agent memory and other internal client data outside the indexed repository.
 
+When a client bridge returns the raw MCP result, prefer `structuredContent`; use text `content` only as a fallback for older servers. Do not emit both or return the whole MCP response envelope to the agent.
+
 ---
 
 ## 1. Start Every Task
@@ -175,7 +177,7 @@ Use this when you need likely files and symbols before choosing `symbol.edit` or
 
 Use the cheapest rung that answers the task. Static price tags in `sdl.manual` and `sdl.action.search` are release-time estimates, not live telemetry; use them to choose the first probe, then use `usage.stats` and `signalDensity` only when you need a savings or waste report.
 
-- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`.
+- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`. Do not guess `runtimeQueryOutput` arguments; replay a returned action unchanged or call focused `sdl.manual` for `runtime.queryOutput` first.
   ```json
   {
     "fn": "runtimeExecute",

templates/sdl-mcp-agent-workflow/SKILL.md

@@ -7,6 +7,10 @@ description: Use when working in an SDL-MCP-enabled repository, including reposi
 
 Use SDL-MCP as the repository boundary.
 
+When a client bridge returns the raw MCP result, prefer `structuredContent`; use
+text `content` only as a fallback for older servers. Do not emit both or return
+the whole MCP response envelope to the agent.
+
 1. Start with `repo.status`.
 2. Use `sdl.context` for task-shaped explain, debug, review, and implement work.
    Its request is flat and requires `budget.maxTokens`; never send `options`,
@@ -18,7 +22,9 @@ Use SDL-MCP as the repository boundary.
    runtimeExecute executes repository tooling. Permitted uses include build,
    test, lint, compiler, named scripts, and targeted edit scripts. Do not use it
    to inspect, search, or print repository files. Use sdl.context or sdl.retrieve
-   for indexed source and sdl.file with op="read" for other files.
+   for indexed source and sdl.file with op="read" for other files. Do not guess
+   `runtimeQueryOutput` arguments; replay a returned action unchanged or call
+   focused `sdl.manual` for `runtime.queryOutput` first.
 5. Read non-indexed files through `sdl.file`. Its targeted write operation can
    update one indexed file with live reconciliation; prefer symbol or
    search-edit preview/apply operations when they can anchor the change.

tests/stress/fixtures/SDL.md

@@ -4,6 +4,8 @@ Use this file as the repository fallback for the `sdl-mcp-agent-workflow` skill.
 
 SDL-MCP is the normal repository interface. Native filesystem and shell tools are fallback-only when SDL-MCP is unavailable, or when accessing agent memory and other internal client data outside the indexed repository.
 
+When a client bridge returns the raw MCP result, prefer `structuredContent`; use text `content` only as a fallback for older servers. Do not emit both or return the whole MCP response envelope to the agent.
+
 ---
 
 ## 1. Start Every Task
@@ -175,7 +177,7 @@ Use this when you need likely files and symbols before choosing `symbol.edit` or
 
 Use the cheapest rung that answers the task. Static price tags in `sdl.manual` and `sdl.action.search` are release-time estimates, not live telemetry; use them to choose the first probe, then use `usage.stats` and `signalDensity` only when you need a savings or waste report.
 
-- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`.
+- Runtime: prefer `outputMode: "digest"` for build/test/lint and other noisy commands. The digest keeps a compact parsed status and persists full output for `runtimeQueryOutput`. Do not guess `runtimeQueryOutput` arguments; replay a returned action unchanged or call focused `sdl.manual` for `runtime.queryOutput` first.
   ```json
   {
     "fn": "runtimeExecute",

tests/unit/agent-workflow-sync.test.ts

@@ -99,6 +99,35 @@ ${result.stderr}`);
     }
   });
 
+  it("keeps raw MCP result handling compact across agent workflow surfaces", () => {
+    const workflowSurfaces = [
+      "templates/SDL.md",
+      "SDL.md",
+      "tests/stress/fixtures/SDL.md",
+      "templates/sdl-mcp-agent-workflow/SKILL.md",
+      "src/mcp/server-instructions.ts",
+    ];
+
+    for (const relativePath of workflowSurfaces) {
+      const content = readFileSync(resolve(repoRoot, relativePath), "utf8");
+      assert.match(
+        content,
+        /prefer `structuredContent`[\s\S]{0,220}fallback[\s\S]{0,120}older servers/i,
+        relativePath,
+      );
+      assert.match(
+        content,
+        /do not emit both[\s\S]{0,120}whole MCP response envelope/i,
+        relativePath,
+      );
+      assert.match(
+        content,
+        /Do not guess\s+`runtimeQueryOutput` arguments[\s\S]{0,180}sdl\.manual/i,
+        relativePath,
+      );
+    }
+  });
+
   it("keeps fallback workflow readiness and provenance guidance current", () => {
     const workflowSurfaces = [
       "templates/SDL.md",

tests/unit/response-projection-inventory.test.ts

@@ -20,7 +20,10 @@ import {
   zodToSchemaSummary,
 } from "../../dist/code-mode/action-catalog.js";
 import { getActiveFnNameMap } from "../../dist/code-mode/manual-generator.js";
-import { projectToolResultForModelContent } from "../../dist/mcp/context-response-projection.js";
+import {
+  projectToolResultForModelContent,
+  projectWorkflowChildResultForModel,
+} from "../../dist/mcp/context-response-projection.js";
 import { OUTPUT_BUDGET_TOKEN_LIMITS } from "../../dist/mcp/response-projection/budgets.js";
 import { buildValidatedRecoveryAction } from "../../dist/mcp/response-projection/recovery.js";
 import {
@@ -799,6 +802,74 @@ describe("response projection inventory", () => {
     assert.deepEqual(workflowOutputSchema.parse(projected), projected);
   });
 
+  it("accepts every projected workflow child fixture", () => {
+    const workflowRegistration = capturePublicToolRegistrations({
+      enabled: true,
+      exclusive: true,
+    }).find(({ name }) => name === "sdl.workflow");
+    assert.ok(workflowRegistration);
+    const workflowOutputSchema = exhaustiveOutputSchema(workflowRegistration);
+    assert.ok(workflowOutputSchema);
+
+    const fnByAction = new Map<string, string>([
+      ...Object.entries(getActiveFnNameMap(true)).map(
+        ([fn, action]) => [action, fn] as const,
+      ),
+      ...Object.keys(INTERNAL_TRANSFORM_OUTPUT_SCHEMA_BY_ACTION).map(
+        (action) => [action, action] as const,
+      ),
+    ]);
+    const coveredActions = new Set<string>();
+    const failures: string[] = [];
+
+    for (const fixture of AGENT_OUTPUT_CASES) {
+      const fn = fnByAction.get(fixture.action);
+      if (fn === undefined) continue;
+      coveredActions.add(fixture.action);
+      for (const detail of ["compact", "full"] as const) {
+        const workflowArgs = {
+          repoId: "projection-fixture",
+          detail,
+          includeDiagnostics: false,
+          steps: [{ fn, args: fixture.publicRequest, detail }],
+        };
+        const childResult = projectWorkflowChildResultForModel(
+          fn,
+          fixture.canonicalResultFactory(),
+          workflowArgs,
+          { ...fixture.publicRequest, detail },
+        );
+        const projected = projectToolResultForModelContent(
+          "sdl.workflow",
+          {
+            results: [{
+              stepIndex: 0,
+              fn,
+              status: "ok",
+              result: childResult,
+              _resolvedArgs: fixture.publicRequest,
+            }],
+          },
+          workflowArgs,
+        );
+        const parsed = workflowOutputSchema.safeParse(projected);
+        if (!parsed.success) {
+          failures.push(
+            `${fixture.action}/${detail}: projected=${JSON.stringify(projected)} issues=${JSON.stringify(parsed.error.issues)}`,
+          );
+        } else {
+          assert.deepEqual(parsed.data, projected, `${fixture.action}/${detail}`);
+        }
+      }
+    }
+
+    assert.deepEqual(
+      [...coveredActions].sort(),
+      [...new Set(fnByAction.keys())].sort(),
+    );
+    assert.deepEqual(failures, []);
+  });
+
   it("rejects arbitrary response content schemas and incoherent continuations", () => {
     const registrations = capturePublicToolRegistrations();
     const responseRegistration = registrations.find(

tests/unit/server-unit.test.ts

@@ -285,11 +285,23 @@ describe("MCPServer", () => {
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /sdl-mcp-agent-workflow/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /repo\.status/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /sdl\.workflow[^\n]*repoStatus/);
+      assert.match(
+        SDL_MCP_SERVER_INSTRUCTIONS,
+        /prefer `structuredContent`[^\n]*fallback[^\n]*older servers/i,
+      );
+      assert.match(
+        SDL_MCP_SERVER_INSTRUCTIONS,
+        /do not emit both[^\n]*whole MCP response envelope/i,
+      );
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /sdl\.action\.search/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /sdl\.context/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /usageStats/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /outputMode: \"digest\"/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /outputMode: \"minimal\"/);
+      assert.match(
+        SDL_MCP_SERVER_INSTRUCTIONS,
+        /Do not guess `runtimeQueryOutput` arguments[^\n]*sdl\.manual/i,
+      );
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /refsMode: \"off\"/);
       assert.match(SDL_MCP_SERVER_INSTRUCTIONS, /short ids/);
       assert.match(