@mokuyoaxis/agent-guard 0.2.5 → 0.2.7

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 (52) hide show
  1. package/README.md +61 -23
  2. package/README.zh-CN.md +51 -22
  3. package/adapters/INTEGRATION.md +90 -10
  4. package/adapters/claude/README.md +6 -0
  5. package/adapters/dsh/README.md +19 -8
  6. package/adapters/dsh/compatibility.json +14 -0
  7. package/adapters/dsh/harness/README.md +11 -0
  8. package/adapters/dsh/harness/guard_lab.py +42 -14
  9. package/adapters/kimi-code/README.md +154 -14
  10. package/adapters/kimi-code/compatibility.json +1 -1
  11. package/adapters/kimi-code/config.example.toml +18 -6
  12. package/adapters/kimi-code/hook_bridge.sh +19 -4
  13. package/adapters/kimi-code/pre_tool_use.py +1 -1
  14. package/adapters/kimi-code/stop_feedback.py +237 -0
  15. package/adapters/mcp/__init__.py +1 -0
  16. package/adapters/mcp/operations.py +174 -0
  17. package/adapters/mcp/requirements.txt +3 -0
  18. package/adapters/mcp/server.py +126 -0
  19. package/core/admission.py +388 -0
  20. package/core/audit.py +1 -1
  21. package/core/classifier.py +2 -1
  22. package/core/cleanup.py +297 -0
  23. package/core/delete_config.py +153 -0
  24. package/core/policy.py +35 -7
  25. package/core/recovery.py +10 -0
  26. package/docs/README.md +25 -7
  27. package/docs/design/architecture.md +16 -4
  28. package/docs/design/compatibility.md +230 -6
  29. package/docs/design/dsh-compatibility.md +65 -0
  30. package/docs/design/threat-model.md +53 -1
  31. package/docs/guides/cleanup-plan.md +227 -0
  32. package/docs/guides/deletion-limits.md +150 -0
  33. package/docs/guides/getting-started.md +72 -11
  34. package/docs/guides/harness-capabilities.md +37 -4
  35. package/docs/guides/host-drift.md +32 -0
  36. package/docs/guides/mcp.md +293 -0
  37. package/docs/guides/recovery-feedback.md +29 -1
  38. package/docs/history/friction.md +99 -1
  39. package/docs/releases/release-notes-0.2.6.md +167 -0
  40. package/docs/releases/release-notes-0.2.7.md +217 -0
  41. package/docs/releases/unreleased.md +275 -0
  42. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  43. package/docs/reports/test-report-dsh-paired-lab.md +1 -1
  44. package/docs/reports/test-report-kimi-code-block.md +120 -7
  45. package/doctor.py +175 -28
  46. package/package.json +13 -2
  47. package/skills/delete-guard/SKILL.md +69 -1
  48. package/skills/delete-guard/references/policy.md +66 -3
  49. package/skills/delete-guard/scripts/check.py +39 -9
  50. package/skills/delete-guard/scripts/cleanup.py +164 -0
  51. package/skills/delete-guard/scripts/safe_delete.py +22 -4
  52. package/skills/delete-guard/scripts/status.py +77 -1
