dsh-plugin-prompt-tool 2.0.1 → 3.0.0

package/engine/template-evaluation.mjs

@@ -0,0 +1,178 @@
+/** 有界模板解析与原生求值；只返回正文和变更，不持有或写入持久状态。 */
+import { Buffer } from 'node:buffer'
+import { interpolateVariables, isReservedInterpolationName, normalizeMacroSyntax } from './interpolate.mjs'
+
+const MAX_BYTES = 1024 * 1024
+const MAX_DEPTH = 32
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype'])
+
+function byteLength(text) {
+  const size = Buffer.byteLength(text, 'utf8')
+  if (size > MAX_BYTES) throw new RangeError('Template text exceeds 1 MiB')
+  return size
+}
+
+/** JSON 单花括号及字符串内的右括号不构成模板边界。 */
+function macroEnd(text, start, depth = 0) {
+  const frames = [{ braces: 0, brackets: 0, quote: false, escape: false }]
+  if (depth >= MAX_DEPTH) throw new RangeError('Template depth exceeds 32')
+  for (let index = start + 2; index < text.length; index++) {
+    const frame = frames.at(-1), char = text[index]
+    if (frame.escape) { frame.escape = false; continue }
+    if (frame.quote && char === '\\') { frame.escape = true; continue }
+    if (char === '"' && (frame.quote || frame.braces > 0 || frame.brackets > 0)) { frame.quote = !frame.quote; continue }
+    if (text.startsWith('{{', index)) {
+      if (depth + frames.length >= MAX_DEPTH) throw new RangeError('Template depth exceeds 32')
+      frames.push({ braces: 0, brackets: 0, quote: false, escape: false }); index++; continue
+    }
+    if (frame.quote) continue
+    if (char === '{') frame.braces++
+    else if (char === '}' && frame.braces > 0) frame.braces--
+    else if (text.startsWith('}}', index)) {
+      frames.pop()
+      if (!frames.length) return index + 2
+      index++
+    } else if (char === '[') frame.brackets++
+    else if (char === ']') frame.brackets = Math.max(0, frame.brackets - 1)
+  }
+  return -1
+}
+
+/** ST 编辑残片不是可执行表达式；只保留顶层尾部未知裸名，不放宽操作或嵌套语法。 */
+function isLiteralFragment(text) {
+  const match = /^\{\{\s*([A-Za-z0-9_.\u4e00-\u9fff-]+)\s*\}?$/.exec(text.trimEnd())
+  if (!match) return false
+  const key = match[1]
+  return !FORBIDDEN_KEYS.has(key) && !isReservedInterpolationName(key)
+    && !/^(?:(?:module|global)(?:\.|$)|(?:set|add|get|inc|dec)(?:global)?var$|char$|charifnotgroup$|user$|trim$|ERA$)/i.test(key)
+}
+
+/** 转换端和求值端共用边界与预算；出现身份不含正文字符偏移。 */
+export function transformTemplate(text, macro) {
+  let work = 0, occurrence = 0
+  function walk(source, depth = 0) {
+    work += byteLength(source)
+    if (work > MAX_BYTES * MAX_DEPTH) throw new RangeError('Template expansion work limit exceeded')
+    const chunks = []
+    let size = 0, cursor = 0
+    const append = value => {
+      size += byteLength(value)
+      if (size > MAX_BYTES) throw new RangeError('Template output exceeds 1 MiB')
+      chunks.push(value)
+    }
+    while (cursor < source.length) {
+      const start = source.indexOf('{{', cursor)
+      if (start < 0) { append(source.slice(cursor)); break }
+      append(source.slice(cursor, start))
+      const end = macroEnd(source, start, depth)
+      if (end < 0) {
+        const rest = source.slice(start)
+        if (depth === 0 && isLiteralFragment(rest)) { append(rest); break }
+        throw new TypeError('Unclosed template expression')
+      }
+      append(macro(source.slice(start + 2, end - 2), value => walk(value, depth + 1), occurrence++))
+      cursor = end
+    }
+    return chunks.join('')
+  }
+  return walk(text)
+}
+
+/** 当前层第一个分隔符；嵌套表达式里的分隔符属于子表达式。 */
+export function splitTemplateArgument(text) {
+  for (let index = 0; index < text.length; index++) {
+    if (text.startsWith('{{', index)) {
+      const end = macroEnd(text, index)
+      if (end < 0) throw new TypeError('Unclosed template expression')
+      index = end - 1
+    } else if (text.startsWith('::', index)) return [text.slice(0, index), text.slice(index + 2)]
+  }
+  return [text, undefined]
+}
+
+function addValue(value, increment) {
+  const current = value || '0'
+  let parsed
+  try { parsed = JSON.parse(current) } catch { /* 非 JSON 继续按数值或文本处理。 */ }
+  if (Array.isArray(parsed)) { parsed.push(increment); return JSON.stringify(parsed) }
+  if (Number.isNaN(Number(increment)) || Number.isNaN(Number(current))) return (value || '') + increment
+  const result = Number(current) + Number(increment)
+  if (!Number.isFinite(result)) throw new RangeError('Template variable number is not finite')
+  return String(result)
+}
+
+export function evaluateTemplate(text, { module = {}, global = {}, session, sourceId = '', readOnly = false, samples = new Map() } = {}) {
+  const tables = { module: { ...module }, global: { ...global } }
+  const reads = new Set(), resolving = new Set(), values = {}
+  let scope, pick = 0
+  const keyOf = key => {
+    if (!key || FORBIDDEN_KEYS.has(key) || isReservedInterpolationName(key)) throw new TypeError(`Template variable key blocked: ${key}`)
+    return key
+  }
+  const raw = (domain, key) => {
+    reads.add(domain)
+    if (Object.hasOwn(tables[domain], key)) return { domain, value: tables[domain][key] }
+    if (domain === 'module') {
+      reads.add('global')
+      if (Object.hasOwn(tables.global, key)) return { domain: 'global', value: tables.global[key] }
+    }
+    return undefined
+  }
+  const read = (found, key, expand) => {
+    if (!found) return ''
+    const id = `${found.domain}:${key}`
+    if (resolving.has(id)) throw new RangeError(`Template variable cycle: ${id}`)
+    resolving.add(id)
+    try { return expand(String(found.value)) } finally { resolving.delete(id) }
+  }
+  const write = (domain, key, value) => {
+    if (readOnly) throw new TypeError('Read-only template cannot write variables')
+    if (scope !== undefined && scope !== domain) throw new TypeError('One template may write only one variable scope')
+    byteLength(value)
+    scope = domain
+    tables[domain][key] = value
+    values[key] = value
+  }
+  const output = transformTemplate(text, (body, expand, occurrence) => {
+    const [name, args] = splitTemplateArgument(body)
+    const operation = /^(module|global)\.(set|get|add|inc|dec)$/.exec(name.trim())
+    if (operation) {
+      if (args === undefined) throw new TypeError(`Missing arguments for ${name}`)
+      const [rawKey, rawValue] = splitTemplateArgument(args)
+      const key = keyOf(expand(rawKey).trim()), domain = operation[1], action = operation[2]
+      if (readOnly && (action !== 'get' || rawValue !== undefined)) throw new TypeError('Read-only template cannot write variables')
+      if (action === 'get') {
+        const found = raw(domain, key)
+        if (found) return read(found, key, expand)
+        const fallback = rawValue === undefined ? '' : expand(rawValue)
+        if (fallback !== '') write(domain, key, fallback)
+        return fallback
+      }
+      if ((action === 'set' || action === 'add') && rawValue !== undefined) {
+        const value = expand(rawValue)
+        write(domain, key, action === 'set' ? value : addValue(read(raw(domain, key), key, expand), value))
+        return ''
+      }
+      if ((action === 'inc' || action === 'dec') && rawValue === undefined) {
+        const value = addValue(read(raw(domain, key), key, expand), action === 'inc' ? '1' : '-1')
+        write(domain, key, value)
+        return value
+      }
+      throw new TypeError(`Invalid arguments for ${name}`)
+    }
+    if (/^(set|add|get|inc|dec)(global)?var$/i.test(name.trim())) throw new TypeError('ST variable operations are retired; reimport or explicitly convert to module/global operations')
+    const whole = normalizeMacroSyntax(`{{${expand(body)}}}`)
+    const [key] = splitTemplateArgument(whole.slice(2, -2))
+    if (FORBIDDEN_KEYS.has(key)) throw new TypeError(`Template variable key blocked: ${key}`)
+    if (args === undefined && !isReservedInterpolationName(key)) {
+      const found = raw('module', key)
+      if (found) return read(found, key, expand)
+    }
+    if (whole.slice(2, -2).includes('{{')) return whole
+    const identity = key.toLowerCase() === 'pick' ? `pick:${pick++}` : String(occurrence)
+    const sample = `${identity}:${whole}`
+    if (!samples.has(sample)) samples.set(sample, interpolateVariables(whole, {}, session, undefined, `${sourceId}:${identity}`))
+    return samples.get(sample)
+  })
+  return { text: output, reads: [...reads], ...(scope === undefined ? {} : { changes: { scope, values } }) }
+}

package/engine/template-frame.d.mts

@@ -0,0 +1,16 @@
+import type { TemplateSnapshot } from './template-evaluation.mjs'
+export interface TemplateVariableStore {
+  read(moduleId: string): { module: Record<string, string>; global: Record<string, string>; enabled?: boolean; revisions: { module: string; global: string | null; settings?: string } }
+  commit(moduleId: string, request: { scope: 'global' | 'module'; changes: Record<string, string>; expectedRevisions: { module?: string; global?: string | null; settings?: string } }): { publicationPending?: boolean }
+  publish(moduleId: string): void
+}
+export interface TemplateConfig {
+  sourceModuleId: string
+  ruleId?: string
+  id: string
+  texts: string[]
+  variables?: TemplateSnapshot['module']
+  variableStore?: TemplateVariableStore
+}
+export function templateExecutionKey(agent: unknown, signal?: AbortSignal): string | undefined
+export function renderTemplate(config: TemplateConfig, context?: { agent?: unknown; signal?: AbortSignal }, options?: { variableStore?: TemplateVariableStore; enabled?: boolean; warn?: (message: string) => void }): string

package/engine/template-frame.mjs

@@ -0,0 +1,69 @@
+/** 执行凭据独立于规则 mount；变量真值始终归显式宿主 adapter。 */
+import { historyEvents } from './history.mjs'
+import { evaluateTemplate } from './template-evaluation.mjs'
+import { interpolateVariables, stripUnresolvedRefs } from './interpolate.mjs'
+
+const frames = new WeakMap()
+const MAX_CARDS = 4096
+
+/** 官方循环先 assemble、再 pre-step、最后打开 step/start；两出口共享已提交边界。 */
+export function templateExecutionKey(agent, signal) {
+  if (agent?.status !== 'running' || !signal || signal.aborted) return undefined
+  const events = historyEvents(agent.session)
+  const turn = events.findLast(event => event.type === 'turn/start' || event.type === 'turn/end')
+  if (turn?.type !== 'turn/start' || !Number.isSafeInteger(turn.seq)) return undefined
+  const step = events.findLast(event => event.type === 'step/start' || event.type === 'step/end')
+  if (step?.type === 'step/start' && step.seq > turn.seq) return undefined
+  return `${turn.seq}:${step?.seq ?? -1}`
+}
+
+export function renderTemplate(config, context = {}, { variableStore = config.variableStore, enabled = true, warn = () => {} } = {}) {
+  const text = config.texts.join('\n\n'), agent = context.agent, signal = context.signal
+  signal?.throwIfAborted()
+  if (!enabled) return stripUnresolvedRefs(interpolateVariables(text, {}, agent?.session, undefined, config.id)).text
+  const execution = templateExecutionKey(agent, signal)
+  let frame
+  if (execution !== undefined) {
+    frame = frames.get(agent)
+    if (frame?.execution !== execution) { frame = { execution, cards: new Map() }; frames.set(agent, frame) }
+  }
+  const identity = JSON.stringify([config.sourceModuleId, config.ruleId, config.id])
+  const previous = frame?.cards.get(identity)
+  const publish = entry => {
+    if (!entry.pending) return
+    try {
+      if (!variableStore?.publish) throw new Error('Variable publication adapter unavailable')
+      variableStore.publish(config.sourceModuleId)
+      entry.pending = false
+    } catch (error) { warn(`Template ${config.id}: variables saved; publication pending: ${String(error?.message ?? error)}`) }
+  }
+  if (previous) { publish(previous); return previous.text }
+  if (frame?.cards.size >= MAX_CARDS) throw new RangeError('Template execution card limit exceeded')
+  const samples = new Map()
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const snapshot = variableStore?.read(config.sourceModuleId) ?? { module: config.variables ?? {}, global: {} }
+    if (snapshot.enabled === false) return stripUnresolvedRefs(interpolateVariables(text, {}, agent?.session, undefined, config.id)).text
+    const result = evaluateTemplate(text, { module: snapshot.module, global: snapshot.global, session: agent?.session,
+      sourceId: `${config.sourceModuleId ?? ''}:${config.id}`, readOnly: execution === undefined, samples })
+    const entry = { text: stripUnresolvedRefs(result.text).text, pending: false }
+    if (result.changes) {
+      if (!variableStore?.commit) throw new Error('Persistent template writes require a variable adapter')
+      signal?.throwIfAborted()
+      const domains = new Set([...result.reads, result.changes.scope])
+      const expectedRevisions = Object.fromEntries([...domains].map(domain => [domain, snapshot.revisions[domain]]))
+      if (snapshot.revisions.settings !== undefined) expectedRevisions.settings = snapshot.revisions.settings
+      try {
+        const saved = variableStore.commit(config.sourceModuleId, { scope: result.changes.scope, changes: result.changes.values, expectedRevisions })
+        entry.pending = saved.publicationPending === true
+      } catch (error) {
+        if (error?.persisted === true) entry.pending = true
+        else if (error?.status === 409 && attempt < 2) continue
+        else throw error
+      }
+    }
+    frame?.cards.set(identity, entry)
+    if (entry.pending) warn(`Template ${config.id}: variables saved; publication pending`)
+    return entry.text
+  }
+  throw new Error('Template variable commit conflict')
+}

