Harness实战：Subagent——大任务拆小，上下文隔离

第1轮: bash → cat package.json          (输出: 200行JSON)
第2轮: bash → cat jest.config.js        (输出: 30行配置)
第3轮: bash → cat tsconfig.json         (输出: 50行JSON)
第4轮: bash → ls tests/                 (输出: 15行文件列表)
第5轮: bash → head -20 tests/setup.ts   (输出: 20行代码)

┌──────────────────────────────────────────────────────┐
│  父 Agent (messages[])                                │
│                                                       │
│  User: "分析技术栈，然后更新 README"                  │
│  Assistant: 我先调研技术栈 → tool_use: task            │
│                                                       │
│  ┌────────────────────────────────────────────────┐   │
│  │  子 Agent (sub_messages[] — 独立，用完即弃)    │   │
│  │                                                │   │
│  │  bash → cat package.json         (200行)       │   │
│  │  bash → cat jest.config.js       (30行)        │   │
│  │  bash → ls src/                  (20行)        │   │
│  │                                                │   │
│  │  最终回复: "TypeScript 5.3 + React 18 + Jest"  │   │
│  │  ★ 整个 sub_messages[] 在这里丢弃              │   │
│  └────────────────────────────────────────────────┘   │
│                                                       │
│  tool_result: "TypeScript 5.3 + React 18 + Jest"      │
│  Assistant: 好的，现在编辑 README...（继续干净工作）   │
└──────────────────────────────────────────────────────┘

TASK_TOOL = {
    "name": "task",
    "description": (
        "Run a subtask in an isolated context. "
        "The subtask gets its own clean message history, "
        "only the final text summary is returned. "
        "Use for research, analysis, or any work whose "
        "intermediate output the parent does not need."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "prompt": {
                "type": "string",
                "description": "Task description for the subagent",
            }
        },
        "required": ["prompt"],
    },
}

MAX_SUBAGENT_TURNS = 30
SUBAGENT_SYSTEM = f"""You are a focused agent at {WORKDIR}.
Complete the given task, then provide a clear summary of results.
Do not ask for clarification — work with what you have."""


def extract_text(response) -> str:
    """从响应中提取纯文本，丢弃工具调用块。"""
    parts = [b.text for b in response.content if hasattr(b, "text")]
    return "\n".join(parts) if parts else "(subagent produced no text output)"


def run_subagent(prompt: str) -> str:
    """在隔离上下文中执行子任务，仅返回最终文本。"""
    sub_messages = [{"role": "user", "content": prompt}]

    for _turn in range(MAX_SUBAGENT_TURNS):
        response = client.messages.create(
            model=MODEL,
            system=SUBAGENT_SYSTEM,
            messages=sub_messages,
            tools=BASE_TOOLS,          # ★ 没有 task 工具，不能递归
            max_tokens=4096,
        )
        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":
                handler = BASE_HANDLERS.get(block.name)
                output = handler(**block.input) if handler else f"Unknown: {block.name}"
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        sub_messages.append({"role": "user", "content": results})

    # ★ 关键：只提取最终文本，sub_messages 整个丢弃
    return extract_text(response)

# 基础工具（子 Agent 用这个，不含 task）
BASE_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
}

# 父 Agent 的工具列表和 dispatch（含 task）
TOOLS = BASE_TOOLS + [TASK_TOOL]
TOOL_HANDLERS = {
    **BASE_HANDLERS,
    "task": lambda **kw: run_subagent(kw["prompt"]),
}

# 阶段 2：执行时提示模型可以用 task 工具委派
messages.append({
    "role": "user",
    "content": f"{feedback} Now execute it step by step. "
               f"Use the `task` tool to delegate independent subtasks."
})
agent_loop(messages)

❯ /plan 分析项目技术栈并更新 README

⏳ Generating plan...

📋 Plan:
1. 调研项目使用的语言、框架、测试工具
2. 读取当前 README 内容
3. 在 README 中补充技术栈说明

 Execute? (y/n) y

⚡ Executing...

  🔀 Subagent started: 调研项目的语言、框架、测试工具...
    > bash: cat package.json | head -30
    > bash: cat jest.config.js
    > read_file: vite.config.ts
  🔀 Subagent done (8 messages)

> task: TypeScript 5.3, React 18 + Vite 5, Jest + Testing Library, pnpm...
> read_file: # My Project ...
> edit_file: Edited README.md

已在 README.md 中补充了完整的技术栈说明。

✅ 父 → [子A, 子B, 子C]      (宽度扩展)
❌ 父 → 子 → 孙 → 曾孙        (深度递归)

SUBAGENT_SYSTEM = """You are a focused agent at {WORKDIR}.
Complete the given task, then provide a clear summary of results.
Do not ask for clarification — work with what you have."""