extra-tools

@asm/extra-tools 为 Durable 提供四个可选工具，不包含业务 Provider、数据库或独立的 Agent 运行框架。

安装扩展

下面创建 Registry 并安装工具。传给 Harness 时使用该 Registry；提问回调的返回值按问题 ID 组织，每个答案是字符串数组：

import { createRegistry } from "@earendil-works/pi-durable";
import { createExtraToolsExtension } from "@asm/extra-tools";

const registry = createRegistry();
registry.install(createExtraToolsExtension({
  multiTenant: true,
  allowedTools: ["read", "knowledge_search"],
  maxDepth: 1,
  maxConcurrency: 4,
  onAskUser: async (request, context) => {
    // 宿主实现展示和等待；每个问题返回所选 label 数组。
    return hostQuestions(request, context);
  },
  skills: [{
    name: "closing",
    description: "演示用闭店检查步骤",
    markdown: "# 闭店检查\n按需读取 references/checklist.md。",
    resources: { "references/checklist.md": "确认结算与交接已完成。" },
  }],
}));

hostQuestions 是宿主提供的回调，不是包导出。allowedTools 中填写父 Agent 实际启用的工具名；使用 ASM 桥接时名称带有 asm__ 前缀，例如 asm__knowledge_search。

四个工具

工具	输入与行为
ask_user	questions 数组包含 id、question、options: [{ label, description? }]，可设置 multiSelect / allowCustom
run_subagent	{ mode: "single" | "parallel" | "chain", tasks: string[] }，返回子会话最终摘要
load_skill	{ name }，返回指令和资源路径，不读取资源正文
read_skill_resource	{ name, resource }，读取指定技能的一个相对路径资源

createExtraTools(options) 只返回这四个工具的注册项。createExtraToolsExtension(options) 还安装技能元数据发现和提问拦截钩子。

子任务的权限边界

子会话继承父 Agent 配置和租户 Context，但不复制父消息。工具来自父 Agent 已启用的集合，并受 allowedTools 限制；子会话不能再调用 ask_user 或 run_subagent。

maxDepth 默认是 1，maxConcurrency 默认是 4，后者可设为 1–4。single 只接收一个任务，parallel 分批并行，chain 将前一任务摘要传给下一任务。子会话记录和请求身份可在 Durable 重放中复用。

技能与无人值守任务

技能内容由宿主以 Markdown 和资源字符串传入。范围级定义覆盖租户级定义，租户级覆盖平台定义。资源仅按相对路径读取，不访问文件系统；绝对路径、路径穿越和编码路径会被拒绝。

多租户模式要求 Context 包含共享 TENANT_CONTEXT_KEY。无人值守执行通过 RUN_ORIGIN_KEY = "cron" 禁止提问；持久化 Routine 可配置 isUnattended: isRoutineUnattended，该解析器由 @asm/asm-mcp 导出。通用宿主也能提供同签名函数。

已完成的提问答案会持久化。若进程在答案提交前中断，宿主仍需用自己的请求身份避免重复展示同一个待回答问题。

源码依据：工具与配置、子任务、技能解析。