package/engine/tool-config-engine.mjs

@@ -14,7 +14,7 @@
  *   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 内）
+ *   fs       — 文件操作（read/write/append/list/delete，真实路径限定 cwd 内）
  *   ask-user — approval 通道询问用户（结果文本化）
  *
  * 安全：行 config.requireApproval = [kind...] 时该执行器先过 approval 门
@@ -22,22 +22,22 @@
  * 工具注册经 disposer 契约（keepDisposer），插件卸载自动撤销。
  *
  * ── 能力提供者边界（T4）────────────────────────────────────────────────────
- * 本模块是**能力提供者**，不是触发器。分类判据（与组合源 tool-config-engine.yml、
- * subagent-tool-policy.yml 及 test/engine/provider-boundary.test.mjs 同一份措辞）：
+ * 本模块是**能力提供者**，不是触发器。分类判据（与组合源 tool-config-engine.yml
+ * 同一份措辞）：
  *   - 会给模型提供可调用能力（注册工具 / 域 / 服务）的 → 能力提供者；
  *   - 干预流程（改提示词、改装配、裁决、追加）的 → 声明式触发器。
  * 因此本模块**不接入** engine/trigger.mjs：它不订阅装配 waterfall，也没有
- * when/do 声明，只在装配期把 module.yml 的 customTools 段编译出的工具注册进官方
+ * 声明式触发器（`if`/`then` 声明），只在装配期把 module.yml 的 customTools 段编译出的工具注册进官方
  * registry。强行并进触发器会让引擎同时承担「提供能力」与「干预流程」两种职责。
  *
  * 样板收敛：
  *   - 配置声明走 fields.mjs 的 `defineConfig`（未知键在挂载期 fail loud）；
  *   - 注册走 disposer 契约：单次注册用 shared.keepDisposer（register() 返回的正是
  *     它自己的 effect disposer）；需要整组原子回滚或定向撤销句柄时才用 ctx.effect；
