The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(gateway): join delegations in the turn when interim messages are off
Victor Kyriazakosfa2befeed70f
diff --git a/gateway/session_execution.py b/gateway/session_execution.pyindex 3277a93230a..7c550889619 100644--- a/gateway/session_execution.py+++ b/gateway/session_execution.py@@ -221,9 +221,16 @@ class GatewaySessionAgentMixin:if found.evicted is not None:self._release_evicted_agent(found.evicted)if agent is None:- agent = self._build_fresh_agent(- turn_route, platform_key, combined_ephemeral, max_iterations, reasoning_config, pr, skip_context_files,- )+ from tools.delegate_tool_config import gateway_delegation_inline, gateway_delegation_inline_scope+ # delegation.gateway_mode from this turn's own (profile-scoped) config and resolved interim setting;+ # read once, by the agent's first tool build, then carried by its delegate_task schema and pin.+ inline = gateway_delegation_inline(+ ctx.user_config, platform_key, interim_enabled=ctx.interim_assistant_messages_enabled)+ with gateway_delegation_inline_scope(inline):+ agent = self._build_fresh_agent(+ turn_route, platform_key, combined_ephemeral, max_iterations, reasoning_config, pr,+ skip_context_files,+ )if cache_lock and cache is not None:with cache_lock:# Record the snapshot's session_id with message_count so the cross-process guarddiff --git a/hermes_cli/config_defaults.py b/hermes_cli/config_defaults.pyindex d7eb16119fa..14434ff9377 100644--- a/hermes_cli/config_defaults.py+++ b/hermes_cli/config_defaults.py@@ -1355,8 +1355,7 @@ DEFAULT_CONFIG = {# children fail only from real errors (API, tools, iteration budget). A progressing child (including one# waiting on a multi-minute completion) restarts the window; a frozen one is caught."child_timeout_seconds": 0,- # Subagent effort: "ultra" | "max" | "xhigh" | "high" | "medium" | "low" | "minimal" |- # "none" (empty = inherit)+ # Subagent effort: "ultra" | "max" | "xhigh" | "high" | "medium" | "low" | "minimal" | "none" (empty = inherit)"reasoning_effort": "",# Max parallel children per batch AND max concurrent background delegation units; async# dispatches beyond it run synchronously. Floor 1, no ceiling.@@ -1364,6 +1363,7 @@ DEFAULT_CONFIG = {# Background fan-outs return as ONE message when the whole call finishes. true = each task# (or `group`) returns on its own as it finishes — more new turns for the orchestrator."independent_completions": False,+ "gateway_mode": "auto", # gateway: inline (join in the turn) | background | auto = inline where interim msgs are off# Orchestrator role controls. Depth floored at 1, no ceiling; each level multiplies cost."max_spawn_depth": 1, # 1 = flat, 2 = orchestrator→leaf, 3+ = deeper"orchestrator_enabled": True, # kill switch for role="orchestrator"diff --git a/run_agent.py b/run_agent.pyindex 021d3db0c0f..51174f3e807 100644--- a/run_agent.py+++ b/run_agent.py@@ -1343,9 +1343,10 @@ class AIAgent(def _dispatch_delegate_task(self, function_args: dict) -> str:"""Single call site for delegate_task dispatch; new DELEGATE_TASK_SCHEMA fields are added only here."""from tools.delegate_tool import _strip_model_hidden_task_fields, delegate_task as _delegate_task- # Top-level MODEL delegations always run in the background (handle returned, results re-enter as- # messages). An ORCHESTRATOR SUBAGENT (depth > 0) stays synchronous — it needs results in-turn and- # owns no gateway session. The schema-level `background` param is intentionally ignored.+ # Top-level MODEL delegations run in the background (handle returned, results re-enter as messages),+ # unless the session's delegate_task is the joined variant (one-shot, delegation.gateway_mode inline).+ # An ORCHESTRATOR SUBAGENT (depth > 0) stays synchronous — it needs results in-turn and owns no gateway+ # session. The schema-level `background` param is intentionally ignored.return _delegate_task(goal=function_args.get("goal"), context=function_args.get("context"),tasks=_strip_model_hidden_task_fields(function_args.get("tasks")),diff --git a/tests/gateway/test_gateway_delegation_mode.py b/tests/gateway/test_gateway_delegation_mode.pynew file mode 100644index 00000000000..633bd9027c9--- /dev/null+++ b/tests/gateway/test_gateway_delegation_mode.py@@ -0,0 +1,318 @@+"""Gateway delegation joins inside the turn when interim assistant messages are off.++Top-level ``delegate_task`` on a messaging gateway runs in the background, and its tool text tells+the model to "give a one-line status and END YOUR TURN". With ``display.interim_assistant_messages``+off that status is the turn's FINAL answer, so the chat still receives a "checks are running, no+findings yet" message and the real answer later, as a second message. ``delegation.gateway_mode``+(default ``auto``) now joins the children inside the turn on such sessions: the model waits for them+in the tool call and the chat gets one completed answer. Related: #95522, #141778.++Real ``GatewayRunner._run_agent`` + real ``AIAgent`` + real child ``AIAgent`` against a loopback+model. The model obeys whatever the ``delegate_task`` tool tells it: given a dispatch handle it ends+its turn with a status, given the child's result it answers. The adapter is a recording transport+driven by the base adapter's own ``_process_message_background`` (typing loop + final send).+"""++from __future__ import annotations++import asyncio+import os+import threading+import time+from pathlib import Path++import pytest++import hermes_yaml as yaml+from gateway.config import Platform, PlatformConfig, StreamingConfig+from gateway.platforms.base import BasePlatformAdapter, SendResult+from gateway.platforms.event import MessageEvent, MessageType+from gateway.session import SessionSource+from tests.e2e.core.history._helpers import NO_BACKGROUND_REVIEW, OFFLINE_CONFIG+from tests.fakes.fake_llm_provider import FakeLLMServer, Hang, Text, ToolCall, write_hermes_home+from tests.gateway.test_run_progress_topics import _make_runner+from tests.waiting import wait_until++GOAL = "Audit the billing module for stale invoices"+FINDING = "BILLING-OK-7731"+PAUSE = "Checks are running in parallel, I don't have the findings yet."+ANSWER = f"Done. The billing audit came back clean: {FINDING}"+END_TURN = "END YOUR TURN"+++class _Chat(BasePlatformAdapter):+ """Recording transport: every outbound message lands in ``sent``."""++ SUPPORTS_MESSAGE_EDITING = True++ def __init__(self, platform: Platform):+ super().__init__(PlatformConfig(enabled=True, token="***"), platform)+ self.sent: list[str] = []+ self.typing = 0++ async def connect(self, *, is_reconnect=False):+ return True++ async def disconnect(self):+ return None++ async def send(self, chat_id, content, reply_to=None, metadata=None):+ self.sent.append(content)+ return SendResult(success=True, message_id=f"m{len(self.sent)}")++ async def edit_message(self, chat_id, message_id, content, **_):+ self.sent.append(content)+ return SendResult(success=True, message_id=message_id)++ async def send_typing(self, chat_id, metadata=None):+ self.typing += 1++ async def get_chat_info(self, chat_id):+ return {"id": chat_id}+++def _first_user_text(record: dict) -> str:+ messages = record["body"].get("messages", [])+ return str(next((m.get("content") for m in messages if m.get("role") == "user"), ""))+++def _model(child_reply):+ """A model that follows the tool contract: a dispatch handle gets a status, a result gets the answer."""++ def respond(request):+ if GOAL in _first_user_text(request): # the child's own conversation+ return child_reply+ last = request["body"]["messages"][-1]+ if last.get("role") == "tool":+ return Text(ANSWER if FINDING in str(last.get("content")) else PAUSE)+ return ToolCall("delegate_task", {"tasks": [{"goal": GOAL, "context": "Repo at /srv/billing."}]})++ def aux(request):+ return child_reply if GOAL in _first_user_text(request) else Text("Fake summary.")++ return respond, aux+++def _delegate_def(request: dict) -> dict:+ return next(t["function"] for t in request["tools"] if t["function"]["name"] == "delegate_task")+++def dispatches(monkeypatch):+ """Every hand-off to the async completion registry (the background path)."""+ from tools import async_delegation++ calls = []+ real = async_delegation.dispatch_async_delegation_batch++ def recording(**kwargs):+ calls.append(kwargs)+ return real(**kwargs)++ monkeypatch.setattr(async_delegation, "dispatch_async_delegation_batch", recording)+ return calls+++async def _turn(monkeypatch, config: dict, *, platform=Platform.WHATSAPP, model=None, during=None):+ """One inbound message through the real gateway turn; returns (chat, the parent's model requests)."""+ import gateway.run as gateway_run+ from tools import async_delegation++ home = Path(os.environ["HERMES_HOME"])+ chat = _Chat(platform)+ source = SessionSource(platform=platform, chat_id="c1", chat_type="dm", user_id="u1")+ event = MessageEvent(text="How is billing doing?", source=source, message_type=MessageType.TEXT)+ session_key = f"agent:main:{platform.value}:dm:c1"+ respond, aux = model or _model(Text(f"Audit finished: {FINDING}"))+ base = {+ "tools": {"tool_search": {"enabled": "off"}},+ "platform_toolsets": {platform.value: ["delegation", "todo"]},+ }+ # Tool progress lines are their own operator knob (display.tool_progress); a quiet chat turns them off.+ merged = {**base, **config, "display": {"tool_progress": "off", **config.get("display", {})}}+ with FakeLLMServer(respond, aux=aux) as srv:+ write_hermes_home(home, srv.base_url, extra_config=OFFLINE_CONFIG + NO_BACKGROUND_REVIEW+ + yaml.safe_dump(merged))+ monkeypatch.setattr(gateway_run, "_hermes_home", home)+ monkeypatch.setattr(gateway_run, "_resolve_runtime_agent_kwargs", lambda: {+ "api_key": "sk-fake-e2e", "base_url": srv.base_url, "provider": "custom", "api_mode": "chat_completions"})+ runner = _make_runner(chat)+ runner.config.streaming = StreamingConfig(enabled=False)++ async def handler(ev):+ result = await runner._run_agent(message=ev.text, context_prompt="", history=[], source=source,+ session_id="s1", session_key=session_key)+ return None if result.get("already_sent") else result["final_response"]++ chat.set_message_handler(handler)+ turn = asyncio.ensure_future(chat._process_message_background(event, session_key))+ if during is not None:+ await during()+ await asyncio.wait_for(turn, timeout=60)+ # A background unit must settle before its provider goes away.+ await asyncio.to_thread(wait_until, lambda: async_delegation.active_count() == 0, 30, 0.02, "async units")+ parent_requests = [r["body"] for r in srv.requests+ if r["kind"] == "main" and GOAL not in _first_user_text(r)]+ return chat, parent_requests+++def _interim(value) -> dict:+ return {"display": {"interim_assistant_messages": value}}+++async def test_interim_off_joins_the_children_and_the_chat_gets_one_completed_answer(monkeypatch, dispatches):+ chat, requests = await _turn(monkeypatch, _interim(False))++ assert chat.sent == [ANSWER] # one message, written after the child's result+ assert chat.typing # the typing indicator is what the user sees while the children run+ delegate = _delegate_def(requests[0])+ assert END_TURN not in delegate["description"] and "BETWEEN your turns" not in delegate["description"]+ assert "results return in this tool call" in delegate["description"]+ assert not {"action", "subagent_id", "message"} & set(delegate["parameters"]["properties"])+ tool_result = requests[-1]["messages"][-1]+ assert tool_result["role"] == "tool" and FINDING in tool_result["content"]+ assert END_TURN not in tool_result["content"] and '"dispatched"' not in tool_result["content"]+ assert dispatches == [] # the async completion registry is never used+++async def test_interim_on_keeps_the_background_path_and_its_schema_byte_identical(monkeypatch, dispatches):+ import model_tools++ chat, requests = await _turn(monkeypatch, {})++ assert chat.sent == [PAUSE] # today's behaviour: the status is the turn's answer+ assert len(dispatches) == 1+ delegate = _delegate_def(requests[0])+ assert END_TURN in delegate["description"]+ registry_delegate = next(t["function"] for t in model_tools.get_tool_definitions(+ enabled_toolsets=["delegation", "todo"], quiet_mode=True) if t["function"]["name"] == "delegate_task")+ assert delegate == registry_delegate+ assert '"dispatched"' in requests[-1]["messages"][-1]["content"]++[email protected](("config", "inline"), [+ ({**_interim(True), "delegation": {"gateway_mode": "inline"}}, True),+ ({**_interim(False), "delegation": {"gateway_mode": "background"}}, False),+ ({**_interim(False), "delegation": {"gateway_mode": "async"}}, False),+ ({**_interim(False), "delegation": {"gateway_mode": "auto"}}, True),+], ids=["inline-overrides-interim-on", "background-overrides-interim-off", "async-alias", "explicit-auto"])+async def test_an_explicit_gateway_mode_wins_over_the_interim_setting(monkeypatch, dispatches, config, inline):+ chat, requests = await _turn(monkeypatch, config)++ assert chat.sent == ([ANSWER] if inline else [PAUSE])+ assert (END_TURN in _delegate_def(requests[0])["description"]) is not inline+ assert len(dispatches) == (0 if inline else 1)++[email protected](("platform", "inline"), [(Platform.WHATSAPP, True), (Platform.TELEGRAM, False)])+async def test_a_platform_interim_override_decides_for_that_platform_only(monkeypatch, dispatches, platform, inline):+ config = {"display": {"interim_assistant_messages": True,+ "platforms": {"whatsapp": {"interim_assistant_messages": False}}}}+ chat, _ = await _turn(monkeypatch, config, platform=platform)++ assert chat.sent == ([ANSWER] if inline else [PAUSE])+ assert len(dispatches) == (0 if inline else 1)+++async def test_a_platform_override_can_turn_interim_back_on_under_a_global_off(monkeypatch, dispatches):+ config = {"display": {"interim_assistant_messages": False,+ "platforms": {"whatsapp": {"interim_assistant_messages": True}}}}+ chat, _ = await _turn(monkeypatch, config)++ assert chat.sent == [PAUSE] and len(dispatches) == 1++[email protected]("hard", [True, False], ids=["stop-command", "interrupting-follow-up"])+async def test_stop_during_the_inline_wait_cancels_the_children(monkeypatch, dispatches, hard):+ """``/stop`` hard-interrupts the running parent and a follow-up message under the default+ ``busy_input_mode: interrupt`` soft-interrupts it; inline children are attached to the parent, so either+ reaches the child's in-flight request and the turn ends without waiting for the provider."""+ from tools import delegate_tool++ parents, stops = [], []+ real_build = delegate_tool._build_child_agent++ def recording_build(*args, **kwargs):+ child = real_build(*args, **kwargs)+ parents.append(kwargs.get("parent_agent"))+ for name in ("interrupt", "hard_interrupt"): # instance attributes win the static lookup too+ real = getattr(child, name)+ setattr(child, name, lambda *a, _real=real, _name=name, **k: (stops.append(_name), _real(*a, **k))[1])+ return child++ monkeypatch.setattr(delegate_tool, "_build_child_agent", recording_build)+ child_waiting = threading.Event()+ respond, _ = _model(Text("unused"))++ def routed(request):+ if GOAL in _first_user_text(request):+ if not child_waiting.is_set(): # the first child's request never gets an answer+ child_waiting.set()+ return Hang(seconds=120)+ return Text(f"Audit finished: {FINDING}")+ return respond(request)++ async def stop_once_the_child_waits():+ assert await asyncio.to_thread(child_waiting.wait, 30), "the child never reached its provider"+ if hard:+ parents[0].interrupt(None, hard_cancel=True) # what /stop does to the running agent+ else:+ parents[0].interrupt("actually, check payroll instead") # a follow-up in interrupt mode++ started = time.monotonic()+ chat, _ = await _turn(monkeypatch, _interim(False), model=(routed, lambda req: Text("Fake summary.")),+ during=stop_once_the_child_waits)++ assert stops # the stop reached the child through the parent's interrupt fan-out+ assert time.monotonic() - started < 60 # the turn did not sit out the child's 120 s provider hang+ if hard:+ assert all(FINDING not in text for text in chat.sent)+ else: # the follow-up then runs as the next turn, which delegates afresh and answers once+ assert chat.sent[-1] == ANSWER+ assert dispatches == []+++def test_each_profile_resolves_its_own_mode_under_the_multiplexer(monkeypatch, tmp_path):+ """A -> B -> A through ``_profile_scope_for_source`` (the seam every turn enters): the mode comes from the+ routed profile's own config, never from whichever profile resolved last."""+ from agent import secret_scope+ from tools.delegate_tool_config import gateway_delegation_inline++ root = tmp_path / "hermes"+ beta = root / "profiles" / "beta"+ beta.mkdir(parents=True)+ (root / "config.yaml").write_text(yaml.safe_dump(_interim(False)))+ (beta / "config.yaml").write_text(yaml.safe_dump(_interim(True)))+ monkeypatch.setenv("HERMES_HOME", str(root))+ monkeypatch.setattr("hermes_constants.get_default_hermes_root", lambda: root)+ prev = secret_scope.is_multiplex_active()+ secret_scope.set_multiplex_active(True)+ try:+ runner = _make_runner(_Chat(Platform.WHATSAPP))+ runner.config.multiplex_profiles = True+ source_a = SessionSource(platform=Platform.WHATSAPP, chat_id="D1", chat_type="dm", profile="default")+ source_b = SessionSource(platform=Platform.WHATSAPP, chat_id="D2", chat_type="dm", profile="beta")+ seen = []+ for source in (source_a, source_b, source_a):+ with runner._profile_scope_for_source(source): # the inputs a fresh agent's build resolves from+ disp = runner._run_agent_display_settings(source)+ seen.append(gateway_delegation_inline(+ disp.user_config, disp.platform_key, interim_enabled=disp.interim_assistant_messages_enabled))+ finally:+ secret_scope.set_multiplex_active(prev)+ assert seen == [True, False, True]++[email protected]("platform_key", ["api_server", "local", "webhook"])+def test_auto_never_joins_on_a_surface_that_is_not_a_chat(platform_key):+ """``auto`` is about a pause message reaching a person: API, local and webhook turns keep today's path."""+ from tools.delegate_tool_config import gateway_delegation_inline++ assert gateway_delegation_inline(_interim(False), platform_key, interim_enabled=False) is False+ assert gateway_delegation_inline({"delegation": {"gateway_mode": "inline"}}, platform_key, interim_enabled=True)diff --git a/tests/tools/test_delegate_gateway_inline.py b/tests/tools/test_delegate_gateway_inline.pynew file mode 100644index 00000000000..8b8c457acf9--- /dev/null+++ b/tests/tools/test_delegate_gateway_inline.py@@ -0,0 +1,165 @@+"""A session's ``delegate_task`` schema decides whether its children join in the call.++The gateway builds a session's agent inside ``gateway_delegation_inline_scope`` when that session resolved+``delegation.gateway_mode`` to inline (``auto`` + interim assistant messages off, or ``inline``). The tool build+then carries the joined ``delegate_task`` variant (results return in the call, no live control), and dispatch+follows the variant the model actually sees, so schema and behaviour cannot disagree. The variant rides the+session's tools[] pin like every other schema byte: a config edit applies from the next session (``/new``),+the rule ``delegation.backend`` already follows, and a cache eviction or restart never flips a live chat.+"""++from __future__ import annotations++import json+from types import SimpleNamespace+from unittest.mock import MagicMock++import pytest++from gateway.session_context import set_session_vars+from tools.process_registry import process_registry++LIVE_CONTROL = {"action", "subagent_id", "message"}++[email protected](autouse=True)+def _clean_queue_and_context(monkeypatch):+ import gateway.session_context as sc++ monkeypatch.delenv("HERMES_SINGLE_QUERY_SESSION", raising=False)+ yield+ for var in sc._VAR_MAP.values():+ var.set(sc._UNSET)+ sc._SESSION_ASYNC_DELIVERY.set(sc._UNSET)+ sc._SESSION_HISTORY_DELIVERY.set(sc._UNSET)+ while not process_registry.completion_queue.empty():+ process_registry.completion_queue.get_nowait()+++def _built(inline: bool):+ from agent.agent_init import _load_tools+ from tools.delegate_tool_config import gateway_delegation_inline_scope++ agent = SimpleNamespace(platform="whatsapp", quiet_mode=True)+ with gateway_delegation_inline_scope(inline):+ _load_tools(agent, ["hermes-cli"], None)+ return agent+++def _delegate(agent) -> dict:+ return next(t["function"] for t in agent.tools if t["function"]["name"] == "delegate_task")+++def test_the_build_scope_picks_the_schema_and_the_agent_keeps_it():+ import model_tools+ from tools.delegate_tool import oneshot_delegate_function+ from tools.mcp_tool_agent import refresh_agent_mcp_tools++ background = _built(inline=False)+ registry = next(t["function"] for t in model_tools.get_tool_definitions(+ enabled_toolsets=["hermes-cli"], disabled_toolsets=background.disabled_toolsets, quiet_mode=True)+ if t["function"]["name"] == "delegate_task")+ assert _delegate(background) == registry # byte-identical to main++ inline = _built(inline=True)+ assert _delegate(inline) == oneshot_delegate_function(registry)+ assert "END YOUR TURN" not in _delegate(inline)["description"]+ assert not LIVE_CONTROL & set(_delegate(inline)["parameters"]["properties"])+ assert "clarify" in {t["function"]["name"] for t in inline.tools} # nothing else of the one-shot footprint++ # A later rebuild outside any gateway scope (explicit reload, compaction) keeps the session's variant.+ refresh_agent_mcp_tools(inline, quiet_mode=True, content_aware=True)+ assert _delegate(inline) == oneshot_delegate_function(registry)+++def test_a_session_keeps_its_mode_until_a_new_session():+ """Operator flips interim back on mid-session, then the cached agent is evicted: the fresh agent is built+ for background, but the session pin restores the joined schema the model has been seeing, and dispatch+ follows the pin. A new session (no pin) takes the new setting."""+ from tools.delegate_tool import session_joins_delegation+ from tools.mcp_tool_agent import restore_agent_tool_prefix, tool_pin_version++ first = _built(inline=True)+ fresh = _built(inline=False)+ restore_agent_tool_prefix(fresh, {"version": tool_pin_version(), "tools": first.tools})+ assert _delegate(fresh) == _delegate(first)+ assert session_joins_delegation(fresh) is True+ assert session_joins_delegation(_built(inline=False)) is False++ # And the other way round: a background session stays background after interim is turned off.+ background = _built(inline=False)+ rebuilt = _built(inline=True)+ restore_agent_tool_prefix(rebuilt, {"version": tool_pin_version(), "tools": background.tools})+ assert session_joins_delegation(rebuilt) is False+++def _parent(tools, depth=0):+ parent = MagicMock()+ parent._delegate_depth = depth+ parent.session_id = "sess"+ parent._interrupt_requested = False+ parent._active_children = []+ parent._active_children_lock = None+ parent._oneshot_session = False+ parent.tools = tools+ return parent+++def fast_children(monkeypatch):+ import tools.delegate_tool as dt++ def build_child(**kw):+ child = MagicMock()+ child._delegate_role, child._subagent_id = "leaf", "s1"+ return child++ def run_child(task_index, goal, child=None, parent_agent=None, **kw):+ return {"task_index": task_index, "status": "completed", "summary": f"done: {goal}",+ "api_calls": 1, "duration_seconds": 0.1, "model": "m", "exit_reason": "completed"}++ creds = dict.fromkeys(("provider", "base_url", "api_key", "api_mode", "command", "args"), None)+ monkeypatch.setattr(dt, "_build_child_agent", build_child)+ monkeypatch.setattr(dt, "_run_single_child", run_child)+ monkeypatch.setattr(dt, "_resolve_delegation_credentials", lambda *a, **k: {**creds, "model": "m"})+ set_session_vars(platform="whatsapp", chat_id="c1", session_key="agent:main:whatsapp:dm:c1", session_id="sess")+ return dt+++def test_dispatch_follows_the_schema_the_session_carries(fast_children, monkeypatch):+ from tools import async_delegation++ dispatched = []+ monkeypatch.setattr(async_delegation, "dispatch_async_delegation_batch",+ lambda **kw: dispatched.append(kw) or {"status": "dispatched", "delegation_id": "d1"})++ joined = json.loads(fast_children.delegate_task(+ goal="audit", background=True, parent_agent=_parent(_built(inline=True).tools)))+ assert joined["results"][0]["summary"] == "done: audit"+ assert "note" not in joined and dispatched == [] # no "end your turn", no async registry++ detached = json.loads(fast_children.delegate_task(+ goal="audit", background=True, parent_agent=_parent(_built(inline=False).tools)))+ assert detached["status"] == "dispatched" and "END YOUR TURN" in detached["note"]+ assert len(dispatched) == 1+++def test_nested_and_one_shot_delegation_keep_their_own_paths(fast_children, monkeypatch):+ # An orchestrator child (depth > 0) was always synchronous; a one-shot session keeps its explanatory note.+ monkeypatch.setattr(fast_children, "_get_max_spawn_depth", lambda: 2)+ nested = json.loads(fast_children.delegate_task(+ goal="audit", background=False, parent_agent=_parent(_built(inline=False).tools, depth=1)))+ assert nested["results"][0]["status"] == "completed" and "note" not in nested++ oneshot = _parent(_built(inline=True).tools)+ oneshot._oneshot_session = True+ result = json.loads(fast_children.delegate_task(goal="audit", background=True, parent_agent=oneshot))+ assert "SYNCHRONOUSLY" in result["note"]+++def test_live_control_degrades_to_plain_answers_in_an_inline_session(fast_children):+ parent = _parent(_built(inline=True).tools)+ listed = json.loads(fast_children.delegate_task(action="list", parent_agent=parent))+ assert isinstance(listed, dict)+ stopped = json.loads(fast_children.delegate_task(action="stop", subagent_id="nope", parent_agent=parent))+ assert "error" in stoppeddiff --git a/tools/AGENTS.md b/tools/AGENTS.mdindex 3af6842bb27..78a80afbca2 100644--- a/tools/AGENTS.md+++ b/tools/AGENTS.md@@ -152,7 +152,7 @@ and the stall clock arms when the runner starts, so a queued unit is never judgeno `delegate_task`, `clarify`, `memory`, `send_message`, `cronjob`; keeps `execute_code`) and`orchestrator` (keeps `delegate_task`; gated by `delegation.orchestrator_enabled`, bounded by`delegation.max_spawn_depth`, default 2). Config knobs under `delegation:`:-`max_concurrent_children, independent_completions, max_spawn_depth, child_timeout_seconds, orchestrator_enabled,+`max_concurrent_children, independent_completions, gateway_mode, max_spawn_depth, child_timeout_seconds, orchestrator_enabled,subagent_auto_approve, inherit_mcp_toolsets, max_iterations, backend, backends`. **Routes:** `delegation.backend` picks adelegation provider (`agent/delegation_provider.py`, `ctx.register_delegation_provider`; its settings live in`delegation.backends.<name>`) that answers each task's route (`tools/delegate_tool_routes.py`: model/provider fieldsdiff --git a/tools/delegate_tool.py b/tools/delegate_tool.pyindex be53cfb15ce..e057e7e0187 100644--- a/tools/delegate_tool.py+++ b/tools/delegate_tool.py@@ -872,6 +872,20 @@ def oneshot_delegate_function(function: dict) -> dict:return {**function, "description": description, "parameters": {**params, "properties": properties}}+def session_joins_delegation(agent: Any) -> bool:+ """Whether *agent*'s top-level delegations join in the call because the ``delegate_task`` the model sees is the+ joined variant (a gateway session with ``delegation.gateway_mode`` inline). Dispatch follows the schema bytes,+ which ride the session's tools[] pin: a config change can never leave the model reading "results return in+ this tool call" while children detach, or the reverse. One-shot sessions keep their own fallback (and note)."""+ if getattr(agent, "_oneshot_session", None) is True:+ return False+ for tool in getattr(agent, "tools", None) or ():+ function = tool.get("function") if isinstance(tool, dict) else None+ if isinstance(function, dict) and function.get("name") == "delegate_task":+ return _ONESHOT_DESCRIPTION_DELIVERY in (function.get("description") or "")+ return False++# --- Registry ---from tools.registry import registry, tool_errordiff --git a/tools/delegate_tool_config.py b/tools/delegate_tool_config.pyindex 23b175f937b..96c9c0ef826 100644--- a/tools/delegate_tool_config.py+++ b/tools/delegate_tool_config.py@@ -4,7 +4,9 @@ from __future__ import annotationsimport loggingimport os-from typing import Any, Dict, List, NamedTuple, Optional+from contextlib import contextmanager+from contextvars import ContextVar+from typing import Any, Dict, Iterator, List, NamedTuple, Optionalfrom utils import base_url_hostname, is_truthy_valuefrom hermes_cli.fallback_config import scoped_fallback_chain@@ -112,6 +114,46 @@ def _get_independent_completions() -> bool:completion messages that land as each finishes. Off = one consolidated message when the whole call is done."""return is_truthy_value(_cfg().get("independent_completions", False))+# delegation.gateway_mode: "background" (alias "async") always detaches; "inline" joins in the turn; anything else is+# "auto". Read from the gateway turn's own (profile-scoped) user config, not from this process's config.+_GATEWAY_MODES = {"inline": True, "background": False, "async": False}++def gateway_delegation_inline(user_config: Any, platform_key: str, *, interim_enabled: bool) -> bool:+ """Whether a gateway session joins its top-level delegations inside the turn (``delegation.gateway_mode``).++ ``auto`` (default) joins on a human chat whose interim assistant messages are off (the gateway's resolved+ ``display.interim_assistant_messages``, platform overrides included): there the "status, end your turn" reply+ the background path asks for would be delivered as the turn's answer, then the real answer as a second message.+ API, local and webhook surfaces keep the background path under ``auto``."""+ from gateway.session_context import NON_MESSAGING_SESSION_SURFACES+ section = user_config.get("delegation") if isinstance(user_config, dict) else None+ mode = str(section.get("gateway_mode") or "auto").strip().lower() if isinstance(section, dict) else "auto"+ if mode in _GATEWAY_MODES:+ return _GATEWAY_MODES[mode]+ return not interim_enabled and str(platform_key or "").lower() not in NON_MESSAGING_SESSION_SURFACES++# Set by the gateway around building a session's agent; read once by that agent's first tool build.+_GATEWAY_DELEGATION_INLINE: ContextVar[bool] = ContextVar("hermes_gateway_delegation_inline", default=False)++@contextmanager+def gateway_delegation_inline_scope(inline: bool) -> Iterator[None]:+ """Build an agent whose session joins its delegations in the call (see :func:`agent_joins_delegation`)."""+ token = _GATEWAY_DELEGATION_INLINE.set(bool(inline))+ try:+ yield+ finally:+ _GATEWAY_DELEGATION_INLINE.reset(token)++def agent_joins_delegation(agent: Any) -> bool:+ """The gateway's inline decision, frozen on *agent* at its first tool build (like ``agent_is_oneshot``), so+ later rebuilds outside the build scope keep the same ``delegate_task`` bytes. Dispatch does not read this: it+ follows the schema the session carries (``tools.delegate_tool.session_joins_delegation``)."""+ cached = getattr(agent, "_delegation_inline", None)+ if not isinstance(cached, bool):+ cached = _GATEWAY_DELEGATION_INLINE.get()+ agent._delegation_inline = cached+ return cached+def _get_worktree_isolation() -> bool:"""delegation.worktree_isolation (bool, default False): each child gets its owngit worktree off the parent's HEAD so parallel children never contend for onediff --git a/tools/delegate_tool_dispatch.py b/tools/delegate_tool_dispatch.pyindex 30a4d5412b9..8d498e3b53e 100644--- a/tools/delegate_tool_dispatch.py+++ b/tools/delegate_tool_dispatch.py@@ -486,10 +486,11 @@ def _dispatch_background(batch: _Batch) -> str:def _run_batch(batch: _Batch, background: bool) -> str:"""Tool result JSON: a dispatch handle (background) or the joined combined results."""+ from tools.delegate_tool import session_joins_delegation# Every unit of this call shares task_list, so its last joined unit emits the call's one row.begin_delegation_run(batch.task_list, subagents=len(batch.children), depth=getattr(batch.parent_agent, "_delegate_depth", 0) + 1,)- if background:+ if background and not session_joins_delegation(batch.parent_agent):return _dispatch_background(batch)return json.dumps(_execute_and_aggregate(batch), ensure_ascii=False)diff --git a/toolsets.py b/toolsets.pyindex a4f73e29c05..1d931d1e7d7 100644--- a/toolsets.py+++ b/toolsets.py@@ -474,13 +474,15 @@ def agent_tool_drops(agent: Any) -> frozenset:def agent_tool_surface(agent: Any, tools: list[dict[str, Any]]) -> list[dict[str, Any]]:- """*tools* as *agent* carries them: :func:`agent_tool_drops` removed and, in a one-shot session, the- one-shot schema variants (``agent.oneshot_footprint.oneshot_tool_schemas``). Applied to FRESH definitions (load,- MCP refresh) before any merge: a pinned or carried entry keeps the bytes already sent."""+ """*tools* as *agent* carries them: :func:`agent_tool_drops` removed and, in a one-shot session or a gateway+ session that joins its delegations in the turn (``delegation.gateway_mode``), the joined ``delegate_task``+ variant (``agent.oneshot_footprint.oneshot_tool_schemas``). Applied to FRESH definitions (load, MCP refresh)+ before any merge: a pinned or carried entry keeps the bytes already sent."""from agent.oneshot_footprint import agent_is_oneshot, oneshot_tool_schemas+ from tools.delegate_tool_config import agent_joins_delegationdrops = agent_tool_drops(agent)tools = [tool for tool in tools if (tool.get("function") or {}).get("name") not in drops] if drops else list(tools)- return oneshot_tool_schemas(tools) if agent_is_oneshot(agent) else tools+ return oneshot_tool_schemas(tools) if agent_is_oneshot(agent) or agent_joins_delegation(agent) else toolsdef validate_toolset(name: str) -> bool:diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.mdindex 1ebaadb8a5e..8220b94d235 100644--- a/website/docs/user-guide/configuration.md+++ b/website/docs/user-guide/configuration.md@@ -3089,6 +3089,7 @@ delegation:max_spawn_depth: 1 # Delegation tree depth cap (1-3, clamped). 1 = flat (default): parent spawns leaves that cannot delegate. 2 = orchestrator children can spawn leaf grandchildren. 3 = three levels.orchestrator_enabled: true # Global kill switch. When false, role="orchestrator" is ignored and every child is forced to leaf regardless of max_spawn_depth.oneshot_max_children: 2 # Total subagents a one-shot run (hermes chat -q / --oneshot) may spawn; 0 = unlimited. Interactive and gateway sessions are never capped by this.+ gateway_mode: auto # Gateway sessions: auto | inline | background. auto = join children inside the turn (one answer) on a messaging chat whose display.interim_assistant_messages is off. See Subagent Delegation → Messaging chats without interim messages.```**Delegation strategy (`backend`):** `delegation.backend` picks the strategy plugin that decides each subagent's route. `default` follows the keys below (or the parent's route when they are empty). Plugin strategies such as `model_map` (a named model per task) and `profile_routes` (a Hermes profile per task) read their settings from `delegation.backends.<backend name>`. A backend whose plugin is missing or disabled fails closed: `delegate_task` returns a tool error naming it and the fix (`/delegation default`, or `hermes config set delegation.backend default`) instead of running children on another route. A backend route without its own `fallback_providers` uses `delegation.fallback_providers`. See [Subagent Delegation → Delegation strategies](features/delegation.md#delegation-strategies-delegationbackend).diff --git a/website/docs/user-guide/features/delegation.md b/website/docs/user-guide/features/delegation.mdindex 46a4a4f11bf..29a4c5595b1 100644--- a/website/docs/user-guide/features/delegation.md+++ b/website/docs/user-guide/features/delegation.md@@ -606,7 +606,8 @@ parent in the same turn. Batch children still run in parallel, subject tofinal response before the CLI exits.- **Automatic joining:** no opt-in or background-mode override is needed.- Interactive TTY chat and messaging sessions keep background delegation.+ Interactive TTY chat keeps background delegation; messaging sessions follow+ `delegation.gateway_mode` (see below).- **Per-input policy:** the CLI records finite consumption with the admitted prompt,including when resuming an interactive session. It does not change that session'screation policy, sibling viewers, or the daemon environment.@@ -623,6 +624,40 @@ Closing the CLI detaches rather than terminating its gateway-owned turn. Childexecution is still process-local to that owner: use a durable scheduler for workthat must survive an owner restart.+## Messaging chats without interim messages++On a messaging platform, a background delegation tells the parent to send a one-line+status and end its turn. When `display.interim_assistant_messages` is off for that+platform, that status is the turn's final answer, so the chat would receive a "working+on it" message and then the real answer as a second message. `delegation.gateway_mode`+controls this:++```yaml+delegation:+ gateway_mode: auto # auto (default) | inline | background+```++- **`auto`:** a messaging chat whose resolved `display.interim_assistant_messages` is off+ (global value, `display.platforms.<platform>` override or the platform's default) joins+ its children inside the turn. The parent waits in the `delegate_task` call, gets the+ results there, and sends one completed answer. Chats with interim messages on, the API+ server, local sessions and webhooks keep background delegation.+- **`inline`:** every gateway session joins its children inside the turn.+- **`background`** (alias `async`): every gateway session keeps background delegation.++An inline session's `delegate_task` says results return in the call and leaves out the+live-control parameters (`action` list/steer/stop, `subagent_id`, `message`), the same+schema as a one-shot run. While it waits, the typing indicator stays on and the turn+behaves like any long tool call. `/stop` stops the children, and so does a follow-up+message under the default `busy_input_mode: interrupt` (each child returns an interrupted+result with its partial output); under `queue` the follow-up waits for the turn.+`display.long_running_notifications` still governs the periodic "still working" notice.+Nested delegation is unchanged.++The mode is part of a session's tool schema, which is cached with the conversation. A+change to `gateway_mode` or to `interim_assistant_messages` applies from the next session+(`/new`); a running chat keeps the mode it started with, also across gateway restarts.+## Lifetime and Durability:::warning Background completion durability is not durable execution@@ -709,6 +744,7 @@ delegation:max_iterations: 250 # Max turns per child (default: 250)# max_concurrent_children: 10 # Parallel children per batch (default: 10)# independent_completions: false # true = each task/group returns as it finishes (default: one message per call)+ # gateway_mode: auto # auto | inline | background (see Messaging chats without interim messages)# worktree_isolation: false # Give each child its own git worktree (see Worktree Isolation above)# max_spawn_depth: 1 # Tree depth (floor 1, no ceiling, default 1 = flat). Raise to 2 to allow orchestrator children to spawn leaves; 3+ for deeper trees.# orchestrator_enabled: true # Disable to force all children to leaf role.