dsh-plugin-prompt-tool 2.1.0 → 3.0.0

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,8 +22,8 @@
  * 工具注册经 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，也没有
@@ -34,10 +34,10 @@
  *   - 配置声明走 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 }
+}

package/engine/{dev-tool-search.mjs → tool-search.mjs}

@@ -6,8 +6,9 @@
  *
  * 两个动作合一：
  *  - `query` 关键词搜索**完整装配目录**（只回名字 + 一行截断描述，不回 parameters）；
- *  - `toolNames` 按**精确名**解锁。解锁名写进本次 `tool/call` 的持久参数，
- *    `assembly.target.tools.allowFrom` 从那里读回 → 下次请求起生效，且跨压缩保留。
+ *  - `toolNames` 按**精确名**解锁。解锁名写进本次调用的持久参数（顶层 `tool/call`；
+ *    PTC 嵌套为 `tool/ptc-dispatch`），发现消费方的 allowExtra 从那里读回 → 下次请求起
+ *    生效，且跨压缩保留。
  *
  * **能力摘要来自运行时截获，不手工维护**（2026-10-05 用户指出）：空查询时按前缀把
  * `ctx.tools.schemas()` 的可见目录折叠成分组摘要（`mcp__github__* ×46`，实测 433 字符
@@ -15,17 +16,22 @@
  * 名字写错还会让模型照着错名字解锁（那份实现甚至需要一条专门测试来防错名）。
  * 官方注册表只投影 name/description（无分组字段），所以分组只能按前缀在本地折叠。
  *
- * 与原 `dev-tool-search.mjs` 的两处修正照搬：
+ * 与原 `tool-search.mjs` 的两处修正照搬：
  *  1. 匹配是**打分**而非 AND 过滤——长自然语言查询（"file edit write replace"）在
  *     AND 口径下命中零个，等于白搜。现在精确名优先，其次按命中 token 数排序。
  *  2. 描述里显式教解锁路径（"搜索为空 ≠ 工具不存在"）——实测模型只会搜、不会传
  *     toolNames，于是收窄后永远拿不到工具。
  */
-export const name = 'dev-tool-search'
+export const name = 'tool-search'
 
 /** 工具注册表必须先于本工具存在（同 skill-search 的 inject 纪律）。 */
 export const inject = ['tools']
 
+import { toJsonSchema } from './shared.mjs'
+import { renderRows, rankRows, scoreRows, queryTokens } from './discovery.mjs'
+import { toolScopeSnapshot } from './tool-scope.mjs'
+import { DISCOVERY_SERVICE } from './service-names.mjs'
+
 /** 单次搜索结果上限：再多就该让模型收窄关键词。 */
 export const MAX_RESULTS = 25
 
@@ -36,31 +42,17 @@ const DESC_LIMIT = 90
 const MAX_GROUPS = 24
 
 /** 常驻核心集：由工具面收窄模板声明，这里只在描述里如实告知模型。 */
-const RESIDENT = ['pwsh', 'read', 'write', 'edit', 'glob', 'grep', 'todo_write', 'skill_search', 'skill_load']
-
-/** 零依赖的最小 JSON schema 编译器（与 skill-search 同构）。 */
-function toJsonSchema(spec) {
-  const properties = {}
-  const required = []
-  for (const [key, meta] of Object.entries(spec || {})) {
-    const prop = { type: meta.type }
-    if (meta.description) prop.description = meta.description
-    if (meta.items) prop.items = meta.items
-    properties[key] = prop
-    if (meta.required) required.push(key)
-  }
-  return { type: 'object', properties, required, additionalProperties: false }
-}
+const RESIDENT = ['bash', 'pwsh', 'read', 'write', 'edit', 'glob', 'grep', 'todo_write', 'skill_search', 'skill_load']
+
+/** 参数 schema 由 `shared.mjs` 的统一实现生成（与 `skill-search` 同一份）。 */
 
 /**
- * 能力索引：常驻核心集（pwsh / read / write / edit / glob / grep / todo_write /
+ * 能力索引：常驻核心集（bash / pwsh / read / write / edit / glob / grep / todo_write /
  * skill_search / skill_load）覆盖不到的能力。名字全部取自实测工具面。
  */
 