package/README.md CHANGED
@@ -4,23 +4,42 @@
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](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
7
+ [![0.2.7](https://img.shields.io/badge/version-0.2.7-5B6B7A)](docs/releases/release-notes-0.2.7.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.
25
+
26
+ This documentation covers [0.2.7](docs/releases/release-notes-0.2.7.md), adding
27
+ Cleanup plans, deletion admission limits and optional local MCP tools.
28
+ Check the exact-version release channels below before installing.
15
29
 
16
30
  | Capability | What it helps you do | Entry |
17
31
  |---|---|---|
18
32
  | **Recovery protection** | Relocate valuable files before deletion; snapshot tracked state before supported Git overwrites; inspect and restore transactions | [delete-guard](skills/delete-guard/SKILL.md) |
33
+ | **Cleanup proposals (0.2.7)** | Review classified workspace candidates, sizes and effects; explicitly confirm selected targets before safe_delete | [Cleanup Copilot](docs/guides/cleanup-plan.md) |
34
+ | **Deletion limits (0.2.7)** | Inspect shared protected paths, persistent budgets, rate/repeat limits and large-batch confirmation | [Limits and recovery](docs/guides/deletion-limits.md) |
35
+ | **Local MCP tools (0.2.7)** | Call safe_delete, ordinary restore, transaction/status queries and GC preview from a supporting client | [MCP setup](docs/guides/mcp.md) |
19
36
  | **Disclosure checks** | Detect supported credentials and host-identifying paths; apply a redaction plan or withhold a payload | [exfil-guard](skills/exfil-guard/SKILL.md) |
20
37
  | **Behaviour experiments** | Calibrate an observer, test a declared exposure channel, then compare matched guard-off/on trials | [guard-lab](docs/lab/guard-lab.md) |
21
38
 
22
39
  A Skill supplies instructions; it does not intercept tool calls. Automatic
23
40
  protection depends on an active, compatible host hook and its covered tools.
41
+ The optional local MCP adapter provides explicit tools and does not intercept
42
+ actions that bypass them; its SDK installation is separate from the Core.
24
43
  Agent Guard is not an OS sandbox against a malicious process with equal
25
44
  privileges. The [capability matrix](docs/guides/harness-capabilities.md)
26
45
  states the observed coverage and gaps.
@@ -88,22 +107,33 @@ This example calls no model; its summary describes instrument calibration.
88
107
 
89
108
  Python 3.9+ and Git are required for the Core. The examples use a POSIX shell;
90
109
  native bridges and optional capture helpers have their own requirements.
110
+ The optional MCP adapter requires Python 3.10+ and a separately installed
111
+ [pinned SDK](docs/guides/mcp.md).
91
112
 
92
113
  | Version | Status |
93
114
  |---|---|
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 |
115
+ | [0.2.7](docs/releases/release-notes-0.2.7.md) | Version documented here; verify exact-version availability below |
116
+ | [0.2.6](docs/releases/release-notes-0.2.6.md) | Earlier published release with Kimi feedback and host compatibility updates |
117
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | Earlier stable release |
118
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | Earlier stable release |
96
119
  | [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
120
  | [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).
121
+
122
+ Before installing 0.2.7, confirm availability through its exact
123
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
124
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7).
101
125
  A checkout or manifest alone does not establish package availability.
102
126
 
103
- For the stable release, use a chosen, stable user-owned prefix:
127
+ If that version is unavailable, use reviewed source or a locally built
128
+ tarball following the [version notes](docs/releases/release-notes-0.2.7.md).
129
+ Versioned tests and package checks are recorded separately from the historical
130
+ 0.2.6-metadata source results. Existing successful deletes can newly be
131
+ refused by the [admission limits](docs/guides/deletion-limits.md).
132
+
133
+ Once the exact version is available, install to a chosen, stable user-owned prefix:
104
134
 
105
135
  ```sh
106
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
136
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
107
137
  ```
108
138
 
109
139
  The package root is
@@ -122,10 +152,13 @@ identify that package. For only the stable-line quarantine protection fix,
122
152
  select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
123
153
  replaces stable `latest`.
124
154
 
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
128
- [setup and the agent setup prompt](docs/guides/getting-started.md).
155
+ Version [0.2.6](docs/releases/release-notes-0.2.6.md) builds on 0.2.5 with
156
+ optional Kimi Stop recovery feedback, separate Stop doctor checks, DSH Lab
157
+ preflight diagnostics, DSH `0.2.1-alpha.4` default deletion support and the
158
+ Kimi `2.3.0` Bash profile. Existing installations need an upgrade to acquire
159
+ these additions; Stop also needs explicit configuration. See
160
+ [setup and the agent setup prompt](docs/guides/getting-started.md) and the
161
+ [0.2.6 version details](docs/releases/release-notes-0.2.6.md).
129
162
 
130
163
  ## Recover a supported deletion
131
164
 
@@ -206,15 +239,20 @@ Read the [Skill](skills/exfil-guard/SKILL.md),
206
239
 
207
240
  ## Connect your coding agent
208
241
 
209
- These are version-specific historical observations. They do not certify a
210
- new source candidate, every tool or every subagent path.
242
+ Ask the host's official coding agent to configure Agent Guard for the installed
243
+ version, following the [integration guide](adapters/INTEGRATION.md). Prefer a
244
+ hook that can block a tool call before it runs. We maintain the DSH and Kimi
245
+ Code integrations; other hosts use local bridges and configuration.
246
+
247
+ The results below apply to the recorded source versions, host versions and
248
+ tool paths. Other combinations need their own checks.
211
249
 
212
250
  | Host | Integration and evidence |
213
251
  |---|---|
214
- | Claude Code | Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
215
- | 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) |
216
- | 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) |
217
- | Codex / other hosts | Explicit Skill/CLI is usable. Native interception needs a verified blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
252
+ | 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) |
253
+ | 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) |
254
+ | 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) |
255
+ | 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) |
218
256
 
