@mokuyoaxis/agent-guard 0.2.6 → 0.2.8
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 +45 -20
- package/README.zh-CN.md +39 -19
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/doctor.py +325 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +35 -14
- package/docs/design/architecture.md +42 -16
- package/docs/design/compatibility.md +246 -7
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +26 -12
- package/docs/guides/harness-capabilities.md +29 -4
- package/docs/guides/mcp.md +420 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +182 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +3 -1
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- package/skills/delete-guard/scripts/status.py +77 -1
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# 0.2.7 — Cleanup, deletion limits and local MCP
|
|
2
|
+
|
|
3
|
+
Version 0.2.7 adds Cleanup plans, shared deletion admission and optional local
|
|
4
|
+
MCP tools to [0.2.6](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/releases/release-notes-0.2.6.md).
|
|
5
|
+
Use the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
|
|
6
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
|
|
7
|
+
to verify availability before installing; a manifest, checkout or local
|
|
8
|
+
tarball alone does not establish publication. This version leaves the
|
|
9
|
+
existing `rc` and `hotfix` channels unchanged. The separate 0.3.0 plan remains
|
|
10
|
+
paused. Local preparation evidence below is dated 2026-10-29.
|
|
11
|
+
|
|
12
|
+
本版收录 Cleanup Copilot、删除准入加固和可选本地 MCP 工具。新增预算与保护
|
|
13
|
+
可能拒绝此前可执行的删除。安装前请确认精确版本的发行与包页面可用;下方
|
|
14
|
+
版本化测试、打包与发布门记录单独保留,不能沿用旧 0.2.6 元数据工件的结论。
|
|
15
|
+
|
|
16
|
+
<a id="candidate-scope"></a>
|
|
17
|
+
|
|
18
|
+
## Version scope
|
|
19
|
+
|
|
20
|
+
### Cleanup Copilot
|
|
21
|
+
|
|
22
|
+
`agent-guard-cleanup` proposes workspace candidates with logical sizes,
|
|
23
|
+
reasons and projected effects in four categories: regenerable, explicitly
|
|
24
|
+
caller-declared discarded, uncertain and protected. Age, ignore status or
|
|
25
|
+
being untracked alone does not make a file disposable.
|
|
26
|
+
|
|
27
|
+
Default planning writes no workspace files, guard metadata or audit records.
|
|
28
|
+
Execution requires an unchanged reviewed plan, explicit selection and terminal
|
|
29
|
+
`EXECUTE` confirmation, then delegates to the existing safe_delete path.
|
|
30
|
+
Valuable files retain recovery copies and disk use; only provably regenerable
|
|
31
|
+
artifacts follow the existing physical-delete rules. See
|
|
32
|
+
[the workflow and limits](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/cleanup-plan.md).
|
|
33
|
+
|
|
34
|
+
### Shared deletion admission
|
|
35
|
+
|
|
36
|
+
Optional `.agent-guard/delete-policy.json` supplies protected paths and limits.
|
|
37
|
+
Missing configuration uses defaults; malformed configuration or unusable
|
|
38
|
+
admission state refuses covered execution instead of silently disabling it.
|
|
39
|
+
The configuration directory and admission control files are protected.
|
|
40
|
+
|
|
41
|
+
| Default | Value |
|
|
42
|
+
|---|---|
|
|
43
|
+
| Quarantine admission ceiling | 5 GiB / 100000 entries |
|
|
44
|
+
| Cumulative session budget | 1 GiB / 10000 entries |
|
|
45
|
+
| Rolling rate | 60 admissions per 60 seconds |
|
|
46
|
+
| Repeated normalized target set | 5 admissions per window |
|
|
47
|
+
| Batch review threshold | Above 256 MiB or 1000 entries |
|
|
48
|
+
|
|
49
|
+
Measurement, durable debit and guarded mutation share a cross-process lock.
|
|
50
|
+
Unnamed CLI processes use a stable shared budget; failures and later restores
|
|
51
|
+
do not refund admitted bytes/entries. Rate windows expire, while cumulative
|
|
52
|
+
budgets require explicit operator action. A repeated-target-set stop is a
|
|
53
|
+
simple loop signal, not a general anomaly detector.
|
|
54
|
+
|
|
55
|
+
Large covered automated deletions return `BLOCK_DELETE_BATCH_CONFIRM` with
|
|
56
|
+
Cleanup guidance. The shell checker combines supported rm/artifact/Git-clean
|
|
57
|
+
targets across a request before its first compensation. Cleanup confirmation
|
|
58
|
+
creates a ten-minute session/configuration/path/metadata-bound approval,
|
|
59
|
+
consumed once per selected path; it lifts only the batch gate, not protection,
|
|
60
|
+
capacity, budget or rate limits.
|
|
61
|
+
|
|
62
|
+
The additive refusal codes are:
|
|
63
|
+
|
|
64
|
+
- `BLOCK_DELETE_CONFIG_INVALID`
|
|
65
|
+
- `BLOCK_DELETE_PROTECTED`
|
|
66
|
+
- `BLOCK_DELETE_LIMIT`
|
|
67
|
+
- `BLOCK_DELETE_RATE`
|
|
68
|
+
- `BLOCK_DELETE_REPEAT`
|
|
69
|
+
- `BLOCK_DELETE_BATCH_CONFIRM`
|
|
70
|
+
- `BLOCK_DELETE_STATE_INVALID`
|
|
71
|
+
|
|
72
|
+
Existing Decision classes, check.py exit roles and recovery-manifest formats
|
|
73
|
+
retain their contracts. No data/configuration migration or automatic GC is
|
|
74
|
+
introduced. See [defaults, accounting and operator recovery](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/deletion-limits.md)
|
|
75
|
+
and the [compatibility contract](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/design/compatibility.md) for the bounded
|
|
76
|
+
maintainer decision to select 0.2.7 for these additions.
|
|
77
|
+
|
|
78
|
+
### Optional local MCP tools
|
|
79
|
+
|
|
80
|
+
`agent-guard-mcp` exposes safe_delete, ordinary restore, transactions, status
|
|
81
|
+
and GC-plan preview over local stdio. Workspace, local quarantine and stable
|
|
82
|
+
session identity are fixed at trusted startup. Tools cannot supply a new
|
|
83
|
+
workspace/session/environment, force restore, GC execution, budget reset or
|
|
84
|
+
Cleanup approval. Quarantine targets are refused by MCP safe_delete to avoid
|
|
85
|
+
a permanent-GC shortcut.
|
|
86
|
+
|
|
87
|
+
The official MIT-licensed `mcp==2.3.0` SDK is installed separately in an
|
|
88
|
+
optional Python 3.10+ environment. Core/CLI still requires Python 3.9+ and Git
|
|
89
|
+
without third-party Python packages; npm does not install the SDK. No server
|
|
90
|
+
network listener is provided. Follow the [MCP setup guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/guides/mcp.md).
|
|
91
|
+
|
|
92
|
+
MCP is an explicit cooperative tool interface. It does not intercept shell,
|
|
93
|
+
script or editor operations that bypass it. Startup session selection chooses
|
|
94
|
+
the existing CLI authorization mode as well as budget. It does not inherit
|
|
95
|
+
native host restrictions or an in-memory veto without trusted bridging.
|
|
96
|
+
|
|
97
|
+
## Upgrade and operator notes
|
|
98
|
+
|
|
99
|
+
- Covered automated filesystem compensation, regenerable direct deletion,
|
|
100
|
+
Git-clean compensation and force-restore occupant preservation can newly
|
|
101
|
+
refuse work when limits are reached. An earlier advisory assessment is not
|
|
102
|
+
a capacity grant. A later refusal can follow completed earlier operations;
|
|
103
|
+
inspect returned transaction IDs and the filesystem.
|
|
104
|
+
- Normal restore remains available without a fresh deletion debit. Explicit
|
|
105
|
+
transaction GC and existing unprotected quarantine housekeeping retain
|
|
106
|
+
their exemptions; configuration/control-path protection still precedes
|
|
107
|
+
housekeeping. The existing GC CLI's `--execute` does not require a TTY;
|
|
108
|
+
MCP's preview-only scope does not change that separate interface.
|
|
109
|
+
- Existing compound-command ASK and Git reset/restore/checkout SNAPSHOT paths
|
|
110
|
+
are outside these new admission counters. Git stash storage can still grow.
|
|
111
|
+
Do not describe this release as a limit on every destructive operation.
|
|
112
|
+
- `status.py --reset-delete-budget` requires an interactive terminal and
|
|
113
|
+
`RESET`, after investigation. It resets only the selected bucket and its
|
|
114
|
+
approvals, without deleting recovery copies or altering capacity/limits.
|
|
115
|
+
Agents must not change identity, remove state or manufacture confirmation
|
|
116
|
+
to bypass a refusal.
|
|
117
|
+
- Accounting uses bounded logical lstat inventory, including directory and
|
|
118
|
+
symlink metadata and conservative per-entry hardlink counts. It is not an
|
|
119
|
+
OS disk quota. Audit/manifest metadata and unrelated writers can still grow
|
|
120
|
+
storage; scan/state bounds may refuse before a larger configured limit.
|
|
121
|
+
- Package/Core changes affect doctor fingerprints. An old baseline may become
|
|
122
|
+
`DRIFTED`; it is not silently replaced, and a new local baseline does not
|
|
123
|
+
prove native-hook interception or model receipt of feedback.
|
|
124
|
+
|
|
125
|
+
Existing installations require an explicit upgrade to acquire these additions.
|
|
126
|
+
Installing a separate copy does not upgrade another existing installation;
|
|
127
|
+
host configuration and hook activation remain separate steps.
|
|
128
|
+
Same-UID, concurrency and uncovered-tool
|
|
129
|
+
limitations remain in the [threat model](https://github.com/mokuyoaxis/agent-guard/blob/0.2.7/docs/design/threat-model.md).
|
|
130
|
+
|
|
131
|
+
<a id="evaluate-the-unpublished-candidate"></a>
|
|
132
|
+
|
|
133
|
+
## Install or evaluate version 0.2.7
|
|
134
|
+
|
|
135
|
+
After confirming that the exact version is available on both publication
|
|
136
|
+
pages above, install it into a chosen, stable prefix:
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
For source review or before publication is available, use a reviewed checkout
|
|
143
|
+
or a tarball produced and checked from that exact source. An already-built
|
|
144
|
+
local tarball can be installed into a disposable prefix:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund \
|
|
148
|
+
--prefix /absolute/path/to/agent-guard-review \
|
|
149
|
+
/absolute/path/to/mokuyoaxis-agent-guard-0.2.7.tgz
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The optional MCP SDK remains a separate installation. Compare the selected
|
|
153
|
+
package with the release artifact checksum; local packaging and the version
|
|
154
|
+
string alone do not establish registry availability.
|
|
155
|
+
|
|
156
|
+
## Validation status
|
|
157
|
+
|
|
158
|
+
**Local 0.2.7-versioned validation passed on 2026-10-29.** The explicit
|
|
159
|
+
219-file public candidate excluded private experiments. All 1129 Python cases
|
|
160
|
+
and both Node groups passed in 1194.265 seconds, with no failures, errors,
|
|
161
|
+
skips, timeouts or automatic retries. The existing diagnostic collector kept
|
|
162
|
+
`npm test`'s scope and original deadlines; npm itself was not invoked.
|
|
163
|
+
|
|
164
|
+
The 155-file 0.2.7 package passed offline installation, all 12 CLI entry-point
|
|
165
|
+
checks and actual installed stdio deletion, restoration, persistent-budget,
|
|
166
|
+
protection and batch-gate checks. MCP `serverInfo.version` matched package
|
|
167
|
+
version `0.2.7`; read-only tools left the workspace unchanged and forbidden
|
|
168
|
+
override/force/reset/GC-execute arguments were refused. A separate final
|
|
169
|
+
package consistency check verifies documentation-only updates against the
|
|
170
|
+
tested runtime and the final source.
|
|
171
|
+
|
|
172
|
+
Six release-gate tests executed the workflow's actual SDK preflight body:
|
|
173
|
+
missing/wrong/broken SDK and disabled/skipped/empty protocol suites were
|
|
174
|
+
refused. The same body also passed against the existing isolated SDK. The tag
|
|
175
|
+
workflow now installs that pinned SDK and requires enabled protocol coverage
|
|
176
|
+
before its unchanged `npm test` step. These are the **2026-10-29 local
|
|
177
|
+
preparation results**: they did not include final-commit remote CI or
|
|
178
|
+
publication checks and made no new real-model requests. Published artifact
|
|
179
|
+
and workflow results must be checked through the exact version links above.
|
|
180
|
+
|
|
181
|
+
Earlier local source evidence is retained with its original checkpoint:
|
|
182
|
+
|
|
183
|
+
| Checkpoint | Observed result |
|
|
184
|
+
|---|---|
|
|
185
|
+
| Cleanup-only | 1012 Python cases and both Node groups passed continuously in 979.997 seconds; 37 Cleanup/9 manifest checks and a 146-file offline package also passed |
|
|
186
|
+
| Deletion hardening | Three independent runs each passed 1090 Python cases and both Node groups in 1061.017 / 1025.315 / 1042.145 seconds; a 149-file offline package and three real Kimi root-Bash scenarios passed |
|
|
187
|
+
| MCP source, first full run | 1123 Python cases, one observer READY-startup error, no skips; 1156.312 seconds; Node did not start |
|
|
188
|
+
| Same MCP source, second full run | 1123 Python cases and both Node groups passed in 1143.435 seconds, without failures, errors, skips, timeouts or automatic retries |
|
|
189
|
+
| MCP source packaging | 154 files / 12 CLI checks, local offline installation and actual installed stdio deletion/recovery/budget/protection checks passed |
|
|
190
|
+
|
|
191
|
+
These source/package checks used 0.2.6 package metadata before selecting
|
|
192
|
+
version 0.2.7. They are not acceptance of a renamed 0.2.7 tarball. The first MCP
|
|
193
|
+
run's observer error remains unresolved; the unchanged case passed separate
|
|
194
|
+
SDK/system-Python checks in 4.409 / 2.979 seconds. The successful second run
|
|
195
|
+
does not establish a general timeout fix. Both full runs used the existing
|
|
196
|
+
diagnostic result collector with npm test's scope and original deadlines,
|
|
197
|
+
without invoking npm itself.
|
|
198
|
+
|
|
199
|
+
At the earlier 0.2.6-metadata MCP checkpoint, three real Kimi Code 2.3.0
|
|
200
|
+
root-agent native MCP trials passed: normal
|
|
201
|
+
deletion/model-driven restore (27.288 seconds), same-session budget refusal
|
|
202
|
+
and model-driven restore (26.121 seconds), and configured protection
|
|
203
|
+
(16.814 seconds). All 19 configured-route requests returned HTTP 200;
|
|
204
|
+
16 model-generated MCP calls matched native stdio requests, without Bash,
|
|
205
|
+
fixed replies, automatic trial retries or route changes. Restored bytes and
|
|
206
|
+
user configuration/auth fingerprints matched; restored budget remained
|
|
207
|
+
charged. The existing loopback gateway's server-side model identity was not
|
|
208
|
+
independently authenticated.
|
|
209
|
+
|
|
210
|
+
Local evidence is ARM64/PRoot POSIX, Python 3.13.5 and Node 22.23.4.
|
|
211
|
+
Without the optional SDK, seven real-stdio protocol cases skip; the local
|
|
212
|
+
0.2.7 full run included that SDK, and the release gate refuses skipped
|
|
213
|
+
protocol coverage. New SDK-backed CI declarations are not
|
|
214
|
+
remote-CI results. Protocol evidence exercised the classic 2025-06-18
|
|
215
|
+
handshake, not every extension/client version. Claude/Cursor/Codex examples
|
|
216
|
+
are documentation guidance; no new live-client, subagent, native Windows,
|
|
217
|
+
macOS or shared-Android-storage acceptance is claimed.
|
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
# 0.2.8 — MCP diagnosis and recovery validation
|
|
2
|
+
|
|
3
|
+
Version 0.2.8 adds MCP connection diagnosis, real protocol-interruption
|
|
4
|
+
checks and documentation to the
|
|
5
|
+
[0.2.7](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/releases/release-notes-0.2.7.md)
|
|
6
|
+
baseline. Use the exact
|
|
7
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
8
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
9
|
+
to verify availability before installing; a source version or local tarball
|
|
10
|
+
alone does not establish publication. The separate `rc` and `hotfix` channels
|
|
11
|
+
retain their versions.
|
|
12
|
+
|
|
13
|
+
本版提供 MCP 接入诊断与恢复验证。安装前核实精确版本的发行与包页面。已有 0.2.7 的测试、宿主实测
|
|
14
|
+
和发布记录保留各自版本边界,不能直接作为 0.2.8 候选的通过证据。
|
|
15
|
+
|
|
16
|
+
## Version scope
|
|
17
|
+
|
|
18
|
+
### Explicit MCP doctor
|
|
19
|
+
|
|
20
|
+
`agent-guard-doctor mcp` checks a selected local service through the existing
|
|
21
|
+
stdio interface. It checks the interpreter and optional pinned MCP SDK,
|
|
22
|
+
SDK imports, service handshake and package-matching version, the expected
|
|
23
|
+
five tools and query annotations, workspace/quarantine binding, and successful
|
|
24
|
+
`status`, `transactions` and `gc_plan` calls.
|
|
25
|
+
|
|
26
|
+
From this checkout or a package built from it:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
30
|
+
--python /absolute/path/to/agent-guard-mcp-venv/bin/python \
|
|
31
|
+
--workspace /absolute/path/to/your-project --json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
`--python` defaults to the doctor interpreter. `--server` optionally selects
|
|
35
|
+
another reviewed script, otherwise the package's own adapter is used.
|
|
36
|
+
`--timeout` defaults to 30 seconds and accepts 5–120 for diagnostic checks;
|
|
37
|
+
service-process shutdown can add up to three seconds of process waits and one second
|
|
38
|
+
of reader-thread waiting. The doctor starts these
|
|
39
|
+
trusted executable inputs without a shell; it neither installs dependencies
|
|
40
|
+
nor discovers or rewrites client configuration.
|
|
41
|
+
|
|
42
|
+
The independent `schema_version: 1` report contains fixed diagnostic status,
|
|
43
|
+
stage/code, message, guidance and checks. It does not expose raw child stderr,
|
|
44
|
+
configuration/authentication contents or recovery/audit records. Exit `0`
|
|
45
|
+
means PASS, `1` means diagnostic failure and `2` means invalid CLI usage.
|
|
46
|
+
These codes do not extend the Decision Protocol reason-code namespace.
|
|
47
|
+
The existing Kimi/Claude doctor paths retain their interfaces.
|
|
48
|
+
`diagnostic_stderr_bytes` exposes a byte count only. The report can show
|
|
49
|
+
`deletion_admission: BLOCKED` while connection checks pass; `READABLE` means
|
|
50
|
+
admission information was inspected, not that future deletion is approved.
|
|
51
|
+
|
|
52
|
+
A PASS covers direct checks of the selected service. `host_connection`,
|
|
53
|
+
`model_delivery` and `host_interception` stay `UNVERIFIED`; actual host loading
|
|
54
|
+
and model use require separate acceptance. No model, deletion, restore, GC
|
|
55
|
+
execution, policy modification or budget reset is performed by the doctor.
|
|
56
|
+
See the [MCP guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#diagnose-a-local-service-028).
|
|
57
|
+
|
|
58
|
+
### Recovery after response loss
|
|
59
|
+
|
|
60
|
+
The protocol checks target a client deadline, cancellation notification,
|
|
61
|
+
stdin EOF and service termination at a controlled barrier after safe_delete
|
|
62
|
+
has committed but before a response is sent. They inspect files, recovery
|
|
63
|
+
transactions, persistent accounting and ordinary restoration on reconnect.
|
|
64
|
+
This checks a specific response-loss boundary, not arbitrary partial
|
|
65
|
+
multi-file interruption or atomic rollback.
|
|
66
|
+
|
|
67
|
+
After an uncertain mutation, inspect status, transactions and the source/
|
|
68
|
+
recovery copy before another mutation. Reconnect with the same trusted
|
|
69
|
+
workspace/quarantine/session identity. Restoration does not refund the
|
|
70
|
+
deletion budget. See [interrupted-connection recovery](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#after-a-lost-response-or-interrupted-connection).
|
|
71
|
+
|
|
72
|
+
### Documentation and existing Codex evidence
|
|
73
|
+
|
|
74
|
+
The MCP guide now distinguishes direct-service diagnosis, live-client
|
|
75
|
+
acceptance and actual model calls. It includes the separate 2026-10-29
|
|
76
|
+
Codex CLI 0.165.0 acceptance of the published **0.2.7** package: three
|
|
77
|
+
native-client groups and three real-model tasks, totaling 16 model MCP calls.
|
|
78
|
+
That exact-version result covers the cooperative MCP path, not native Shell/
|
|
79
|
+
editor interception or the 0.2.8 candidate. Original failures and evidence
|
|
80
|
+
limitations remain in the [recorded validation](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/guides/mcp.md#recorded-validation-and-remaining-limits).
|
|
81
|
+
|
|
82
|
+
## Compatibility and upgrade notes
|
|
83
|
+
|
|
84
|
+
The maintainer selected 0.2.8 for these bounded diagnosis/reliability additions.
|
|
85
|
+
Earlier doctor drift/live-sentinel additions were classified as minor. This
|
|
86
|
+
release's independent diagnostic surface is explicitly recorded as a
|
|
87
|
+
maintenance-version decision; the 0.2.7 exception is not inherited and does
|
|
88
|
+
not permit unrelated policy changes. See the
|
|
89
|
+
[compatibility decision](https://github.com/mokuyoaxis/agent-guard/blob/0.2.8/docs/design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
90
|
+
|
|
91
|
+
The five MCP tools and their arguments, Decision classes/reasons, default
|
|
92
|
+
deletion rules, recovery manifests, persistent budget and preview-only MCP
|
|
93
|
+
GC retain their contracts. There is no storage/configuration migration or
|
|
94
|
+
automatic client setup. The pinned `mcp==2.3.0` SDK remains an optional
|
|
95
|
+
separate-environment dependency; Core/CLI still needs Python 3.9+ and Git
|
|
96
|
+
without third-party Python packages. MCP requires a compatible Python 3.10+
|
|
97
|
+
SDK environment.
|
|
98
|
+
|
|
99
|
+
Package/helper changes can make an older doctor fingerprint baseline
|
|
100
|
+
`DRIFTED`; it is not silently replaced. Existing installations require an
|
|
101
|
+
explicit upgrade to gain the new doctor path. Same-UID, concurrency and
|
|
102
|
+
uncovered-tool boundaries retain their existing scope. Configuration
|
|
103
|
+
diagnosis prototypes, new deletion permissions, automatic GC, 0.3.0 work
|
|
104
|
+
and commercial capabilities are outside this release.
|
|
105
|
+
|
|
106
|
+
## Install or evaluate version 0.2.8
|
|
107
|
+
|
|
108
|
+
After confirming availability on both publication pages above, install into
|
|
109
|
+
a chosen stable prefix:
|
|
110
|
+
|
|
111
|
+
```sh
|
|
112
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
For source review or before registry availability, use reviewed source or a
|
|
116
|
+
verified local tarball in a separate prefix. The optional MCP SDK is still
|
|
117
|
+
installed separately; npm does not install it or configure host clients.
|
|
118
|
+
Existing installations require an explicit upgrade.
|
|
119
|
+
|
|
120
|
+
## Validation status
|
|
121
|
+
|
|
122
|
+
Local 0.2.8 candidate validation **passed** on 2026-11-06. Local checks used ARM64/PRoot,
|
|
123
|
+
Python 3.13.5, Node 22.23.4 and the separate pinned MCP SDK 2.3.0 environment.
|
|
124
|
+
|
|
125
|
+
| Check | Observed result |
|
|
126
|
+
|---|---|
|
|
127
|
+
| Focused MCP doctor | 16 cases passed in 40.956 seconds, including four real-SDK cases |
|
|
128
|
+
| Focused protocol interruption | Four cases passed in 44.090 seconds |
|
|
129
|
+
| First completed full regression | 1152 Python cases in 1620.567 seconds: no assertion failures, one error, no skips; Node groups were not started after Python failed |
|
|
130
|
+
| Independent check of the failed case | Passed in 10.802 seconds (11.301 seconds for the outer process); this does not replace the failed full run |
|
|
131
|
+
| Complete rerun of the same candidate | PASS: 1152 Python cases and both Node groups, no failures/errors/skips, 1719.330 seconds overall; all 224 frozen public files were unchanged |
|
|
132
|
+
| Local package | 157 files; offline installation, 12 CLI help checks, installed doctor and actual MCP deletion/restoration passed; restored bytes matched and budget remained charged |
|
|
133
|
+
|
|
134
|
+
The full-run error was a fresh server's initialization exceeding its existing
|
|
135
|
+
20-second wait in an interruption test. The same run's monitoring also had a
|
|
136
|
+
415.159-second heartbeat gap. The cause remains unknown; that observation is
|
|
137
|
+
not a proven explanation for the timeout. Runtime, assertions and deadlines
|
|
138
|
+
were not changed to make the independent check or complete rerun pass.
|
|
139
|
+
The passing rerun also recorded a separate 470.896-second monitoring gap,
|
|
140
|
+
without test errors. Neither the passing checks nor these timing observations
|
|
141
|
+
establish the cause of the earlier timeout.
|
|
142
|
+
|
|
143
|
+
The full rerun used the existing immediate-diagnostic unittest collector,
|
|
144
|
+
followed by the two Node groups, with the public `npm test` pipeline's scope
|
|
145
|
+
and unchanged per-test limits. It did not invoke npm directly. All 1152 test
|
|
146
|
+
start/finish records paired uniquely; the 1800-second overall deadline was
|
|
147
|
+
retained. The SDK-backed doctor and interruption tests actually executed.
|
|
148
|
+
|
|
149
|
+
An earlier full attempt was intentionally stopped to add explicit handling
|
|
150
|
+
and a regression for an empty `--python` argument; it is not a completed full
|
|
151
|
+
run. That additional regression later passed among the 17 doctor cases in
|
|
152
|
+
the completed Python suite above. It is not combined with the earlier
|
|
153
|
+
16-case focused run and reported as a single 17-case focused result.
|
|
154
|
+
|
|
155
|
+
Package checks compare runtime and test bytes with the frozen full-test
|
|
156
|
+
candidate and account for documentation-only updates separately. They include
|
|
157
|
+
offline packing/installation, member hashes, the installed doctor and actual
|
|
158
|
+
MCP recovery. Optional-SDK skips are not protocol acceptance; SDK-backed release
|
|
159
|
+
checks must exercise the real protocol cases.
|
|
160
|
+
|
|
161
|
+
The implementation commit `1323ca5` subsequently passed
|
|
162
|
+
[CI 42353094903](https://github.com/mokuyoaxis/agent-guard/actions/runs/42353094903)
|
|
163
|
+
on 2026-11-07: all 15 jobs succeeded, including the Linux/macOS Python
|
|
164
|
+
3.9–3.13 matrices, Windows Core, DSH checks and both SDK-backed MCP jobs.
|
|
165
|
+
This checkpoint precedes the documentation-only publication alignment;
|
|
166
|
+
the release commit requires its own CI and the tag's Release workflow.
|
|
167
|
+
Actual CI/release runs and package availability remain separately verifiable;
|
|
168
|
+
these local and implementation-CI records do not certify a later artifact.
|
|
169
|
+
No new real-model trial was performed for 0.2.8.
|
|
170
|
+
|
|
171
|
+
The preceding 0.2.7 artifact and Codex/Kimi records retain their original
|
|
172
|
+
versions and scope. They are not substituted for this candidate's results.
|
|
@@ -1,4 +1,179 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 0.2.8 and earlier maintenance history
|
|
2
|
+
|
|
3
|
+
<a id="028-development-and-earlier-maintenance-history"></a>
|
|
4
|
+
|
|
5
|
+
<a id="unreleased-changes-and-026-maintenance-history"></a>
|
|
6
|
+
<a id="027-candidate-changes-and-026-maintenance-history"></a>
|
|
7
|
+
|
|
8
|
+
<a id="mcp-diagnosis-and-reliability-maintenance-028-development"></a>
|
|
9
|
+
|
|
10
|
+
## MCP diagnosis and reliability maintenance (0.2.8)
|
|
11
|
+
|
|
12
|
+
The maintainer selected **0.2.8** for an explicit `doctor.py mcp` path,
|
|
13
|
+
real-protocol response-loss checks and documentation. Stable installation
|
|
14
|
+
examples select this exact version; confirm its GitHub release and npm
|
|
15
|
+
availability through the [version notes](release-notes-0.2.8.md). The local
|
|
16
|
+
validation and remote CI checkpoints are recorded separately.
|
|
17
|
+
|
|
18
|
+
The doctor checks a selected Python/optional SDK, service handshake and
|
|
19
|
+
version, the five-tool set, workspace binding and read-only queries. It does
|
|
20
|
+
not call a model, change host configuration or delete/restore files. Its
|
|
21
|
+
version-1 diagnosis and exit codes are separate from the existing
|
|
22
|
+
Kimi/Claude doctor and Decision Protocol surfaces. A direct-service PASS keeps
|
|
23
|
+
host connection, model delivery and interception `UNVERIFIED`.
|
|
24
|
+
|
|
25
|
+
The interruption work covers client deadline, cancellation, stdin EOF and
|
|
26
|
+
service termination after a real deletion has committed but before a reply.
|
|
27
|
+
Checks examine transaction recoverability and persistent budget, without
|
|
28
|
+
assuming that losing a response rolled back the operation. This does not
|
|
29
|
+
prove arbitrary multi-file interruption atomicity. A separate full rerun passed
|
|
30
|
+
1152 Python cases and both Node groups with no failures/errors/skips; local
|
|
31
|
+
157-file package checks passed. The earlier full-run initialization timeout
|
|
32
|
+
and its unresolved cause remain recorded in the
|
|
33
|
+
[0.2.8 notes](release-notes-0.2.8.md#validation-status).
|
|
34
|
+
|
|
35
|
+
The five tools, default deletion policy, recovery format and budget semantics
|
|
36
|
+
retain their contracts. The SDK stays separately optional; the separate
|
|
37
|
+
0.3.0 and commercial plans remain paused. See the
|
|
38
|
+
[MCP diagnosis and interruption guide](../guides/mcp.md#diagnose-a-local-service-028)
|
|
39
|
+
and this release's [bounded compatibility decision](../design/compatibility.md#028-diagnosis-maintenance-decision).
|
|
40
|
+
|
|
41
|
+
The guide also records later Codex 0.165.0 acceptance of the published 0.2.7
|
|
42
|
+
package: three native-client groups and three real-model tasks with 16 MCP
|
|
43
|
+
calls. That exact-version cooperative-MCP evidence is not 0.2.8 acceptance or
|
|
44
|
+
native-shell interception evidence. Earlier checkpoints below keep their
|
|
45
|
+
original versions, results and failure history.
|
|
46
|
+
|
|
47
|
+
## 0.2.7 changes and 0.2.6 maintenance history
|
|
48
|
+
|
|
49
|
+
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
50
|
+
optional local MCP tools. Check its exact GitHub release and npm version
|
|
51
|
+
through the [version notes](release-notes-0.2.7.md) before installing; a source
|
|
52
|
+
version alone does not establish publication. This path is retained for
|
|
53
|
+
existing links. At the **2026-10-29 local preparation checkpoint**, versioned
|
|
54
|
+
validation passed:
|
|
55
|
+
1129 Python cases and both Node groups in 1194.265 seconds, with no failures,
|
|
56
|
+
errors, skips, timeouts or automatic retries, plus a 155-file offline package
|
|
57
|
+
and installed MCP identity/operation checks. The diagnostic collector kept
|
|
58
|
+
`npm test` scope/deadlines without invoking npm. Release SDK-gate fault checks
|
|
59
|
+
also passed; that checkpoint did not include final-commit remote CI or
|
|
60
|
+
publication. These results are separate from the historical checkpoints below; this preparation
|
|
61
|
+
made no new real-model requests. See
|
|
62
|
+
[version scope, upgrade effects and validation](release-notes-0.2.7.md).
|
|
63
|
+
The separate 0.3.0 plan remains paused.
|
|
64
|
+
|
|
65
|
+
<a id="local-mcp-tools-unreleased"></a>
|
|
66
|
+
<a id="local-mcp-tools-027-candidate"></a>
|
|
67
|
+
|
|
68
|
+
## Local MCP tools (0.2.7)
|
|
69
|
+
|
|
70
|
+
The checkout adds an optional local stdio server for explicit safe_delete,
|
|
71
|
+
ordinary restore, transaction/status queries and GC-plan preview. Workspace
|
|
72
|
+
and stable session identity are set at startup; tools cannot override them,
|
|
73
|
+
the environment or quarantine. Operations use the existing CLI without a
|
|
74
|
+
shell and retain deletion protection, budget, audit and recovery semantics.
|
|
75
|
+
Session selection chooses saved CLI authorization mode as well as budget;
|
|
76
|
+
without it, legacy CLI state and the shared default bucket apply. Reusing
|
|
77
|
+
state requires matching workspace/quarantine/session. Native host-session
|
|
78
|
+
restrictions or in-memory veto require trusted bridging and are not inherited
|
|
79
|
+
merely by registering this server.
|
|
80
|
+
No force restore, GC execution, budget reset or Cleanup approval is exposed;
|
|
81
|
+
safe-delete quarantine targets are also refused. The existing GC CLI remains
|
|
82
|
+
separate; preview-only MCP does not add a terminal requirement to that CLI.
|
|
83
|
+
|
|
84
|
+
The official MIT-licensed `mcp==2.3.0` SDK is an optional separate-environment
|
|
85
|
+
dependency, not a new Core/CLI requirement or automatic npm installation.
|
|
86
|
+
MCP tools do not replace native hooks or cover shell/script/editor actions
|
|
87
|
+
that bypass them. For the 2026-10-28 frozen candidate, the first full local
|
|
88
|
+
run finished 1123 Python cases with one observer READY-startup error in
|
|
89
|
+
1156.312 seconds; Node did not run. The original error remains unresolved.
|
|
90
|
+
The same case passed separate SDK/system-Python checks, and a second complete
|
|
91
|
+
run passed all 1123 Python cases and both Node groups in 1143.435 seconds,
|
|
92
|
+
without failures, errors, skips, timeouts, runtime changes or automatic retries.
|
|
93
|
+
The diagnostic collector preserved `npm test` scope/deadlines; npm itself was
|
|
94
|
+
not invoked. Default Core testing without the optional SDK skips seven
|
|
95
|
+
protocol cases; the two recorded full runs included it. An independent
|
|
96
|
+
SDK CI job is configured; the local preparation checkpoint included no
|
|
97
|
+
remote execution of that job.
|
|
98
|
+
|
|
99
|
+
The 154-file offline install/12 CLI checks and three real Kimi 2.3.0 native-MCP
|
|
100
|
+
trials passed: ordinary delete/restore, same-session budget and configured
|
|
101
|
+
protection. The model made 16 MCP calls across 19 real configured-route HTTP
|
|
102
|
+
200 requests, without Bash, fixed replies or route changes. Its gateway's
|
|
103
|
+
server-side model identity was not independently verified. Local evidence
|
|
104
|
+
covers ARM64/PRoot Python 3.13.5; there are no new Windows/macOS/shared-storage
|
|
105
|
+
or live Claude/Cursor/Codex tests. Their setup examples remain documentation
|
|
106
|
+
guidance. See [installation, failure history and limits](../guides/mcp.md).
|
|
107
|
+
Published 0.2.6 and its old evidence remain unchanged; 0.3.0 is still paused.
|
|
108
|
+
|
|
109
|
+
<a id="deletion-admission-hardening-unreleased"></a>
|
|
110
|
+
<a id="deletion-admission-hardening-027-candidate"></a>
|
|
111
|
+
|
|
112
|
+
## Deletion admission hardening (0.2.7)
|
|
113
|
+
|
|
114
|
+
The current checkout adds quarantine capacity admission, persistent session
|
|
115
|
+
byte/entry budgets, short-window rate and repeated-target-set limits, and
|
|
116
|
+
shared protected paths in optional `.agent-guard/delete-policy.json`.
|
|
117
|
+
Cross-process locking covers measurement, durable admission debit and the
|
|
118
|
+
guarded mutation. Failures and restores do not refund session budget; unnamed
|
|
119
|
+
CLI processes share a default bucket. Configuration/state failures block new
|
|
120
|
+
admission instead of silently disabling limits.
|
|
121
|
+
|
|
122
|
+
Large batches require Cleanup's existing terminal review, followed by a
|
|
123
|
+
ten-minute approval bound to paths, metadata, configuration and session and
|
|
124
|
+
consumed once per selected path. Covered automated large-delete checks BLOCK with
|
|
125
|
+
Cleanup guidance; no new host approval/resume protocol is added. Approval
|
|
126
|
+
does not bypass capacity, budgets or protection. Status adds explicit
|
|
127
|
+
terminal-confirmed reset of the current budget only.
|
|
128
|
+
Existing compound-command ASK and Git snapshots remain outside the new
|
|
129
|
+
budget; normal restore, explicit GC and unprotected quarantine housekeeping
|
|
130
|
+
remain exempt. Configuration/control-path protection still applies.
|
|
131
|
+
|
|
132
|
+
Accounting uses logical `lstat` sizes including directory metadata and
|
|
133
|
+
conservative per-entry hardlink counts, not physical disk quotas. Audits,
|
|
134
|
+
metadata and unrelated writers can still grow storage. GC remains explicit;
|
|
135
|
+
capacity refusal never downgrades to permanent deletion. See
|
|
136
|
+
[defaults, reason codes and recovery](../guides/deletion-limits.md).
|
|
137
|
+
|
|
138
|
+
The 2026-10-28 frozen public runtime passed three independent full runs,
|
|
139
|
+
each with 1090 Python cases and both Node groups: 1061.017, 1025.315 and
|
|
140
|
+
1042.145 seconds, with no failures, errors, skips, timeouts or automatic retries.
|
|
141
|
+
The existing diagnostic collector retained `npm test` scope/deadlines without
|
|
142
|
+
invoking npm itself. An offline 149-file package and three real Kimi 2.3.0
|
|
143
|
+
root-Bash cases passed; nine configured-route model requests returned HTTP 200.
|
|
144
|
+
See the guide for POSIX-only validation, gateway identity and host/tool limits.
|
|
145
|
+
The earlier unexplained npm timeout did not recur; its history is retained.
|
|
146
|
+
The Cleanup-only results below predate these changes. Those earlier checks
|
|
147
|
+
used 0.2.6 package metadata without claiming the additions shipped in that
|
|
148
|
+
release. Subsequent versioned 0.2.7 tests and package checks passed as recorded
|
|
149
|
+
above; the separate 0.3.0 plan remains paused.
|
|
150
|
+
|
|
151
|
+
<a id="cleanup-copilot-unreleased"></a>
|
|
152
|
+
<a id="cleanup-copilot-027-candidate"></a>
|
|
153
|
+
|
|
154
|
+
## Cleanup Copilot (0.2.7)
|
|
155
|
+
|
|
156
|
+
The current checkout adds a metadata-only cleanup plan and an explicitly
|
|
157
|
+
confirmed CLI execution workflow. It reports regenerable, caller-declared
|
|
158
|
+
discarded, uncertain and protected targets with logical sizes, reasons and
|
|
159
|
+
projected deletion/quarantine effects. Execution still uses safe_delete;
|
|
160
|
+
ordinary quarantined files retain disk usage. The default plan writes no
|
|
161
|
+
workspace or guard metadata. See [usage and limits](../guides/cleanup-plan.md).
|
|
162
|
+
|
|
163
|
+
This initial addition is separate from published 0.2.6 and is included in
|
|
164
|
+
version 0.2.7. At its initial checkpoint it added no native host tool or
|
|
165
|
+
deletion-policy change. Subsequent admission hardening is described above. At the Cleanup-only
|
|
166
|
+
checkpoint, the runtime passed a continuous local ARM64/PRoot POSIX rerun:
|
|
167
|
+
1012 Python cases and both Node groups in 979.997 seconds, with no failures,
|
|
168
|
+
errors, skips or retries. This used the existing diagnostic result collector
|
|
169
|
+
with the same test scope and deadlines as `npm test`. The earlier literal
|
|
170
|
+
npm command's timeout remains recorded and unexplained; it did not recur
|
|
171
|
+
in this rerun. Focused cleanup/manifest checks and an offline package also passed,
|
|
172
|
+
including terminal confirmation, physical deletion and quarantine/restore.
|
|
173
|
+
See the guide's [validation scope](../guides/cleanup-plan.md#validation-scope)
|
|
174
|
+
for the local platform and host limits.
|
|
175
|
+
|
|
176
|
+
## Maintenance delivered in 0.2.6 / 0.2.6 维护说明
|
|
2
177
|
|
|
3
178
|
Updated 2026-10-22. The additions previously tracked here now ship in
|
|
4
179
|
[0.2.6](release-notes-0.2.6.md). This path is retained for existing links and
|
|
@@ -126,16 +301,18 @@ commands; restoration and repeat-Stop checks passed. This does not establish
|
|
|
126
301
|
all-model, subagent, background or long-running behavior. The new DSH
|
|
127
302
|
diagnostic checks made no external model requests.
|
|
128
303
|
|
|
129
|
-
|
|
304
|
+
<a id="中文摘要"></a>
|
|
305
|
+
|
|
306
|
+
## 0.2.6 中文摘要
|
|
130
307
|
|
|
131
|
-
|
|
308
|
+
以下为 0.2.6 历史维护摘要:Kimi 可选 Stop 恢复反馈、120 秒外层超时接入说明,以及
|
|
132
309
|
DSH Lab 版本/配置预检的原因、退出码和计时诊断,及 Kimi Stop 的独立 doctor 检查。
|
|
133
310
|
后续默认删除适配加入 DSH `0.2.1-alpha.4`,读取脱敏/Lab 不随之扩大。
|
|
134
311
|
Kimi Bash profile 新增精确版本 2.3.0;CLI/ACP 各八项固定响应试次提供有限根代理证据,
|
|
135
312
|
未调用外部模型,也未扩大 Kimi Lab 的 2.1.1 准入或子代理声明。
|
|
136
313
|
Stop 未配置不报错;配置或本地探针失败退出 1,模型送达始终未验证。已发布 0.2.5 的范围保持原记录;
|
|
137
|
-
|
|
314
|
+
这些功能自 0.2.6 起提供,Stop 另需显式配置;原页面路径为已有链接保留。
|
|
138
315
|
|
|
139
316
|
版本/文档对齐前,最终实现检查点的 974 项 Python 与两组 Node 已在同一冻结流程通过;
|
|
140
317
|
此前 962 项检查点和历史失败分别保留,原失败原因仍未确定。
|
|
141
|
-
|
|
318
|
+
上述 0.2.6 维护未改变删除策略、rm 通配符规则、恢复格式或手动 GC。
|
|
@@ -97,7 +97,7 @@ The pinned `read` tool's presentation metadata contains the returned lines.
|
|
|
97
97
|
Replacing only `content` therefore leaves a second copy of read text in the
|
|
98
98
|
private session/UI data.
|
|
99
99
|
|
|
100
|
-
The [native probe](
|
|
100
|
+
The [native probe](https://github.com/mokuyoaxis/agent-guard/blob/e73101666288735880d4ff70bb0a20a025d426b0/tests/probes/dsh_result_hook.mjs) instantiates the real
|
|
101
101
|
Cordis, SystemPrompt and ToolRuntime services, registers synthetic tools and
|
|
102
102
|
tests their results without a model, shell, session or network request:
|
|
103
103
|
|
|
@@ -287,7 +287,7 @@ old direct-Python hook-startup failure demonstrates a concrete fail-open
|
|
|
287
287
|
boundary; the later bridge trial shows only a bounded mitigation.
|
|
288
288
|
The fixtures and traces were preserved for review. Adapter-level regressions
|
|
289
289
|
for both inert command shapes live in
|
|
290
|
-
[`tests/test_kimi_adapter.py`](
|
|
290
|
+
[`tests/test_kimi_adapter.py`](https://github.com/mokuyoaxis/agent-guard/blob/75b51b888279583541792e00b14a4ceaf2a59fba/tests/test_kimi_adapter.py).
|
|
291
291
|
|
|
292
292
|
After the live trials, the Kimi adapter was tightened to reject malformed
|
|
293
293
|
`PreToolUse` JSON and missing required Bash fields. Unit tests verify this
|