Subagent：上下文隔离的正确姿势

import uuid

# 模拟 QueryChainTracking
def make_tracking(parent_tracking=None):
    """生成调用链追踪信息"""
    if parent_tracking:
        return {
            "chain_id": parent_tracking["chain_id"],
            "depth": parent_tracking["depth"] + 1
        }
    return {"chain_id": str(uuid.uuid4()), "depth": 0}

def run_subagent(prompt: str, parent_tracking=None,
                 model=None) -> str:
    """启动子 Agent，返回最终摘要文本

    与 Claude Code 的关键对应：
    - parent_tracking → QueryChainTracking（支持嵌套）
    - model → AgentTool 的 model 参数
    - CHILD_TOOLS 包含 task → 允许递归（靠 depth 追踪）
    """
    tracking = make_tracking(parent_tracking)
    use_model = model or MODEL

    sub_messages = [{"role": "user", "content": prompt}]

    for _ in range(30):  # 安全限制
        response = client.messages.create(
            model=use_model,
            system=SUBAGENT_SYSTEM,
            messages=sub_messages,
            tools=PARENT_TOOLS,  # 子 Agent 也有 task 工具，允许嵌套
            max_tokens=8000,
        )
        sub_messages.append({"role": "assistant", "content": response.content})

        if response.stop_reason != "tool_use":
            break

        results = []
        for block in response.content:
            if block.type == "tool_use":
                if block.name == "task":
                    # 递归调用子 Agent，传递 tracking
                    output = run_subagent(
                        block.input["prompt"],
                        parent_tracking=tracking,
                        model=block.input.get("model"),
                    )
                else:
                    handler = TOOL_HANDLERS.get(block.name)
                    output = (handler(**block.input) if handler
                              else f"Unknown tool: {block.name}")
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(output)[:50000]
                })
        sub_messages.append({"role": "user", "content": results})

    return "".join(
        b.text for b in response.content if hasattr(b, "text")
    ) or "(no summary)"

PARENT_TOOLS = BASE_TOOLS + [
    {
        "name": "task",
        "description": (
            "启动子 Agent 处理子任务，返回摘要。"
            "子 Agent 有独立的上下文和完整的工具能力（包括再次调用 task）。"
        ),
        "input_schema": {
            "type": "object",
            "properties": {
                "description": {
                    "type": "string",
                    "description": "3-5 个词的任务简述"
                },
                "prompt": {
                    "type": "string",
                    "description": "子任务的完整描述，需自包含"
                },
                "model": {
                    "type": "string",
                    "enum": ["sonnet", "opus", "haiku"],
                    "description": "可选的模型覆盖"
                }
            },
            "required": ["description", "prompt"]
        }
    }
]

TOOL_HANDLERS["task"] = lambda **kw: run_subagent(
    kw["prompt"], model=kw.get("model")
)

# 错误：子 Agent 不知道"这个项目"是什么
"找出这个项目使用的测试框架"

# 正确：自包含的任务描述
"读取 /workspace/learn-claude-code 项目根目录下的文件，
 找出使用的测试框架（查看 requirements.txt、setup.py、pyproject.toml 等），
 返回测试框架名称和版本。"