@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.6

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 (44) hide show
  1. package/README.md +64 -34
  2. package/README.zh-CN.md +53 -27
  3. package/SECURITY.md +5 -3
  4. package/adapters/INTEGRATION.md +84 -10
  5. package/adapters/claude/README.md +6 -0
  6. package/adapters/dsh/README.md +51 -7
  7. package/adapters/dsh/compatibility.json +14 -0
  8. package/adapters/dsh/harness/README.md +11 -0
  9. package/adapters/dsh/harness/guard_lab.py +42 -14
  10. package/adapters/dsh/lib/index.js +127 -33
  11. package/adapters/kimi-code/README.md +154 -14
  12. package/adapters/kimi-code/compatibility.json +1 -1
  13. package/adapters/kimi-code/config.example.toml +18 -6
  14. package/adapters/kimi-code/hook_bridge.sh +19 -4
  15. package/adapters/kimi-code/pre_tool_use.py +1 -1
  16. package/adapters/kimi-code/stop_feedback.py +237 -0
  17. package/core/messages.py +40 -0
  18. package/core/policy.py +2 -1
  19. package/docs/README.md +30 -8
  20. package/docs/design/architecture.md +13 -6
  21. package/docs/design/compatibility.md +87 -4
  22. package/docs/design/dsh-compatibility.md +65 -0
  23. package/docs/design/threat-model.md +2 -2
  24. package/docs/guides/getting-started.md +76 -17
  25. package/docs/guides/harness-capabilities.md +24 -5
  26. package/docs/guides/host-drift.md +32 -0
  27. package/docs/guides/recovery-feedback.md +126 -0
  28. package/docs/history/friction.md +21 -1
  29. package/docs/lab/blue-team-calibration.md +1 -1
  30. package/docs/lab/guard-lab.md +6 -2
  31. package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
  32. package/docs/releases/release-notes-0.2.5.md +123 -0
  33. package/docs/releases/release-notes-0.2.6.md +167 -0
  34. package/docs/releases/unreleased.md +141 -0
  35. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  36. package/docs/reports/test-report-kimi-code-block.md +119 -6
  37. package/doctor.py +175 -28
  38. package/package.json +11 -2
  39. package/skills/delete-guard/SKILL.md +30 -13
  40. package/skills/delete-guard/references/policy.md +16 -3
  41. package/skills/delete-guard/scripts/check.py +13 -0
  42. package/skills/delete-guard/scripts/gc.py +4 -2
  43. package/skills/delete-guard/scripts/safe_delete.py +20 -14
  44. package/skills/delete-guard/scripts/status.py +9 -0
