dsh-task-guard 0.0.0-stage → 0.6.2

package/README.md

@@ -1,3 +1,161 @@
-# Temporary Holding Version
+# dsh-task-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**任务级工具收窄**：任务开始时按 `groups` 收窄一次工具表，任务结束时恢复。零依赖，纯 Node 内置模块。
+
+> 它不是"又一个任务系统"。它只守一条线：**工具表在一个任务里只准改一次**。
+> 因为每改一次就是一次全价前缀重建——本机实测单次最高 56 万 token 全价。
+
+## 三条铁律（这插件全部价值都在这三条）
+
+| 铁律 | 为什么 |
+|---|---|
+| **只用 `deny`，绝不用 `allow`** | `restrict({allow})` 会藏掉**点不出名字**的工具（作用域本地注册的 `read`/`write`/`send_message`）。实测 4/4 会话丢 `read`，其中一个连 `send_message` 都没了 → 子代理干完活回不来 → **死锁** |
+| **一个任务只收窄一次** | 每次改工具表 = 前缀指纹变化 = 一次全价重建 |
+| **永不 `deny` 逃生门** | `run_code` 写进列表会**直接抛错**（静默不裁剪）；`subagent`/`send_message` 藏了就断掉委派；`route_*`/`guard_*`/`cache_probe_*` 是你出问题时唯一的退路 |
+
+## 三个工具
+
+| 工具 | 作用 |
+|---|---|
+| `task_start({ groups, goal? })` | 抢锁 → 收窄一次 → 记账。`groups` 为空直接拒绝（歧义不猜） |
+| `task_end()` | 拆限制 → 放锁 → 记账（耗时、摘了多少） |
+| `task_status()` | 只读：当前任务、谁持有跨进程锁、状态目录在哪 |
+
+## 安装
+
+```bash
+# 开发期（link 安装，改代码后 disable→enable 生效）
+dsh plugin --profile desktop add link:C:/path/to/dsh-task-guard
+
+# 或手工：把目录加进 profile 的 dependencies 与 dsh.profile.bundles
+```
+
+`cordis.patch.yml` 顶层必须是数组：
+
+```yaml
+- insert:
+    - id: task-guard
+      name: dsh-task-guard
+      config:
+        lockTtlHours: 6
+```
+
+## 状态文件（都在 `~/.dsh/task-guard/`）
+
+| 文件 | 内容 |
+|---|---|
+| `active.lock` | 跨进程任务锁：`{ taskId, pid, startedAt, groups }`，原子写（tmp + rename） |
+| `usage.jsonl` | 每次 `start` / `end` 一行，带 `taskId`、`denyCount`、`durationMs`，字段名与 minimal-router 的探针记录保持一致，便于一起分析 |
+| `current.json` | 给 UI 的快照：`active`、`groups`、`denyCount`、`keptCount`、`keptTools`、`deniedTools`、`savingsPerTurn`… |
+| `tool-registry.json` | **全量工具清单**（v0.5.0）：`task_start`（**含 dryRun**）时写入，任务结束也不删。认领建议和徽章空态都靠它 |
+| `mode.json` | `{"mode":"auto"\|"manual"}`（v0.6.0）：**谁来决定工具表**。徽章写，minimal-router 读 |
+| `request.json` | UI 发来的手动动作（v0.6.0）：`{id, action:'start'\|'end', groups, ts}` |
+| `request-result.json` | 上一次动作的结果：`{id, ok, error}`，UI 用它显示成功/失败原因 |
+
+> 放家目录而不是包目录：包目录在 pnpm 安装下是只读的，写进去升级就丢。
+> 测试可用 `TASK_GUARD_DIR` 环境变量覆盖。
+
+### UI 请求通道（v0.6.0）
+
+浏览器调不了工具，所以徽章的动作走"文件邮箱"：
+
+```
+徽章面板 → POST /task-guard/action（badge 插件的 host 路由）
+        → 写 request.json
+        → 本插件在**下一次 tools/pre-execute** 里消费
+        → restrict({deny}) / dispose()  → 写 request-result.json
+```
+
+**为什么是 pre-execute**：`restrict()` 必须作用在 `agent.ctx.tools` 上，而 pre-execute 是
+唯一每轮都会发生、且能拿到那个作用域的位置（不用额外起定时器）。
+
+三条保护：超过 60 秒的请求不执行、同一个 `id` 只执行一次、失败把原因写进结果文件。
+
+
+## 成本闸门（v0.2.0）
+
+收窄 = **一次全价前缀重建**，而省下来的钱是**每轮**的。所以它有个回本点。
+
+本机实测（2026-10-31，一次真实收窄）：
+
+```
+272 个工具 / 232,458 字节  →  78 个 / 57,883 字节   （摘掉 174,575 字节，−75.1%）
+那一次请求：promptTokens 285,701，cacheRead 仅 4,608  →  命中率 1.61%
+一次性成本 ≈ 28.1 万全价 token；每轮省 ≈ 5.2 万 → 回本 ≈ 5.4 轮
+```
+
+所以 `task_start` 加了闸门（实现见 `lib/cost-gate.js`）：
+
+| 条件 | 行为 |
+|---|---|
+| 上下文 > 200,000 token **且** 预估轮数 < 6 | **拒绝**，报 `COST_GATE`，提示跑不够就亏 |
+| 同上但传 `force: true` | 放行（你自己认这笔账） |
+| 没传 `contextTokens` | 放行，但如实说"算不出来"，并告诉你数据从哪取 |
+| 本来就没东西可摘 | 放行（没有切换成本） |
+
+```jsonc
+task_start({
+  "groups": ["unity"],
+  "contextTokens": 285701,   // 从 cache_probe_report 的 lastPromptTokens 取
+  "turns": 12,               // 预估轮数
+  "force": false
+})
+```
+
+返回里会带上这笔账：`cost.savingsPerTurn` / `cost.paybackTurns` / `cost.message`。
+
+## 先看后付：`dryRun`（v0.3.0）
+
+**起因是一次真实事故**：一次 `groups:["unity"]` 摘掉 194 个工具——连带摘掉了
+`plugin_manager`（标签 `plugin`）和 `cordis_inspect_*`（标签 `cordis`），
+而那正是当时在做的事。**是用户看截图发现的，插件自己不知道。**
+
+根因不是逻辑错，是**调用方不知道有哪些组可以选**："开发 DSH 插件"这个领域在工具表里
+没有对应标签，它的工具散在 `plugin` / `cordis` / `web` / `skill` 里。
+
+所以加了 `dryRun`（**成本 0**：不抢锁、不动工具表、不写任务状态）：
+
+```jsonc
+task_start({ "groups": ["core", "plugin", "cordis"], "dryRun": true })
+```
+
+| 返回字段 | 含义 |
+|---|---|
+| `availableGroups` | **这台机器上真实存在的组**（组名 → 工具数，降序） |
+| `foundGroups` / `missingGroups` | 你点名的组里，哪些存在、哪些写错了 |
+| `willKeep` / `willDeny` | 会保留几个、摘掉几个 |
+| `keepSample` / `denySample` | 各给 8 个样例（不用翻全表） |
+| `cost` | 回本账（即使闸门会拒，也照样算给你看） |
+
+**正确姿势：先 `dryRun` 看清单 → 改对了再去掉 `dryRun` 真开。**
+
+## 多领域的唯一纪律
+
+| 场景 | 做法 |
+|---|---|
+| 开头就知道要跨领域 | **开头取并集**（`["unity","art"]`），一次收窄 |
+| 中途才跨领域 | **不要重开任务**（再付一次重建）。要么接受工具不够，要么 `task_end` 后重开 |
+| 完全不确定 | 先 `dryRun` 看清楚，别急着开 |
+
+> **铁律：任务中途永远不改工具表。** 多领域靠"开头想清楚"，不靠"动态调整"。
+
+> **为什么不做成"永远拦"**：数据不全时拦人 = 让人以为插件坏了。
+> 拿不到就明说"算不出来"，把判断权交回去。
+
+## 已知边界（写在前面）
+
+1. **跨进程锁是"全机器一把"**：同一台机器同时只允许一个任务。同进程多会话由内存 Map 守卫。
+2. **只按 `deny` 算**：如果某个工具不在这个 agent 的注册表里、但存在于更大的全局表，我们摘不掉它——结果是**欠收窄**（安全方向），不是错杀。
+3. **不碰 prompt**：它不往上下文里塞一个字（可选的尾巴提示默认关）。
+4. **`taskId` 写在自己文件的 `usage.jsonl` 里**，不写入 minimal-router 的探针文件（避免跨插件写别人的数据）。要对齐两边，用 `at` 时间窗口 join，或给 router 的探针加一个扩展点。
+
+## 测试
+
+```bash
+node test/task-guard.test.mjs   # 12 项，零依赖（node:test）
+```
+
+## 规模
+
+- `index.js`：**347 行代码**（不含注释）+ 178 行中文注释
+- 依赖：**0**

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-task-guard · 任务级工具收窄
+# 顶层必须是数组；新增插件写 - insert: 再挂一个列表（写成 mapping 会被 Loader 拒绝）。
+- insert:
+    - id: task-guard
+      name: dsh-task-guard
+      config:
+        # 任务锁的存活上限（小时）。超过这个时间即使 pid 还活着，也当成僵尸锁回收。
+        lockTtlHours: 6
+        # 每轮末尾的尾巴提示开关（默认关：本插件不往上下文里塞东西）
+        hintEnabled: false

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="T">
+  <rect x="2" y="2" width="60" height="60" rx="16" fill="#22C55E"/>
+  <text x="32" y="43" text-anchor="middle" font-family="Segoe UI, Helvetica, Arial, sans-serif"
+        font-size="30" font-weight="600" fill="#ffffff">T</text>
+</svg>

