@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +127 -83
  2. package/README.zh-CN.md +106 -74
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +24 -15
  8. package/adapters/dsh/harness/README.md +75 -19
  9. package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
  10. package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
  11. package/adapters/dsh/harness/guard_lab.py +194 -32
  12. package/adapters/dsh/harness/native_session.py +41 -20
  13. package/adapters/dsh/harness/profiles.py +74 -22
  14. package/adapters/dsh/lib/index.js +1 -1
  15. package/adapters/kimi-code/README.md +15 -14
  16. package/adapters/kimi-code/harness/README.md +3 -3
  17. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  18. package/core/__init__.py +1 -1
  19. package/core/classifier.py +41 -16
  20. package/core/lab.py +24 -1
  21. package/core/policy.py +11 -4
  22. package/core/recovery.py +256 -23
  23. package/core/redaction.py +157 -55
  24. package/core/trash_index.py +193 -0
  25. package/docs/README.md +104 -0
  26. package/docs/{architecture.md → design/architecture.md} +31 -6
  27. package/docs/{compatibility.md → design/compatibility.md} +54 -4
  28. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  29. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  30. package/docs/guides/trash-index.md +106 -0
  31. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +8 -9
  32. package/docs/{friction.md → history/friction.md} +107 -4
  33. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +23 -22
  34. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +6 -4
  35. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +19 -15
  36. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  37. package/docs/{guard-lab.md → lab/guard-lab.md} +18 -11
  38. package/docs/lab/tasks/guard-lab-read-trial-task.md +7 -0
  39. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +5 -5
  40. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +7 -7
  41. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  42. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +9 -10
  43. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +4 -2
  44. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  45. package/docs/releases/release-notes-0.2.3.md +84 -0
  46. package/docs/releases/release-notes-0.2.4.md +89 -0
  47. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  48. package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
  49. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  50. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  51. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  52. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  53. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  54. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  55. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  56. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
  57. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  58. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
  59. package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
  60. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
  61. package/package.json +1 -1
  62. package/skills/delete-guard/SKILL.md +40 -3
  63. package/skills/delete-guard/references/policy.md +18 -5
  64. package/skills/delete-guard/scripts/check.py +19 -0
  65. package/skills/delete-guard/scripts/restore.py +18 -6
  66. package/skills/delete-guard/scripts/status.py +52 -0
  67. package/skills/exfil-guard/SKILL.md +37 -7
  68. package/skills/exfil-guard/references/channels.md +1 -1
  69. package/skills/exfil-guard/references/rules.md +84 -16
  70. package/skills/exfil-guard/scripts/_payload.py +99 -0
  71. package/skills/exfil-guard/scripts/check_span.py +14 -81
  72. package/skills/exfil-guard/scripts/sanitize.py +113 -34
  73. package/docs/release-notes-0.2.3.md +0 -45
  74. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  75. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  76. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  77. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  78. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  79. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  80. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  81. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
