fix(agent): ignore empty working_dir placeholders

[Truraly]

What this PR does

Normalizes empty and whitespace-only working_dir values to an omitted value before Agent parameter routing. This lets subagent calls continue when an OpenAI-compatible model emits an empty placeholder for the optional field, including isolated worktree launches. Non-empty working_dir values continue through the existing validation and mutual-exclusion checks.

Why it's needed

Some OpenAI-compatible models emit every declared tool property even when the property is optional. For Agent calls, this can produce working_dir: "", which is rejected before an otherwise valid launch can proceed. This change provides a narrow compatibility path for empty placeholders while leaving non-empty path validation intact.

Reviewer Test Plan

How to verify

Run the focused Agent tool test and confirm empty and whitespace-only working_dir values are removed, calls with isolation: "worktree" are no longer rejected solely because of an empty placeholder, and non-empty working_dir plus isolation remains rejected as mutually exclusive.

cd packages/core && npx vitest run src/tools/agent/agent.test.ts

Also confirm the repository builds and type-checks:

npm run build
npm run typecheck

Evidence (Before & After)

Before: a generated Agent tool call containing working_dir: "" failed with Parameter "working_dir" must be a non-empty string when set.

After: empty and whitespace-only placeholders are treated as omitted; existing validation still applies to non-empty paths.

Tested on

OS	Status
🍏 macOS	⚠️ not tested
🪟 Windows	⚠️ not tested
🐧 Linux	✅ tested

Environment (optional)

Node.js development environment using the repository workspace. Verified with the focused 169-test Agent suite, full build, and full typecheck.

Risk & Scope

• Main risk or tradeoff: callers that intentionally pass an empty working_dir now receive the same behavior as callers that omit it.
• Not validated / out of scope: models that emit a non-empty unwanted working_dir, broader OpenAI-compatible schema conversion behavior, macOS, and Windows runtime behavior.
• Breaking changes / migration notes: none.

Linked Issues

Addresses part of #7315.

中文说明

此 PR 的改动

在 Agent 参数路由前，将空字符串及仅含空白字符的 working_dir 归一化为未传值。如此，当 OpenAI 兼容模型为可选字段输出空占位时，子代理调用仍可继续，包括隔离 worktree 启动。非空 working_dir 仍沿用现有校验与互斥检查。

为什么需要

部分 OpenAI 兼容模型会输出工具 schema 中声明的所有属性，即使属性并非必填。Agent 调用因此可能带有 working_dir: ""，导致原本有效的调用在启动前被拒绝。本改动仅兼容空占位，不放宽非空路径校验。

Reviewer Test Plan

如何验证

运行 Agent 工具定向测试，确认空字符串与纯空白 working_dir 会被移除，带 isolation: "worktree" 的调用不再仅因空占位而失败，且非空 working_dir 与 isolation 同时出现时仍以互斥错误拒绝。

cd packages/core && npx vitest run src/tools/agent/agent.test.ts

并确认全仓构建与类型检查通过：

npm run build
npm run typecheck

前后证据

修改前：Agent tool call 若包含 working_dir: ""，会报 Parameter "working_dir" must be a non-empty string when set.。

修改后：空字符串及纯空白占位按未传处理；非空路径仍执行原有校验。

测试平台

OS	状态
🍏 macOS	⚠️ 未测试
🪟 Windows	⚠️ 未测试
🐧 Linux	✅ 已测试

环境

使用仓库工作区的 Node.js 开发环境。已验证 Agent 定向测试 169 项、全仓构建及全仓类型检查。

风险与范围

• 主要风险或权衡：调用方若有意传入空 working_dir，现会得到与省略该字段相同的行为。
• 未验证或范围外：模型输出非空但非预期的 working_dir、更广泛的 OpenAI 兼容 schema 转换问题、macOS 与 Windows 运行行为。
• 破坏性变更或迁移说明：无。

关联 Issue

处理 #7315 的部分问题。

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓

Problem: observed bug with evidence — linked issue #7315 documents three concrete reproductions where OpenAI-compatible models emit empty working_dir placeholders that fail validation. This PR targets Reproduction 2 (empty/whitespace working_dir alongside isolation: "worktree"). Not theoretical.

