feat(subagent): guard transfer_to calls with per-run limit

astrbot/core/astr_agent_tool_exec.py

@@ -44,6 +44,100 @@
 
 
 class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
+    _HANDOFF_CALL_COUNT_EXTRA_KEY = "_subagent_handoff_call_count"
+    _DEFAULT_MAX_HANDOFF_CALLS_PER_RUN = 8
+    _MAX_HANDOFF_CALL_COUNT_SANITY_LIMIT = 10_000
+
+    @classmethod
+    def _coerce_int(
+        cls,
+        value: T.Any,
+        *,
+        default: int,
+        minimum: int,
+        maximum: int,
+    ) -> int:
+        try:
+            parsed = int(value)
+        except (TypeError, ValueError):
+            return default
+        return max(minimum, min(maximum, parsed))
+
+    @classmethod
+    def _get_event_extra(
+        cls,
+        event: T.Any,
+        key: str,
+        default: T.Any = None,
+    ) -> T.Any:
+        if event is None:
+            return default
+
+        get_extra = getattr(event, "get_extra", None)
+        if get_extra is None:
+            return default
+
+        try:
+            return get_extra(key, default)
+        except TypeError:
+            result = get_extra(key)
+            return default if result is None else result
+
+    @classmethod
+    def _set_event_extra(cls, event: T.Any, key: str, value: T.Any) -> bool:
+        set_extra = getattr(event, "set_extra", None)
+        if set_extra is None:
+            return False
+        try:
+            set_extra(key, value)
+            return True
+        except TypeError:
+            return False
+
+    @classmethod
+    def _resolve_handoff_call_limit(
+        cls,
+        run_context: ContextWrapper[AstrAgentContext],
+    ) -> int:
+        ctx = run_context.context.context
+        event = run_context.context.event
+        cfg = ctx.get_config(umo=event.unified_msg_origin)
+        subagent_cfg = cfg.get("subagent_orchestrator", {})
+        if not isinstance(subagent_cfg, dict):
+            return cls._DEFAULT_MAX_HANDOFF_CALLS_PER_RUN
+        return cls._coerce_int(
+            subagent_cfg.get(
+                "max_handoff_calls_per_run",
+                cls._DEFAULT_MAX_HANDOFF_CALLS_PER_RUN,
+            ),
+            default=cls._DEFAULT_MAX_HANDOFF_CALLS_PER_RUN,
+            minimum=1,
+            maximum=128,
+        )
+
+    @classmethod
+    def _check_and_increment_handoff_calls(
+        cls,
+        run_context: ContextWrapper[AstrAgentContext],
+    ) -> tuple[bool, int]:
+        event = run_context.context.event
+        max_handoff_calls = cls._resolve_handoff_call_limit(run_context)
+        current_handoff_count = cls._coerce_int(
+            cls._get_event_extra(event, cls._HANDOFF_CALL_COUNT_EXTRA_KEY, 0),
+            default=0,
+            minimum=0,
+            maximum=cls._MAX_HANDOFF_CALL_COUNT_SANITY_LIMIT,
+        )
+        if current_handoff_count >= max_handoff_calls:
+            return False, max_handoff_calls
+
+        cls._set_event_extra(
+            event,
+            cls._HANDOFF_CALL_COUNT_EXTRA_KEY,
+            current_handoff_count + 1,
+        )
+        return True, max_handoff_calls
+
     @classmethod
     def _collect_image_urls_from_args(cls, image_urls_raw: T.Any) -> list[str]:
         if image_urls_raw is None:
@@ -246,6 +340,23 @@ async def _execute_handoff(
     ):
         tool_args = dict(tool_args)
         input_ = tool_args.get("input")
+        ctx = run_context.context.context
+        allowed, max_handoff_calls = cls._check_and_increment_handoff_calls(run_context)
+        if not allowed:
+            yield mcp.types.CallToolResult(
+                content=[
+                    mcp.types.TextContent(
+                        type="text",
+                        text=(
+                            "error: handoff_call_limit_reached. "
+                            f"max_handoff_calls_per_run={max_handoff_calls}. "
+                            "Stop delegating and continue with current context."
+                        ),
+                    )
+                ]
+            )
+            return
+        event = run_context.context.event
         if image_urls_prepared:
             prepared_image_urls = tool_args.get("image_urls")
             if isinstance(prepared_image_urls, list):