package/README.md CHANGED
@@ -4,14 +4,24 @@
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-rc3 candidate](https://img.shields.io/badge/RC-0.2.5--rc3-5B6B7A)](docs/releases/release-notes-0.2.5-rc3.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
 
11
- Agent Guard is reliability infrastructure for coding agents. It provides
12
- recovery before supported destructive actions, checks text before disclosure,
13
- and gives users a Lab for testing observed agent and harness behaviour.
14
- The shared Python Core works through explicit CLIs and optional host adapters.
11
+ Agent Guard preserves recovery data before supported destructive actions,
12
+ checks text before sending it, and provides a Lab for testing agent and host
13
+ behaviour. The shared Python Core can be called through command-line tools
14
+ or host adapters.
15
+
16
+ **AI agents setting up this project:** Before changing configuration or writing
17
+ a bridge, read the [integration requirements](adapters/INTEGRATION.md), then
18
+ the [setup workflow](docs/guides/getting-started.md#set-up-a-coding-agent) and
19
+ the matching adapter guide. Check your actual host/version and its official
20
+ hook documentation, verify the integration, and report the observed coverage.
21
+ Installed Skills or copied configuration alone do not establish protection.
22
+
23
+ We currently focus on **DSH and Kimi Code** integrations. For other hosts,
24
+ ask the official coding agent to configure Agent Guard locally.
15
25
 
16
26
  | Capability | What it helps you do | Entry |
17
27
  |---|---|---|
@@ -65,7 +75,7 @@ external transfer or model request. Existing
65
75
  [DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
66
76
  results, failures and review states.
67
77
 
68
- RC3 adds [blue-team research](docs/research/README.md), a
78
+ Since RC3, the package includes [blue-team research](docs/research/README.md), a
69
79
  [sanitized experiment report](docs/reports/blue-team-lab-2026-10.md) and a
70
80
  [portable four-control example](docs/lab/blue-team-calibration.md).
71
81
  The research covers provenance, disclosure permissions and task utility in
@@ -73,7 +83,7 @@ bounded private experiments; those methods do not extend production hook
73
83
  coverage. Lab proceeds gradually. Forks, PRs and independent defensive
74
84
  reproductions are welcome; preserve failed and inconclusive results.
75
85
 
76
- From the RC3 checkout or review package, run all four existing controls:
86
+ From a checkout or package containing the example, run all four existing controls:
77
87
 
78
88
  ```sh
79
89
  blue_run="$(mktemp -d)"
@@ -91,15 +101,21 @@ native bridges and optional capture helpers have their own requirements.
91
101
 
92
102
  | Version | Status |
93
103
  |---|---|
94
- | [0.2.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
95
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Previous published prerelease baseline |
96
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | Maintenance prerelease; check the exact publication receipts |
97
- | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Research/documentation source preview; package publication requires separate receipts |
104
+ | [0.2.6](docs/releases/release-notes-0.2.6.md) | Stable release; npm `latest`; release links below |
105
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | Previous stable release |
106
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | Earlier stable release |
107
+ | [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` |
108
+ | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
109
+
110
+ Publication is established by the exact
111
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)
112
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6).
113
+ A checkout or manifest alone does not establish package availability.
98
114
 
99
- For the published stable package, use a chosen, stable user-owned prefix:
115
+ For the stable release, use a chosen, stable user-owned prefix:
100
116
 
101
117
  ```sh
102
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
118
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.6
103
119
  ```
104
120
 
105
121
  The package root is
@@ -111,17 +127,20 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
111
127
  cd agent-guard
112
128
  ```
113
129
 
114
- For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly; the RC
115
- channel does not replace stable `latest`. Check the
116
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
117
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
118
- for publication. A reviewed checkout or supplied tarball is also usable;
119
- the manifest alone does not establish registry availability. See
120
- [setup and the agent setup prompt](docs/guides/getting-started.md).
121
-
122
- Evaluate RC3 through a reviewed source checkout or supplied tarball. Its
123
- manifest and a main-branch commit do not establish a registry release;
124
- version tags and GitHub/npm package publication are separate steps.
130
+ To select the published prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3`.
131
+ The [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
132
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
133
+ identify that package. For only the stable-line quarantine protection fix,
134
+ select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
135
+ replaces stable `latest`.
136
+
137
+ Version [0.2.6](docs/releases/release-notes-0.2.6.md) builds on 0.2.5 with
138
+ optional Kimi Stop recovery feedback, separate Stop doctor checks, DSH Lab
139
+ preflight diagnostics, DSH `0.2.1-alpha.4` default deletion support and the
140
+ Kimi `2.3.0` Bash profile. Existing installations need an upgrade to acquire
141
+ these additions; Stop also needs explicit configuration. See
142
+ [setup and the agent setup prompt](docs/guides/getting-started.md) and the
143
+ [maintenance details](docs/releases/unreleased.md).
125
144
 
126
145
  ## Recover a supported deletion
127
146
 
@@ -131,7 +150,7 @@ From the workspace being protected, point at your package/checkout root:
131
150
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
132
151
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
133
152
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
134
- python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
153
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
135
154
  ```
136
155
 
137
156
  Valuable targets are relocated with exact recovery paths in a manifest.
@@ -141,6 +160,11 @@ untracked/ignored content are refused. Force restore preserves the current
141
160
  occupant before replacement. Errors can leave partial work: inspect the
142
161
  reported transaction IDs, filesystem and state before retrying.
143
162
 
163
+ Version 0.2.5 makes these results explicit:
164
+ quarantined data still occupies storage, GC is manual, and `ALLOW_NOOP`
165
+ does not certify unrecognized command effects. Local status does not prove
166
+ that a host loaded the guard. See [status and cleanup feedback](docs/guides/recovery-feedback.md).
167
+
144
168
  Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
145
169
  may write quarantine/audit metadata and a Git local exclude entry. Advisory
146
170
  exit 0 is not permission to execute a BLOCK or ASK.
@@ -148,8 +172,9 @@ See the [policy and assessment contract](skills/delete-guard/references/policy.m
148
172
 
149
173
  RC1 added quarantine control-path protection, excluded PURGED transactions
150
174
  from active GC planning, and minimized restore/safe_delete audit fields.
151
- Exact CLI/manifest recovery paths remain available. These changes are not in
152
- the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
175
+ Exact CLI/manifest recovery paths remain available. The original 0.2.4 package
176
+ lacks these changes; 0.2.4-hotfix.1 backports only quarantine control-path
177
+ protection. See the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
153
178
 
154
179
  RC2 introduced shared audit metadata projection,
155
180
  uses opaque session correlation, and limits legacy status/GC metadata.
@@ -196,15 +221,20 @@ Read the [Skill](skills/exfil-guard/SKILL.md),
196
221
 
197
222
  ## Connect your coding agent
198
223
 
199
- These are version-specific historical observations. They do not certify a
200
- new source candidate, every tool or every subagent path.
224
+ Ask the host's official coding agent to configure Agent Guard for the installed
225
+ version, following the [integration guide](adapters/INTEGRATION.md). Prefer a
226
+ hook that can block a tool call before it runs. We maintain the DSH and Kimi
227
+ Code integrations; other hosts use local bridges and configuration.
228
+
229
+ The results below apply to the recorded source versions, host versions and
230
+ tool paths. Other combinations need their own checks.
201
231
 
202
232
  | Host | Integration and evidence |
203
233
  |---|---|
204
- | Claude Code | Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
205
- | Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
206
- | DSH | Reviewed 0.1.5-rc.1/0.2.0-rc.2 deletion paths; optional complete text-read protection is default off. Sampled PTC Bash refusal does not imply universal PTC mediation. [Setup](adapters/dsh/README.md) |
207
- | Codex / other hosts | Explicit Skill/CLI is usable. Native interception needs a verified blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
234
+ | Claude Code | Retained reference; new version validation paused. Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
235
+ | Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. Version 0.2.6 adds 2.3.0 prompt/ACP root-Bash evidence with fixed responses. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
236
+ | DSH | Default deletion paths on 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4. Optional native read and Lab retain their two-version boundaries. [Compatibility](docs/design/dsh-compatibility.md) · [Setup](adapters/dsh/README.md) |
237
+ | Codex / other hosts | Use the official coding agent for version-specific local hook setup; verify blocking before claiming native interception. Without a blocking hook, explicit Skill/CLI remains cooperative. [Adaptation guide](adapters/INTEGRATION.md) |
208
238
 
209
239
  Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
210
240
  for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
@@ -234,7 +264,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
234
264
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
235
265
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
236
266
  | [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
237
- | [0.2.5-rc3 notes](docs/releases/release-notes-0.2.5-rc3.md) | Current source candidate's scope and validation status |
267
+ | [0.2.5 notes](docs/releases/release-notes-0.2.5.md) | Release scope, upgrade impact and validation boundaries |
238
268
 
239
269
  ## Contributing
240
270
 
package/README.zh-CN.md CHANGED
@@ -4,13 +4,22 @@
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-rc3 候选](https://img.shields.io/badge/RC-0.2.5--rc3-5B6B7A)](docs/releases/release-notes-0.2.5-rc3.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
 
11
- Agent Guard 是给编码 Agent 用的可靠性工具:在受支持的破坏性操作前建立
12
- 恢复路径,在文本外发前检查泄露风险,并让用户通过 Lab 验测实际观察到的
13
- Agent/宿主行为。共享 Python Core 可通过显式 CLI 或可选宿主适配器使用。
11
+ Agent Guard 在受支持的删除、覆盖操作前保留恢复数据,检查待外发文本中的
12
+ 敏感信息,并提供 Lab 来测试 Agent 和宿主的实际行为。共享 Python Core
13
+ 可通过命令行工具或宿主适配器调用。
14
+
15
+ **负责接入本项目的 AI agent:** 修改配置或编写桥接前,必须先读取
16
+ [适配要求](adapters/INTEGRATION.md),再阅读
17
+ [接入流程](docs/guides/getting-started.md#set-up-a-coding-agent)和对应适配器指南。
18
+ 确认实际宿主/版本,查阅其官方 hook 文档,完成验证后报告实际覆盖范围。
19
+ 不能仅凭 Skill 已安装或配置已复制,就告诉用户防护已生效。
20
+
21
+ 目前主要维护 **DSH 和 Kimi Code** 的接入。其他宿主建议交给对应的官方
22
+ 编码 Agent 在本地配置。
14
23
 
15
24
  | 能力 | 能帮助你做什么 | 入口 |
16
25
  |---|---|---|
@@ -56,13 +65,13 @@ harness/版本/模型、任务、协议及非防护配置。结果只覆盖
56
65
  [DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
57
66
  失败和待审状态。
58
67
 
59
- RC3 新增[蓝队研究](docs/research/README.md)、
68
+ 自 RC3 起,包中包含[蓝队研究](docs/research/README.md)、
60
69
  [去敏实验报告](docs/reports/blue-team-lab-2026-10.md)和
61
70
  [便携四控制示例](docs/lab/blue-team-calibration.md),公开来源、发送授权和正常任务效用的
62
71
  有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进,欢迎 fork、PR
63
72
  与独立防守复现;失败和未定结果也应保留。
64
73
 
65
- 在 RC3 源码或评审包根目录,可一次运行现有四种控制:
74
+ 在包含该示例的源码或包根目录,可一次运行现有四种控制:
66
75
 
67
76
  ```sh
68
77
  blue_run="$(mktemp -d)"
@@ -78,15 +87,21 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
78
87
 
79
88
  | 版本 | 状态 |
80
89
  |---|---|
81
- | [0.2.4](docs/releases/release-notes-0.2.4.md) | 已发布的稳定基线 |
82
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 已发布的历史预发布基线 |
83
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | 维护预发布;以准确版本的发布回执为准 |
84
- | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 研究/文档源码预览;包发布以独立回执为准 |
90
+ | [0.2.6](docs/releases/release-notes-0.2.6.md) | 正式版;npm `latest`;发布地址见下方 |
91
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | 上一稳定版 |
92
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | 更早稳定版 |
93
+ | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
94
+ | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
95
+
96
+ 实际发布状态以精确版本的
97
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)和
98
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6)为准,
99
+ checkout 或 manifest 本身不代表包已可安装。
85
100
 