- *   - 降级告警统一 `${name}: <what>; <fallback>` 一个前缀格式（见 provider-boundary 用例）。
+ *   - 降级告警统一 `${name}: <what>; <fallback>` 一个前缀格式。
  *
- * 登记入口：`engineProvider`（数据导出），供边界守卫消费。提供者登记与声明式触发器
- * 声明（约定为 `engineTriggers`）**互斥**，同一模块不得同时导出两者。
+ * 能力提供：把 module.yml 的 customTools 段注册进官方 tools registry；模型可见工具名
+ * 在装配期决定，引擎侧无法静态枚举（本模块不导出 provider 登记）。
  *
  * 文件归属校正（PLAN T4）：第三个指定提供者 str-replace-editor 由
  * engine/compositions/source/local/filesystem-editor.yml:20 引用**官方**包
@@ -46,11 +46,12 @@
  */
 
 import { readFileSync, readdirSync, writeFileSync, appendFileSync, rmSync, statSync } from 'node:fs'
-import { execFile } from 'node:child_process'
+import { execFile, execFileSync } 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 { resolveRealWithin } from './path-safety.mjs'
 import { validateDefinition } from './tool-definition.mjs'
 import { defineConfig, passthrough } from './fields.mjs'
 import { keepDisposer } from './shared.mjs'
