docs: document tools.disabled and tools.visible settings

[Nas01010101]

What this PR does

Adds the missing settings-reference rows for tools.disabled and tools.visible in docs/users/configuration/settings.md.

Why it's needed

Both settings are implemented and wired end to end (settings schema, normalizeDisabledTools.ts, and the ToolRegistry registration gate, which has test coverage in tool-registry.test.ts), but neither appears in the settings reference. Their deprecated siblings tools.core, tools.exclude, and tools.allowed are all documented, so users find the deprecated options and miss the live ones.

This matters in practice: tools.disabled already answers a recurring request. For example, #5970 asked for "an option to disable Plan Mode" so the model can never switch into plan mode on its own, and {"tools": {"disabled": ["enter_plan_mode"]}} does exactly that today. It just was not discoverable.

Reviewer Test Plan

How to verify

Docs-only change. Confirm the two new rows match the source of truth in packages/cli/src/config/settingsSchema.ts (the tools.disabled and tools.visible entries, including MergeStrategy.UNION) and the registration behavior in packages/core/src/tools/tool-registry.ts (isToolDisabled gate). Prettier was run via the repo pre-commit hook.

Evidence (Before & After)

N/A (docs table rows only).

Tested on

OS	Status
🍏 macOS	✅
🪟 Windows	N/A
🐧 Linux	N/A

[qwen-code-ci-bot]

Thanks for the PR!

Template looks good ✓ — all required sections present (What, Why, Reviewer Test Plan).

Problem: Real and observable. tools.disabled and tools.visible are fully implemented (settings schema at line 2269/2281, normalizeDisabledTools.ts, isToolDisabled gate in tool-registry.ts, test coverage) but missing from the settings reference. The deprecated siblings (tools.core, tools.exclude, tools.allowed) are all documented, so users discover deprecated options while missing the live ones. The reference to #5970 is a concrete example of a user looking for exactly this.

Direction: Clearly aligned — documenting existing, tested settings is straightforward documentation work. No direction concerns.

Size: Not applicable — docs-only, no core paths touched.

Approach: Minimal and focused — exactly two table rows, placed correctly between the deprecated tool settings. Descriptions verified against settingsSchema.ts: tools.disabled ("never registered, so they do not appear in /tools") and tools.visible ("without requiring tool_search") both match the schema descriptions accurately. MergeStrategy.UNION correctly documented as "Merged as a union across scopes." The enter_plan_mode example in tools.disabled is a helpful practical touch.

Moving on to code review. 🔍

中文说明

感谢贡献！

模板完整 ✓ — 所有必填章节齐全（What、Why、Reviewer Test Plan）。

问题：真实可观测的问题。tools.disabled 和 tools.visible 在代码中已完整实现（settings schema 第 2269/2281 行、normalizeDisabledTools.ts、tool-registry.ts 中的 isToolDisabled 门控、测试覆盖），但在 settings 参考文档中缺失。已废弃的同类项（tools.core、tools.exclude、tools.allowed）反而都有文档，导致用户发现的是已废弃选项而非当前有效选项。引用的 #5970 是用户寻找此功能的具体案例。

方向：明确对齐——为已实现、已测试的 settings 补充文档，是纯文档工作，无方向顾虑。

规模：不适用——仅文档改动，未触及核心路径。

方案：最小且聚焦——恰好两行表格，放在已废弃工具 settings 之间，位置正确。描述已与 settingsSchema.ts 核实：tools.disabled（"never registered, so they do not appear in /tools"）和 tools.visible（"without requiring tool_search"）均与 schema 描述一致。MergeStrategy.UNION 正确标注为"Merged as a union across scopes"。tools.disabled 中附带了 enter_plan_mode 的实用示例。

进入代码审查 🔍

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

Code Review

Independent proposal (before reading diff): I would have read settingsSchema.ts for the exact type/default/description of tools.disabled and tools.visible, confirmed MergeStrategy.UNION, checked tool-registry.ts for the runtime gate behavior, and added two rows to the settings table — positioned among the other tools.* entries.

Comparison: The PR's approach matches exactly. Two rows, correctly positioned between the deprecated tools.exclude and tools.allowed, with descriptions that faithfully reflect the schema source.

Findings: No issues.

• Descriptions verified against settingsSchema.ts lines 2269–2292: types (array of strings), defaults (undefined), and MergeStrategy.UNION all match.
• The distinction between tools.disabled (never registered, invisible to model) vs permissions.deny (blocks at runtime) is accurately captured and useful for users.
• The enter_plan_mode example is a practical addition that helps users understand the use case.
• Table column count (5) is consistent with all surrounding rows.
• Patch applies cleanly on current main.

No critical blockers. No AGENTS.md violations. This is a clean docs addition.

Testing

This is a docs-only change (two markdown table rows) — there is no runtime behavior to test in tmux. Verification was done by:

1. Applying the patch to current main — clean apply, no conflicts.
2. Verifying table structure: all rows in the affected range (lines 318–328) have exactly 5 columns, consistent with the existing table.
3. Cross-referencing descriptions against the source of truth in settingsSchema.ts and tool-registry.ts.

# Patch application
$ gh pr diff 6641 --repo QwenLM/qwen-code | git apply
APPLIED

# Table column count verification (all rows in affected range)
$ awk -F'|' 'NR>=318 && NR<=328 {print NR": cols="NF-2}' docs/users/configuration/settings.md
318: cols=5
319: cols=5
320: cols=5
321: cols=5
322: cols=5
323: cols=5
324: cols=5
325: cols=5
326: cols=5
327: cols=5
328: cols=5

# Source-of-truth verification
$ grep -n 'disabled\|visible' packages/cli/src/config/settingsSchema.ts | head -4
2271:        label: 'Disabled Tools',
2276:          'Tool names hidden from the registry...'
2282:        label: 'Visible Deferred Tools',
2287:          'Deferred tool names made visible at startup...'

$ grep -c 'mergeStrategy: MergeStrategy.UNION' (around lines 2269-2292)
Confirmed: both entries have MergeStrategy.UNION ✓

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

This is a clean, minimal docs PR that does exactly one thing and does it well.

The gap is real: tools.disabled and tools.visible have been implemented and tested but were invisible to users in the settings reference, while their deprecated predecessors (tools.core, tools.exclude, tools.allowed) were all documented. Issue #5970 is proof that users are looking for exactly these settings.

The two rows are accurate — I verified descriptions against settingsSchema.ts line by line, and the MergeStrategy.UNION documentation is correct. The placement between the deprecated tool settings makes sense contextually. The enter_plan_mode example is a practical touch that helps users immediately understand the use case.

Nothing extraneous. No scope creep. The kind of PR that's a pleasure to review.

Approving. ✅

中文说明

这是一个干净、最小化的文档 PR，只做了一件事且做得很好。

缺失是真实的：tools.disabled 和 tools.visible 早已实现并有测试覆盖，但在 settings 参考文档中对用户不可见，而它们已废弃的前身（tools.core、tools.exclude、tools.allowed）反而都有文档。Issue #5970 证明用户正在寻找这些设置。

两行描述准确——已逐行对照 settingsSchema.ts 核实，MergeStrategy.UNION 的文档也正确。放在已废弃工具 settings 之间的位置在上下文中有意义。enter_plan_mode 示例帮助用户立即理解使用场景。

没有多余内容，没有范围蔓延。

批准 ✅

— Qwen Code · qwen3.7-max

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-ci-bot]

No review findings. Downgraded from Approve to Comment: CI still running.

— qwen3.7-max via Qwen Code /review

[wenshao]

No issues found. LGTM! ✅

— qwen3.7-max via Qwen Code /review