feat(tool-search): defer optional core toolsets safely

[richardclawbot]

Why

Hermes currently ships every built-in tool schema eagerly even when large optional surfaces are not needed. On the RTrade profile, tool schemas account for roughly 62 KB of fixed prompt payload. This adds bounded progressive disclosure for reviewed optional core toolsets without changing default behavior or weakening the recovery/discovery kernel.

Design

• Add opt-in tools.tool_search.defer_core_toolsets for browser, cronjob, image_gen, tts, and vision.
• Keep terminal/process, file operations, web search/extract, skill discovery/loading, and clarification permanently eager.
• Freeze Tool Search policy per agent session and reuse it across initial assembly, MCP refresh, search, describe, and call.
• Unwrap deferred tool_call before checkpoints, middleware hooks, plugin policy, and loop guardrails so each observes the underlying tool.
• Fail closed on malformed, unresolved, out-of-scope, missing-module, or uncertain-core-provenance paths.
• Preserve upstream describe-first validation for missing deferred arguments in sequential and concurrent execution.
• Extend hermes prompt-size with raw/visible/deferred counts and bytes while retaining current skill and toolset attribution.
• Keep blocked repository-context precedence fail closed.

Default defer_core_toolsets: [] is backward compatible.

Verification

• CI-equivalent scripts/run_tests.sh on the repaired candidate.
• Affected Tool Search, executor, MCP-refresh, prompt-builder, prompt-size, and model-tools suites pass.
• Ruff and git diff --check pass.
• Independent adversarial review reproduced and closed a session-policy drift where search/describe consulted changed live config while execution remained pinned.
• Regression coverage includes both live-policy mutation directions, sequential/concurrent propagation, MCP refresh, malformed bridge arguments, scope rejection, underlying-hook identity, and failed core-provenance discovery.
• Current-main prompt-size default: 34 visible, 0 newly deferred.
• Isolated configured profile: 31 raw, 20 visible, 14 deferred, 15,801 schema bytes saved, tier 1/full listing.

Risk / rollout

Opt-in only. Main risk is a deferred catalog becoming inconsistent with session policy; policy pinning and fail-closed regressions cover that boundary. Roll out first on an isolated profile, verify a fresh session can search/describe/call a deferred browser tool, then restart the gateway only after active workers drain. Revert the single commit and remove defer_core_toolsets to restore fully eager schemas.

[alt-glitch]

This was generated by AI during triage.

Related: open #58838, #60182, and #53193 all defer built-in tools through Tool Search but expose different configuration and safety-policy contracts. This PR's explicit reviewed toolset set and session pinning make it a competing design, not a duplicate.

[teknium1]

Thanks for the careful opt-in design and session-policy pinning work.

Problems

• Current main intentionally defines built-in core tools as permanently eager: tools/tool_search.py:5,10-11, the user docs at website/docs/user-guide/features/tool-search.md:18-24, and the hard-invariant tests at tests/tools/test_tool_search.py:66-80 all state that contract. This is therefore a competing product design, not a stale implementation gap.
• Salvage is not mechanical: since this PR's base, agent/tool_executor.py has changed by 945 lines and the default-config payload moved from hermes_cli/config.py to hermes_cli/config_defaults.py (config_defaults.py:2231-2265).

Suggested changes

• Maintainership should select one shared built-in deferral policy among the related proposals noted in the PR discussion (fix(agent): defer verbose core tool schemas #58838, feat(tool_search): defer_toolsets — opt built-in toolsets into deferral #60182, feat(tool-search): lazy-load core tools via defer_core/defer_always_core #53193) before porting an implementation to current main.

Automated hermes-sweeper review.