dsh-plugin-prompt-tool 0.7.2 → 0.8.0

package/engine/tool-config-engine.mjs

@@ -3,20 +3,46 @@
  *
  * 工具定义从 configsDir 目录加载（writePreset 渲染 custom-tools/*.yml，
  * 源 = preset.yml 顶层 customTools 段），每份一个工具定义：
- *   id / name / description / scope / timeoutMs / parameters（dsh-tools schema
- *   DSL 的 JSON 形态）/ output.schema / execute.{kind, ...}
+ *   id / name / description / timeoutMs / parameters（标准 JSON Schema
+ *   object，writePreset 已用官方 @deepseek-ai/dsh-tools 的
+ *   parameterSchemaSpecToJsonSchema / valueSchemaSpecToJsonSchema 把
+ *   preset.yml 的 dsh-tools DSL 转换）/ output.schema / execute.{kind, ...}
  *
  * 执行器（kind）：
  *   shell    — 命令执行（execFile 无 shell 解析，env 白名单，cwd=会话工作区）
  *   http     — fetch 请求（method/url/headers/body，{{args.x}} 插值）
- *   delegate — 委托已注册工具（ctx.tools.get + 透传参数，高级用法：
- *              目标工具 execute 直接调用，不经 registry 校验管线）
+ *   delegate — 委托已注册工具（经 ctx.tools.execute 的 nested dispatch 走
+ *              完整官方管线：参数/输出校验、allow/deny/ask、pre/execute/post
+ *              waterfall、timeout、nested token 与 durable result）
  *   fs       — 文件操作（read/write/append/list/delete，路径限定 cwd 内）
  *   ask-user — approval 通道询问用户（结果文本化）
  *
  * 安全：行 config.requireApproval = [kind...] 时该执行器先过 approval 门
  * （无 approval 服务则拒绝）；单条定义非法 warnOnce 跳过（不挂整行）。
- * 工具注册经 ctx.effect，插件卸载自动撤销。
+ * 工具注册经 disposer 契约（keepDisposer），插件卸载自动撤销。
+ *
+ * ── 能力提供者边界（T4）────────────────────────────────────────────────────
+ * 本模块是**能力提供者**，不是触发器。分类判据（与组合源 tool-config-engine.yml、
+ * subagent-tool-policy.yml 及 test/engine/provider-boundary.test.mjs 同一份措辞）：
+ *   - 会给模型提供可调用能力（注册工具 / 域 / 服务）的 → 能力提供者；
+ *   - 干预流程（改提示词、改装配、裁决、追加）的 → 声明式触发器。
+ * 因此本模块**不接入** engine/trigger.mjs：它不订阅装配 waterfall，也没有
+ * when/do 声明，只在装配期把 preset.yml 的 customTools 段物化出的工具注册进官方
+ * registry。强行并进触发器会让引擎同时承担「提供能力」与「干预流程」两种职责。
+ *
+ * 样板收敛：
+ *   - 配置声明走 fields.mjs 的 `defineConfig`（未知键在挂载期 fail loud）；
+ *   - 注册走 disposer 契约：单次注册用 shared.keepDisposer（register() 返回的正是
+ *     它自己的 effect disposer）；需要整组原子回滚或定向撤销句柄时才用 ctx.effect；
+ *   - 降级告警统一 `${name}: <what>; <fallback>` 一个前缀格式（见 provider-boundary 用例）。
+ *
+ * 登记入口：`engineProvider`（数据导出），供边界守卫消费。提供者登记与声明式触发器
+ * 声明（约定为 `engineTriggers`）**互斥**，同一模块不得同时导出两者。
+ *
+ * 文件归属校正（PLAN T4）：第三个指定提供者 str-replace-editor 由
+ * engine/compositions/source/local/filesystem-editor.yml:20 引用**官方**包
+ * `@deepseek-ai/dsh-tool-str-replace-editor`，本仓库没有对应 `.mjs`；
+ * engine/tool-git-bash.mjs 提供的是 `bash` 工具，**不是**第三个指定提供者。
  */
 
 import { readFileSync, readdirSync, writeFileSync, appendFileSync, rmSync, statSync } from 'node:fs'
@@ -24,18 +50,18 @@ import { execFile } from 'node:child_process'
 import { isAbsolute, join, resolve, sep } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { parse as parseYaml } from './vendor/yaml/index.js'