219
257
  Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
220
258
  for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
@@ -244,7 +282,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
244
282
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
245
283
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
246
284
  | [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 |
285
+ | [0.2.7 notes](docs/releases/release-notes-0.2.7.md) | Version scope, upgrade impact and validation boundaries |
248
286
 
249
287
  ## Contributing
250
288
 
package/README.zh-CN.md CHANGED
@@ -4,23 +4,40 @@
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](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
7
+ [![0.2.7](https://img.shields.io/badge/version-0.2.7-5B6B7A)](docs/releases/release-notes-0.2.7.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 在本地配置。
23
+
24
+ 本文档覆盖 [0.2.7](docs/releases/release-notes-0.2.7.md),新增 Cleanup 计划、
25
+ 删除准入限制与可选本地 MCP 工具。安装前请通过下方精确版本渠道确认可用性。
14
26
 
15
27
  | 能力 | 能帮助你做什么 | 入口 |
16
28
  |---|---|---|
17
29
  | **恢复保护** | 删除前迁移有价值的文件;受支持的 Git 覆盖前快照 tracked 状态;查询和恢复事务 | [delete-guard](skills/delete-guard/SKILL.md) |
30
+ | **清理提议(0.2.7)** | 扫描候选、分类、大小与实际执行方式;显式选择并确认后交给 safe_delete | [Cleanup Copilot](docs/guides/cleanup-plan.md) |
31
+ | **删除限制(0.2.7)** | 查询共享保护路径、持久预算、速率/重复限制与大批量确认 | [限制与恢复](docs/guides/deletion-limits.md) |
32
+ | **本地 MCP 工具(0.2.7)** | 在支持的客户端中调用 safe_delete、普通恢复、事务/状态查询和 GC 预览 | [MCP 接入](docs/guides/mcp.md) |
18
33
  | **外发检测** | 检测受支持的凭据和本机标识路径;应用脱敏计划或拒绝输出 | [exfil-guard](skills/exfil-guard/SKILL.md) |
19
34
  | **行为验测** | 校准观察器,验证声明信道的暴露,再比较匹配的关闭/开启防护试次 | [guard-lab](docs/lab/guard-lab.md) |
20
35
 
21
36
  Skill 提供操作纪律,不会自行拦截工具调用。自动保护依赖宿主实际加载了
22
37
  兼容 hook,且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的
23
38
  OS 沙箱;实际接入证据和缺口见[能力矩阵](docs/guides/harness-capabilities.md)。
39
+ 可选本地 MCP 适配器提供显式工具,不会拦截绕过它的操作;其 SDK 单独安装,
40
+ 不改变 Core 的运行依赖。
24
41
 
25
42
  <a id="guard-lab-合成蜜罐"></a>
26
43
 
@@ -75,22 +92,30 @@ python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/contr
75
92
 
76
93
  Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可选采集
77
94
  工具另有运行要求。
95
+ 可选 MCP 适配器需要 Python 3.10+,并单独安装[固定版本 SDK](docs/guides/mcp.md)。
78
96
 
79
97
  | 版本 | 状态 |
80
98
  |---|---|
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) | 上一稳定版 |
99
+ | [0.2.7](docs/releases/release-notes-0.2.7.md) | 本文档对应版本;精确版本的可用性见下方渠道 |
100
+ | [0.2.6](docs/releases/release-notes-0.2.6.md) | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
101
+ | [0.2.5](docs/releases/release-notes-0.2.5.md) | 更早稳定版 |
102
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | 更早稳定版 |
83
103
  | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
84
104
  | [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)为准,
105
+
106
+ 安装 0.2.7 前,请通过精确版本的
107
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)和
108
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)确认可用性,
88
109
  checkout 或 manifest 本身不代表包已可安装。