-/** 把查询切成小写 token（Unicode 字母数字与下划线连字符，与 skill-search 同口径）。 */
-export function queryTokens(query) {
-  return (typeof query === 'string' ? query : '').toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(Boolean)
-}
+/** 查询分词由发现引擎统一实现（与技能面同一口径）。 */
+export { queryTokens }
 
 /**
  * 一个工具名的分组键：MCP 工具折到服务级（`mcp__github__*`），其余折到首个下划线段
@@ -102,17 +94,10 @@ export function summarizeCatalog(schemas) {
  * `wanted` 为空时返回空数组——调用方据此区分「没给查询」与「没搜到」。
  */
 export function scoreTools(schemas, wanted) {
-  if (!Array.isArray(schemas) || wanted.length === 0) return []
-  return schemas
-    .map((schema) => {
-      const name = typeof schema?.name === 'string' ? schema.name : ''
-      const haystack = `${name} ${schema?.description ?? ''}`.toLowerCase()
-      let score = 0
-      for (const token of wanted) if (haystack.includes(token)) score += 1
-      return { schema, name, score, exact: wanted.includes(name.toLowerCase()) }
-    })
-    .filter((entry) => entry.name.length > 0 && (entry.exact || entry.score >= 1))
-    .sort((a, b) => (b.exact - a.exact) || (b.score - a.score) || a.name.localeCompare(b.name))
+  return rankRows(scoreRows(schemas, wanted, {
+    nameOf: (schema) => schema?.name,
+    haystackOf: (schema) => `${schema?.name ?? ''} ${schema?.description ?? ''}`,
+  })).map((row) => ({ ...row, schema: row.item }))
 }
 
 /** 解锁名单归一：只留非空字符串，去重保序。 */