Direction: aligned. OpenAI-compatible provider support is core to qwen-code, and models that emit every declared tool property (even optional ones) are a known real-world pattern. The fix is narrowly scoped to empty placeholders and doesn't relax validation for non-empty paths.

Size: 2 files, ~9 production lines in agent.ts (test file excluded). Well under any threshold. Not applicable for maintainer awareness.

Approach: the scope feels right — normalizing empty/whitespace/null working_dir to undefined before the existing validation is the minimal fix for this specific failure mode. One note: the mutation happens inside validateToolParams, which is semantically a validation function. It works because BaseDeclarativeTool.build() passes the same object through to createInvocation, but it's worth being aware that this is a validate-and-normalize pattern rather than pure validation. Not a blocker — the alternative (overriding build()) would be more code for the same effect. The PR honestly states it addresses only part of #7315; the non-empty working_dir + isolation case (Reproductions 1 and 3) remains open.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓

问题：已观测到的 bug，有证据——关联 issue #7315 记录了三个具体复现，OpenAI 兼容模型输出空 working_dir 占位导致校验失败。本 PR 针对复现 2（空/纯空白 working_dir 与 isolation: "worktree" 同时出现）。非理论性问题。

方向：对齐。OpenAI 兼容 provider 支持是 qwen-code 的核心功能，模型输出所有声明的工具属性（包括可选属性）是已知的真实场景。修复仅针对空占位，不放宽非空路径校验。

规模：2 个文件，agent.ts 中约 9 行生产代码（测试文件不计）。远低于任何阈值。无需维护者关注。

方案：范围合理——在现有校验前将空/纯空白/null working_dir 归一化为 undefined 是针对此特定失败模式的最小修复。注意：归一化发生在 validateToolParams 内部，语义上是校验函数。之所以可行，是因为 BaseDeclarativeTool.build() 将同一对象传递给 createInvocation，但需意识到这是"校验+归一化"模式而非纯校验。不构成阻塞——替代方案（重写 build()）代码更多但效果相同。PR 诚实声明仅处理 #7315 的部分问题；非空 working_dir + isolation 的情况（复现 1 和 3）仍待解决。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