86
101
  稳定包可安装到用户选定的长期目录:
87
102
 
88
103
  ```sh
89
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
104
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.6
90
105
  ```
91
106
 
92
107
  包根目录是
@@ -98,14 +113,17 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
98
113
  cd agent-guard
99
114
  ```
100
115
 
101
- RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定版 `latest`。
102
- 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
103
- 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)为准,
104
- 也可使用已核查的 checkout 或提供的 tarball;manifest 版本不代表 registry 已可安装。
105
- 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)。
116
+ 选用已发布的预发布版时,指定 `@mokuyoaxis/agent-guard@0.2.5-rc3`,对应
117
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)与
118
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)。
119
+ 若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
120
+ 这两个通道均不替换稳定版 `latest`。
106
121
 
107
- 通过已核查源码 checkout 或提供的 tarball 评估 RC3;manifest 或 main 提交不代表 registry 已发布。
108
- 版本标签与 GitHub/npm 包发布分别执行。
122
+ [0.2.6](docs/releases/release-notes-0.2.6.md) 在 0.2.5 的基础上补充 Kimi 可选 Stop
123
+ 恢复反馈、独立 Stop doctor 检查、DSH Lab 预检诊断、DSH `0.2.1-alpha.4` 默认删除适配,
124
+ 以及 Kimi `2.3.0` Bash profile。已有安装需要升级才能取得这些功能,Stop 还需显式配置。
125
+ 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md),
126
+ 功能边界见[维护说明](docs/releases/unreleased.md)。
109
127
 
110
128
  ## 恢复一次受支持的删除
111
129
 
@@ -115,7 +133,7 @@ RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定
115
133
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
116
134
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
117
135
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
118
- python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
136
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
119
137
  ```