@@ -129,46 +114,38 @@ export function unlockNames(value) {
 
 /** 把目录搜索结果渲染成给模型的文本（带截断提示与解锁引导）。 */
 export function renderMatches(scored, query) {
-  const lines = []
-  const matches = scored.slice(0, MAX_RESULTS)
-  if (matches.length === 0) {
-    lines.push(
-      `No tools match "${query}". An empty result only means no tool matched your keywords — if you need a specific tool, unlock it directly by exact name, e.g. dev_tool_search({"toolNames":["web_search"]}).`,
-    )
-    return lines
-  }
-  lines.push(`Matching tools (${matches.length}${scored.length > MAX_RESULTS ? ` of ${scored.length}` : ''}):`)
-  for (const { schema, name, exact } of matches) {
-    const desc = String(schema?.description ?? '').split('\n')[0].slice(0, DESC_LIMIT)
-    lines.push(`- ${name}${exact ? ' (exact)' : ''}: ${desc}`)
-  }
-  if (scored.length > MAX_RESULTS) {
-    lines.push(`(truncated at ${MAX_RESULTS} — add tokens to narrow the query)`)
-  }
-  lines.push('Unlock with dev_tool_search({"toolNames": ["<exact name>"]}).')
-  return lines
+  return renderRows(scored, {
+    query,
+    limit: MAX_RESULTS,
+    noun: 'tools',
+    emptyText: `No tools match "${query}". An empty result only means no tool matched your keywords — if you need a specific tool, unlock it directly by exact name, e.g. tool_search({"toolNames":["web_search"]}).`,
+    lineOf: ({ schema, name, exact }) => `- ${name}${exact ? ' (exact)' : ''}: ${String(schema?.description ?? '').split('\n')[0].slice(0, DESC_LIMIT)}`,
+    footer: 'Unlock with tool_search({"toolNames": ["<exact name>"]}).',
+  })
 }
 
-/** 注册模型可见的 `dev_tool_search`。 */
-export function apply(ctx) {
-  ctx.tools.register({
-    name: 'dev_tool_search',
+/** 注册模型可见的 `tool_search`。 */
+export function createToolSearchDefinition(ctx, options = {}) {
+  const resident = options.resident ?? RESIDENT
+  const unlockKey = options.unlockKey ?? 'toolNames'
+  return {
+    name: options.tool ?? 'tool_search',
     description: [
       'Discover and unlock tools that are NOT currently available.',
       '',
-      `This session starts with a minimal resident set: ${RESIDENT.join(', ')}. Everything else is unlocked on demand through this tool.`,
+      `This session starts with a minimal resident set: ${resident.join(', ')}. Everything else is unlocked on demand through this tool.`,
       '',
       'Usage:',
       '- `query` — search the catalog by keyword (matches tool names AND descriptions, 1-2 short words work best).',
       '- call with NO arguments — list the catalog as group counts (`<prefix>_*(count) ...`), so you can see what exists before searching.',
-      '- `toolNames` — unlock exact names. Unlocked tools appear from the NEXT request on and stay unlocked for the session.',
+      `- \`${unlockKey}\` — unlock exact names. Unlocked tools appear from the NEXT request on and stay unlocked for the session.`,
       '',
-      'Example: dev_tool_search({"query":"pull request","toolNames":["mcp__github__create_pull_request"]}) — search AND unlock in one call.',
-      'IMPORTANT: an empty search result does NOT mean the tool does not exist — it only means no tool matched your keywords. Call with no arguments to see the catalog groups, then unlock by exact name.',
+      `Example: ${options.tool ?? 'tool_search'}({"query":"pull request","${unlockKey}":["mcp__github__create_pull_request"]}) — search AND unlock in one call.`,
+      'IMPORTANT: if the task needs a capability outside that resident set — web search, subagents, task boards, MCP servers, anything not listed above — search for it here and unlock it. Do NOT make do with a resident tool when the tool you actually need is merely locked; an empty search result does NOT mean the tool does not exist, it only means no tool matched your keywords. Call with no arguments to see the catalog groups, then unlock by exact name.',
     ].join('\n'),
     parameters: toJsonSchema({
       query: { type: 'string', required: false, description: 'search keywords (e.g. "web", "subagent", "github")' },
-      toolNames: {
+      [unlockKey]: {
         type: 'array',
         required: false,
         items: { type: 'string' },
@@ -181,7 +158,7 @@ export function apply(ctx) {
     },
     async execute(args, exec) {
       const query = typeof args?.query === 'string' ? args.query.trim() : ''
-      const unlock = unlockNames(args?.toolNames)
+      const unlock = unlockNames(args?.[unlockKey])
       const lines = []
       // 解锁动作本身不需要任何运行时服务：引擎的 allowFrom 只读本工具的持久调用参数，
       // 所以即便目录不可用（无 tools 服务/无 agent），解锁也必须照样回报成功。
@@ -191,7 +168,7 @@ export function apply(ctx) {
       try {
         // 执行中的 agent 就是观察作用域：preset 工具注册在 agent scope 层，
         // 不带 scope 的 schemas() 只看全局层，会漏掉它们。
-        schemas = ctx.tools.schemas(exec?.agent)
+        schemas = toolScopeSnapshot(ctx.tools, exec?.agent).visible
       } catch (error) {
         return { text: [...lines, `catalog search unavailable: ${String(error?.message ?? error)}`].join('\n') }
       }
@@ -209,5 +186,26 @@ export function apply(ctx) {
       lines.push(...renderMatches(scoreTools(schemas, queryTokens(query)), query))
       return { text: lines.join('\n') }
     },
-  })
+  }
 }
+
+/** 本引擎向发现注册表提供的元数据：工具名与「解锁名单从哪个参数回收」。 */
+export const discoveryAdapter = Object.freeze({
+  kind: 'tools',
+  tool: 'tool_search',
+  unlock: Object.freeze({ tool: 'tool_search', key: 'toolNames' }),
+})
+
+/**
+ * 组合源入口：注册工具（行语义不变），并向发现注册表登记元数据。
+ * 注册表由宿主 root provide；引擎单独使用时它不存在，跳过登记即可。
+ */
+export function apply(ctx, _config, options = {}) {
+  const registered = ctx.tools.register(createToolSearchDefinition(ctx))
+  const registry = typeof ctx.get === 'function' ? ctx.get(DISCOVERY_SERVICE) : undefined
+  const disposeAdapter = registry === undefined ? undefined : registry.register(options.agent, 'tools', discoveryAdapter)
+  return () => {
+    if (typeof disposeAdapter === 'function') disposeAdapter()
+    if (typeof registered === 'function') registered()
+  }
+}