Code Mode fails when a tool description contains literal {{...}} text: malformed prompt variable reference in section "tools:sdk"

[Max-LiQingYang]

Summary

Running an agent in Code Mode (the code preset, shown as "PTC 模式" in the web GUI) fails every turn with:

本轮运行失败 malformed prompt variable reference "{{dotted.state.path}}" in section "tools:sdk" (variable names match /^[a-z][a-z0-9_]*$/)

Root cause

In Code Mode the generated tools:sdk prompt section embeds every visible tool's schema description (and property descriptions) verbatim as JSDoc (renderToolsSdk in packages/core/tools/src/ts-types.ts, docLines). The section is a normal prompt section, so renderPrompt's strict interpolator (packages/core/system-prompt/src/index.ts) scans that generated text for {{variable}} references, and variable names must match /^[a-z][a-z0-9_]*$/. Any tool description containing a literal {{…}} group — for example a graph tool documenting its own {{dotted.state.path}} template syntax — makes prompt rendering throw before any model request, so every turn fails.

Tool descriptions are third-party plugin text, not authored prompt templates, and section text has no escape syntax for literal braces.

Reproduction

1. Mount any tool whose schema description contains a literal {{...}} group (e.g. {{dotted.state.path}}).
2. Run an agent in Code Mode (code preset / PTC 模式).
3. Every turn fails with the malformed prompt variable reference ... in section "tools:sdk" error.

Native (non-Code) mode is unaffected because descriptions travel inside the JSON tool schema without interpolation.

Impact

Any deployment whose tool descriptions contain {{...}} — common for tools that document their own template syntax — cannot use Code Mode at all.

Proposed fix

Mark the SDK section raw on PromptSection so generated sections skip prompt-variable interpolation entirely; see the accompanying PR.

[Max-LiQingYang]

A fix is ready and pushed to Max-LiQingYang/deepseek-harness branch fix/tools-sdk-raw-section (commit c2af02e): PromptSection gains an opt-in raw flag and the Code Mode tools:sdk section registers raw: true, so generated SDK text is emitted verbatim and tool descriptions containing literal {{…}} groups can no longer fail prompt rendering. Includes unit tests, a code-mode regression spec, bilingual docs, and an Agent Note. The repository currently has pull requests disabled ("An owner of this repository has disabled the ability to open pull requests"), so the change is filed here rather than as a PR; the compare page will work once PRs are re-enabled.

[zoahdev]

同类问题在 #1341 已有记录（同一根因：工具 description 原样嵌入 tools:sdk，严格插值器把字面量 {{...}} 当变量引用且变量名必须是 /^[a-z][a-z0-9_]*$/）。你定位的 renderToolsSdk 链路与那帖一致。两条建议：1) 变量名正则与转义规则应该对生成式 section 豁免或先转义字面量；2) 短期 workaround 是避免在工具 description 里写 {{（或写成 { {）。如需把这帖合并进 #1341 的修复讨论，我可以把两边的复现信息并到一起。

[denial123789]

I updated the existing source-backed Code Mode runbook with this dotted-path reproduction and reviewed c2af02e as a contributor proposal rather than an upstream fix. The new case is useful because it covers the grammar-failure branch (malformed) in addition to the earlier valid-but-unregistered branch (unknown).

The raw-section design is stronger than description-only escaping: generated SDK text can also contain double-brace groups through special property names, enum values, and const strings. The regression matrix therefore checks those carriers plus raw propagation through assembly replacement and complete-section selection, while ordinary persona sections remain strict.

Visual boundary and operator recovery:
https://sandbaseai.github.io/deepseek-harness-handbook/code-mode-unknown-prompt-variable.html

Canonical revision 2 and complete gates:
https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/code-mode-unknown-prompt-variable.md