# 工具调用（子 Run 模式）最小闭环

本次改动新增 Tool 子系统，保持 RunLoop/Provider 的事件驱动模型不变，通过“子 Run”执行工具并把结果回灌到父 Run。

## 关键链路
- Provider 产生 `tool.call`（Streaming 中的 `tool.delta` 聚合），RunLoop 落库 `tool.call` 并生成子 Run `run:{parent}:{tool_call_id}`。
- `ToolRunJob` 执行具体工具（当前内置 `get_time`），写入 `tool.result` 与子 Run 的 `run.status`。
- 父 Run 轮询等待子 Run 结果（超时/失败即终止），将 `tool.result` 追加到上下文后再次调用 Provider，直至产出最终 `agent.message`。
- 幂等：`tool.call`、子 Run `run.status` 与 `tool.result` 均带 dedupe_key；同一个 tool_call_id 只会执行一次。

## 消息/事件
- 新增消息类型：`tool.call`（role=AGENT，payload 含 tool_call_id/name/arguments）、`tool.result`（role=TOOL，payload 含 parent_run_id/run_id/status/result）。
- Provider 事件新增 `tool.delta`，RunLoop 内部聚合后才触发子 Run；`finish_reason=tool_calls` 会结束本轮流并进入工具执行。

## 配置要点
- `AGENT_TOOL_MAX_CALLS_PER_RUN`：单个父 Run 允许的工具调用次数（默认 1，超过直接失败）。
- `AGENT_TOOL_WAIT_TIMEOUT_MS` / `AGENT_TOOL_WAIT_POLL_MS`：父 Run 等待子 Run 结果的超时与轮询间隔。
- `AGENT_TOOL_TIMEOUT_SECONDS` / `AGENT_TOOL_RESULT_MAX_BYTES`：工具执行超时标记与结果截断保护。
- `AGENT_TOOL_CHOICE`：传递给 OpenAI 的 tool_choice（默认 auto）。
- ToolRunJob 队列参数：`AGENT_TOOL_JOB_TRIES` / `AGENT_TOOL_JOB_BACKOFF` / `AGENT_TOOL_JOB_TIMEOUT`。

## 预留/限制
- 目前仅支持单工具调用闭环；多次调用的上限可调但仍是串行流程。
- 工具列表可通过 `ToolRegistry` 扩展（当前内置 `get_time` 纯函数）。
- 结果超时为父 Run 级别的软超时，PHP 层未强制中断长耗时函数（后续可接入外部超时控制）。