@mokuyoaxis/agent-guard 0.2.5 → 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.
- package/README.md +39 -19
- package/README.zh-CN.md +33 -18
- package/adapters/INTEGRATION.md +84 -10
- package/adapters/claude/README.md +6 -0
- package/adapters/dsh/README.md +19 -8
- package/adapters/dsh/compatibility.json +14 -0
- package/adapters/dsh/harness/README.md +11 -0
- package/adapters/dsh/harness/guard_lab.py +42 -14
- package/adapters/kimi-code/README.md +154 -14
- package/adapters/kimi-code/compatibility.json +1 -1
- package/adapters/kimi-code/config.example.toml +18 -6
- package/adapters/kimi-code/hook_bridge.sh +19 -4
- package/adapters/kimi-code/pre_tool_use.py +1 -1
- package/adapters/kimi-code/stop_feedback.py +237 -0
- package/docs/README.md +19 -6
- package/docs/design/architecture.md +7 -2
- package/docs/design/compatibility.md +53 -3
- package/docs/design/dsh-compatibility.md +65 -0
- package/docs/guides/getting-started.md +55 -7
- package/docs/guides/harness-capabilities.md +22 -4
- package/docs/guides/host-drift.md +32 -0
- package/docs/guides/recovery-feedback.md +29 -1
- package/docs/releases/release-notes-0.2.6.md +167 -0
- package/docs/releases/unreleased.md +141 -0
- package/docs/reports/test-report-dsh-alpha4.md +102 -0
- package/docs/reports/test-report-kimi-code-block.md +119 -6
- package/doctor.py +175 -28
- package/package.json +11 -2
package/README.md
CHANGED
|
@@ -8,10 +8,20 @@
|
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
11
|
-
Agent Guard
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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
|
|---|---|---|
|
|
@@ -91,19 +101,21 @@ native bridges and optional capture helpers have their own requirements.
|
|
|
91
101
|
|
|
92
102
|
| Version | Status |
|
|
93
103
|
|---|---|
|
|
94
|
-
| [0.2.
|
|
95
|
-
| [0.2.
|
|
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 |
|
|
96
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` |
|
|
97
108
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
|
|
109
|
+
|
|
98
110
|
Publication is established by the exact
|
|
99
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
100
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
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).
|
|
101
113
|
A checkout or manifest alone does not establish package availability.
|
|
102
114
|
|
|
103
115
|
For the stable release, use a chosen, stable user-owned prefix:
|
|
104
116
|
|
|
105
117
|
```sh
|
|
106
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
118
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.6
|
|
107
119
|
```
|
|
108
120
|
|
|
109
121
|
The package root is
|
|
@@ -122,10 +134,13 @@ identify that package. For only the stable-line quarantine protection fix,
|
|
|
122
134
|
select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
|
|
123
135
|
replaces stable `latest`.
|
|
124
136
|
|
|
125
|
-
Version 0.2.
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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).
|
|
129
144
|
|
|
130
145
|
## Recover a supported deletion
|
|
131
146
|
|
|
@@ -206,15 +221,20 @@ Read the [Skill](skills/exfil-guard/SKILL.md),
|
|
|
206
221
|
|
|
207
222
|
## Connect your coding agent
|
|
208
223
|
|
|
209
|
-
|
|
210
|
-
|
|
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.
|
|
211
231
|
|
|
212
232
|
| Host | Integration and evidence |
|
|
213
233
|
|---|---|
|
|
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 |
|
|
217
|
-
| Codex / other hosts |
|
|
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) |
|
|
218
238
|
|
|
219
239
|
Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
|
|
220
240
|
for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
|
package/README.zh-CN.md
CHANGED
|
@@ -8,9 +8,18 @@
|
|
|
8
8
|
|
|
9
9
|
**让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
|
|
10
10
|
|
|
11
|
-
Agent Guard
|
|
12
|
-
|
|
13
|
-
|
|
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
|
|---|---|---|
|
|
@@ -78,19 +87,21 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
78
87
|
|
|
79
88
|
| 版本 | 状态 |
|
|
80
89
|
|---|---|
|
|
81
|
-
| [0.2.
|
|
82
|
-
| [0.2.
|
|
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) | 更早稳定版 |
|
|
83
93
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
|
|
84
94
|
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
|
|
95
|
+
|
|
85
96
|
实际发布状态以精确版本的
|
|
86
|
-
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.
|
|
87
|
-
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
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)为准,
|
|
88
99
|
checkout 或 manifest 本身不代表包已可安装。
|
|
89
100
|
|
|
90
101
|
稳定包可安装到用户选定的长期目录:
|
|
91
102
|
|
|
92
103
|
```sh
|
|
93
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
104
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.6
|
|
94
105
|
```
|
|
95
106
|
|
|
96
107
|
包根目录是
|
|
@@ -108,10 +119,11 @@ cd agent-guard
|
|
|
108
119
|
若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
|
|
109
120
|
这两个通道均不替换稳定版 `latest`。
|
|
110
121
|
|
|
111
|
-
0.2.5
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
[入门指南](docs/guides/getting-started.md)
|
|
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)。
|
|
115
127
|
|
|
116
128
|
## 恢复一次受支持的删除
|
|
117
129
|
|
|
@@ -179,15 +191,18 @@ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
|
|
|
179
191
|
|
|
180
192
|
## 接入你的编码 Agent
|
|
181
193
|
|
|
182
|
-
|
|
183
|
-
|
|
194
|
+
让对应宿主的官方编码 Agent 按[适配指南](adapters/INTEGRATION.md),为当前
|
|
195
|
+
安装的版本配置 Agent Guard。优先使用能在工具执行前阻止调用的 hook。
|
|
196
|
+
我们主要维护 DSH 和 Kimi Code 的接入;其他宿主由 Agent 在本地配置桥接。
|
|
197
|
+
|
|
198
|
+
下表记录所测源码、宿主版本和工具路径;其他组合需要另行验证。
|
|
184
199
|
|
|
185
200
|
| 宿主 | 接入与证据 |
|
|
186
201
|
|---|---|
|
|
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 |
|
|
190
|
-
| Codex/其他宿主 |
|
|
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) |
|
|
191
206
|
|
|
192
207
|
精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
|
|
193
208
|
`doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
|
package/adapters/INTEGRATION.md
CHANGED
|
@@ -1,9 +1,30 @@
|
|
|
1
1
|
# Integrating another coding-agent host
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
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.
|
package/adapters/dsh/README.md
CHANGED
|
@@ -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
|
-
|
|
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.
|
|
22
|
-
startup/status diagnostics below
|
|
23
|
-
|
|
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.
|
|
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.
|
|
38
|
-
and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.
|
|
39
|
-
receipts establish 0.2.
|
|
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
|
-
|
|
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 =
|
|
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
|
-
|
|
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)
|