Agent tool schema forces mutually exclusive working_dir and isolation parameters

[jpwong]

Description

In Qwen Code 0.20.0, Agent tool calls generated through an OpenAI-compatible provider can make the optional working_dir and isolation fields behave as if both are required. This makes normal, caller-owned-worktree, and isolated-worktree subagent launches fail validation.

The model can explicitly recognize the conflict and say that it will omit one field, but the next emitted tool call still contains both fields. Repeated retries can eventually trigger loop detection.

Environment

• Qwen Code: 0.20.0
• Model: gpt-5.6-sol
• Provider interface: OpenAI-compatible
• OS: Linux
• Agent type used: built-in Explore

Reproduction 1: caller-owned worktree

Create a Git repository with an existing registered linked worktree, then ask:

Use the Explore subagent to inspect the existing linked worktree at /path/to/repo/.qwen/worktrees/existing. Pin the subagent to that caller-owned worktree and wait for its result.

Expected Agent arguments:

{
  "subagent_type": "Explore",
  "working_dir": "/path/to/repo/.qwen/worktrees/existing",
  "run_in_background": false
}

Actual Agent arguments:

{
  "isolation": "worktree",
  "subagent_type": "Explore",
  "working_dir": "/path/to/repo/.qwen/worktrees/existing",
  "run_in_background": false
}

Result:

Parameters "working_dir" and "isolation" are mutually exclusive.

The model then says it will retry without isolation, but emits the same arguments repeatedly until loop detection stops the run.

Reproduction 2: isolated temporary worktree

Ask:

Use the Explore subagent in a newly created isolated temporary worktree.

Expected Agent arguments:

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

Actual calls contain either:

{
  "isolation": "worktree",
  "working_dir": ""
}

or a non-empty current-repository path in working_dir. The resulting errors are:

Parameter "working_dir" must be a non-empty string when set.

or:

Parameters "working_dir" and "isolation" are mutually exclusive.

Reproduction 3: normal current-repository subagent

Even when asking the Explore agent to run in the current repository without requesting any worktree mode, the generated call can contain both:

{
  "isolation": "worktree",
  "working_dir": "/path/to/repo"
}

and fail with the same mutual-exclusion error.

Relevant implementation detail

The bundled Agent schema in 0.20.0 declares only these fields as required:

required: ["description", "prompt"]

working_dir and isolation are optional in that source schema, and runtime validation correctly rejects their simultaneous presence. However, the model-facing tool declaration appears to force/default both fields. This suggests the issue may be in schema conversion or tool registration between the Agent JSON Schema and the OpenAI-compatible tool declaration.

Expected behavior

• Normal launch: omit both working_dir and isolation.
• Caller-owned worktree: send only working_dir.
• Agent-managed temporary worktree: send only isolation: "worktree".
• Optional tool properties must remain omittable through OpenAI-compatible providers.

Additional impact

Because the model understands the validation error but cannot omit the schema-forced field on retry, it may repeat identical invalid Agent calls and terminate with:

Loop detection halted the run (consecutive_identical_tool_calls...)

[qwen-code-ci-bot]

Triage

• Type: bug
• Labels: type/bug, category/core, priority/P1
• Next: Inspect schema conversion for OpenAI-compatible providers to identify root cause

中文说明

• 类型: bug
• 标签: type/bug, category/core, priority/P1
• 下一步: 检查 OpenAI 兼容 provider 的 schema 转换逻辑，定位根因

---

Root Cause Analysis

Confirmed — the problem is real and the mechanism is clear.

The Agent tool schema (packages/core/src/tools/agent/agent.ts:782) declares additionalProperties: false alongside required: ['description', 'prompt']. The fields working_dir and isolation are genuinely optional in the source schema.

However, the OpenAI conversion path (packages/core/src/core/openaiContentGenerator/converter.ts:344-361) passes the schema through essentially unchanged — convertSchema() in 'auto' mode is a no-op (packages/core/src/utils/schemaConverter.ts:27). Neither the converter nor the schema converter strips additionalProperties or $schema.

Why this breaks: OpenAI's structured-output contract requires that when additionalProperties: false is present, every property must be listed in required. OpenAI-compatible gateways enforce this server-side by promoting all properties to required — forcing the model to emit both working_dir and isolation on every call. The model then hits the mutual-exclusion validation error, retries identically, and triggers loop detection.

Blast radius: 64 occurrences of additionalProperties: false across tool schemas. The Agent tool is the most visibly affected (mutually exclusive optional fields), but any tool with optional fields could see models forced to fill them with empty strings or hallucinated values.

Fix direction: Strip additionalProperties: false (and $schema) in the OpenAI conversion path for non-strict function calling. Client-side validation (validateToolParams) still enforces the constraint — removing it from the wire format just stops the provider from forcing the model to fill in optional fields. Alternatively, the converter could remove additionalProperties: false only when the schema has optional properties not listed in required.

中文说明

已确认——问题真实存在，机制清晰。

Agent 工具的 schema（packages/core/src/tools/agent/agent.ts:782）声明了 additionalProperties: false，同时 required: ['description', 'prompt']。working_dir 和 isolation 在源 schema 中确实是可选的。

但 OpenAI 转换路径（converter.ts:344-361）基本原样传递 schema——convertSchema() 在 'auto' 模式下是空操作（schemaConverter.ts:27）。转换器和 schema 转换器都没有去除 additionalProperties 或 $schema。

为什么会出问题： OpenAI 的 structured-output 合约要求：当 additionalProperties: false 存在时，所有属性必须列入 required。OpenAI 兼容的网关在服务端强制执行这一点，将所有属性提升为 required——迫使模型在每次调用时都输出 working_dir 和 isolation。模型随后触发互斥验证错误，重复重试，最终触发循环检测。

影响范围： 工具 schema 中有 64 处 additionalProperties: false。Agent 工具最明显受影响（互斥的可选字段），但任何有可选字段的工具都可能看到模型被迫填入空字符串或虚构值。

修复方向： 在 OpenAI 转换路径中，对非 strict 函数调用去除 additionalProperties: false（和 $schema）。客户端验证（validateToolParams）仍然执行约束——从 wire format 中移除只是阻止 provider 强迫模型填写可选字段。

— Qwen Code · qwen3.7-max

[zjunothing]

Fix submitted: #7344 — implements the triage's surgical variant. The OpenAI tool-declaration path now runs a relaxSchemaForFunctionCalling pass: additionalProperties: false is removed only on object levels that declare optional properties (fully-required levels keep it — a gateway has nothing to promote there), and $schema/$id are dropped; client-side validateToolParams still enforces the full source schema, so the mutual-exclusion check keeps working — the gateway just can no longer force the model to emit both fields. Wire-format E2E against a fake OpenAI server: before, the agent tool ships additionalProperties: false at top level (11 occurrences across all tool schemas); after, the agent schema is clean with required unchanged and only the 2 fully-required levels retain the constraint.

中文

修复已提交：#7344——按 triage 的外科式方案实现。OpenAI 工具声明路径新增 relaxSchemaForFunctionCalling：仅在声明了可选属性的对象层级移除 additionalProperties: false（全必填层级保留），并删除 $schema/$id；客户端 validateToolParams 仍执行完整源 schema，互斥校验照常生效——只是网关不再能强迫模型同时发出两个字段。伪 OpenAI 服务器的线上格式 E2E：修复前 agent 工具顶层携带该约束（全线 11 处）；修复后 agent schema 干净、required 不变、仅剩 2 处全必填层级保留。