@@ -266,8 +377,6 @@ async def _execute_handoff(
         # Build handoff toolset from registered tools plus runtime computer tools.
         toolset = cls._build_handoff_toolset(run_context, tool.agent.tools)
 
-        ctx = run_context.context.context
-        event = run_context.context.event
         umo = event.unified_msg_origin
 
         # Use per-subagent provider override if configured; otherwise fall back

astrbot/core/config/default.py

@@ -188,6 +188,9 @@
     "subagent_orchestrator": {
         "main_enable": False,
         "remove_main_duplicate_tools": False,
+        # Limits total handoff tool calls in one agent run to prevent
+        # runaway delegation loops.
+        "max_handoff_calls_per_run": 8,
         "router_system_prompt": (
             "You are a task router. Your job is to chat naturally, recognize user intent, "
             "and delegate work to the most suitable subagent using transfer_to_* tools. "

astrbot/dashboard/routes/subagent.py

@@ -4,10 +4,15 @@
 
 from astrbot.core import logger
 from astrbot.core.agent.handoff import HandoffTool
+from astrbot.core.config.default import DEFAULT_CONFIG
 from astrbot.core.core_lifecycle import AstrBotCoreLifecycle
 
 from .route import Response, Route, RouteContext
 
+DEFAULT_MAX_HANDOFF_CALLS_PER_RUN = int(
+    DEFAULT_CONFIG.get("subagent_orchestrator", {}).get("max_handoff_calls_per_run", 8)
+)
+
 
 class SubAgentRoute(Route):
     def __init__(
@@ -36,6 +41,7 @@ async def get_config(self):
                 data = {
                     "main_enable": False,
                     "remove_main_duplicate_tools": False,
+                    "max_handoff_calls_per_run": DEFAULT_MAX_HANDOFF_CALLS_PER_RUN,
                     "agents": [],
                 }
 
@@ -50,6 +56,10 @@ async def get_config(self):
             # Ensure required keys exist.
             data.setdefault("main_enable", False)
             data.setdefault("remove_main_duplicate_tools", False)
+            data.setdefault(
+                "max_handoff_calls_per_run",
+                DEFAULT_MAX_HANDOFF_CALLS_PER_RUN,
+            )
             data.setdefault("agents", [])
 
             # Backward/forward compatibility: ensure each agent contains provider_id.

tests/unit/test_astr_agent_tool_exec.py

@@ -343,3 +343,219 @@ async def _fake_convert_to_file_path(self):
     )
 
     assert image_urls == []
+
+
+@pytest.mark.asyncio
+async def test_execute_handoff_rejects_when_call_limit_reached():
+    captured: dict = {}
+
+    class _EventWithExtras:
+        def __init__(self) -> None:
+            self.unified_msg_origin = "webchat:FriendMessage:webchat!user!session"
+            self.message_obj = SimpleNamespace(message=[])
+            self._extras = {
+                FunctionToolExecutor._HANDOFF_CALL_COUNT_EXTRA_KEY: 1,
+            }
+
+        def get_extra(self, key: str, default=None):
+            return self._extras.get(key, default)
+
+        def set_extra(self, key: str, value):
+            self._extras[key] = value
+
+    async def _fake_get_current_chat_provider_id(_umo):
+        return "provider-id"
+
+    async def _fake_tool_loop_agent(**kwargs):
+        captured.update(kwargs)
+        return SimpleNamespace(completion_text="ok")
+
+    context = SimpleNamespace(
+        get_current_chat_provider_id=_fake_get_current_chat_provider_id,
+        tool_loop_agent=_fake_tool_loop_agent,
+        get_config=lambda **_kwargs: {
+            "provider_settings": {},
+            "subagent_orchestrator": {"max_handoff_calls_per_run": 1},
+        },
+    )
+    event = _EventWithExtras()
+    run_context = ContextWrapper(context=SimpleNamespace(event=event, context=context))
+    tool = SimpleNamespace(
+        name="transfer_to_subagent",
+        provider_id=None,
+        agent=SimpleNamespace(
+            name="subagent",
+            tools=[],
+            instructions="subagent-instructions",
+            begin_dialogs=[],
+            run_hooks=None,
+        ),
+    )
+
+    results = []
+    async for result in FunctionToolExecutor._execute_handoff(
+        tool,
+        run_context,
+        image_urls_prepared=True,
+        input="hello",
+        image_urls=[],
+    ):
+        results.append(result)
+
+    assert len(results) == 1
+    assert "handoff_call_limit_reached" in results[0].content[0].text
+    assert captured == {}
+
+
+@pytest.mark.asyncio
+async def test_execute_handoff_increments_call_count_on_success():
+    class _EventWithExtras:
+        def __init__(self) -> None:
+            self.unified_msg_origin = "webchat:FriendMessage:webchat!user!session"
+            self.message_obj = SimpleNamespace(message=[])
+            self._extras: dict[str, int] = {}
+
+        def get_extra(self, key: str, default=None):
+            return self._extras.get(key, default)
+
+        def set_extra(self, key: str, value):
+            self._extras[key] = value
+
+    async def _fake_get_current_chat_provider_id(_umo):
+        return "provider-id"
+
+    async def _fake_tool_loop_agent(**_kwargs):
+        return SimpleNamespace(completion_text="ok")
+
+    context = SimpleNamespace(
+        get_current_chat_provider_id=_fake_get_current_chat_provider_id,
+        tool_loop_agent=_fake_tool_loop_agent,
+        get_config=lambda **_kwargs: {
+            "provider_settings": {},
+            "subagent_orchestrator": {"max_handoff_calls_per_run": 2},
+        },
+    )
+    event = _EventWithExtras()
+    run_context = ContextWrapper(context=SimpleNamespace(event=event, context=context))
+    tool = SimpleNamespace(
+        name="transfer_to_subagent",
+        provider_id=None,
+        agent=SimpleNamespace(
+            name="subagent",
+            tools=[],
+            instructions="subagent-instructions",
+            begin_dialogs=[],
+            run_hooks=None,
+        ),
+    )
+
+    results = []
+    async for result in FunctionToolExecutor._execute_handoff(
+        tool,
+        run_context,
+        image_urls_prepared=True,
+        input="hello",
+        image_urls=[],
+    ):
+        results.append(result)
+
+    assert len(results) == 1
+    assert (
+        event._extras[FunctionToolExecutor._HANDOFF_CALL_COUNT_EXTRA_KEY]
+        == 1
+    )
+
+
+@pytest.mark.asyncio
+async def test_execute_handoff_enforces_call_limit_across_multiple_calls():
+    call_count = {"tool_loop": 0}
+
+    class _EventWithExtras:
+        def __init__(self) -> None:
+            self.unified_msg_origin = "webchat:FriendMessage:webchat!user!session"
+            self.message_obj = SimpleNamespace(message=[])
+            self._extras: dict[str, int] = {}
+
+        def get_extra(self, key: str, default=None):
+            return self._extras.get(key, default)
+
+        def set_extra(self, key: str, value):
+            self._extras[key] = value
+
+    async def _fake_get_current_chat_provider_id(_umo):
+        return "provider-id"
+
+    async def _fake_tool_loop_agent(**_kwargs):
+        call_count["tool_loop"] += 1
+        return SimpleNamespace(completion_text="ok")
+
+    context = SimpleNamespace(
+        get_current_chat_provider_id=_fake_get_current_chat_provider_id,
+        tool_loop_agent=_fake_tool_loop_agent,
+        get_config=lambda **_kwargs: {
+            "provider_settings": {},
+            "subagent_orchestrator": {"max_handoff_calls_per_run": 2},
+        },
+    )
+    event = _EventWithExtras()
+    run_context = ContextWrapper(context=SimpleNamespace(event=event, context=context))
+    tool = SimpleNamespace(
+        name="transfer_to_subagent",
+        provider_id=None,
+        agent=SimpleNamespace(
+            name="subagent",
+            tools=[],
+            instructions="subagent-instructions",
+            begin_dialogs=[],
+            run_hooks=None,
+        ),
+    )
+
+    first_results = []
+    async for result in FunctionToolExecutor._execute_handoff(
+        tool,
+        run_context,
+        image_urls_prepared=True,
+        input="first",
+        image_urls=[],
+    ):
+        first_results.append(result)
+    assert len(first_results) == 1
+    assert "handoff_call_limit_reached" not in first_results[0].content[0].text
+    assert (
+        event._extras[FunctionToolExecutor._HANDOFF_CALL_COUNT_EXTRA_KEY]
+        == 1
+    )
+
+    second_results = []
+    async for result in FunctionToolExecutor._execute_handoff(
+        tool,
+        run_context,
+        image_urls_prepared=True,
+        input="second",
+        image_urls=[],
+    ):
+        second_results.append(result)
+    assert len(second_results) == 1
+    assert "handoff_call_limit_reached" not in second_results[0].content[0].text
+    assert (
+        event._extras[FunctionToolExecutor._HANDOFF_CALL_COUNT_EXTRA_KEY]
+        == 2
+    )
+
+    third_results = []
+    async for result in FunctionToolExecutor._execute_handoff(
+        tool,
+        run_context,
+        image_urls_prepared=True,
+        input="third",
+        image_urls=[],
+    ):
+        third_results.append(result)
+    assert len(third_results) == 1
+    assert "handoff_call_limit_reached" in third_results[0].content[0].text
+    assert (
+        event._extras[FunctionToolExecutor._HANDOFF_CALL_COUNT_EXTRA_KEY]
+        == 2
+    )
+    assert call_count["tool_loop"] == 2