feat(tool_search): defer_toolsets — opt built-in toolsets into deferral

[lEWFkRAD]

What does this PR do?

Tool search (progressive tool disclosure) currently defers only MCP and plugin tools; built-in ("core") toolsets are always loaded. On installs with few or no MCP servers this makes the feature a near no-op, because there the built-in schemas are the entry tax — 14k+ tokens re-prefixed onto every session's first prefill.

This adds tools.tool_search.defer_toolsets: an explicit, default-empty list of built-in toolset names whose tools ride the existing tool_search / tool_describe / tool_call bridge, exactly like MCP/plugin tools already do. It's opt-in — nothing changes for existing configs, and core protection stays the default for everything not listed.

The opt-in is honored consistently on both sides of the bridge — assembly (classify/strip) and dispatch (tool_describe, tool_call unwrap, session scoping) resolve the same set — so an opted-in tool stripped from the visible array stays reachable through the bridge with guardrails, approvals, and hooks firing identically.

Related Issue

Fixes #60181

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• tools/tool_search.py — resolve a per-install "deferrable built-in" set from defer_toolsets and apply it symmetrically in assembly and dispatch.
• tests/tools/test_tool_search.py — coverage for the opt-in set: classification/strip, describe/call reachability, session scoping, and the default (empty) no-op.
• cli-config.yaml.example — document the tools.tool_search block (previously unlisted), including defer_toolsets and its round-trip trade-off.

How to Test

1. On an MCP-light install, set tools.tool_search.defer_toolsets: [session_search, delegation, skills, computer_use].
2. Start a session — the deferred toolsets no longer appear in the model-facing tools array (measured ~7.2k-token / ~49% cut to the first-prefill tool-schema tax).
3. Ask for something that needs a deferred tool — the model discovers it via tool_search and invokes it through the bridge; guardrails/approvals/hooks fire as normal.
4. pytest tests/tools/test_tool_search.py -q → 47 passed.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(tool_search):)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature (no unrelated commits)
• I've run pytest tests/ -q and the tool_search tests pass (47 passed)
• I've added tests for my changes
• I've tested on my platform: Windows 11

Documentation & Housekeeping

• I've updated relevant documentation (docstrings) — and cli-config.yaml.example
• I've updated cli-config.yaml.example (added the tools.tool_search block incl. defer_toolsets)
• N/A — no architecture/workflow change to CONTRIBUTING/AGENTS
• I've considered cross-platform impact — pure config/assembly logic, no platform-specific paths
• I've updated tool descriptions/schemas if I changed tool behavior — N/A (bridge behavior unchanged; only which tools ride it)

[teknium1]

Thanks for the focused opt-in design and for threading the configured set through assembly and bridge dispatch.

Problems

• tools/tool_search.py:589 removes opted-in core tools from the assembled array, and agent/agent_init.py:1195-1204 derives agent.valid_tool_names from that array. This drops SESSION_SEARCH_GUIDANCE, SKILLS_GUIDANCE, and computer-use guidance because agent/system_prompt.py:222-252 gates them on valid_tool_names; direct calls to deferred names also fail validation in agent/conversation_loop.py:4567-4575.
• The patch updates only cli-config.yaml.example; website/docs/user-guide/features/tool-search.md:18-25 and hermes_cli/config.py:2824-2846 still state that core tools never defer.

Suggested changes

• Preserve a session-static pre-assembly availability set for guidance and deliberate deferred-tool routing, distinct from the model-visible bridge schema set.
• Add the default-empty key to DEFAULT_CONFIG, update the user guide, and cover an AIAgent-level opted-in core-tool path.

Automated hermes-sweeper review.