"""delegate 工具:schema 载体。

真正的执行走 AgentLoop 内建拦截(`_run_delegate`,§8.11)—— 因为要读"活的"
llm/caps(skill 热切会在运行中改)、executor、cancel_check,这些都在 loop 实例上。
本类只负责把 schema 暴露给 LLM;`execute` 是防御性 no-op(loop 拦截后正常到不了)。
子循环里 FilteredExecutor 不含本工具 → schema 不暴露、无法递归调用。
"""
from __future__ import annotations

from .base import Tool


class DelegateTool(Tool):
    name = "delegate"
    description = (
        "把一段『查资料 / 读文件 / 收集数据』的检索工作委派给一个隔离的子助手:它在全新的"
        "空上下文里用只读 / 检索工具(搜索、抓取、读文件、查 Materials Project)干活,"
        "只把简明结论返回给你,大量中间检索数据不会灌进你的上下文。"
        "适用:文献综述式地毯搜索、批量读多个文件后只要结论、扫一批数据得汇总。"
        "不适用:需要写文件 / 改文件 / 跑代码 / shell 的工作(子助手没有这些工具)。"
        "instruction 要写清目标 + 必要的路径 / 关键词 / 约束——子助手看不到你当前对话,全靠这段说明。"
    )
    parameters = {
        "type": "object",
        "properties": {
            "instruction": {
                "type": "string",
                "description": (
                    "交给检索子助手的完整任务说明:要查什么、已知的文件路径 / 关键词 / 约束、"
                    "期望的结论形态。子助手是空上下文,需要的信息都写进来。"
                ),
            },
        },
        "required": ["instruction"],
    }

    def execute(self, instruction: str = "") -> str:
        return "[Error] delegate 只能在 agent 主循环内运行(loop 拦截未启用)。"