120
138
 
121
139
  有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被
@@ -124,13 +142,18 @@ hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force res
124
142
  先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的
125
143
  事务 ID、现场文件和状态,再决定后续动作。
126
144
 
145
+ 0.2.5 明确提示:迁入回收站的数据仍占空间,
146
+ GC 需要显式执行,`ALLOW_NOOP` 不代表未识别命令没有破坏性。
147
+ 本地状态查询也不能证明宿主已加载防护。见[状态与清理反馈](docs/guides/recovery-feedback.md)。
148
+
127
149
  advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,但可能写入
128
150
  隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
129
151
  操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
130
152
 
131
153
  RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
132
154
  restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
133
- 这些维护不属于已发布的 0.2.4 包,见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
155
+ 原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。
156
+ 见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
134
157
 
135
158
  RC2 进一步限定通用审计字段、使用不透明 session 关联,
136
159
  并收口旧日志 status 展示与 GC 元信息,见[审计契约及保留边界](docs/guides/audit-metadata.md)。
@@ -168,15 +191,18 @@ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
168
191
 
169
192
  ## 接入你的编码 Agent
170
193
 
171
- 下列为按版本保留的历史观察,不代表新候选源码、所有工具或所有子代理路径
172
- 都已验收。
194
+ 让对应宿主的官方编码 Agent 按[适配指南](adapters/INTEGRATION.md),为当前
195
+ 安装的版本配置 Agent Guard。优先使用能在工具执行前阻止调用的 hook。
196
+ 我们主要维护 DSH 和 Kimi Code 的接入;其他宿主由 Agent 在本地配置桥接。
197
+
198
+ 下表记录所测源码、宿主版本和工具路径;其他组合需要另行验证。
173
199
 
