显式接入工具执行

@hostanagent/tool-runner@0.2.5 是产品自行启用的执行适配层。模型提出工具调用后，执行器必须领取、取得 grant、验证当前业务权限、保存 assignment 和回执，才执行业务处理器。文本 Widget 本身不会启动 ToolRunner。

一个只读工具的结构

import { AgentToolRunner, proxyCoordinator } from '@hostanagent/tool-runner';

const runner = AgentToolRunner.attach(client, {
  executorId: stableExecutorId,
  coordinator: proxyCoordinator(client),
  handlers: {
    'product.read_selection': async (_args, context) => {
      await context.progress('正在读取已授权的选择');
      return product.readSelectionFor(trustedSubject); // 产品实现并重查 ACL
    },
  },
  receipts: durableReceiptStore, // 产品持久化；不能使用内存存储承诺重启恢复
  authorize: async (call, phase) => {
    if (!await product.authorizeTool(trustedSubject, call, phase)) {
      throw new Error('工具未授权');
    }
  },
  reconcile: call => product.lookupSavedReceipt(call.id),
  onError: (_call, error) => reportSafeErrorCode(error),
});

client、trustedSubject、product、持久存储和报错函数由你的应用提供。上述代码展示接入边界，不能独立运行。先在“工具”页配置绑定和工具集版本，把它关联到已发布 Agent；然后让产品代理显式放行所需工具路由。工具配置。

handler 返回的完整结果用于回执与核对；模型首次看到的结果另按工具定义 max_result_context_bytes 裁剪，默认 16 KiB、最高 32 KiB。该字段配置在工具集，不能通过 AgentToolRunner.attach 设置。产品应分页、筛选字段，并用真实大小的样本检查 dry-run 的 context_preview；不要假设中间游标或业务字段一定能进入模型上下文。结果预算与预览示例。

有副作用的工具要在业务系统以稳定 operationKey 做幂等，并在执行前记录 assignment；最终结果和 receipt 先保存再提交。replayed=true 的领取只允许重投保存的回执或查询已有业务结果，不能重跑 handler。普通异常表示结果待核对；只有业务确认失败或取消，才能返回相应终态。accepted 回执需服务端明确确认后才可启动 handler。

连接、心跳、候选、待核对报告和断开由产品显式驱动。默认 MemoryReceiptStore 只适合进程内试验；可靠产品使用自己的数据库事务 outbox 或经验证的私有持久化实现。长任务与回执协议说明重启和重复投递的处理。