@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 CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm stable](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![0.2.5-rc3 candidate](https://img.shields.io/badge/RC-0.2.5--rc3-5B6B7A)](docs/releases/release-notes-0.2.5-rc3.md)
7
+ [![0.2.5](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -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 adds [blue-team research](docs/research/README.md), a
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 the RC3 checkout or review package, run all four existing controls:
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.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
95
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Previous published prerelease baseline |
96
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | Maintenance prerelease; check the exact publication receipts |
97
- | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Research/documentation source preview; package publication requires separate receipts |
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 published stable package, use a chosen, stable user-owned prefix:
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.4
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
- For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly; the RC
115
- channel does not replace stable `latest`. Check the
116
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
117
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
118
- for publication. A reviewed checkout or supplied tarball is also usable;
119
- the manifest alone does not establish registry availability. See
120
- [setup and the agent setup prompt](docs/guides/getting-started.md).
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
- Evaluate RC3 through a reviewed source checkout or supplied tarball. Its
123
- manifest and a main-branch commit do not establish a registry release;
124
- version tags and GitHub/npm package publication are separate steps.
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. These changes are not in
152
- the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
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-rc3 notes](docs/releases/release-notes-0.2.5-rc3.md) | Current source candidate's scope and validation status |
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
  [![npm 稳定版](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![0.2.5-rc3 候选](https://img.shields.io/badge/RC-0.2.5--rc3-5B6B7A)](docs/releases/release-notes-0.2.5-rc3.md)
7
+ [![0.2.5](https://img.shields.io/badge/release-0.2.5-5B6B7A)](docs/releases/release-notes-0.2.5.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -56,13 +56,13 @@ harness/版本/模型、任务、协议及非防护配置。结果只覆盖
56
56
  [DSH](docs/reports/test-report-dsh-guard-lab.md) 报告保留各自的有限结论、
57
57
  失败和待审状态。
58
58
 
59
- RC3 新增[蓝队研究](docs/research/README.md)、
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
- 在 RC3 源码或评审包根目录,可一次运行现有四种控制:
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.4](docs/releases/release-notes-0.2.4.md) | 已发布的稳定基线 |
82
- | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | 已发布的历史预发布基线 |
83
- | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | 维护预发布;以准确版本的发布回执为准 |
84
- | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 研究/文档源码预览;包发布以独立回执为准 |
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.4
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
- RC2 显式选择 `@mokuyoaxis/agent-guard@0.2.5-rc2`;RC 通道不替换稳定版 `latest`。
102
- 发布状态以 [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
103
- 和 [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)为准,
104
- 也可使用已核查的 checkout 或提供的 tarball;manifest 版本不代表 registry 已可安装。
105
- 接入步骤与 Agent 提示词见[入门指南](docs/guides/getting-started.md)。
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
- 通过已核查源码 checkout 或提供的 tarball 评估 RC3;manifest 或 main 提交不代表 registry 已发布。
108
- 版本标签与 GitHub/npm 包发布分别执行。
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
- 这些维护不属于已发布的 0.2.4 包,见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
143
+ 原始 0.2.4 包不含这些维护;0.2.4-hotfix.1 仅回补回收站控制路径保护。
144
+ 见 [RC 说明](docs/releases/release-notes-0.2.5-rc1.md)。
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-rc3 说明](docs/releases/release-notes-0.2.5-rc3.md) | 当前源码候选范围与验收状态 |
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 makes destructive actions reversible by
13
- default and records evidence. It is **not a security sandbox** - an agent
12
+ Reliability infrastructure: it provides recovery for supported destructive
13
+ actions and records evidence under the documented audit contracts. It is
14
+ **not a security sandbox** - an agent
14
15
  with the same OS privileges as the guard can bypass it. See
15
16
  [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
16
17
 
@@ -49,7 +50,8 @@ from local command checks and require a selected experiment scope.
49
50
 
50
51
  Recovery manifests, CLI diagnostics and historical audit records can contain
51
52
  exact paths or other private text. Writer minimization introduced in RC1 and
52
- the shared projection introduced in RC2 remain in RC3; they do not make every
53
+ the shared projection introduced in RC2 remain in 0.2.5;
54
+ they do not make every
53
55
  output or old record secret-free. The exfil text
54
56
  CLIs return decisions/plans or sanitized stdout; they do not automatically
55
57
  persist egress audit events. Review and redact evidence before sharing it.
@@ -18,12 +18,12 @@ retains the earlier failures and correction history.
18
18
 
19
19
  ## Install
20
20
 
21
- The [0.2.4 release](../../docs/releases/release-notes-0.2.4.md) updates the shared
22
- Core and docs without broadening the admitted DSH versions or native-read
23
- coverage. Install the exact version:
21
+ The [0.2.5 release](../../docs/releases/release-notes-0.2.5.md) includes the
22
+ startup/status diagnostics below without broadening admitted DSH versions or
23
+ native-read coverage. Install the exact stable version:
24
24
 
25
25
  ```bash
26
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
26
+ dsh plugin --profile 'your-profile' add @mokuyoaxis/agent-guard@0.2.5
27
27
  ```
28
28
 
29
29
  Use an exact package version whose host contract matches your DSH installation.
@@ -31,17 +31,50 @@ The package ships prebuilt JavaScript and its Python Core; Python 3.9+ and
31
31
  Git must already be available. Installation does not enable the optional
32
32
  text-read guard.
33
33
 
34
+ As checked on 2026-10-19, the published opt-in versions are
35
+ `@mokuyoaxis/agent-guard@0.2.4-hotfix.1` for the stable-line quarantine fix and
36
+ `@mokuyoaxis/agent-guard@0.2.5-rc3` for the cumulative prerelease.
37
+ Versioned [GitHub](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
38
+ and [npm](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
39
+ receipts establish 0.2.5 availability. A reviewed checkout or tarball is also
40
+ usable as described in [getting started](../../docs/guides/getting-started.md).
41
+
34
42
  ## What gets registered
35
43
 
36
44
  | Contribution | Mechanism | Behavior |
37
45
  |---|---|---|
38
- | Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; ALLOW proceeds (compensation applied), ASK escalates once to the human, BLOCK denies with explanation and remediation |
46
+ | Interception | `tools/pre-execute` waterfall | destructive-looking bash runs through `check.py --enforce` first; permitted calls proceed after any required compensation, ASK uses the host approval path or denies when unavailable, BLOCK denies with explanation and remediation |
39
47
  | `agent_guard_safe_delete` | model tool | recoverable delete with explicit glob expansion and manifest |
40
48
  | `agent_guard_restore` | model tool | list / non-overwriting restore of quarantine transactions; forced overwrite remains human-only CLI functionality |
41
- | `agent_guard_status` | model tool | mode, usage, retention view, recent decisions |
49
+ | `agent_guard_status` | model tool | adapter diagnostics, mode, usage, retention view, GC commands and recent decisions; no live-host certification |
42
50
  | Prompt section | system prompt (order 105) | deletion discipline for the model |
43
51
  | Experimental text `read` redaction | opt-in `tools/post-execute` value replacement | shared Core scans a complete read and DSH regenerates content and presentation metadata; unsupported or unscannable results are withheld |
44
52
 
53
+ ## Startup and status diagnostics
54
+
55
+ Version 0.2.5 runs `python3 check.py --help`
56
+ before contributing the Hook/tools. This tests Python and imports in the
57
+ plugin process, without assessing a command or writing guard metadata.
58
+ Missing dependencies or a failed/timed-out startup check produce an explicit
59
+ initialization error instead of a log-only disabled adapter. The local check
60
+ has a 10-second timeout; the existing command-check timeout remains unchanged.
61
+
62
+ Startup success says that the listener was registered, while live host
63
+ interception remains `UNVERIFIED`. `agent_guard_status.adapter` reports that
64
+ distinction and the most recent checker result. It does not turn a local
65
+ Python test into a check of every shell/sandbox environment. If the plugin
66
+ never loads, its tools may be absent: inspect the host's plugin activation
67
+ status. An initialization error does not stop the host's other tools.
68
+
69
+ Checker process errors, timeout and unusable output remain denials with
70
+ static diagnostics separate from policy refusals. Relocation results state
71
+ that data still occupies storage; status includes accurate GC commands.
72
+ Status-query timeout, unsuccessful exit and unusable reports return `ok: false`
73
+ with a `STATUS_*` diagnostic and adapter facts, without changing the last
74
+ command-checker result. Partial relocation failures retain their recovery IDs
75
+ and storage guidance when files have moved.
76
+ See [status and cleanup feedback](../../docs/guides/recovery-feedback.md).
77
+
45
78
  ## Configuration (cordis.patch.yml row)
46
79
 
47
80
  | Key | Default | Meaning |
@@ -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 pythonReady = fs.existsSync(path.join(scriptsDir, "check.py"));
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
- pythonReady,
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
- if (config.readResultGuard) throw new Error("[agent-guard] READ_GUARD_STARTUP_REFUSED");
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.pythonReady) {
301
- if (config.readResultGuard) throw new Error("[agent-guard] READ_GUARD_STARTUP_REFUSED");
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
- console.error("[agent-guard] check.py infrastructure error");
356
- return {
357
- kind: "deny",
358
- reason: "[agent-guard] guard infrastructure error (fail-closed)",
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
- console.error("[agent-guard] unparseable guard output");
364
- return {
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(value, null, 2).slice(0, 4000) },
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
- const result = await rt.runScript(
433
- plan.script,
434
- plan.argString,
435
- plan.workdir,
436
- 120000,
437
- exec
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 agent-guard state: authorization mode, quarantine usage, retention/GC view, recent decisions.",
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
- "Recoverable delete: globs expanded explicitly, targets quarantined to .agent-trash/ with a manifest. Preferred over raw rm.",
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
- "This workspace runs agent-guard: an automatic recovery system with human escalation - not an approval system. Irreversible destruction is not a default capability.",
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 the agent_guard_safe_delete tool: targets are quarantined under .agent-trash/ with a manifest and stay restorable. Pass cwd when operating in a repo below the workspace root.",
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). Every decision is audit-logged; circumvention is a violation.",
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 {