174
200
  | 宿主 | 接入与证据 |
175
201
  |---|---|
176
- | Claude Code | Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
177
- | Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
178
- | DSH | 核查过 0.1.5-rc.1/0.2.0-rc.2 的删除路径;完整文本 read 防护默认关闭。特定 PTC Bash 拒绝不代表所有 PTC API 都受控。[接入](adapters/dsh/README.md) |
179
- | Codex/其他宿主 | 可显式使用 Skill/CLI。原生拦截需先验证宿主提供阻塞 hook。[适配指南](adapters/INTEGRATION.md) |
202
+ | Claude Code | 保留参考实现,暂缓新版本验收。Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
203
+ | Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。0.2.6 新增 2.3.0 prompt/ACP 根代理 Bash 固定响应证据。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
204
+ | DSH | 默认删除适配覆盖 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4。可选原生 read 与 Lab 保留各自的两版边界。[兼容范围](docs/design/dsh-compatibility.md) · [接入](adapters/dsh/README.md) |
205
+ | Codex/其他宿主 | 推荐官方 Agent 按当前版本完成本地 hook 接入,并验证确实阻止执行。没有阻塞 hook 时,Skill/CLI 仍属于协作式使用。[适配指南](adapters/INTEGRATION.md) |
180
206
 
181
207
  精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