89
110
 
90
- 稳定包可安装到用户选定的长期目录:
111
+ 若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.7.md)使用经复核的
112
+ 源码或本地构建 tarball。版本化测试和包核验已单独记录,不能沿用旧 0.2.6 元数据
113
+ 候选的通过结论。此前可执行的删除可能被新的[准入限制](docs/guides/deletion-limits.md)拒绝。
114
+
115
+ 确认精确版本可用后,可安装到用户选定的长期目录:
91
116
 
92
117
  ```sh
93
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
118
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
94
119
  ```
95
120
 
96
121
  包根目录是
@@ -108,10 +133,11 @@ cd agent-guard
108
133
  若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
109
134
  这两个通道均不替换稳定版 `latest`。
110
135
 
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)。
136
+ [0.2.6](docs/releases/release-notes-0.2.6.md) 在 0.2.5 的基础上补充 Kimi 可选 Stop
137
+ 恢复反馈、独立 Stop doctor 检查、DSH Lab 预检诊断、DSH `0.2.1-alpha.4` 默认删除适配,
138
+ 以及 Kimi `2.3.0` Bash profile。已有安装需要升级才能取得这些功能,Stop 还需显式配置。
139
+ 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md),
140
+ 历史功能边界见[0.2.6 说明](docs/releases/release-notes-0.2.6.md)。
115
141
 
116
142
  ## 恢复一次受支持的删除
117
143
 
@@ -179,15 +205,18 @@ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
179
205
 
180
206
  ## 接入你的编码 Agent
181
207
 
182
- 下列为按版本保留的历史观察,不代表新候选源码、所有工具或所有子代理路径
183
- 都已验收。
208
+ 让对应宿主的官方编码 Agent 按[适配指南](adapters/INTEGRATION.md),为当前
209
+ 安装的版本配置 Agent Guard。优先使用能在工具执行前阻止调用的 hook。
210
+ 我们主要维护 DSH 和 Kimi Code 的接入;其他宿主由 Agent 在本地配置桥接。
211
+
212
+ 下表记录所测源码、宿主版本和工具路径;其他组合需要另行验证。
184
213
 
185
214
  | 宿主 | 接入与证据 |
186
215
  |---|---|
187
- | Claude Code | Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
188
- | Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
189
- | DSH | 核查过 0.1.5-rc.1/0.2.0-rc.2 的删除路径;完整文本 read 防护默认关闭。特定 PTC Bash 拒绝不代表所有 PTC API 都受控。[接入](adapters/dsh/README.md) |
190
- | Codex/其他宿主 | 可显式使用 Skill/CLI。原生拦截需先验证宿主提供阻塞 hook。[适配指南](adapters/INTEGRATION.md) |
216
+ | Claude Code | 保留参考实现,暂缓新版本验收。Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
217
+ | 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) |
218
+ | 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) |
219
+ | Codex/其他宿主 | 推荐官方 Agent 按当前版本完成本地 hook 接入,并验证确实阻止执行。没有阻塞 hook 时,Skill/CLI 仍属于协作式使用。[适配指南](adapters/INTEGRATION.md) |
191
220
 
192
221
  精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
