aip-agents-binary 0.0.0__py3-none-any.whl

aip_agents/middleware/task_delegation.py

@@ -0,0 +1,1656 @@
+"""Task delegation middleware for dynamic worker spawning.
+
+This module provides a ``task`` tool that allows a parent agent to delegate
+one bounded sub-task to a worker agent at runtime, while enforcing delegation
+depth, concurrency, and tool-scope constraints.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+import uuid
+from collections.abc import AsyncIterator
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any, cast
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import ArgsSchema, BaseTool
+from langgraph.config import get_stream_writer
+from langgraph.types import Command, StreamWriter
+from pydantic import BaseModel, Field, SkipValidation
+
+from aip_agents.middleware.base import AgentMiddleware, ModelRequest
+from aip_agents.middleware.schema import MiddlewareToolConfig
+from aip_agents.schema.step_limit import StepLimitConfig
+from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import (
+    DELEGATED_AGENT_TIMEOUT_CONFIG_ERROR_KEY,
+    INVALID_DELEGATED_AGENT_TIMEOUT_MESSAGE,
+)
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.metadata_helper import MetadataFieldKeys, get_next_step_number
+from aip_agents.utils.pii.pii_helper import extract_pii_mapping_from_agent_response
+from aip_agents.utils.step_limit_manager import (
+    _DELEGATION_CHAIN_CVAR,
+    _DELEGATION_DEPTH_CVAR,
+    _REMAINING_STEP_BUDGET_CVAR,
+    _STEP_LIMIT_CONFIG_CVAR,
+    StepLimitManager,
+)
+from aip_agents.utils.token_usage_helper import (
+    MODEL_USAGE_DELTA_KEY,
+    MODEL_USAGE_KEY,
+    STEP_USAGE_KEY,
+    TOTAL_USAGE_KEY,
+    USAGE_METADATA_KEY,
+)
+
+logger = get_logger(__name__)
+
+TASK_DELEGATION_SYSTEM_PROMPT = (
+    "You are a Coordinator using the `task` tool for bounded delegation.\n"
+    "Default strategy: decompose multi-part or research-heavy requests into delegated tracks, then synthesize worker outputs.\n"
+    "When a request has independent sections or subtasks, delegate each section with `task(...)` before final synthesis.\n"
+    "Keep parent execution focused on orchestration, validation, and final artifact assembly.\n"
+    "After delegating a track, do not repeat materially equivalent tool workflows in the parent; issue a follow-up task instead.\n"
+    "Write task calls with explicit objective, scope, constraints, and output format."
+)
+
+WORKER_DELEGATION_NOT_ALLOWED = "worker_delegation_not_allowed"
+WORKER_CONCURRENCY_LIMIT_REACHED = "worker concurrency limit reached"
+UNKNOWN_OR_DISALLOWED_TOOLS = "unknown_or_disallowed_tools"
+INSUFFICIENT_STEP_BUDGET = "insufficient_step_budget"
+DEFAULT_MAX_CONCURRENT_WORKERS = 5
+DEFAULT_MAX_PENDING_WORKERS = 20
+MAX_ERROR_MESSAGE_LENGTH = 400
+ALLOWED_TOOL_NAME_PREFIXES = ("functions.", "function.", "tools.")
+EVENT_TYPE_TOOL_CALL = "tool_call"
+EVENT_TYPE_TOOL_RESULT = "tool_result"
+EVENT_TYPE_FINAL_RESPONSE = "final_response"
+EVENT_TYPE_CONTENT_CHUNK = "content_chunk"
+EVENT_TYPE_STATUS_UPDATE = "status_update"
+SUB_AGENT_EVENT_METADATA_KEY = "is_sub_agent_event"
+DELEGATION_METADATA_KEY = "delegation_worker_timeout"
+DELEGATION_FAILED_STATUS = "failed"
+DELEGATION_TOOL_TIMEOUT_REASON = "tool_timeout"
+SUB_AGENT_TERMINAL_EVENT_REMAP = {
+    EVENT_TYPE_FINAL_RESPONSE: EVENT_TYPE_CONTENT_CHUNK,
+    "error": EVENT_TYPE_STATUS_UPDATE,
+    "step_limit_exceeded": EVENT_TYPE_STATUS_UPDATE,
+}
+METADATA_INTERNAL_PREFIXES = ("__", "langgraph_", "langchain_")
+METADATA_INTERNAL_KEYS = {"step_id", "previous_step_ids", "agent_name"}
+_TASK_SUB_START_STEP_CVAR: ContextVar[dict[str, str] | None] = ContextVar("_task_sub_start_step_cvar", default=None)
+
+
+class TaskDelegationConfig(BaseModel):
+    """Configuration for dynamic task delegation middleware."""
+
+    max_concurrent_workers: int = DEFAULT_MAX_CONCURRENT_WORKERS
+    max_pending_workers: int = DEFAULT_MAX_PENDING_WORKERS
+    timeout_seconds: float | None = None
+
+    def create_middleware(self, parent_agent: Any) -> TaskDelegationMiddleware:
+        """Create task delegation middleware for one parent agent.
+
+        Returns:
+            TaskDelegationMiddleware: Configured middleware instance.
+        """
+        return TaskDelegationMiddleware(
+            parent_agent=parent_agent,
+            max_concurrent_workers=self.max_concurrent_workers,
+            max_pending_workers=self.max_pending_workers,
+            worker_timeout_seconds=self.timeout_seconds,
+        )
+
+
+class TaskToolSchema(BaseModel):
+    """Schema for task tool inputs.
+
+    Attributes:
+        query (str): Delegated task mission text.
+        prompt (str | None): Optional additional instruction context.
+        allowed_tools (list[str] | None): Optional narrowing-only allowlist.
+    """
+
+    query: str = Field(..., description="Delegated task mission text")
+    prompt: str | None = Field(default=None, description="Optional extra instruction context")
+    allowed_tools: list[str] | None = Field(default=None, description="Optional narrowing-only tool allowlist")
+
+
+class TaskResult(BaseModel):
+    """Deterministic task execution result.
+
+    Attributes:
+        success (bool): True when delegated execution completed successfully.
+        result (str): Worker output text, or empty string on failure.
+        error (str | None): Failure reason when ``success`` is False.
+    """
+
+    success: bool
+    result: str
+    error: str | None = None
+    worker_response: dict[str, Any] | None = Field(default=None, exclude=True, repr=False)
+
+
+@dataclass(frozen=True)
+class WorkerExecutionPlan:
+    """Precomputed worker execution inputs used by ``run_task``.
+
+    Attributes:
+        worker_tools (list[BaseTool]): Effective toolset for worker execution.
+        filesystem_backend (Any | None): Shared filesystem backend when enabled.
+        use_shared_filesystem_middleware (bool): Whether worker should reuse parent
+            filesystem middleware backend.
+        child_budget (int): Derived worker step budget.
+        worker_instruction (str): Final worker system prompt.
+        worker_kwargs (dict[str, Any]): Child runnable kwargs.
+    """
+
+    worker_tools: list[BaseTool]
+    filesystem_backend: Any | None
+    use_shared_filesystem_middleware: bool
+    child_budget: int
+    worker_instruction: str
+    worker_kwargs: dict[str, Any]
+
+
+class TaskDelegationTool(BaseTool):
+    """LangChain-compatible ``task`` tool wrapper.
+
+    Attributes:
+        name (str): Tool name exposed to the model.
+        description (str): Tool behavior summary and argument contract.
+        args_schema (ArgsSchema): Input schema used for argument validation.
+        middleware (TaskDelegationMiddleware): Owning middleware instance.
+    """
+
+    name: str = "task"
+    description: str = (
+        "Spawn an ephemeral worker for one delegated task. "
+        "Arguments: query (required), prompt (optional), allowed_tools (optional narrowing-only)."
+    )
+    args_schema: ArgsSchema = TaskToolSchema
+    tool_config_schema: type[BaseModel] = MiddlewareToolConfig
+    middleware: SkipValidation[TaskDelegationMiddleware] = Field(exclude=True)
+    metadata: dict[str, Any] | None = Field(default=None)
+
+    def _run(
+        self,
+        query: str,
+        prompt: str | None = None,
+        allowed_tools: list[str] | None = None,
+        config: RunnableConfig | None = None,
+    ) -> str | dict[str, Any] | Command:
+        """Execute delegated task synchronously.
+
+        Args:
+            query (str): Delegated task mission text.
+            prompt (str | None, optional): Additional worker instructions.
+                Defaults to None.
+            allowed_tools (list[str] | None, optional): Narrowing-only allowlist
+                for worker tools. Defaults to None.
+            config (RunnableConfig | None, optional): Runnable execution config.
+                Defaults to None.
+
+        Returns:
+            str | dict[str, Any] | Command: Delegation-style tool output.
+        """
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(self._arun(query=query, prompt=prompt, allowed_tools=allowed_tools, config=config))
+
+        return self._run_arun_in_thread(
+            query=query,
+            prompt=prompt,
+            allowed_tools=allowed_tools,
+            config=config,
+        )
+
+    def _run_arun_in_thread(
+        self,
+        *,
+        query: str,
+        prompt: str | None,
+        allowed_tools: list[str] | None,
+        config: RunnableConfig | None,
+    ) -> str | dict[str, Any] | Command:
+        """Execute async task delegation from sync context with active event loop.
+
+        Args:
+            query (str): Delegated task mission text.
+            prompt (str | None): Optional additional worker instructions.
+            allowed_tools (list[str] | None): Optional narrowing-only allowlist.
+            config (RunnableConfig | None): Runnable execution config.
+
+        Returns:
+            str | dict[str, Any] | Command: Delegation-style tool output.
+
+        Raises:
+            RuntimeError: If thread execution returns no result.
+            Exception: Re-raises exceptions captured from async execution.
+        """
+        result_holder: list[str | dict[str, Any] | Command] = []
+        error_holder: list[Exception] = []
+
+        def _runner() -> None:
+            try:
+                result_holder.append(
+                    asyncio.run(self._arun(query=query, prompt=prompt, allowed_tools=allowed_tools, config=config))
+                )
+            except Exception as exc:
+                error_holder.append(exc)
+
+        thread = threading.Thread(target=_runner, daemon=True)
+        thread.start()
+        thread.join()
+
+        if error_holder:
+            raise error_holder[0]
+        if not result_holder:
+            raise RuntimeError("TaskDelegationTool._run produced no result")
+
+        return result_holder[0]
+
+    async def _arun(
+        self,
+        query: str,
+        prompt: str | None = None,
+        allowed_tools: list[str] | None = None,
+        config: RunnableConfig | None = None,
+    ) -> str | dict[str, Any] | Command:
+        """Execute delegated task asynchronously.
+
+        Args:
+            query (str): Delegated task mission text.
+            prompt (str | None, optional): Additional worker instructions.
+                Defaults to None.
+            allowed_tools (list[str] | None, optional): Narrowing-only allowlist
+                for worker tools. Defaults to None.
+            config (RunnableConfig | None, optional): Runnable execution config.
+                Defaults to None.
+
+        Returns:
+            str | dict[str, Any] | Command: Delegation-style tool output.
+        """
+        result = await self.middleware.run_task(
+            query=query,
+            prompt=prompt,
+            allowed_tools=allowed_tools,
+            config=config,
+            stream_writer=self._resolve_stream_writer(),
+        )
+        if not result.success:
+            return result.error or "task delegation failed"
+
+        if not isinstance(result.worker_response, dict):
+            return result.result
+
+        return self._format_task_response_with_extras(result.result, result.worker_response)
+
+    def _format_task_response_with_extras(
+        self,
+        text_response: str,
+        worker_response: dict[str, Any],
+    ) -> str | Command:
+        """Format worker response into delegation-compatible tool output.
+
+        Args:
+            text_response (str): Worker text output.
+            worker_response (dict[str, Any]): Worker response payload.
+
+        Returns:
+            str | Command: Plain text when no extras are present; otherwise
+            ``Command(update=...)`` with metadata and artifacts.
+        """
+        full_state = worker_response.get("full_final_state")
+        if not isinstance(full_state, dict):
+            return text_response
+
+        metadata = full_state.get("metadata")
+        metadata_update = self.middleware._filter_worker_metadata(metadata) if isinstance(metadata, dict) else {}
+
+        total_usage = full_state.get("total_usage")
+        token_usage = total_usage if isinstance(total_usage, dict) and total_usage else None
+
+        references = full_state.get("references")
+        references_list = references if isinstance(references, list) else []
+
+        artifacts = full_state.get("artifacts")
+        artifacts_list = artifacts if isinstance(artifacts, list) else []
+
+        pii_mapping = extract_pii_mapping_from_agent_response(worker_response)
+
+        has_extras = any((metadata_update, token_usage, references_list, artifacts_list, pii_mapping))
+        if not has_extras:
+            return text_response
+
+        update_dict: dict[str, Any] = {"result": text_response}
+        if metadata_update:
+            update_dict["metadata"] = metadata_update
+        if token_usage:
+            update_dict[USAGE_METADATA_KEY] = token_usage
+        if references_list:
+            update_dict[MetadataFieldKeys.REFERENCES] = references_list
+        if artifacts_list:
+            update_dict["artifacts"] = artifacts_list
+        if pii_mapping:
+            update_dict[MetadataFieldKeys.PII_MAPPING] = pii_mapping
+
+        return Command(update=update_dict)
+
+    @staticmethod
+    def _resolve_stream_writer() -> StreamWriter:
+        """Resolve current LangGraph stream writer with no-op fallback.
+
+        Returns:
+            StreamWriter: Active stream writer or fallback no-op callable.
+        """
+        try:
+            return cast(StreamWriter, get_stream_writer())
+        except Exception:
+            logger.debug("task_delegation_stream_writer_unavailable", exc_info=True)
+
+            def _noop_writer(_: Any) -> None:
+                """Fallback no-op stream writer used outside streaming context."""
+                return None
+
+            return _noop_writer
+
+
+class TaskDelegationMiddleware(AgentMiddleware):
+    """Middleware that injects runtime task delegation support.
+
+    The middleware adds a ``task`` tool and enforces bounded worker delegation.
+    It prevents nested worker delegation, applies queue/concurrency limits, and
+    narrows worker tools when an allowlist is provided.
+    """
+
+    def __init__(
+        self,
+        parent_agent: Any,
+        *,
+        max_concurrent_workers: int = DEFAULT_MAX_CONCURRENT_WORKERS,
+        max_pending_workers: int = DEFAULT_MAX_PENDING_WORKERS,
+        worker_timeout_seconds: float | None = None,
+    ) -> None:
+        """Initialize task delegation middleware.
+
+        Args:
+            parent_agent (Any): Parent agent instance that owns this middleware.
+            max_concurrent_workers (int, optional): Maximum concurrently running
+                workers. Defaults to 5.
+            max_pending_workers (int, optional): Maximum pending worker requests
+                allowed in addition to active workers. Defaults to 20.
+            worker_timeout_seconds (float | None, optional): Parent-owned timeout
+                budget for each dynamic worker run. Defaults to None.
+
+        Raises:
+            ValueError: If concurrency or pending limits are invalid.
+        """
+        if max_concurrent_workers < 1:
+            raise ValueError("max_concurrent_workers must be >= 1")
+        if max_pending_workers < 0:
+            raise ValueError("max_pending_workers must be >= 0")
+
+        self.parent_agent = parent_agent
+        self.max_concurrent_workers = max_concurrent_workers
+        self.max_pending_workers = max_pending_workers
+        self.worker_timeout_seconds = worker_timeout_seconds
+        self.system_prompt_additions = TASK_DELEGATION_SYSTEM_PROMPT
+
+        self._semaphore = asyncio.Semaphore(max_concurrent_workers)
+        self._pending_lock = asyncio.Lock()
+        self._pending_workers = 0
+        self._active_workers = 0
+
+        self.tools: list[BaseTool] = [TaskDelegationTool(middleware=self, metadata=self._build_task_tool_metadata())]
+
+    def _build_task_tool_metadata(self) -> dict[str, Any]:
+        """Build delegation-style timeout metadata for the dynamic task tool.
+
+        Returns:
+            dict[str, Any]: Tool metadata consumed by delegation timeout policy.
+        """
+        metadata: dict[str, Any] = {
+            "is_delegation_tool": True,
+            "delegated_agent_name": f"{self.parent_agent.name}_task_worker",
+            "tool_type": "delegation",
+            "delegation_manager": self.__class__.__name__,
+        }
+
+        if self.worker_timeout_seconds is None:
+            return metadata
+
+        try:
+            timeout_seconds = float(self.worker_timeout_seconds)
+        except (TypeError, ValueError):
+            metadata[DELEGATED_AGENT_TIMEOUT_CONFIG_ERROR_KEY] = INVALID_DELEGATED_AGENT_TIMEOUT_MESSAGE
+            return metadata
+
+        if timeout_seconds <= 0:
+            metadata[DELEGATED_AGENT_TIMEOUT_CONFIG_ERROR_KEY] = INVALID_DELEGATED_AGENT_TIMEOUT_MESSAGE
+            return metadata
+
+        metadata["delegated_agent_timeout_seconds"] = timeout_seconds
+        return metadata
+
+    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """No-op hook before model invocation.
+
+        Args:
+            state (dict[str, Any]): Current graph state.
+
+        Returns:
+            dict[str, Any]: Empty update.
+        """
+        return {}
+
+    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
+        """Pass through model request unchanged.
+
+        Args:
+            request (ModelRequest): Outgoing model request payload.
+            state (dict[str, Any]): Current graph state.
+
+        Returns:
+            ModelRequest: Unmodified request.
+        """
+        return request
+
+    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """No-op hook after model invocation.
+
+        Args:
+            state (dict[str, Any]): Current graph state.
+
+        Returns:
+            dict[str, Any]: Empty update.
+        """
+        return {}
+
+    async def run_task(
+        self,
+        *,
+        query: str,
+        prompt: str | None,
+        allowed_tools: list[str] | None,
+        config: RunnableConfig | None,
+        stream_writer: StreamWriter | None = None,
+    ) -> TaskResult:
+        """Run one delegated worker task with safety constraints.
+
+        Args:
+            query (str): Delegated task mission text.
+            prompt (str | None): Optional additional worker instructions.
+            allowed_tools (list[str] | None): Optional narrowing-only allowlist.
+            config (RunnableConfig | None): Runnable execution config.
+            stream_writer (StreamWriter | None, optional): Parent stream writer
+                receiving forwarded sub-agent events. Defaults to None.
+
+        Returns:
+            TaskResult: Execution result with success flag and error context.
+
+        Raises:
+            None: All internal failures are converted into ``TaskResult`` with
+                ``success=False``.
+        """
+        start_time = time.perf_counter()
+        task_id = uuid.uuid4().hex[:12]
+        queue_reserved = False
+        slot_acquired = False
+        sub_start_token = _TASK_SUB_START_STEP_CVAR.set({})
+
+        try:
+            preflight_failure = await self._validate_task_entry(task_id, start_time)
+            if preflight_failure is not None:
+                return preflight_failure
+            queue_reserved = True
+
+            concurrency_slot = await self._acquire_worker_slot()
+            slot_acquired = True
+
+            execution_plan_or_failure = self._build_worker_execution_plan(
+                task_id=task_id,
+                prompt=prompt,
+                allowed_tools=allowed_tools,
+                config=config,
+                start_time=start_time,
+            )
+            if isinstance(execution_plan_or_failure, TaskResult):
+                return execution_plan_or_failure
+
+            execution_plan = execution_plan_or_failure
+            self._log_worker_spawn(task_id, query, execution_plan, concurrency_slot)
+            return await self._execute_worker_task(
+                task_id=task_id,
+                query=query,
+                execution_plan=execution_plan,
+                stream_writer=stream_writer,
+                start_time=start_time,
+            )
+        finally:
+            if slot_acquired:
+                await self._release_worker_slot()
+            elif queue_reserved:
+                await self._release_pending_slot()
+            _TASK_SUB_START_STEP_CVAR.reset(sub_start_token)
+
+    async def _validate_task_entry(self, task_id: str, start_time: float) -> TaskResult | None:
+        """Validate delegation entry constraints before worker acquisition.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            start_time (float): Perf counter timestamp at task start.
+
+        Returns:
+            TaskResult | None: Failure result when entry checks fail; otherwise
+            ``None``.
+        """
+        current_depth = _DELEGATION_DEPTH_CVAR.get() or 0
+        if current_depth > 0:
+            return self._failure(task_id, WORKER_DELEGATION_NOT_ALLOWED, start_time)
+
+        if not await self._reserve_queue_slot():
+            return self._failure(task_id, WORKER_CONCURRENCY_LIMIT_REACHED, start_time)
+
+        return None
+
+    async def _acquire_worker_slot(self) -> int:
+        """Acquire semaphore and convert one pending slot into active execution.
+
+        Returns:
+            int: Active worker count after acquisition.
+        """
+        semaphore_acquired = False
+        try:
+            await self._semaphore.acquire()
+            semaphore_acquired = True
+            async with self._pending_lock:
+                self._pending_workers = max(0, self._pending_workers - 1)
+                self._active_workers += 1
+                return self._active_workers
+        except asyncio.CancelledError:
+            if semaphore_acquired:
+                self._semaphore.release()
+            raise
+
+    async def _release_pending_slot(self) -> None:
+        """Release one reserved pending slot when worker acquisition is aborted."""
+        async with self._pending_lock:
+            self._pending_workers = max(0, self._pending_workers - 1)
+
+    async def _release_worker_slot(self) -> None:
+        """Release one active worker slot and return semaphore permit."""
+        async with self._pending_lock:
+            self._active_workers = max(0, self._active_workers - 1)
+        self._semaphore.release()
+
+    def _build_worker_execution_plan(
+        self,
+        *,
+        task_id: str,
+        prompt: str | None,
+        allowed_tools: list[str] | None,
+        config: RunnableConfig | None,
+        start_time: float,
+    ) -> WorkerExecutionPlan | TaskResult:
+        """Build deterministic worker execution inputs.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            prompt (str | None): Optional additional worker instructions.
+            allowed_tools (list[str] | None): Optional narrowing-only allowlist.
+            config (RunnableConfig | None): Parent runnable config.
+            start_time (float): Perf counter timestamp at task start.
+
+        Returns:
+            WorkerExecutionPlan | TaskResult: Worker plan on success, otherwise
+            a failure ``TaskResult``.
+        """
+        worker_tools, tools_error = self._resolve_worker_tools(allowed_tools)
+        if tools_error is not None:
+            return self._failure(task_id, tools_error, start_time)
+
+        filesystem_backend, filesystem_tool_names = self._get_parent_filesystem_context()
+        use_shared_filesystem_middleware = filesystem_backend is not None and allowed_tools is None
+        if use_shared_filesystem_middleware and filesystem_tool_names:
+            worker_tools = self._exclude_parent_filesystem_tools(worker_tools, filesystem_tool_names)
+
+        child_budget = self._derive_child_budget()
+        if child_budget <= 0:
+            return self._failure(task_id, INSUFFICIENT_STEP_BUDGET, start_time)
+
+        return WorkerExecutionPlan(
+            worker_tools=worker_tools,
+            filesystem_backend=filesystem_backend,
+            use_shared_filesystem_middleware=use_shared_filesystem_middleware,
+            child_budget=child_budget,
+            worker_instruction=self._build_worker_instruction(prompt),
+            worker_kwargs=self._build_child_run_kwargs(config),
+        )
+
+    @staticmethod
+    def _exclude_parent_filesystem_tools(
+        worker_tools: list[BaseTool], filesystem_tool_names: set[str]
+    ) -> list[BaseTool]:
+        """Remove filesystem tools already provided by shared middleware.
+
+        Args:
+            worker_tools (list[BaseTool]): Candidate worker tools.
+            filesystem_tool_names (set[str]): Parent filesystem tool names.
+
+        Returns:
+            list[BaseTool]: Filtered worker toolset.
+        """
+        return [
+            tool
+            for tool in worker_tools
+            if isinstance(getattr(tool, "name", None), str) and getattr(tool, "name") not in filesystem_tool_names
+        ]
+
+    def _log_worker_spawn(
+        self,
+        task_id: str,
+        query: str,
+        execution_plan: WorkerExecutionPlan,
+        concurrency_slot: int,
+    ) -> None:
+        """Emit deterministic worker spawn telemetry.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            query (str): Delegated task mission text.
+            execution_plan (WorkerExecutionPlan): Planned worker execution inputs.
+            concurrency_slot (int): Active worker slot number.
+        """
+        logger.info(
+            "task_delegation_spawn task_id=%s parent_thread_id=%s tools_count=%s query_length=%s concurrency_slot=%s",
+            task_id,
+            execution_plan.worker_kwargs.get("configurable", {}).get(self.parent_agent.thread_id_key),
+            len(execution_plan.worker_tools),
+            len(query),
+            concurrency_slot,
+        )
+
+    async def _execute_worker_task(
+        self,
+        *,
+        task_id: str,
+        query: str,
+        execution_plan: WorkerExecutionPlan,
+        stream_writer: StreamWriter | None,
+        start_time: float,
+    ) -> TaskResult:
+        """Execute worker agent using a precomputed execution plan.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            query (str): Delegated task mission text.
+            execution_plan (WorkerExecutionPlan): Worker execution inputs.
+            stream_writer (StreamWriter | None): Optional parent stream writer.
+            start_time (float): Perf counter timestamp at task start.
+
+        Returns:
+            TaskResult: Success or failure result.
+        """
+        try:
+            from aip_agents.agent.langgraph_react_agent import LangGraphReactAgent
+
+            worker_model = self.parent_agent.model
+            if worker_model is None:
+                worker_model = self.parent_agent.lm_invoker
+
+            worker = LangGraphReactAgent(
+                name=f"{self.parent_agent.name}_worker_{task_id}",
+                instruction=execution_plan.worker_instruction,
+                model=worker_model,
+                tools=execution_plan.worker_tools,
+                filesystem=(
+                    execution_plan.filesystem_backend if execution_plan.use_shared_filesystem_middleware else None
+                ),
+                task_delegation=False,
+                step_limit_config=StepLimitConfig(max_steps=max(1, execution_plan.child_budget)),
+            )
+            response = await self._run_worker_with_stream_trace(
+                worker,
+                query=query,
+                worker_kwargs=execution_plan.worker_kwargs,
+                stream_writer=stream_writer,
+            )
+            worker_output = response.get("output", "") if isinstance(response, dict) else str(response)
+            result = TaskResult(
+                success=True,
+                result=str(worker_output),
+                error=None,
+                worker_response=response if isinstance(response, dict) else None,
+            )
+
+            logger.debug(
+                "task_delegation_output task_id=%s worker_response=%r",
+                task_id,
+                response,
+            )
+            return self._success(task_id, result, start_time)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("task_delegation_exception task_id=%s error=%s", task_id, str(exc))
+            return self._failure(task_id, str(exc), start_time)
+
+    async def _reserve_queue_slot(self) -> bool:
+        """Reserve a bounded slot for pending work.
+
+        Returns:
+            bool: True when combined active and pending capacity remains
+            available, False when delegation capacity is saturated.
+        """
+        async with self._pending_lock:
+            if self._active_workers + self._pending_workers >= self.max_concurrent_workers + self.max_pending_workers:
+                return False
+            self._pending_workers += 1
+            return True
+
+    def _derive_child_budget(self) -> int:
+        """Compute worker step budget from current delegation context.
+
+        Returns:
+            int: Child step budget. Values less than or equal to zero are
+            considered insufficient for worker execution.
+        """
+        current_depth = _DELEGATION_DEPTH_CVAR.get() or 0
+        current_chain = list(_DELEGATION_CHAIN_CVAR.get() or ())
+        remaining_budget = _REMAINING_STEP_BUDGET_CVAR.get()
+        parent_config = _STEP_LIMIT_CONFIG_CVAR.get()
+
+        manager = StepLimitManager(
+            config=parent_config,
+            initial_delegation_depth=current_depth,
+            parent_step_budget=remaining_budget,
+        )
+        manager.context.delegation_chain = current_chain
+        return manager.get_child_budget()
+
+    def _resolve_worker_tools(self, allowed_tools: list[str] | None) -> tuple[list[BaseTool], str | None]:
+        """Resolve effective worker tools under narrowing constraints.
+
+        Args:
+            allowed_tools (list[str] | None): Optional narrowing-only allowlist.
+
+        Returns:
+            tuple[list[BaseTool], str | None]: A tuple of ``(tools, error)``.
+            ``error`` is ``None`` on success; otherwise it contains a
+            deterministic error message.
+        """
+        candidate_tools = self._collect_candidate_worker_tools()
+
+        tool_by_name = {tool.name: tool for tool in candidate_tools}
+
+        if allowed_tools is None:
+            return candidate_tools, None
+
+        canonical_names, unknown = self._resolve_requested_allowed_tool_names(allowed_tools, tool_by_name)
+
+        if unknown:
+            return [], f"{UNKNOWN_OR_DISALLOWED_TOOLS}: {', '.join(unknown)}"
+
+        return [tool_by_name[name] for name in canonical_names], None
+
+    def _collect_candidate_worker_tools(self) -> list[BaseTool]:
+        """Collect parent tools eligible for worker execution.
+
+        Returns:
+            list[BaseTool]: Parent tools excluding delegation entries.
+        """
+        resolved_tools = getattr(self.parent_agent, "resolved_tools", []) or []
+        candidate_tools: list[BaseTool] = []
+        for tool in resolved_tools:
+            if self._is_worker_eligible_tool(tool):
+                candidate_tools.append(tool)
+        return candidate_tools
+
+    @staticmethod
+    def _is_worker_eligible_tool(tool: Any) -> bool:
+        """Return whether one parent tool is eligible for worker runs.
+
+        Args:
+            tool (Any): Candidate tool.
+
+        Returns:
+            bool: True when the tool is non-delegation with valid name.
+        """
+        tool_name = getattr(tool, "name", "")
+        if not isinstance(tool_name, str) or not tool_name:
+            return False
+        if tool_name == "task" or tool_name.startswith("delegate_to_"):
+            return False
+        tool_metadata = getattr(tool, "metadata", None)
+        return not (isinstance(tool_metadata, dict) and tool_metadata.get("is_delegation_tool") is True)
+
+    def _resolve_requested_allowed_tool_names(
+        self,
+        allowed_tools: list[str],
+        tool_by_name: dict[str, BaseTool],
+    ) -> tuple[list[str], list[str]]:
+        """Resolve requested allowlist names into canonical tool names.
+
+        Args:
+            allowed_tools (list[str]): Requested tool names.
+            tool_by_name (dict[str, BaseTool]): Candidate tools keyed by canonical name.
+
+        Returns:
+            tuple[list[str], list[str]]: Canonical names and unknown names.
+        """
+        canonical_names: list[str] = []
+        unknown: list[str] = []
+        seen: set[str] = set()
+
+        normalized_names = [name for name in allowed_tools if isinstance(name, str) and name]
+        for requested_name in normalized_names:
+            canonical_name = self._normalize_allowed_tool_name(requested_name, tool_by_name)
+            if canonical_name is None:
+                unknown.append(requested_name)
+                continue
+            if canonical_name in seen:
+                continue  # pragma: no cover
+            seen.add(canonical_name)
+            canonical_names.append(canonical_name)
+        return canonical_names, unknown
+
+    @staticmethod
+    def _normalize_allowed_tool_name(requested_name: str, tool_by_name: dict[str, BaseTool]) -> str | None:
+        """Normalize requested tool name against known tool map.
+
+        Args:
+            requested_name (str): Raw tool name requested by caller.
+            tool_by_name (dict[str, BaseTool]): Candidate tools keyed by name.
+
+        Returns:
+            str | None: Canonical tool name or ``None`` when not resolvable.
+        """
+        if requested_name in tool_by_name:
+            return requested_name
+
+        for prefix in ALLOWED_TOOL_NAME_PREFIXES:
+            if requested_name.startswith(prefix):
+                stripped_name = requested_name[len(prefix) :]
+                if stripped_name in tool_by_name:
+                    return stripped_name
+
+        return None
+
+    def _get_parent_filesystem_context(self) -> tuple[Any | None, set[str]]:
+        """Return parent filesystem backend and filesystem tool names.
+
+        Returns:
+            tuple[Any | None, set[str]]: Parent filesystem backend (if any) and
+            the set of filesystem tool names exposed by parent middleware.
+        """
+        backend = getattr(self.parent_agent, "_filesystem_backend", None)
+        middleware = getattr(self.parent_agent, "_filesystem_middleware", None)
+
+        if backend is None or middleware is None:
+            return None, set()
+
+        names: set[str] = set()
+        for tool in getattr(middleware, "tools", []) or []:
+            name = getattr(tool, "name", None)
+            if isinstance(name, str) and name:
+                names.add(name)
+
+        return backend, names
+
+    def _build_worker_instruction(self, prompt: str | None) -> str:
+        """Build worker instruction text.
+
+        Args:
+            prompt (str | None): Optional additional instruction context.
+
+        Returns:
+            str: Worker system instruction.
+        """
+        base = (
+            f"You are a Worker for parent agent '{self.parent_agent.name}'.\n"
+            "Execute exactly one delegated track with bounded tools and limits.\n"
+            "Focus on direct execution and concise, source-backed output for the requested track.\n"
+            "Do not delegate further tasks."
+        )
+        if prompt:
+            return f"{base}\n\nTASK INSTRUCTION CONTEXT:\n{prompt}"
+        return base
+
+    def _build_child_run_kwargs(self, config: RunnableConfig | None) -> dict[str, Any]:
+        """Build worker run kwargs from parent config.
+
+        Args:
+            config (RunnableConfig | None): Parent runnable config.
+
+        Returns:
+            dict[str, Any]: Child run kwargs with ``configurable.thread_id`` and
+            optional metadata subset.
+        """
+        thread_key = getattr(self.parent_agent, "thread_id_key", "thread_id")
+        parent_thread_id = self._resolve_parent_thread_id(config, thread_key)
+        metadata_subset = self._extract_child_metadata_subset(config)
+
+        run_kwargs: dict[str, Any] = {
+            "configurable": {thread_key: parent_thread_id},
+        }
+        if metadata_subset:
+            run_kwargs["metadata"] = metadata_subset
+
+        return run_kwargs
+
+    def _resolve_parent_thread_id(self, config: RunnableConfig | None, thread_key: str) -> str:
+        """Resolve parent thread id from config, parent state, or fallback uuid.
+
+        Args:
+            config (RunnableConfig | None): Parent runnable config.
+            thread_key (str): Configurable thread-id key.
+
+        Returns:
+            str: Parent thread id.
+        """
+        config_thread_id = self._extract_config_thread_id(config, thread_key)
+        if config_thread_id is not None:
+            return config_thread_id
+
+        parent_thread_candidate = getattr(self.parent_agent, thread_key, None)
+        if isinstance(parent_thread_candidate, str) and parent_thread_candidate:
+            return parent_thread_candidate
+        return str(uuid.uuid4())
+
+    @staticmethod
+    def _extract_config_thread_id(config: RunnableConfig | None, thread_key: str) -> str | None:
+        """Extract thread id from runnable config configurable section.
+
+        Args:
+            config (RunnableConfig | None): Parent runnable config.
+            thread_key (str): Thread key to lookup.
+
+        Returns:
+            str | None: Config thread id when present and non-empty.
+        """
+        if not isinstance(config, dict):
+            return None
+        configurable = config.get("configurable")
+        if not isinstance(configurable, dict):
+            return None  # pragma: no cover
+        candidate = configurable.get(thread_key)
+        if isinstance(candidate, str) and candidate:
+            return candidate
+        return None  # pragma: no cover
+
+    @staticmethod
+    def _extract_child_metadata_subset(config: RunnableConfig | None) -> dict[str, Any]:
+        """Extract safe metadata keys forwarded to worker run kwargs.
+
+        Args:
+            config (RunnableConfig | None): Parent runnable config.
+
+        Returns:
+            dict[str, Any]: Metadata subset containing trace/request/run ids.
+        """
+        if not isinstance(config, dict):
+            return {}
+        metadata = config.get("metadata")
+        if not isinstance(metadata, dict):
+            return {}
+
+        metadata_subset: dict[str, Any] = {}
+        for key in ("trace_id", "request_id", "run_id"):
+            value = metadata.get(key)
+            if value is not None:
+                metadata_subset[key] = value
+        return metadata_subset
+
+    @staticmethod
+    def _filter_worker_metadata(metadata: dict[str, Any]) -> dict[str, Any]:
+        """Filter worker metadata keys before propagating to parent update.
+
+        Args:
+            metadata (dict[str, Any]): Raw worker metadata dictionary.
+
+        Returns:
+            dict[str, Any]: Filtered metadata preserving safe linkage fields.
+        """
+        filtered: dict[str, Any] = {
+            key: value
+            for key, value in metadata.items()
+            if not any(key.startswith(prefix) for prefix in METADATA_INTERNAL_PREFIXES)
+            and key not in METADATA_INTERNAL_KEYS
+        }
+        previous_step_ids = metadata.get("previous_step_ids")
+        if isinstance(previous_step_ids, list) and previous_step_ids:
+            filtered["previous_step_ids"] = list(previous_step_ids)
+        step_id = metadata.get("step_id")
+        if step_id:
+            filtered.setdefault("step_id", step_id)
+        return filtered
+
+    def _success(self, task_id: str, result: TaskResult, start_time: float) -> TaskResult:
+        """Log and return a successful task result.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            result (TaskResult): Successful result payload.
+            start_time (float): Perf counter timestamp at task start.
+
+        Returns:
+            TaskResult: Unmodified successful result.
+        """
+        duration_ms = int((time.perf_counter() - start_time) * 1000)
+        logger.info(
+            "task_delegation_result task_id=%s success=%s duration_ms=%s",
+            task_id,
+            result.success,
+            duration_ms,
+        )
+        return result
+
+    def _failure(self, task_id: str, error: str, start_time: float) -> TaskResult:
+        """Log and return a failure task result.
+
+        Args:
+            task_id (str): Delegation task identifier.
+            error (str): Failure reason text.
+            start_time (float): Perf counter timestamp at task start.
+
+        Returns:
+            TaskResult: Failure result with bounded error text.
+        """
+        bounded_error = error[:MAX_ERROR_MESSAGE_LENGTH]
+        duration_ms = int((time.perf_counter() - start_time) * 1000)
+        logger.error(
+            "task_delegation_result task_id=%s success=%s duration_ms=%s error=%s",
+            task_id,
+            False,
+            duration_ms,
+            bounded_error,
+        )
+        return TaskResult(success=False, result="", error=bounded_error)
+
+    async def _run_worker_with_stream_trace(
+        self,
+        worker: Any,
+        *,
+        query: str,
+        worker_kwargs: dict[str, Any],
+        stream_writer: StreamWriter | None,
+    ) -> dict[str, Any]:
+        """Execute worker stream and collect normalized final response payload.
+
+        Args:
+            worker (Any): Worker agent exposing ``arun_a2a_stream``.
+            query (str): Delegated task mission text.
+            worker_kwargs (dict[str, Any]): Child runnable kwargs.
+            stream_writer (StreamWriter | None): Optional parent stream writer.
+
+        Returns:
+            dict[str, Any]: Worker response with ``output`` and ``full_final_state``.
+
+        Raises:
+            RuntimeError: If worker stream API is missing, invalid, or lacks
+                ``final_response`` event.
+        """
+        stream_method = getattr(worker, "arun_a2a_stream", None)
+        if not callable(stream_method):
+            raise RuntimeError("Worker does not support arun_a2a_stream; task delegation requires stream mode")
+
+        stream = stream_method(query, **worker_kwargs)
+        if not hasattr(stream, "__aiter__"):
+            raise RuntimeError("Worker stream is not async-iterable; task delegation requires async stream mode")
+        async_stream = cast(AsyncIterator[Any], stream)
+
+        stream_records: list[dict[str, Any]] = []
+        final_event: dict[str, Any] | None = None
+        parent_thread_id = self._extract_parent_thread_id(worker_kwargs)
+
+        async for chunk in async_stream:
+            if not isinstance(chunk, dict):
+                continue
+            normalized = self._normalize_worker_stream_chunk(chunk)
+            stream_records.append(normalized)
+            self._forward_sub_agent_chunk(normalized, stream_writer, parent_thread_id)
+
+            event_type = self._normalize_event_type(normalized.get("event_type"))
+            if event_type == EVENT_TYPE_FINAL_RESPONSE:
+                final_event = normalized
+
+        if not isinstance(final_event, dict):
+            raise RuntimeError(
+                "No final_response event captured from worker stream (likely model/context/tool execution failure)"
+            )
+
+        response = self._build_worker_response_from_stream_final(final_event, stream_records)
+        return response
+
+    def _forward_sub_agent_chunk(
+        self,
+        chunk: dict[str, Any],
+        writer: StreamWriter | None,
+        parent_thread_id: str | None,
+    ) -> None:
+        """Forward one normalized sub-agent chunk to the parent stream.
+
+        Args:
+            chunk (dict[str, Any]): Normalized worker stream chunk.
+            writer (StreamWriter | None): Parent stream writer.
+            parent_thread_id (str | None): Parent thread identifier.
+        """
+        if writer is None:
+            return
+
+        event_type = self._normalize_event_type(chunk.get("event_type"))
+        if event_type == EVENT_TYPE_TOOL_CALL:
+            self._forward_tool_call_event(chunk, writer, parent_thread_id)
+            return
+        if event_type == EVENT_TYPE_TOOL_RESULT:
+            self._forward_tool_result_event(chunk, writer)
+            return
+
+        marked_chunk = dict(chunk)
+        metadata = chunk.get("metadata")
+        marked_metadata = dict(metadata) if isinstance(metadata, dict) else {}
+        marked_metadata[SUB_AGENT_EVENT_METADATA_KEY] = True
+        marked_chunk["metadata"] = marked_metadata
+        normalized_chunk = self._normalize_forwarded_sub_agent_chunk(marked_chunk)
+        writer(normalized_chunk)
+
+    @staticmethod
+    def _extract_parent_thread_id(worker_kwargs: dict[str, Any]) -> str | None:
+        """Extract parent thread id from child runnable kwargs.
+
+        Args:
+            worker_kwargs (dict[str, Any]): Child runnable kwargs.
+
+        Returns:
+            str | None: Parent thread id when present.
+        """
+        configurable = worker_kwargs.get("configurable") if isinstance(worker_kwargs.get("configurable"), dict) else {}
+        for value in configurable.values():
+            if isinstance(value, str) and value:
+                return value
+        return None
+
+    def _forward_tool_call_event(
+        self,
+        chunk: dict[str, Any],
+        writer: StreamWriter,
+        parent_thread_id: str | None,
+    ) -> None:
+        """Forward tool-call event using delegation-compatible envelope.
+
+        Args:
+            chunk (dict[str, Any]): Normalized stream chunk.
+            writer (StreamWriter): Parent stream writer.
+            parent_thread_id (str | None): Parent thread identifier.
+        """
+        tool_info = chunk.get("tool_info") if isinstance(chunk.get("tool_info"), dict) else {}
+        message = self._create_tool_call_message(tool_info)
+        metadata = self._prepare_tool_call_metadata(chunk, tool_info, parent_thread_id)
+
+        a2a_event: dict[str, Any] = {
+            "event_type": EVENT_TYPE_TOOL_CALL,
+            "content": message,
+            "metadata": metadata,
+            "tool_info": tool_info,
+            "is_final": False,
+            "artifacts": chunk.get("artifacts"),
+            MetadataFieldKeys.REFERENCES: chunk.get(MetadataFieldKeys.REFERENCES),
+            STEP_USAGE_KEY: chunk.get(STEP_USAGE_KEY),
+            TOTAL_USAGE_KEY: chunk.get(TOTAL_USAGE_KEY),
+            MODEL_USAGE_DELTA_KEY: chunk.get(MODEL_USAGE_DELTA_KEY),
+            MODEL_USAGE_KEY: chunk.get(MODEL_USAGE_KEY),
+        }
+        writer(a2a_event)
+
+    def _prepare_tool_call_metadata(
+        self,
+        chunk: dict[str, Any],
+        tool_info: dict[str, Any],
+        parent_thread_id: str | None,
+    ) -> dict[str, Any]:
+        """Prepare tool-call metadata with linkage and generated step id.
+
+        Args:
+            chunk (dict[str, Any]): Normalized stream chunk.
+            tool_info (dict[str, Any]): Tool info payload.
+            parent_thread_id (str | None): Parent thread identifier.
+
+        Returns:
+            dict[str, Any]: Enriched metadata for forwarded event.
+        """
+        metadata = dict(chunk.get("metadata") or {})
+        metadata[SUB_AGENT_EVENT_METADATA_KEY] = True
+        self._ensure_step_id_in_metadata(metadata, tool_info)
+
+        agent_name = metadata.get("agent_name")
+        if isinstance(agent_name, str) and agent_name:
+            self._setup_agent_linkage(metadata, agent_name, tool_info, parent_thread_id)
+        else:
+            self._handle_missing_agent_name(metadata)
+        return metadata
+
+    def _ensure_step_id_in_metadata(self, metadata: dict[str, Any], tool_info: dict[str, Any]) -> None:
+        """Ensure metadata has ``step_id``, generating one when missing.
+
+        Args:
+            metadata (dict[str, Any]): Event metadata to mutate.
+            tool_info (dict[str, Any]): Tool info for deterministic id generation.
+        """
+        if "step_id" in metadata:
+            return
+        raw_agent_name = metadata.get("agent_name")
+        agent_name_for_id = raw_agent_name if isinstance(raw_agent_name, str) and raw_agent_name else "anon_agent"
+        metadata["step_id"] = self._generate_delegation_step_id(EVENT_TYPE_TOOL_CALL, agent_name_for_id, tool_info)
+
+    def _generate_delegation_step_id(self, event_type: str, agent_name: str, tool_info: dict[str, Any]) -> str:
+        """Generate deterministic fallback step identifiers for delegated events.
+
+        Args:
+            event_type (str): Event type name.
+            agent_name (str): Sub-agent name.
+            tool_info (dict[str, Any]): Tool info payload.
+
+        Returns:
+            str: Generated step id.
+        """
+        try:
+            counter = get_next_step_number()
+            if event_type == EVENT_TYPE_TOOL_CALL:
+                candidate = tool_info.get("tool_calls")
+                if isinstance(candidate, list) and candidate:
+                    first_call = candidate[0] if isinstance(candidate[0], dict) else {}
+                    tool_name = first_call.get("name") if isinstance(first_call.get("name"), str) else "tool"
+                    return f"{tool_name}_{counter:03d}"
+            if event_type == EVENT_TYPE_TOOL_RESULT:
+                tool_name = tool_info.get("name") if isinstance(tool_info.get("name"), str) else "result"
+                return f"{tool_name}_{counter:03d}"
+            fallback_prefix = self._build_fallback_prefix(agent_name)
+            return f"{fallback_prefix}_{event_type}_{counter:03d}"
+        except Exception:
+            return f"task_{uuid.uuid4().hex[:8]}"
+
+    @staticmethod
+    def _build_fallback_prefix(agent_name: str) -> str:
+        """Build sanitized fallback prefix from agent name.
+
+        Args:
+            agent_name (str): Agent name candidate.
+
+        Returns:
+            str: Prefix used for generated fallback ids.
+        """
+        if not agent_name:
+            return "task"
+        sanitized = "".join(ch for ch in agent_name.lower() if ch.isalnum())[:8]
+        return f"task_{sanitized}" if sanitized else "task"
+
+    def _setup_agent_linkage(
+        self,
+        metadata: dict[str, Any],
+        agent_name: str,
+        tool_info: dict[str, Any],
+        parent_thread_id: str | None,
+    ) -> None:
+        """Attach parent/sub-agent linkage fields for tool-call events.
+
+        Args:
+            metadata (dict[str, Any]): Metadata to mutate.
+            agent_name (str): Sub-agent name.
+            tool_info (dict[str, Any]): Tool info payload.
+            parent_thread_id (str | None): Parent thread identifier.
+        """
+        parent_step_id = self._get_parent_step_id(tool_info, parent_thread_id)
+        metadata["previous_step_ids"] = [parent_step_id] if parent_step_id else []
+
+        sub_start_map = _TASK_SUB_START_STEP_CVAR.get() or {}
+        step_id = metadata.get("step_id")
+        if isinstance(step_id, str) and step_id:
+            sub_start_map[agent_name] = step_id
+            _TASK_SUB_START_STEP_CVAR.set(sub_start_map)
+
+    def _get_parent_step_id(self, tool_info: dict[str, Any], parent_thread_id: str | None) -> str | None:
+        """Resolve parent step id from tool parent map when available.
+
+        Args:
+            tool_info (dict[str, Any]): Tool info payload.
+            parent_thread_id (str | None): Parent thread identifier.
+
+        Returns:
+            str | None: Parent step id when found.
+        """
+        if (
+            self.parent_agent is None
+            or not hasattr(self.parent_agent, "_tool_parent_map_by_thread")
+            or not parent_thread_id
+        ):
+            return None
+        return self._lookup_parent_step_from_agent(tool_info, parent_thread_id)
+
+    def _lookup_parent_step_from_agent(self, tool_info: dict[str, Any], parent_thread_id: str) -> str | None:
+        """Lookup parent step id using parent agent thread-scoped map.
+
+        Args:
+            tool_info (dict[str, Any]): Tool info payload.
+            parent_thread_id (str): Parent thread identifier.
+
+        Returns:
+            str | None: Mapped parent step id when found.
+        """
+        try:
+            parent_map = self.parent_agent._tool_parent_map_by_thread.get(parent_thread_id, {})
+            if not isinstance(parent_map, dict):
+                return None
+
+            tool_call_id = tool_info.get("id")
+            if not isinstance(tool_call_id, str) and isinstance(tool_info.get("tool_calls"), list):
+                for call in tool_info.get("tool_calls", []):
+                    if isinstance(call, dict) and isinstance(call.get("id"), str):
+                        tool_call_id = call.get("id")
+                        break
+
+            if isinstance(tool_call_id, str) and tool_call_id:
+                parent_step = parent_map.get(str(tool_call_id))
+                if isinstance(parent_step, str) and parent_step:
+                    return parent_step
+        except Exception:
+            logger.debug("task_delegation_parent_step_lookup_failed", exc_info=True)
+        return None
+
+    @staticmethod
+    def _handle_missing_agent_name(metadata: dict[str, Any]) -> None:
+        """Mark metadata for missing agent-name linkage scenario.
+
+        Args:
+            metadata (dict[str, Any]): Metadata to mutate.
+        """
+        metadata["previous_step_ids"] = []
+        metadata["agent_name_missing"] = True
+
+    def _forward_tool_result_event(self, chunk: dict[str, Any], writer: StreamWriter) -> None:
+        """Forward tool-result event using delegation-compatible envelope.
+
+        Args:
+            chunk (dict[str, Any]): Normalized stream chunk.
+            writer (StreamWriter): Parent stream writer.
+        """
+        tool_info = chunk.get("tool_info") if isinstance(chunk.get("tool_info"), dict) else {}
+        deduped_tool_names = self._extract_tool_result_names(tool_info)
+        metadata = self._build_tool_result_metadata(chunk)
+
+        content = self._build_completion_content(deduped_tool_names)
+        a2a_event: dict[str, Any] = {
+            "event_type": EVENT_TYPE_TOOL_RESULT,
+            "content": content,
+            "metadata": metadata,
+            "tool_info": tool_info,
+            "is_final": False,
+            "artifacts": chunk.get("artifacts"),
+            MetadataFieldKeys.REFERENCES: chunk.get(MetadataFieldKeys.REFERENCES),
+            STEP_USAGE_KEY: chunk.get(STEP_USAGE_KEY),
+            TOTAL_USAGE_KEY: chunk.get(TOTAL_USAGE_KEY),
+            MODEL_USAGE_DELTA_KEY: chunk.get(MODEL_USAGE_DELTA_KEY),
+            MODEL_USAGE_KEY: chunk.get(MODEL_USAGE_KEY),
+        }
+        writer(a2a_event)
+
+    @staticmethod
+    def _extract_tool_result_names(tool_info: dict[str, Any]) -> list[str]:
+        """Extract deterministic tool-name list from tool-result payload.
+
+        Args:
+            tool_info (dict[str, Any]): Tool result payload.
+
+        Returns:
+            list[str]: Deduplicated non-empty tool names.
+        """
+        primary_name = tool_info.get("name")
+        if isinstance(primary_name, str) and primary_name:
+            return [primary_name]
+
+        tool_calls = tool_info.get("tool_calls")
+        if not isinstance(tool_calls, list):
+            return ["unknown_tool"]  # pragma: no cover
+
+        tool_names: list[str] = []
+        for call in tool_calls:
+            if not isinstance(call, dict):
+                continue
+            name = call.get("name")
+            if isinstance(name, str) and name:
+                tool_names.append(name)
+
+        deduped_names = list(dict.fromkeys(tool_names))
+        return deduped_names or ["unknown_tool"]
+
+    def _build_tool_result_metadata(self, chunk: dict[str, Any]) -> dict[str, Any]:
+        """Build delegated metadata envelope for forwarded tool-result event.
+
+        Args:
+            chunk (dict[str, Any]): Normalized worker chunk.
+
+        Returns:
+            dict[str, Any]: Metadata with sub-agent linkage markers.
+        """
+        metadata = dict(chunk.get("metadata") or {})
+        metadata[SUB_AGENT_EVENT_METADATA_KEY] = True
+
+        agent_name = metadata.get("agent_name")
+        if not isinstance(agent_name, str) or not agent_name:
+            self._handle_missing_agent_name(metadata)
+            return metadata
+
+        sub_start_map = _TASK_SUB_START_STEP_CVAR.get() or {}
+        start_step_id = sub_start_map.get(agent_name)
+        metadata["previous_step_ids"] = [start_step_id] if isinstance(start_step_id, str) and start_step_id else []
+        return metadata
+
+    def _build_completion_content(self, tool_names: list[str]) -> str:
+        """Build parent-facing completion content for tool-result events.
+
+        Args:
+            tool_names (list[str]): Completed tool names.
+
+        Returns:
+            str: Completion text matching delegation manager style.
+        """
+        if self.parent_agent and hasattr(self.parent_agent, "_get_tool_completion_content"):
+            try:
+                return self.parent_agent._get_tool_completion_content(tool_names)
+            except Exception:
+                logger.debug("task_delegation_parent_completion_format_failed", exc_info=True)
+
+        has_delegation = any(name.startswith("delegate_to") for name in tool_names)
+        prefix = "Completed sub-agents:" if has_delegation else "Completed tools:"
+        return f"{prefix} {', '.join(tool_names)}"
+
+    @staticmethod
+    def _create_tool_call_message(tool_info: dict[str, Any]) -> str:
+        """Build human-readable message for forwarded tool-call events.
+
+        Args:
+            tool_info (dict[str, Any]): Tool info payload.
+
+        Returns:
+            str: Formatted message with tool names.
+        """
+        tool_calls = tool_info.get("tool_calls", [])
+        tool_names = [tc.get("name", "unknown") for tc in tool_calls if isinstance(tc, dict)]
+        if not tool_names:
+            tool_names = ["unknown"]
+        return f"Processing with tools: {', '.join(tool_names)}"
+
+    def _normalize_forwarded_sub_agent_chunk(self, chunk: dict[str, Any]) -> dict[str, Any]:
+        """Normalize forwarded sub-agent chunk for parent stream safety.
+
+        Args:
+            chunk (dict[str, Any]): Marked sub-agent chunk.
+
+        Returns:
+            dict[str, Any]: Normalized chunk with terminal remapping applied.
+        """
+        normalized_chunk = dict(chunk)
+        if normalized_chunk.get("is_final") is True:
+            normalized_chunk["is_final"] = False
+        normalized_chunk.pop("final", None)
+
+        event_type = self._normalize_event_type(normalized_chunk.get("event_type"))
+        remapped_event_type = SUB_AGENT_TERMINAL_EVENT_REMAP.get(event_type)
+        if remapped_event_type is not None:
+            normalized_chunk["event_type"] = remapped_event_type
+        return normalized_chunk
+
+    @staticmethod
+    def _build_worker_response_from_stream_final(
+        final_event: dict[str, Any],
+        stream_records: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Build canonical worker response payload from final stream event.
+
+        Args:
+            final_event (dict[str, Any]): Final stream event payload.
+            stream_records (list[dict[str, Any]]): Normalized stream records.
+
+        Returns:
+            dict[str, Any]: Canonical worker response with ``full_final_state``.
+        """
+        final_metadata = final_event.get("metadata") if isinstance(final_event.get("metadata"), dict) else {}
+        merged_metadata = dict(final_metadata)
+
+        timeout_delegation = TaskDelegationMiddleware._extract_timeout_delegation_metadata(stream_records)
+        if timeout_delegation is not None:
+            existing_delegation = merged_metadata.get(DELEGATION_METADATA_KEY)
+            if isinstance(existing_delegation, dict):
+                merged_delegation = dict(existing_delegation)  # pragma: no cover
+                merged_delegation.update(timeout_delegation)  # pragma: no cover
+                merged_metadata[DELEGATION_METADATA_KEY] = merged_delegation  # pragma: no cover
+            else:
+                merged_metadata[DELEGATION_METADATA_KEY] = timeout_delegation
+
+        return {
+            "output": str(final_event.get("content", "")),
+            "full_final_state": {
+                "total_usage": final_event.get("total_usage")
+                if isinstance(final_event.get("total_usage"), dict)
+                else {},
+                "references": final_event.get("references") if isinstance(final_event.get("references"), list) else [],
+                "metadata": merged_metadata,
+                "stream_trace": stream_records,
+                "artifacts": final_event.get("artifacts") if isinstance(final_event.get("artifacts"), list) else [],
+            },
+        }
+
+    @staticmethod
+    def _extract_timeout_delegation_metadata(stream_records: list[dict[str, Any]]) -> dict[str, Any] | None:
+        """Extract timeout delegation metadata from normalized worker stream records."""
+        timeout_execution = TaskDelegationMiddleware._extract_timeout_tool_execution(stream_records)
+        if timeout_execution is None:
+            return None
+
+        return {
+            "status": DELEGATION_FAILED_STATUS,
+            "reason": DELEGATION_TOOL_TIMEOUT_REASON,
+            "tool_execution": timeout_execution,
+        }
+
+    @staticmethod
+    def _extract_timeout_tool_execution(stream_records: list[dict[str, Any]]) -> dict[str, Any] | None:
+        """Return the last timeout-marked tool_execution payload from stream records."""
+        for record in reversed(stream_records):
+            if not isinstance(record, dict):
+                continue  # pragma: no cover
+            if record.get("event_type") != EVENT_TYPE_TOOL_RESULT:
+                continue
+
+            metadata = record.get("metadata")
+            if not isinstance(metadata, dict):
+                continue  # pragma: no cover
+
+            tool_execution = metadata.get("tool_execution")
+            if not isinstance(tool_execution, dict):
+                continue
+            if tool_execution.get("status") != "timeout":
+                continue  # pragma: no cover
+
+            return dict(tool_execution)
+
+        return None
+
+    @staticmethod
+    def _normalize_event_type(raw: Any) -> str:
+        """Normalize event type values from enum or arbitrary objects.
+
+        Args:
+            raw (Any): Raw event type value.
+
+        Returns:
+            str: Normalized event type string.
+        """
+        if hasattr(raw, "value"):
+            return str(raw.value)
+        if isinstance(raw, str):
+            return raw
+        return str(raw)
+
+    def _normalize_worker_stream_chunk(self, chunk: dict[str, Any]) -> dict[str, Any]:
+        """Normalize raw worker stream chunk into stable internal structure.
+
+        Args:
+            chunk (dict[str, Any]): Raw worker stream chunk.
+
+        Returns:
+            dict[str, Any]: Normalized stream chunk.
+        """
+        event_type = self._normalize_event_type(chunk.get("event_type"))
+        metadata = chunk.get("metadata") if isinstance(chunk.get("metadata"), dict) else {}
+        tool_info = chunk.get("tool_info") if isinstance(chunk.get("tool_info"), dict) else {}
+        record: dict[str, Any] = {
+            "event_type": event_type,
+            "step_id": metadata.get("step_id"),
+            "previous_step_ids": metadata.get("previous_step_ids"),
+            "is_final": bool(chunk.get("is_final")),
+            "content": chunk.get("content", ""),
+            "metadata": metadata,
+            "tool_info": tool_info,
+            "step_usage": chunk.get("step_usage") if isinstance(chunk.get("step_usage"), dict) else None,
+            "total_usage": chunk.get("total_usage") if isinstance(chunk.get("total_usage"), dict) else None,
+            MODEL_USAGE_DELTA_KEY: chunk.get(MODEL_USAGE_DELTA_KEY)
+            if isinstance(chunk.get(MODEL_USAGE_DELTA_KEY), dict)
+            else None,
+            MODEL_USAGE_KEY: chunk.get(MODEL_USAGE_KEY) if isinstance(chunk.get(MODEL_USAGE_KEY), list) else None,
+            "references": chunk.get("references") if isinstance(chunk.get("references"), list) else None,
+            "artifacts": chunk.get("artifacts") if isinstance(chunk.get("artifacts"), list) else None,
+        }
+
+        if event_type == EVENT_TYPE_TOOL_CALL:
+            tool_calls: list[dict[str, Any]] = (
+                [tc for tc in tool_info.get("tool_calls", []) if isinstance(tc, dict)]
+                if isinstance(tool_info.get("tool_calls"), list)
+                else []
+            )
+            record["tool_calls"] = [
+                {
+                    "id": tc.get("id"),
+                    "name": tc.get("name"),
+                    "args": tc.get("args"),
+                }
+                for tc in tool_calls
+            ]
+        elif event_type == EVENT_TYPE_TOOL_RESULT:
+            record["tool_result"] = {
+                "id": tool_info.get("id"),
+                "name": tool_info.get("name"),
+                "execution_time": tool_info.get("execution_time"),
+                "args": tool_info.get("args"),
+                "output": tool_info.get("output"),
+            }
+
+        return record