_{Reviewed at 475194121fda87feee96451e2103de445d25db07 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code Review

Independent proposal: normalize empty/whitespace-only/null working_dir to undefined before the existing validation checks, add tests for each normalization case, and keep all existing validation for non-empty values intact.

Comparison: the PR does exactly this. The 9-line normalization block sits right before the isolation and working_dir validation, so empty placeholders are gone before they can trigger false "must be a non-empty string" or "mutually exclusive" errors. Non-empty values flow through to the existing checks unchanged.

No critical blockers found. One observation: the normalization mutates params inside validateToolParams, which is semantically a validation function. This works because BaseDeclarativeTool.build() passes the same object to createInvocation, but it's a validate-and-normalize pattern rather than pure validation. Not a blocker — the alternative (overriding build()) would be more code for the same effect, and the tests explicitly verify the mutation.

Minor nit: the code comment says "With isolation selected, normalize it away" but the normalization applies to all cases (empty working_dir is normalized regardless of whether isolation is set). The comment describes the primary motivation rather than the full behavior. Not worth a change request.

Testing

Unit tests (primary evidence — the bug is triggered by model behavior that can't be deterministically reproduced in tmux):

 ✓ src/tools/agent/agent.test.ts (169 tests) 1830ms

 Test Files  1 passed (1)
      Tests  169 passed (169)

Build + typecheck: both pass.

tmux smoke test (Agent tool works with PR code, no regression):

$ npm run dev -- -p 'I need you to use the Agent tool (not glob or ls) to spawn
  an Explore subagent that lists files in packages/core/src/tools/agent.'
  --output-format text -y

> @qwen-code/qwen-code@0.20.0 dev
> node scripts/dev.js -p I need you to use the Agent tool (not glob or ls) to
  spawn an Explore subagent that lists files in packages/core/src/tools/agent.
  --output-format text -y

The Explore subagent found **4 files** in `packages/core/src/tools/agent/`:

| # | File |
|---|------|
| 1 | `agent.ts` |
| 2 | `agent.test.ts` |
| 3 | `agent-override.test.ts` |
| 4 | `fork-subagent.ts` |

No subdirectories exist in that folder.

The specific bug scenario (model emitting working_dir: "" alongside isolation: "worktree") depends on OpenAI-compatible model behavior and cannot be triggered deterministically in a tmux session. The 169-test suite covers the normalization directly, including the empty + isolation combination.

中文说明

代码审查

独立方案： 在现有校验前将空/纯空白/null working_dir 归一化为 undefined，为每种归一化情况添加测试，保持非空值的现有校验不变。

对比： PR 完全匹配此方案。9 行归一化代码位于 isolation 和 working_dir 校验之前，空占位在触发错误的"必须为非空字符串"或"互斥"错误前即被移除。非空值照常通过现有检查。

未发现关键阻塞问题。一点观察：归一化在 validateToolParams 内部修改了 params，语义上这是校验函数。之所以可行，是因为 BaseDeclarativeTool.build() 将同一对象传递给 createInvocation，但这是"校验+归一化"模式而非纯校验。不构成阻塞——替代方案（重写 build()）代码更多但效果相同，且测试明确验证了修改行为。

小瑕疵：代码注释写"With isolation selected, normalize it away"，但归一化适用于所有情况（无论是否设置 isolation，空 working_dir 都会被归一化）。注释描述的是主要动机而非完整行为。不值得要求修改。

测试

单元测试（主要证据——bug 由模型行为触发，无法在 tmux 中确定性复现）：169 项全部通过。

构建 + 类型检查： 均通过。

tmux 冒烟测试： Agent 工具在 PR 代码下成功启动 Explore 子代理，无回归。

具体 bug 场景（模型输出 working_dir: "" 与 isolation: "worktree" 同时出现）取决于 OpenAI 兼容模型行为，无法在 tmux 会话中确定性触发。169 项测试套件直接覆盖了归一化逻辑，包括空值 + isolation 的组合。

— Qwen Code · qwen3.7-max

_{Reviewed at 475194121fda87feee96451e2103de445d25db07 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — clean, minimal fix for a real P1 bug; would merge without hesitation.

This is exactly the kind of PR I like to see. Nine lines of production code that solve a concrete problem users are hitting with OpenAI-compatible providers — models that emit every declared tool property, even optional ones, producing working_dir: "" that trips validation. The normalization is placed at the right spot (before both the isolation and working_dir checks), handles all three degenerate cases (empty string, whitespace-only, null), and leaves non-empty validation completely untouched.

The tests are thorough: the two existing "rejects empty/whitespace working_dir" tests are updated to assert normalization instead of rejection, and two new tests cover the empty + isolation combination that was the primary failure mode in #7315. All 169 tests pass, build and typecheck are clean, and the Agent tool works in a live tmux session.

The PR honestly scopes itself to "part of #7315" — the non-empty working_dir + isolation case (Reproductions 1 and 3) remains open and will need a different approach (you can't just discard a non-empty path the model provided). That's fine; this PR solves the most clear-cut failure mode without overreaching.

中文说明

置信度：5/5 —— 干净、最小的修复，解决真实 P1 bug；毫不犹豫合并。

这正是我希望看到的 PR。9 行生产代码解决了用户在使用 OpenAI 兼容 provider 时遇到的具体问题——模型输出所有声明的工具属性（包括可选属性），产生 working_dir: "" 触发校验错误。归一化放在正确位置（isolation 和 working_dir 检查之前），处理了三种退化情况（空字符串、纯空白、null），非空校验完全不受影响。

测试全面：两个现有的"拒绝空/纯空白 working_dir"测试更新为断言归一化而非拒绝，两个新测试覆盖了空值 + isolation 的组合（#7315 中的主要失败模式）。169 项测试全部通过，构建和类型检查干净，Agent 工具在 tmux 实时会话中正常工作。

PR 诚实声明范围为"#7315 的部分问题"——非空 working_dir + isolation 的情况（复现 1 和 3）仍待解决，需要不同方案（不能直接丢弃模型提供的非空路径）。这没问题；本 PR 解决了最明确的失败模式，没有过度扩展。

— Qwen Code · qwen3.7-max

_{Reviewed at 475194121fda87feee96451e2103de445d25db07 · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[wenshao]

Local real-run verification (merge reference)

I built this PR from its head (475194121) and verified it locally on Linux / Node 22, including a real TUI run driving the actual built bundle against a scripted OpenAI-compatible model. Summary: the fix does exactly what it claims, the added tests genuinely gate it, and no existing working_dir/isolation guard regresses. LGTM as a targeted compatibility fix.

1. Focused unit suite — 169/169 ✅

cd packages/core && npx vitest run src/tools/agent/agent.test.ts
→ Test Files 1 passed | Tests 169 passed (169)

The four targeted cases (empty / whitespace-only working_dir, each with and without isolation:"worktree") are green.

2. Negative control (RED → GREEN) ✅ — proves the tests aren't vacuous

Reverting only the production hunk (git show <merge-base>:…/agent.ts > …/agent.ts) while keeping the PR's new tests makes exactly the four new tests fail, and nothing else:

× treats an empty working_dir as unset
× treats a whitespace-only working_dir as unset
× treats an empty working_dir as unset when isolation is set
× treats a whitespace-only working_dir as unset when isolation is set
   (all other 165 stay green — restore → 169/169)

The existing guards (rejects working_dir combined with isolation, … combined with run_in_background, … without an explicit subagent_type, etc.) stay green in both directions → the normalization does not weaken any non-empty-path validation.

3. Typecheck ✅

tsc --noEmit on packages/core is clean. The params.working_dir === null guard type-checks fine — TypeScript exempts null/undefined literal comparisons from the no-overlap rule.

4. Build / bundle ✅

packages/core builds; the CLI bundles to a runnable dist/cli.js (boots as v0.20.0 and ran the E2E below). The bundled chunk contains the normalization (params.working_dir = void 0 after the empty/null check); after reverting the source it is absent — so the A/B below really reflects the source change.

5. Real TUI end-to-end — the actual #7315 symptom, before vs after

Booted the built TUI against a fake model that emits the exact Agent call from issue #7315 Reproduction 2:

{ "subagent_type": "Explore", "isolation": "worktree", "working_dir": "", "run_in_background": false }

Before (base): the call is rejected before launch — Parameter "working_dir" must be a non-empty string when set. This is the validation error that, per #7315, the model then loops on until loop-detection halts the run.

After (this PR): the empty placeholder is normalized away, so validation passes and the Explore subagent launches in an isolated worktree and returns its report (✔ Explore … 0 tools). The fake-server request log confirms the subagent actually ran — its own "file search specialist" system prompt fired as a separate model call, i.e. the worktree was really provisioned and the child executed inside it.

Notes for the merge decision

• Correct & low-risk. Empty / whitespace / null working_dir is normalized to omitted before the mutual-exclusion and non-empty checks; a non-empty working_dir + isolation is still correctly rejected as mutually exclusive (verified in both suites and the negative control).
• Scope. This closes the empty-placeholder slice of Agent tool schema forces mutually exclusive working_dir and isolation parameters #7315 only. The cases where the model emits a non-empty unwanted working_dir alongside isolation (Repro 1 & 3) still fail with mutual-exclusion by design — the PR body already calls this out. This is a runtime compatibility path, not a fix of the OpenAI-compatible schema conversion that leads the model to emit both fields; that root cause remains open.
• Behavior change (acceptable). A caller that intentionally sent working_dir:"" now gets omit-semantics instead of an error — reasonable, since "" was never a valid worktree path.
• Minor, non-blocking nit. The code comment says "With isolation selected, normalize it away," but the normalization runs regardless of isolation (the two no-isolation tests confirm this). The comment is narrower than the behavior.

Status at time of writing

CI Test (ubuntu-latest, Node 22.x) is still pending and the PR is REVIEW_REQUIRED; the above is independent local evidence to support the merge, not a substitute for those gates.

中文说明

本地真实构建验证（合并参考）

我从 PR head（475194121）在本地 Linux / Node 22 完整构建并验证了本 PR，其中包括一次真实 TUI 运行：用构建产物驱动真实 CLI，对接一个脚本化的 OpenAI 兼容假模型。结论：改动确实实现了其声明的效果，新增测试确实对该改动起到判别作用，且没有任何既有的 working_dir/isolation 校验被削弱。作为一处定向兼容性修复，倾向同意合并（LGTM）。

1. 定向单测 —— 169/169 ✅

cd packages/core && npx vitest run src/tools/agent/agent.test.ts
→ Test Files 1 passed | Tests 169 passed (169)

四个目标用例（空串 / 纯空白 working_dir，各自在有 / 无 isolation:"worktree" 下）全部通过。

2. 反向对照（RED → GREEN）✅ —— 证明测试非空转

仅回退生产代码那段改动（git show <merge-base>:…/agent.ts > …/agent.ts）、保留 PR 新增的测试后，恰好只有这四个新测试失败，其余不受影响：

× treats an empty working_dir as unset
× treats a whitespace-only working_dir as unset
× treats an empty working_dir as unset when isolation is set
× treats a whitespace-only working_dir as unset when isolation is set
   （其余 165 项保持绿色；恢复后 169/169）

既有校验（rejects working_dir combined with isolation、… combined with run_in_background、… without an explicit subagent_type 等）在两个方向上都保持绿色 —— 归一化没有放宽任何非空路径的校验。

3. 类型检查 ✅

packages/core 的 tsc --noEmit 干净通过。params.working_dir === null 这处判断不会报错 —— TypeScript 对 null/undefined 字面量比较豁免了「类型无重叠」规则。

4. 构建 / 打包 ✅

packages/core 可构建；CLI 可打包为可运行的 dist/cli.js（以 v0.20.0 启动并跑通了下方 E2E）。打包后的 chunk 含有归一化逻辑（空/null 判断后 params.working_dir = void 0）；回退源码后该逻辑消失 —— 因此下方的前后对比确实反映的是源码改动本身。

5. 真实 TUI 端到端 —— #7315 的真实现象，前后对比

用假模型驱动真实 TUI，发出 issue #7315 复现 2 中完全一致的 Agent 调用：

{ "subagent_type": "Explore", "isolation": "worktree", "working_dir": "", "run_in_background": false }

修改前（base）： 调用在启动前被拒 —— Parameter "working_dir" must be a non-empty string when set.。按 #7315 所述，模型随后会对此反复重试，直至触发循环检测而中止。

修改后（本 PR）： 空占位被归一化去除，校验通过，Explore 子代理在隔离 worktree 中成功启动并返回结果（✔ Explore … 0 tools）。假服务器请求日志确认子代理确实运行了 —— 它自身的「file search specialist」系统提示作为一次独立的模型请求出现，即 worktree 确实被创建、子代理确实在其中执行。

合并决策备注

• 正确且低风险。 空串 / 纯空白 / null 的 working_dir 会在互斥检查与非空检查之前被归一化为「未传」；而非空 working_dir 与 isolation 同时出现时仍被正确判为互斥拒绝（两套测试与反向对照均已验证）。
• 范围。 本 PR 只解决 Agent tool schema forces mutually exclusive working_dir and isolation parameters #7315 中「空占位」这一部分。模型输出非空但非预期 working_dir 且带 isolation 的情形（复现 1、3）仍按设计以互斥报错 —— PR 描述已明确说明。这是一条运行时兼容路径，并非对「OpenAI 兼容 schema 转换导致模型同时输出两个字段」这一根因的修复；根因仍待处理。
• 行为变化（可接受）。 有意传入 working_dir:"" 的调用方，现在得到的是「按未传处理」而非报错 —— 合理，因为 "" 从来就不是合法的 worktree 路径。
• 小瑕疵（不阻塞）。 代码注释写的是「With isolation selected, normalize it away」，但归一化实际上与是否设置 isolation 无关（两个无 isolation 的测试即为佐证）。注释的表述比实际行为更窄。

撰写时状态

CI Test (ubuntu-latest, Node 22.x) 仍在 pending，PR 处于 REVIEW_REQUIRED；以上为支持合并的独立本地证据，并不替代这些门禁。

---

🤖 Generated with Claude Code — Claude Opus 4.8 (1M context)

[doudouOUC]

Reviewed — no blockers. Suggestions are inline. 1 Suggestion-level finding(s) could not be anchored to a changed line and were dropped; nothing further to act on here.

— qwen3.7-max via Qwen Code /review

[doudouOUC]

[Suggestion] Comment says "With isolation selected" but the normalization block below has no params.isolation condition — it runs unconditionally for all callers. Two of the four new tests confirm this by exercising normalization without isolation set.

Failure scenario: A future maintainer reads "With isolation selected" and assumes normalization should only fire when isolation is set. They add an isolation guard, reintroducing #7315 for non-isolation callers where models emit empty working_dir.

Suggested change

	// Some models emit an empty placeholder for the unused optional field.
	// With isolation selected, normalize it away before downstream routing.
	// Some models emit an empty placeholder for the unused optional field.
	// Normalize it away before downstream routing.

— qwen3.7-max via Qwen Code /review

[doudouOUC]

[Suggestion] The === null branch has no test coverage. All four new tests use empty or whitespace-only strings; none pass null.

Failure scenario: A future refactor simplifies the condition to only the string-trim check, dropping the null arm. Models sending working_dir: null would then hit the downstream typeof !== 'string' check and be rejected with "must be a non-empty string when set" — the exact spurious rejection this PR prevents.

Consider adding a test:

it('treats a null working_dir as unset', () => {
  const params = {
    ...validParams,
    working_dir: null as unknown as string,
  };
  expect(agentTool.validateToolParams(params)).toBeNull();
  expect(params.working_dir).toBeUndefined();
});

— qwen3.7-max via Qwen Code /review

[gwinthis]

本地验证报告 — PR #7343

论点：此 PR 应合并。 将空 working_dir 从"拒绝"改为"归一化为 undefined"是正确的模型行为适配，单元测试全部通过，CLI 在此分支上正常运行。

验证环境

• macOS darwin, Node v22.22.1
• 分支：fix/agent-empty-working-dir（通过 pull/7343/head 拉取）

1. 单元测试（169/169 通过）

cd packages/core && npx vitest run src/tools/agent/agent.test.ts

 ✓ src/tools/agent/agent.test.ts (169 tests) 41617ms
   ✓ treats an empty working_dir as unset
   ✓ treats a whitespace-only working_dir as unset
   ✓ treats an empty working_dir as unset when isolation is set
   ✓ treats a whitespace-only working_dir as unset when isolation is set
   ... (165 other tests)

 Test Files  1 passed (1)
      Tests  169 passed (169)
   Duration  47.71s

4 个新增测试精确覆盖了行为变更：空字符串、纯空白、与 isolation 组合的空字符串、与 isolation 组合的纯空白。所有既有测试（包括 rejects working_dir combined with isolation）继续通过，证明归一化不破坏互斥校验。

2. tmux CLI 启动验证

$ npx tsx packages/cli/src/cli.ts --version
0.20.0

CLI 在此分支上正常编译运行，无启动错误。

3. 代码审查

变更仅 9 行（agent.ts L1031-1039），在 validateToolParams 的 isolation 互斥校验之前插入归一化：

if (
  (typeof params.working_dir === 'string' &&
    params.working_dir.trim().length === 0) ||
  params.working_dir === null
) {
  params.working_dir = undefined;
}

位置正确：归一化在互斥校验之前，确保 isolation + working_dir: "" 不会误触发 working_dir and isolation are mutually exclusive 错误。

论据链：

1. 部分模型（尤其是较小模型）会为未使用的可选字段生成空占位符 "" 或 " "
2. 旧行为：拒绝 → 模型收到错误 → 重试 → 浪费 token 和延迟
3. 新行为：静默归一化为 undefined → 等同于未传 → 零开销
4. 互斥校验不受影响：归一化后 working_dir 为 undefined，不会触发 isolation 互斥
5. 169 个测试全部通过，包括 4 个新增测试和所有既有回归测试

结论：合并安全，无回归风险。