package/README.zh-CN.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm 版本](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![v0.2.3-rc2 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.3--rc2-5B6B7A)](docs/release-notes-0.2.3-rc2.md)
7
+ [![v0.2.4 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.4-5B6B7A)](docs/releases/release-notes-0.2.4.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -31,29 +31,31 @@ Core、决策协议与 Skills 是产品本体,适配器只是可替换的接
31
31
  ```text
32
32
  rm -rf build/ → RELOCATE # 工作区内目录先迁入隔离区
33
33
  rm -rf . → BLOCK # 保护工作区根目录
34
- git reset --hard → SNAPSHOT # Git 状态允许时先做快照
34
+ git reset --hard → SNAPSHOT # 先检查路径冲突,再保存已跟踪修改
35
35
  git push --force → BLOCK # 不自动改写远端历史
36
36
  ```
37
37
 
38
38
  这是受支持输入的**示意判决**,不是让你执行这些命令,也不表示所有宿主都会
39
- 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;Git 快照无法建立时会
40
- 保守拒绝。能恢复或安全改写时,Agent 可以继续工作;否则交给人或阻断。
39
+ 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;hard reset 的目标树与未跟踪
40
+ 或忽略内容冲突,或无法完成预检/快照时,会保守拒绝。能恢复或安全改写时,
41
+ Agent 可以继续工作;否则交给人或阻断。
41
42
 
42
43
  ## 让编码 Agent 帮你接入
43
44
 
44
- 可以在 npm registry 可用后安装带作用域的包,也可以保留一个稳定的 Git
45
- checkout。不要误装无作用域的同名 `agent-guard` 包。
45
+ 可以安装带作用域的 npm 包,也可以保留一个稳定的 Git checkout。
46
+ 无作用域的同名 `agent-guard` 包与本项目无关。
46
47
 
47
48
  把固定版本安装到用户选择的稳定路径:
48
49
 
49
50
  ```sh
50
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
51
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
51
52
  ```
52
53
 
53
- `0.2.2` 仍是稳定版推荐。已发布的预览版
54
- `@mokuyoaxis/agent-guard@0.2.3-rc1` 也可通过 npm `@rc` 安装,但它不含
55
- guard-lab。当前 checkout 是 `0.2.3-rc2` 源码候选;是否已经发布,请以
56
- Releases 与 npm 为准。预发布不会替换 npm `latest`。
54
+ **0.2.4** 包含 hard reset 碰撞检查、restore 来源/目标
55
+ 验证、强制恢复时保留当前版本,以及垃圾桶只读位置查询。
56
+ 本次行为变化与证据边界见 [发布说明](docs/releases/release-notes-0.2.4.md);
57
+ npm 徽章和 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
58
+ 展示实际可用的发布工件。
57
59
 
58
60
  安装后的包根目录是
59
61
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
@@ -69,7 +71,8 @@ Core 需要 Python 3.9+ 和 Git;是否能自动拦截取决于宿主是否提
69
71
 
70
72
  ```text
71
73
  请为当前工作区接入 agent-guard。只使用现有 Git checkout,或精确的 scoped
72
- npm 包 @mokuyoaxis/agent-guard@0.2.2;不要安装无作用域的同名 agent-guard。
74
+ npm 包 @mokuyoaxis/agent-guard@0.2.4;不要安装无作用域的同名
75
+ agent-guard。若 0.2.4 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
73
76
  安装前先让我选择并批准一个稳定的用户目录,然后把 checkout 或 npm 安装后的
74
77
  包根目录作为下文的 /absolute/path/to/agent-guard。
75
78
  先识别当前 harness 实际支持的 hook 与 Skill,阅读本 README 和对应 adapter
@@ -84,7 +87,7 @@ adapters/kimi-code/README.md,DSH 参考 adapters/dsh/README.md。
84
87
  拦截证明。最后报告宿主版本、工具范围、实际安装内容、确实拦截的调用和未验证路径。
85
88
  ```
86
89
 
87
- 手动接入与证据边界见 [harness 能力矩阵](docs/harness-capabilities.md)
90
+ 手动接入与证据边界见 [harness 能力矩阵](docs/guides/harness-capabilities.md)
88
91
  及对应的 adapter README。
89
92
 
90
93
  ## 设计原则
@@ -183,7 +186,7 @@ DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
183
186
  DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#experimental-text-read-redaction),
184
187
  仅覆盖版本门控下的完整原生读取。它复用同一 Core,并让 DSH 同时重新生成
185
188
  返回文本和展示元数据;零模型原生验证已覆盖下一次请求和 JSONL 落盘。
186
- 另一次[官方 Flash 真实直接读取对照](docs/test-report-dsh-real-followup.md)
189
+ 另一次[官方 Flash 真实直接读取对照](docs/reports/test-report-dsh-real-followup.md)
187
190
  观察到支持规则的合成秘密被脱敏,同时保留有用配置;这不是提示注入 L2 结论。
188
191
 
189
192
  它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
@@ -203,16 +206,21 @@ DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#exp
203
206
 
204
207
  ### 检测什么
205
208
 
206
- **T1 厂商凭据特征**(`secret/*`,确定性,误报接近零)。rule id 包括:
209
+ **T1 厂商凭据特征**(`secret/*`)。按已知格式识别,用文档化占位符和反例
210
+ 约束误伤。rule id 包括:
207
211
  `secret/openai-key`、`secret/github-token`、`secret/aws-access-key-id`、
208
212
  `secret/gitlab-token`、`secret/slack-token`、`secret/stripe-key`
209
- (仅 live key,`sk_test_` 豁免)、`secret/jwt`(结构化:头部必须 base64
210
- 解码为含 `alg` 的 JSON),以及 `secret/private-key-block`
211
- (整段 `-----BEGIN ... PRIVATE KEY-----` 一次性脱敏)。冻结规则表见
213
+ (仅 live key,`sk_test_` 豁免)、`secret/pypi-token`、`secret/jwt`(结构化:
214
+ 头部须解码为 JSON,且 `alg` 是非空 ASCII 字符串),以及 `secret/private-key-block`
215
+ (整段 `-----BEGIN ... PRIVATE KEY-----` 一次性脱敏)。规则表与保留边界见
212
216
  [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)。
213
217
 
214
- **不读值的密钥引用**(`secret/source-reference`)。Guard 只对变量**名**
215
- (`*KEY*`、`*TOKEN*`、`*SECRET*`、`*PASSWORD*`、`*CRED*`、`*AUTH*`)与
218
+ `secret/connection-password` 另检测 URI 用户信息中的非空口令,只遮口令,
219
+ 保留协议、账号与主机以便排错。支持百分号编码口令和 JSON 转义的协议斜杠;
220
+ 这不等于隐藏网络拓扑,也不覆盖所有 DSN 格式。
221
+
222
+ **不读值的密钥引用**(`secret/source-reference`)。Guard 按变量名中的完整
223
+ 组成部分(如 `KEY`、`TOKEN`、`SECRET`、`PASSWORD`、`PASSWD`、`CRED`、`AUTH`)与
216
224
  密钥库**文件名**(`.env`、`*.pem`、`id_rsa*`、`.netrc`、`kubeconfig` 等)
217
225
  分类,并识别整环境展开(`printenv`、`env | ...`、
218
226
  `cat /proc/self/environ`)。这个扫描器**不解析变量的值**;这不代表其他
@@ -264,6 +272,21 @@ echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.p
264
272
  `--json` 输出机器可读判决(仅偏移、rule id 与占位符——**绝不含匹配到的
265
273
  字节**);`--path` 为即将写入的文件启用仓库本地豁免文件。
266
274
 
275
+ `sanitize.py` 同样落实上述退出码:ASK/BLOCK 和错误时 stdout 不输出正文。
276
+ 外部 `--plan` 必须与当前扫描一致,改写后复扫通过才输出。两个 CLI 共用默认
277
+ 工作区和宿主模式;stdin 在读取时即受到扫描上限限制(默认 4 MiB),外部计划文件
278
+ 也受同一上限约束。checker 使用显式模式或路径豁免产生的计划,仍须满足 sanitizer
279
+ 当前策略;计划本身不是发送授权。
280
+
281
+ 凭据检测支持经典和 `ghs_APPID_JWT` GitHub 安装令牌,完整遮挡长签名,并能识别
282
+ 紧贴中文的凭据。占位符豁免要求完整形状,token 内偶然出现示例词不会整段放行。
283
+ 秘密变量引用按名称组成部分判断,保留 `MONKEY` 等普通标识符和 `TOKEN_COUNT`
284
+ 等元数据名称。支持的形式和限制见[规则说明](skills/exfil-guard/references/rules.md)。
285
+
286
+ 新增 PyPI 发布令牌识别,按官方前缀与最小 body 形状完整遮挡长令牌。AWS 组/
287
+ 用户/角色/策略 ID 与访问密钥 ID 分开处理;JWT header 的 `alg` 须为非空
288
+ ASCII 字符串。公钥变量名称与通用 `sk-` 形状仍保留已说明的保守边界。
289
+
267
290
  ### 不打印值地查看配置
268
291
 
269
292
  此 CLI 从 `0.2.0` 源码开始提供,**不属于**此前的 `0.2.0-rc2`
@@ -306,13 +329,14 @@ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config
306
329
  - **没有 hook 的信道在结构上不可达。** 无代理的托管模型调用、模型自身的
307
330
  工具调用、程序内部产生的内容、人类剪贴板,一律**不给判决**——不作任何
308
331
  覆盖声明。详见 `references/channels.md` 与
309
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 的
332
+ [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 的
310
333
  可达性表。
311
334
  - **不是文件扫描器。** 它不是 gitleaks 的替代品;它扫描 Guard 在**发出
312
335
  路径上**能看到的内容。
313
336
  - **不改写历史。** 检测到已经进入 git 历史的密钥最多只是一份报告。
314
337
  改写历史是需要人类执行、且自带风险的动作。
315
- - **本版本不含 T3 熵检测器。** 它是最大的单一误报来源,而目标场景并不需要它。
338
+ - **本版本不含 T3 熵检测器。** 不把看起来随机的字符串直接当作凭据,减少
339
+ 对普通标识符的干扰。
316
340
 
317
341
  ## 手动使用(不依赖特定 harness)
318
342
 
@@ -324,6 +348,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
324
348
 
325
349
  # 查看状态与恢复:
326
350
  python3 skills/delete-guard/scripts/status.py
351
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
327
352
  python3 skills/delete-guard/scripts/restore.py list
328
353
  python3 skills/delete-guard/scripts/restore.py <txid>
329
354
 
@@ -331,6 +356,10 @@ python3 skills/delete-guard/scripts/restore.py <txid>
331
356
  python3 skills/delete-guard/scripts/gc.py
332
357
  ```
333
358
 
359
+ 本地新增的[垃圾桶位置查询](docs/guides/trash-index.md)提供 Agent 与未来前端
360
+ 共用的只读 JSON 接口,报告指定范围内的位置候选与布局标识;不读取恢复内容,
361
+ 地址也不代表清理授权。这项能力包含在 0.2.4 中。
362
+
334
363
  受支持的 harness 适配器可在 shell 命令执行前调用 Guard,再将退出码映射
335
364
  为宿主自己的工具判决:
336
365
 
@@ -345,7 +374,7 @@ python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
345
374
  ## 受保护行为一览
346
375
 
347
376
  下列是命令确实进入 Guard、且目标符合所述条件时的示意结果;各宿主实际
348
- 验证到的范围见 [能力矩阵](docs/harness-capabilities.md)。
377
+ 验证到的范围见 [能力矩阵](docs/guides/harness-capabilities.md)。
349
378
 
350
379
  ```text
351
380
  rm -rf build/ → RELOCATE (整树隔离后放行)
@@ -355,7 +384,8 @@ rm *.log → BLOCK (不透明通配;safe_delete 会显式展
355
384
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
356
385
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
357
386
  git clean -fd → RELOCATE (先 -n 枚举迁移再放行)
358
- git reset --hard → SNAPSHOT (Git 状态允许建立快照时)
387
+ git reset --hard → SNAPSHOT (路径冲突预检 + 已跟踪修改快照)
388
+ reset 覆盖未跟踪内容 → BLOCK (先单独保存冲突内容)
359
389
  git push --force → BLOCK (远端历史不交给 Agent 自动处理)
360
390
  node_modules/(已 ignore) → ALLOW (可证明可再生)
361
391
  隔离区写满 → BLOCK (绝不回退到永久删除)
@@ -363,25 +393,32 @@ node_modules/(已 ignore) → ALLOW (可证明可再生)
363
393
 
364
394
  ## 接入与验证矩阵
365
395
 
366
- [![Node.js 20 smoke](https://img.shields.io/badge/Node.js-20%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
367
- [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/test-report-codex-gpt-6-astra-high.md)
368
- [![DSH 0.1.5-rc.1 宿主 BLOCK 实测](https://img.shields.io/badge/DSH%200.1.5--rc.1-%E5%AE%BF%E4%B8%BB%20BLOCK%20%E5%AE%9E%E6%B5%8B-4D6BFE)](docs/test-report-dsh-0.1.5-rc.1.md)
369
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
370
- [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/test-report-claude-code-harness.md)
371
- [![Kimi Code 2.1.1 K3 Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-K3%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
396
+ [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
397
+ [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/reports/test-report-codex-gpt-6-astra-high.md)
398
+ [![DSH 0.1.5-rc.1 宿主 BLOCK 实测](https://img.shields.io/badge/DSH%200.1.5--rc.1-%E5%AE%BF%E4%B8%BB%20BLOCK%20%E5%AE%9E%E6%B5%8B-4D6BFE)](docs/reports/test-report-dsh-0.1.5-rc.1.md)
399
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
400
+ [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/reports/test-report-claude-code-harness.md)
401
+ [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/reports/test-report-kimi-code-block.md)
402
+ [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
403
+ [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
404
+ [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/reports/test-report-release-readiness-0.2.3.md)
405
+
406
+ 徽章链接到各自范围内的证据,不代表所有工具和模型均已通过。
407
+ DSH 文本读取脱敏是可选功能,默认关闭。
372
408
 
373
409
  “Core 可用”、“受 Skill 引导的 Agent 使用过”和“harness 会强制拦截每次匹配的
374
410
  工具调用”是三种不同强度的结论:
375
411
 
376
412
  | Harness/实测版本 | 接入路径 | 证据与边界 |
377
413
  |---|---|---|
378
- | **Claude Code 2.1.270 / 2.1.273** | [Bash 原生 `PreToolUse`](adapters/claude/README.md) | [真实 CLI+脚本模型](docs/test-report-claude-code-harness.md):抽样 allow/ask/deny 与 Python 启动故障;其他工具未验证。 |
379
- | **DSH 0.1.5-rc.1** | [原生 pre-execute adapter](adapters/dsh/README.md) | [真实宿主打包插件探针](docs/test-report-dsh-0.1.5-rc.1.md):执行级 `BLOCK` 与已加载 adapter 的 Core 故障拒绝。另一次[真实模型 Lab 基线](docs/test-report-dsh-guard-lab.md)在 guard-off 下未触发诱饵,故没有 L2 缓解结论;模型主动提出破坏性 `bash` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
380
- | **DSH CLI rc.1/工具与 FS rc.2/Node 22** | [实验性文本读取脱敏](adapters/dsh/README.md#experimental-text-read-redaction),默认关闭 | [零模型原生验证](docs/test-report-dsh-read-redaction.md):下一次请求和 JSONL 落盘。[官方 Flash 真实读取 off/on](docs/test-report-dsh-real-followup.md):支持规则的合成秘密在工具内容/元数据/会话中被脱敏,有用配置保留;无提示注入 L2 结论。 |
381
- | **DSH 0.2.0-rc.2/Node 22** | [默认删除与可选文本读取 adapter](adapters/dsh/README.md) | [最新契约复核](docs/test-report-release-readiness-0.2.3.md):原生删除阻断、已审阅本地/沙箱 FS 的读取脱敏、下一次合成请求与 JSONL 落盘。原生 v4 Lab 支持仍有范围限制;没有新的真实模型 L2 结果。 |
382
- | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
383
- | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
384
- | **Kimi Code 0.42.0 / 2.1.1** | [Bash 原生 `PreToolUse`](adapters/kimi-code/README.md) | [有界实测](docs/test-report-kimi-code-block.md):2.1.1 在 OAuth 官模和维护者确认的官方 K3 可信中转上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
414
+ | **Claude Code 2.1.270 / 2.1.273** | [Bash 原生 `PreToolUse`](adapters/claude/README.md) | [真实 CLI+脚本模型](docs/reports/test-report-claude-code-harness.md):抽样 allow/ask/deny 与 Python 启动故障;其他工具未验证。 |
415
+ | **DSH 0.1.5-rc.1** | [原生 pre-execute adapter](adapters/dsh/README.md) | [真实宿主打包插件探针](docs/reports/test-report-dsh-0.1.5-rc.1.md):执行级 `BLOCK` 与已加载 adapter 的 Core 故障拒绝。另一次[真实模型 Lab 基线](docs/reports/test-report-dsh-guard-lab.md)在 guard-off 下未触发诱饵,故没有 L2 缓解结论;模型主动提出破坏性 `bash` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
416
+ | **DSH CLI rc.1/工具与 FS rc.2/Node 22** | [实验性文本读取脱敏](adapters/dsh/README.md#experimental-text-read-redaction),默认关闭 | [零模型原生验证](docs/reports/test-report-dsh-read-redaction.md):下一次请求和 JSONL 落盘。[官方 Flash 真实读取 off/on](docs/reports/test-report-dsh-real-followup.md):支持规则的合成秘密在工具内容/元数据/会话中被脱敏,有用配置保留;无提示注入 L2 结论。 |
417
+ | **DSH 0.2.0-rc.2/Node 22** | [默认删除与可选文本读取 adapter](adapters/dsh/README.md) | [最新契约复核](docs/reports/test-report-release-readiness-0.2.3.md):原生删除阻断、已审阅本地/沙箱 FS 的读取脱敏、下一次合成请求与 JSONL 落盘。原生 v4 Lab 支持仍有范围限制;没有新的真实模型 L2 结果。 |
418
+ | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
419
+ | **WorkBuddy(版本未记录;Windows 11)** | [Core/CLI](docs/reports/test-report-workbuddy-windows-core.md) | 社区在 0.2.2 上发现两个 Core 缺陷,现有回归与聚焦 Windows CI 覆盖;没有 WorkBuddy adapter 或原生 hook 验证。 |
420
+ | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/reports/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
421
+ | **Kimi Code 0.42.0 / 2.1.1** | [Bash 原生 `PreToolUse`](adapters/kimi-code/README.md) | [有界实测](docs/reports/test-report-kimi-code-block.md):2.1.1 在 OAuth 官方模型和另一条已配置模型路由上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
385
422
  | **其他/未列出宿主** | [自适配指南](adapters/INTEGRATION.md) | 未独立验证调用前阻断与目标未执行前,不作原生支持声明。 |
386
423
 
387
424
  由 Agent 协助接入时,先识别真实宿主版本与工具名称,阅读上表对应指南,
@@ -402,14 +439,14 @@ Kimi 或 Claude 安装可分别运行 `python3 doctor.py kimi --probe`、
402
439
  Agent Guard 运行路径生成去敏指纹;结果使用 `CURRENT`、`STALE`、
403
440
  `DRIFTED`、`BROKEN` 或 `UNVERIFIED`。即使是 `CURRENT` 也只代表静态预检,
404
441
  不是实时拦截证明。可选基线只保存解析后的版本和 SHA-256 指纹,详见
405
- [宿主漂移检查说明](docs/host-drift.md)。显式 `--live-sentinel` 可在私有空白
442
+ [宿主漂移检查说明](docs/guides/host-drift.md)。显式 `--live-sentinel` 可在私有空白
406
443
  夹具中消耗一次已配置模型调用,按 `PASS`、`FAIL`、`INCONCLUSIVE` 返回
407
444
  `NONE`/`NOTICE`、`CRITICAL` 或 `WARNING` 报警;仅仅“标记不存在”绝不算
408
445
  通过。它保留哈希化/去敏结果而不保留模型原始输出。这是可信提供方下的
409
446
  可靠性探针,不是针对恶意模型的沙盒。Kimi 的可选 doctor 因 TOML 解析需要 Python 3.11+;Core 与
410
447
  hook adapter 仍支持 Python 3.9+。
411
448
  各宿主的覆盖范围、证据等级和执行级验收条件见
412
- [harness 能力矩阵](docs/harness-capabilities.md)。
449
+ [harness 能力矩阵](docs/guides/harness-capabilities.md)。
413
450
 
414
451
  ## 目录结构
415
452
 
@@ -428,7 +465,7 @@ agent-guard/
428
465
  ├── adapters/dsh/ # DeepSeek Harness 接入桥
429
466
  ├── adapters/codex/harness/# CLI 验收 driver;不是原生 hook
430
467
  ├── tests/ # unittest 测试套件,含跨 harness 一致性
431
- └── docs/ # architecture · threat-model · friction log
468
+ └── docs/ # 使用指南 · 架构 · Lab · 测试报告 · 发布记录 · 历史设计
432
469
  ```
433
470
 
434
471
  Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`、
@@ -436,25 +473,18 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
436
473
 
437
474
  ## 文档
438
475
 
476
+ [文档导航](docs/README.md)按用途列出全部文档。历史报告保留所测版本与证据边界。
477
+
439
478
  | 阅读 | 内容 |
440
479
  |---|---|
441
480
  | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
442
- | [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
443
- | [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
444
- | [docs/guard-lab.md](docs/guard-lab.md) | 合成 Lab 流程、证据语义与不支持的信道 |
445
- | [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | 离线 guard-lab 源码候选 |
446
- | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
447
- | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
448
- | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
449
- | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
481
+ | [使用指南](docs/README.md#guides) | 当前宿主能力、漂移检查与维护操作 |
482
+ | [架构与契约](docs/README.md#design) | 数据流、威胁模型与兼容约定 |
483
+ | [Lab](docs/README.md#lab) | 实验指南、任务模板与候选攻击素材 |
484
+ | [测试报告](docs/README.md#reports) | 按版本记录的 Core、CLI、hook 与 Lab 证据 |
485
+ | [发布记录](docs/README.md#releases) | 正式版与预览版各自的范围 |
486
+ | [历史设计与经验](docs/README.md#history) | 早期方案、实现教训与事故探索 |
450
487
  | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | 未列出宿主的自适配检查清单 |
451
- | [docs/threat-model.md](docs/threat-model.md) | 诚实边界:它是什么、不是什么 |
452
- | [docs/friction.md](docs/friction.md) | 真实 Agent 与宿主进程撞出来的教训(F1–F20) |
453
- | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | 去标识化事故探索与面向恢复的后续方向 |
454
- | [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex 评估(medium + high) |
455
- | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | 当前 DSH 打包插件与执行级 `bash` 验收 |
456
- | [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | DSH 真实模型有界 Lab 基线;无 L2 结论 |
457
- | [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH 真机测试(DeepSeek V4 Pro high,极简模式) |
458
488
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
459
489
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
460
490
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil 规则表、reason code、豁免格式与审计结构 |
@@ -462,41 +492,43 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
462
492
 
463
493
  ## 状态与路线图
464
494
 
465
- 当前源码版本为 **v0.2.3-rc2**,最新稳定版仍为 **v0.2.2**。已发布的
466
- `v0.2.0` 基线包含可恢复的破坏性
467
- 操作、cmd/PowerShell 方言解析、`exfil-guard` 文本 CLI、只读配置安全视图
468
- 和 `recovery-audit`。后续源码版新增 Claude/Kimi POSIX hook 桥、有界宿主
469
- 证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH 打包验收;rc2 源码另含
470
- 下述离线 guard-lab MVP。准确范围见
471
- [0.2.3-rc2 说明](docs/release-notes-0.2.3-rc2.md)记录源码候选范围,
472
- [0.2.3-rc1 说明](docs/release-notes-0.2.3-rc1.md)记录已发布候选范围,
473
- [0.2.2 说明](docs/release-notes-0.2.2.md)记录稳定版范围;是否已正式发布以
474
- [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) 为准,
475
- 源码版本号本身不代表已有 Release。
476
-
477
- 该版本的项目身份与 harness 无关。现有 DSH、Claude adapter,Codex/ZCode
478
- 验收证据,以及有边界的 Kimi 实测,只是不断扩展的兼容矩阵,不分别定义产品。
495
+ **v0.2.4** 在 0.2.3 上增加恢复维护与 trash 查询:拒绝 hard reset 与
496
+ 未跟踪/ignored 内容的碰撞,检查恢复来源和目标,强制恢复前先保存占位版本。
497
+ 只读查询提供 CLI、Agent 和未来前端共用的契约。已有文本脱敏、配置安全视图、
498
+ 离线 Lab、Claude/Kimi 接入桥、doctor、宿主漂移检查与实时哨兵继续提供。
499
+ DSH 接入支持已复核的 `0.1.5-rc.1` 和 `0.2.0-rc.2` 契约;可选文本读取
500
+ 保护仍默认关闭。
501
+
502
+ [0.2.4 说明](docs/releases/release-notes-0.2.4.md)记录本次范围;
503
+ [0.2.3](docs/releases/release-notes-0.2.3.md)、
504
+ [rc2](docs/releases/release-notes-0.2.3-rc2.md)、[rc1](docs/releases/release-notes-0.2.3-rc1.md)
505
+ 和 [0.2.2](docs/releases/release-notes-0.2.2.md) 说明保留各自历史范围。
506
+ 已发布工件以 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
507
+ 和 npm 为准。
508
+
509
+ Core 和 Decision Protocol 由各 harness 共用。DSH、Claude、Kimi 的适配器
510
+ 以及 Codex/WorkBuddy/ZCode 的验收记录,统一列在兼容矩阵中。
479
511
  Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
480
512
  所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
481
513
  启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
482
- 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。候选版为 Issue #7
514
+ 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。本次版本为 Issue #7
483
515
  新增了聚焦的真实 Windows Core 门,但各 harness 下的原生 cmd/PowerShell
484
516
  执行与一般并发子代理安全仍是明确缺口。
485
517
  后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
486
518
 
487
- ## 0.2.3-rc2 源码候选:guard-lab 合成蜜罐
519
+ ## guard-lab 合成蜜罐
488
520
 
489
- 当前源码加入了可选的离线蜜罐 MVP:在一次性项目中放入不具备认证能力的合成
521
+ 可选的离线蜜罐 Lab 在一次性项目中放入不具备认证能力的合成
490
522
  标记。`clean`、`mock-positive`、`mock-injection` 与 `snapshot-positive` 四组
491
523
  对照不调用模型,也不访问外网;限时回环观察器记录假 Lab 工具、诱饵 URL 或
492
524
  经验证的合成快照,用户还可在试次结束后显式扫描选定输出,只保留哈希、阶段与
493
525
  命中的 bait id,不保存原值。
494
526
 
495
527
  真控制器与证据由用户保管,和交给受测 Agent 的夹具分开。观察器、控制文件或
496
- 事件链有问题时只报 `INCONCLUSIVE`。首版不能看到普通文件读取,不能证明数据
528
+ 事件链有问题时只报 `INCONCLUSIVE`。Lab 不能看到普通文件读取,不能证明数据
497
529
  已经外发,不能普遍封禁 LLM 调用,也不能抵抗同一系统用户权限下的对手。
498
530
  涉及真实 harness 前,请先跑零 Token 对照并阅读
499
- [guard-lab 指南](docs/guard-lab.md)。
531
+ [guard-lab 指南](docs/lab/guard-lab.md)。
500
532
  这些内建 case 只报 `CALIBRATION_ONLY`。另设的手动 `injection-probe` 会把诱饵
501
533
  命中记为 `EXPOSURE_OBSERVED`;只有未防护基线确实中招,并与相同协议、
502
534
  harness/版本/模型、实验组和任务哈希的开启防护试次配对,`compare` 才可能给出
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is a checklist for a user or their agent, **not** a claim that an
4
4
  unlisted host is supported. Start with the [capability and evidence
5
- matrix](../docs/harness-capabilities.md). A prompt, Skill, CLI call, or
5
+ matrix](../docs/guides/harness-capabilities.md). A prompt, Skill, CLI call, or
6
6
  adapter exit code alone does not prove automatic tool interception.
7
7
 
8
8
  ## 1. Identify the actual boundary
@@ -33,7 +33,7 @@ or a public report. If the host contract or version is unclear, mark it
33
33
  second copy of the rule table. Inspect the [Claude](claude/pre_tool_use.py),
34
34
  [Kimi](kimi-code/pre_tool_use.py), and [DSH](dsh/lib/index.js) adapters as
35
35
  examples of host-specific mapping, not drop-in templates.
36
- - **No verified blocking event:** use the [Skills](../skills/) and explicit
36
+ - **No verified blocking event:** use the [Skills](../skills) and explicit
37
37
  CLI cooperatively. Say `Skill/CLI only`; do not claim native interception.
38
38
  A hook limited to some tools does not cover other tools or hidden uploads.
39
39
 
@@ -73,7 +73,7 @@ For those two hosts, `--check-drift` adds local version/profile comparison and
73
73
  privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
74
74
  version change; it does not assert incompatibility. `CURRENT` still does not
75
75
  promote `host_interception` above `UNVERIFIED`. See the
76
- [host drift contract](../docs/host-drift.md).
76
+ [host drift contract](../docs/guides/host-drift.md).
77
77
 
78
78
  An explicit `--live-sentinel` can spend one configured model call to test one
79
79
  real root-agent Bash path in a private fixture. PASS requires a hashed exact
@@ -87,7 +87,7 @@ Report the host/version, tool and event, config scope, root/subagent path,
87
87
  dialect, model setup if one was used, the Core decision, host outcome, and
88
88
  independent non-execution observation. Label evidence as `CLI`, `Adapter`,
89
89
  `Hook observed`, or `Enforcement observed` using the
90
- [matrix definitions](../docs/harness-capabilities.md#evidence-levels).
90
+ [matrix definitions](../docs/guides/harness-capabilities.md#evidence-levels).
91
91
  Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
92
92
  `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
93
93
  evidence, not an independent security boundary against that same agent or a
@@ -78,11 +78,11 @@ prompt.
78
78
  A passing check does **not** inspect Claude's merged settings, prove a
79
79
  running session loaded the hook, or verify host-level interception. For
80
80
  those claims, use the isolated host acceptance in the
81
- [capability matrix](../../docs/harness-capabilities.md).
81
+ [capability matrix](../../docs/guides/harness-capabilities.md).
82
82
  Add `--check-drift` to compare the installed Claude Code version with the
83
83
  shipped profile and compute privacy-safe configuration/runtime
84
84
  fingerprints. `CURRENT` still does not prove live interception; see the
85
- [drift status contract](../../docs/host-drift.md).
85
+ [drift status contract](../../docs/guides/host-drift.md).
86
86
  An explicit `--live-sentinel` may then use one configured model call in a
87
87
  private fixture and requires adapter, audit, host-feedback, and marker
88
88
  evidence. It keeps `dontAsk` and never enables permission bypass.
@@ -126,7 +126,7 @@ returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
126
126
  Validated end-to-end against real Claude Code sessions (2.1.270 and 2.1.273) with a
127
127
  scripted mock Anthropic endpoint standing in for the model, plus the
128
128
  `python3`-free regression tests. See
129
- [`docs/test-report-claude-code-harness.md`](../../docs/test-report-claude-code-harness.md)
129
+ [`docs/reports/test-report-claude-code-harness.md`](../../docs/reports/test-report-claude-code-harness.md)
130
130
  and the shipped harness in [`harness/`](harness/README.md).
131
131
 
132
132
  The guard child is spawned with `sys.executable`, never `python3` from
@@ -1,7 +1,7 @@
1
1
  # Claude Code end-to-end harness
2
2
 
3
3
  Reproduces the live interception test in
4
- [`docs/test-report-claude-code-harness.md`](../../../docs/test-report-claude-code-harness.md):
4
+ [`docs/reports/test-report-claude-code-harness.md`](../../../docs/reports/test-report-claude-code-harness.md):
5
5
  the **real** Claude Code CLI, the **real** agent-guard `PreToolUse` hook, and
6
6
  a **scripted mock Anthropic endpoint** standing in for the model.
7
7
 
@@ -1,10 +1,10 @@
1
1
  # Codex acceptance harness
2
2
 
3
3
  Reproduces the 20-check acceptance run recorded in
4
- [`docs/test-report-codex-gpt-6-astra-high.md`](../../../docs/test-report-codex-gpt-6-astra-high.md)
4
+ [`docs/reports/test-report-codex-gpt-6-astra-high.md`](../../../docs/reports/test-report-codex-gpt-6-astra-high.md)
5
5
  (2026-09-19, baseline `de5a00e`, `gpt-6-astra` / `high`).
6
6
 
7
- Unlike [`adapters/claude/harness/`](../../claude/harness/), there is no Codex
7
+ Unlike [`adapters/claude/harness/`](../../claude/harness), there is no Codex
8
8
  adapter behind this directory. Codex has no native PreToolUse hook in this
9
9
  repository, so nothing here implies automatic interception: the driver
10
10
  exercises the guard through the production CLI (`check.py`, `safe_delete.py`,
@@ -1,27 +1,36 @@
1
1
  # agent-guard adapter for DeepSeek Harness
2
2
 
3
- Official DSH integration, shipped as a first-class `dsh-plugin` bundle.
4
- The decision rules are NOT implemented here - this adapter translates the
5
- Decision Protocol onto DSH's native mechanisms and delegates deletion
6
- verdicts to the shared Python core (`skills/delete-guard/scripts/check.py`).
3
+ DSH integration shipped as a `dsh-plugin` bundle in the Agent Guard package.
4
+ This adapter maps the Decision Protocol onto DSH's native mechanisms and
5
+ delegates deletion verdicts to the shared Python core
6
+ (`skills/delete-guard/scripts/check.py`).
7
7
  The opt-in text-read prototype reuses the existing Core exfil policy through
8
8
  a bounded local worker. Both ship inside this package.
9
9
 
10
- The [current contract review](../../docs/test-report-release-readiness-0.2.3.md)
10
+ The [0.2.3 contract review](../../docs/reports/test-report-release-readiness-0.2.3.md)
11
11
  verifies the default deletion path on `0.2.0-rc.2` and `0.1.5-rc.1`, and
12
12
  the opt-in read path on the reviewed new local and sandbox filesystem providers.
13
13
  The package admits both exact host versions. Lab preflight accepts both and
14
14
  binds their native formats separately; unsupported session shapes remain
15
15
  inconclusive. A running Web service's plugin inventory does not validate this
16
- checkout or its agent scope. The [initial upgrade check](../../docs/test-report-dsh-0.2-upgrade.md)
16
+ checkout or its agent scope. The [initial upgrade check](../../docs/reports/test-report-dsh-0.2-upgrade.md)
17
17
  retains the earlier failures and correction history.
18
18
 
19
19
  ## Install
20
20
 
21
+ The [0.2.4 release](../../docs/releases/release-notes-0.2.4.md) updates the shared
22
+ Core and docs without broadening the admitted DSH versions or native-read
23
+ coverage. Install the exact version:
24
+
21
25
  ```bash
22
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard
26
+ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
23
27
  ```
24
28
 
29
+ Use an exact package version whose host contract matches your DSH installation.
30
+ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
31
+ Git must already be available. Installation does not enable the optional
32
+ text-read guard.
33
+
25
34
  ## What gets registered
26
35
 
27
36
  | Contribution | Mechanism | Behavior |
@@ -90,19 +99,20 @@ it reads no target file and performs no model/network call. Native `read`
90
99
  continues to own filesystem access. The shell-policy inheritance note below
91
100
  applies to the existing deletion commands, not this controller worker.
92
101
 
93
- The [zero-model native report](../../docs/test-report-dsh-read-redaction.md)
102
+ The [zero-model native report](../../docs/reports/test-report-dsh-read-redaction.md)
94
103
  verifies the actual returned value/content/meta, next request, and full durable
95
104
  JSONL log through the real AgentLoop with a synthetic stream. It does not
96
105
  establish real-model injection mitigation or universal emission protection.
97
- The separate [official Flash real-model follow-up](../../docs/test-report-dsh-real-followup.md)
106
+ The separate [official Flash real-model follow-up](../../docs/reports/test-report-dsh-real-followup.md)
98
107
  observed supported synthetic-secret redaction in tool content, presentation
99
108
  metadata and the decoded session during a direct-read off/on experiment. It
100
109
  preserved useful configuration and remains outside the Lab injection L2 protocol.
101
110
  Custom/later finalizers, unreviewed tool providers, PTC, other tool results,
102
111
  early events, tool-call arguments and preexisting session data are outside
103
112
  this prototype. Plugin composition is trusted; the binding check is not
104
- authentication of arbitrary plugins. Existing reviewed Lab pair profiles
105
- remain deletion-only and do not enable this flag.
113
+ authentication of arbitrary plugins. Lab pairs enable this flag only when
114
+ the explicit [`read-redaction-v1` profile](harness/README.md#explicit-native-read-redaction-profile)
115
+ is selected; the default profiles keep it off.
106
116
 
107
117
  ## Shell dialect
108
118
 
@@ -126,12 +136,11 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
126
136
  event contract, or failure before listener registration cannot deny a call
127
137
  the adapter never receives.
128
138
  - The Python core requires `python3` and `git` on PATH.
129
- - Until the scoped npm package is actually published, install from a GitHub
130
- checkout or release tarball rather than treating the registry command above
131
- as available.
139
+ - The scoped npm package is published. Use an exact package version when
140
+ reproducing a test; a source checkout may contain later changes.
132
141
  - DSH `0.1.5-rc.1` package loading and one harmless execution-level `bash`
133
142
  block are independently verified in the
134
- [bounded host report](../../docs/test-report-dsh-0.1.5-rc.1.md). Model,
143
+ [bounded host report](../../docs/reports/test-report-dsh-0.1.5-rc.1.md). Model,
135
144
  subagent, concurrency, ASK UI and non-`bash` paths remain separate tests.
136
145
  - For repeatable baselines and reviewed guard-off/on Lab pairs, use the
137
146
  [headless capture/review runner](harness/README.md). Its separate `check`