@mokuyoaxis/agent-guard 0.2.5-rc2 → 0.2.5

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 (40) hide show
  1. package/CONTRIBUTING.md +24 -0
  2. package/README.md +52 -18
  3. package/README.zh-CN.md +46 -15
  4. package/SECURITY.md +18 -10
  5. package/adapters/dsh/README.md +39 -6
  6. package/adapters/dsh/harness/README.md +5 -0
  7. package/adapters/dsh/harness/guard_lab.py +3 -2
  8. package/adapters/dsh/lib/index.js +127 -33
  9. package/adapters/kimi-code/harness/README.md +5 -0
  10. package/core/lab.py +5 -2
  11. package/core/messages.py +40 -0
  12. package/core/policy.py +2 -1
  13. package/docs/README.md +29 -8
  14. package/docs/design/architecture.md +9 -5
  15. package/docs/design/compatibility.md +43 -3
  16. package/docs/design/threat-model.md +2 -2
  17. package/docs/guides/getting-started.md +28 -12
  18. package/docs/guides/harness-capabilities.md +9 -2
  19. package/docs/guides/recovery-feedback.md +98 -0
  20. package/docs/history/friction.md +21 -1
  21. package/docs/lab/blue-team-calibration.md +45 -0
  22. package/docs/lab/examples/blue-team-calibration.py +53 -0
  23. package/docs/lab/guard-lab.md +12 -2
  24. package/docs/releases/release-notes-0.2.5-rc3.md +82 -0
  25. package/docs/releases/release-notes-0.2.5.md +123 -0
  26. package/docs/reports/blue-team-lab-2026-10.md +73 -0
  27. package/docs/research/README.md +41 -0
  28. package/docs/research/content-authorization.md +54 -0
  29. package/docs/research/dataflow-observability.md +48 -0
  30. package/docs/research/delegation-provenance.md +56 -0
  31. package/docs/research/evaluation-method.md +51 -0
  32. package/docs/research/lab-observations-2026-10.json +43 -0
  33. package/package.json +1 -1
  34. package/skills/delete-guard/SKILL.md +31 -14
  35. package/skills/delete-guard/references/policy.md +20 -6
  36. package/skills/delete-guard/scripts/check.py +13 -0
  37. package/skills/delete-guard/scripts/gc.py +4 -2
  38. package/skills/delete-guard/scripts/safe_delete.py +20 -14
  39. package/skills/delete-guard/scripts/status.py +9 -0
  40. package/skills/exfil-guard/references/rules.md +2 -2
package/CONTRIBUTING.md CHANGED
@@ -57,6 +57,20 @@ Review, merge, tagging, GitHub Release, and npm publication are separate
57
57
  maintainer decisions. Acceptance of a contribution does not promise a specific
58
58
  release date.
59
59
 
60
+ ### Defensive research and reproductions
61
+
62
+ Lab develops through small, bounded experiments. Forks, PRs, method reviews
63
+ and independent reproductions are welcome, without a promised experiment or
64
+ release cadence. Public research focuses on defensive controls, provenance,
65
+ task utility and evidence limits. Share synthetic, sanitized observations;
66
+ coordinate sensitive details privately before posting executable adversarial
67
+ payloads or raw captures.
68
+
69
+ Include the code/host versions, declared model configuration, input/task,
70
+ budget, control conditions and observed channels. Report authorization,
71
+ task completion and evidence health separately, retaining failed and
72
+ inconclusive trials. See the [research index](docs/research/README.md).
73
+
60
74
  ## 中文
61
75
 
62
76
  ### 先发 Issue
@@ -99,3 +113,13 @@ Core/CLI、模拟宿主还是真实宿主。模拟测试通过不能写成所有
99
113
 
100
114
  审阅、合并、标签、GitHub Release 与 npm 发布是维护者分别作出的决定;贡献被
101
115
  接受不代表承诺在某个版本或日期发布。
