Plugin seams for reversible secret tokenization — tool-argument rewriting and assistant-text restore

[jkt-check]

English

Title: Plugin seams for reversible secret tokenization — tool-argument rewriting and assistant-text restore

Who

We maintain dsh-secret-scrub, a dsh plugin that rewrites text on its way to the session log and the model: secret-shaped fragments (API keys, tokens, private key blocks, PII) are replaced irreversibly with [REDACTED:<category>] placeholders. It works entirely through the published plugin events (agent/pre-step, tools/post-execute, tools/ptc-dispatch-log).

The use case

Users want the model to complete tasks that involve their secrets — write a config file containing the real API key, construct an authenticated curl command, fill in a .env — without the real values ever reaching the model or the durable session log.

The standard pattern for this is vault tokenization:

1. Outbound (toward the model): replace each real secret with a shape-preserving random token (e.g. a real sk-ant-api03-… becomes a different, well-formed sk-ant-api03-…), recording the token → real-value mapping in a local, in-memory, session-scoped vault that never leaves the machine.
2. The model sees only tokens and treats them as real values — it writes configs, builds commands, reasons normally.
3. Inbound (away from the model): restore tokens to real values at the two points where model output becomes user-visible effect:
   • tool-call arguments, before execution — so write_file(content="…token…") writes the real value to disk;
   • assistant text, before display — so the final answer the user reads contains the real values.

What works today

Outbound rewriting is well covered by the existing waterfalls: agent/pre-step (admitted user messages), tools/post-execute (accepted tool results), and tools/ptc-dispatch-log (the durable copy of run_code sub-dispatches). Our plugin already does the tokenization half on these seams.

What is missing — two blockers

Neither restore point is reachable from a plugin today:

1. Tool-call arguments cannot be rewritten before execution.
   PreToolDecision is allow | deny | ask only, and the type documentation states the exclusion explicitly: "Input rewriting is excluded because arguments are already logged and presented." The around-dispatch tools/execute waterfall "may change only exec.signal, while call identity remains immutable." So a write_file call carrying a token executes with the token verbatim.

2. Assistant text cannot be rewritten before display.
   Session events are append-only and deep-frozen; session/event is emit-only, and the agent/request waterfall "cannot mutate messages." There is no seam on the presentation path between the model's emitted text and what the user sees.

A related outbound gap shares blocker 1: tool-call arguments also cannot be scrubbed today — a secret the model legitimately echoes into a tool call lands in the durable log unredacted. The same seam would let plugins redact the logged copy.

Requests

• R1 — a tool-argument rewriting seam. For example, a PreToolDecision variant such as { kind: 'allow', args }, or a dedicated waterfall positioned after the original call is logged/presented and before the body dispatches. This placement has a clean security story: the durable log and the presented call keep the tokenized arguments, while the tool body receives the restored values. Call identity, signal re-fusion, scope filtering, and listener-failure containment can all be preserved unchanged.
• R2 — an assistant-text display seam. A waterfall on the presentation/projection path that may replace text blocks for display only, without mutating the durable session log — the log keeps tokens, the user reads real values.

Non-goals

We are not asking dsh to implement the vault, the tokenization, or any secret handling — only the two rewrite seams. The plugin owns the mapping and its security invariants (memory-only, session-scoped, never logged).

We are happy to prototype either seam and share the branch.

---

中文

标题： 可逆密钥令牌化所需的插件接缝 —— 工具参数改写与助手文本还原

我们是谁

我们维护着 dsh 插件 dsh-secret-scrub：它在文本进入会话日志和模型请求之前做不可逆打码，把密钥形态的片段（API key、token、私钥块、PII）替换为 [REDACTED:<category>] 占位符。插件完全基于已发布的插件事件（agent/pre-step、tools/post-execute、tools/ptc-dispatch-log）实现。

使用场景

用户希望模型完成涉及真实密钥的任务——把真实 API key 写进配置文件、构造带凭证的 curl 命令、填写 .env——但真实值永远不进入模型上下文和持久化会话日志。

标准做法是令牌化（vault tokenization）：

1. 出站（发往模型）：把每个真实密钥替换为形状保持的随机令牌（例如真实的 sk-ant-api03-… 换成另一个合法形态的 sk-ant-api03-…），令牌 → 真实值的映射记录在本机内存中的会话级 vault 里，永不出机。
2. 模型只能看到令牌，并将其当作真实值使用——正常写配置、构造命令。
3. 入站（离开模型）：在模型输出产生用户可见效果的两个点上把令牌还原为真实值：
   • 工具调用参数，执行前还原——让 write_file(content="…令牌…") 落盘的是真实值；
   • 助手文本，展示前还原——让用户读到的最终答案包含真实值。

目前已可行的部分

出站改写已被现有 waterfall 良好覆盖：agent/pre-step（准入的用户消息）、tools/post-execute（被接受的工具结果）、tools/ptc-dispatch-log（run_code 子调度的持久化副本）。我们的插件已经在这些接缝上完成了令牌化的一半。

缺失的部分 —— 两个堵点

两个还原点目前都无法从插件触达：

