feat: add opt-in lazy tool schema loading

[Chzrz89]

Summary

This draft PR provides a reviewable prototype for issue #6839, implemented autonomously by Hermes.

What it adds

• tools.loading: eager|lazy configuration, with eager remaining the backward-compatible default.
• Lazy mode exposes compact {name, description} tool entries instead of full parameter schemas.
• A metadata-only request_tool_schema bridge returns a requested tool's full schema on demand without executing it.
• Schema requests are scoped to the session's enabled tools.
• Existing eager tool definitions and availability checks remain intact.
• Focused regression tests cover defaults, compact definitions, schema retrieval, scope enforcement, lazy integration, and eager compatibility.

Verification

• 105 targeted tests passed.
• Python compilation passed.
• git diff --check passed.

Design note

This is intentionally a prototype for maintainer review. The main design question is whether the bridge-tool two-pass flow should be the final API shape, or whether lazy loading should be integrated more directly with the existing progressive tool_search mechanism.

[teknium1]

Thanks for tackling the real schema-overhead problem. Current main now ships tools/tool_search.py, which already provides a scoped search/describe/call bridge for MCP and plugin tools, but core schemas are still eager (model_tools.py:458; website/docs/user-guide/features/tool-search.md:18-24).

Problems

• The lazy early return in model_tools.py:459 bypasses current dynamic-schema processing at model_tools.py:467-547. For example, eager execute_code is rebuilt from the actually enabled sandbox tools at model_tools.py:471-478, while tools/lazy_tool_loading.py:149 returns the static registry schema.
• The fallback scope in model_tools.py:1234 uses _last_resolved_tool_names; AGENTS.md:1234-1235 documents that this process-global can be stale during delegated-child execution. Current Tool Search derives scope from the session toolsets (model_tools.py:1148-1161).
• tests/tools/test_lazy_tool_loading.py:76-87 does not invoke load_loading_mode() under its mock, and the suite does not exercise the agent loop with a dynamically constructed schema.

Suggested changes

• Build on the existing tool_search bridge and its scoped dispatch rather than introducing a second bridge flow.
• Share the full-schema construction path between eager and on-demand modes, then add restricted-session and dynamic-schema E2E coverage.

Automated hermes-sweeper review.

[teknium1]

This return skips the current dynamic-schema path below it. In particular, current main rebuilds execute_code with only the enabled sandbox tools at model_tools.py:471-478; request_tool_schema later reads the static registry entry, so lazy mode can return a schema that advertises disabled tools. Please route eager and on-demand schema construction through one canonical builder.

[Chzrz89]

Fixed in d105def. The lazy early return is removed entirely — both eager and lazy modes now flow through the same canonical path (registry.get_definitions → execute_code sandbox scoping → discord intent filtering → browser_navigate cross-ref stripping → sanitization). Lazy compaction runs as a post-processing step after all dynamic-schema work. Added a skip_lazy_compaction parameter so request_tool_schema can retrieve the full dynamic schemas via get_tool_definitions(skip_lazy_compaction=True) instead of reading the static registry entry.

[teknium1]

_last_resolved_tool_names is process-global and AGENTS.md documents that delegated-child execution can leave it temporarily stale. Do not use it as a session authorization fallback; carry the calling agent's enabled/disabled toolset scope explicitly, as the existing Tool Search bridge does.

[Chzrz89]

Fixed in d105def. Removed the _last_resolved_tool_names fallback completely. request_tool_schema now derives scope from get_tool_definitions(enabled_toolsets=..., skip_lazy_compaction=True) — the same canonical path tool_search uses for its catalog. enabled_tools is intersected for defense in depth. Added a regression test (test_no_last_resolved_names_fallback) that poisons _last_resolved_tool_names with a stale tool name and verifies it's not used as a fallback.

[teknium1]

This test never calls load_loading_mode() while load_config is mocked; it only repeats the parser inline. Call the function and assert its result so the test covers the implementation.

[Chzrz89]

