@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -23
- package/README.zh-CN.md +29 -18
- package/SECURITY.md +5 -3
- package/adapters/dsh/README.md +39 -6
- package/adapters/dsh/lib/index.js +127 -33
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +16 -7
- package/docs/design/architecture.md +8 -6
- package/docs/design/compatibility.md +37 -4
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +28 -17
- package/docs/guides/harness-capabilities.md +5 -4
- package/docs/guides/recovery-feedback.md +98 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +1 -1
- package/docs/lab/guard-lab.md +6 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +30 -13
- package/skills/delete-guard/references/policy.md +16 -3
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.5.md)
|
|
8
8
|
|
|
9
9
|
**Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
|
|
10
10
|
|
|
@@ -65,7 +65,7 @@ external transfer or model request. Existing
|
|
|
65
65
|
[DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
|
|
66
66
|
results, failures and review states.
|
|
67
67
|
|
|
68
|
-
RC3
|
|
68
|
+
Since RC3, the package includes [blue-team research](docs/research/README.md), a
|
|
69
69
|
[sanitized experiment report](docs/reports/blue-team-lab-2026-10.md) and a
|
|
70
70
|
[portable four-control example](docs/lab/blue-team-calibration.md).
|
|
71
71
|
The research covers provenance, disclosure permissions and task utility in
|
|
@@ -73,7 +73,7 @@ bounded private experiments; those methods do not extend production hook
|
|
|
73
73
|
coverage. Lab proceeds gradually. Forks, PRs and independent defensive
|
|
74
74
|
reproductions are welcome; preserve failed and inconclusive results.
|
|
75
75
|
|
|
76
|
-
From
|
|
76
|
+
From a checkout or package containing the example, run all four existing controls:
|
|
77
77
|
|
|
78
78
|
```sh
|
|
79
79
|
blue_run="$(mktemp -d)"
|
|
@@ -91,15 +91,19 @@ native bridges and optional capture helpers have their own requirements.
|
|
|
91
91
|
|
|
92
92
|
| Version | Status |
|
|
93
93
|
|---|---|
|
|
94
|
-
| [0.2.
|
|
95
|
-
| [0.2.
|
|
96
|
-
| [0.2.
|
|
97
|
-
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) |
|
|
94
|
+
| [0.2.5](docs/releases/release-notes-0.2.5.md) | Stable release line; npm `latest`; availability in the versioned receipts below |
|
|
95
|
+
| [0.2.4](docs/releases/release-notes-0.2.4.md) | Previous stable release |
|
|
96
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | Opt-in quarantine protection backport; npm `hotfix` |
|
|
97
|
+
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
|
|
98
|
+
Publication is established by the exact
|
|
99
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
100
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5).
|
|
101
|
+
A checkout or manifest alone does not establish package availability.
|
|
98
102
|
|
|
99
|
-
For the
|
|
103
|
+
For the stable release, use a chosen, stable user-owned prefix:
|
|
100
104
|
|
|
101
105
|
```sh
|
|
102
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
106
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
|
|
103
107
|
```
|
|
104
108
|
|
|
105
109
|
The package root is
|
|
@@ -111,17 +115,17 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
|
111
115
|
cd agent-guard
|
|
112
116
|
```
|
|
113
117
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
[
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
[setup and the agent setup prompt](docs/guides/getting-started.md).
|
|
118
|
+
To select the published prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3`.
|
|
119
|
+
The [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
|
|
120
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
|
|
121
|
+
identify that package. For only the stable-line quarantine protection fix,
|
|
122
|
+
select `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` explicitly. Neither channel
|
|
123
|
+
replaces stable `latest`.
|
|
121
124
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
+
Version 0.2.5 combines RC1–RC3 with clearer startup, command and storage
|
|
126
|
+
feedback. A reviewed local checkout or supplied tarball is also usable. See
|
|
127
|
+
[release notes](docs/releases/release-notes-0.2.5.md) and
|
|
128
|
+
[setup and the agent setup prompt](docs/guides/getting-started.md).
|
|
125
129
|
|
|
126
130
|
## Recover a supported deletion
|
|
127
131
|
|
|
@@ -131,7 +135,7 @@ From the workspace being protected, point at your package/checkout root:
|
|
|
131
135
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
|
|
132
136
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
133
137
|
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>
|
|
138
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
135
139
|
```
|
|
136
140
|
|
|
137
141
|
Valuable targets are relocated with exact recovery paths in a manifest.
|
|
@@ -141,6 +145,11 @@ untracked/ignored content are refused. Force restore preserves the current
|
|
|
141
145
|
occupant before replacement. Errors can leave partial work: inspect the
|
|
142
146
|
reported transaction IDs, filesystem and state before retrying.
|
|
143
147
|
|
|
148
|
+
Version 0.2.5 makes these results explicit:
|
|
149
|
+
quarantined data still occupies storage, GC is manual, and `ALLOW_NOOP`
|
|
150
|
+
does not certify unrecognized command effects. Local status does not prove
|
|
151
|
+
that a host loaded the guard. See [status and cleanup feedback](docs/guides/recovery-feedback.md).
|
|
152
|
+
|
|
144
153
|
Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
|
|
145
154
|
may write quarantine/audit metadata and a Git local exclude entry. Advisory
|
|
146
155
|
exit 0 is not permission to execute a BLOCK or ASK.
|
|
@@ -148,8 +157,9 @@ See the [policy and assessment contract](skills/delete-guard/references/policy.m
|
|
|
148
157
|
|
|
149
158
|
RC1 added quarantine control-path protection, excluded PURGED transactions
|
|
150
159
|
from active GC planning, and minimized restore/safe_delete audit fields.
|
|
151
|
-
Exact CLI/manifest recovery paths remain available.
|
|
152
|
-
|
|
160
|
+
Exact CLI/manifest recovery paths remain available. The original 0.2.4 package
|
|
161
|
+
lacks these changes; 0.2.4-hotfix.1 backports only quarantine control-path
|
|
162
|
+
protection. See the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
|
|
153
163
|
|
|
154
164
|
RC2 introduced shared audit metadata projection,
|
|
155
165
|
uses opaque session correlation, and limits legacy status/GC metadata.
|
|
@@ -234,7 +244,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
|
|
|
234
244
|
| [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
|
|
235
245
|
| [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
|
|
236
246
|
| [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
|
|
237
|
-
| [0.2.5
|
|
247
|
+
| [0.2.5 notes](docs/releases/release-notes-0.2.5.md) | Release scope, upgrade impact and validation boundaries |
|
|
238
248
|
|
|
239
249
|
## Contributing
|
|
240
250
|
|
package/README.zh-CN.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](docs/releases/release-notes-0.2.5.md)
|
|
8
8
|
|
|
9
9
|
**让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
|
|
10
10
|
|
|
@@ -56,13 +56,13 @@ harness/版本/模型、任务、协议及非防护配置。结果只覆盖
|
|
|
56
56
|
[DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
|
|
57
57
|
失败和待审状态。
|
|
58
58
|
|
|
59
|
-
RC3
|
|
59
|
+
自 RC3 起,包中包含[蓝队研究](docs/research/README.md)、
|
|
60
60
|
[去敏实验报告](docs/reports/blue-team-lab-2026-10.md)和
|
|
61
61
|
[便携四控制示例](docs/lab/blue-team-calibration.md),公开来源、发送授权和正常任务效用的
|
|
62
62
|
有界研究。私有装配中的验证不扩展生产 hook 覆盖。Lab 将缓慢、小规模推进,欢迎 fork、PR
|
|
63
63
|
与独立防守复现;失败和未定结果也应保留。
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
在包含该示例的源码或包根目录,可一次运行现有四种控制:
|
|
66
66
|
|
|
67
67
|
```sh
|
|
68
68
|
blue_run="$(mktemp -d)"
|
|
@@ -78,15 +78,19 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
|
|
|
78
78
|
|
|
79
79
|
| 版本 | 状态 |
|
|
80
80
|
|---|---|
|
|
81
|
-
| [0.2.
|
|
82
|
-
| [0.2.
|
|
83
|
-
| [0.2.
|
|
84
|
-
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) |
|
|
81
|
+
| [0.2.5](docs/releases/release-notes-0.2.5.md) | 正式版;npm `latest`;实际可用性见下方版本化回执 |
|
|
82
|
+
| [0.2.4](docs/releases/release-notes-0.2.4.md) | 上一稳定版 |
|
|
83
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
|
|
84
|
+
| [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
|
|
85
|
+
实际发布状态以精确版本的
|
|
86
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)和
|
|
87
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)为准,
|
|
88
|
+
checkout 或 manifest 本身不代表包已可安装。
|
|
85
89
|
|
|
86
90
|
稳定包可安装到用户选定的长期目录:
|
|
87
91
|
|
|
88
92
|
```sh
|
|
89
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
93
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
|
|
90
94
|
```
|
|
91
95
|
|
|
92
96
|
包根目录是
|
|
@@ -98,14 +102,16 @@ git clone https://github.com/mokuyoaxis/agent-guard.git
|
|
|
98
102
|
cd agent-guard
|
|
99
103
|
```
|
|
100
104
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
105
|
+
选用已发布的预发布版时,指定 `@mokuyoaxis/agent-guard@0.2.5-rc3`,对应
|
|
106
|
+
[GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)与
|
|
107
|
+
[npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)。
|
|
108
|
+
若只需要稳定线的回收站保护修复,可显式选择 `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`。
|
|
109
|
+
这两个通道均不替换稳定版 `latest`。
|
|
106
110
|
|
|
107
|
-
|
|
108
|
-
|
|
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)。
|
|
109
115
|
|
|
110
116
|
## 恢复一次受支持的删除
|
|
111
117
|
|
|
@@ -115,7 +121,7 @@ RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定
|
|
|
115
121
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
|
|
116
122
|
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
117
123
|
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>
|
|
124
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
119
125
|
```
|
|
120
126
|
|
|
121
127
|
有价值的目标迁入隔离区,manifest 保留准确恢复路径。可证明能够再生成且被
|
|
@@ -124,13 +130,18 @@ hard reset 与 untracked/ignored 内容发生碰撞时拒绝执行。force res
|
|
|
124
130
|
先保全当前占位版本,再恢复旧版本。错误可能留下部分操作,应先核查返回的
|
|
125
131
|
事务 ID、现场文件和状态,再决定后续动作。
|
|
126
132
|
|
|
133
|
+
0.2.5 明确提示:迁入回收站的数据仍占空间,
|
|
134
|
+
GC 需要显式执行,`ALLOW_NOOP` 不代表未识别命令没有破坏性。
|
|
135
|
+
本地状态查询也不能证明宿主已加载防护。见[状态与清理反馈](docs/guides/recovery-feedback.md)。
|
|
136
|
+
|
|
127
137
|
advisory `check.py` 和 `safe_delete.py --dry-run` 保持命令目标不变,但可能写入
|
|
128
138
|
隔离区/审计元数据及 Git 本地 exclude。advisory 退出码 0 不代表 BLOCK/ASK
|
|
129
139
|
操作获准执行。详见[策略与评估契约](skills/delete-guard/references/policy.md)。
|
|
130
140
|
|
|
131
141
|
RC1 已增加隔离区控制路径保护、从活跃 GC 计划排除 PURGED 事务,并最小化
|
|
132
142
|
restore/safe_delete 审计字段;CLI/manifest 仍保留准确恢复路径。
|
|
133
|
-
|
|
143
|
+
原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。
|
|
144
|
+
见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
|
|
134
145
|
|
|
135
146
|
RC2 进一步限定通用审计字段、使用不透明 session 关联,
|
|
136
147
|
并收口旧日志 status 展示与 GC 元信息,见[审计契约及保留边界](docs/guides/audit-metadata.md)。
|
|
@@ -204,7 +215,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
|
|
|
204
215
|
| [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
|
|
205
216
|
| [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
|
|
206
217
|
| [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
|
|
207
|
-
| [0.2.5
|
|
218
|
+
| [0.2.5 说明](docs/releases/release-notes-0.2.5.md) | 发布范围、升级影响与验证边界 |
|
|
208
219
|
|
|
209
220
|
## 参与贡献
|
|
210
221
|
|
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
|
|
13
|
-
|
|
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
|
|
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.
|
package/adapters/dsh/README.md
CHANGED
|
@@ -18,12 +18,12 @@ retains the earlier failures and correction history.
|
|
|
18
18
|
|
|
19
19
|
## Install
|
|
20
20
|
|
|
21
|
-
The [0.2.
|
|
22
|
-
|
|
23
|
-
coverage. Install the exact version:
|
|
21
|
+
The [0.2.5 release](../../docs/releases/release-notes-0.2.5.md) includes the
|
|
22
|
+
startup/status diagnostics below without broadening admitted DSH versions or
|
|
23
|
+
native-read coverage. Install the exact stable version:
|
|
24
24
|
|
|
25
25
|
```bash
|
|
26
|
-
dsh plugin --profile
|
|
26
|
+
dsh plugin --profile 'your-profile' add @mokuyoaxis/agent-guard@0.2.5
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
Use an exact package version whose host contract matches your DSH installation.
|
|
@@ -31,17 +31,50 @@ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
|
|
|
31
31
|
Git must already be available. Installation does not enable the optional
|
|
32
32
|
text-read guard.
|
|
33
33
|
|
|
34
|
+
As checked on 2026-10-19, the published opt-in versions are
|
|
35
|
+
`@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
|
|
36
|
+
`@mokuyoaxis/agent-guard@0.2.5-rc3` for the cumulative prerelease.
|
|
37
|
+
Versioned [GitHub](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
|
|
38
|
+
and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
|
|
39
|
+
receipts establish 0.2.5 availability. A reviewed checkout or tarball is also
|
|
40
|
+
usable as described in [getting started](../../docs/guides/getting-started.md).
|
|
41
|
+
|
|
34
42
|
## What gets registered
|
|
35
43
|
|
|
36
44
|
| Contribution | Mechanism | Behavior |
|
|
37
45
|
|---|---|---|
|
|
38
|
-
| Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first;
|
|
46
|
+
| Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; permitted calls proceed after any required compensation, ASK uses the host approval path or denies when unavailable, BLOCK denies with explanation and remediation |
|
|
39
47
|
| `agent_guard_safe_delete` | model tool | recoverable delete with explicit glob expansion and manifest |
|
|
40
48
|
| `agent_guard_restore` | model tool | list / non-overwriting restore of quarantine transactions; forced overwrite remains human-only CLI functionality |
|
|
41
|
-
| `agent_guard_status` | model tool | mode, usage, retention view, recent decisions |
|
|
49
|
+
| `agent_guard_status` | model tool | adapter diagnostics, mode, usage, retention view, GC commands and recent decisions; no live-host certification |
|
|
42
50
|
| Prompt section | system prompt (order 105) | deletion discipline for the model |
|
|
43
51
|
| Experimental text `read` redaction | opt-in `tools/post-execute` value replacement | shared Core scans a complete read and DSH regenerates content and presentation metadata; unsupported or unscannable results are withheld |
|
|
44
52
|
|
|
53
|
+
## Startup and status diagnostics
|
|
54
|
+
|
|
55
|
+
Version 0.2.5 runs `python3 check.py --help`
|
|
56
|
+
before contributing the Hook/tools. This tests Python and imports in the
|
|
57
|
+
plugin process, without assessing a command or writing guard metadata.
|
|
58
|
+
Missing dependencies or a failed/timed-out startup check produce an explicit
|
|
59
|
+
initialization error instead of a log-only disabled adapter. The local check
|
|
60
|
+
has a 10-second timeout; the existing command-check timeout remains unchanged.
|
|
61
|
+
|
|
62
|
+
Startup success says that the listener was registered, while live host
|
|
63
|
+
interception remains `UNVERIFIED`. `agent_guard_status.adapter` reports that
|
|
64
|
+
distinction and the most recent checker result. It does not turn a local
|
|
65
|
+
Python test into a check of every shell/sandbox environment. If the plugin
|
|
66
|
+
never loads, its tools may be absent: inspect the host's plugin activation
|
|
67
|
+
status. An initialization error does not stop the host's other tools.
|
|
68
|
+
|
|
69
|
+
Checker process errors, timeout and unusable output remain denials with
|
|
70
|
+
static diagnostics separate from policy refusals. Relocation results state
|
|
71
|
+
that data still occupies storage; status includes accurate GC commands.
|
|
72
|
+
Status-query timeout, unsuccessful exit and unusable reports return `ok: false`
|
|
73
|
+
with a `STATUS_*` diagnostic and adapter facts, without changing the last
|
|
74
|
+
command-checker result. Partial relocation failures retain their recovery IDs
|
|
75
|
+
and storage guidance when files have moved.
|
|
76
|
+
See [status and cleanup feedback](../../docs/guides/recovery-feedback.md).
|
|
77
|
+
|
|
45
78
|
## Configuration (cordis.patch.yml row)
|
|
46
79
|
|
|
47
80
|
| Key | Default | Meaning |
|
|
@@ -27,8 +27,12 @@
|
|
|
27
27
|
|
|
28
28
|
import fs from "node:fs";
|
|
29
29
|
import path from "node:path";
|
|
30
|
+
import { execFile } from "node:child_process";
|
|
31
|
+
import { promisify } from "node:util";
|
|
30
32
|
import { fileURLToPath } from "node:url";
|
|
31
33
|
|
|
34
|
+
const runFile = promisify(execFile);
|
|
35
|
+
|
|
32
36
|
export const name = "agent_guard";
|
|
33
37
|
|
|
34
38
|
/** Services that must resolve before apply() runs. */
|
|
@@ -217,7 +221,13 @@ function dialectSelector(args, config, env) {
|
|
|
217
221
|
function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
218
222
|
const repoRoot = config.repoRoot || PACKAGE_ROOT;
|
|
219
223
|
const scriptsDir = path.join(repoRoot, "skills", "delete-guard", "scripts");
|
|
220
|
-
const
|
|
224
|
+
const diagnostics = {
|
|
225
|
+
startup_check: "NOT_RUN",
|
|
226
|
+
startup_scope: "plugin_process",
|
|
227
|
+
hook_registered: false,
|
|
228
|
+
last_checker_result: "NOT_RUN",
|
|
229
|
+
host_interception: "UNVERIFIED",
|
|
230
|
+
};
|
|
221
231
|
|
|
222
232
|
// The caller's sandbox policy travels with the session so guard
|
|
223
233
|
// invocations inherit exactly what the calling agent already has.
|
|
@@ -277,7 +287,7 @@ function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
|
277
287
|
systemPrompt,
|
|
278
288
|
repoRoot,
|
|
279
289
|
scriptsDir,
|
|
280
|
-
|
|
290
|
+
diagnostics,
|
|
281
291
|
shQuote,
|
|
282
292
|
runScript,
|
|
283
293
|
outText,
|
|
@@ -288,21 +298,37 @@ function buildRuntime(ctx, config, shell, systemPrompt) {
|
|
|
288
298
|
// Async functions cannot be mistaken for constructor plugins by Cordis.
|
|
289
299
|
// The host must await optional read-guard startup before admitting work.
|
|
290
300
|
export async function apply(ctx, config) {
|
|
301
|
+
function refuseStartup(detail) {
|
|
302
|
+
const code = config.readResultGuard ? "READ_GUARD_STARTUP_REFUSED" : "GUARD_STARTUP_FAILED";
|
|
303
|
+
throw new Error(`[agent-guard] ${code}: ${detail} No guard hook or tools were registered. Other host tools may still run.`);
|
|
304
|
+
}
|
|
291
305
|
const shell = ctx.get ? ctx.get("shell") : undefined;
|
|
292
306
|
if (shell === undefined) {
|
|
293
|
-
|
|
294
|
-
console.error("[agent-guard] shell service unavailable; adapter disabled");
|
|
295
|
-
return;
|
|
307
|
+
refuseStartup("The shell service is unavailable.");
|
|
296
308
|
}
|
|
297
309
|
const systemPrompt = ctx.get ? ctx.get("systemPrompt") : undefined;
|
|
298
310
|
const rt = buildRuntime(ctx, config, shell, systemPrompt);
|
|
299
311
|
|
|
300
|
-
if (!rt.
|
|
301
|
-
|
|
302
|
-
console.error("[agent-guard] check.py not found under", rt.repoRoot);
|
|
303
|
-
return;
|
|
312
|
+
if (!fs.existsSync(path.join(rt.scriptsDir, "check.py"))) {
|
|
313
|
+
refuseStartup("check.py was not found. Check the package or repoRoot setting.");
|
|
304
314
|
}
|
|
305
315
|
|
|
316
|
+
// --help loads Python and the checker imports without assessing a command
|
|
317
|
+
// or writing guard metadata. This checks the plugin process environment;
|
|
318
|
+
// the caller's shell/sandbox environment is only exercised by actual tools.
|
|
319
|
+
try {
|
|
320
|
+
await runFile("python3", [path.join(rt.scriptsDir, "check.py"), "--help"], {
|
|
321
|
+
timeout: 10000,
|
|
322
|
+
maxBuffer: 65536,
|
|
323
|
+
});
|
|
324
|
+
} catch (error) {
|
|
325
|
+
refuseStartup(error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" ?
|
|
326
|
+
"The local checker startup check exceeded its output limit. Check the package and checker entry point." :
|
|
327
|
+
error.killed ? "The local checker startup check timed out." :
|
|
328
|
+
"The local Python checker could not run. Check python3 on the plugin process PATH and the checker imports.");
|
|
329
|
+
}
|
|
330
|
+
rt.diagnostics.startup_check = "PASSED";
|
|
331
|
+
|
|
306
332
|
if (config.readResultGuard) {
|
|
307
333
|
return import("./read_result_guard.js").then(async ({ installReadResultGuard }) => {
|
|
308
334
|
await installReadResultGuard(ctx, config, rt.repoRoot);
|
|
@@ -319,6 +345,13 @@ function contribute(ctx, config, rt) {
|
|
|
319
345
|
ctx.effect(() => {
|
|
320
346
|
const disposers = [];
|
|
321
347
|
|
|
348
|
+
function checkerFailure(code, detail) {
|
|
349
|
+
rt.diagnostics.last_checker_result = code;
|
|
350
|
+
const reason = `[agent-guard] ${code}: ${detail} Command denied (fail-closed).`;
|
|
351
|
+
console.error(reason);
|
|
352
|
+
return { kind: "deny", reason };
|
|
353
|
+
}
|
|
354
|
+
|
|
322
355
|
// ---- 1) interception -------------------------------------------------
|
|
323
356
|
disposers.push(
|
|
324
357
|
ctx.on("tools/pre-execute", async (exec, next) => {
|
|
@@ -352,20 +385,23 @@ function contribute(ctx, config, rt) {
|
|
|
352
385
|
exec
|
|
353
386
|
);
|
|
354
387
|
} catch (_err) {
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
388
|
+
return checkerFailure("CHECKER_EXECUTION_FAILED",
|
|
389
|
+
"The checker could not start or finish. Check Python and the caller's shell environment; inspect recovery state before retrying.");
|
|
390
|
+
}
|
|
391
|
+
if (result.timedOut) {
|
|
392
|
+
return checkerFailure("CHECKER_TIMEOUT",
|
|
393
|
+
"The checker timed out. Inspect recovery state before retrying.");
|
|
394
|
+
}
|
|
395
|
+
if (![0, 2, 3].includes(result.exitCode)) {
|
|
396
|
+
return checkerFailure("CHECKER_PROCESS_FAILED",
|
|
397
|
+
"The checker did not complete with a supported exit status. Check the Python runtime and recovery state.");
|
|
360
398
|
}
|
|
361
399
|
const verdict = rt.parseJson(rt.outText(result.stdout));
|
|
362
|
-
if (!verdict || !verdict.decision) {
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
kind: "deny",
|
|
366
|
-
reason: "[agent-guard] unparseable guard output (fail-closed)",
|
|
367
|
-
};
|
|
400
|
+
if (!verdict || !["ALLOW", "ASK", "BLOCK"].includes(verdict.decision)) {
|
|
401
|
+
return checkerFailure("CHECKER_INVALID_OUTPUT",
|
|
402
|
+
"The checker returned no usable decision. Check the package and recovery state.");
|
|
368
403
|
}
|
|
404
|
+
rt.diagnostics.last_checker_result = "OK";
|
|
369
405
|
if (verdict.decision === "ALLOW") {
|
|
370
406
|
const comps = verdict.compensations || [];
|
|
371
407
|
if (comps.length > 0) {
|
|
@@ -375,6 +411,8 @@ function contribute(ctx, config, rt) {
|
|
|
375
411
|
"check_id=" + (verdict.check_id || "unknown")
|
|
376
412
|
);
|
|
377
413
|
}
|
|
414
|
+
if (verdict.storage_notice) console.log("[agent-guard]", verdict.storage_notice,
|
|
415
|
+
"Use agent_guard_status for usage and GC commands.");
|
|
378
416
|
return next();
|
|
379
417
|
}
|
|
380
418
|
const reasons = Array.isArray(verdict.reasons)
|
|
@@ -403,11 +441,22 @@ function contribute(ctx, config, rt) {
|
|
|
403
441
|
};
|
|
404
442
|
})
|
|
405
443
|
);
|
|
444
|
+
rt.diagnostics.hook_registered = true;
|
|
406
445
|
|
|
407
446
|
// ---- 2) model tools --------------------------------------------------
|
|
408
447
|
function renderJson(_args, value) {
|
|
448
|
+
// Keep diagnostics and storage guidance visible before long target/audit
|
|
449
|
+
// arrays consume the existing model-facing preview budget.
|
|
450
|
+
const display = {
|
|
451
|
+
...(value.adapter ? { adapter: value.adapter } : {}),
|
|
452
|
+
...(value.report?.storage_notice ? {
|
|
453
|
+
storage_notice: value.report.storage_notice,
|
|
454
|
+
gc: value.report.gc,
|
|
455
|
+
} : {}),
|
|
456
|
+
...value,
|
|
457
|
+
};
|
|
409
458
|
return [
|
|
410
|
-
{ type: "text", text: JSON.stringify(
|
|
459
|
+
{ type: "text", text: JSON.stringify(display, null, 2).slice(0, 4000) },
|
|
411
460
|
];
|
|
412
461
|
}
|
|
413
462
|
|
|
@@ -417,6 +466,24 @@ function contribute(ctx, config, rt) {
|
|
|
417
466
|
"Working directory (repo root) for this operation; defaults to the session workspace.",
|
|
418
467
|
};
|
|
419
468
|
|
|
469
|
+
function adapterStatus() {
|
|
470
|
+
return {
|
|
471
|
+
...rt.diagnostics,
|
|
472
|
+
note: "Startup checks the plugin process Python only. Hook registration and a local status result do not verify live host interception or every shell environment.",
|
|
473
|
+
};
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
function statusFailure(diagnostic, detail, exitCode = null) {
|
|
477
|
+
return {
|
|
478
|
+
ok: false,
|
|
479
|
+
exitCode,
|
|
480
|
+
report: null,
|
|
481
|
+
diagnostic,
|
|
482
|
+
stderr: detail,
|
|
483
|
+
adapter: adapterStatus(),
|
|
484
|
+
};
|
|
485
|
+
}
|
|
486
|
+
|
|
420
487
|
function makeTool(name, description, parameterSpec, buildArgs) {
|
|
421
488
|
return {
|
|
422
489
|
name,
|
|
@@ -429,19 +496,44 @@ function contribute(ctx, config, rt) {
|
|
|
429
496
|
execute: async (args, exec) => {
|
|
430
497
|
assertToolArgs(name, parameterSpec, args);
|
|
431
498
|
const plan = buildArgs(args);
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
499
|
+
let result;
|
|
500
|
+
try {
|
|
501
|
+
result = await rt.runScript(
|
|
502
|
+
plan.script,
|
|
503
|
+
plan.argString,
|
|
504
|
+
plan.workdir,
|
|
505
|
+
120000,
|
|
506
|
+
exec
|
|
507
|
+
);
|
|
508
|
+
} catch (error) {
|
|
509
|
+
if (name !== "agent_guard_status") throw error;
|
|
510
|
+
return statusFailure("STATUS_EXECUTION_FAILED",
|
|
511
|
+
"Status could not run in the caller's shell environment. Check Python and the package; adapter diagnostics below remain available.");
|
|
512
|
+
}
|
|
439
513
|
const parsed = rt.parseJson(rt.outText(result.stdout));
|
|
514
|
+
if (name === "agent_guard_status") {
|
|
515
|
+
if (result.timedOut) {
|
|
516
|
+
return statusFailure("STATUS_TIMEOUT",
|
|
517
|
+
"Status timed out. No recovery report is available; inspect the workspace before retrying.", result.exitCode);
|
|
518
|
+
}
|
|
519
|
+
if (result.exitCode !== 0) {
|
|
520
|
+
return statusFailure("STATUS_PROCESS_FAILED",
|
|
521
|
+
"Status exited unsuccessfully. Check Python, the package and recovery data.", result.exitCode);
|
|
522
|
+
}
|
|
523
|
+
if (typeof parsed?.workspace !== "string" || typeof parsed?.mode !== "string" ||
|
|
524
|
+
!Number.isFinite(parsed?.usage?.bytes)) {
|
|
525
|
+
return statusFailure("STATUS_INVALID_OUTPUT",
|
|
526
|
+
"Status returned no usable recovery report. Check the package and caller's shell environment.", result.exitCode);
|
|
527
|
+
}
|
|
528
|
+
}
|
|
440
529
|
return {
|
|
441
530
|
ok: result.exitCode === 0,
|
|
442
531
|
exitCode: result.exitCode,
|
|
443
532
|
report: parsed === undefined ? rt.outText(result.stdout) : parsed,
|
|
444
533
|
stderr: rt.outText(result.stderr).slice(0, 2000),
|
|
534
|
+
...(name === "agent_guard_status" ? {
|
|
535
|
+
adapter: adapterStatus(),
|
|
536
|
+
} : {}),
|
|
445
537
|
};
|
|
446
538
|
},
|
|
447
539
|
};
|
|
@@ -451,7 +543,7 @@ function contribute(ctx, config, rt) {
|
|
|
451
543
|
ctx.tools.register(
|
|
452
544
|
makeTool(
|
|
453
545
|
"agent_guard_status",
|
|
454
|
-
"Show
|
|
546
|
+
"Show adapter diagnostics, recovery mode, quarantine usage and GC commands. Local status does not verify live host interception.",
|
|
455
547
|
{ cwd: CWD_PROP },
|
|
456
548
|
(args) => ({ script: "status.py", argString: "--json", workdir: args.cwd })
|
|
457
549
|
)
|
|
@@ -461,7 +553,7 @@ function contribute(ctx, config, rt) {
|
|
|
461
553
|
ctx.tools.register(
|
|
462
554
|
makeTool(
|
|
463
555
|
"agent_guard_safe_delete",
|
|
464
|
-
"
|
|
556
|
+
"Delete with the existing recovery policy: valuable targets go to quarantine and still use disk space; eligible generated artifacts may be deleted directly. Accepts paths and globs.",
|
|
465
557
|
{
|
|
466
558
|
paths: {
|
|
467
559
|
type: "array",
|
|
@@ -512,22 +604,24 @@ function contribute(ctx, config, rt) {
|
|
|
512
604
|
text: [
|
|
513
605
|
"## Deletion discipline (agent-guard)",
|
|
514
606
|
"",
|
|
515
|
-
"
|
|
607
|
+
"Agent Guard checks supported destructive-looking Bash commands and provides recovery tools. Other tools and scripts may be outside its coverage.",
|
|
516
608
|
"",
|
|
517
|
-
"- To delete files/directories/globs, prefer
|
|
609
|
+
"- To delete files/directories/globs, prefer agent_guard_safe_delete. Valuable targets move to quarantine and still use disk space; eligible generated artifacts may be deleted directly. Pass cwd for the intended repo. Status includes GC planning and explicit purge commands.",
|
|
518
610
|
"- Raw rm / git clean / git reset --hard are intercepted before execution. Most are compensated automatically (relocate or snapshot) and simply proceed; note the txid.",
|
|
519
611
|
"- Shape rules: a command line that cds before deleting (COMPOUND_CWD_DELETE), or creates files and then deletes them (COMPOUND_CREATE_DELETE), triggers a single-execution user authorization. Splitting the deletion into its own standalone command avoids the prompt entirely.",
|
|
520
612
|
"- True effect-uncertainty ($VAR targets, bash -c, find -delete, xargs-fed lists) stays hard-BLOCKED: restating with explicit concrete paths is the only remedy.",
|
|
521
613
|
"- BLOCK_OUT_OF_WORKSPACE, BLOCK_PROTECTED_PATH (.git, workspace root) and BLOCK_FORCE_PUSH are policy violations and never askable: do not retry variants; ask the human if truly needed.",
|
|
522
614
|
"- In RESTRICTED mode only explicit single-file deletes inside the workspace are permitted; only a human can restore NORMAL.",
|
|
523
|
-
"- Never circumvent the guard (no /bin/rm, python os.unlink, node fs.rmSync, relocated scripts).
|
|
615
|
+
"- Never circumvent the guard (no /bin/rm, python os.unlink, node fs.rmSync, relocated scripts). Calls outside the covered path may have no recovery or audit record.",
|
|
524
616
|
"- Undo with agent_guard_restore(txid). Inspect state with agent_guard_status().",
|
|
525
617
|
].join("\n"),
|
|
526
618
|
})
|
|
527
619
|
);
|
|
528
620
|
}
|
|
529
621
|
|
|
622
|
+
console.log("[agent-guard] Hook registered; local Python checker passed. Live host interception is unverified. Inspect agent_guard_status for diagnostics.");
|
|
530
623
|
return () => {
|
|
624
|
+
rt.diagnostics.hook_registered = false;
|
|
531
625
|
while (disposers.length) {
|
|
532
626
|
const d = disposers.pop();
|
|
533
627
|
try {
|