+import { importHostPackage } from './host-package.mjs'
+import { validateDefinition } from './tool-definition.mjs'
+import { defineConfig, passthrough } from './fields.mjs'
+import { keepDisposer } from './shared.mjs'
+
+const { ToolArgsError } = await importHostPackage('@deepseek-ai/dsh-tools')
 
 /** Cordis 插件名，供 loader 诊断使用。 */
 export const name = 'tool-config-engine'
 
 export const inject = ['tools']
 
-/** 工具名规范（模型可见，schemas() 白名单要求）。 */
-const TOOL_NAME_RE = /^[a-z][a-z0-9_]*$/
-
-/** 合法参数节点类型（dsh-tools ValueSchemaSpec 的 type 枚举）。 */
-const SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'array', 'object', 'json', 'oneOf'])
-
 /** shell 执行器的 env 白名单（无凭据形态；与 run-code-env 同基调）。 */
 const ENV_ALLOWLIST = [
   'PATH', 'PATHEXT', 'SystemRoot', 'COMSPEC', 'TEMP', 'TMP',
@@ -54,91 +80,67 @@ function interpolateArgs(text, args) {
   })
 }
 
-/** 递归校验 schema 节点（宽松：type 枚举 + object 必须声明 additionalProperties + required 必须 true）。 */
-function validateSchemaNode(node, path, seen) {
-  if (node === null || typeof node !== 'object' || Array.isArray(node)) {
-    throw new TypeError(`${path} must be an object`)
-  }
-  if (seen.has(node)) throw new TypeError(`${path} is circular`)
-  seen.add(node)
-  try {
-    if (typeof node.type !== 'string' || !SCHEMA_TYPES.has(node.type)) {
-      throw new TypeError(`${path}.type must be one of ${[...SCHEMA_TYPES].join('/')}`)
-    }
-    if (node.type === 'object' && typeof node.additionalProperties !== 'boolean') {
-      throw new TypeError(`${path}.additionalProperties must be explicitly true or false`)
-    }
-    if (node.required !== undefined && node.required !== true) {
-      throw new TypeError(`${path}.required must be true when present`)
+/**
+ * 按 JSON Schema 子集校验参数值（引擎侧输入校验；官方 defineTool 的 validateArgs
+ * 同样校验——registry 对裸 register 工具不校验参数，引擎自持保证"非法参数在执行前
+ * 失败且实现不运行"）。object required/additionalProperties:false、array items、
+ * scalar type/enum/const、oneOf 覆盖；annotation-only（无 type）视为任意 JSON。
+ */
+function validateJsonSchemaValue(schema, value) {
+  const violations = []
+  const walk = (node, value, path) => {
+    if (node === null || typeof node !== 'object' || Array.isArray(node)) {
+      violations.push(path + ': invalid schema node')
+      return
     }
-    if (node.type === 'object' && node.properties !== undefined) {
-      for (const [key, child] of Object.entries(node.properties)) {
-        validateSchemaNode(child, `${path}.properties.${key}`, seen)
+    if (Array.isArray(node.oneOf)) {
+      for (const branch of node.oneOf) {
+        const before = violations.length
+        walk(branch, value, path)
+        if (violations.length === before) return
+        violations.length = before
       }
+      violations.push(path + ': does not match any oneOf branch')
+      return
     }
-    if (node.type === 'array' && node.items !== undefined) {
-      validateSchemaNode(node.items, `${path}.items`, seen)
+    const type = node.type
+    if (type === undefined) return // annotation-only = unconstrained
+    const actualType = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value
+    const matchesType = actualType === type
+      || (type === 'integer' && actualType === 'number' && Number.isInteger(value))
+    if (!matchesType) {
+      violations.push(path + ': expected ' + type + ', got ' + actualType)
+      return
     }
-    if (node.type === 'oneOf' && Array.isArray(node.oneOf)) {
-      if (node.oneOf.length < 2) throw new TypeError(`${path}.oneOf needs at least two branches`)
-      for (const [index, branch] of node.oneOf.entries()) {
-        validateSchemaNode(branch, `${path}.oneOf[${index}]`, seen)
-      }
+    if (node.enum !== undefined && !node.enum.some((item) => Object.is(item, value))) {
+      violations.push(path + ': value not in enum')
     }
-  } finally {
-    seen.delete(node)
-  }
-}
-
-/** 工具定义轻校验（fail loud → 调用方 warnOnce 跳过该条）。 */
-function validateDefinition(def) {
-  if (def === null || typeof def !== 'object' || Array.isArray(def)) throw new TypeError('tool definition must be an object')
-  if (typeof def.id !== 'string' || def.id.length === 0) throw new TypeError('tool definition needs a non-empty string id')
-  if (typeof def.name !== 'string' || !TOOL_NAME_RE.test(def.name)) {
-    throw new TypeError(`tool name ${JSON.stringify(def.name)} must match ${TOOL_NAME_RE}`)
-  }
-  if (typeof def.description !== 'string' || def.description.trim().length === 0) {
-    throw new TypeError(`tool ${def.id}: description is required`)
-  }
-  if (def.parameters !== undefined) {
-    if (def.parameters === null || typeof def.parameters !== 'object' || Array.isArray(def.parameters)) {
-      throw new TypeError(`tool ${def.id}: parameters must be an object map`)
+    if (node.const !== undefined && !Object.is(node.const, value)) {
+      violations.push(path + ': value not equal to const')
     }
-    for (const [key, child] of Object.entries(def.parameters)) {
-      validateSchemaNode(child, `parameters.${key}`, new Set())
+    if (type === 'array' && node.items !== undefined && Array.isArray(value)) {
+      value.forEach((item, index) => walk(node.items, item, path + '[' + index + ']'))
+    }
+    if (type === 'object' && typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      if (Array.isArray(node.required)) {
+        for (const key of node.required) {
+          if (!(key in value)) violations.push(path + ': missing required property \"' + key + '\"')
+        }
+      }
+      if (node.properties !== undefined && typeof node.properties === 'object' && !Array.isArray(node.properties)) {
+        for (const [key, child] of Object.entries(node.properties)) {
+          if (key in value) walk(child, value[key], path + '.' + key)
+        }
+      }
+      if (node.additionalProperties === false && node.properties !== undefined) {
+        for (const key of Object.keys(value)) {
+          if (!(key in node.properties)) violations.push(path + ': unexpected property \"' + key + '\"')
+        }
+      }
     }
   }
-  const output = def.output
-  if (output === null || typeof output !== 'object' || Array.isArray(output)) {
-    throw new TypeError(`tool ${def.id}: output is required`)
-  }
-  validateSchemaNode(output.schema, 'output.schema', new Set())
-  const exec = def.execute
-  if (exec === null || typeof exec !== 'object' || Array.isArray(exec)) {
-    throw new TypeError(`tool ${def.id}: execute is required`)
-  }
-  if (typeof exec.kind !== 'string' || !['shell', 'http', 'delegate', 'fs', 'ask-user'].includes(exec.kind)) {
-    throw new TypeError(`tool ${def.id}: execute.kind must be shell/http/delegate/fs/ask-user`)
-  }
-  if (exec.kind === 'shell' && (typeof exec.command !== 'string' || exec.command.trim().length === 0)) {
-    throw new TypeError(`tool ${def.id}: execute.command is required for shell`)
-  }
-  if (exec.kind === 'http' && (typeof exec.url !== 'string' || exec.url.trim().length === 0)) {
-    throw new TypeError(`tool ${def.id}: execute.url is required for http`)
-  }
-  if (exec.kind === 'delegate' && (typeof exec.tool !== 'string' || exec.tool.length === 0)) {
-    throw new TypeError(`tool ${def.id}: execute.tool is required for delegate`)
-  }
-  if (exec.kind === 'fs' && (typeof exec.action !== 'string'
-    || (!['read', 'write', 'append', 'list', 'delete'].includes(exec.action) && !exec.action.includes('{{args.')))) {
-    throw new TypeError(`tool ${def.id}: execute.action must be read/write/append/list/delete (or {{args.*}} template) for fs`)
-  }
-  if (def.scope !== undefined && !['main', 'subagent', 'both'].includes(def.scope)) {
-    throw new TypeError(`tool ${def.id}: scope must be main/subagent/both`)
-  }
-  if (def.enabled !== undefined && typeof def.enabled !== 'boolean') {
-    throw new TypeError(`tool ${def.id}: enabled must be a boolean`)
-  }
+  walk(schema, value, 'arguments')
+  return violations
 }
 
 /** approval 门：requireApproval 含该 kind 时先请求批准；无 approval 服务拒绝。 */
@@ -171,10 +173,47 @@ function withinCwd(cwd, target) {
   return resolved
 }
 
+/** delegate args 映射：完整引用（{{args.x}}）透传原始类型（数组/数字/布尔不字符串化）；
+ *  部分引用（前缀-{{args.x}}）插值为字符串；非插值值原样。 */
+function mapDelegateArgs(execArgs, args) {
+  const FULL_REF_RE = /^\{\{args\.([A-Za-z0-9_.]+)\}\}$/
+  const mapValue = (value) => {
+    if (Array.isArray(value)) return value.map(mapValue)
+    if (value !== null && typeof value === 'object') {
+      return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, mapValue(child)]))
+    }
+    if (typeof value === 'string') {
+      const ref = FULL_REF_RE.exec(value)
+      if (ref !== null) {
+        let resolved = args
+        for (const part of ref[1].split('.')) {
+          if (resolved === null || typeof resolved !== 'object') {
+            resolved = undefined
+            break
+          }
+          resolved = resolved[part]
+        }
+        return resolved === undefined ? value : resolved
+      }
+      return interpolateArgs(value, args)
+    }
+    return value
+  }
+  return execArgs !== undefined && execArgs !== null && typeof execArgs === 'object'
+    ? Object.fromEntries(Object.entries(execArgs).map(([key, value]) => [key, mapValue(value)]))
+    : args
+}
+
 /** 执行器分发：返回成功值（registry 按 output.schema 校验）。 */
 function createExecute(ctx, def, requireApproval) {
   const exec = def.execute
   return async (args, run) => {
+    if (def.parameters !== undefined) {
+      const violations = validateJsonSchemaValue(def.parameters, args)
+      if (violations.length > 0) {
+        throw new ToolArgsError(violations)
+      }
+    }
     if (requireApproval.includes(exec.kind)) {
       const gate = await approvalGate(ctx, run, exec.kind, `custom tool ${def.name} (${exec.kind})`)
       if (!gate.ok) return { ok: false, error: gate.message }
@@ -198,7 +237,7 @@ function createExecute(ctx, def, requireApproval) {
             exitCode: error === null ? 0 : (typeof error.code === 'number' ? error.code : 1),
             stdout: String(stdout ?? ''),
             stderr: String(stderr ?? ''),
-            error: error === null ? undefined : String(error.message),
+            ...(error === null ? {} : { error: String(error.message) }),
           })
         })
         const timeout = def.timeoutMs
@@ -224,55 +263,31 @@ function createExecute(ctx, def, requireApproval) {
       return { status: response.status, ok: response.ok, body: text }
     }
     if (exec.kind === 'delegate') {
-      const tools = ctx.get('tools')
-      const target = tools?.get?.(exec.tool)
-      if (target === undefined || typeof target.execute !== 'function') {
-        return { ok: false, error: `delegated tool ${exec.tool} is not registered` }
-      }
-      // 高级用法：透传参数直接调用目标 execute（不经 registry 校验管线）。
-      // args 映射：完整引用（{{args.x}}）透传原始类型（数组/数字/布尔不字符串化）；
-      // 部分引用（前缀-{{args.x}}）插值为字符串；非插值值原样。
-      const FULL_REF_RE = /^\{\{args\.([A-Za-z0-9_.]+)\}\}$/
-      const mapDelegateArg = (value) => {
-        if (Array.isArray(value)) return value.map(mapDelegateArg)
-        if (value !== null && typeof value === 'object') {
-          return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, mapDelegateArg(child)]))
-        }
-        if (typeof value === 'string') {
-          const ref = FULL_REF_RE.exec(value)
-          if (ref !== null) {
-            let resolved = args
-            for (const part of ref[1].split('.')) {
-              if (resolved === null || typeof resolved !== 'object') {
-                resolved = undefined
-                break
-              }
-              resolved = resolved[part]
-            }
-            return resolved === undefined ? value : resolved
-          }
-          return interpolateArgs(value, args)
-        }
-        return value
+      const tools = ctx.tools ?? ctx.get('tools')
+      if (tools === undefined || typeof tools.execute !== 'function') {
+        return { ok: false, error: 'no tool runtime is available for delegate' }
       }
-      const delegatedArgs = exec.args !== undefined && exec.args !== null && typeof exec.args === 'object'
-        ? Object.fromEntries(Object.entries(exec.args).map(([key, value]) => [key, mapDelegateArg(value)]))
-        : args
-      const minimalExec = {
-        name: def.name,
-        callId: `delegate-${def.name}-${Date.now().toString(36)}`,
+      const delegatedArgs = mapDelegateArgs(exec.args, args)
+      // nested dispatch：走完整官方管线（校验/allow-deny-ask/pre-execute/post/
+      // timeout/nested token/durable result），调用身份由外层 callId 稳定派生，
+      // 禁止 Date.now() 生成调用身份。
+      const result = await tools.execute({
+        callId: `${run.callId}:delegate:${exec.tool}`,
+        rootCallId: run.rootCallId,
+        name: exec.tool,
         agent: run.agent,
-        parent: run.parent,
-        signal: run.signal,
+        parent: run.token,
         arguments: delegatedArgs,
-        deferContext: () => {},
-        concludeTurn: () => {},
+        signal: run.signal,
+      })
+      if (result.isError) {
+        return { ok: false, error: String(result.error?.message ?? result.error ?? `delegated tool ${exec.tool} failed`) }
       }
-      try {
-        return { ok: true, value: await target.execute(delegatedArgs, minimalExec) }
-      } catch (error) {
-        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      for (const context of result.additionalContexts ?? []) {
+        run.deferContext(context)
       }
+      if (result.concludesTurn === true) run.concludeTurn()
+      return { ok: true, value: result.value }
     }
     if (exec.kind === 'fs') {
       const cwd = run.agent?.session?.header?.cwd ?? process.cwd()
@@ -324,12 +339,22 @@ function createExecute(ctx, def, requireApproval) {
   }
 }
 
-/** 单份工具定义文件 → 编译为 ToolDefinition 结构（不含 id）。 */
+/** 宿主 system-prompt 对 section 文本做 {{var}} 变量校验（变量名须匹配 [a-z][a-z0-9_]* 且已注册），
+ *  工具 description 进入 tools:sdk 段；description 中的双花括号字面量会炸掉整轮提示词组装
+ *  （malformed / unknown prompt variable reference）。把配对的 {{...}} 统一降级为单花括号
+ *  示意（{...}），其余字面保留；不配对的 {{ 宿主按字面处理，无需处理。 */
+function sanitizeDescription(text) {
+  return text.replace(/\{\{([^{}]*)\}\}/g, '{$1}')
+}
+
+/** 单份工具定义文件 → 编译为完整官方 ToolDefinition（不含 id）。
+ *  parameters/output.schema 已是 writePreset 物化的标准 JSON Schema；无参数
+ *  工具补空 object Schema（真实 ctx.tools.schemas() 需要 parameters 存在）。 */
 function compileTool(ctx, def, requireApproval) {
   return {
     name: def.name,
-    description: def.description,
-    ...(def.parameters !== undefined && Object.keys(def.parameters).length > 0 ? { parameters: def.parameters } : {}),
+    description: sanitizeDescription(def.description),
+    parameters: def.parameters ?? { type: 'object', properties: {} },
     output: {
       schema: def.output.schema,
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
@@ -340,12 +365,21 @@ function compileTool(ctx, def, requireApproval) {
 }
 
 /** 工具定义文件加载（*.yml / *.json；与 prompt-config-engine configsDir 同构）。 */
-function loadToolFiles(dirUrl) {
+function loadToolFiles(dirUrl, presetRootUrl) {
   const resolved = isAbsolute(dirUrl)
     ? pathToFileURL(dirUrl).href
     : dirUrl
   const dir = new URL(resolved.endsWith('/') ? resolved : `${resolved}/`, import.meta.url)
   const localDir = fileURLToPath(dir)
+  // 相对 configsDir 只允许解析到预设根内：防组合行声明越界目录；绝对路径（显式配置/
+  // 测试桩）保持允许。预设根基准显式注入优先（引擎由插件包提供时必需），缺省沿用
+  // 「引擎上一级目录」这一历史布局推导。
+  if (!isAbsolute(dirUrl)) {
+    const presetRoot = fileURLToPath(presetRootUrl ?? new URL('../..', import.meta.url)).replace(/[\\\\/]$/, '')
+    if (localDir !== presetRoot && !localDir.startsWith(presetRoot + sep)) {
+      throw new Error(`${name}: configsDir ${JSON.stringify(dirUrl)} escapes preset root`)
+    }
+  }
   const files = readdirSync(localDir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && /\.(ya?ml|json)$/i.test(entry.name))
     .sort((a, b) => a.name.localeCompare(b.name))
@@ -358,17 +392,41 @@ function loadToolFiles(dirUrl) {
   return out
 }
 
+/**
+ * 配置契约：白名单由字段声明派生（此前没有白名单，未知键被静默忽略）。
+ * requireApproval 迁移前对**非数组取 `[]`**、对数组**过滤掉非字符串项**（宽容而非报错），
+ * configsDir 对非字符串/空串取默认值——两者都用 passthrough 保住该语义。
+ * 本任务只新增「未知键报错」，缺键与错类型的既有行为逐字段不变。
+ */
+export const configContract = defineConfig({
+  configsDir: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : './custom-tools')),
+  requireApproval: passthrough((value) => (Array.isArray(value) ? value.filter((kind) => typeof kind === 'string') : [])),
+  // 预设根基准（绝对 file URL）：引擎由插件包提供时由装配期注入，替代引擎位置推导。
+  presetRoot: passthrough((value) => (typeof value === 'string' && value.length > 0 ? value : undefined)),
+})
+
+/**
+ * 能力提供者登记（T4 边界守卫的数据源）。
+ * `provides.kind === 'dynamic'`：模型可见的工具名由 preset.yml 的 customTools 段在
+ * 装配期决定（物化为 custom-tools/*.yml），引擎侧无法静态枚举——守卫只断言登记形状、
+ * 注册通道，以及「提供者不导出触发器声明」这条互斥。
+ */
+export const engineProvider = {
+  kind: 'provider',
+  moduleId: name,
+  registers: 'tools',
+  provides: { kind: 'dynamic', source: 'preset.yml#customTools → custom-tools/*.yml' },
+}
+
 /** 插件入口：扫描 configsDir 注册全部自定义工具。 */
 export function apply(ctx, config) {
-  const dirName = typeof config?.configsDir === 'string' && config.configsDir.length > 0
-    ? config.configsDir
-    : './custom-tools'
-  const requireApproval = Array.isArray(config?.requireApproval)
-    ? config.requireApproval.filter((kind) => typeof kind === 'string')
-    : []
+  const { configsDir: dirName, requireApproval, presetRoot: rawPresetRoot } = configContract.parse(config, name)
+  const presetRootUrl = rawPresetRoot === undefined
+    ? undefined
+    : new URL(rawPresetRoot.endsWith('/') ? rawPresetRoot : `${rawPresetRoot}/`)
   let definitions = []
   try {
-    definitions = loadToolFiles(dirName)
+    definitions = loadToolFiles(dirName, presetRootUrl)
   } catch (error) {
     ctx.logger?.warn(`${name}: cannot load ${dirName}: ${error?.message ?? error}`)
     return
@@ -381,7 +439,11 @@ export function apply(ctx, config) {
         continue
       }
       const tool = compileTool(ctx, def, requireApproval)
-      ctx.effect(() => ctx.tools.register(tool), `${name}: ${def.name}`)
+      // 注册走 disposer 契约：register() 返回的正是它自己的 effect disposer，
+      // keepDisposer 把该 disposer 纳入本插件的资源所有权（卸载即撤销）。fiber 已卸载时
+      // register() 内部先抛 INACTIVE_EFFECT（与改写前 ctx.effect 的前置断言同一错误），
+      // 因此注册不会发生——降级语义与错误消息逐字不变。
+      keepDisposer(ctx, ctx.tools.register(tool), `${name}: ${def.name}`)
       ctx.logger?.info(`${name}: registered custom tool ${def.name} (${def.execute.kind})`)
     } catch (error) {
       ctx.logger?.warn(`${name}: skipping tool ${JSON.stringify(def?.id ?? def?.name)}: ${error?.message ?? error}`)

package/engine/tool-definition.mjs

@@ -0,0 +1,143 @@
+/** 自定义工具物化定义的纯校验：host 保存/物化与运行时共用，不加载宿主服务。 */
+
+const TOOL_NAME_RE = /^[a-z][a-z0-9_]*$/
+const JSON_SCHEMA_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'array', 'object'])
+const JSON_SCHEMA_ANNOTATIONS = new Set(['description', 'title', 'default', 'examples'])
+
+/** JSON Schema 结构校验；DSL 转换与官方 registry 仍负责 enforced subset 校验。 */
+export function validateJsonSchemaNode(node, path, seen = new Set()) {
+  if (node === null || typeof node !== 'object' || Array.isArray(node)) {
+    throw new TypeError(`${path} must be an object`)
+  }
+  if (seen.has(node)) throw new TypeError(`${path} is circular`)
+  seen.add(node)
+  try {
+    if (node.type !== undefined) {
+      if (!JSON_SCHEMA_TYPES.has(node.type)) {
+        throw new TypeError(`${path}.type must be one of ${[...JSON_SCHEMA_TYPES].join('/')} (dsh-tools DSL 形态 'json'/'oneOf' 未在物化时转换)`)
+      }
+      if (node.type === 'object') {
+        if (node.properties !== undefined) {
+          if (node.properties === null || typeof node.properties !== 'object' || Array.isArray(node.properties)) {
+            throw new TypeError(`${path}.properties must be an object of schemas`)
+          }
+          for (const [key, child] of Object.entries(node.properties)) {
+            validateJsonSchemaNode(child, `${path}.properties.${key}`, seen)
+          }
+        }
+        if (node.required !== undefined) {
+          if (!Array.isArray(node.required) || node.required.some((item) => typeof item !== 'string')) {
+            throw new TypeError(`${path}.required must be an array of property names`)
+          }
+        }
+        if (node.additionalProperties !== undefined && typeof node.additionalProperties !== 'boolean') {
+          throw new TypeError(`${path}.additionalProperties must be a boolean`)
+        }
+      }
+      if (node.type === 'array' && node.items !== undefined) {
+        validateJsonSchemaNode(node.items, `${path}.items`, seen)
+      }
+    } else if (Array.isArray(node.oneOf)) {
+      if (node.oneOf.length < 2) throw new TypeError(`${path}.oneOf needs at least two branches`)
+      for (const [index, branch] of node.oneOf.entries()) {
+        validateJsonSchemaNode(branch, `${path}.oneOf[${index}]`, seen)
+      }
+    } else if (!Object.keys(node).every((key) => JSON_SCHEMA_ANNOTATIONS.has(key))) {
+      // 官方 DSL type: json 物化为 {} 或仅含 annotation 的节点；不能误判为未转换的 DSL。
+      throw new TypeError(`${path} must declare type or oneOf (or contain annotations only)`)
+    }
+  } finally {
+    seen.delete(node)
+  }
+}
+
+/** 完整定义校验；保存方拒绝写盘，writer / runtime 按单条告警跳过。 */
+export function validateDefinition(def) {
+  if (def === null || typeof def !== 'object' || Array.isArray(def)) throw new TypeError('tool definition must be an object')
+  if (typeof def.id !== 'string' || def.id.trim().length === 0) throw new TypeError('tool definition needs a non-empty string id')
+  if (typeof def.name !== 'string' || !TOOL_NAME_RE.test(def.name)) {
+    throw new TypeError(`tool name ${JSON.stringify(def.name)} must match ${TOOL_NAME_RE}`)
+  }
+  if (typeof def.description !== 'string' || def.description.trim().length === 0) {
+    throw new TypeError(`tool ${def.id}: description is required`)
+  }
+  if (def.scope !== undefined) {
+    throw new TypeError(`tool ${def.id}: customTools.scope is not supported (subagent tool policy is configured via subagentToolPolicy, not per-tool scope)`)
+  }
+  if (def.parameters !== undefined) {
+    validateJsonSchemaNode(def.parameters, `tool ${def.id}: parameters`)
+  }
+  const output = def.output
+  if (output === null || typeof output !== 'object' || Array.isArray(output)) {
+    throw new TypeError(`tool ${def.id}: output is required`)
+  }
+  validateJsonSchemaNode(output.schema, `tool ${def.id}: output.schema`)
+  const exec = def.execute
+  if (exec === null || typeof exec !== 'object' || Array.isArray(exec)) {
+    throw new TypeError(`tool ${def.id}: execute is required`)
+  }
+  if (typeof exec.kind !== 'string' || !['shell', 'http', 'delegate', 'fs', 'ask-user'].includes(exec.kind)) {
+    throw new TypeError(`tool ${def.id}: execute.kind must be shell/http/delegate/fs/ask-user`)
+  }
+  if (exec.kind === 'shell' && (typeof exec.command !== 'string' || exec.command.trim().length === 0)) {
+    throw new TypeError(`tool ${def.id}: execute.command is required for shell`)
+  }
+  if (exec.kind === 'http' && (typeof exec.url !== 'string' || exec.url.trim().length === 0)) {
+    throw new TypeError(`tool ${def.id}: execute.url is required for http`)
+  }
+  if (exec.kind === 'delegate' && (typeof exec.tool !== 'string' || exec.tool.length === 0)) {
+    throw new TypeError(`tool ${def.id}: execute.tool is required for delegate`)
+  }
+  if (exec.kind === 'fs' && (typeof exec.action !== 'string'
+    || (!['read', 'write', 'append', 'list', 'delete'].includes(exec.action) && !exec.action.includes('{{args.')))) {
+    throw new TypeError(`tool ${def.id}: execute.action must be read/write/append/list/delete (or {{args.*}} template) for fs`)
+  }
+  if (def.enabled !== undefined && typeof def.enabled !== 'boolean') {
+    throw new TypeError(`tool ${def.id}: enabled must be a boolean`)
+  }
+  // 与 Node 定时器的有符号 32 位上限一致，避免溢出后变成 1 ms。
+  if (def.timeoutMs !== undefined && (!Number.isSafeInteger(def.timeoutMs) || def.timeoutMs <= 0 || def.timeoutMs > 2_147_483_647)) {
+    throw new TypeError(`tool ${def.id}: timeoutMs must be an integer from 1 to 2147483647`)
+  }
+  for (const field of ['command', 'shell', 'url', 'method', 'tool', 'action', 'path', 'content', 'question']) {
+    if (exec[field] !== undefined && typeof exec[field] !== 'string') {
+      throw new TypeError(`tool ${def.id}: execute.${field} must be a string`)
+    }
+  }
+  if (exec.shell !== undefined && (exec.shell.trim().length === 0 || exec.shell.includes('\0'))) {
+    throw new TypeError(`tool ${def.id}: execute.shell must be a non-empty executable name or path without NUL`)
+  }
+  if (exec.method !== undefined && !/^\{\{args\.[A-Za-z0-9_.]+\}\}$/.test(exec.method) && (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(exec.method)
+    || ['CONNECT', 'TRACE', 'TRACK'].includes(exec.method.toUpperCase()))) {
+    throw new TypeError(`tool ${def.id}: execute.method must be a supported HTTP method token`)
+  }
+  if (exec.kind === 'fs' && (typeof exec.path !== 'string' || exec.path.includes('\0'))) {
+    throw new TypeError(`tool ${def.id}: execute.path must be a string without NUL for fs`)
+  }
+  for (const field of ['env', 'headers', 'args']) {
+    const value = exec[field]
+    if (value === undefined) continue
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      throw new TypeError(`tool ${def.id}: execute.${field} must be an object`)
+    }
+    if (field !== 'args' && Object.values(value).some((entry) => typeof entry !== 'string')) {
+      throw new TypeError(`tool ${def.id}: execute.${field} values must be strings`)
+    }
+    if (field === 'env' && Object.entries(value).some(([key, entry]) => key.length === 0 || /[=\0]/.test(key) || entry.includes('\0'))) {
+      throw new TypeError(`tool ${def.id}: execute.env must contain valid environment names and values`)
+    }
+    if (field === 'headers') {
+      try { new Headers(value) } catch {
+        throw new TypeError(`tool ${def.id}: execute.headers must contain valid HTTP names and values`)
+      }
+    }
+  }
+  // 单条上限覆盖命令、文件内容及嵌套 body/args/schema；不丢弃模板未知字段。
+  let serialized
+  try { serialized = JSON.stringify(def) } catch {
+    throw new TypeError(`tool ${def.id}: definition must be JSON serializable`)
+  }
+  if (Buffer.byteLength(serialized, 'utf8') > 1_048_576) {
+    throw new TypeError(`tool ${def.id}: definition must not exceed 1048576 UTF-8 bytes`)
+  }
+}