182
208
  `doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
@@ -204,7 +230,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
204
230
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
205
231
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
206
232
  | [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
207
- | [0.2.5-rc3 说明](docs/releases/release-notes-0.2.5-rc3.md) | 当前源码候选范围与验收状态 |
233
+ | [0.2.5 说明](docs/releases/release-notes-0.2.5.md) | 发布范围、升级影响与验证边界 |
208
234
 
209
235
  ## 参与贡献
210
236
 
package/SECURITY.md CHANGED
@@ -9,8 +9,9 @@ where possible. See [CONTRIBUTING.md](CONTRIBUTING.md) before sharing captures.
9
9
 
10
10
  ## What agent-guard claims to be
11
11
 
12
- Reliability infrastructure: it makes destructive actions reversible by
13
- 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
14
15
  with the same OS privileges as the guard can bypass it. See
15
16
  [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
16
17
 
@@ -49,7 +50,8 @@ from local command checks and require a selected experiment scope.
49
50
 
50
51
  Recovery manifests, CLI diagnostics and historical audit records can contain
51
52
  exact paths or other private text. Writer minimization introduced in RC1 and
52
- the shared projection introduced in RC2 remain in RC3; they do not make every
53
+ the shared projection introduced in RC2 remain in 0.2.5;
54
+ they do not make every
53
55
  output or old record secret-free. The exfil text
54
56
  CLIs return decisions/plans or sanitized stdout; they do not automatically
55
57
  persist egress audit events. Review and redact evidence before sharing it.
@@ -1,9 +1,30 @@
1
1
  # Integrating another coding-agent host
2
2
 
3
- This is a checklist for a user or their agent, **not** a claim that an
4
- unlisted host is supported. Start with the [capability and evidence
5
- matrix](../docs/guides/harness-capabilities.md). A prompt, Skill, CLI call, or
6
- adapter exit code alone does not prove automatic tool interception.
3
+ Use this checklist to configure Agent Guard for your installed coding-agent
4
+ host and version. The [capability matrix](../docs/guides/harness-capabilities.md)
5
+ records which paths have been tested. A prompt, Skill, CLI call or adapter
6
+ exit code alone does not prove automatic tool interception.
7
+
8
+ Give the host's **official coding agent** the
9
+ [setup prompt](../docs/guides/getting-started.md#set-up-a-coding-agent) and this
10
+ guide. It should check the installed version and official hook documentation,
11
+ reuse a matching adapter where possible, and prefer a synchronous hook that
12
+ can block the call before execution. The project maintains the shared Core,
13
+ CLI/Decision Protocol, reference adapters and these verification steps.
14
+
15
+ We currently focus on **DSH and Kimi Code**. The Claude Code adapter and its
16
+ tested-version records remain available; testing new Claude versions is
17
+ paused. For other hosts, including Codex, create only the bridge and
18
+ configuration needed locally, within the user's authorized scope. Call the
19
+ shared Core rather than copying its policy. A local setup does not extend
20
+ the project's tested-version list.
21
+
22
+ **Instructions for the AI agent doing the setup:** Read this guide before
23
+ editing settings or writing a bridge, including when an adapter already
24
+ exists. Then read the relevant Skill contracts and adapter guide, inspect the
25
+ installed host, and check its official hook documentation. Complete the
26
+ checks below and report their actual results; a copied configuration is not
27
+ an acceptance result. Reuse Core rather than duplicating its policy rules.
7
28
 
8
29
  ## 1. Identify the actual boundary
9
30
 
@@ -15,12 +36,18 @@ exit/response semantics, approval behavior, matcher rules, timeout, and what
15
36
  happens when the hook is missing or fails to start. A post-tool event cannot
16
37
  undo an already executed operation.
17
38
 
39
+ Check whether the project or individual hook requires trust review. Complete
40
+ the host's normal review within the authorized scope, or report activation
41
+ as pending; a configured but untrusted hook is not active protection.
42
+
18
43
  Read only the relevant hook configuration. Do not copy authentication
19
44
  material, private routes, or the full user configuration into model context
20
45
  or a public report. If the host contract or version is unclear, mark it
21
46
  `UNVERIFIED` rather than guessing from another host's schema.
22
47
 
23
- ## 2. Choose the smallest honest integration
48
+ <a id="2-choose-the-smallest-honest-integration"></a>
49
+
50
+ ## 2. Choose an integration
24
51
 
25
52
  - **Documented host:** choose its adapter README from the
26
53
  [integration matrix](../README.md#integration-and-validation-matrix) and
@@ -47,12 +74,31 @@ command targets, but may initialize quarantine/audit metadata and a Git local
47
74
  exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
48
75
  [assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
49
76
 
77
+ Verify recovery feedback separately from the allow/deny decision. A successful
78
+ hook can authorize a tool while the host omits its explanation from the next
79
+ model request. Kimi's [optional Stop feedback](kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition)
80
+ ships in [0.2.6](../docs/releases/release-notes-0.2.6.md);
81
+ it adds a response after
82
+ the initial answer. A pre-tool doctor PASS does not verify that later delivery.
83
+
50
84
  ## 3. Configure and verify without destructive trials
51
85
 
52
- Before editing user-wide settings, changing security policy, or installing
53
- dependencies, show the exact proposed change and obtain user approval. Keep
54
- the prior configuration and a rollback path. Prefer a disposable project and
55
- a project-scoped configuration where the host supports it.
86
+ Stay within the user's already authorized paths and configuration scope.
87
+ For additional user-wide settings, security-policy changes, or dependencies
88
+ beyond that scope, show the exact proposed change and obtain approval first.
89
+ Keep the prior configuration and a rollback path. Prefer a disposable project
90
+ and a project-scoped configuration where the host supports it.
91
+
92
+ Keep the user's selected account and model provider. If model authentication
93
+ is unavailable, complete the available local checks and record which live
94
+ checks could not run.
95
+
96
+ Choose checks that are present in the selected root. A full source checkout
97
+ includes `tests/`; the npm package omits that directory and provides the
98
+ CLIs, adapters and doctor instead. For a packaged Kimi/Claude setup, run the
99
+ local doctor probes and any additional fixed-payload checks needed below.
100
+ Report the source unit suite as `NOT_INCLUDED` when absent; it is a separate
101
+ validation step requiring a full checkout.
56
102
 
57
103
  1. Run adapter contract tests with fixed payloads: allowed call, policy
58
104
  refusal, compensable call, malformed payload, `ASK`, and a failed runtime.
@@ -68,9 +114,22 @@ a project-scoped configuration where the host supports it.
68
114
  mismatched, timed out, or bypassed, record that as a gap; adapter tests
69
115
  cannot turn those host boundaries into fail-closed behavior.
70
116
 
117
+ Keep configuration and fresh-host verification as separate stages. When
118
+ hooks load at startup, finish the settings and local probes, then report the
119
+ paths, results and pending activation before opening the next authorized
120
+ host process. Repeating local probes cannot turn `host_interception` or
121
+ `model_delivery` into PASS. At a step limit, leave a checkpoint with completed
122
+ work and remaining checks so the next session can continue without repeating
123
+ the setup.
124
+
71
125
  `doctor.py` currently supports only `kimi` and `claude`. Its configuration
72
126
  and local-probe PASS states do **not** prove a live host loaded or enforced a
73
127
  hook. Do not reuse those states as an unknown-host certification.
128
+ The 0.2.6 Kimi doctor also reports optional Stop under `feedback`.
129
+ Its configuration/local probe is separate from PreToolUse, and
130
+ `model_delivery` remains `UNVERIFIED`. A missing Stop is optional; an invalid
131
+ or locally failing configured Stop exits 1. The importable `check_kimi()`
132
+ wrapper retains its original PreToolUse-only scope for existing Lab callers.
74
133
  For those two hosts, `--check-drift` adds local version/profile comparison and
75
134
  privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
76
135
  version change; it does not assert incompatibility. `CURRENT` still does not
@@ -83,7 +142,9 @@ hook receipt, matching Core audit, host block feedback, and an absent marker;
83
142
  missing evidence is INCONCLUSIVE. It is not an adversarial sandbox and must
84
143
  not be generalized to subagents or other tools.
85
144
 
86
- ## 4. Report the evidence, not a blanket guarantee
145
+ <a id="4-report-the-evidence-not-a-blanket-guarantee"></a>
146
+
147
+ ## 4. Report results
87
148
 
88
149
  Report the host/version, tool and event, config scope, root/subagent path,
89
150
  dialect, model setup if one was used, the Core decision, host outcome, and
@@ -94,3 +155,16 @@ Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
94
155
  `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
