Skip to content

fix: align subagent tool descriptions with availability - #4066

Draft
7Sageer wants to merge 4 commits into
mainfrom
fix/subagent-tool-availability
Draft

7Sageer wants to merge 4 commits into
mainfrom
fix/subagent-tool-availability

Conversation

@7Sageer

@7Sageer 7Sageer commented Sep 28, 2026 •

Copy link
Copy Markdown
Collaborator

Requirement or Bug

子 agent 的工具描述可能列出实际无法启用的工具,例如未配置搜索服务时仍宣称可以使用 WebSearch。

Bug Reproduction Steps

  1. 在没有配置 WebSearch provider 或托管搜索凭据的环境中启动会话。
  2. 查看 Agent 工具描述中的子 agent 工具名单,其中仍包含 WebSearch。
  3. 创建 explore 子 agent,其实际工具列表没有 WebSearch。

关闭 WaitFor 或缺少工具所需的运行环境能力时,也会出现相同问题。

Root Cause

工具激活会检查贡献的 when 条件和运行环境能力,但描述生成只枚举静态贡献。描述与激活现在复用同一套可用性判断,并继续按目标 profile 应用工具策略。

媒体工具单独按可选或强制子模型的能力生成候选项,显式工具名单和未声明 tools 的自定义 profile 共用此结果。这样父模型支持图片、强制子模型为纯文本时,不会从父工具注册表误带入 ReadMediaFile;父模型为纯文本而子模型支持媒体时,也能正确列出它。用户提供的同名媒体工具优先保留。select_tools 还检查动态工具 flag 和可选或强制子模型的能力,避免未声明 tools 的自定义 profile 列出实际不可用的工具。

Code Changes

 tool contribution
+ 共用运行环境能力与 when 条件检查

 Agent description
- 静态贡献名单及独立 NotifyUser 检查
+ 可用贡献与动态工具,保留用户同名覆盖
+ 在候选工具列表统一处理子模型媒体能力与动态工具能力,再应用目标 profile 策略

 agent loop
+ step hooks 完成后、构建模型工具 schema 前刷新激活状态

子 agent 继续继承调用方的运行环境;模型选择策略和 MCP 通配符匹配规则不变。

Behavior Changes and Affected Users

行为 变化前 变化后 受影响人群 退路
条件工具描述 可能宣称存在不可用的 WebSearch、WaitFor 或依赖运行环境的工具 与激活使用相同的运行条件 缺少搜索配置、关闭 WaitFor 或使用受限运行环境的会话 配置搜索服务、开启对应 flag 或恢复环境能力
模型步骤之间的可用性变化 已注册条件工具可能保持过期状态 下次模型请求前移除或恢复条件工具 运行条件在会话内变化的用户 恢复相关条件
未声明工具名单的自定义 profile 显示 Tools: all 或 all except ... 列出当前可用且策略允许的具体工具 未声明 tools 的自定义 agent 用户 工具权限不变;描述统一显示具体名单
媒体工具描述 显式名单才应用子模型媒体判断;其他枚举路径可能依赖父模型注册表 所有 profile 共用子模型媒体候选项 父子模型媒体能力不同的用户,含强制子模型配置 调整子模型配置;实际模型能力和工具权限不变
动态工具描述 具体工具枚举可能列出不可用的 select_tools 仅在动态工具 flag 开启且可选或强制子模型具备所需能力时列出 未声明 tools 的自定义 agent 用户,含父子模型能力不同的配置 开启 flag 并选择支持动态工具的子模型;实际工具权限不变
用户同名工具覆盖 描述可能优先采用内置贡献的可用条件 保留实际注册的用户工具,包括同名 WebSearch 和 ReadMediaFile 注册同名工具的 SDK 调用方 删除用户覆盖即可使用内置工具
explore 联网指引 无条件建议 WebSearch 或 FetchURL 在工具可用时建议使用 新创建的 explore agent 工具可用时仍提供相同指引
plan 联网指引 无条件宣称可以联网 以联网工具可用为前提 新创建的 plan agent 工具可用时仍可联网