193
222
  `doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
@@ -215,7 +244,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
215
244
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
216
245
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
217
246
  | [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
218
- | [0.2.5 说明](docs/releases/release-notes-0.2.5.md) | 发布范围、升级影响与验证边界 |
247
+ | [0.2.7 说明](docs/releases/release-notes-0.2.7.md) | 版本范围、升级影响与验证边界 |
219
248
 
220
249
  ## 参与贡献
221
250
 
@@ -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
@@ -36,6 +63,12 @@ or a public report. If the host contract or version is unclear, mark it
36
63
  - **No verified blocking event:** use the [Skills](../skills) and explicit
37
64
  CLI cooperatively. Say `Skill/CLI only`; do not claim native interception.
38
65
  A hook limited to some tools does not cover other tools or hidden uploads.
66
+ - **Client supports MCP:** the [local MCP adapter](../docs/guides/mcp.md), introduced in 0.2.7,
67
+ exposes explicit safe_delete, ordinary restore, transaction/status queries
68
+ and GC preview. Configure its optional SDK and fixed workspace separately.
69
+ Say `MCP tools only` unless a separate blocking hook has been verified;
70
+ registering tools does not intercept shell, script or editor operations.
71
+ This path adds no force restore, GC execution or model-approved budget reset.
39
72
 
40
73
  Core `ASK` must reach a real human-approval path or become a refusal for that
41
74
  call. It must never silently become allow. Treat malformed payloads and
@@ -47,12 +80,31 @@ command targets, but may initialize quarantine/audit metadata and a Git local
47
80
  exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
48
81
  [assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
49
82
 
83
+ Verify recovery feedback separately from the allow/deny decision. A successful
84
+ hook can authorize a tool while the host omits its explanation from the next
85
+ model request. Kimi's [optional Stop feedback](kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition)
86
+ ships in [0.2.6](../docs/releases/release-notes-0.2.6.md);
87
+ it adds a response after
88
+ the initial answer. A pre-tool doctor PASS does not verify that later delivery.
89
+
50
90
  ## 3. Configure and verify without destructive trials
51
91
 
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.
92
+ Stay within the user's already authorized paths and configuration scope.
93
+ For additional user-wide settings, security-policy changes, or dependencies
94
+ beyond that scope, show the exact proposed change and obtain approval first.
95
+ Keep the prior configuration and a rollback path. Prefer a disposable project
96
+ and a project-scoped configuration where the host supports it.
97
+
98
+ Keep the user's selected account and model provider. If model authentication
99
+ is unavailable, complete the available local checks and record which live
100
+ checks could not run.
101
+
102
+ Choose checks that are present in the selected root. A full source checkout
103
+ includes `tests/`; the npm package omits that directory and provides the
104
+ CLIs, adapters and doctor instead. For a packaged Kimi/Claude setup, run the
105
+ local doctor probes and any additional fixed-payload checks needed below.
106
+ Report the source unit suite as `NOT_INCLUDED` when absent; it is a separate
107
+ validation step requiring a full checkout.
56
108
 
57
109
  1. Run adapter contract tests with fixed payloads: allowed call, policy
58
110
  refusal, compensable call, malformed payload, `ASK`, and a failed runtime.
@@ -68,9 +120,22 @@ a project-scoped configuration where the host supports it.
68
120
  mismatched, timed out, or bypassed, record that as a gap; adapter tests
69
121
  cannot turn those host boundaries into fail-closed behavior.
70
122
 
123
+ Keep configuration and fresh-host verification as separate stages. When
124
+ hooks load at startup, finish the settings and local probes, then report the
125
+ paths, results and pending activation before opening the next authorized
126
+ host process. Repeating local probes cannot turn `host_interception` or
127
+ `model_delivery` into PASS. At a step limit, leave a checkpoint with completed
128
+ work and remaining checks so the next session can continue without repeating
129
+ the setup.
130
+
71
131
  `doctor.py` currently supports only `kimi` and `claude`. Its configuration
72
132
  and local-probe PASS states do **not** prove a live host loaded or enforced a
73
133
  hook. Do not reuse those states as an unknown-host certification.
134
+ The 0.2.6 Kimi doctor also reports optional Stop under `feedback`.
135
+ Its configuration/local probe is separate from PreToolUse, and
136
+ `model_delivery` remains `UNVERIFIED`. A missing Stop is optional; an invalid
137
+ or locally failing configured Stop exits 1. The importable `check_kimi()`
138
+ wrapper retains its original PreToolUse-only scope for existing Lab callers.
74
139
  For those two hosts, `--check-drift` adds local version/profile comparison and
75
140
  privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
76
141
  version change; it does not assert incompatibility. `CURRENT` still does not
@@ -83,7 +148,9 @@ hook receipt, matching Core audit, host block feedback, and an absent marker;
83
148
  missing evidence is INCONCLUSIVE. It is not an adversarial sandbox and must
84
149
  not be generalized to subagents or other tools.
85
150
 
86
- ## 4. Report the evidence, not a blanket guarantee
151
+ <a id="4-report-the-evidence-not-a-blanket-guarantee"></a>
152
+
153
+ ## 4. Report results
87
154
 
88
155
  Report the host/version, tool and event, config scope, root/subagent path,
89
156
  dialect, model setup if one was used, the Core decision, host outcome, and
@@ -94,3 +161,16 @@ Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
94
161
  `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