package/index.js

@@ -0,0 +1,814 @@
+/**
+ * ============================================================================
+ * dsh-task-guard · 任务级工具收窄（300 行的护城河）
+ * ============================================================================
+ * 这个插件只干一件事：**任务开始时按 groups 收窄一次工具表，任务结束时恢复。**
+ *
+ * ---------------------------------------------------------------------------
+ * 为什么只做这一件事
+ * ---------------------------------------------------------------------------
+ * 在 DSH 里，改工具表 = 前缀指纹变化 = 一次**全价重建**。本机实测：一次重载
+ * 563,654 token 全价（命中率 0.97%）；长会话里一次重建能到几十万 token。
+ * 所以"收窄"只在**任务开头**做**一次**，中途绝不调整——这就是它跟市面那堆
+ * "每轮按任务改工具表"的插件的根本区别。
+ *
+ * ---------------------------------------------------------------------------
+ * 为什么只用 deny，绝不用 allow（这是踩出来的，不是理论）
+ * ---------------------------------------------------------------------------
+ * restrict({ allow }) 的语义是"只留我点名的"。而 read / write / send_message
+ * 这类**作用域本地注册**的工具不在 restrictableNames 里——我们点不出名字，
+ * 它们就会被"只留点名的"一起藏掉。
+ * 实测 4/4 个会话丢掉 read（报 unknown tool "read"），其中一个连 send_message
+ * 都没了 → 子代理干完活无法回报 → **父代理永远等不到 → 死锁**。
+ *
+ * ---------------------------------------------------------------------------
+ * 为什么这些工具永远不 deny
+ * ---------------------------------------------------------------------------
+ *   run_code      DSH 硬拦截：把它写进 allow/deny 会直接抛错，而我们外层是
+ *                 try/catch，表现就是"静默不裁剪"
+ *   subagent /   藏了它们 = 断掉委派与回报 = 死锁
+ *   send_message
+ *   route_* /    逃生门与仪表：出问题时你得能切回去、能看账单
+ *   guard_* /
+ *   cache_probe_*
+ *   core 类工具  连读文件都禁掉，任务就没法干了
+ * ============================================================================
+ */
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  appendFileSync,
+  existsSync,
+} from 'node:fs'
+import { estimateTaskCost, measureDeniedBytes } from './lib/cost-gate.js'
+import { buildPreview, summarizeGroups } from './lib/scope-preview.js'
+
+/** 插件名（DSH 里用于配置定位） */
+export const name = 'task-guard'
+/**
+ * 依赖声明。
+ * 【必须是硬依赖】apply() 里要调 ctx.tools.register，而 Cordis 规定：
+ * 没在 inject 里声明的服务，访问时会抛 `cannot get property "tools" without inject`。
+ * （第一版我写成 inject = []，装上去直接报这个错——所以这条不是理论。）
+ * 不声明 systemPrompt：本插件**一个字节都不往上下文里塞**。
+ */
+export const inject = ['tools']
+
+/**
+ * 状态目录。
+ * 【为什么不在插件目录里】pnpm 安装的包目录是只读/会被覆盖的，
+ * 往包内写文件 = 升级即丢数据。必须放到用户家目录。
+ * 【为什么允许环境变量覆盖】测试要隔离，不能污染真实状态。
+ */
+export const STATE_DIR =
+  typeof process.env.TASK_GUARD_DIR === 'string' && process.env.TASK_GUARD_DIR
+    ? process.env.TASK_GUARD_DIR
+    : join(homedir(), '.dsh', 'task-guard')
+
+export const LOCK_FILE = join(STATE_DIR, 'active.lock')
+export const USAGE_FILE = join(STATE_DIR, 'usage.jsonl')
+
+/**
+ * "当前任务"快照文件。
+ * 【为什么要有它】客户端 UI（浏览器里跑的徽章）读不到 Host 进程的内存，
+ * 只能靠 HTTP 接口取状态。所以每次任务开始/结束时把快照写下来，UI 去读这个文件。
+ */
+export const CURRENT_FILE = join(STATE_DIR, 'current.json')
+/**
+ * 全量工具清单（v0.5.0）。
+ * task_start（含 dryRun）会把它写下来；task_end 不影响它。
+ * 用途：认领建议、徽章空态显示工具数——这些都不该依赖"当前是否有任务"。
+ */
+export const REGISTRY_FILE = join(STATE_DIR, 'tool-registry.json')
+/**
+ * UI 请求通道（v0.6.0）。
+ * 浏览器没法直接调工具，所以徽章把「收窄 / 恢复」写进 request.json，
+ * 本插件在下一次工具调用前消费掉（不额外起定时器）。
+ */
+export const REQUEST_FILE = join(STATE_DIR, 'request.json')
+/** 处理结果，供 UI 显示"成功/失败原因" */
+export const RESULT_FILE = join(STATE_DIR, 'request-result.json')
+
+/** 任务锁存活上限（毫秒）：超过就算僵尸锁，直接回收 */
+export const LOCK_TTL_MS = 6 * 3600 * 1000
+
+/** 永远不 deny 的**标签**：task/route/guard/cache 这几组是逃生门与仪表 */
+export const KEEP_TAGS = Object.freeze(new Set(['task', 'route', 'guard', 'cache']))
+
+/** 永远不 deny 的**具体工具名**（原因见文件头注释） */
+export const KEEP_NAMES = Object.freeze(
+  new Set(['run_code', 'subagent', 'subagent_fork', 'workflow', 'send_message', 'todo_write']),
+)
+
+/**
+ * 【DSH 强制】每个工具必须声明 output：{ schema, render }。
+ * 少了它注册直接抛 TypeError: tool "x" must declare output { schema, render, presentationMeta? }
+ * 形状和 dsh-minimal-router 里的一致（纯 JSON 文本输出）。
+ */
+const RENDER = {
+  schema: { type: 'object', additionalProperties: true },
+  render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+}
+
+// ============================================================================
+// 一、纯函数层（可单测，不碰 IO）
+// ============================================================================
+
+/**
+ * 从工具名推标签。规则和 minimal-router 保持一致：
+ *   read                        → core     （没有下划线）
+ *   unity_object_create         → unity
+ *   task_start                  → task
+ *   mcp__meshy__meshy_image_to_3d → meshy  （MCP 的组在中间）
+ * @param {string} toolName
+ * @returns {string}
+ */
+export function tagOf(toolName) {
+  if (typeof toolName !== 'string' || toolName.length === 0) return 'unknown'
+  if (toolName.startsWith('mcp__')) {
+    const parts = toolName.split('__')
+    return parts.length >= 3 && parts[1] ? parts[1] : 'mcp'
+  }
+  const cut = toolName.indexOf('_')
+  return cut <= 0 ? 'core' : toolName.slice(0, cut)
+}
+
+/**
+ * 算出要摘掉哪些工具。
+ *
+ * 【关键】这里只返回 deny 列表，**永远不构造 allow 列表**。
+ *
+ * @param {string[]} toolNames 当前这个会话能看见的工具名
+ * @param {string[]} groups 任务要保留的组
+ * @returns {{ deny: string[], kept: string[], unknownGroups: string[] }}
+ */
+export function computeDeny(toolNames, groups) {
+  const want = new Set(
+    (Array.isArray(groups) ? groups : [])
+      .map((g) => (typeof g === 'string' ? g.trim().toLowerCase() : ''))
+      .filter(Boolean),
+  )
+  const names = Array.isArray(toolNames) ? toolNames : []
+  const deny = []
+  const kept = []
+  const seenGroups = new Set()
+
+  for (const toolName of names) {
+    if (typeof toolName !== 'string' || toolName.length === 0) continue
+    const tag = tagOf(toolName)
+    seenGroups.add(tag)
+    const alwaysKeep =
+      KEEP_NAMES.has(toolName) || tag === 'core' || KEEP_TAGS.has(tag) || want.has(tag)
+    if (alwaysKeep) kept.push(toolName)
+    else deny.push(toolName)
+  }
+
+  // 用户写的组名如果在这台机器上根本不存在，要明确告诉他（否则"装了没效果"）
+  const unknownGroups = [...want].filter((g) => !seenGroups.has(g))
+  return { deny, kept, unknownGroups }
+}
+
+// ============================================================================
+// 二、IO 层（原子写 + 锁）
+// ============================================================================
+
+/** 目录按需创建（幂等） */
+export function ensureDir() {
+  mkdirSync(STATE_DIR, { recursive: true })
+}
+
+/**
+ * 原子写 JSON：先写 tmp 再 rename。
+ * 【为什么】直接 writeFileSync 在写入过程中崩溃会留下半个文件，
+ * 下次读 JSON.parse 直接抛，整个插件起不来。rename 在同一分区上是原子的。
+ */
+export function atomicWriteJson(file, value) {
+  ensureDir()
+  const tmp = `${file}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(value, null, 2), 'utf8')
+  renameSync(tmp, file)
+}
+
+/**
+ * pid 还活着吗？
+ * 【注意 EPERM】kill(pid,0) 在无权限时抛 EPERM，但那说明进程**存在**，要当活着。
+ */
+export function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return error && error.code === 'EPERM'
+  }
+}
+
+/** 读当前锁（没有/坏文件都返回 null，不抛） */
+export function readLock() {
+  try {
+    if (!existsSync(LOCK_FILE)) return null
+    return JSON.parse(readFileSync(LOCK_FILE, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 抢锁。已有一个**活着且没超时**的任务 → 抛 TASK_LOCKED。
+ * @param {{taskId:string, groups:string[], cwd?:string}} info
+ */
+export function acquireLock(info) {
+  const current = readLock()
+  if (current && current.taskId !== info.taskId) {
+    const ageMs = Date.now() - Number(current.startedAt || 0)
+    // 同进程内允许多次（不同会话各自有 Map 守卫），跨进程才靠这把锁
+    if (pidAlive(Number(current.pid)) && current.pid !== process.pid && ageMs < LOCK_TTL_MS) {
+      const error = new Error(
+        `另一个任务还在跑：${current.taskId}（pid ${current.pid}，已 ${Math.round(ageMs / 1000)} 秒）`,
+      )
+      error.code = 'TASK_LOCKED'
+      throw error
+    }
+  }
+  atomicWriteJson(LOCK_FILE, {
+    taskId: info.taskId,
+    pid: process.pid,
+    startedAt: Date.now(),
+    groups: info.groups,
+    cwd: info.cwd || '',
+  })
+}
+
+/**
+ * 放锁。只放自己那把（taskId 对不上就不动，避免把别人的锁删了）。
+ * @param {string} taskId
+ */
+export function releaseLock(taskId) {
+  const current = readLock()
+  if (!current) return false
+  if (taskId && current.taskId !== taskId) return false
+  try {
+    if (existsSync(LOCK_FILE)) writeFileSync(LOCK_FILE, '', 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 往任务流水里追加一条记录（JSONL，一行一条）。
+ * 字段刻意和 minimal-router 的探针记录保持同一套命名，方便一起分析。
+ * @param {object} record
+ */
+export function appendRecord(record) {
+  ensureDir()
+  const line = JSON.stringify({
+    v: 1,
+    at: Date.now(),
+    iso: new Date().toISOString(),
+    pid: process.pid,
+    ...record,
+  })
+  appendFileSync(USAGE_FILE, `${line}\n`, 'utf8')
+}
+
+// ============================================================================
+// 三、会话状态
+// ============================================================================
+
+/**
+ * 写"当前任务"快照（给 UI 读）。
+ * 失败不抛：UI 是锦上添花，不能因为它让任务开不起来。
+ * @param {object} state
+ */
+export function writeCurrent(state) {
+  try {
+    atomicWriteJson(CURRENT_FILE, { ...state, at: Date.now() })
+  } catch {
+    /* UI 快照失败不影响主流程 */
+  }
+}
+
+/** 每个会话当前在跑的任务：key → { taskId, groups, startedAt, dispose, applied, denyCount } */
+const activeTasks = new Map()
+
+/**
+ * 给 agent 对象分配稳定 key。
+ * 【为什么用 WeakMap】没有 id 的 agent（测试里常见）如果退化成同一个字符串，
+ * 多会话状态会互相污染——minimal-router 在这上面踩过坑。
+ */
+const agentKeys = new WeakMap()
+let agentSeq = 0
+
+export function keyOf(exec) {
+  const agent = exec && exec.agent
+  if (agent && typeof agent === 'object') {
+    let key = agentKeys.get(agent)
+    if (!key) {
+      agentSeq += 1
+      key = `agent-${agentSeq}`
+      agentKeys.set(agent, key)
+    }
+    return key
+  }
+  const sessionId = exec && exec.sessionId
+  return `session-${typeof sessionId === 'string' && sessionId ? sessionId : 'unknown'}`
+}
+
+/** 生成任务 id：时间可读 + 随机后缀防撞 */
+function newTaskId() {
+  return `tg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`
+}
+
+// ============================================================================
+// 四、插件入口
+// ============================================================================
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{lockTtlHours?: number}} config
+ */
+export function apply(ctx, config = {}) {
+  ensureDir()
+
+  // 【卸载保护】插件被禁用/热重载时，必须把工具表还回去。
+  // 否则会出现"任务没结束但限制永远留着"——最恶心的一种残留。
+  ctx.effect(
+    () => () => {
+      for (const [key, task] of activeTasks) {
+        try {
+          if (typeof task.dispose === 'function') task.dispose()
+        } catch {
+          /* 卸载时的异常不该影响主流程 */
+        }
+        releaseLock(task.taskId)
+        appendRecord({ event: 'end', taskId: task.taskId, reason: 'plugin-teardown', key })
+        activeTasks.delete(key)
+      }
+    },
+  )
+
+  // --------------------------------------------------------------------------
+  // task_start —— 开任务 + 收窄一次
+  // --------------------------------------------------------------------------
+  ctx.effect(() =>
+    ctx.tools.register({
+      name: 'task_start',
+      output: RENDER,
+      description:
+        'Start a task and narrow the visible tool groups once (deny-only). Tools outside the named groups are removed for the duration of the task and restored by task_end. Call this once at the beginning — do not re-narrow mid-task (each change costs a full-price prefix rebuild).',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          groups: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Tool groups to keep for this task, e.g. ["unity","asset"]. Base tools, route_*/guard_*/cache_probe_* are always kept.',
+          },
+          goal: {
+            type: 'string',
+            description: 'Optional one-line goal, recorded in the usage log.',
+          },
+          contextTokens: {
+            type: 'integer',
+            description:
+              'Current context size in tokens (take lastPromptTokens from cache_probe_report). Narrowing costs one full-price rebuild of about this size, so it is needed to decide whether narrowing pays off.',
+          },
+          turns: {
+            type: 'integer',
+            description:
+              'Roughly how many turns this task will take. In a large context, fewer than 6 turns cannot pay back the rebuild and is refused unless force is set.',
+          },
+          force: {
+            type: 'boolean',
+            description: 'Narrow even when the cost gate says it will not pay back — you accept one full-price rebuild.',
+          },
+          dryRun: {
+            type: 'boolean',
+            description:
+              'Preview only: report what would be kept or removed plus availableGroups, without touching the tool table or taking the lock. Costs nothing. Use it to pick the right groups before committing.',
+          },
+        },
+        required: ['groups'],
+      },
+      async execute(args, exec) {
+        const key = keyOf(exec)
+        if (activeTasks.has(key)) {
+          const running = activeTasks.get(key)
+          return { ok: false, code: 'ALREADY_ACTIVE', taskId: running.taskId, hint: '先 task_end 结束当前任务' }
+        }
+
+        const groups = (Array.isArray(args?.groups) ? args.groups : [])
+          .map((g) => (typeof g === 'string' ? g.trim().toLowerCase() : ''))
+          .filter(Boolean)
+
+        // 【歧义就报错，不要猜】groups: [] 可以理解成"只留基础工具"，也可以理解成"不收窄"。
+        // 两种都合理，但选错一次就把任务需要的工具全摘了。所以直接拒绝，让调用方写清楚。
+        if (groups.length === 0) {
+          return {
+            ok: false,
+            code: 'EMPTY_GROUPS',
+            message: 'groups 不能为空：要收窄就写至少一个组名；不想收窄就别开任务。',
+          }
+        }
+
+        // 拿到这个会话真实的工具清单（优先 agent 作用域）
+        const agent = exec && exec.agent
+        const scoped = agent && agent.ctx && agent.ctx.tools
+        let schemas = []
+        try {
+          if (scoped && typeof scoped.schemas === 'function') schemas = scoped.schemas()
+          else if (typeof ctx.tools.schemas === 'function') schemas = ctx.tools.schemas()
+        } catch {
+          schemas = []
+        }
+        // 只要名字给算法层；原始 schema 留着给成本估算量字节
+        const toolNames = (Array.isArray(schemas) ? schemas : [])
+          .map((t) => (t && typeof t.name === 'string' ? t.name : ''))
+          .filter(Boolean)
+
+        const { deny, kept, unknownGroups } = computeDeny(toolNames, groups)
+
+        // 【v0.5.0】持久工具清单：dryRun 也会写（不花重建成本）。
+        // 为什么需要：task_end 之后的快照里没有名单，而"认领建议 / 空态显示工具数"
+        // 都需要一份全量工具名。这份文件是唯一的长期来源。
+        try {
+          atomicWriteJson(REGISTRY_FILE, { at: Date.now(), count: toolNames.length, tools: toolNames })
+        } catch {
+          // 写不了就算了，不影响任务
+        }
+
+        // 【B】把这台机器上真实存在的组列出来——否则调用方只能凭记忆猜组名。
+        const availableGroups = summarizeGroups(schemas, tagOf)
+
+        // 【成本闸门】收窄 = 一次全价重建（实测 33 万上下文 ≈ 28 万全价 token）。
+        // 数据由调用方给，拿不到就如实说"算不出来"，绝不猜。
+        const deniedBytes = measureDeniedBytes(schemas, new Set(deny))
+        const cost = estimateTaskCost({
+          contextTokens: args?.contextTokens,
+          turns: args?.turns,
+          deniedBytes,
+        })
+
+        // 【A】dryRun：只看不碰。不抢锁、不动工具表、不写任务状态，成本 0。
+        // 连成本闸门的拒绝也一并展示出来——你需要看到"为什么不该切"。
+        if (args?.dryRun === true) {
+          const preview = buildPreview({ deny, kept, availableGroups, groups })
+          appendRecord({ event: 'dry-run', groups, denyCount: deny.length, deniedBytes, gate: cost.reason })
+          return {
+            ok: true,
+            dryRun: true,
+            ...preview,
+            unknownGroups,
+            cost,
+            message:
+              `预览：会保留 ${preview.willKeep} 个、摘掉 ${preview.willDeny} 个。` +
+              (preview.missingGroups.length > 0 ? `这些组名在这台机器上不存在：${preview.missingGroups.join(', ')}。` : '') +
+              '确认无误后去掉 dryRun 再调一次。',
+          }
+        }
+
+        if (!cost.allow && args?.force !== true) {
+          appendRecord({ event: 'gate-refused', groups, denyCount: deny.length, deniedBytes, cost })
+          return { ok: false, code: 'COST_GATE', message: cost.message, cost, availableGroups }
+        }
+
+        const taskId = newTaskId()
+
+        // 先抢锁（跨进程唯一），失败就不要动工具表
+        try {
+          acquireLock({ taskId, groups, cwd: process.cwd() })
+        } catch (error) {
+          return { ok: false, code: error.code || 'LOCK_FAILED', message: String(error.message || error) }
+        }
+
+        // 只在 agent.ctx.tools 上调（全局调用 DSH 会直接拒绝）
+        let dispose = null
+        let restrictError = ''
+        if (deny.length > 0) {
+          if (scoped && typeof scoped.restrict === 'function') {
+            try {
+              // 只用 deny。allow 会藏掉点不出名字的工具（实测 4/4 丢 read）
+              dispose = scoped.restrict({ deny })
+            } catch (error) {
+              restrictError = String((error && error.message) || error)
+            }
+          } else {
+            restrictError = 'no-scoped-tools'
+          }
+        }
+
+        // 收窄失败就别占着锁（否则后面的任务都进不来）
+        if (!dispose && deny.length > 0) {
+          releaseLock(taskId)
+          appendRecord({ event: 'start-failed', taskId, groups, denyCount: deny.length, error: restrictError })
+          return { ok: false, code: 'RESTRICT_FAILED', message: restrictError, denyCount: deny.length }
+        }
+
+        const task = {
+          taskId,
+          groups,
+          goal: typeof args?.goal === 'string' ? args.goal.slice(0, 200) : '',
+          startedAt: Date.now(),
+          dispose,
+          applied: Boolean(dispose),
+          denyCount: deny.length,
+          knownTools: toolNames.length,
+          cost,
+        }
+        activeTasks.set(key, task)
+
+        // 给 UI 的快照（浏览器读不到内存，只能读文件）
+        // 【v0.4.0】除了数字，也把**具体工具名**写进去：面板要能回答"保留了什么、砍了什么"。
+        const countByTag = (names) => {
+          const out = {}
+          for (const name of names) {
+            const tag = tagOf(name)
+            out[tag] = (out[tag] || 0) + 1
+          }
+          return out
+        }
+        writeCurrent({
+          active: true,
+          taskId,
+          groups,
+          goal: task.goal,
+          denyCount: deny.length,
+          keptCount: kept.length,
+          keptTools: kept,
+          deniedTools: deny,
+          deniedByTag: countByTag(deny),
+          deniedBytes,
+          startedAt: task.startedAt,
+          applied: task.applied,
+          savingsPerTurn: cost.savingsPerTurn,
+          paybackTurns: cost.paybackTurns,
+        })
+
+        appendRecord({
+          event: 'start',
+          taskId,
+          key,
+          goal: task.goal,
+          groups,
+          denyCount: deny.length,
+          keptCount: kept.length,
+          knownTools: toolNames.length,
+          applied: task.applied,
+          unknownGroups,
+          // 经济账也一起记下来，事后能复盘"这次收窄到底值不值"
+          deniedBytes,
+          costTokens: cost.costTokens,
+          savingsPerTurn: cost.savingsPerTurn,
+          paybackTurns: cost.paybackTurns,
+          gate: cost.reason,
+        })
+
+        return {
+          ok: true,
+          taskId,
+          groups,
+          // 注意：这是"我们摘掉了多少"，不是"还剩多少"。真实剩余以探针为准。
+          denyCount: deny.length,
+          keptCount: kept.length,
+          applied: task.applied,
+          unknownGroups,
+          // 【B】也带一份组清单：任务跑起来后你还想知道"当初如果有别的组可不可以选"
+          availableGroups,
+          cost,
+          note: '工具表已按任务收窄；结束时调 task_end 恢复。中途不要改。',
+        }
+      },
+    }),
+  )
+
+  // --------------------------------------------------------------------------
+  // task_end —— 结束任务 + 恢复全量
+  // --------------------------------------------------------------------------
+  ctx.effect(() =>
+    ctx.tools.register({
+      name: 'task_end',
+      output: RENDER,
+      description:
+        'End the current task: dispose the tool restriction (restore every tool) and release the task lock. Returns the task summary recorded in the usage log.',
+      parameters: { type: 'object', additionalProperties: false, properties: {} },
+      async execute(_args, exec) {
+        const key = keyOf(exec)
+        const task = activeTasks.get(key)
+        if (!task) return { ok: false, code: 'NO_ACTIVE_TASK', hint: '当前会话没有在跑的任务' }
+
+        let restored = false
+        try {
+          if (typeof task.dispose === 'function') {
+            task.dispose()
+            restored = true
+          }
+        } catch (error) {
+          appendRecord({ event: 'end-error', taskId: task.taskId, key, error: String((error && error.message) || error) })
+        }
+        releaseLock(task.taskId)
+        activeTasks.delete(key)
+
+        // 告诉 UI：任务结束了（保留工具总数，好让徽章显示"工具表：全开（N 个）"）
+        writeCurrent({
+          active: false,
+          taskId: task.taskId,
+          groups: task.groups,
+          denyCount: task.denyCount,
+          keptCount: Math.max(0, (task.knownTools || 0) - task.denyCount),
+          knownTools: task.knownTools,
+          endedAt: Date.now(),
+        })
+
+        const durationMs = Date.now() - task.startedAt
+        appendRecord({
+          event: 'end',
+          taskId: task.taskId,
+          key,
+          groups: task.groups,
+          denyCount: task.denyCount,
+          durationMs,
+          restored,
+        })
+
+        return {
+          ok: true,
+          taskId: task.taskId,
+          durationMs,
+          restored,
+          denyCount: task.denyCount,
+          note: restored ? '工具表已恢复全量' : '本来就没收窄（或限制已被外部拆除）',
+        }
+      },
+    }),
+  )
+
+  // --------------------------------------------------------------------------
+  // task_status —— 只读（没有它，出问题只能靠猜）
+  // --------------------------------------------------------------------------
+  ctx.effect(() =>
+    ctx.tools.register({
+      name: 'task_status',
+      output: RENDER,
+      description:
+        'Read-only: the active task for this session (id, groups, how many tools were denied, elapsed), plus whoever holds the cross-process lock. Changes nothing.',
+      parameters: { type: 'object', additionalProperties: false, properties: {} },
+      async execute(_args, exec) {
+        const key = keyOf(exec)
+        const task = activeTasks.get(key)
+        const lock = readLock()
+        return {
+          ok: true,
+          active: task
+            ? {
+                taskId: task.taskId,
+                groups: task.groups,
+                goal: task.goal,
+                applied: task.applied,
+                denyCount: task.denyCount,
+                knownTools: task.knownTools,
+                durationMs: Date.now() - task.startedAt,
+              }
+            : null,
+          lock: lock
+            ? {
+                taskId: lock.taskId,
+                pid: lock.pid,
+                alive: pidAlive(Number(lock.pid)),
+                ageMs: Date.now() - Number(lock.startedAt || 0),
+                mine: lock.pid === process.pid,
+              }
+            : null,
+          stateDir: STATE_DIR,
+        }
+      },
+    }),
+  )
+
+  // --------------------------------------------------------------------------
+  // UI 请求通道（v0.6.0）：浏览器写 request.json，这里在下一次工具调用前消费
+  // --------------------------------------------------------------------------
+  // 为什么挂在 pre-execute：浏览器没有调用工具的权限，而 pre-execute 是唯一
+  // 每轮都会发生、且能拿到 agent 作用域（restrict 必须作用在 agent.ctx.tools）的位置。
+  let lastUiRequestId = ''
+  ctx.effect(() =>
+    ctx.on('tools/pre-execute', (...args) => {
+      const downstream = typeof args[args.length - 1] === 'function' ? args[args.length - 1] : null
+      const exec = args[0]
+      try {
+        consumeUiRequest(exec)
+      } catch {
+        // 消费失败不能影响工具调用
+      }
+      return downstream ? downstream() : { kind: 'allow' }
+    }),
+  )
+
+  function consumeUiRequest(exec) {
+    let request = null
+    try {
+      request = JSON.parse(readFileSync(REQUEST_FILE, 'utf8'))
+    } catch {
+      return
+    }
+    if (!request || typeof request.id !== 'string' || request.id === lastUiRequestId) return
+    const age = Date.now() - (Number(request.ts) || 0)
+    if (!(age >= 0 && age < 60 * 1000)) return // 过期请求不执行
+
+    const key = keyOf(exec)
+    const agent = exec && exec.agent && typeof exec.agent === 'object' ? exec.agent : null
+    const scoped = agent && agent.ctx && agent.ctx.tools ? agent.ctx.tools : null
+    const result = { id: request.id, action: String(request.action || ''), at: Date.now(), ok: false }
+
+    try {
+      if (request.action === 'end') {
+        const task = activeTasks.get(key)
+        if (!task) {
+          result.error = '当前会话没有进行中的任务'
+        } else {
+          try {
+            if (typeof task.dispose === 'function') task.dispose()
+          } catch {
+            /* 释放失败也要把状态清掉 */
+          }
+          releaseLock(task.taskId)
+          activeTasks.delete(key)
+          writeCurrent({
+            active: false,
+            taskId: task.taskId,
+            groups: task.groups,
+            denyCount: task.denyCount,
+            keptCount: Math.max(0, (task.knownTools || 0) - task.denyCount),
+            knownTools: task.knownTools,
+            endedAt: Date.now(),
+          })
+          appendRecord({ event: 'end', taskId: task.taskId, key, reason: 'ui-request' })
+          result.ok = true
+        }
+      } else if (request.action === 'start') {
+        if (!scoped || typeof scoped.restrict !== 'function') {
+          result.error = '拿不到 agent 作用域的工具表（这条消息还没调用过工具？）'
+        } else {
+          const groups = Array.isArray(request.groups) ? request.groups.filter((g) => typeof g === 'string' && g) : []
+          const schemas = typeof scoped.schemas === 'function' ? scoped.schemas() : []
+          const toolNames = schemas.map((t) => (t && typeof t.name === 'string' ? t.name : '')).filter(Boolean)
+          const { deny, kept } = computeDeny(toolNames, new Set(groups))
+          const deniedBytes = measureDeniedBytes(schemas, new Set(deny))
+          const taskId = newTaskId()
+          const dispose = deny.length > 0 ? scoped.restrict({ deny: deny.filter((n) => n !== 'run_code') }) : null
+          activeTasks.set(key, {
+            taskId,
+            groups,
+            goal: '（UI 手动收窄）',
+            startedAt: Date.now(),
+            dispose,
+            applied: Boolean(dispose),
+            denyCount: deny.length,
+            knownTools: toolNames.length,
+          })
+          try {
+            acquireLock({ taskId, groups, cwd: process.cwd() })
+          } catch {
+            // 锁被别的进程占着也允许 UI 收窄，不阻塞
+          }
+          atomicWriteJson(REGISTRY_FILE, { at: Date.now(), count: toolNames.length, tools: toolNames })
+          writeCurrent({
+            active: true,
+            taskId,
+            groups,
+            goal: '（UI 手动收窄）',
+            denyCount: deny.length,
+            keptCount: kept.length,
+            keptTools: kept,
+            deniedTools: deny,
+            deniedBytes,
+            startedAt: Date.now(),
+            applied: Boolean(dispose),
+            savingsPerTurn: Math.round(deniedBytes * 0.3),
+            paybackTurns: null,
+          })
+          appendRecord({ event: 'start', taskId, key, groups, denyCount: deny.length, by: 'ui-request' })
+          result.ok = true
+          result.taskId = taskId
+          result.denyCount = deny.length
+        }
+      } else {
+        result.error = `未知动作：${request.action}`
+      }
+    } catch (error) {
+      result.error = String((error && error.message) || error).slice(0, 160)
+    }
+
+    lastUiRequestId = request.id
+    try {
+      atomicWriteJson(RESULT_FILE, result)
+    } catch {
+      /* 结果写不进去不影响主流程 */
+    }
+  }
+}

package/lib/cost-gate.js

@@ -0,0 +1,150 @@
+/**
+ * ============================================================================
+ * lib/cost-gate.js · 收窄的"经济账"
+ * ============================================================================
+ * 任务收窄是**一次性全价重建 + 每轮持续省钱**。所以它有个回本点：
+ *
+ *   成本   = 切换那一刻的整段上下文（contextTokens，全价重算）
+ *   每轮省 = 被摘掉工具声明的字节数 × 每字节 token 数（0.3，和 router 同一口径）
+ *   回本   = 成本 / 每轮省
+ *
+ * 实测依据（本机，2026-10-31，一次真实收窄）：
+ *   272 个工具 / 232,458 字节 → 78 个 / 57,883 字节（摘掉 174,575 字节）
+ *   那一次请求：promptTokens 285,701，cacheRead 只有 4,608 → 命中率 1.61%
+ *   → 一次性成本 ≈ 28.1 万全价 token，按 0.3 算每轮省 ≈ 5.2 万 → 回本 ≈ 5.4 轮
+ *
+ * 结论：**任务跑不够约 6 轮，收窄就是纯亏。** 这个文件就是把这条账做成门槛。
+ * ============================================================================
+ */
+
+/** 上下文超过这个量级，一次重建就非常贵了（实测 33 万上下文 ≈ 28 万全价 token） */
+export const FULL_PRICE_CONTEXT = 200_000
+
+/** 低于这个预估轮数、且上下文已经很大时，收窄不划算 */
+export const MIN_TURNS_TO_PAYBACK = 6
+
+/**
+ * 每字节约等于多少 token。
+ *
+ * 【实测校准（2026-10-31）】Web UI 的「用量 → 工具定义」显示约 58.3K token，
+ * 而探针的 toolsChars 是 232,458 字节 → 232,458 / 58,300 ≈ 3.99 字节/token，
+ * 也就是 **0.25 token/字节**。
+ *
+ * 原来按 router 的 switchSavingsPerByte = 0.3 填的，**高估约 20%**：
+ * 每轮省会被算大，回本被算短。这里改成实测值，宁可保守也不要乐观。
+ */
+export const SAVINGS_PER_BYTE = 0.25
+
+/**
+ * 量一下"这次要摘掉多少字节的工具声明"。
+ * 和 router 里的算法一致：把 name/description/parameters 序列化后计长。
+ * @param {Array<{name?:string, description?:string, parameters?:object}>} schemas
+ * @param {Set<string>} denySet 要摘掉的名字集合
+ * @returns {number} 字节数
+ */
+export function measureDeniedBytes(schemas, denySet) {
+  try {
+    const list = Array.isArray(schemas) ? schemas : []
+    if (!(denySet instanceof Set) || denySet.size === 0) return 0
+    let bytes = 0
+    for (const tool of list) {
+      if (!tool || typeof tool.name !== 'string' || !denySet.has(tool.name)) continue
+      bytes += JSON.stringify({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+      }).length
+    }
+    return bytes
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * 算这笔账。
+ *
+ * 【诚实原则】`contextTokens` 和 `turns` 都是**调用方给的**，我们不会去猜，也不会去读
+ * 别的插件的数据文件（跨插件读别人的账单属于隐性耦合）。拿不到就如实说"数据不足"。
+ *
+ * @param {{contextTokens?: number|null, turns?: number|null, deniedBytes?: number}} input
+ * @returns {{
+ *   allow: boolean,
+ *   reason: 'ok'|'not-worth-it'|'insufficient-data'|'nothing-to-deny',
+ *   costTokens: number|null,
+ *   savingsPerTurn: number,
+ *   paybackTurns: number|null,
+ *   deniedBytes: number,
+ *   message: string,
+ * }}
+ */
+export function estimateTaskCost(input) {
+  const rawContext = Number(input && input.contextTokens)
+  const contextTokens = Number.isFinite(rawContext) && rawContext > 0 ? Math.trunc(rawContext) : null
+  const rawTurns = Number(input && input.turns)
+  const turns = Number.isFinite(rawTurns) && rawTurns > 0 ? Math.trunc(rawTurns) : null
+  const deniedBytes = Math.max(0, Math.trunc(Number(input && input.deniedBytes) || 0))
+
+  const savingsPerTurn = Math.round(deniedBytes * SAVINGS_PER_BYTE)
+
+  // 没什么可摘的 → 不用算，也不会亏
+  if (deniedBytes === 0) {
+    return {
+      allow: true,
+      reason: 'nothing-to-deny',
+      costTokens: contextTokens,
+      savingsPerTurn: 0,
+      paybackTurns: null,
+      deniedBytes: 0,
+      message: '这个任务本来就不需要摘工具，没有切换成本。',
+    }
+  }
+
+  // 数据不足 → 不拦（拦了会让人以为插件坏了），但明确说"没算出来"
+  if (contextTokens === null) {
+    return {
+      allow: true,
+      reason: 'insufficient-data',
+      costTokens: null,
+      savingsPerTurn,
+      paybackTurns: null,
+      deniedBytes,
+      message: `没拿到当前上下文大小，无法估算回本。每轮约省 ${savingsPerTurn} token；想让我算清楚就传 contextTokens（可从 cache_probe_report 的 lastPromptTokens 取）。`,
+    }
+  }
+
+  const paybackTurns = savingsPerTurn > 0 ? Math.ceil(contextTokens / savingsPerTurn) : null
+
+  // 【主判据】用户的显式规则：上下文已经很大 + 任务又短 → 拒绝
+  const tooExpensive = contextTokens > FULL_PRICE_CONTEXT
+  const tooShort = turns !== null && turns < MIN_TURNS_TO_PAYBACK
+  const notWorthIt = tooExpensive && tooShort
+
+  if (notWorthIt) {
+    return {
+      allow: false,
+      reason: 'not-worth-it',
+      costTokens: contextTokens,
+      savingsPerTurn,
+      paybackTurns,
+      deniedBytes,
+      message:
+        `【拒绝收窄】当前上下文 ${contextTokens} token，收窄会触发一次约 ${contextTokens} token 的全价重建；` +
+        `而这次任务预估只有 ${turns} 轮，每轮约省 ${savingsPerTurn} token，` +
+        `需要 ${paybackTurns ?? '>99'} 轮才回本（阈值 ${MIN_TURNS_TO_PAYBACK} 轮）——跑不够就是亏。` +
+        '确实要切就传 force: true。',
+    }
+  }
+
+  return {
+    allow: true,
+    reason: 'ok',
+    costTokens: contextTokens,
+    savingsPerTurn,
+    paybackTurns,
+    deniedBytes,
+    message:
+      `收窄一次性成本约 ${contextTokens} token，每轮约省 ${savingsPerTurn} token` +
+      (paybackTurns === null ? '。' : `，约 ${paybackTurns} 轮回本。`),
+  }
+}

package/lib/scope-preview.js

@@ -0,0 +1,69 @@
+/**
+ * ============================================================================
+ * lib/scope-preview.js · "先看后付"用的纯函数
+ * ============================================================================
+ * 为什么需要它（真实事故，2026-10-31）：
+ *   一次 task_start 用了 groups:["unity"]，结果把 `plugin_manager`（标签 plugin）
+ *   和 `cordis_inspect_*`（标签 cordis）一起摘掉了 —— 而那正是当时在做的活。
+ *   根因不是逻辑错，是**调用方不知道有哪些组可以选**：领域（"开发 DSH 插件"）
+ *   这个说法在工具表里根本没有对应标签，它的工具散在 plugin / cordis / web / skill 里。
+ *
+ * 所以这里提供两件东西：
+ *   1. summarizeGroups —— 把"这台机器上真实存在的组"列出来（组名 → 工具数）
+ *   2. buildPreview    —— 一次收窄会保留什么、摘掉什么（含少量样例）
+ *
+ * 两者都是**纯函数**，不碰 IO、不碰工具表，可以在 dryRun 里零成本调用。
+ * ============================================================================
+ */
+
+/** 预览里每边最多列几个名字（全列会刷屏，也没人看） */
+export const SAMPLE_SIZE = 8
+
+/**
+ * 统计这台机器上真实存在的工具组。
+ * @param {Array<{name?: string}>} schemas
+ * @param {(name: string) => string} tagOf
+ * @returns {Record<string, number>} 组名 → 工具数，按数量降序
+ */
+export function summarizeGroups(schemas, tagOf) {
+  const counts = new Map()
+  try {
+    for (const tool of Array.isArray(schemas) ? schemas : []) {
+      const name = tool && typeof tool.name === 'string' ? tool.name : ''
+      if (!name) continue
+      const tag = tagOf(name)
+      counts.set(tag, (counts.get(tag) || 0) + 1)
+    }
+  } catch {
+    return {}
+  }
+  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+  return Object.fromEntries(sorted)
+}
+
+/**
+ * 组一次收窄的预览。
+ * @param {{deny: string[], kept: string[], availableGroups: Record<string, number>, groups: string[]}} input
+ * @returns {object}
+ */
+export function buildPreview(input) {
+  const deny = Array.isArray(input && input.deny) ? input.deny : []
+  const kept = Array.isArray(input && input.kept) ? input.kept : []
+  const availableGroups = (input && input.availableGroups) || {}
+  const groups = Array.isArray(input && input.groups) ? input.groups : []
+
+  // 用户点名的组里，哪些在这台机器上真的存在
+  const foundGroups = groups.filter((g) => Object.hasOwn(availableGroups, g))
+  const missingGroups = groups.filter((g) => !Object.hasOwn(availableGroups, g))
+
+  return {
+    groups,
+    foundGroups,
+    missingGroups,
+    availableGroups,
+    willKeep: kept.length,
+    willDeny: deny.length,
+    keepSample: kept.slice(0, SAMPLE_SIZE),
+    denySample: deny.slice(0, SAMPLE_SIZE),
+  }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Task guard",
+    "description": "Narrows the tool table to the named groups at task start (deny-only) and restores it at task end; ships a cross-process lock, a cost gate and a usage ledger."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "任务收窄锁",
+    "description": "任务开始时按组收窄工具表（只用 deny）、结束时恢复；自带跨进程锁、成本闸门与任务台账。"
+  }
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "dsh-task-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.2",
+  "type": "module",
+  "main": "./index.js",
+  "description": "Task-scoped tool narrowing for DSH: narrow the tool table once when a task starts (deny-only), restore it when the task ends. Ships a cross-process task lock and a taskId-tagged usage log. Zero dependencies.",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.4"
+  },
+  "files": [
+    "index.js",
+    "lib/*.js",
+    "cordis.patch.yml",
+    "README.md",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "scripts": {
+    "test": "node test/task-guard.test.mjs"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "context-caching",
+    "task-scope",
+    "deepseek-harness",
+    "tools",
+    "context-cache"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qwq1223211/dsh-task-guard.git"
+  },
+  "homepage": "https://github.com/qwq1223211/dsh-task-guard#readme",
+  "bugs": {
+    "url": "https://github.com/qwq1223211/dsh-task-guard/issues"
+  }
+}