95
156
  evidence, not an independent security boundary against that same agent or a
96
157
  malicious host with equal OS privileges.
158
+
159
+ Leave a short handoff so the user or next session can continue:
160
+
161
+ ```text
162
+ Host/version, OS and shell dialect:
163
+ Agent Guard root/version:
164
+ Changed configuration/bridge paths and rollback:
165
+ Hook event/tools, trust and activation state:
166
+ Core decision mappings, including ASK:
167
+ Local checks and evidence locations:
168
+ Host interception and recovery-feedback observations:
169
+ Unverified checks and next action:
170
+ ```
@@ -1,5 +1,11 @@
1
1
  # agent-guard adapter for Claude Code
2
2
 
3
+ We currently focus on DSH and Kimi Code. This Claude Code adapter and its past
4
+ test results remain available as a reference; testing new Claude versions is
5
+ paused. For local setup, follow the [integration requirements](../INTEGRATION.md)
6
+ and independently test the installed version. The results below cover only
7
+ the recorded versions.
8
+
3
9
  Wraps Claude Code's `PreToolUse` hook so matching Bash calls that reach the
4
10
  hook pass through the shared core (`skills/delete-guard/scripts/check.py`)
5
11
  before execution. A missing, mismatched, or timed-out hook is not covered.
@@ -10,7 +10,7 @@ a bounded local worker. Both ship inside this package.
10
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
- The package admits both exact host versions. Lab preflight accepts both and
13
+ Those are the published 0.2.5 host declarations. 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
16
  checkout or its agent scope. The [initial upgrade check](../../docs/reports/test-report-dsh-0.2-upgrade.md)
@@ -18,12 +18,13 @@ 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.6 release](../../docs/releases/release-notes-0.2.6.md) retains the
22
+ startup/status diagnostics below and adds DSH `0.2.1-alpha.4` for default
23
+ deletion interception. Optional native read keeps its separate boundary.
24
+ Install the exact stable version:
24
25
 