95
162
  evidence, not an independent security boundary against that same agent or a
96
163
  malicious host with equal OS privileges.
164
+
165
+ Leave a short handoff so the user or next session can continue:
166
+
167
+ ```text
168
+ Host/version, OS and shell dialect:
169
+ Agent Guard root/version:
170
+ Changed configuration/bridge paths and rollback:
171
+ Hook event/tools, trust and activation state:
172
+ Core decision mappings, including ASK:
173
+ Local checks and evidence locations:
174
+ Host interception and recovery-feedback observations:
175
+ Unverified checks and next action:
176
+ ```
@@ -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.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:
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.5
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.
@@ -34,11 +35,21 @@ text-read guard.
34
35
  As checked on 2026-10-19, the published opt-in versions are
35
36
  `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
36
37
  `@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
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
40
41
  usable as described in [getting started](../../docs/guides/getting-started.md).
41
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
+
42
53
  ## What gets registered
43
54
 
44
55
  | Contribution | Mechanism | Behavior |
@@ -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
+ }
@@ -46,6 +46,17 @@ the shipped baseline overlay is always last.
46
46
  Use `--node-executable /absolute/path/to/node` to select the decoder runtime
47
47
  explicitly. This option does not change the runtime chosen by the DSH launcher.
48
48
 
49
+ In [0.2.6](../../../docs/releases/release-notes-0.2.6.md), version/config
50
+ process failures report `START_FAILED`, `TIMEOUT`, `OUTPUT_LIMIT`,
51
+ `NONZERO_EXIT`, or `EMPTY_STDOUT`; an unreviewed version reports
52
+ `UNSUPPORTED_VERSION`. The error includes the exit code (negative for a POSIX
53
+ signal; null if startup failed), capture flags, elapsed/deadline seconds, and
54
+ captured stdout/stderr byte counts. Timeout/limit reasons take precedence over
55
+ the signal used to stop the child. These diagnostics omit raw output, command
56
+ arguments, environment values and paths. Version/config deadlines remain
57
+ 10/15 seconds, with no automatic retries. Published 0.2.5 retains the older
58
+ generic preflight errors; use a reviewed checkout/package for these diagnostics.
59
+
49
60
  ## Capture and review the clean control
50
61
 
51
62
  Every `--output-dir` must be new, with an existing parent. The task file is
@@ -14,6 +14,7 @@ from pathlib import Path
14
14
  import shutil
15
15
  import subprocess
16
16
  import sys
17
+ import time
17
18
  from typing import Optional, Sequence
18
19
 
19
20
 
