dsh-hitl 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,6 @@
-# dsh-hitl · Human-in-the-loop for any tool
+# dsh-hitl · Human-in-the-loop for DeepSeek Harness
+
+[![npm version](https://img.shields.io/npm/v/dsh-hitl)](https://www.npmjs.com/package/dsh-hitl) [![license](https://img.shields.io/npm/l/dsh-hitl)](LICENSE) [![Website](https://img.shields.io/badge/Website-4c566a)](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 English | [中文](README.zh.md)
 
@@ -7,7 +9,7 @@ English | [中文](README.zh.md)
 
 `dsh-hitl` is an installable DeepSeek Harness (DSH) plugin (bundle): **zero dependencies, zero build** — `index.js` (host half) + `client.js` (browser half) + `lib/` are plain JS that loads as it is. Install it, refresh the page once, and it works.
 
-![A complete decision card: title, pending proposal, approve/modify/reject buttons, and a countdown](docs/01-panel-en.png)
+**[View Website](https://yunpengdon.github.io/dsh-hitl-landing/)**
 
 ## Features
 
@@ -18,18 +20,17 @@ English | [中文](README.zh.md)
 - **Rejection with feedback**: 【Reject】 can carry a **feedback box**, and what you write there reaches the agent together with the rejection — it knows "don't do it" *and* "why not";
 - **Configurable countdown**: a **countdown** plus three endings (**approve automatically / reject automatically / report the timeout to the agent**).
 
-![The three proposal renderers in one card: a split diff, a text input, and markdown preview with edit](docs/02-fields-en.png)
 
 ## Made for DSH
 
 **Subagent pass-through: a tool call inside a subagent raises its approval request in the main conversation too.** Every tool call inside an in-process subagent (`spawn` / `fork`) goes through the same gate — the request is filed **both** under the child Session that made it and under the Session you are currently looking at: whichever conversation you are in, the card can appear there, labelled 「from subagent Session xxx」 with an 【Open that Session】 button.
 (Out-of-process backends never reach this gate — see §6.1.)
 
-![A card in the main conversation, labelled as coming from a subagent Session, with a jump button](docs/03-subagent-en.png)
+[See this card on the landing page →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 **A mini approval request even when you are not in a conversation.** Switch to the plugins page, open settings, or select no Session at all, and a notice floats at the top of the page, so HITL does not have to block the run while you are elsewhere (count, tool name, source Session, remaining time + 【Approve】【Reject】【Open that Session】).
 
-![The fallback notice floating above the settings modal](docs/04-overlay-en.png)
+[See the notice on the landing page →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 ---
 
@@ -142,9 +143,10 @@ Without `fields`, the proposal is **every parameter of this call**:
 | `reject.feedbackPrompt` | string | built-in copy | Feedback box placeholder |
 | `reject.requireFeedback` | boolean | `false` | Feedback is required (an empty box is refused with a hint) |
 | `modify.mode` | `revise-request` \| `allow-and-inform` | `revise-request` | What 【Modify】 means after an edit; see §5 |
-| `whenUnavailable` | `reject` \| `wait` | `reject` | Behaviour with no browser connected (`reject` = fail-closed) |
+| `whenUnavailable` | `reject` \| `wait` | `reject` | Behaviour with no browser connected: `reject` = fail-closed; `wait` = wait indefinitely, so **pair it with a `countdown`** or that call hangs until its Session ends (the host warns at mount time); see §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | Turn a mount off temporarily / make it conditional |
 | `maxFieldChars` | number | `20000` | Per-field render cap; longer values are truncated with a note |
+| `resolveTimeoutMs` | number | `5000` | Bound on resolving one **computed** field; a timeout or a throw fails that field alone, never the call |
 
 ### FieldSpec
 
@@ -153,6 +155,7 @@ Without `fields`, the proposal is **every parameter of this call**:
   render: 'markdown',        // markdown | text | diff | json | hidden
   editable: true,            // overrides the default editability
   labels: ['irreversible'],  // field-level labels
+  value: 'fixed copy',       // this field's text: a literal, or (exec) => string | Promise<string>
   diff: { before: 'old_string', after: 'new_string', path: 'file_path' } }   // used when render: 'diff'
 ```
 
@@ -160,6 +163,31 @@ Without `fields`, the proposal is **every parameter of this call**:
 - When `fields` is given, **only** the listed fields are shown (parameters you leave out never reach the panel).
 - Config rows may shorten a spec to a bare string: `fields: ['command', { param: 'cwd', title: 'Working directory' }]`.
 
+### Computed fields: putting what the arguments do not carry on the card
+
+`diff.before` / `diff.after` / `diff.path` normally name a **parameter** (the host reads `args[name]`). Like a field's `value`, any of them may instead be a **function**: the host calls it with the pending `exec` before the card opens and uses what it returns as the text.
+
+```js
+ctx.hitl.protect('update_index', {
+  title: 'Update the knowledge-tree index',
+  fields: [
+    { param: 'content', title: 'New index text', render: 'markdown' },
+    { param: 'index', title: 'What changes in the index file', render: 'diff', editable: false,
+      // `before` reads the old index from disk, `after` derives the new file text —
+      // neither of them is one of the call's parameters
+      diff: { path: 'index.md',
+              before: async exec => readIndexFile(exec),
+              after: exec => `# Knowledge tree index\n\n${exec.arguments.content}` } },
+  ],
+})
+```
+
+- A string `diff.path` that is **not** a parameter name is used as a literal path: the file a call is about to change is often not one of its arguments.
+- Resolvers may be async; one field's resolution is bounded by `resolveTimeoutMs` (5s by default).
+- **A failed resolution never blocks the decision**: a throw or a timeout turns *that field* into one `⚠️ …could not be resolved…` line, the card still opens, and the human still decides. If the resolution machinery itself breaks, the proposal degrades to the raw arguments instead of denying the call.
+- The wire format and the browser half are unchanged: both sides of a diff always travelled in the frame; the panel just renders them.
+- Each side of a diff is cut past `maxDiffLines` (2000 lines) with a note, so a whole-file diff cannot become an unbounded frame.
+
 ### The three endings of a countdown
 
 `countdown.action` decides what the host does when the countdown reaches zero:
@@ -274,12 +302,36 @@ The panel follows the **application's current language** — not the mounting pl
 - **With no browser connected the default is fail-closed**: a tool mounted behind HITL is rejected and the model sees `Error: HITL: no browser is connected to decide, so tool "x" did not run (fail-closed).` Set `whenUnavailable` to `wait` if it should wait forever in unattended runs instead.
 - In a composition with no Web service at all (headless/TUI) the plugin **stays active and keeps gating** — "no UI, therefore no gate" is not this plugin's semantics.
 
+### 7.1 The security boundary: what HITL stops and what it cannot
+
+- **It stops a call from *starting*; it does not stop the world.** If a tool has already produced a side effect inside its own
+  execution layer (a concurrent race, an asynchronous write, a request already sent), a rejection prevents "next", never "already" —
+  **HITL is neither a transaction nor a sandbox**.
+- So how safe you actually are depends on two things: **① how dangerous the operations your matcher covers are; ② whether the tool
+  puts its irreversible step last.** Mounting `bash` / `write` / `edit` — tools that are dangerous the moment they start — is the
+  right use. If a tool only reveals its risk halfway through, HITL can only help you decide whether to begin.
+- **A human's approval is not a privilege escalation**: the sandbox, guards, hooks and approval still run afterwards (§8); and the
+  reverse holds too — another pre-execution policy can refuse *before* this plugin is even asked. That was measured once:
+  `fs-observation-policy` stopped a call before the human pressed 【Approve】, so no HITL panel ever appeared (§8).
+- **`whenUnavailable: wait` is fail-open**: with no browser connected the call simply waits, and without a `countdown` it waits until
+  its Session ends. Use the fail-closed default (`reject`) when an unattended run must not stall, or pair `wait` with a `countdown`
+  (the host warns at mount time when you do not).
+- **The local trust boundary**: the decision channel and `/status` answer loopback addresses only. Any process on this machine can
+  read `/status`, which carries the **mount list** and, per pending decision, the **tool name / Session id / remaining milliseconds /
+  hold state** — **no tool arguments and no token**. To size that hole precisely: a local process can already read the session logs
+  under `~/.dsh/sessions/**`, which do contain every tool argument, so `/status` exposes a strictly smaller subset of what is already
+  readable locally. The hole is deliberate: without it, "what is HITL holding right now?" could only be answered by opening the page.
+
 ---
 
 ## 8. Relationship to other pre-execution policies
 
 - This plugin listens on `tools/pre-execute` with `prepend: true`, i.e. **ask the human first**; once the human agrees, the sandbox, guards, hooks, approval, and every other policy still run afterwards. **A human's approval is not a privilege escalation.**
 - So "the human approved but the sandbox or a guard still refused" is by design, not a bug.
+- **The reverse holds too**: another pre-execution policy can refuse **before** this plugin is ever asked, in which case no HITL panel
+  appears at all — so "it ran (or failed) without asking me" is a question for the other policies first. Measured once:
+  `fs-observation-policy` demands a re-read before overwriting a deleted file, and it stopped a call both *after* the human pressed
+  【Approve】 (the panel had appeared as usual) and, in another round, *before* this plugin was reached (no panel at all).
 - This plugin only asks before execution: it never rewrites a tool's arguments and never rewrites a tool's result.
 
 ---
@@ -287,6 +339,7 @@ The panel follows the **application's current language** — not the mounting pl
 ## 9. Known limitations
 
 - **Tool arguments cannot be rewritten** (see §5), so 【Modify】 defaults to "refuse and hand the edit back".
+- **HITL is not a side-effect boundary** (see §7.1): it stops a call from starting and cannot roll back a side effect that already happened; how much it protects you depends on the matcher and on the tool's own design.
 - **Mount copy is not localized**: `title` / `labels` / field titles are strings the mounting plugin supplies; this plugin does not translate them and does not accept a `{zh, en}` map (see §6.3).
 - **No session audit event**: DSH does not let a plugin append new event types, so the decision trail lives only in the tool result (and, under `allow-and-inform`, in one user message).
 - **Only the Web UI has a panel**: under ACP/TUI/headless the mount's `whenUnavailable` decides (reject by default).
@@ -359,28 +412,30 @@ Reply: `{ ok: true, accepted: true, held?, expiresAt? }` or
 
 ```text
 dsh-hitl/
-├── index.js                629   host half: service + gate + countdown/hold + SSE & decision routes + token injection
+├── index.js                666   host half: service + gate + countdown/hold + SSE & decision routes + token injection
 ├── client.js              1918   browser half: decision panel + frame-level notice (self-contained classic script, no imports)
 ├── lib/                          the host half's pure logic: no Cordis, no DOM, testable on its own
-│   ├── protocol.js         182   frame and uplink validation, limits, error codes (the single source of the protocol)
-│   ├── resolve.js          302   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
-│   ├── fields.js           244   default proposal derivation, diff pairing, decision → model-visible text
+│   ├── protocol.js         195   frame and uplink validation, limits, error codes (the single source of the protocol)
+│   ├── resolve.js          363   matcher compilation (name/glob/RegExp/predicate), option normalization and diagnostics
+│   ├── fields.js           449   default proposal derivation, diff pairing, computed-field resolution, decision → model-visible text
 │   └── pending.js          217   the pending-decision state machine (injectable clock): countdown, hold, settle-once
 ├── locale/                       the plugin list's name and description (shape must be {"meta":{...}}, see §6.3)
 │   ├── en.json               6
 │   └── zh.json               6
-├── docs/                         the screenshots shown above, one set per language (-en / -cn)
-├── tests/                        zero-dependency Node tests, 151 cases in total
+├── docs/                         screenshot sources, deliberately NOT shipped: the README links the landing page instead
+├── tests/                        zero-dependency Node tests, 167 cases in total
 │   ├── client.test.js      818   (65) the browser half's pure helpers + store / connection / seat
-│   ├── fields.test.js      269   (26) proposal derivation and decision text
+│   ├── fields.test.js      387   (37) proposal derivation, computed fields and decision text
 │   ├── pending.test.js     240   (18) the state machine (injected clock, no real waiting)
-│   ├── resolve.test.js     162   (18) matchers and option normalization
+│   ├── resolve.test.js     224   (22) matchers and option normalization
 │   ├── protocol.test.js    117   (16) frame and uplink validation
-│   ├── docs.test.js        116   (5) the two READMEs, their links, and the numbers in this very table
-│   └── manifest.test.js     61   (3) package metadata and the locale resource shape
-├── package.json             69   manifest: exports / dsh.bundle.patch / dsh.client / icon
+│   ├── docs.test.js        121   (5) the two READMEs, the landing-page link, and the numbers in this very table
+│   └── manifest.test.js     77   (4) package metadata and the locale resource shape
+├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
+├── package.json             68   manifest: exports / dsh.bundle.patch / dsh.client / icon
 ├── cordis.patch.yml         17   the bundle's configuration layer (inserts the row with id `hitl`)
 ├── icon.svg                  6   the plugin list icon
+├── LICENSE                       MIT
 ├── README.md                     this document
 └── README.zh.md                  the Chinese twin of this document
 ```
@@ -392,7 +447,7 @@ dsh-hitl/
 | `index.js`, `lib/*.js` | host half (Node) | **restart dsh**. Node's ESM module cache is not invalidated by "disable → enable on that row" |
 | `client.js` | browser half | **client hot-reload** picks it up (the host stats each row's client artefact every 500ms and broadcasts over `/plugins/events`); no page refresh needed |
 | `locale/*.json` | plugin-list metadata | when the plugin manager re-reads metadata (opening the plugins page / restarting dsh) |
-| `docs/*.png` | documentation | when the README is rendered |
+| `docs/*.png` | screenshot sources | kept in the repository only; the published package excludes them (see the appendix note) |
 | `package.json`, `cordis.patch.yml` | manifest and config layer | a restart or a reload of that row; an installed package is not swapped in place |
 | `tests/*.js` | development | never runs in production; executed by `npm test` / `node --test` |
 
@@ -408,7 +463,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # syntax
-npm test                                     # 151 zero-dependency cases: pure functions, state machines, the channel
+npm test                                     # 167 zero-dependency cases: pure functions, state machines, the channel
 npm run check                                # both of the above (syntax + the whole suite)
 ```
 

package/README.zh.md

@@ -1,5 +1,7 @@
 # dsh-hitl · 给任意工具挂上人工决策（Human-in-the-loop）
 
+[![npm version](https://img.shields.io/npm/v/dsh-hitl)](https://www.npmjs.com/package/dsh-hitl) [![license](https://img.shields.io/npm/l/dsh-hitl)](LICENSE) [![官网](https://img.shields.io/badge/%E5%AE%98%E7%BD%91-4c566a)](https://yunpengdon.github.io/dsh-hitl-landing/)
+
 [English](README.md) | 中文
 
 > **让 Agent 在动手之前，先问你一句。**
@@ -8,7 +10,7 @@
 `dsh-hitl` 是 DeepSeek Harness (DSH) 的可安装插件（bundle）：**零依赖、零构建**——`index.js`（宿主半）+ `client.js`（浏览器半）+ `lib/`
 全是可直接加载的纯 JS，装上刷新一次页面就能用。
 
-![一张完整的决策卡：标题 + 待决策提案 + 同意/修改/拒绝 + 倒计时](docs/01-panel-cn.png)
+**[访问网站](https://yunpengdon.github.io/dsh-hitl-landing/)**
 
 ## 主要功能
 
@@ -19,7 +21,6 @@
 - **带反馈文本的拒绝**：【拒绝】可以带一个**反馈栏**，在反馈栏中写下的意见会随拒绝一起交给 Agent——它知道"不要做"，也知道"为什么不要做"；
 - **支持倒计时配置**：可配置**倒计时**与三种结局（**自动同意 / 自动拒绝 / 把超时事件反馈给 Agent**）；
 
-![提案区三种形态同框：并排 diff / 文本输入框 / markdown 的预览与编辑](docs/02-fields-cn.png)
 
 ## 为DSH定制的适配
 
@@ -28,12 +29,12 @@
 「来自子代理会话 xxx」+【前往该会话】。
 （跨进程后端不进这道门禁，见 §6.1。）
 
-![主对话里的卡片：标着「来自子代理会话」+【前往该会话】](docs/03-subagent-cn.png)
+[在 landing page 上看这张卡 →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 **不在对话界面上时，支持弹出迷你批准请求** 切到插件页、打开设置、甚至没选会话时，页面顶部会浮出一条提醒事项，减少用户不在对话页时HITL对流程的阻塞。
 （条数、工具名、来源会话、剩余时间 +【同意】【拒绝】【前往该会话】）。
 
-![设置面板之上浮着的兜底提醒条](docs/04-overlay-cn.png)
+[在 landing page 上看这条浮层 →](https://yunpengdon.github.io/dsh-hitl-landing/)
 
 ---
 
@@ -155,9 +156,10 @@ export function apply(ctx) {
 | `reject.feedbackPrompt` | string | 内置文案 | 反馈栏 placeholder |
 | `reject.requireFeedback` | boolean | `false` | 反馈必填（为空时拒绝按钮会提示） |
 | `modify.mode` | `revise-request` \| `allow-and-inform` | `revise-request` | 用户改了文本后点【修改】的语义，见 §5 |
-| `whenUnavailable` | `reject` \| `wait` | `reject` | 没有任何浏览器连接时的行为（`reject` = fail-closed） |
+| `whenUnavailable` | `reject` \| `wait` | `reject` | 没有任何浏览器连接时的行为：`reject` = fail-closed；`wait` = 一直等，**务必配 `countdown`**，否则那次调用会挂到会话结束（挂载时宿主会给 `dsh-hitl:` 警告），见 §7.1 |
 | `enabled` | boolean \| `(exec) => boolean` | `true` | 临时关闭 / 条件挂载 |
 | `maxFieldChars` | number | `20000` | 单字段渲染上限，超出会截断并提示 |
+| `resolveTimeoutMs` | number | `5000` | 单个**计算字段**的解析上限；超时或抛错只让那个字段显示失败，不阻断这次调用 |
 
 ### FieldSpec
 
@@ -166,6 +168,7 @@ export function apply(ctx) {
   render: 'markdown',        // markdown | text | diff | json | hidden
   editable: true,            // 覆盖默认可编辑性
   labels: ['不可撤销'],       // 字段级标签
+  value: '固定文案',          // 该字段的文本：字面量，或 (exec) => string | Promise<string>
   diff: { before: 'old_string', after: 'new_string', path: 'file_path' } }   // render: 'diff' 时用
 ```
 
@@ -173,6 +176,30 @@ export function apply(ctx) {
 - `fields` 给定时**只显示**列出的字段（未列出的参数不会出现在面板里）。
 - 配置行里可以简写成字符串：`fields: ['command', { param: 'cwd', title: '工作目录' }]`。
 
+### 计算字段：把参数之外的东西放进卡里
+
+`diff.before` / `diff.after` / `diff.path` 平时填的是**参数名**（宿主取 `args[名字]`）。它们与字段的 `value` 一样，也可以填**函数**：宿主在弹卡前用这次调用的 `exec` 调它，把返回值当作文本。
+
+```js
+ctx.hitl.protect('update_index', {
+  title: '更新知识树索引',
+  fields: [
+    { param: 'content', title: '新索引正文', render: 'markdown' },
+    { param: 'index', title: '索引文件的变化', render: 'diff', editable: false,
+      // before 读磁盘上的旧索引，after 由新正文推出来——两者都不在参数里
+      diff: { path: 'index.md',
+              before: async exec => readIndexFile(exec),
+              after: exec => `# 知识树索引\n\n${exec.arguments.content}` } },
+  ],
+})
+```
+
+- 字符串形式的 `diff.path` 若**不是**某个参数名，就当作字面路径使用：被改的文件常常不是这次调用的参数。
+- 函数可以是 async；每个字段的解析上限是 `resolveTimeoutMs`（默认 5s）。
+- **解析失败不阻断**：函数抛错或超时，只会把**那个字段**变成一行 `⚠️ 无法解析该字段：…`，卡照常弹出、人照常决策。整个解析过程坏掉时，提案退回到"参数原样"，而不是拒绝调用。
+- wire 格式与浏览器半都没有变化：diff 的两侧本来就在帧里，前端只是照常渲染。
+- diff 的每一侧超过 `maxDiffLines`（2000 行）会被截断并标注，避免整文件 diff 变成无上限的一帧。
+
 ### 倒计时的三种结局
 
 `countdown.action` 决定倒计时归零后宿主怎么判：
@@ -340,6 +367,21 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
   想让它在无人值守时一直等，把 `whenUnavailable` 设为 `wait`。
 - 插件在没有任何 Web 服务的组合里（headless/TUI）**仍然激活并继续拦**——"没有 UI 就不拦"不是本插件的语义。
 
+### 7.1 安全边界：HITL 拦得住什么、拦不住什么
+
+- **它拦的是"这一次调用在真正执行之前"，不是世界状态。** 如果工具在自己的执行层已经产生了副作用（并发竞态、异步落盘、
+  已经发出去的外部请求），拒绝只能阻止"接下来"，回滚不了"已经"——**HITL 不是事务，也不是沙箱**。
+- 所以实际安全程度取决于两件事：**① 你的 matcher 覆盖了多危险的操作；② 工具是否把不可逆动作放在最后一刻。**
+  把 `bash` / `write` / `edit` 这类"入口即危险"的工具挂上是对的；若某个工具的风险要到执行中途才出现，HITL 只能替你决定"要不要开始"。
+- **用户的同意 ≠ 越权**：同意之后沙箱、guard、hooks、审批照常随后生效（§8）；反过来，别的执行前策略也可能**先于**本插件拒绝——
+  实测过一次：`fs-observation-policy` 在用户点【同意】之前就把调用挡了，HITL 连面板都没弹（见 §8）。
+- **`whenUnavailable: wait` 是 fail-open**：没有任何浏览器连接时会一直等，没配 `countdown` 就是等到会话结束。
+  想让"无人值守也不卡死"，用默认的 `reject`，或者 `wait` + `countdown`（挂载时宿主会对这种组合给出警告）。
+- **本机信任边界**：决策通道与 `/status` 都只认回环地址。同机任意进程可以读 `/status`，它只含**挂载列表**与**待决策的
+  工具名 / 会话 id / 剩余毫秒 / 是否暂停**——**没有工具参数，也没有令牌**。要把这个口子量准：同机进程本来就能读
+  `~/.dsh/sessions/**` 的会话日志，而那里有完整的工具参数，所以 `/status` 的暴露面是它严格更小的子集。
+  这个口子是有意保留的：没有它，在终端里回答"HITL 现在拦着什么"就只能靠翻页面。
+
 ---
 
 ## 8. 与其他执行前策略的关系
@@ -347,6 +389,9 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 - 本插件用 `tools/pre-execute` 且 `prepend: true`，也就是**先问人**；用户同意后，
   沙箱、guard、hooks、审批等其它策略照常随后生效。**用户的同意不等于越权**。
 - 因此可能出现"用户同意了，但工具仍被沙箱/守卫拒绝"——这是设计使然，不是 bug。
+- **反过来也成立**：别的执行前策略可能在**本插件之前**就拒绝，此时 HITL 面板根本不会出现——所以"没弹面板就直接执行了/就失败了"
+  两种现象都要先看别的策略。实测过一次：`fs-observation-policy` 要求"重写已删除文件前先重读"，
+  它在用户点【同意】**之后**把调用挡了下来（面板照常弹过），也在另一轮里**先于**本插件直接拒绝（面板没弹）。
 - 本插件只做"执行前问人"，不改变工具参数、不改变工具结果。
 
 ---
@@ -354,6 +399,7 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 ## 9. 已知限制
 
 - **不能改写工具参数**（见 §5），所以【修改】默认走"拒绝并交回修改内容"。
+- **HITL 不是副作用边界**（见 §7.1）：它拦的是"调用开始之前"，回滚不了已经发生的副作用；安全性取决于 matcher 覆盖面与工具自身的设计。
 - **挂载文案不本地化**：`title` / `labels` / 字段标题都是挂载方给的字符串，本插件不翻译，也不接受 `{zh, en}` 映射（见 §6.3）。
 - **不写会话审计事件**：DSH 不允许插件追加新的事件类型，决策痕迹只存在于工具结果（和 `allow-and-inform` 的那条 user 消息）里。
 - **只有 Web 界面有面板**：ACP/TUI/headless 下按 `whenUnavailable` 处理（默认拒绝）。
@@ -428,28 +474,30 @@ Error: HITL: no human decision arrived within 75s, so tool "glob" did not run. T
 
 ```text
 dsh-hitl/
-├── index.js                629   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
+├── index.js                666   宿主半：服务 + 门禁 + 倒计时/持握 + SSE/决策路由 + 令牌注入
 ├── client.js              1918   浏览器半：决策面板 + 帧级浮层（自包含 classic script，无 import）
 ├── lib/                          宿主半的纯逻辑：不碰 Cordis、不碰 DOM，可单独跑测试
-│   ├── protocol.js         182   帧与上行校验、上限、错误码（协议规范的唯一出处）
-│   ├── resolve.js          302   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
-│   ├── fields.js           244   默认提案推导、diff 配对、决策 → 模型可见文本
+│   ├── protocol.js         195   帧与上行校验、上限、错误码（协议规范的唯一出处）
+│   ├── resolve.js          363   matcher 编译（名字/通配/RegExp/谓词）、挂载选项归一化与诊断
+│   ├── fields.js           449   默认提案推导、diff 配对、计算字段解析、决策 → 模型可见文本
 │   └── pending.js          217   待决策状态机（可注入时钟）：倒计时、持握、恰好一次的结算
 ├── locale/                       插件列表里的名字与简介（形状必须是 {"meta":{...}}，见 §6.3）
 │   ├── en.json               6
 │   └── zh.json               6
-├── docs/                         上文那些截图，中英各一套（-cn / -en）
-├── tests/                        零依赖 Node 测试，共 151 个用例
+├── docs/                         截图源文件，**故意不进 npm 包**：README 改为链接 landing page
+├── tests/                        零依赖 Node 测试，共 167 个用例
 │   ├── client.test.js      818   （65）浏览器半的纯函数 + store / connection / seat
-│   ├── fields.test.js      269   （26）提案推导与决策文本
+│   ├── fields.test.js      387   （37）提案推导、计算字段与决策文本
 │   ├── pending.test.js     240   （18）状态机（注入时钟，无真实等待）
-│   ├── resolve.test.js     162   （18）matcher 与选项归一化
+│   ├── resolve.test.js     224   （22）matcher 与选项归一化
 │   ├── protocol.test.js    117   （16）帧与上行校验
-│   ├── docs.test.js        116   （5）两份 README、互链，以及上面这张表里的每个数字
-│   └── manifest.test.js     61   （3）包元数据与 locale 资源形状
-├── package.json             69   清单：exports / dsh.bundle.patch / dsh.client / icon
+│   ├── docs.test.js        121   （5）两份 README、landing page 链接，以及上面这张表里的每个数字
+│   └── manifest.test.js     77   （4）包元数据与 locale 资源形状
+├── .github/workflows/release.yml     tag-triggered publish via npm trusted publishing (OIDC)
+├── package.json             68   清单：exports / dsh.bundle.patch / dsh.client / icon
 ├── cordis.patch.yml         17   bundle 的配置层（插入 id 为 hitl 的那一行）
 ├── icon.svg                  6   插件列表图标
+├── LICENSE                       MIT
 ├── README.md                     本文档（英文版）
 └── README.zh.md                  本文档的中文版
 ```
@@ -461,7 +509,7 @@ dsh-hitl/
 | `index.js`、`lib/*.js` | 宿主半（Node） | 必须**重启 dsh**。Node 的 ESM 模块缓存不会因为"禁用→启用这一行"而失效 |
 | `client.js` | 浏览器半 | **客户端热重载**自动拾取（宿主每 500ms stat 一次各行的 client 产物并广播 `/plugins/events`），不用刷新页面 |
 | `locale/*.json` | 插件列表元数据 | 插件管理器重读元数据时生效（打开插件页 / 重启 dsh） |
-| `docs/*.png` | 文档 | README 渲染时 |
+| `docs/*.png` | 截图源文件 | 只留在仓库里；发布的包里不再包含（见附录说明） |
 | `package.json`、`cordis.patch.yml` | 清单与配置层 | 需要重启或重新加载该行；已安装包不会被就地替换 |
 | `tests/*.js` | 开发期 | 不参与运行，只由 `npm test` / `node --test` 执行 |
 
@@ -483,7 +531,7 @@ dsh-hitl/
 
 ```sh
 node --check index.js client.js lib/*.js     # 语法
-npm test                                     # 151 个纯函数/状态机/通道用例，零依赖
+npm test                                     # 167 个纯函数/状态机/通道用例，零依赖
 npm run check                                # 上面两步合起来（语法 + 全部用例）
 ```
 

package/index.js

@@ -21,7 +21,9 @@ import {
   DEFAULT_ENDPOINT, ERROR_CODES, GLOBAL_KEY, LIMITS, OUTCOMES, errorBody, frameHoldAck,
   framePing, frameRequest, frameSettled, frameSnapshot, okBody, parseUplink, sseChunk,
 } from './lib/protocol.js'
-import { buildRequest, capReason, describeDecision, isRevision, revisionContext } from './lib/fields.js'
+import {
+  buildRequest, capReason, describeDecision, hasComputed, isRevision, resolveFields, revisionContext,
+} from './lib/fields.js'
 import { DEFAULT_HOLD_GRACE_MS, createPendingRegistry } from './lib/pending.js'
 import { matchMount, mountApplies, normalizeMount, normalizeProtectList } from './lib/resolve.js'
 
@@ -107,7 +109,14 @@ export function apply(ctx, config = {}) {
   const clients = new Set()
   const resolvers = new Map()
   const cleanups = new Map()
-  const revisions = new Map()
+  // Revision context for `allow-and-inform`, keyed by the execution object the
+  // pipeline carries from `tools/pre-execute` through `tools/post-execute`.
+  // A WeakMap, not a callId-keyed Map: if a call is allowed and then never
+  // reaches post-execute (an aborted turn, a process torn down mid-execution),
+  // a Map entry would outlive the call for the rest of the process. Keyed by
+  // the execution itself, the entry dies with the call that owns it, so there
+  // is nothing to leak and nothing to remember to clean up.
+  const revisions = new WeakMap()
 
   const registry = createPendingRegistry({
     holdGraceMs: positiveInteger(options.holdGraceMs, DEFAULT_HOLD_GRACE_MS),
@@ -227,6 +236,8 @@ export function apply(ctx, config = {}) {
       rejectFeedback: mount.options.reject.feedback,
       modify: mount.options.modify.mode,
       whenUnavailable: mount.options.whenUnavailable,
+      /** Whether this mount's proposal needs the host to compute a field. */
+      computed: hasComputed(mount.options),
     })),
     /** Every decision still waiting for a human, oldest first. */
     pending: () => registry.list().map(request => ({
@@ -293,7 +304,9 @@ export function apply(ctx, config = {}) {
     if (settlement.decision.kind === 'cancel') return { kind: 'cancel' }
     const revising = isRevision(settlement.decision)
     if (revising && mount.options.modify.mode === 'allow-and-inform' && settlement.source === OUTCOMES.user) {
-      if (exec.callId !== undefined) revisions.set(String(exec.callId), { request, decision: settlement.decision })
+      // The call is about to run with its original arguments; the edit rides
+      // along as context on the result instead (see the post-execute listener).
+      revisions.set(exec, { request, decision: settlement.decision })
       return { kind: 'allow' }
     }
     const info = settlement.source === OUTCOMES.timeout
@@ -306,6 +319,23 @@ export function apply(ctx, config = {}) {
     }
   }
 
+  /**
+   * Collect a mount's computed fields for one call.
+   *
+   * If the resolution itself breaks, the proposal degrades to the call's own
+   * arguments: a panel of raw parameters is still a decision the human can make,
+   * while a denied call is not. A resolver that fails on its own degrades inside
+   * `resolveFields` instead, into one field that says so.
+   */
+  async function resolutionFor(exec, mount) {
+    try {
+      return await resolveFields(exec, mount, { timeoutMs: mount.options.resolveTimeoutMs, warn })
+    } catch (error) {
+      warn(`the computed fields of tool ${JSON.stringify(exec.name)} could not be resolved: ${String(error)}`)
+      return undefined
+    }
+  }
+
   async function gate(exec, next) {
     let mount
     try {
@@ -326,7 +356,13 @@ export function apply(ctx, config = {}) {
     }
     const id = `hitl:${String(exec.callId ?? randomUUID())}`
     try {
-      const request = buildRequest({ execution: exec, mount, sessionId, id })
+      const request = buildRequest({
+        execution: exec,
+        mount,
+        sessionId,
+        id,
+        resolution: await resolutionFor(exec, mount),
+      })
       const settlement = await waitForDecision(id, request, mount, exec)
       return toPreToolDecision(exec, request, mount, settlement)
     } catch (error) {
@@ -342,17 +378,17 @@ export function apply(ctx, config = {}) {
 
   /**
    * Hand the user's revision to the model next to the result it approved, in
-   * the `allow-and-inform` modify mode. The message is built to the shape
-   * `createUserMessage` produces, because a plain bundle cannot import that
-   * factory; `source.kind` is the standard `user` one.
+   * the `allow-and-inform` modify mode. Lookup is by the execution object, so a
+   * call that never reaches this stage costs nothing but its own lifetime; the
+   * delete keeps a second post-execute for the same execution from attaching
+   * the same context twice.
    */
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    if (revisions.size === 0 || exec.callId === undefined) return decision
-    const key = String(exec.callId)
-    const revision = revisions.get(key)
+    const revision = revisions.get(exec)
     if (revision === undefined) return decision
-    revisions.delete(key)
+    revisions.delete(exec)
+    const label = exec.callId === undefined ? String(exec.name) : String(exec.callId)
     try {
       const message = {
         id: randomUUID(),
@@ -362,7 +398,7 @@ export function apply(ctx, config = {}) {
       }
       return { ...decision, additionalContexts: [...(decision.additionalContexts ?? []), message] }
     } catch (error) {
-      warn(`the revision context for ${key} was dropped: ${String(error)}`)
+      warn(`the revision context for ${label} was dropped: ${String(error)}`)
       return decision
     }
   })
@@ -622,7 +658,8 @@ export function apply(ctx, config = {}) {
       }
     }
     mounts.length = 0
-    revisions.clear()
+    // `revisions` is a WeakMap: shutdown has nothing to clear, and a call that
+    // never came back takes its own entry with it.
     resolvers.clear()
     cleanups.clear()
   }, 'dsh-hitl: shutdown')