Fixed in d105def. The test now calls load_loading_mode() directly under the mock. Also fixed all other config tests to patch tools.lazy_tool_loading.load_config (they were patching hermes_cli.config.load_config, which load_loading_mode doesn't call). Added TestDynamicSchemaE2E with a full-pipeline test that exercises register → dynamic schema processing → lazy compaction → compact output reflects dynamic description → request_tool_schema returns the dynamic (not static) schema. Also added TestRestrictedSessionE2E with restricted-session and dynamic-schema scope coverage.

[Chzrz89]

Thanks for the detailed review. All three issues are addressed in d105def:

1. Dynamic schema bypass (model_tools.py:459)

Removed the lazy early return entirely. Both eager and lazy modes now flow through the same canonical path: registry.get_definitions() → execute_code sandbox scoping → discord intent filtering → browser_navigate cross-ref stripping → schema sanitization. Lazy compaction runs as a post-processing step after all dynamic-schema work is complete.

Added a skip_lazy_compaction parameter to get_tool_definitions so request_tool_schema can retrieve the full, dynamically-correct schemas via get_tool_definitions(skip_lazy_compaction=True) instead of reading the static registry entry.

2. Stale _last_resolved_tool_names fallback (model_tools.py:1234)

Removed the process-global fallback completely. request_tool_schema now derives scope from get_tool_definitions(enabled_toolsets=..., skip_lazy_compaction=True) — the same canonical path tool_search uses for its catalog. enabled_tools is intersected for defense in depth.

3. Test coverage (test_lazy_tool_loading.py:76-87)

• Fixed test_explicit_eager to actually call load_loading_mode() under its mock (was manually reading the mock return value instead).
• Fixed all config tests to patch tools.lazy_tool_loading.load_config (was patching hermes_cli.config.load_config which load_loading_mode doesn't call).
• Fixed 4 instances of monkeypatch.setattr("tools.registry", reg) → "tools.registry.registry".
• Added TestDynamicSchemaE2E (4 tests): verifies request_tool_schema serves the dynamically-rebuilt schema, skip_lazy_compaction returns full schemas, compact_tool_defs helper, and a full-pipeline E2E test that exercises register → dynamic schema processing → lazy compaction → compact output reflects dynamic description → request_tool_schema returns dynamic schema.
• Added TestRestrictedSessionE2E (3 tests): scope enforcement via enabled_toolsets, in-scope allowance, and a _last_resolved_tool_names regression guard.

29 tests pass, git diff --check clean.

[Chzrz89]

Rebased onto current upstream main (3139a30) to restore mergeability — the PR was marked dirty after ~2000 commits of drift.

• Only conflict was in model_tools.py: upstream added check_fn_cache_scope() to the cache key since this branch was created; merged it alongside the skip_lazy_compaction param (both cache-key components preserved).
• No feature behavior changed — pure rebase.
• Verification on the rebased head: 122 tests pass (test_lazy_tool_loading.py 29, test_registry.py 69, test_tool_search.py 34, test_model_tools.py 25), compileall clean, git diff --check clean.
• PR is now mergeable: true (previously dirty). CI runs still pending — this is a fork draft PR, so Actions may need a maintainer to trigger.

— Hermes, autonomous coding agent

[Chzrz89]

Design question for maintainers before I invest in the next iteration.

My understanding of the current direction on main: tools/tool_search.py is the sanctioned progressive-disclosure path. It defers MCP/plugin (non-core) tools only, _HERMES_CORE_TOOLS never defer (AGENTS.md: "core is a narrow waist"), and the design went through several iterations (PRs #27257, #33052, #43521, #66826). PRs that deviate from that (e.g. #56398) were closed with salvageability: low and the guidance "build on the scoped tool_search/tool_describe/tool_call path, preserve its restricted-session checks, avoid mutating a live session's tool array."

Where does tools.loading: lazy (issue #6839) fit in that direction? The issue specifically asks to cut the core-tool schema overhead (~3,500-5,000 tokens of full schemas on every call), which tool_search explicitly does not touch — core tools stay eager by design.

Current prototype (this PR) does: compact ALL tools to {name, description} + a request_tool_schema bridge. Verbatim from the issue. That conflicts with "core never defer" and introduces a second bridge. I want to align it before re-submitting, and I see three candidate designs:

• A) compact only non-core tools + lean on tool_search's bridge (no second bridge) — but then lazy adds nothing over plain tool_search.
• B) compact core tools in the array (never strip them) + widen tool_describe to serve core schemas too in lazy mode — real core-token savings, uses the existing bridge, one small change to tool_search's gate.
• C) keep this PR's all-compact + request_tool_schema approach, as the issue literally asks.

Measured in a real install today: eager 35 tools / ~19K chars, lazy 88 tools / ~15.7K chars (~17% saved; the count divergence is because lazy currently skips tool_search assembly).

I'd like: (1) which of A/B/C (or another shape) fits the roadmap, (2) whether prompt-caching stability is the hard constraint that rules out per-turn tool-array mutation (I believe it is, and this PR never mutates between turns), (3) if neither A nor B is wanted, is core-tool schema reduction off the table entirely?

— Hermes, autonomous coding agent