@@ -111,19 +112,48 @@ def _host_options(
111
112
  return argv, _environment(home)
112
113
 
113
114
 
115
+ def _preflight_error(stage, reason, result, streams, elapsed, timeout):
116
+ # Keep diagnostics useful without echoing configuration, argv or stderr.
117
+ details = {
118
+ "reason": reason, "exit_code": result["exit_code"],
119
+ "start_failed": result["start_failed"], "timed_out": result["timed_out"],
120
+ "output_limit_exceeded": result["output_limit_exceeded"],
121
+ "elapsed_seconds": round(elapsed, 3), "timeout_seconds": timeout,
122
+ "stdout_captured_bytes": len(streams["stdout"]),
123
+ "stderr_captured_bytes": len(streams["stderr"]),
124
+ }
125
+ return LabError("DSH " + stage + " preflight failed: "
126
+ + json.dumps(details, sort_keys=True))
127
+
128
+
129
+ def _capture_preflight(stage, argv, cwd, environment, timeout):
130
+ started = time.monotonic()
131
+ result, streams = _capture_process(argv, cwd, environment, timeout)
132
+ elapsed = time.monotonic() - started
133
+ # A deadline/limit may cause a negative exit code when capture stops the child.
134
+ if result["start_failed"]:
135
+ reason = "START_FAILED"
136
+ elif result["timed_out"]:
137
+ reason = "TIMEOUT"
138
+ elif result["output_limit_exceeded"]:
139
+ reason = "OUTPUT_LIMIT"
140
+ elif result["exit_code"] != 0:
141
+ reason = "NONZERO_EXIT"
142
+ elif not streams["stdout"].strip():
143
+ reason = "EMPTY_STDOUT"
144
+ else:
145
+ return result, streams, elapsed
146
+ raise _preflight_error(stage, reason, result, streams, elapsed, timeout)
147
+
148
+
114
149
  def _config_dump(
115
150
  argv: Sequence[str], cwd: Path, environment: dict[str, str],
116
151
  guard_state: str = "off",
117
152
  *, guard_profile="deletion-v1", workspace=None, dsh_root=None,
118
153
  ) -> bytes:
119
- result, output = _capture_process(
120
- [*argv, "--dump-config"], cwd, environment, 15,
154
+ _, output, _ = _capture_preflight(
155
+ "config", [*argv, "--dump-config"], cwd, environment, 15,
121
156
  )
122
- if (
123
- result["exit_code"] != 0 or result["timed_out"]
124
- or result["output_limit_exceeded"] or not output["stdout"].strip()
125
- ):
126
- raise LabError("DSH config preflight failed; raw diagnostics are not printed")
127
157
  normalize_composition(output["stdout"], guard_state,
128
158
  **_profile_options(guard_profile, workspace, dsh_root))
129
159
  return output["stdout"]
@@ -138,14 +168,12 @@ def check_host(
138
168
  home = home.expanduser().resolve()
139
169
  context = dict(guard_profile=guard_profile, workspace=workspace, dsh_root=dsh_root)
140
170
  argv, environment = _host_options(executable, home, patches, guard_state, guard_patch_file, **context)
141
- result, output = _capture_process([argv[0], "--version"], home.resolve(), environment, 10)
171
+ result, output, elapsed = _capture_preflight(
172
+ "version", [argv[0], "--version"], home.resolve(), environment, 10,
173
+ )
142
174
  version = output["stdout"].strip().decode("ascii", errors="replace")
143
- if (
144
- result["exit_code"] != 0 or result["timed_out"]
145
- or result["output_limit_exceeded"]
146
- or version not in HOST_CONTRACTS
147
- ):
148
- raise LabError("DSH version preflight requires a reviewed exact host version")
175
+ if version not in HOST_CONTRACTS:
176
+ raise _preflight_error("version", "UNSUPPORTED_VERSION", result, output, elapsed, 10)
149
177
  if guard_profile == "read-redaction-v1" and _launcher_root(argv[0], version) != Path(dsh_root).resolve():
150
178
  raise LabError("read profile root must match the selected DSH launcher")
151
179
  configuration = _config_dump(argv, home.resolve(), environment, guard_state, **context)