[bug] code 模式下 run_code/bash 同名 required description 导致工具调用死循环

[rongyulin3]

一句话

code 模式下 run_code 和 bash 都把 UI 摘要字段叫 description 且标成 required，模型常把内层 bash.description 当成已经传过，外层 JSON 只剩 {"code":"..."}，于是反复报 missing required property "description"，看起来像工具层随机丢参数。

English summary

In code mode, both run_code and bash require a description that is documented as UI-only. Models frequently put description inside tools.bash({...}) in the code string and omit the outer run_code argument. Validation then fails with the same invalid arguments: missing required property "description" string used for both layers, so the model concludes the harness is dropping fields and retries forever. Session logs show the model never emitted the outer key.

环境

• @deepseek-ai/dsh 0.1.0-rc.6
• agent preset: code（只允许直接调用 run_code）
• 模型：DeepSeek V4（function calling / JSON tool arguments）

复现

1. 用 code preset 开一轮，让模型执行需要 bash 的诊断/搜索。
2. 观察 run_code 的 tool-call arguments 原始 JSON。
3. 失败调用几乎都是：

{"code":"const out = await tools.bash({\n  command: \"...\",\n  description: \"Check port listeners\"\n});\nreturn out.stdout.text;"}

注意：内层 bash 的 description 在 code 字符串里；外层 JSON 没有 "description" 键。

4. 校验立刻失败：Error: invalid arguments: missing required property "description"（ToolArgsError / INVALID_ARGS）。
5. repeat-tool-reminder 把规范化参数回显成 arguments: {"code":"..."}，模型据此认定 harness 丢掉了字段，换内容重试，成功率极低。

一次真实会话的计数（不是抽样感觉）

同一会话 160 次 run_code：

模型实际发出的外层 JSON	次数	结果
只有 code	156	全部 INVALID_ARGS（缺 run_code.description）
code + description	4	3 次成功；1 次失败是因为 内层 bash 没带 description（worker bindingFailure → ToolCallError）

那 156 次里，有 120 次 code 字符串中已经写了 description:。所以这不是传输随机丢字段：JSON.parse 后对象里本来就没有外层键。

对照成功调用（外层键齐全）：

{"code":"... tools.bash({ command: \"...\", description: \"...\" }) ...","description":"Check port 3081 connectivity and listeners"}

失败的“外层有 description、内层没有”的那一次，code 是：

const out = await tools.bash({
  command: "curl ...; lsof ..."
});

报错栈在 dsh-code-runtime-worker-thread 的 bindingFailure，文案仍然是同一句 missing required property "description"。

为什么模型会误判成 harness bug

1. 两个 required 字段同名：run_code.description 和 bash.description，schema 文案都写着 “shown in the UI”。
2. 两层校验失败用同一句 invalid arguments: missing required property "description"。外层是 defineTool 的 ToolArgsError；内层是 worker 把 bash 的 ToolArgsError 包成 ToolCallError。
3. reminder 只展示规范化后的 arguments。外层缺键时，模型看到的就是 {"code":"..."}，于是写 “harness dropped description”。
4. 换 command 内容重试解决不了，因为漏的是 function-call JSON 的顶层键，不是 bash 命令文本。

相关代码：

• dsh-tools createRunCodeTool：code 和 description 都是 required: true；description 说明是 5–10 词 UI 摘要。
• dsh-tool-bash：command 和 description 同样 required: true，README 写明 description 不影响执行。
• dsh-agent-loop parseArguments：JSON.parse(raw)，没有剥键。
• dsh-code-runtime-worker-thread bindingFailure：内层失败也复用同一句 message。

预期

• 缺哪个工具的哪个字段，报错应写明（例如 run_code missing description vs bash missing description）。
• UI 摘要不应让 agent 在 code 模式下陷入不可恢复的重试环。

建议（任选，按侵入性）

1. 报错带工具名：invalid arguments for run_code: missing required property "description" / invalid arguments for bash: ...。这是最小改动，能打破“harness 丢参数”的错误归因。
2. 把 description 改成 optional，缺省时用 command/code 截断当 UI 标题（README 已说它不影响执行）。
3. 改名消歧义：外层改成 summary / label，避免和 SDK 里每个工具的 description 撞名。
4. 校验失败时提示正确形状，明确要求顶层 JSON 同时有 code 和 description，内层 bash 的 description 不能代替外层。

验收

• 只有内层 bash({command, description})、外层缺 description 时，错误明确说是 run_code 缺字段，而不是让模型以为传输丢了。
• 外层齐全、内层 bash 缺 description 时，错误明确说是 bash。
• code 模式下连续 run_code 不再因为同名 UI 字段出现接近 97% 的 INVALID_ARGS 死循环。

[ericcaiwx-star]

Minimal fix for the identical-error attribution (tool name in ToolArgsError): #581 — branch ericcaiwx-star/deepseek-harness:fix/tool-args-error-names-tool (b5de96e5de). Does not change whether description is required.