建议：ToolArgsError 报错带上工具名，并考虑放宽 run_code 的 description 必填

[luxueliu]

现象

Code Mode（agentPreset=code）下模型只能直接调 run_code。当某次 run_code 调用缺少必填参数 description 时，工具结果只返回：

Error: invalid arguments: missing required property "description"

这条报错没有指明是哪个工具、哪个层级的参数。实际调试中，模型（deepseek-v4-flash）连续 13 次把 description 写进了 code 字符串内部的 tools.pwsh({ ... description: ... })，而不是写在 run_code 顶层参数对象里；每次收到同一条报错，模型都误判为「内层参数 / 引号转义 / 序列化」问题并原地重试，浪费了大量轮次。

数据

同一个本地会话（deepseek-v4-flash，官方 API）：

• 17 次 run_code 调用，13 次漏传顶层 description，全部被拒（错误均为上述 INVALID_ARGS）；
• 4 次带全 code + description 则全部成功。

说明这不是解析层 bug，而是模型在该任务上下文下对「run_code 顶层必填 description」的遵循不稳定（同一模型的其它会话 131/131 合规；deepseek-v4-pro 系几百次调用零遗漏）。

建议

1. ToolArgsError 报错带上工具名与参数路径，例如：
   invalid arguments for tool run_code: missing required property "description" (top-level)
   现在 dsh-tools 的 ToolArgsError 只输出 invalid arguments: ...，模型和用户无法区分是 run_code 顶层缺参还是内层工具缺参，非常容易误诊。

2. 考虑把 run_code 的 description 改为可选（或提供默认值）。description 目前只作为 UI 展示标签（title: args.description）加一条非空校验，对执行结果没有影响；把它设为必填却要所有模型稳定遵守，成本高于收益。若保留必填，建议在 tools:sdk 指令里把「run_code 顶层 description」与「tools.* 内层 description」的层级关系写得更显式。

版本：@deepseek-ai/dsh 0.1.0-rc.7

[luxueliu]

补充：这个建议我已经做了最小实现并验证，改动在 https://github.com/xiedongqingxiao-ops/deepseek-harness/tree/fix/toolargs-error-tool-name （commit 1444bbbba6，3 个文件 +8/-8）：

• ToolArgsError 构造函数增加 toolName，报错变为 invalid arguments for tool <name>: ...
• defineTool 的 execute 校验路径传入 tool.name；子代理 structured_output 校验路径传入 STRUCTURED_OUTPUT_TOOL
• 相关测试断言已同步更新

验证：packages/core/tools/tests/tools.spec.ts 136 个测试通过；packages/subagent/subagent-in-process-driver 相关 48 个测试通过。

本想直接提 PR，但仓库当前 has_pull_requests=false（PR 创建与列表接口均返回 404），PR 通道似乎已关闭。如果官方愿意收这类小改动，可以直接从上述分支拉取，或重新开启 PR 通道；需要我调整实现也请随时说。

[argszero]

English summary: source-verified at rc.7 (99f6f02). ToolArgsError (schema.ts:461-470) indeed carries no tool name — invalid arguments: ${violations}. The fix shape (adding toolName, passing tool.name at schema.ts:587 and STRUCTURED_OUTPUT_TOOL at structured.ts:89) covers exactly the two throw sites. But there's a second half to your suggestion #1 that the current implementation doesn't address: violations are already path-qualified via propertyPath (json-schema.ts:422-424), but at the TOP level the path collapses to the bare property name (path === '' ? key : path.key) — so missing required property "description" is structurally indistinguishable from a nested tools.pwsh.description tail. The minimal complement is a (top-level) marker when path === '' — exactly your original example. On suggestion #2: verified description is used only as title: args.description (code-mode.ts:655), so relaxing it is execution-safe; with toolName + (top-level) the retry-loop cost drops substantially, making "keep required" defensible — either way the two changes are independent and both are PR-ready when the channel opens.

源码验证（rc.7 99f6f02fec）——你的分析完全正确，且你的最小实现已经覆盖了两个 throw 点。但建议 #1 有一半没落地，值得补齐。

1. 机制确认（源码）

• ToolArgsError（packages/core/tools/src/schema.ts:461-470）：消息就是 invalid arguments: ${violations.join('; ')}——确实没有工具名，也没有"层级"信息。
• 两个 throw 点你全找到了：
  • defineTool.execute 校验路径（schema.ts:587）——tool.name 就在作用域内；
  • 子代理 structured_output 校验路径（subagent-in-process-driver/src/structured.ts:89）——传 STRUCTURED_OUTPUT_TOOL 正确。
