Bug: unknown prompt variable "{{hexagon}}" in section "tools:sdk" under code-mode presets with drawio MCP

[Marker689]

Describe the bug

Assembling the system prompt fails with:

unknown prompt variable "{{hexagon}}" in section "tools:sdk"; registered variables: provider, model, cwd, mnemon_runtime_memory_literal_open_braces

This happens only under a non-native tool presentation (tool-presentation.mode: code or both) while the drawio MCP server (@drawio/mcp, bridged through @deepseek-ai/dsh-mcp-client) is registered. Native-mode presets are unaffected.

To reproduce

1. Start a dsh session with a preset that sets tool-presentation.mode: code (e.g. the code agent preset).
2. Register the drawio MCP (@drawio/mcp; tools surface as mcp__drawio__*).
3. Run any request that assembles the prompt — the error above is thrown and the request fails.

Root cause

• In non-native modes dsh-tools registers the tools:sdk prompt section, which renders every registered tool — including MCP tools — into a generated SDK text (renderToolsSdk / renderToolsSdkPy in @deepseek-ai/dsh-tools). Each tool's raw description is embedded as doc comments (docLines(schema.description, ...)), and schema property descriptions are embedded by jsonSchemaToTs / renderType too.
• The open_drawio_mermaid tool description (shipped by @drawio/mcp as mermaid-reference.md) contains {{hexagon}} — mermaid syntax for a hexagon-shaped node (Node shapes by bracket: ... {{hexagon}} ..., also in the Mindmap section) — which is not a prompt variable.
• interpolate() in @deepseek-ai/dsh-system-prompt strictly scans every {{name}} in section text and throws for any name that is not a registered prompt variable. There is no escape mechanism: fenced code blocks are not skipped and there is no escape sequence like \{{.

Expected behavior

Tool-owned prose (descriptions from tools / MCP servers) must not be interpreted as prompt variables. Either sanitize or escape {{ when embedding descriptions into generated SDK sections, or teach the interpolator to ignore fenced code blocks / support an escape sequence.

Workaround applied locally

Patch in @deepseek-ai/dsh-tools/lib/index.js: added sdkSafeText() ({{ → { {) applied to tool descriptions and to the output of jsonSchemaToTs / renderType in both SDK renderers (TypeScript and Python). It fixes the whole class of failures (any MCP description containing {{...}}), but it is lost on every dsh update.

Environment

• dsh: 0.1.0-rc.8 (npm @deepseek-ai/dsh)
• drawio MCP: @drawio/mcp (latest)
• preset: tool-presentation.mode: code

[argszero]

Verified against rc.8 (141eb6f) — your analysis is exact at source, and the failure class is bigger than drawio: any tool/MCP description containing {{...}} breaks prompt assembly in non-native tool presentation. My additions:

1. Source confirmation (rc.8)

• packages/core/system-prompt/src/index.ts:258-295 — interpolate() scans every {{, requires a complete {{name}} group, and throws for any unregistered name (:283-286 "unknown prompt variable …"). No escape mechanism, no fenced-code skip — your "strict scan" claim is literal.
• packages/core/tools/src/ts-types.ts:273-278 — renderToolsSdk embeds each tool's raw description into the tools:sdk section via docLines(schema.description, 1) (:278). Property descriptions go in the same way (:164). So any description containing {{hexagon}} (mermaid's hexagon-node syntax — genuinely common in diagram-tool descriptions) flows straight into the interpolator.
• The renderer is chosen by tool-presentation.mode (index.ts:61-62: typescript: renderToolsSdk, python: renderToolsSdkPy) — matching your "only non-native modes" observation.

2. The design tension: strict interpolation vs tool-owned prose

The strictness is deliberate (the doc comment at :193 says references are strict; a lone {{ without }} is literal prose, but a complete group is assumed to be a variable). The flaw is the trust boundary: section text authored by the harness (sections like deployment:persona) can be held to strict-variable discipline, but tools:sdk is generated from third-party tool schemas — the harness does not control MCP server descriptions. Treating both under one strict interpolator is the bug. The author's sdkSafeText() (escape {{ → { {) applied at the generation boundary is the correct layer: tool prose should be sanitized before it enters a strict-interpolation section, not taught to the interpolator.

3. On the three fix options — which is right

1. Sanitize at generation (your patch) — correct layer. The tools:sdk renderer is the boundary between third-party-owned prose and harness-owned section text. Escape ({{ → { { or \{{) in docLines / jsonSchemaToTs / renderType outputs. This is the durable fix.
2. Teach the interpolator to skip fenced code — wrong layer, and fragile: it would silently change the meaning of legitimate {{variable}} references inside fenced blocks that the harness does author (e.g. a tools:sdk example showing {{cwd}}), and MCP descriptions aren't reliably fenced anyway.
3. Escape sequence \{{ in the interpolator — useful complement, but only helps harness-authored sections that want literal braces; it does nothing for third-party prose that arrives unescaped (the drawio case). Not a substitute for (1).

So: sanitize at the SDK generation boundary (your sdkSafeText is exactly right, and it fixes the whole class — any future MCP tool with {{...}} in a description). Consider also sanitizing docLines' collapse step (the \s+→space collapse at ts-types.ts:36) — it's the single choke point where every description line passes, so a one-line escape there covers both TS and Python renderers.

4. The regression test shape

A test that registers a fake tool whose description contains {{hexagon}} (or {{anything_unregistered}}), assembles the prompt in code mode, and asserts no throw + the literal text survives (escaped). That pins the boundary: third-party prose with brace-groups must never reach the strict interpolator unescaped. Without it, the next MCP server with {{...}} in a description re-breaks silently.

5. PR shape

One PR: sdkSafeText (or inline escape) in docLines + the jsonSchemaToTs/renderType outputs + the regression test. Small, contained to dsh-tools, and it un-breaks the whole class. Worth noting the failure mode is nasty precisely because it's environment-dependent (only MCP servers with brace-y descriptions + only non-native modes) — the same session works or breaks based on which tools are registered.

Nice find — the mermaid {{hexagon}} description is a great real-world trigger, and your sdkSafeText is the right shape. When PRs reopen this should be a quick merge.

[denial123789]

Published the complete operator and regression matrix derived from this report. Two details worth making explicit for future readers:

• both is not a workaround: it keeps native schemas but still generates tools:sdk, so the poisoned description still reaches interpolation. Only native removes this path.
• The repair surface includes both the TypeScript and Python SDK renderers, plus nested property descriptions—not only the top-level draw.io tool description. Strict unknown-variable errors should remain intact for deployment-authored sections.

Visual trace and bounded recovery: https://sandbaseai.github.io/deepseek-harness-handbook/code-mode-unknown-prompt-variable.html
Canonical source-backed guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/code-mode-unknown-prompt-variable.md

[zhangchengxiang-ctrl]

同一类失败又在 DataSage MCP 的 upload_static_resource 描述（字面量 {{ param }}）上复现了，不只是 drawio 的 {{hexagon}}。

新讨论：#4241

按这里的共识，补丁在 SDK 生成边界把每个 {{ 拆成 { {（TS / Python 两端，code/both 的 assemble + renderPrompt 回归）：https://github.com/zhangchengxiang-ctrl/deepseek-harness/tree/fix/code-mode-sdk-literal-braces