Tool：把意图变成受约束的动作

从 schema 到 executionMode，再到 before/after hooks，拆解一个工具调用的完整边界。

Tool 不是一个随便调用的函数

Tool contract

interface AgentTool {
  name: string;
  label: string;
  description: string;
  parameters: TSchema;
  executionMode?: "sequential" | "parallel";
  execute(id, params, signal, onUpdate): Promise<AgentToolResult>;
}

content 是发回模型的文本或图片；details 是日志/UI 可消费的结构化信息。两者分开，避免为了给 UI 展示元数据而污染模型上下文。

调用链

assistant toolCall
  → locate tool
  → prepareArguments?()
  → validateToolArguments()
  → beforeToolCall()
  → tool.execute()
  → streamed onUpdate()
  → afterToolCall()
  → tool_execution_end
  → ToolResultMessage

参数验证

schema 是模型与运行时的契约。验证失败不会执行函数，而是产生 error tool result，让模型有机会纠正参数。

执行策略

读操作通常可并行；需要用户输入、修改共享文件或依赖顺序的工具应标为 sequential。Pi 允许全局设置，也允许工具覆盖。

终止提示

工具结果可返回 terminate: true。但一个 batch 只有在每个已完成结果都要求终止时才提前结束，避免一个并行工具无意中吞掉其他调用的后续语义。

内建工具与产品策略

Pi 默认 coding session 暴露 read、write、edit、bash；也可用 grep、find、ls 组成 read-only session。所谓“只读”在这里是选择不注册写工具，并不自动限制 extension 或 host process。

Trade-off

细粒度 schema 与 hooks 增加实现工作，却换来可验证参数、可观察增量、UI 与模型输出分离，以及策略可插入点。工具少而清晰，通常比工具多而重叠更容易让模型稳定选择。