• 你的分支改动方向（构造函数加 toolName + 两处传入）就是正确的最小修复。

2. 建议 #1 缺失的一半：路径在顶层会塌缩

violation 字符串本身是带路径的：

// packages/core/tools/src/json-schema.ts:422-424
function propertyPath(path: string, key: string): string {
  return path === '' ? key : `${path}.${key}`
}

但顶层（path === ''）塌缩成裸属性名——missing required property "description" 和嵌套的 tools.pwsh.description 尾部结构上不可区分。这正是你描述的误诊场景的精确机制：模型看到 description，无法判断是 run_code 顶层还是内层。

你的实现加了工具名（invalid arguments for tool run_code: ...），但路径层级歧义还在。补齐最小改动（你原帖例子里的 (top-level)）：

function propertyPath(path: string, key: string): string {
  return path === '' ? `${key} (top-level)` : `${path}.${key}`
}

或者更通用：顶层加 . 前缀让层级自洽（missing required property ".description" vs 嵌套 "tools.pwsh.description"）。无论哪种，都是 json-schema.ts 一行 + 断言更新——和你现有改动同一量级。

3. 建议 #2（description 改可选）的评估

已验证你的依据成立：code-mode.ts:655 title: args.description——description 的唯一消费方是 UI 标题，对执行结果零影响（code 才是唯一执行载荷，:308 required）。

两个选项都成立，取决于维护者偏好：

• 保持必填：有了工具名 + (top-level) 标记后，模型误诊循环成本骤降（你的数据：13 次误判 → 错误信息自解释后应显著收敛）；且 description 必填对 UI 有保证（title 永不缺失）。这是"错误信息修复优先"的路线。
• 改为可选：required: true 去掉 + render 侧 title: args.description ?? RUN_CODE_NAME 兜底（code-mode.ts:655 处）。执行安全，但属于 schema 语义变更，需要过一遍 tools 套件的 schema 断言（tools.spec.ts 有参数 schema 结构断言，改动会触碰）。

建议拆分提交：工具名 + (top-level) 是一个独立小 PR（错误信息可诊断性，纯增量、零语义变更）；description 可选是另一个（schema 语义变更，需评审）。两个都 ready 了，通道开启即可落地。

4. 一个额外观察

你的 13/17 失败率 vs 另一会话 131/131 合规说明这是模型上下文敏感而非解析 bug——你已排除得干净。但同族还有一层：INVALID_ARGS 错误目前是 isError 结果进入模型重试循环（structured.ts 注释明说 "the model retries within the same turn"），如果错误信息里带上上次失败的具体参数快照（哪个 key 缺了、当前给了哪些），重试收敛会更快。这是超出本次修复的可选增强，先记录。

补充：structured.ts:89 的 ToolArgsError 注释确认了同一错误族的行为契约——model retries within the same turn，所以错误信息的可诊断性直接决定重试轮次成本，你这波改动的杠杆比表面看起来大。

[luxueliu]

感谢 @argszero 的源码级复核！按你的两条意见补齐了，分支 fix/toolargs-error-tool-name 已更新（1444bbbba6 之上新增两个 commit）：

commit 22fc3df88b — 顶层 (top-level) 标记

• 按你指出的 json-schema.ts:422-424 塌缩机制，新增 propertyDisplayPath：顶层必填缺失报 missing required property "description (top-level)"，嵌套保持 tools.pwsh.description 不变。
• 注意没有改 propertyPath 本身——它还用于子帧递归路径（570 行 children 的 path），只在 required-violation 文案层加展示标记，避免破坏嵌套路径计算。
• 同步更新 tools.spec.ts（6 处断言）与 tool-bash tools.spec.ts（2 处正则）。

commit 33669ef955 — run_code description 改可选

• 两处 schema 发射（静态校验 spec + 语言感知 getter）都去掉 description 的 required；
• execute 守卫改为仅对「已提供但为空串」抛 invalid description，缺省时放行；
• presentCall 标题回退 title: args.description ?? RUN_CODE_NAME；
• TS/Python 两个 flavor 描述与 SDK 指令文本同步改为「code 必填 + description 可选（缺省用工具名）」。

验证：tools / code-mode / ts-types / py-types / json-schema 5 个 spec 共 315 个测试通过；subagent structured 相关 48 个通过。

同意你说的拆法：错误信息可诊断性（纯增量、零语义变更）与 schema 语义变更（需评审）各自独立。PR 通道目前仍处于关闭状态，分支保持同步，随时可收。