25
26
  ```bash
26
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
27
+ dsh plugin --profile 'your-profile' add @mokuyoaxis/agent-guard@0.2.6
27
28
  ```
28
29
 
29
30
  Use an exact package version whose host contract matches your DSH installation.
@@ -31,17 +32,60 @@ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
31
32
  Git must already be available. Installation does not enable the optional
32
33
  text-read guard.
33
34
 
35
+ As checked on 2026-10-19, the published opt-in versions are
36
+ `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
37
+ `@mokuyoaxis/agent-guard@0.2.5-rc3` for the cumulative prerelease.
38
+ Versioned [GitHub](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)
39
+ and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6)
40
+ receipts establish 0.2.6 availability. A reviewed checkout or tarball is also
41
+ usable as described in [getting started](../../docs/guides/getting-started.md).
42
+
43
+ Version [0.2.6](../../docs/releases/release-notes-0.2.6.md) adds
44
+ Lab version/config preflight diagnostics and admits `0.2.1-alpha.4` for the default deletion
45
+ adapter, alongside `0.1.5-rc.1` and `0.2.0-rc.2`. It retains the existing
46
+ interception and recovery logic. Alpha.4 is not admitted for optional native
47
+ read protection or Lab. See [DSH compatibility](../../docs/design/dsh-compatibility.md)
48
+ for the exact declarations and [native validation](../../docs/reports/test-report-dsh-alpha4.md)
49
+ for the evidence. Upgrade an existing 0.2.5 installation to obtain these additions.
50
+ See the [Lab runner](harness/README.md)
51
+ for the separate preflight diagnostic fields.
52
+
34
53
  ## What gets registered
35
54
 
36
55
  | Contribution | Mechanism | Behavior |
37
56
  |---|---|---|
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 |
57
+ | 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
58
  | `agent_guard_safe_delete` | model tool | recoverable delete with explicit glob expansion and manifest |
40
59
  | `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 |
60
+ | `agent_guard_status` | model tool | adapter diagnostics, mode, usage, retention view, GC commands and recent decisions; no live-host certification |
42
61
  | Prompt section | system prompt (order 105) | deletion discipline for the model |
43
62
  | 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
63
 
64
+ ## Startup and status diagnostics
65
+
66
+ Version 0.2.5 runs `python3 check.py --help`
67
+ before contributing the Hook/tools. This tests Python and imports in the
68
+ plugin process, without assessing a command or writing guard metadata.
69
+ Missing dependencies or a failed/timed-out startup check produce an explicit
70
+ initialization error instead of a log-only disabled adapter. The local check
71
+ has a 10-second timeout; the existing command-check timeout remains unchanged.
72
+
73
+ Startup success says that the listener was registered, while live host
74
+ interception remains `UNVERIFIED`. `agent_guard_status.adapter` reports that
75
+ distinction and the most recent checker result. It does not turn a local
76
+ Python test into a check of every shell/sandbox environment. If the plugin
77
+ never loads, its tools may be absent: inspect the host's plugin activation
78
+ status. An initialization error does not stop the host's other tools.
79
+
80
+ Checker process errors, timeout and unusable output remain denials with
81
+ static diagnostics separate from policy refusals. Relocation results state
82
+ that data still occupies storage; status includes accurate GC commands.
83
+ Status-query timeout, unsuccessful exit and unusable reports return `ok: false`
84
+ with a `STATUS_*` diagnostic and adapter facts, without changing the last
85
+ command-checker result. Partial relocation failures retain their recovery IDs
86
+ and storage guidance when files have moved.
87
+ See [status and cleanup feedback](../../docs/guides/recovery-feedback.md).
88
+
45
89
  ## Configuration (cordis.patch.yml row)
46
90
 
47
91
  | Key | Default | Meaning |
@@ -0,0 +1,14 @@
1
+ {
2
+ "schema_version": 1,
3
+ "profile_id": "dsh-pre-execute-bash-v1",
4
+ "harness": "dsh",
5
+ "display_name": "DeepSeek Harness",
6
+ "tested_versions": ["0.1.5-rc.1", "0.2.0-rc.2", "0.2.1-alpha.4"],
7
+ "contract": {
8
+ "event": "tools/pre-execute",
9
+ "tools": ["bash"],
10
+ "blocking": true,
11
+ "ask": "native-or-deny",
12
+ "scope": "default-deletion-adapter"
13
+ }
14
+ }