工具注册与延迟发现

工具是否注册、是否出现在初始模型请求和调用是否自动批准，是不同控制层。缩小初始工具描述并不会自动禁止其执行。

主要设置

设置	含义
tools.disabled	完全不注册；不出现在 /tools，也不能发现或调用；跨范围取并集
tools.visible	将指定延迟工具提前声明；跨范围取并集
tools.eager	仅列出的默认 eager 工具可保留初始声明，其余延迟；后层替换前层列表
permissions.allow	只自动批准，不隐藏、移除或延迟工具
permissions.deny	阻止调用；整工具规则还移除多数内置工具，MCP 有例外

显式 eager=[] 会延迟全部非豁免的默认 eager 工具，省略则不限制。原本默认延迟的工具即使写入 eager 也不会提前，需使用 visible。

tool_search、tool_call、structured_output、Plan 生命周期工具、task_stop、MCP、computer_use__* 不受该 eager 列表限制。

ToolSearch 与 ToolCall

tools.toolSearch.enabled 默认 true，使用稳定的 tool_search 发现描述和 tool_call 调用。桥接本身不重新声明工具，有助于保持请求缓存前缀。

tools.toolSearch.threshold 默认 0，即不按阈值预加载。设为 N 后，只有所有符合条件的延迟 schema 总体能放入上下文窗口 N% 时才全部提前声明，否则保持延迟；被 eager 降级的工具不参加此预加载。

visible、会话历史兼容扫描、部分桥接缺失的回退、daemon 的晚注册等仍可提前声明工具，不能把 threshold=0 理解为任何情况都不声明。

桥接任一半被禁用或 deny 时，eager 仍隐藏 schema，但这些工具不能经桥接加载，系统警告；它们仍可能注册、显示于 /tools，直接按名称调用仍经过正常审批。visible 或包含直接调用的实时历史，在后续工具集合刷新时可使其重新声明。若目的是禁止执行，使用 deny/disabled。

Code Mode

tools.codeModeOnly 默认 false，启用后 top-level tool_search 发现 schema，通过 exec 调用；不使用普通延迟预加载和初始目录。当前范围无法搜索时，exec 描述会包含全部允许的工具签名。

tools.freeform 默认 false，只有 codeModeOnly=true 且选中 Responses wireApi 时有效，将 exec 输入改为原始文本；端点必须支持 Responses Custom Tools。两者修改需重启，freeform 不在 Settings 对话框显示。

旧配置迁移

tools.allowed、exclude 分别手工迁移到 permissions.allow、deny；启动仍识别旧设置，但不自动改写。

非空 tools.core 对核心工具形成缺省拒绝的白名单，动态 MCP/Skill 和若干系统工具不在其范围；空数组视为未设置。eager 只延迟、deny 逐项排除，都不能完整复制该白名单对未来新增核心工具的限制。迁移后应按新版本重新核对工具集合。

执行与输出

• tools.shell.defaultTimeoutMs 未设时前台 shell 为 120000ms，单次调用可覆盖，0 禁用超时。
• tools.shell.heartbeatIntervalMs 未设时为 10000ms，无输出时向 ACP/stream-json 发心跳，0 禁用。
• enableInteractiveShell 未设时，显式单次 prompt 用 child_process；交互 TUI、ACP、stream-json 输入、仅 stdin 和文件输入倾向 PTY，平台可回退。
• tools.truncateToolOutputThreshold 默认 25000 字符，truncateToolOutputLines 默认 1000；适用于官方列出的 shell、搜索和文件工具，修改需重启。
• tools.useRipgrep 与 useBuiltinRipgrep 默认 true；后者 false 时改用系统 rg，前者 false 时使用回退实现。
• tools.listDirectory.enabled 与 todoWrite.enabled 默认 false；显式 core 白名单包含 list_directory 时可重新启用目录工具。

自定义 discoveryCommand 返回的工具也受 eager 影响。callCommand 的约定为首参数函数名、stdin JSON 参数、stdout JSON 结果；不能把普通任意输出脚本直接当作该接口。