116
+
117
+ ### 防守研究与独立复现
118
+
119
+ Lab 将按小规模、明确范围逐步推进,欢迎 fork、PR、方法评审与独立复现,
120
+ 不承诺固定实验频率或发布时间。公开研究重点是防护、来源、正常任务效用和证据边界。
121
+ 分享合成、去敏后的观察;可执行诱导载荷、敏感复现细节与原始捕获先私下协调。
122
+
123
+ 注明代码/宿主版本、客户端声明的模型配置、输入/任务、预算、对照条件和观察信道。
124
+ 分别报告授权遵守、任务完成和证据健康,保留失败及未定试次。
125
+ 方法与公开示例见[研究导航](docs/research/README.md)。
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm stable](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
- [![0.2.5-rc2 candidate](https://img.shields.io/badge/RC-0.2.5--rc2-5B6B7A)](docs/releases/release-notes-0.2.5-rc2.md)
7
+ [![0.2.5](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -65,6 +65,23 @@ external transfer or model request. Existing
65
65
  [DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
66
66
  results, failures and review states.
67
67
 
68
+ Since RC3, the package includes [blue-team research](docs/research/README.md), a
69
+ [sanitized experiment report](docs/reports/blue-team-lab-2026-10.md) and a
70
+ [portable four-control example](docs/lab/blue-team-calibration.md).
71
+ The research covers provenance, disclosure permissions and task utility in
72
+ bounded private experiments; those methods do not extend production hook
73
+ coverage. Lab proceeds gradually. Forks, PRs and independent defensive
74
+ reproductions are welcome; preserve failed and inconclusive results.
75
+
76
+ From a checkout or package containing the example, run all four existing controls:
77
+
78
+ ```sh
79
+ blue_run="$(mktemp -d)"
80
+ python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"
81
+ ```
82
+
83
+ This example calls no model; its summary describes instrument calibration.
84
+
68
85
  <a id="quick-start-with-your-coding-agent"></a>
69
86
 
70
87
  ## Install and choose a version
@@ -74,14 +91,19 @@ native bridges and optional capture helpers have their own requirements.
74
91
 
75
92
  | Version | Status |
76
93
  |---|---|
77
- | [0.2.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
78
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Previous published prerelease baseline |
79
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | Maintenance prerelease; check the exact publication receipts |
94
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | Stable release line; npm `latest`; availability in the versioned receipts below |
95
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | Previous stable release |
96
+ | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | Opt-in quarantine protection backport; npm `hotfix` |
97
+ | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
98
+ Publication is established by the exact
99
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
100
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5).
101
+ A checkout or manifest alone does not establish package availability.
80
102
 
81
- For the published stable package, use a chosen, stable user-owned prefix:
103
+ For the stable release, use a chosen, stable user-owned prefix:
82
104
 
83
105
  ```sh
84
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
106
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
85
107
  ```
86
108
 
87
109
  The package root is
@@ -93,12 +115,16 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
93
115
  cd agent-guard
94
116
  ```
95
117
 
96
- For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly; the RC
97
- channel does not replace stable `latest`. Check the
98
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
99
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
100
- for publication. A reviewed checkout or supplied tarball is also usable;
101
- the manifest alone does not establish registry availability. See
118
+ To select the published prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3`.
119
+ The [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
120
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
121
+ identify that package. For only the stable-line quarantine protection fix,
122
+ select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
123
+ replaces stable `latest`.
124
+
125
+ Version 0.2.5 combines RC1–RC3 with clearer startup, command and storage
126
+ feedback. A reviewed local checkout or supplied tarball is also usable. See
127
+ [release notes](docs/releases/release-notes-0.2.5.md) and
102
128
  [setup and the agent setup prompt](docs/guides/getting-started.md).
103
129
 
104
130
  ## Recover a supported deletion
@@ -109,7 +135,7 @@ From the workspace being protected, point at your package/checkout root:
109
135
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
110
136
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
111
137
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
112
- python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
138
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
113
139
  ```
114
140
 
115
141
  Valuable targets are relocated with exact recovery paths in a manifest.
@@ -119,6 +145,11 @@ untracked/ignored content are refused. Force restore preserves the current
119
145
  occupant before replacement. Errors can leave partial work: inspect the
120
146
  reported transaction IDs, filesystem and state before retrying.
121
147
 
148
+ Version 0.2.5 makes these results explicit:
149
+ quarantined data still occupies storage, GC is manual, and `ALLOW_NOOP`
150
+ does not certify unrecognized command effects. Local status does not prove
151
+ that a host loaded the guard. See [status and cleanup feedback](docs/guides/recovery-feedback.md).
152
+
122
153
  Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
123
154
  may write quarantine/audit metadata and a Git local exclude entry. Advisory
124
155
  exit 0 is not permission to execute a BLOCK or ASK.
@@ -126,10 +157,11 @@ See the [policy and assessment contract](skills/delete-guard/references/policy.m
126
157
 
127
158
  RC1 added quarantine control-path protection, excluded PURGED transactions
128
159
  from active GC planning, and minimized restore/safe_delete audit fields.
129
- Exact CLI/manifest recovery paths remain available. These changes are not in
130
- the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
160
+ Exact CLI/manifest recovery paths remain available. The original 0.2.4 package
161
+ lacks these changes; 0.2.4-hotfix.1 backports only quarantine control-path
162
+ protection. See the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
131
163
 
132
- The RC2 source candidate also projects shared audit metadata,
164
+ RC2 introduced shared audit metadata projection,
133
165
  uses opaque session correlation, and limits legacy status/GC metadata.
134
166
  See the [audit contract and remaining boundaries](docs/guides/audit-metadata.md).
135
167
  It adds observer startup diagnostics and correct cancellation accounting;
@@ -211,13 +243,15 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
211
243
  | [Architecture](docs/design/architecture.md) | Shared Core, compensation and adapter flow |
212
244
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
213
245
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
214
- | [0.2.5-rc2 notes](docs/releases/release-notes-0.2.5-rc2.md) | Current source candidate's changes and validation status |
246
+ | [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
247
+ | [0.2.5 notes](docs/releases/release-notes-0.2.5.md) | Release scope, upgrade impact and validation boundaries |
215
248
 
216
249
  ## Contributing
217
250
 
218
251
  Bug reports, compatibility evidence, documentation fixes and focused code
219
252
  changes are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before sharing
220
- logs. Use [Issues](https://github.com/mokuyoaxis/agent-guard/issues) and
253
+ defensive research, independent reproductions or logs. Use
254
+ [Issues](https://github.com/mokuyoaxis/agent-guard/issues) and
221
255
  [Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls); keep credentials,
222
256
  private configuration and unredacted incident records out of public reports.
223
257
 
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
- [![0.2.5-rc2 候选](https://img.shields.io/badge/RC-0.2.5--rc2-5B6B7A)](docs/releases/release-notes-0.2.5-rc2.md)
7
+ [![0.2.5](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -56,6 +56,21 @@ harness/版本/模型、任务、协议及非防护配置。结果只覆盖
56
56
  [DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
57
57
  失败和待审状态。
58
58
 
59
+ 自 RC3 起,包中包含[蓝队研究](docs/research/README.md)、
60
+ [去敏实验报告](docs/reports/blue-team-lab-2026-10.md)和
61
+ [便携四控制示例](docs/lab/blue-team-calibration.md),公开来源、发送授权和正常任务效用的
62
+ 有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进,欢迎 fork、PR
63
+ 与独立防守复现;失败和未定结果也应保留。
64
+
65
+ 在包含该示例的源码或包根目录,可一次运行现有四种控制:
66
+
67
+ ```sh
68
+ blue_run="$(mktemp -d)"
69
+ python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"
70
+ ```
71
+
72
+ 示例不调用模型,摘要只用于仪器校准。
73
+
59
74
  ## 安装与版本选择
60
75
 
61
76
  Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可选采集
@@ -63,14 +78,19 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
63
78
 
64
79
  | 版本 | 状态 |
65
80
  |---|---|
66
- | [0.2.4](docs/releases/release-notes-0.2.4.md) | 已发布的稳定基线 |
67
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 已发布的历史预发布基线 |
68
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | 维护预发布;以准确版本的发布回执为准 |
81
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | 正式版;npm `latest`;实际可用性见下方版本化回执 |
82
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | 上一稳定版 |
83
+ | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
84
+ | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
85
+ 实际发布状态以精确版本的
86
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)和
87
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)为准,
88
+ checkout 或 manifest 本身不代表包已可安装。
69
89
 
70
90
  稳定包可安装到用户选定的长期目录:
71
91
 
72
92
  ```sh
73
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
93
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
74
94
  ```
75
95
 
76
96
  包根目录是
@@ -82,11 +102,16 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
82
102
  cd agent-guard
83
103
  ```
84
104
 
85
- RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定版 `latest`。
86
- 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
87
- 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)为准,
88
- 也可使用已核查的 checkout 或提供的 tarball;manifest 版本不代表 registry 已可安装。
89
- 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)。
105
+ 选用已发布的预发布版时,指定 `@mokuyoaxis/agent-guard@0.2.5-rc3`,对应
106
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)与
107
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)。
108
+ 若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
109
+ 这两个通道均不替换稳定版 `latest`。
110
+
111
+ 0.2.5 汇合 RC1—RC3,并明确启动、命令与空间占用反馈,
112
+ 也可使用已核查的 checkout 或提供的 tarball。
113
+ 范围见[发布说明](docs/releases/release-notes-0.2.5.md),接入步骤与 Agent 提示词见
114
+ [入门指南](docs/guides/getting-started.md)。
90
115
 
91
116
  ## 恢复一次受支持的删除
92
117
 
@@ -96,7 +121,7 @@ RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定
96
121
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
97
122
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
98
123
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
99
- python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
124
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
100
125
  ```
101
126
 
102
127
  有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被
@@ -105,15 +130,20 @@ hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force res
105
130
  先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的
106
131
  事务 ID、现场文件和状态,再决定后续动作。
107
132
 
133
+ 0.2.5 明确提示:迁入回收站的数据仍占空间,
134
+ GC 需要显式执行,`ALLOW_NOOP` 不代表未识别命令没有破坏性。
135
+ 本地状态查询也不能证明宿主已加载防护。见[状态与清理反馈](docs/guides/recovery-feedback.md)。
136
+
108
137
  advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,但可能写入
109
138
  隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
110
139
  操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
111
140
 
112
141
  RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
113
142
  restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
114
- 这些维护不属于已发布的 0.2.4 包,见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
143
+ 原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。
144
+ 见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
115
145
 
116
- RC2 源码候选进一步限定通用审计字段、使用不透明 session 关联,
146
+ RC2 进一步限定通用审计字段、使用不透明 session 关联,
117
147
  并收口旧日志 status 展示与 GC 元信息,见[审计契约及保留边界](docs/guides/audit-metadata.md)。
118
148
  同时补充 observer 启动诊断与取消健康记账;最初偶发超时的具体原因仍未知,
119
149
  见 [RC2 范围与证据](docs/releases/release-notes-0.2.5-rc2.md)。
@@ -184,11 +214,12 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
184
214
  | [架构](docs/design/architecture.md) | 共享 Core、补偿与适配器数据流 |
185
215
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
186
216
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
187
- | [0.2.5-rc2 说明](docs/releases/release-notes-0.2.5-rc2.md) | 当前源码候选变更与验收状态 |
217
+ | [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
218
+ | [0.2.5 说明](docs/releases/release-notes-0.2.5.md) | 发布范围、升级影响与验证边界 |
188
219
 
189
220
  ## 参与贡献
190
221
 
191
- 欢迎缺陷报告、兼容性证据、文档修订和范围明确的代码改动。分享日志前阅读
222
+ 欢迎 fork、PR、独立防守复现、缺陷报告、兼容性证据和文档修订。分享研究资料或日志前阅读
192
223
  [CONTRIBUTING.md](CONTRIBUTING.md),通过
193
224
  [Issues](https://github.com/mokuyoaxis/agent-guard/issues) 和
194
225
  [Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls)参与;
package/SECURITY.md CHANGED
@@ -3,13 +3,15 @@
3
3
  ## Reporting
4
4
 
5
5
  Open a GitHub issue for non-sensitive issues, or contact the maintainer
6
- directly for anything you believe is exploitable. Please include the
7
- verdict JSON and audit lines involved.
6
+ directly for anything you believe is exploitable. Include the minimal
7
+ sanitized verdict/audit metadata needed to explain it, using synthetic data
8
+ where possible. See [CONTRIBUTING.md](CONTRIBUTING.md) before sharing captures.
8
9
 
9
10
  ## What agent-guard claims to be
10
11
 
11
- Reliability infrastructure: it makes destructive actions reversible by
12
- default and records evidence. It is **not a security sandbox** - an agent
12
+ Reliability infrastructure: it provides recovery for supported destructive
13
+ actions and records evidence under the documented audit contracts. It is
14
+ **not a security sandbox** - an agent
13
15
  with the same OS privileges as the guard can bypass it. See
14
16
  [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
15
17
 
@@ -27,10 +29,10 @@ will therefore report hits such as:
27
29
  - credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
28
30
  (a guide about *avoiding* credential leaks).
29
31
 
30
- As of v0.1.0 a full self-scan reports 61 hits (29 high / 10 medium / 22
31
- low) with **zero in runtime decision paths** - all are documentation or
32
- test fixtures. If you find a hit outside docs/tests/fixtures, please
33
- report it.
32
+ A historical v0.1.0 self-scan reported 61 hits (29 high / 10 medium / 22 low).
33
+ That count is a dated checkpoint, not a current runtime-reachability audit.
34
+ Review the concrete call and its context; report unexpected runtime behavior
35
+ with a minimal, sanitized reproduction.
34
36
 
35
37
  ## Data handling
36
38
 
@@ -47,7 +49,13 @@ the configured provider through the host and consume quota; they are separate
47
49
  from local command checks and require a selected experiment scope.
48
50
 
49
51
  Recovery manifests, CLI diagnostics and historical audit records can contain
50
- exact paths or other private text. Audit minimization in the 0.2.5-rc1 source
51
- candidate does not make every output or old record secret-free. The exfil text
52
+ exact paths or other private text. Writer minimization introduced in RC1 and
53
+ the shared projection introduced in RC2 remain in 0.2.5;
54
+ they do not make every
55
+ output or old record secret-free. The exfil text
52
56
  CLIs return decisions/plans or sanitized stdout; they do not automatically
53
57
  persist egress audit events. Review and redact evidence before sharing it.
58
+
59
+ The [public blue-team research](docs/research/README.md) shares sanitized
60
+ methods and aggregate observations. Raw sessions, private configuration and
61
+ reusable induction payloads are not part of those new public materials.
@@ -18,12 +18,12 @@ 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:
21
+ The [0.2.5 release](../../docs/releases/release-notes-0.2.5.md) includes the
22
+ startup/status diagnostics below without broadening admitted DSH versions or
23
+ native-read coverage. Install the exact stable version:
24
24
 
25
25
  ```bash
26
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
26
+ dsh plugin --profile 'your-profile' add @mokuyoaxis/agent-guard@0.2.5
27
27
  ```
28
28
 
29
29
  Use an exact package version whose host contract matches your DSH installation.
@@ -31,17 +31,50 @@ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
31
31
  Git must already be available. Installation does not enable the optional
32
32
  text-read guard.
33
33
 
34
+ As checked on 2026-10-19, the published opt-in versions are
35
+ `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
36
+ `@mokuyoaxis/agent-guard@0.2.5-rc3` for the cumulative prerelease.
37
+ Versioned [GitHub](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
38
+ and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
39
+ receipts establish 0.2.5 availability. A reviewed checkout or tarball is also
40
+ usable as described in [getting started](../../docs/guides/getting-started.md).
41
+
34
42
  ## What gets registered
35
43
 
36
44
  | Contribution | Mechanism | Behavior |
37
45
  |---|---|---|
38
- | Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; ALLOW proceeds (compensation applied), ASK escalates once to the human, BLOCK denies with explanation and remediation |
46
+ | Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; permitted calls proceed after any required compensation, ASK uses the host approval path or denies when unavailable, BLOCK denies with explanation and remediation |
39
47
  | `agent_guard_safe_delete` | model tool | recoverable delete with explicit glob expansion and manifest |
40
48
  | `agent_guard_restore` | model tool | list / non-overwriting restore of quarantine transactions; forced overwrite remains human-only CLI functionality |
41
- | `agent_guard_status` | model tool | mode, usage, retention view, recent decisions |
49
+ | `agent_guard_status` | model tool | adapter diagnostics, mode, usage, retention view, GC commands and recent decisions; no live-host certification |
42
50
  | Prompt section | system prompt (order 105) | deletion discipline for the model |
43
51
  | Experimental text `read` redaction | opt-in `tools/post-execute` value replacement | shared Core scans a complete read and DSH regenerates content and presentation metadata; unsupported or unscannable results are withheld |
44
52
 
53
+ ## Startup and status diagnostics
54
+
55
+ Version 0.2.5 runs `python3 check.py --help`
56
+ before contributing the Hook/tools. This tests Python and imports in the
57
+ plugin process, without assessing a command or writing guard metadata.
58
+ Missing dependencies or a failed/timed-out startup check produce an explicit
59
+ initialization error instead of a log-only disabled adapter. The local check
60
+ has a 10-second timeout; the existing command-check timeout remains unchanged.
61
+
62
+ Startup success says that the listener was registered, while live host
63
+ interception remains `UNVERIFIED`. `agent_guard_status.adapter` reports that
64
+ distinction and the most recent checker result. It does not turn a local
65
+ Python test into a check of every shell/sandbox environment. If the plugin
66
+ never loads, its tools may be absent: inspect the host's plugin activation
67
+ status. An initialization error does not stop the host's other tools.
68
+
69
+ Checker process errors, timeout and unusable output remain denials with
70
+ static diagnostics separate from policy refusals. Relocation results state
71
+ that data still occupies storage; status includes accurate GC commands.
72
+ Status-query timeout, unsuccessful exit and unusable reports return `ok: false`
73
+ with a `STATUS_*` diagnostic and adapter facts, without changing the last
74
+ command-checker result. Partial relocation failures retain their recovery IDs
75
+ and storage guidance when files have moved.
76
+ See [status and cleanup feedback](../../docs/guides/recovery-feedback.md).
77
+
45
78
  ## Configuration (cordis.patch.yml row)
46
79
 
47
80
  | Key | Default | Meaning |
@@ -6,6 +6,11 @@ host completion explicitly user-declared. No production dependency is added.
6
6
  The default remains guard-off; the paired workflow below supplies the local
7
7
  Guard patch only to guard-on members.
8
8
 
9
+ For a zero-model starting point, use the [four-control example](../../../docs/lab/blue-team-calibration.md).
10
+ The [defensive research](../../../docs/research/README.md) describes separate
11
+ private provenance/delegation experiments; it does not expand this runner's
12
+ single-root native receipt contract.
13
+
9
14
  ## Select the runtime
10
15
 
11
16
  Use Node.js 22.23.2 or another runtime with the required native Zstandard APIs.
@@ -221,7 +221,7 @@ def run_trial(
221
221
  node_executable: str = "node",
222
222
  guard_state: str = "off", guard_patch_file: Optional[Path] = None,
223
223
  expected_configuration_sha256: Optional[str] = None,
224
- *, guard_profile="deletion-v1", dsh_root=None,
224
+ *, guard_profile="deletion-v1", dsh_root=None, _prepare_run=None,
225
225
  ) -> dict:
226
226
  if case_id not in {"clean", "injection-probe"}:
227
227
  raise LabError("this runner supports clean and injection-probe only")
@@ -268,7 +268,8 @@ def run_trial(
268
268
  "trial_group": trial_group, "task_file": task_file,
269
269
  "non_guard_configuration_sha256": preflight["non_guard_configuration_sha256"],
270
270
  }
271
- prepared = prepare_run(
271
+ # Private experiments can pass a fixture constructor without module patches.
272
+ prepared = (prepare_run if _prepare_run is None else _prepare_run)(
272
273
  output / "fixture", output / "evidence", case_id,
273
274
  model_usage="real", attack_sample=attack_sample, **metadata,
274
275
  )