docs: clarify direct response continuation

Author: GlitterKill

SDL.md

@@ -15,7 +15,7 @@ SDL-MCP is the normal repository interface. Native filesystem and shell tools ar
    - Use `sdl.workflow` only when steps need result piping, transforms, runtime execution, batch operations, or mutations.
 3. Never use `file.read` for indexed source. It is only for non-indexed files such as docs, configs, templates, JSON, and YAML.
 4. Treat focus fields as seed priorities, not output boundaries. The task profile and token budget determine expansion and evidence rungs.
-5. Keep `responseMode: "auto"` for potentially large responses. If a response handle is returned, continue directly with `sdl.retrieve` using `op: "responseGet"` and `args: { handle, ... }`; request only the needed field or page. For JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
+5. Keep `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; do not reconstruct the continuation. The outer `repoId` owns trusted dispatch, while `detail` and `includeDiagnostics` remain outer `sdl.retrieve` controls. Nested `args` contains only artifact view and paging fields; nested `repoId` is invalid. Request only the needed field or page: for JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when direct `sdl.retrieve` is unavailable or an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
 6. Use focused `sdl.manual` only when composing a non-obvious request. Use `sdl.action.search` when the correct SDL action is unclear.
 
 Never call `index.refresh`, directly, through `sdl.workflow`, or via `sdl-mcp index`, without explicit user approval in the current turn. Status flags, graph verification, parser-state/provenance warnings, and refresh recommendations are diagnostics, not approval.

src/mcp/server-instructions.ts

@@ -5,7 +5,7 @@ export const SDL_MCP_SERVER_INSTRUCTIONS = [
   '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 response handle is returned, continue the canonical `response.get` action directly with `sdl.retrieve` using `op: "responseGet"` and `args: { handle, ... }`; request only the needed field or page. Use `sdl.workflow` with `fn: "responseGet"` only when an existing multi-step workflow needs the result.',
+  '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.',

templates/SDL.md

@@ -15,7 +15,7 @@ SDL-MCP is the normal repository interface. Native filesystem and shell tools ar
    - Use `sdl.workflow` only when steps need result piping, transforms, runtime execution, batch operations, or mutations.
 3. Never use `file.read` for indexed source. It is only for non-indexed files such as docs, configs, templates, JSON, and YAML.
 4. Treat focus fields as seed priorities, not output boundaries. The task profile and token budget determine expansion and evidence rungs.
-5. Keep `responseMode: "auto"` for potentially large responses. If a response handle is returned, continue directly with `sdl.retrieve` using `op: "responseGet"` and `args: { handle, ... }`; request only the needed field or page. For JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
+5. Keep `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; do not reconstruct the continuation. The outer `repoId` owns trusted dispatch, while `detail` and `includeDiagnostics` remain outer `sdl.retrieve` controls. Nested `args` contains only artifact view and paging fields; nested `repoId` is invalid. Request only the needed field or page: for JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when direct `sdl.retrieve` is unavailable or an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
 6. Use focused `sdl.manual` only when composing a non-obvious request. Use `sdl.action.search` when the correct SDL action is unclear.
 
 Never call `index.refresh`, directly, through `sdl.workflow`, or via `sdl-mcp index`, without explicit user approval in the current turn. Status flags, graph verification, parser-state/provenance warnings, and refresh recommendations are diagnostics, not approval.

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

@@ -22,11 +22,15 @@ Use SDL-MCP as the repository boundary.
 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.
-6. Keep `responseMode: "auto"` for potentially large results. When a handle
-   is returned, continue the canonical `response.get` action directly with
-   `sdl.retrieve` using `op: "responseGet"` and `args: { handle, ... }`; request
-   only the needed field or page. Use workflow `responseGet` only when an
-   existing multi-step workflow needs it.
+6. Keep `responseMode: "auto"` for potentially large results. 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; do not reconstruct it.
+   Outer `repoId` owns trusted dispatch, and `detail`/`includeDiagnostics` stay
+   outer `sdl.retrieve` controls. Nested `args` contains only artifact view and
+   paging fields; nested `repoId` is invalid. Use workflow `responseGet` only
+   when direct `sdl.retrieve` is unavailable or an existing multi-step workflow
+   needs it.
 7. Reuse refs and ETags. Set `refsMode: "off"` only for complete or byte-stable
    output.
 8. Never call `index.refresh`, directly, through `sdl.workflow`, or via

templates/sdl-mcp-agent-workflow/references/tool-recipes.md

@@ -30,8 +30,10 @@
 
 ## Large-Response Recovery
 
-When `sdl.context` returns a response artifact handle, continue directly through
-`sdl.retrieve` and request only the needed canonical field or page:
+When a result returns a canonical `response.get` continuation (`nextAction` or
+`action`) for `sdl.retrieve` with `op: "responseGet"`, replay the returned action
+and arguments unchanged; do not reconstruct the continuation. A direct
+continuation has this shape:
 
 ```json
 {
@@ -42,9 +44,14 @@ When `sdl.context` returns a response artifact handle, continue directly through
     "jsonPath": "evidence",
     "offset": 0,
     "limit": 10
-  }
+  },
+  "detail": "full",
+  "includeDiagnostics": true
 }
 ```
 
-Use `cursor` and `maxBytes` for byte paging. Use workflow `responseGet` only
-when an existing multi-step workflow needs to pipe the retrieved result.
+The outer `repoId` owns trusted dispatch. `detail` and `includeDiagnostics` are
+outer `sdl.retrieve` controls; nested `args` contains only artifact view and
+paging fields, and nested `repoId` is invalid. Use `cursor` and `maxBytes` for
+byte paging. Use workflow `responseGet` only when direct `sdl.retrieve` is
+unavailable or an existing multi-step workflow needs to pipe the result.

tests/stress/fixtures/SDL.md

@@ -15,7 +15,7 @@ SDL-MCP is the normal repository interface. Native filesystem and shell tools ar
    - Use `sdl.workflow` only when steps need result piping, transforms, runtime execution, batch operations, or mutations.
 3. Never use `file.read` for indexed source. It is only for non-indexed files such as docs, configs, templates, JSON, and YAML.
 4. Treat focus fields as seed priorities, not output boundaries. The task profile and token budget determine expansion and evidence rungs.
-5. Keep `responseMode: "auto"` for potentially large responses. If a response handle is returned, continue directly with `sdl.retrieve` using `op: "responseGet"` and `args: { handle, ... }`; request only the needed field or page. For JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
+5. Keep `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; do not reconstruct the continuation. The outer `repoId` owns trusted dispatch, while `detail` and `includeDiagnostics` remain outer `sdl.retrieve` controls. Nested `args` contains only artifact view and paging fields; nested `repoId` is invalid. Request only the needed field or page: for JSON artifacts, prefer `jsonPath` with dot or bracket array paths, add `offset`/`limit` for large arrays, and use `raw: true` only when byte-slicing JSON text is intentional. Use workflow `responseGet` only when direct `sdl.retrieve` is unavailable or an existing multi-step workflow needs the result. A missing path reports the available top-level keys and returns a same-handle direct continuation, preferring `evidence` and then `omitted`.
 6. Use focused `sdl.manual` only when composing a non-obvious request. Use `sdl.action.search` when the correct SDL action is unclear.
 
 Never call `index.refresh`, directly, through `sdl.workflow`, or via `sdl-mcp index`, without explicit user approval in the current turn. Status flags, graph verification, parser-state/provenance warnings, and refresh recommendations are diagnostics, not approval.