@@ -68,6 +69,24 @@ const ENV_ALLOWLIST = [
   'USERPROFILE', 'HOME', 'DSH_HOME', 'DSH_WORKSPACE', 'DSH_SESSION_ID',
 ]
 
+/**
+ * shell 输出上限（stdout/stderr 各自）：超限时 execFile 以
+ * ERR_CHILD_PROCESS_STDIO_MAXBUFFER 失败并保留截断输出，错误文本说明原因。
+ */
+const SHELL_MAX_OUTPUT_BYTES = 1024 * 1024
+
+/** 超时尽量结束整棵子进程树；Windows 用 taskkill /T，失败再退回 child.kill。 */
+function killShellTree(child) {
+  if (child === undefined || child.pid === undefined) return
+  if (process.platform === 'win32') {
+    try {
+      execFileSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true })
+      return
+    } catch { /* taskkill 不可用时退回单进程 kill */ }
+  }
+  try { child.kill() } catch { /* 已退出 */ }
+}
+
 /** 插值 {{args.x.y}} → 参数深取值（缺失保留字面）。 */
 function interpolateArgs(text, args) {
   return String(text ?? '').replace(/\{\{args\.([A-Za-z0-9_.]+)\}\}/g, (_whole, path) => {
@@ -163,16 +182,6 @@ async function approvalGate(ctx, exec, kind, reason) {
   return { ok: false, message: `approval for tool ${exec.name} was ${outcome}` }
 }
 
-/** cwd 内路径限定（防越界；resolve 后必须位于 cwd 之下）。 */
-function withinCwd(cwd, target) {
-  const resolved = resolve(cwd, target)
-  const root = resolve(cwd)
-  if (resolved !== root && !resolved.startsWith(root + sep)) {
-    throw new Error(`path ${JSON.stringify(target)} escapes the workspace`)
-  }
-  return resolved
-}
-
 /** delegate args 映射：完整引用（{{args.x}}）透传原始类型（数组/数字/布尔不字符串化）；
  *  部分引用（前缀-{{args.x}}）插值为字符串；非插值值原样。 */
 function mapDelegateArgs(execArgs, args) {
@@ -231,18 +240,25 @@ function createExecute(ctx, def, requireApproval) {
       const env = { ...Object.fromEntries(ENV_ALLOWLIST.filter((key) => process.env[key] !== undefined).map((key) => [key, process.env[key]])), ...(exec.env ?? {}) }
       const output = await new Promise((resolvePromise) => {
         let killTimer
-        const child = execFile(shell, argv, { cwd, env, windowsHide: true }, (error, stdout, stderr) => {
+        let timedOut = false
+        const child = execFile(shell, argv, { cwd, env, windowsHide: true, maxBuffer: SHELL_MAX_OUTPUT_BYTES }, (error, stdout, stderr) => {
           clearTimeout(killTimer)
+          // 超时被杀与输出超限都不是普通退出码：error 文本必须能区分二者（不新增输出字段）。
+          const reason = error === null ? undefined
+            : timedOut ? `shell command timed out after ${def.timeoutMs} ms and was killed`
+              : error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
+                ? `shell command output exceeded ${SHELL_MAX_OUTPUT_BYTES} bytes (truncated)`
+                : String(error.message)
           resolvePromise({
             exitCode: error === null ? 0 : (typeof error.code === 'number' ? error.code : 1),
             stdout: String(stdout ?? ''),
             stderr: String(stderr ?? ''),
-            ...(error === null ? {} : { error: String(error.message) }),
+            ...(reason === undefined ? {} : { error: reason }),
           })
         })
         const timeout = def.timeoutMs
         if (timeout !== undefined && Number.isSafeInteger(timeout) && timeout > 0) {
-          killTimer = setTimeout(() => child.kill(), timeout)
+          killTimer = setTimeout(() => { timedOut = true; killShellTree(child) }, timeout)
         }
       })
       return output
@@ -292,7 +308,8 @@ function createExecute(ctx, def, requireApproval) {
     if (exec.kind === 'fs') {
       const cwd = run.agent?.session?.header?.cwd ?? process.cwd()
       try {
-        const file = withinCwd(cwd, interpolateArgs(exec.path, args))
+        // 词法 resolve 挡不住 symlink/junction：统一用真实路径判定，不存在的目标按父目录解析。
+        const file = resolveRealWithin(resolve(cwd, interpolateArgs(exec.path, args)), [cwd])
         const action = interpolateArgs(exec.action, args)
         if (action === 'read') {
           const raw = readFileSync(file, 'utf8')
@@ -423,19 +440,6 @@ export const configContract = {
   },
 }
 
-/**
- * 能力提供者登记（T4 边界守卫的数据源）。
- * `provides.kind === 'dynamic'`：模型可见的工具名由 module.yml 的 customTools 段在
- * 装配期决定，引擎侧无法静态枚举——守卫只断言登记形状、
- * 注册通道，以及「提供者不导出触发器声明」这条互斥。
- */
-export const engineProvider = {
-  kind: 'provider',
-  moduleId: name,
-  registers: 'tools',
-  provides: { kind: 'dynamic', source: 'module.yml#customTools → tools' },
-}
-
 /** 插件入口：优先注册内联 tools，缺字段时兼容 configsDir。 */
 export function apply(ctx, config) {
   const source = configContract.parse(config, name)

package/engine/tool-definition.d.mts

@@ -0,0 +1,4 @@
+/** `tool-definition.mjs` 的手写声明：只声明 `src/` 消费的导出。 */
+
+/** 完整定义校验；非法定义抛 `TypeError`，合法定义无返回值。 */
+export function validateDefinition(def: unknown): void

package/engine/tool-definition.mjs

@@ -62,7 +62,7 @@ export function validateDefinition(def) {
     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)`)
+    throw new TypeError(`tool ${def.id}: customTools.scope is not supported (a custom tool carries no per-tool scope)`)
   }
   if (def.parameters !== undefined) {
     validateJsonSchemaNode(def.parameters, `tool ${def.id}: parameters`)
@@ -88,6 +88,10 @@ export function validateDefinition(def) {
   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 === 'delegate' && ['character_import', 'character_list', 'character_apply', 'character_remove', 'character_delete',
+    'world_book_list', 'world_book_upsert', 'world_book_delete', 'world_book_read_memory', 'session_var'].includes(exec.tool)) {
+    throw new TypeError(`tool ${def.id}: delegate ${exec.tool} 已退役；请重新导入或显式转换为模块工具`)
+  }
   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`)

package/engine/tool-git-bash.mjs

@@ -133,12 +133,16 @@ const commandSchema = {
       type: 'string',
       description: 'The bash command to execute (`bash -c` string domain).',
     },
+    description: {
+      type: 'string',
+      description: 'Clear, concise description of what this command does, 5-10 words (shown in the UI).',
+    },
     workdir: {
       type: 'string',
       description: 'Optional working directory; defaults to the session cwd. On Windows, Git Bash paths like /e/foo are accepted and converted to E:\\foo.',
     },
   },
-  required: ['command'],
+  required: ['command', 'description'],
   additionalProperties: false,
 }
 

package/engine/tool-scope.mjs

@@ -0,0 +1,22 @@
+/**
+ * tool-scope — 工具面的作用域快照，避免各消费方把全局视图当成模型可见面。
+ *
+ * 返回两个字段，各自只服务一个调用方：
+ * - visible：带 agent 的 `tools.schemas(agent)`，包含预设/祖先/本层工具；模型可见面。
+ * - globalNames：不带 scope 的 `tools.schemas()` 名字集合；只供 `restrict` 过滤已知名。
+ *
+ * 全局原始 schema 与 visible-only 差集不外露；等真实诊断消费方出现再加字段。
+ */
+
+const schemaList = (tools, scope) => {
+  if (typeof tools?.schemas !== 'function') return []
+  const schemas = tools.schemas(scope)
+  return Array.isArray(schemas) ? schemas : []
+}
+
+export function toolScopeSnapshot(tools, agent) {
+  const global = schemaList(tools)
+  const visible = agent === undefined ? global : schemaList(tools, agent)
+  const globalNames = new Set(global.map((schema) => schema?.name).filter((name) => typeof name === 'string'))
+  return { visible, globalNames }
+}