Skip to content

feat(runtime): bucket ungrouped native tools by categoryHint in tool search - #4376

Open
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:fix/tool-search-category-families
Open

feat(runtime): bucket ungrouped native tools by categoryHint in tool search#4376
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:fix/tool-search-category-families

Conversation

@liugddx

@liugddx liugddx commented Aug 31, 2026

Copy link
Copy Markdown
Member

What

Deferred tool discovery (tool_search) collapsed every ungrouped native tool into a single opaque other group in the searchable inventory. When the model browses the inventory it sees one undifferentiated other bucket with no capability signal to steer by.

This buckets ungrouped native tools by the permission categoryHint (ToolCategory) already present on the bound tool, producing a compact capability-family map instead:

categoryHint family id label
read / file_write / fs_destructive filesystem Filesystem & search
shell_safe / shell_unsafe / privileged / git_destructive shell Shell & processes
web_read / network_send web Web & network
browser browser Browser automation
computer_use computer_use Computer use
client_capability client_capability Client capabilities
subagent agents Agent orchestration

Why it's safe

  • Reads metadata already on the bound tool — no tool schema is loaded, nothing is fetched.
  • Permission classification is untouched: grouping is presentation-only. Every native tool stays gated + deferred exactly as before.
  • A caller-supplied group with a colliding id keeps precedence: family members merge into the explicit group rather than overriding it.
  • Tools with no hint (or custom_tool) still fall back to other — no behavior change for them.

Tests

Two regression tests added to tool-availability.test.ts:

  1. buckets ungrouped native tools into capability families by categoryHint — asserts distinct hints land in distinct families, custom_tool/hint-less fall back to other, family ids surface in the searchable inventory, and every tool stays gated + deferred.
  2. a caller-supplied group keeps precedence over a categoryHint family — an explicit group claims a tool; only the remaining hinted tool is family-bucketed; no other.

Causal proof (fail-without / pass-with): with the production hunk temporarily reverted to the old "all → other" logic, exactly these two new tests fail (bySource.agents/web/computer_use come back undefined); with the fix restored, all 20 tests in the suite pass. So the tests gate on this logic rather than passing vacuously.

Part of #4267. Closes #4353.

…search

Deferred tool discovery collapsed every ungrouped native tool into a
single opaque `other` group in the tool_search inventory, giving the
model no capability signal to browse by. Bucket ungrouped tools by the
permission `categoryHint` (ToolCategory) already present on the bound
tool into compact capability families (filesystem, shell, web, browser,
computer_use, client capabilities, agents). This reads existing metadata
only — no tool schema is loaded and permission classification is
untouched. A caller-supplied group with a colliding id keeps precedence
(family members merge into it); tools with no hint or `custom_tool` still
fall back to `other`.

Adds two regression tests: family bucketing by categoryHint, and
explicit-group precedence over a categoryHint family.

Part of apache#4267. Closes apache#4353.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

harness: wire native tool categoryHint/ToolCategory into deferred tool-search groups (item 9 of #4267)

1 participant