@mokuyoaxis/agent-guard 0.2.7 → 0.2.9
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/CONTRIBUTING.md +13 -0
- package/README.md +37 -27
- package/README.zh-CN.md +32 -24
- package/adapters/INTEGRATION.md +9 -3
- package/adapters/mcp/doctor.py +326 -0
- package/adapters/mcp/operations.py +33 -3
- package/adapters/mcp/server.py +17 -0
- package/core/cleanup.py +33 -11
- package/core/cleanup_groups.py +329 -0
- package/core/policy.py +20 -3
- package/docs/README.md +38 -13
- package/docs/design/architecture.md +63 -14
- package/docs/design/compatibility.md +121 -5
- package/docs/guides/cleanup-plan.md +97 -0
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +21 -4
- package/docs/guides/mcp.md +202 -11
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/release-notes-0.2.9.md +68 -0
- package/docs/releases/unreleased.md +198 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +27 -1
- package/skills/delete-guard/scripts/cleanup.py +48 -3
package/docs/README.md
CHANGED
|
@@ -1,16 +1,28 @@
|
|
|
1
1
|
# Documentation / 文档导航
|
|
2
2
|
|
|
3
3
|
Start with [getting started](guides/getting-started.md) for installation and
|
|
4
|
-
setup. The three main
|
|
5
|
-
|
|
6
|
-
[behaviour experiments](lab/guard-lab.md). Use the
|
|
4
|
+
setup. The three main capabilities are **Exfil-guard**, **Delete-guard** and
|
|
5
|
+
**Guard-lab**. Use the
|
|
7
6
|
[harness capability matrix](guides/harness-capabilities.md) for observed coverage
|
|
8
7
|
and the [architecture](design/architecture.md) for the shared Core.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
9
|
+
| Main capability / 主要功能 | Included functions and guides / 下属功能与指南 |
|
|
10
|
+
|---|---|
|
|
11
|
+
| **Exfil-guard** | [Text checks and redaction](../skills/exfil-guard/SKILL.md) · [Safe config view](../skills/exfil-guard/SKILL.md#safe-config-view) |
|
|
12
|
+
| **Delete-guard** | [Recoverable deletion](../skills/delete-guard/SKILL.md) · [Cleanup Copilot](guides/cleanup-plan.md) · [Deletion limits](guides/deletion-limits.md) · [Recovery and GC](guides/recovery-feedback.md) · [MCP tools](guides/mcp.md) · [MCP doctor (0.2.8)](guides/mcp.md#diagnose-a-local-service-028) |
|
|
13
|
+
| **Guard-lab** | [Controlled experiments and evidence](lab/guard-lab.md) · [Four zero-model controls](lab/blue-team-calibration.md) · [Defensive research](research/README.md) |
|
|
14
|
+
|
|
15
|
+
Cleanup Copilot, deletion admission and the current MCP tools/doctor are
|
|
16
|
+
Delete-guard functions. [Recovery-audit](../skills/recovery-audit/SKILL.md)
|
|
17
|
+
is an auxiliary incident-recovery workflow.
|
|
18
|
+
|
|
19
|
+
Version [0.2.9](releases/release-notes-0.2.9.md) adds read-only Cleanup
|
|
20
|
+
inventory and selected-scope measurement through CLI and MCP, faster plan
|
|
21
|
+
scans and a repository-corpus test fix. The earlier
|
|
22
|
+
[0.2.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and recovery validation.
|
|
23
|
+
Before installing 0.2.9,
|
|
24
|
+
check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
25
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
|
|
14
26
|
for availability. A checkout or manifest does not establish publication or
|
|
15
27
|
the current npm `latest` channel.
|
|
16
28
|
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
@@ -23,9 +35,15 @@ its doctor checks, Kimi 2.3.0 root-Bash compatibility, DSH Lab preflight
|
|
|
23
35
|
diagnostics and alpha.4 default deletion compatibility. Existing 0.2.5 installations
|
|
24
36
|
need an upgrade to acquire those additions; see its [version notes](releases/release-notes-0.2.6.md).
|
|
25
37
|
|
|
26
|
-
|
|
38
|
+
先看入门指南,再按 Exfil-guard、Delete-guard、Guard-lab 三大功能选择入口。
|
|
39
|
+
Cleanup、删除限制与当前 MCP 工具/doctor 归入 Delete-guard。测试报告按所测版本与配置保留;发布记录、
|
|
27
40
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
28
41
|
|
|
42
|
+
0.2.9 新增[目录概况与计量](guides/cleanup-plan.md#directory-overview-and-measurement-029)
|
|
43
|
+
及两个[只读 MCP 工具](guides/mcp.md#cleanup-observations-unreleased),仍归属 Cleanup Copilot;
|
|
44
|
+
0.2.8 不含这些新增能力。[变更摘要](releases/unreleased.md#current-unreleased-scope)
|
|
45
|
+
汇总当前范围与验证,历史失败和各版发行记录在其后保留。
|
|
46
|
+
|
|
29
47
|
| Category / 分类 | Contents / 内容 |
|
|
30
48
|
|---|---|
|
|
31
49
|
| [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
|
|
@@ -45,9 +63,12 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
45
63
|
|---|---|
|
|
46
64
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
47
65
|
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
48
|
-
| [Cleanup Copilot](guides/cleanup-plan.md) | 0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
49
|
-
| [
|
|
50
|
-
| [
|
|
66
|
+
| [Cleanup Copilot](guides/cleanup-plan.md) | Delete-guard,0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
67
|
+
| [Directory overview and measurement](guides/cleanup-plan.md#directory-overview-and-measurement-029) | Delete-guard,0.2.9:先概况、再按范围发现/计量;没有执行许可 |
|
|
68
|
+
| [Deletion limits](guides/deletion-limits.md) | Delete-guard,0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
|
|
69
|
+
| [Local MCP tools](guides/mcp.md) | Delete-guard,0.2.7:本地 stdio 安全删除、普通恢复、事务/状态和 GC 预览;不替代 hook |
|
|
70
|
+
| [Read-only cleanup MCP](guides/mcp.md#cleanup-observations-029) | Delete-guard,0.2.9:cleanup_discover/cleanup_measure、固定工作区与部分观察状态 |
|
|
71
|
+
| [MCP diagnosis](guides/mcp.md#diagnose-a-local-service-028) | Delete-guard,0.2.8:选定本地服务的依赖、握手、工作区绑定与只读调用检查 |
|
|
51
72
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
52
73
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
53
74
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
@@ -55,7 +76,9 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
55
76
|
| [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
|
|
56
77
|
|
|
57
78
|
Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
|
|
58
|
-
|
|
79
|
+
are documented separately for [Exfil-guard](../skills/exfil-guard/SKILL.md) and
|
|
80
|
+
[Delete-guard](../skills/delete-guard/SKILL.md); the [Guard-lab guide](lab/guard-lab.md)
|
|
81
|
+
describes the user-controlled experiment CLI.
|
|
59
82
|
|
|
60
83
|
We currently focus on DSH and Kimi Code. Claude Code's adapter and past
|
|
61
84
|
reports remain available; testing new Claude versions is paused. For other
|
|
@@ -125,9 +148,11 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
125
148
|
|
|
126
149
|
| Document / 文档 | Scope / 范围 |
|
|
127
150
|
|---|---|
|
|
151
|
+
| [0.2.9](releases/release-notes-0.2.9.md) | 目录概况/计量、两只读 MCP 工具、扫描提速与语料门修复 |
|
|
152
|
+
| [0.2.8](releases/release-notes-0.2.8.md) | MCP 接入诊断、真实协议中断验证、安装与验收边界 |
|
|
128
153
|
| [0.2.7](releases/release-notes-0.2.7.md) | Cleanup、删除准入与MCP的版本范围、升级影响和准备阶段验证 |
|
|
129
154
|
| [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
|
|
130
|
-
| [Changes and maintenance details](releases/unreleased.md) | 0.2.
|
|
155
|
+
| [Changes and maintenance details](releases/unreleased.md) | 0.2.9 范围与本地验证;其后保留0.2.8、0.2.7及更早维护历史 |
|
|
131
156
|
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
132
157
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
133
158
|
| [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
|
|
@@ -2,19 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
## Positioning
|
|
4
4
|
|
|
5
|
-
agent-guard is **Agent Reliability Infrastructure
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
`threat-model.md`).
|
|
5
|
+
agent-guard is **Agent Reliability Infrastructure** with three main
|
|
6
|
+
capabilities: Exfil-guard checks text for disclosure risks, Delete-guard
|
|
7
|
+
preserves recovery paths for supported destructive operations, and Guard-lab
|
|
8
|
+
provides controlled experiments with bounded evidence. The
|
|
9
|
+
[threat model](threat-model.md) describes the trust and coverage limits.
|
|
11
10
|
|
|
12
|
-
The shared Core, Decision Protocol, and
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
the
|
|
11
|
+
The shared Core, Decision Protocol, Skills and Lab CLI define these workflows.
|
|
12
|
+
Adapters connect them to host-native hooks or explicit tools. DSH, Claude
|
|
13
|
+
Code, Codex and other hosts have separate compatibility and coverage evidence;
|
|
14
|
+
see the [capability matrix](../guides/harness-capabilities.md).
|
|
16
15
|
|
|
17
|
-
##
|
|
16
|
+
## Three functional areas
|
|
17
|
+
|
|
18
|
+
| Main capability | Functions and implementation | Contract and guides |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| **Exfil-guard** | Text detection/redaction in `core/redaction.py`, disclosure decisions in `core/policy.py`, and safe config views in `core/safe_view.py` | [Exfil-guard Skill](../../skills/exfil-guard/SKILL.md) |
|
|
21
|
+
| **Delete-guard** | Classification, authorization, recovery and audit; Cleanup Copilot includes read-only inventory/measurement and delegates reviewed execution to `safe_delete`; MCP exposes explicit tools while its doctor performs read-only state queries | [Delete-guard Skill](../../skills/delete-guard/SKILL.md) · [Cleanup](../guides/cleanup-plan.md) · [Limits](../guides/deletion-limits.md) · [MCP](../guides/mcp.md) |
|
|
22
|
+
| **Guard-lab** | `guard_lab.py` and `core/lab.py` provide a user-controlled diagnostic plane: calibration, declared-channel observation and matched comparisons | [Lab workflow and evidence](../lab/guard-lab.md) |
|
|
23
|
+
|
|
24
|
+
Core and adapters provide shared infrastructure. The
|
|
25
|
+
[recovery-audit Skill](../../skills/recovery-audit/SKILL.md) supplies an auxiliary
|
|
26
|
+
workflow for reconstructing workspaces and auditing incident recovery.
|
|
27
|
+
|
|
28
|
+
<a id="the-four-pillars-and-where-they-live"></a>
|
|
29
|
+
|
|
30
|
+
## Delete-guard's four pillars
|
|
18
31
|
|
|
19
32
|
| Pillar | Question it answers | Component |
|
|
20
33
|
|---|---|---|
|
|
@@ -278,6 +291,30 @@ FORBIDDEN (BLOCK, never askable).
|
|
|
278
291
|
feed a Lab observation into Core policy or claim to ban model calls. A real
|
|
279
292
|
block would require a host hook or request gateway that owns the call.
|
|
280
293
|
|
|
294
|
+
<a id="read-only-cleanup-observations-unreleased"></a>
|
|
295
|
+
|
|
296
|
+
## Read-only cleanup observations (0.2.9)
|
|
297
|
+
|
|
298
|
+
`core/cleanup_groups.py` supplies bounded directory-group discovery and
|
|
299
|
+
explicit-scope measurement to the Cleanup CLI. The MCP adapter delegates its
|
|
300
|
+
two new read-only tools to that same CLI, keeping one implementation and a
|
|
301
|
+
fixed original workspace. This addition starts in 0.2.9 and is absent from 0.2.8.
|
|
302
|
+
|
|
303
|
+
Discovery reads a shallow frontier, recognizes environments before cache
|
|
304
|
+
markers, and groups application-managed caches without expanding them.
|
|
305
|
+
Path hints prioritize work within the existing budget; incomplete frontiers
|
|
306
|
+
and unknown sizes stay explicit. A follow-up scope is a new bounded
|
|
307
|
+
observation, not a whole-workspace completion claim. Measurement streams
|
|
308
|
+
metadata into a digest and per-scope/global inode maps, omits protected
|
|
309
|
+
subtrees, and never follows links. Observed subset completeness is separate
|
|
310
|
+
from whole-size completeness.
|
|
311
|
+
|
|
312
|
+
Independent observation schemas and IDs cannot be used as executable Cleanup
|
|
313
|
+
plans. All rows remain nonselectable. A shared Core projection for complete
|
|
314
|
+
ordinary artifacts does not check admission or grant approval. The existing
|
|
315
|
+
plan confirmation and safe_delete pipeline remains responsible for mutation.
|
|
316
|
+
See [result and limit contracts](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased).
|
|
317
|
+
|
|
281
318
|
## Read-only quarantine queries
|
|
282
319
|
|
|
283
320
|
core/trash_index.py exposes list_trash_locations for CLI, agent and future
|
|
@@ -305,9 +342,21 @@ order of value:
|
|
|
305
342
|
|
|
306
343
|
## Delivery status and design directions
|
|
307
344
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
345
|
+
Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only directory
|
|
346
|
+
observations and two MCP tools, speeds up existing planning, and corrects
|
|
347
|
+
the normal-corpus test boundary. The original five operations and mutation
|
|
348
|
+
contracts remain in place. The version decision is recorded in
|
|
349
|
+
[compatibility](compatibility.md#029-cleanup-maintenance-decision).
|
|
350
|
+
|
|
351
|
+
Version [0.2.8](../releases/release-notes-0.2.8.md) adds MCP connection
|
|
352
|
+
diagnosis and protocol-interruption validation. The existing five tools,
|
|
353
|
+
deletion policy and recovery format
|
|
354
|
+
retain their contracts. Direct-service diagnosis, actual-host connection,
|
|
355
|
+
model use and native interception have separate evidence requirements.
|
|
356
|
+
|
|
357
|
+
Version [0.2.7](../releases/release-notes-0.2.7.md) introduced reviewed Cleanup
|
|
358
|
+
plans, shared deletion admission and optional local MCP tools. Confirm
|
|
359
|
+
availability through the exact GitHub release and npm
|
|
311
360
|
version links in those notes; a source version does not establish publication.
|
|
312
361
|
Earlier stable 0.2.6/0.2.5, opt-in 0.2.4-hotfix.1 and prerelease 0.2.5-rc3
|
|
313
362
|
retain their separate artifacts and evidence.
|
|
@@ -4,9 +4,13 @@ agent-guard's promise is recoverability. A promise is only as good as its
|
|
|
4
4
|
stability over time - this page states exactly what may change and what
|
|
5
5
|
may not, per release class.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only Cleanup
|
|
8
|
+
inventory and measurement, faster planning and a repository-corpus test fix.
|
|
9
|
+
Version [0.2.8](../releases/release-notes-0.2.8.md) adds diagnosis and
|
|
10
|
+
reliability maintenance to the published
|
|
11
|
+
[0.2.7](../releases/release-notes-0.2.7.md) baseline. Use exact GitHub release
|
|
12
|
+
and npm version links to confirm availability; a version in source or a local
|
|
13
|
+
tarball does not establish publication.
|
|
10
14
|
Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
|
|
11
15
|
RC maintenance and the feedback/diagnostic additions below. The opt-in
|
|
12
16
|
prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
|
|
@@ -19,6 +23,11 @@ earlier releases.
|
|
|
19
23
|
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
20
24
|
optional MCP tools. The bounded versioning decision is recorded below; the
|
|
21
25
|
separate 0.3.0 plan remains paused.
|
|
26
|
+
The later **0.2.8** selection is independently scoped to MCP diagnosis and
|
|
27
|
+
reliability maintenance, as recorded below; earlier exceptions do not grant
|
|
28
|
+
permission to change unrelated policy under a patch number.
|
|
29
|
+
The **0.2.9** selection has its own bounded decision for the Cleanup
|
|
30
|
+
observation interfaces and accompanying performance/test maintenance below.
|
|
22
31
|
|
|
23
32
|
RC3 publishes defensive research and an example around the existing four
|
|
24
33
|
zero-model controls. Experimental disclosure labels and private delegation
|
|
@@ -26,13 +35,70 @@ methods are not additions to the Decision Protocol or native-hook contract.
|
|
|
26
35
|
No production dependency, policy verdict or storage/configuration migration
|
|
27
36
|
is introduced by the research documentation.
|
|
28
37
|
|
|
38
|
+
<a id="unreleased-cleanup-observation-additions"></a>
|
|
39
|
+
|
|
40
|
+
## Cleanup observation additions (0.2.9)
|
|
41
|
+
|
|
42
|
+
Version 0.2.9 adds independent read-only discovery/measurement schemas,
|
|
43
|
+
CLI modes and MCP tools. They are absent from published 0.2.8 and cannot
|
|
44
|
+
produce an executable plan or approval. Its MCP server advertises seven
|
|
45
|
+
tools; its doctor verifies that set and invokes only the original three
|
|
46
|
+
state queries. Published 0.2.8 retains its five-tool contract. Use doctor and
|
|
47
|
+
server from the same installation; identical version text in a working
|
|
48
|
+
checkout does not establish identical bytes or tools.
|
|
49
|
+
|
|
50
|
+
Existing default Cleanup plans, execution confirmation, original five MCP
|
|
51
|
+
tools, deletion policy and recovery formats retain their interfaces. No
|
|
52
|
+
dependency, configuration or storage migration is introduced.
|
|
53
|
+
See [new observation semantics](../guides/mcp.md#cleanup-observations-029).
|
|
54
|
+
The versioned checkpoints below describe their original release scope.
|
|
55
|
+
|
|
56
|
+
The new CLI modes, independent observation JSON and two MCP tools are
|
|
57
|
+
additive public interfaces, even though they grant no deletion permission.
|
|
58
|
+
The maintainer selected 0.2.9 through the new bounded decision below;
|
|
59
|
+
earlier patch-version exceptions do not authorize it. The paused 0.3.0
|
|
60
|
+
research roadmap is a separate scope decision and is not resumed.
|
|
61
|
+
|
|
29
62
|
## The adapter contract (frozen surface)
|
|
30
63
|
|
|
64
|
+
<a id="mcp-doctor-028-development"></a>
|
|
65
|
+
|
|
66
|
+
### MCP doctor (0.2.8)
|
|
67
|
+
|
|
68
|
+
`doctor.py mcp` is an explicit local diagnosis path. It accepts the selected
|
|
69
|
+
Python interpreter, existing workspace, optional reviewed server script and
|
|
70
|
+
a diagnostic timeout; it does not parse or rewrite host configuration. It
|
|
71
|
+
checks the optional pinned SDK and its imports, service handshake/name/version,
|
|
72
|
+
the five-tool set and query annotations, workspace/quarantine binding and
|
|
73
|
+
successful status/transactions/gc_plan calls. The selected service version
|
|
74
|
+
must match the doctor's package version. It does not call a model or execute
|
|
75
|
+
deletion, restore, GC or budget-reset tools.
|
|
76
|
+
|
|
77
|
+
Its independent `schema_version: 1` report uses fixed `status`, `stage`, `code`,
|
|
78
|
+
`message`, `guidance` and `checks` fields rather than raw child stderr,
|
|
79
|
+
configuration contents or recovery/audit records. It keeps `host_connection`,
|
|
80
|
+
`model_delivery` and `host_interception` at `UNVERIFIED`: direct service
|
|
81
|
+
diagnosis cannot certify another client's loading or behavior. Exit `0` means
|
|
82
|
+
PASS, `1` means diagnostic failure and `2` remains argument-usage failure.
|
|
83
|
+
Diagnostic codes belong to this report, not the Decision Protocol reason-code
|
|
84
|
+
namespace. Existing Kimi/Claude doctor interfaces retain their semantics.
|
|
85
|
+
`diagnostic_stderr_bytes` is a count, not raw stderr. A successful status check
|
|
86
|
+
also records `deletion_admission` as `BLOCKED` or `READABLE`; the latter means
|
|
87
|
+
the information was inspected, not that deletion is authorized. A connection
|
|
88
|
+
PASS can coexist with blocked admission, which the text renderer highlights.
|
|
89
|
+
The 5–120 second diagnostic deadline defaults to 30 seconds; service-process
|
|
90
|
+
shutdown can add up to three seconds of process waits and one second of reader-thread waiting.
|
|
91
|
+
|
|
92
|
+
The SDK remains separately optional, including when invoking Core/CLI or
|
|
93
|
+
doctor help. Changing package/helper bytes can change existing doctor runtime
|
|
94
|
+
fingerprints and produce `DRIFTED`; an old baseline is not automatically
|
|
95
|
+
replaced. See [options, result scope and recovery after a lost response](../guides/mcp.md#diagnose-a-local-service-028).
|
|
96
|
+
|
|
31
97
|
<a id="local-mcp-tools-027-candidate"></a>
|
|
32
98
|
|
|
33
99
|
### Local MCP tools (0.2.7)
|
|
34
100
|
|
|
35
|
-
The
|
|
101
|
+
The 0.2.7 release introduced an optional local stdio MCP server with five explicit tools:
|
|
36
102
|
safe_delete, ordinary restore, transactions, status and GC-plan preview.
|
|
37
103
|
It invokes existing CLI operations without a shell, preserves policy/audit/
|
|
38
104
|
recovery semantics and binds workspace/session identity at trusted startup.
|
|
@@ -55,7 +121,9 @@ and did not run Node; its cause remains undetermined. The second full run
|
|
|
55
121
|
passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
|
|
56
122
|
failures, errors, skips or timeouts. Neither invoked npm directly or changed
|
|
57
123
|
the runtime/tests. A 154-file offline installation and three real Kimi 2.3.0
|
|
58
|
-
native-MCP trials passed; Claude/Cursor/Codex setup examples
|
|
124
|
+
native-MCP trials passed; at that checkpoint Claude/Cursor/Codex setup examples
|
|
125
|
+
were docs-only. Later Codex 0.165.0 acceptance of the published 0.2.7 package
|
|
126
|
+
is recorded separately in the [MCP guide](../guides/mcp.md#codex-01650-with-published-027).
|
|
59
127
|
Without the optional SDK, seven protocol tests skip. The added SDK-backed
|
|
60
128
|
Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
|
|
61
129
|
preparation checkpoint. See
|
|
@@ -233,6 +301,54 @@ While the major version is `0`:
|
|
|
233
301
|
| check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
|
|
234
302
|
| Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
|
|
235
303
|
|
|
304
|
+
<a id="029-cleanup-maintenance-decision"></a>
|
|
305
|
+
|
|
306
|
+
### 0.2.9: bounded Cleanup maintenance decision
|
|
307
|
+
|
|
308
|
+
The maintainer selected **0.2.9** for read-only directory discovery and
|
|
309
|
+
measurement, planning performance and the normal-corpus test correction.
|
|
310
|
+
The new CLI modes, version-1 observation schemas and two MCP tools are
|
|
311
|
+
additive public interfaces carried as this release's explicit maintenance
|
|
312
|
+
exception. The general release-class promises remain in force; this decision
|
|
313
|
+
does not authorize other patch releases or resume the 0.3.0 research plan.
|
|
314
|
+
|
|
315
|
+
Upgrade both doctor and server from the same package: 0.2.9 expects seven
|
|
316
|
+
tools, while 0.2.8 expects five. Existing installations need an explicit
|
|
317
|
+
upgrade. Changed package/helper bytes may make an older doctor fingerprint
|
|
318
|
+
baseline `DRIFTED`; review it rather than silently replacing it.
|
|
319
|
+
|
|
320
|
+
The original five MCP operations, default executable plans and confirmation,
|
|
321
|
+
Decision classes/reasons, default deletion rules, budgets, recovery manifests,
|
|
322
|
+
ordinary restore and preview-only MCP GC retain their contracts. Observation
|
|
323
|
+
IDs and policy projections cannot authorize deletion. No dependency or
|
|
324
|
+
configuration/storage migration is introduced. See the
|
|
325
|
+
[release notes](../releases/release-notes-0.2.9.md).
|
|
326
|
+
|
|
327
|
+
<a id="028-diagnosis-maintenance-decision"></a>
|
|
328
|
+
|
|
329
|
+
### 0.2.8: bounded diagnosis maintenance decision
|
|
330
|
+
|
|
331
|
+
The maintainer selected **0.2.8** for the explicit MCP doctor path, real
|
|
332
|
+
protocol-interruption checks and their documentation. Earlier doctor drift
|
|
333
|
+
and live-sentinel additions were classified as minor below. The new optional
|
|
334
|
+
diagnostic surface is carried as this version's bounded maintenance decision;
|
|
335
|
+
the 0.2.7 exception is not inherited and the general release-class promises
|
|
336
|
+
remain in force.
|
|
337
|
+
|
|
338
|
+
The independent MCP doctor parameters, version-1 diagnosis report and exit
|
|
339
|
+
codes are the upgrade-visible additions. Package/helper changes may affect
|
|
340
|
+
existing doctor fingerprints. The five MCP tools and their arguments,
|
|
341
|
+
Decision classes/reasons, default deletion policy, persistent accounting,
|
|
342
|
+
recovery manifests, ordinary restore and preview-only MCP GC retain their
|
|
343
|
+
contracts. No configuration/storage migration or default SDK installation is
|
|
344
|
+
introduced. The diagnosis checks a selected service; it adds no native host
|
|
345
|
+
interception or client configuration management. The 0.3.0 and commercial
|
|
346
|
+
plans are not resumed.
|
|
347
|
+
|
|
348
|
+
Source validation, installed-package and workflow results retain their
|
|
349
|
+
separate checkpoints in the
|
|
350
|
+
[0.2.8 notes](../releases/release-notes-0.2.8.md#validation-status).
|
|
351
|
+
|
|
236
352
|
<a id="027-candidate-bounded-maintainer-selected-exception"></a>
|
|
237
353
|
|
|
238
354
|
### 0.2.7: bounded maintainer-selected exception
|
|
@@ -14,6 +14,82 @@ layout or Git exclude rules. It also suppresses project bytecode creation.
|
|
|
14
14
|
Planning does not call `safe_delete --dry-run`, whose metadata side effects
|
|
15
15
|
remain documented in the [policy reference](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
16
16
|
|
|
17
|
+
<a id="directory-overview-and-measurement-unreleased"></a>
|
|
18
|
+
|
|
19
|
+
## Directory overview and measurement (0.2.9)
|
|
20
|
+
|
|
21
|
+
These modes are introduced in **0.2.9**, not included in the published 0.2.8
|
|
22
|
+
package. They share the stdlib-only Core with two new
|
|
23
|
+
[read-only MCP tools](mcp.md#cleanup-observations-029). The existing
|
|
24
|
+
default plan and explicit execution workflow below keep their interfaces.
|
|
25
|
+
This addition remains part of Delete-guard's Cleanup Copilot.
|
|
26
|
+
|
|
27
|
+
Start with a bounded overview, then inspect a specific unexpanded directory
|
|
28
|
+
or measure explicit scopes, always keeping the original workspace root:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
32
|
+
--root /absolute/path/to/project --discover --json
|
|
33
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
34
|
+
--root /absolute/path/to/project --discover --scope .work --json
|
|
35
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
|
|
36
|
+
--root /absolute/path/to/project --measure --scope build --scope .pytest_cache --json
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Scopes are literal, non-overlapping directories below that fixed root;
|
|
40
|
+
directory-link components, protected scopes, outside paths and the workspace
|
|
41
|
+
root itself are refused. Without scopes, discovery starts at the root.
|
|
42
|
+
Measurement requires scopes. Quote spaces; use `--scope=-name` for a leading
|
|
43
|
+
dash. A scoped discovery starts a new bounded observation rather than a
|
|
44
|
+
cursor or a claim that previous results now cover the entire workspace.
|
|
45
|
+
|
|
46
|
+
| Mode | Default limits | Output |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `--discover` | Depth 4 per selected root, 10000 entries total, 256 expanded directories, 512 entries per directory | Compact overview; JSON includes all observed groups, review branches and unexpanded paths; all sizes unknown |
|
|
49
|
+
| `--measure` | Depth 32 per scope, 20000 entries shared across scopes | Logical file/link sizes with inode deduplication, protected roots, issues and completeness per scope |
|
|
50
|
+
|
|
51
|
+
`--max-entries` and `--max-depth` override their mode's positive limits in the
|
|
52
|
+
CLI. The MCP tools only allow lowering the stated defaults. These new modes
|
|
53
|
+
have been exercised on Linux ARM64/PRoot; their no-follow cache-marker opening
|
|
54
|
+
uses POSIX facilities and has no Windows acceptance evidence.
|
|
55
|
+
|
|
56
|
+
Discovery recognizes protected boundaries before runtime markers, cache
|
|
57
|
+
markers and known artifact patterns. A regular `pyvenv.cfg` takes precedence
|
|
58
|
+
over `CACHEDIR.TAG`; it identifies an environment hint, not an unused runtime.
|
|
59
|
+
A valid cache signature and the name `uv` provide an ownership hint only.
|
|
60
|
+
Managed caches stay grouped without suggesting their internal build fragments.
|
|
61
|
+
Cache/artifact path hints affect queue order, not permission or proof of
|
|
62
|
+
obsolescence. No age or filename heuristic declares content discarded.
|
|
63
|
+
|
|
64
|
+
JSON uses independent `cleanup_group_discovery/v1` and
|
|
65
|
+
`cleanup_group_measurement/v1` schemas with an `observation_id`, **no
|
|
66
|
+
executable `plan_id`**. Every observation has `execution_supported: false`
|
|
67
|
+
and every group has `selectable: false`. Discovery's `frontier_complete`
|
|
68
|
+
only describes its bounded frontier; `workspace_scan_complete` stays false.
|
|
69
|
+
Inspect `coverage.unexpanded`, limits and issues before choosing a scope.
|
|
70
|
+
|
|
71
|
+
Measurement never follows links. Protected subtrees and external/protected
|
|
72
|
+
link boundaries are omitted; `size_bytes: null` means unknown, not zero.
|
|
73
|
+
`observed_bytes` counts the observed subset and does not predict freed disk
|
|
74
|
+
space. `observed_subset_complete` may be true while `size_complete` and
|
|
75
|
+
`interior_checked` are false because protection prevents a whole-size claim.
|
|
76
|
+
The metadata digest is not a content hash or atomic snapshot. Scans read
|
|
77
|
+
metadata and at most 43 bytes per examined cache tag, plus existing Guard
|
|
78
|
+
configuration and Git facts; they do not parse database or cache payloads.
|
|
79
|
+
|
|
80
|
+
For complete ordinary artifact scopes, `core_policy` may show a shared Core
|
|
81
|
+
projection. Approval remains `NOT_GRANTED`, budget `NOT_CHECKED`, and the
|
|
82
|
+
projection does not grant execution. Application-managed caches remain
|
|
83
|
+
subject to their own consistency and locking protocol.
|
|
84
|
+
|
|
85
|
+
Exit 0 means the requested frontier or observed measurement subset completed;
|
|
86
|
+
1 retains partial observations after limits, I/O errors or observed source
|
|
87
|
+
changes; 2 means invalid options or refusal. A protected unknown whole size
|
|
88
|
+
can therefore coexist with measurement exit 0. None authorizes deletion.
|
|
89
|
+
`--scope` requires these new modes; they reject `--discard`, `--protect`,
|
|
90
|
+
`--execute`, `--plan-id` and `--select`. To delete, produce a separate reviewed
|
|
91
|
+
plan using the existing workflow; an observation cannot be promoted into one.
|
|
92
|
+
|
|
17
93
|
## Review a plan
|
|
18
94
|
|
|
19
95
|
From the intended workspace, run:
|
|
@@ -63,6 +139,17 @@ Unknown subtrees collapse into review rows unless generated, discarded or
|
|
|
63
139
|
protected descendants need to be shown. Candidate directories and their
|
|
64
140
|
children are not offered as overlapping selections.
|
|
65
141
|
|
|
142
|
+
The planner reuses ordinary-file metadata and its batched Git facts within
|
|
143
|
+
one scan. Directory and link boundaries still receive full checks. This does
|
|
144
|
+
not make a partial scan complete or change the scan limits. Execution still
|
|
145
|
+
rescans the plan and reads current policy and Git facts.
|
|
146
|
+
|
|
147
|
+
A regenerable classification does not verify an application's cache protocol.
|
|
148
|
+
For example, [uv documents its cache consistency and locking requirements](https://docs.astral.sh/uv/concepts/cache/#cache-safety)
|
|
149
|
+
and warns against directly changing cache contents. Review such managed
|
|
150
|
+
caches separately; the planner does not coordinate their application locks
|
|
151
|
+
or automatically invoke native cache-cleaning commands.
|
|
152
|
+
|
|
66
153
|
## Confirm and execute
|
|
67
154
|
|
|
68
155
|
Copy the plan's full `plan_id`, select exact rows marked `selectable`, and
|
|
@@ -125,6 +212,10 @@ retrying. No automatic purge or rollback runs.
|
|
|
125
212
|
|
|
126
213
|
## Sizes, limits and output
|
|
127
214
|
|
|
215
|
+
This section describes plan JSON and the confirmation workflow. The
|
|
216
|
+
[read-only observation modes](#directory-overview-and-measurement-unreleased)
|
|
217
|
+
have their own schemas and limits.
|
|
218
|
+
|
|
128
219
|
Sizes are logical file bytes, with hardlinks counted once per entry and per
|
|
129
220
|
category summary. Directory metadata is omitted; links use their own size
|
|
130
221
|
and directory links are not traversed. Protected subtree sizes are unknown.
|
|
@@ -170,6 +261,12 @@ before writing a new baseline at a new path.
|
|
|
170
261
|
|
|
171
262
|
## 中文摘要
|
|
172
263
|
|
|
264
|
+
0.2.9 新增 `--discover` 目录概况、`--measure --scope PATH` 指定范围计量,
|
|
265
|
+
并提供对应的 `cleanup_discover`/`cleanup_measure` MCP 工具;已发布 0.2.8
|
|
266
|
+
不含这些能力。按范围继续发现仍保持原工作区,未展开部分和大小未知必须保留。
|
|
267
|
+
这些观察不生成可执行计划或删除许可,MCP 的 `ok: true, partial: true` 也不代表
|
|
268
|
+
完整扫描。执行仍需另外生成并审阅下面的既有计划。
|
|
269
|
+
|
|
173
270
|
本功能自 0.2.7 加入。默认扫描只输出计划,不修改工作区;“明确废弃”仅来自
|
|
174
271
|
调用者显式声明,旧文件/未跟踪文件不会自动变为垃圾。执行必须提供计划 ID、选定
|
|
175
272
|
具体条目并由操作者在终端确认,确认后复查,再逐项走现有 safe_delete。普通文件
|
|
@@ -10,10 +10,11 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
|
|
|
10
10
|
|
|
11
11
|
## Select the package root
|
|
12
12
|
|
|
13
|
-
This guide covers [0.2.
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
This guide covers [0.2.9](../releases/release-notes-0.2.9.md), with read-only
|
|
14
|
+
Cleanup inventory and measurement, faster plan scans, MCP connection
|
|
15
|
+
diagnosis and the existing deletion/recovery tools. Confirm the
|
|
16
|
+
exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
|
|
17
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
|
|
17
18
|
are available before installing from the registry. A checkout or manifest
|
|
18
19
|
does not establish publication or the current npm `latest` channel.
|
|
19
20
|
|
|
@@ -26,7 +27,7 @@ backports quarantine protection onto the stable line.
|
|
|
26
27
|
Once the exact version is available, use a user-selected stable prefix:
|
|
27
28
|
|
|
28
29
|
```sh
|
|
29
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
30
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
|
|
30
31
|
```
|
|
31
32
|
|
|
32
33
|
The package root is
|
|
@@ -42,7 +43,7 @@ If that version is unavailable, use a reviewed source checkout or a checked
|
|
|
42
43
|
local tarball. Install the tarball into a separate prefix:
|
|
43
44
|
|
|
44
45
|
```sh
|
|
45
|
-
npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.
|
|
46
|
+
npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.9.tgz
|
|
46
47
|
```
|
|
47
48
|
|
|
48
49
|
The review package root is
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Harness capability and evidence matrix
|
|
2
2
|
|
|
3
|
-
This matrix accompanies [0.2.
|
|
3
|
+
This matrix accompanies [0.2.9](../releases/release-notes-0.2.9.md).
|
|
4
4
|
Confirm availability through the exact GitHub release and npm version links
|
|
5
5
|
in those notes; a source version does not establish publication.
|
|
6
6
|
Published prerelease, checked on 2026-10-19:
|
|
@@ -97,9 +97,26 @@ is separate from the standard-library Core/CLI requirements.
|
|
|
97
97
|
|
|
98
98
|
The guide records the 0.2.7 installed-package/protocol checks and the earlier
|
|
99
99
|
bounded Kimi Code 2.3.0 root-agent native-MCP trials with their original
|
|
100
|
-
checkpoint and gateway limits.
|
|
101
|
-
|
|
102
|
-
|
|
100
|
+
checkpoint and gateway limits. A separate
|
|
101
|
+
[Codex 0.165.0 acceptance](mcp.md#codex-01650-with-published-027) used published
|
|
102
|
+
0.2.7: three actual-client groups and three real-model tasks, with 16 model MCP
|
|
103
|
+
calls. Its recorded results and incomplete native-client exit metadata retain
|
|
104
|
+
their stated limits. These cooperative MCP observations do not expand the
|
|
105
|
+
native-hook rows above or establish live Claude/Cursor, arbitrary subagent,
|
|
106
|
+
other-version or additional-platform coverage. Untested client setup examples
|
|
107
|
+
remain documentation guidance.
|
|
108
|
+
|
|
109
|
+
The [MCP doctor introduced in 0.2.8](mcp.md#diagnose-a-local-service-028)
|
|
110
|
+
checks a selected service through handshake and read-only calls. Its PASS
|
|
111
|
+
does not establish host connection, model use or native interception; those
|
|
112
|
+
remain separate evidence levels.
|
|
113
|
+
|
|
114
|
+
Version 0.2.9 adds the read-only `cleanup_discover` and `cleanup_measure`
|
|
115
|
+
tools. Local source checks include real-project stdio observations and one
|
|
116
|
+
bounded Kimi Code inventory task in a synthetic workspace (three MCP calls).
|
|
117
|
+
That task covers the new observation path, not a fresh cross-host acceptance
|
|
118
|
+
of the published package or native interception. See the
|
|
119
|
+
[0.2.9 validation](../releases/release-notes-0.2.9.md#validation).
|
|
103
120
|
|
|
104
121
|
## Acceptance for each native adapter
|
|
105
122
|
|