1. 工具调用参数无法在执行前改写。
   PreToolDecision 只有 allow | deny | ask，类型注释明确写着排除原因："Input rewriting is excluded because arguments are already logged and presented." 环绕执行的 tools/execute waterfall 也声明 "may change only exec.signal, while call identity remains immutable"。携带令牌的 write_file 调用会原样带着令牌执行。

2. 助手文本无法在展示前改写。
   会话事件是 append-only 且深冻结的；session/event 是只读观察（emit 模式）；agent/request waterfall "cannot mutate messages"。模型输出文本与用户可见内容之间的展示链路上没有任何接缝。

一个相关的出站缺口与堵点 1 同源：工具调用参数目前也无法被打码——模型合理回显进工具参数里的密钥会未打码地落入持久化日志。同一个接缝可以解决这个问题。

请求

• R1 —— 工具参数改写接缝。 例如为 PreToolDecision 增加 { kind: 'allow', args } 变体，或提供一个专用 waterfall，位置在原始调用被记录/展示之后、工具体执行之前。这个位置的安全语义很干净：持久化日志和展示层保留令牌化参数，工具体拿到还原后的真实值。调用身份不可变、signal 重融合、scope 过滤、监听器失败隔离等现有保证都可以原样保留。
• R2 —— 助手文本展示接缝。 在展示/投影链路上提供一个 waterfall，允许仅针对展示替换文本块，不改变持久化会话日志——日志保留令牌，用户读到真实值。

非目标

我们不要求 dsh 实现 vault、令牌化或任何密钥处理逻辑——只需要这两个改写接缝。映射表及其安全不变量（仅内存、会话级、永不落日志）由插件自己负责。

我们乐意就任一接缝提供原型实现。

[argszero]

@jkt-check 你的两个堵点我在 d347e7039（v0.1.3-alpha.1, 当前 master）源码上逐项核对了——R1 和 R2 都在源头上成立。补充精确的落脚点, 方便与 maintainer 对齐。

R1 —— 工具参数执行前改写: 确认无 seam

packages/core/tools/src/index.ts:581 的 PreToolDecision 确实只有 allow | deny | ask 三种, 且 :578 的注释原文明写: "Input rewriting is excluded because arguments are already logged and presented." 两处都与你引用的字面完全一致。

tools/pre-execute（:144）返回的就是这个 PreToolDecision; tools/execute around-dispatch（:147）注释原文 "wrappers may change only exec.signal, while call identity remains immutable" —— 所以没有任何一个 waterfall 允许改参数。你断言"write_file 携带令牌会原样带令牌执行"是对的。

一个值得注意的语义细节: 参数早在 pre-execute 之前就已经落日志并被展示了——这正是"参数既已 logged+presented 所以排除改写"的理由。所以 R1 的 { kind: 'allow', args } 或"记录/展示之后、body 派发之前"的专用 waterfall 定位, 安全语义是干净的: 持久化日志和展示层保留令牌, 工具体拿到还原值。这个定位我完全同意——它恰好把"改的是执行用副本, 不改 durable log 与 presented call"分开, 与现有的 call identity + signal 重融合保证正交。

R2 —— 助手文本展示前改写: 确认无 seam

session/event 是 emit-only（packages/core/agent-loop/tests/contract-regressions.spec.ts 只读观察）, agent/request 返回 LlmCallConfig 且"cannot mutate messages"。展示/投影链路上确实没有可替换文本块的 waterfall。你的"仅展示替换, 不改 durable log"诉求是对的——但注意这要求 new seam 在 projection 路径上, 需要 maintainer 明确"presentation-only replace"的语义边界。

关联点: 同源第 3 个 gap 可一并考虑

R1 堵点其实还附带一个出站打码缺口: 模型合理回显进工具参数里的密钥会未打码落入持久化日志。你说的"同一个 seam 可以解决"成立。若维护者要为 R1 开 seam, 建议同时把"打码 logged copy"（执行复制用还原值, 落盘复制用令牌/打码值）纳入——这比只做执行前还原更完整。

与此相关, 我维护的 @argszero/cordis-plugin-session-audit 在做会话日志完整性审计时, 也已遇到"工具调用参数在 durable log 里的可观测性"问题——如果这类 tokenization/scrub seam 落地, session 审计侧的"参数是否已打码"也会成为可检测的审计信号（当前是不变量不可观测）。暂不展开, 只是说明这个方向与既有插件有真实交集, 值得社区持续跟进。

补充一个我源级看到的边界: throwGuardedCreateFailure（fs-local/src/fsio.ts:481-516）对"无硬链接支持"与"目标已存在"做了碰撞性区分, 说明 dsh 内部其实已经意识到不同文件系统下 link 的 errno 值不稳定——这正好是"seam 必须在执行侧还原、不能依赖 Linux 语义"的一个旁证。非本题, 仅供参考。

总之: R1/R2 的缺失是真实的、源级可证的。你的提案把 vault/tokenization 留给插件、只索要两个 rewrite seam, 边界清晰, 是健康的插件面扩展。我支持。

[jkt-check]

这是我们项目dsh-secret-scrub 地址：https://github.com/jkt-check/dsh-secret-scrub @jkt-check/dsh-secret-scrub
可关注，审计也是AI 安全必须的能力，支持 @argszero/cordis-plugin-session-audit