现有工具描述测试覆盖 provider 缺失与恢复、WaitFor、NotifyUser、运行环境能力、用户覆盖、profile 权限差异、媒体模型配置及 step hooks 后的刷新;相关 loop 快照和 compaction token 断言同步更新。新增 6 组 select_tools 描述测试,覆盖关闭 flag、缺少能力、父子能力不同和强制子模型;其中 3 组在修复前失败、修复后通过。

验证:

  • 工具描述、激活与动态工具服务定向测试:115 项通过(按测试名称筛选,其他 108 项未运行)。
  • 引擎 TypeScript 类型检查通过。
  • 修改文件的 type-aware lint 无 error;测试文件未修改区域有 15 条既有 warning,无注释检查通过。
  • 直接执行当前候选工具方法,验证父视觉/子纯文本、父纯文本/子视觉、用户同名媒体工具覆盖;此项为函数级定向验证,未新增跨模型 spawn 集成测试。

Checklist

  • I have read the CONTRIBUTING document.
  • I have linked a related issue(直接报告,未提供 issue)。
  • I have added tests that prove my feature works(保留已有测试并新增 6 组动态工具描述测试;媒体补充修复未新增跨模型 spawn 测试)。
  • The behavior-change table above is complete, and every removed behavior or flipped default is named in the changeset and either has an escape hatch or was explicitly approved by a maintainer in this PR.
  • Ran gen-changesets skill;沿用已有 CLI patch changeset,同一项工具描述修复无需重复条目。
  • Ran gen-docs skill;配置语义和使用方式不变,无需额外文档更新,受影响的内置指引已在此 PR 修改。

@changeset-bot

changeset-bot Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: d553c86

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@moonshot-ai/kimi-code Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@7Hanrui

7Hanrui commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c305d4436b

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +264 to +267
const target: ToolAvailabilityTarget = {
isSubagentPreview: true,
environment: this.environment,
};

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Avoid filtering subagent tools by the caller environment

When the experimental environment argument sends a subagent to a different environment, this preview evaluates capability-gated tools against the caller's binding instead. SessionSubagentService.spawn resolves that argument into a separate child binding before activation, so a caller in a process-only environment will have Read/Edit omitted from the Agent description even when the selected target has fs (and a filesystem-capable caller can advertise them for a process-only target). Do not use the caller environment to prune descriptions when the eventual subagent environment is selectable.

Useful? React with 👍 / 👎.

Comment on lines +277 to +279
return this.knownToolReferences().filter(
(ref) => !contributionNames.has(ref.name) || available.has(ref.name),
);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve user-tool overrides in subagent descriptions

When a user registers a tool named WebSearch while no web-search provider is configured, the registry keeps that user tool and SessionSubagentService inherits it into the child. This filter nevertheless sees the built-in WebSearch contribution, marks it unavailable, and removes the name even though the live registry entry is the user tool. Consequently profiles that allow WebSearch are described as lacking a tool the subagent will actually receive. Base the availability filter on the live entry/source, not merely on a same-named contribution.

Useful? React with 👍 / 👎.

@7Sageer
7Sageer force-pushed the fix/subagent-tool-availability branch from c305d44 to fca3586 Compare September 28, 2026 11:36
@7Sageer
7Sageer changed the base branch from feat/remote-runtime to main September 28, 2026 11:37
@7Hanrui

7Hanrui commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: fca3586755

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Copilot AI balanced review requested due to automatic review settings September 29, 2026 04:06

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@7Hanrui

7Hanrui commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. More of your lovely PRs please.

Reviewed commit: 719a615393

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

@7Hanrui

7Hanrui commented Sep 29, 2026

Copy link
Copy Markdown
Contributor

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: d553c86fc7

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants