feat(mcp): support subagent-only tool scope

[TurgutKural]

Summary

Adds an opt-in MCP tool visibility scope for tools that should be available to delegated subagents but omitted from the main agent's model schema.

• supports server-level scope: subagent_only
• supports tools.scope: subagent_only with existing include/exclude selection semantics
• keeps absent/default scope behavior unchanged
• preserves scope across dynamic tools/list refreshes
• isolates main/child tool-definition caches
• validates scope values and fails open to existing visible behavior with a warning
• documents child toolset inheritance requirements

Clean branch provenance

This PR is based directly on current upstream main:

• upstream base: d9ee342414042bba7bca43438f19d2fba9a54806
• feature commit: b9433337aa722b03afdb84de2a4b7827e45594dc
• commit count over upstream: 1
• changed files: 8

Motivation

Some MCP servers expose powerful or very large tool surfaces that are better used by focused delegated agents. Previously, Hermes had no way to keep those tools out of the main agent schema while retaining them for delegate_task children.

Configuration

mcp_servers:
  analysis-server:
    command: ...
    scope: subagent_only

Per-selected-tool scope is also supported under tools.scope.

Compatibility

No scope or scope: main preserves existing behavior: tools remain visible to both the main agent and delegated children. Unknown values emit a warning and fall back to main.

Validation

• fresh upstream-base focused/dependent suite: 143 passed
• git diff --check upstream/main..HEAD: clean
• independent adversarial review: APPROVE
• production-config smoke: MAIN had 0 RE-scoped tools; delegated child had 303 RE-scoped tools; cache isolation passed

[teknium1]

Thanks for the scoped-MCP design and focused registry/cache coverage. The feature premise is real on current main, but there are blocking integration gaps.

Problems

• scripts/ci/timings_report.py:939 on PR head has an extra indentation under except TimingsUnavailable as e:, so the changed file is invalid Python.
• agent/agent_init.py:1218 only applies scope during initial construction. With default enabled_toolsets=None, tools/delegate_tool.py:1110-1118 derives a child’s toolsets from the parent’s visible names; hidden scoped MCP tools therefore do not contribute their mcp-<server> toolset to the child.
• Scope is also omitted from the rebuild paths: tools/mcp_tool.py:5626-5630, model_tools.py:1106-1110, and agent/tool_executor.py:252-257. Refreshes and Tool Search will omit a child-scoped MCP tool.
• The mixed-scope documentation at website/docs/reference/mcp-config-reference.md:185-189 conflicts with existing tools.include registration semantics in tools/mcp_tool.py:5048-5058.

Suggested changes

• Propagate child scope through child inheritance, MCP refresh, and both Tool Search catalog/unwrap paths; add end-to-end coverage for all three.
• Correct the CI indentation and align the mixed-scope documentation with the implemented registration model.

Automated hermes-sweeper review.

[TurgutKural]

Addressing the hermes-sweeper review

Thanks for the detailed sweep. Summary of what I've done in the latest push (now rebased clean on current main, force-pushed to the fork):

Point 1 — scripts/ci/timings_report.py indentation (REJECTED as false positive).
The PR's actual diff touches only 8 files (agent_init, mcp_config, mcp_security, model_tools, registry, mcp_tool, the test, and the docs). It does not touch scripts/ci/timings_report.py. The reviewer's diff range was computed against the stale upstream base, which surfaced an unrelated CI edit. The current main version of timings_report.py (already fixed by ecd54a001 fix(ci): make timings report fork-safe) parses cleanly — verified with python3 -m py_compile. I rebased on top of that, so the file is correct on this branch. The fork branch also carried a now-redundant copy of that CI fix (4e8ea8549), which is already an ancestor of main; I deliberately dropped it during the rebase so the PR contains only the scope feature.

Point 2 — child toolset inheritance (ADOPTED).
Confirmed real. With the default enabled_toolsets=None, _build_child_agent derives the child's toolset set from the parent's main-visible valid_tool_names, which excludes subagent_only-scoped tools — so the mcp-<server> toolset would never reach the child, defeating the feature. Fixed: added _registered_mcp_toolsets() and fold the registered mcp-* toolsets back into the derived set (gated on inherit_mcp_toolsets default True). MAIN still never sees scoped tools; the child receives the toolset and exposes them via include_subagent_only=True.

Point 3 — refresh + Tool Search paths (ADOPTED).
Threaded include_subagent_only through refresh_agent_mcp_tools (all four production callers key off agent.platform == 'subagent') and through handle_function_call's Tool Search bridge catalog (the two tool_executor paths + agent_runtime_helpers). So MCP refresh and tool_search unwrap now expose scoped tools to children.

Point 4 — mixed-scope docs (ADOPTED).
Corrected the tools.include description: include is a whitelist, so the non-included tools are not registered at all — there is no main-visible remainder. The scoped tools are simply hidden from MAIN and exposed to children.

Added two end-to-end tests (child toolset derivation + Tool Search catalog scope). The feature does not exist on upstream/main (verified by grep), so this PR is the delivery path, not a duplicate of main.

Re-requesting review.

[TurgutKural]

Deep upstream-already-fixed analysis — verdict: STILL_OPEN

I read the current upstream/main (HEAD c0c76a471; 94f8166dc is an ancestor of main) to check whether the subagent-only tool-scope effect is already achievable via a different mechanism. It is not. Summary of the investigation:

What the problem actually requires

A way to register an MCP tool that is hidden from the MAIN agent but visible to delegate_task children — i.e. a tool in a child's toolset that is NOT in the parent's toolset.

Why upstream cannot do this today

1. Children can only ever be a SUBSET of the parent's toolsets — never a superset.

• tools/delegate_tool.py:1066 _build_child_agent(...) — the only caller passes toolsets=None (delegate_tool.py:2580), so the child inherits the parent's toolsets.
• Even if a toolsets arg is supplied, it is intersected with the parent (delegate_tool.py:1143-1148): child_toolsets = [t for t in toolsets if t in expanded_parent]. A child cannot gain a toolset the parent lacks.
• _preserve_parent_mcp_toolsets (delegate_tool.py:576-584) only appends parent MCP toolsets back to a narrowed child; it never introduces tools the parent doesn't have.

2. The model cannot even request a custom child toolset.

• DELEGATE_TASK_SCHEMA (delegate_tool.py:3450-3527) exposes only goal, context, tasks, role, background. There is no tools/toolsets parameter. Per the module docstring (delegate_tool.py:115-117): "Subagents inherit the parent's toolsets; the model cannot choose or narrow them (no model-facing toolsets arg)."

3. MCP tools have no scope/visibility/role field.

• Every MCP tool registers under a single mcp-{server} toolset (mcp_tool.py:5036,5078). The only config-driven selectors are tools.include / tools.exclude (mcp_tool.py:5044-5053), which filter by tool name globally — they apply equally to the parent and to children, so they cannot hide a tool from the parent while showing it to a child.
• The one role-like lever, allowed_models (mcp_tool.py:58,1178,1421), filters by model, not by agent role. Not equivalent.

4. No per-agent tool filter / plugin hook.

• tool_executor.py:219 _tool_search_scoped_names enforces session enabled_toolsets/disabled_toolsets scope only — no role-based visibility.
• agent/agent_runtime_helpers.py has no per-agent tool filter.
• No plugin hook exposes per-agent MCP-tool visibility (plugin hooks are platform/transport/anomaly-oriented).

5. No config schema field.

• hermes_cli/mcp_config.py and hermes_cli/mcp_security.py on upstream contain no scope/only_for/subagent/include_subagent field (I grepped both). The PR's mcp_security.py additions (+42) and mcp_config.py additions (+8) are net-new.

6. Recent history shows no prior solution.

• git log --since=2026-06-01 -- tools/delegate_tool.py tools/mcp_tool.py is all fix(mcp) / fix(delegation) / refactor / docs. None adds scoped tool visibility.

Conclusion

The PR's scope: subagent_only mechanism is the only path to this capability — there is no existing upstream equivalent. The closest upstream behaviors (narrowing a child to a subset of the parent, or tools.include/tools.exclude by name) all operate within the parent's toolset and cannot express "tool visible to children, hidden from main." Leaving open; the feature gap is real and this implementation appears to be the right fix.

[GottZ]

This was generated by AI during triage.

Thanks for the thorough iteration — routing all scope decisions through the single get_definitions choke point is the right call, and the cache-key isolation plus dynamic-refresh coverage are solid. Two things I'd like to see addressed before merge, plus two doc nits:

1. tools.scope is silently ignored without include/exclude. In _register_server_tools._tool_scope (tools/mcp_tool.py:5090-5097), tools_scope is only applied when (include_set or exclude_set) is truthy. A config like tools: { scope: subagent_only } with no include/exclude and no server-level scope leaves every tool at "main" — i.e. it silently exposes tools the user intended to hide, which is the same failure class (inverted) that the _normalize_mcp_scope warning guards against. Could you either apply tools.scope to the full selected set when no filter is present, or reject/warn on that combination? A test for this path would be good too.

2. Enforcement is schema-visibility, not dispatch-level. registry.dispatch doesn't consult scope; containment relies on the valid_tool_names guard in the conversation loop (agent/conversation_loop.py:4712). That's effective for the standard loop, but the reference doc's phrasing "MAIN can no longer reach the tool / adds a containment surface" reads as a hard boundary. Suggest aligning it with the (accurate) PR summary wording: the tool is omitted from MAIN's model schema. Worth noting the interaction with fix(agent): avoid fuzzy repair for MCP tool names #62701 (MCP-name fuzzy repair), since that's the path the guard leans on.

3. Doc says the per-tool scope means "narrower scope wins," but _tool_scope always lets tools.scope override for selected tools even when it's wider than the server scope (e.g. server subagent_only + tools.scope: main → MAIN-visible). Please reword to "tools.scope overrides for the include/exclude-selected tools."

4. test_child_inherits_registered_mcp_toolset re-implements the fold-in inline rather than exercising _build_child_agent (tools/delegate_tool.py:1168) directly — a test that drives the real builder would pin the integration, not just the _registered_mcp_toolsets() helper.

Also: the PR description's "Clean branch provenance / Validation" section still reflects the original 8-file, 1-commit state — the branch is now 15 files / 3 commits after the review fixes. Worth refreshing so reviewers aren't checking against stale numbers. CI is fully green and the change is cleanly additive, so once the tools.scope gap and the doc wording are sorted this looks good to land.

[TurgutKural]

@teknium1 Thanks for the review — this concern has been addressed in the current head (rebased onto upstream/main).

The fix is in tools/delegate_tool.py:

1. _registered_mcp_toolsets() (new helper) — queries the tool registry for all registered MCP toolset names (mcp-<server> pattern).
2. _build_child_agent() — after deriving parent_toolsets from valid_tool_names (the main-visible schema), the code now folds registered MCP toolsets back in:

if _get_inherit_mcp_toolsets():
    parent_toolsets.update(_registered_mcp_toolsets())

This ensures that even when enabled_toolsets=None (all tools), scoped MCP tools with scope=subagent_only are still available to delegated children — they pass include_subagent_only=True to the schema builder, so the child receives the scoped tools that main intentionally hides.

The docstring in _registered_mcp_toolsets() explicitly documents this design: "Subagent-only-scoped MCP tools are deliberately withheld from valid_tool_names (see ToolEntry.scope), so a naive derivation would drop their mcp-<server> toolset."

Please verify the current head addresses your concern. Happy to iterate further if there's a gap I missed.

[TurgutKural]

All four items addressed:

1. tools.scope without include/exclude — _tool_scope now applies tools.scope to ALL tools of the server when no include/exclude filter is present. Previously tools: { scope: subagent_only } with no filter was silently a no-op. Added test_register_server_tools_scope_without_filter_applies_to_all covering this path.

2. Doc wording — "containment surface (MAIN can no longer reach the tool)" → "omitted from MAIN's model schema (the standard containment mechanism)". Accurate: enforcement is schema-visibility via valid_tool_names, not dispatch-level.

3. "narrower scope wins" rewording — now reads "tools.scope overrides for the include/exclude-selected tools; when no filter is set, tools.scope applies to ALL tools of the server."

4. test_child_inherits_registered_mcp_toolset inline fold-in — noted; the test re-implements the derivation inline because it needs to assert on the intermediate toolset set before the child is constructed. Extracting a helper would obscure what's being tested. Happy to refactor if maintainers prefer.

[TurgutKural]

Closing as superseded by upstream's MCP tool progressive disclosure (deferred tool surfaces + tool_search catalog listing, landed in main via the 2026-07-26 batch). The subagent_only scope mechanism this PR introduced is no longer needed: large MCP tool surfaces are now held out of the main agent schema and discoverable through tool_search, which covers the original use case (keep heavy MCP tools off the parent schema while keeping them callable). Thanks for the review.