@mokuyoaxis/agent-guard 0.2.8 → 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 CHANGED
@@ -53,6 +53,13 @@ unverified, and whether the result is a local Core/CLI check, a mock-host check,
53
53
  or real-host evidence. A passing mock must not be described as universal host
54
54
  enforcement.
55
55
 
56
+ The corpus noise regression scans Git-index paths using the current regular
57
+ UTF-8 working-tree files. Tracked modifications and newly staged paths count;
58
+ untracked private experiments are outside this versioned normal corpus.
59
+ Stage intended new files before using this check as a pre-commit gate. Git or
60
+ read errors fail explicitly. This metric does not certify the whole workspace;
61
+ Exfil rules remain active for direct scans of untracked and adversarial files.
62
+
56
63
  Review, merge, tagging, GitHub Release, and npm publication are separate
57
64
  maintainer decisions. Acceptance of a contribution does not promise a specific
58
65
  release date.
@@ -111,6 +118,12 @@ inconclusive trials. See the [research index](docs/research/README.md).
111
118
  PR 描述请写明改了什么、验证了什么、哪些路径仍未验证,以及证据属于本地
112
119
  Core/CLI、模拟宿主还是真实宿主。模拟测试通过不能写成所有宿主都已强制拦截。
113
120
 
121
+ 正常语料噪声回归以 Git 索引路径为范围,读取当前工作树中的普通 UTF-8 文件。
122
+ 已跟踪修改和新增已暂存文件均纳入;未跟踪的私有对抗实验不属于该版本化正常
123
+ 语料。新增文件应在明确准备纳入版本管理后暂存,再使用本项提交前检查;Git 或
124
+ 读取失败会显式报错。本指标不认证整个工作区,直接扫描未跟踪或对抗文件时
125
+ Exfil 规则仍然生效。
126
+
114
127
  审阅、合并、标签、GitHub Release 与 npm 发布是维护者分别作出的决定;贡献被
115
128
  接受不代表承诺在某个版本或日期发布。
116
129
 
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.8](https://img.shields.io/badge/release-0.2.8-5B6B7A)](docs/releases/release-notes-0.2.8.md)
7
+ [![0.2.9](https://img.shields.io/badge/release-0.2.9-5B6B7A)](docs/releases/release-notes-0.2.9.md)
8
8
 
9
9
  **Disclosure checks · Recoverable deletion · Agent experiments** · [简体中文](README.zh-CN.md)
10
10
 
@@ -24,16 +24,18 @@ Installed Skills or copied configuration alone do not establish protection.
24
24
  We currently focus on **DSH and Kimi Code** integrations. For other hosts,
25
25
  ask the official coding agent to configure Agent Guard locally.
26
26
 
27
- Version **[0.2.8](docs/releases/release-notes-0.2.8.md)** adds MCP connection
28
- diagnosis and recovery validation to the Cleanup plans, deletion admission
29
- limits and optional local MCP tools introduced in
30
- [0.2.7](docs/releases/release-notes-0.2.7.md). Before installing, verify the exact
31
- GitHub release and npm version through the links below.
27
+ Version **[0.2.9](docs/releases/release-notes-0.2.9.md)** makes cleanup
28
+ investigation faster: get a bounded directory overview, then measure selected
29
+ scopes through Cleanup Copilot or MCP. Existing plan scans also reuse metadata
30
+ and Git queries. These observations grant no deletion permission; execution
31
+ still requires a separate reviewed plan and confirmation.
32
+ See the [workflow and limits](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029).
33
+ Before installing, verify the exact GitHub release and npm version below.
32
34
 
33
35
  | Main capability | Included functions | Guides |
34
36
  |---|---|---|
35
37
  | **Exfil-guard** | Check supported credentials and identifying paths; plan and apply redaction; inspect JSON/dotenv structure without displaying scalar values | [Skill and CLI](skills/exfil-guard/SKILL.md) · [Rules](skills/exfil-guard/references/rules.md) · [Safe config view](skills/exfil-guard/SKILL.md#safe-config-view) |
36
- | **Delete-guard** | Recoverable deletion and supported Git snapshots; Cleanup Copilot; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis | [Skill and CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [Deletion limits](docs/guides/deletion-limits.md) · [Recovery and GC](docs/guides/recovery-feedback.md) · [MCP tools](docs/guides/mcp.md) · [MCP doctor (0.2.8)](docs/guides/mcp.md#diagnose-a-local-service-028) |
38
+ | **Delete-guard** | Recoverable deletion and supported Git snapshots; Cleanup Copilot plans, directory overview and measurement; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis | [Skill and CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [Deletion limits](docs/guides/deletion-limits.md) · [Recovery and GC](docs/guides/recovery-feedback.md) · [MCP tools](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
37
39
  | **Guard-lab** | Four zero-model calibration controls; synthetic markers and declared-channel observation; evidence and observer-health checks; matched guard-off/on comparisons after an effective baseline | [Lab workflow](docs/lab/guard-lab.md) · [Four-control example](docs/lab/blue-team-calibration.md) · [Evidence levels](docs/lab/guard-lab.md#evidence-levels) |
38
40
 
39
41
  Cleanup Copilot, deletion limits and the current MCP tools/doctor belong to
@@ -117,7 +119,8 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
117
119
 
118
120
  | Version | Status |
119
121
  |---|---|
120
- | [0.2.8](docs/releases/release-notes-0.2.8.md) | Current release line; verify exact-version availability below |
122
+ | [0.2.9](docs/releases/release-notes-0.2.9.md) | Current release line; verify exact-version availability below |
123
+ | [0.2.8](docs/releases/release-notes-0.2.8.md) | Earlier release with MCP diagnosis and recovery validation |
121
124
  | [0.2.7](docs/releases/release-notes-0.2.7.md) | Earlier release with Cleanup, deletion limits and local MCP tools |
122
125
  | [0.2.6](docs/releases/release-notes-0.2.6.md) | Earlier published release with Kimi feedback and host compatibility updates |
123
126
  | [0.2.5](docs/releases/release-notes-0.2.5.md) | Earlier stable release |
@@ -125,21 +128,21 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
125
128
  | [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` |
126
129
  | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
127
130
 
128
- Before installing 0.2.8, confirm availability through its exact
129
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
130
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8).
131
+ Before installing 0.2.9, confirm availability through its exact
132
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
133
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9).
131
134
  A checkout or manifest alone does not establish package availability.
132
135
 
133
136
  If that version is unavailable, use reviewed source or a locally built
134
- tarball following the [version notes](docs/releases/release-notes-0.2.8.md).
137
+ tarball following the [version notes](docs/releases/release-notes-0.2.9.md).
135
138
  Versioned tests and package checks retain their original checkpoints.
136
139
  The [admission limits](docs/guides/deletion-limits.md) introduced in 0.2.7 can
137
- refuse previously successful deletions and remain in effect in 0.2.8.
140
+ refuse previously successful deletions and remain in effect in 0.2.9.
138
141
 
139
142
  Once the exact version is available, install to a chosen, stable user-owned prefix:
140
143
 
141
144
  ```sh
142
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
145
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
143
146
  ```
144
147
 
145
148
  The package root is
@@ -289,7 +292,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
289
292
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
290
293
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
291
294
  | [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
292
- | [0.2.8 notes](docs/releases/release-notes-0.2.8.md) | Version scope, upgrade impact and validation boundaries |
295
+ | [0.2.9 notes](docs/releases/release-notes-0.2.9.md) | Cleanup inventory, performance and upgrade notes |
293
296
 
294
297
  ## Contributing
295
298
 
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.8](https://img.shields.io/badge/release-0.2.8-5B6B7A)](docs/releases/release-notes-0.2.8.md)
7
+ [![0.2.9](https://img.shields.io/badge/release-0.2.9-5B6B7A)](docs/releases/release-notes-0.2.9.md)
8
8
 
9
9
  **外发检查 · 可恢复删除 · Agent 验测** · [English](README.md)
10
10
 
@@ -21,15 +21,16 @@ Agent Guard 提供三大功能:**Exfil-guard** 检查待外发文本,**Delet
21
21
  目前主要维护 **DSH 和 Kimi Code** 的接入。其他宿主建议交给对应的官方
22
22
  编码 Agent 在本地配置。
23
23
 
24
- 本版 **[0.2.8](docs/releases/release-notes-0.2.8.md)** 提供 MCP 接入诊断与恢复验证,
25
- 在 [0.2.7](docs/releases/release-notes-0.2.7.md) 已有的 Cleanup 计划、删除准入限制与
26
- 可选本地 MCP 工具基础上完善。安装前,请通过下方链接核实精确版本的
27
- GitHub Release 与 npm 包是否可用。
24
+ 本版 **[0.2.9](docs/releases/release-notes-0.2.9.md)** 改善清理前的盘点体验:先看目录概况,
25
+ 再计量指定范围,Cleanup Copilot 和 MCP 都可使用;既有计划扫描也减少了重复的
26
+ 文件属性检查和 Git 查询。这些观察不授予删除许可,执行仍需另外生成计划、审阅并确认。
27
+ 使用方式见[目录概况与计量](docs/guides/cleanup-plan.md#directory-overview-and-measurement-029)。
28
+ 安装前,请通过下方链接核实精确版本的 GitHub Release 与 npm 包是否可用。
28
29
 
29
30
  | 主要功能 | 下属功能 | 对应链接 |
30
31
  |---|---|---|
31
32
  | **Exfil-guard** | 受支持的凭据与标识路径检测;脱敏计划与执行;不展示标量值的 JSON/dotenv 配置结构视图 | [Skill 与 CLI](skills/exfil-guard/SKILL.md) · [检测规则](skills/exfil-guard/references/rules.md) · [安全配置视图](skills/exfil-guard/SKILL.md#safe-config-view) |
32
- | **Delete-guard** | 可恢复删除与受支持的 Git 快照;Cleanup Copilot;持久预算、速率/重复限制、保护路径与批量确认;事务恢复与手动 GC;可选本地 MCP 工具及接入诊断 | [Skill 与 CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [删除限制](docs/guides/deletion-limits.md) · [恢复与 GC](docs/guides/recovery-feedback.md) · [MCP 工具](docs/guides/mcp.md) · [MCP doctor(0.2.8)](docs/guides/mcp.md#diagnose-a-local-service-028) |
33
+ | **Delete-guard** | 可恢复删除与受支持的 Git 快照;Cleanup Copilot 计划、目录概况与计量;持久预算、速率/重复限制、保护路径与批量确认;事务恢复与手动 GC;可选本地 MCP 工具及接入诊断 | [Skill 与 CLI](skills/delete-guard/SKILL.md) · [Cleanup Copilot](docs/guides/cleanup-plan.md) · [删除限制](docs/guides/deletion-limits.md) · [恢复与 GC](docs/guides/recovery-feedback.md) · [MCP 工具](docs/guides/mcp.md) · [MCP doctor](docs/guides/mcp.md#diagnose-a-local-service-028) |
33
34
  | **Guard-lab** | 四项零模型校准对照;合成标记与声明信道观察;证据和观察器健康检查;有效基线成立后的关闭/开启防护配对比较 | [Lab 流程](docs/lab/guard-lab.md) · [四控制示例](docs/lab/blue-team-calibration.md) · [证据等级](docs/lab/guard-lab.md#evidence-levels) |
34
35
 
35
36
  Cleanup Copilot、删除限制以及当前 MCP 工具/doctor 均归属 **Delete-guard**。
@@ -99,7 +100,8 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
99
100
 
100
101
  | 版本 | 状态 |
101
102
  |---|---|
102
- | [0.2.8](docs/releases/release-notes-0.2.8.md) | 本版;安装前核实下方精确版本渠道 |
103
+ | [0.2.9](docs/releases/release-notes-0.2.9.md) | 本版;安装前核实下方精确版本渠道 |
104
+ | [0.2.8](docs/releases/release-notes-0.2.8.md) | 较早版本:MCP 接入诊断与恢复验证 |
103
105
  | [0.2.7](docs/releases/release-notes-0.2.7.md) | 历史版本,包含 Cleanup、删除限制与本地 MCP 工具 |
104
106
  | [0.2.6](docs/releases/release-notes-0.2.6.md) | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
105
107
  | [0.2.5](docs/releases/release-notes-0.2.5.md) | 更早稳定版 |
@@ -107,20 +109,20 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
107
109
  | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
108
110
  | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
109
111
 
110
- 安装 0.2.8 前,请通过精确版本的
111
- [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)和
112
- [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)确认可用性,
112
+ 安装 0.2.9 前,请通过精确版本的
113
+ [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)和
114
+ [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)确认可用性,
113
115
  checkout 或 manifest 本身不代表包已可安装。
114
116
 
115
- 若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.8.md)使用经复核的
117
+ 若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.9.md)使用经复核的
116
118
  源码或本地构建 tarball。版本化测试和包核验保留各自检查点。
117
119
  自 0.2.7 引入的[准入限制](docs/guides/deletion-limits.md)可能拒绝此前可执行的删除,
118
- 这些限制在 0.2.8 中继续生效。
120
+ 这些限制在 0.2.9 中继续生效。
119
121
 
120
122
  确认精确版本可用后,可安装到用户选定的长期目录:
121
123
 
122
124
  ```sh
123
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
125
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
124
126
  ```
125
127
 
126
128
  包根目录是
@@ -250,7 +252,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
250
252
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
251
253
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
252
254
  | [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
253
- | [0.2.8 说明](docs/releases/release-notes-0.2.8.md) | 版本范围、升级影响与验证边界 |
255
+ | [0.2.9 说明](docs/releases/release-notes-0.2.9.md) | 清理盘点、扫描提速与升级说明 |
254
256
 
255
257
  ## 参与贡献
256
258
 
@@ -69,6 +69,10 @@ or a public report. If the host contract or version is unclear, mark it
69
69
  Say `MCP tools only` unless a separate blocking hook has been verified;
70
70
  registering tools does not intercept shell, script or editor operations.
71
71
  This path adds no force restore, GC execution or model-approved budget reset.
72
+ Version 0.2.9 also offers read-only `cleanup_discover` and
73
+ `cleanup_measure`; published 0.2.8 does not include them. Inspect their
74
+ coverage/size fields and `partial` status rather than treating a successful
75
+ observation as a complete scan or deletion approval.
72
76
 
73
77
  Core `ASK` must reach a real human-approval path or become a refusal for that
74
78
  call. It must never silently become allow. Treat malformed payloads and
@@ -128,9 +132,11 @@ host process. Repeating local probes cannot turn `host_interception` or
128
132
  work and remaining checks so the next session can continue without repeating
129
133
  the setup.
130
134
 
131
- `doctor.py` currently supports only `kimi` and `claude`. Its configuration
132
- and local-probe PASS states do **not** prove a live host loaded or enforced a
133
- hook. Do not reuse those states as an unknown-host certification.
135
+ The hook-specific `doctor.py kimi|claude` configuration and local-probe PASS
136
+ states do **not** prove a live host loaded or enforced a hook. The separate
137
+ `doctor.py mcp` checks a selected local service's handshake, tool set and
138
+ read-only state queries; see the [MCP guide](../docs/guides/mcp.md#diagnose-a-local-service-028).
139
+ Do not reuse either kind of PASS as an unknown-host certification.
134
140
  The 0.2.6 Kimi doctor also reports optional Stop under `feedback`.
135
141
  Its configuration/local probe is separate from PreToolUse, and
136
142
  `model_delivery` remains `UNVERIFIED`. A missing Stop is optional; an invalid
@@ -22,8 +22,9 @@ ROOT = Path(__file__).resolve().parents[2]
22
22
  SERVER = ROOT / "adapters/mcp/server.py"
23
23
  SDK_VERSION = "2.3.0"
24
24
  PROTOCOL_VERSION = "2025-06-18"
25
- TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan"))
25
+ TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan", "cleanup_discover", "cleanup_measure"))
26
26
  READ_ONLY = ("status", "transactions", "gc_plan")
27
+ READ_ONLY_TOOLS = frozenset(READ_ONLY) | {"cleanup_discover", "cleanup_measure"}
27
28
  MAX_MESSAGE_BYTES = 2 * 1024 * 1024
28
29
 
29
30
  PROBLEMS = {
@@ -51,7 +52,7 @@ PROBLEMS = {
51
52
  "Use the reviewed agent-guard stdio service; stdout must contain protocol messages only."),
52
53
  "MCP_DOCTOR_IDENTITY": ("The service identity or version does not match this installation.",
53
54
  "Select a server script from the same agent-guard version as this doctor."),
54
- "MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match the five-tool contract.",
55
+ "MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match this installation's contract.",
55
56
  "Check the selected service version and tool definitions."),
56
57
  "MCP_DOCTOR_QUERY": ("A read-only tool returned an unsuccessful or invalid result.",
57
58
  "Inspect the failed tool and local recovery state before any mutation."),
@@ -278,7 +279,7 @@ def diagnose(python, workspace, *, server=None, timeout=30):
278
279
  for tool in tools:
279
280
  annotations = tool.get("annotations")
280
281
  if (not isinstance(annotations, dict) or
281
- annotations.get("readOnlyHint") is not (tool["name"] in READ_ONLY)):
282
+ annotations.get("readOnlyHint") is not (tool["name"] in READ_ONLY_TOOLS)):
282
283
  raise _Failure("MCP_DOCTOR_TOOLS")
283
284
  report["tools"] = sorted(TOOLS)
284
285
  report["checks"].append({"stage": stage, "status": "PASS"})
@@ -17,7 +17,8 @@ import threading
17
17
 
18
18
  ROOT = Path(__file__).resolve().parents[2]
19
19
  SCRIPTS = ROOT / "skills" / "delete-guard" / "scripts"
20
- TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan"))
20
+ GROUP_TOOLS = frozenset(("cleanup_discover", "cleanup_measure"))
21
+ TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan")) | GROUP_TOOLS
21
22
  MAX_PATHS = 1000
22
23
  TXID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_-]*\Z")
23
24
 
@@ -76,7 +77,9 @@ class Operations:
76
77
  if not isinstance(arguments, dict):
77
78
  raise InvalidArguments("tool arguments must be an object")
78
79
  allowed = {"safe_delete": {"paths", "dry_run"}, "restore": {"txid"},
79
- "status": {"tail"}, "transactions": set(), "gc_plan": set()}[name]
80
+ "status": {"tail"}, "transactions": set(), "gc_plan": set(),
81
+ "cleanup_discover": {"scopes", "max_entries", "max_depth"},
82
+ "cleanup_measure": {"scopes", "max_entries", "max_depth"}}[name]
80
83
  if set(arguments) - allowed:
81
84
  raise InvalidArguments("unsupported tool argument")
82
85
  result = dict(arguments)
@@ -102,6 +105,19 @@ class Operations:
102
105
  if type(result.get("tail", 10)) is not int or not 0 <= result.get("tail", 10) <= 100:
103
106
  raise InvalidArguments("tail must be an integer between 0 and 100")
104
107
  result["tail"] = result.get("tail", 10)
108
+ elif name in GROUP_TOOLS:
109
+ scopes = result.get("scopes", [])
110
+ if (not isinstance(scopes, list) or len(scopes) > 64
111
+ or (name == "cleanup_measure" and not scopes)
112
+ or any(not isinstance(path, str) or not path or "\0" in path for path in scopes)):
113
+ raise InvalidArguments("scopes must be at most 64 nonempty literal directory paths; measure requires scopes")
114
+ result["scopes"] = scopes
115
+ for field, maximum in (("max_entries", 10000 if name == "cleanup_discover" else 20000),
116
+ ("max_depth", 4 if name == "cleanup_discover" else 32)):
117
+ value = result.get(field, maximum)
118
+ if type(value) is not int or not 1 <= value <= maximum:
119
+ raise InvalidArguments(field + " must be an integer between 1 and " + str(maximum))
120
+ result[field] = value
105
121
  return result
106
122
 
107
123
  def _quarantine_overlap(self, paths):
@@ -136,8 +152,14 @@ class Operations:
136
152
  command = ["restore.py", "list", "--json"]
137
153
  elif name == "status":
138
154
  command = ["status.py", "--json", "--tail", str(args["tail"])]
139
- else:
155
+ elif name == "gc_plan":
140
156
  command = ["gc.py", "--json"]
157
+ else:
158
+ command = ["cleanup.py", "--json", "--discover" if name == "cleanup_discover" else "--measure",
159
+ "--max-entries", str(args["max_entries"]), "--max-depth", str(args["max_depth"])]
160
+ # Equals syntax keeps even an option-looking literal inside its
161
+ # value, without changing the server's fixed workspace binding.
162
+ command += ["--scope=" + scope for scope in args["scopes"]]
141
163
 
142
164
  # Serialize calls in this server, without changing process cwd or
143
165
  # environment. Other participating processes share Core admission.
@@ -168,6 +190,14 @@ class Operations:
168
190
  return self._failure(name, "MCP_CLI_PROTOCOL_ERROR",
169
191
  "CLI did not return a JSON object; inspect recovery state before retrying",
170
192
  exit_code=child.returncode, may_have_changed=mutating)
193
+ if name in GROUP_TOOLS and child.returncode in (0, 1):
194
+ expected = "cleanup_group_discovery/v1" if name == "cleanup_discover" else "cleanup_group_measurement/v1"
195
+ if result.get("schema") != expected:
196
+ return self._failure(name, "MCP_CLI_PROTOCOL_ERROR", "Unexpected cleanup observation schema",
197
+ exit_code=child.returncode)
198
+ partial = (not result["coverage"]["frontier_complete"] if name == "cleanup_discover"
199
+ else any(not row["size_complete"] for row in result["scopes"]))
200
+ return {"tool": name, "ok": True, "partial": partial, "exit_code": child.returncode, "result": result}
171
201
  # Preserve all existing CLI evidence, including txids/moved paths on
172
202
  # partial failures. A nonzero exit never means 'nothing changed'.
173
203
  return {"tool": name, "ok": child.returncode == 0,
@@ -22,6 +22,9 @@ INSTRUCTIONS = (
22
22
  "or retry an uncertain mutation automatically. Large batches and operator-only actions "
23
23
  "remain in the existing CLI workflow. GC here is preview only. These tools do not "
24
24
  "intercept other shell or editor operations."
25
+ " Use cleanup_discover for a bounded directory overview and cleanup_measure for explicit scopes. "
26
+ "Their observations never grant execution permission. A successful call with partial=true "
27
+ "still has incomplete coverage or unknown whole sizes; inspect those fields and use exact scopes."
25
28
  )
26
29
 
27
30
  TOOL_DEFINITIONS = {
@@ -49,6 +52,20 @@ TOOL_DEFINITIONS = {
49
52
  "description": "Preview existing quarantine transaction GC eligibility and retained space. This tool never executes GC or deletes recovery copies. Execution remains an explicit operator CLI action.",
50
53
  "properties": {}, "required": [], "read_only": True, "destructive": False,
51
54
  },
55
+ "cleanup_discover": {
56
+ "description": "Read-only bounded directory overview in the fixed workspace. Optional scopes continue discovery below exact directories. Runtime/cache ownership labels are hints, not proof of obsolescence. Sizes remain unknown; inspect coverage/unexpanded and partial even when ok=true. No executable plan or deletion permission.",
57
+ "properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64},
58
+ "max_entries": {"type": "integer", "minimum": 1, "maximum": 10000, "default": 10000},
59
+ "max_depth": {"type": "integer", "minimum": 1, "maximum": 4, "default": 4}},
60
+ "required": [], "read_only": True, "destructive": False,
61
+ },
62
+ "cleanup_measure": {
63
+ "description": "Read-only metadata measurement of explicit non-overlapping directory scopes below the same workspace. Does not follow links or traverse protected subtrees. size_bytes=null means unknown, not zero; observed_bytes excludes protected data. Core projection is not approval. No plan_id, deletion, restore or GC execution.",
64
+ "properties": {"scopes": {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "maxItems": 64},
65
+ "max_entries": {"type": "integer", "minimum": 1, "maximum": 20000, "default": 20000},
66
+ "max_depth": {"type": "integer", "minimum": 1, "maximum": 32, "default": 32}},
67
+ "required": ["scopes"], "read_only": True, "destructive": False,
68
+ },
52
69
  }
53
70
 
54
71
 
package/core/cleanup.py CHANGED
@@ -113,6 +113,7 @@ def plan_cleanup(
113
113
  physical_protection.append(os.path.relpath(physical, root).replace(os.sep, "/"))
114
114
  protect = sorted(set(protect + physical_protection))
115
115
  trash = os.path.abspath(os.environ.get("AGENT_GUARD_TRASH", os.path.join(root, TRASH_DIRNAME)))
116
+ trash_physical = os.path.realpath(trash)
116
117
  if classifier.inside_path(trash, root):
117
118
  protect = sorted(set(protect + [os.path.relpath(trash, root).replace(os.sep, "/")]))
118
119
  ctx = policy.PolicyContext(workspace=root, trash_root=trash, base_dir=root,
@@ -127,7 +128,7 @@ def plan_cleanup(
127
128
  if record not in errors:
128
129
  errors.append(record)
129
130
 
130
- def visit(relative: str, depth: int) -> _Node:
131
+ def visit(relative: str, depth: int, entry=None) -> _Node:
131
132
  nonlocal examined
132
133
  node = _Node(relative)
133
134
  nodes.append(node)
@@ -144,12 +145,23 @@ def plan_cleanup(
144
145
  problem(node, "PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT")
145
146
  else:
146
147
  try:
147
- info = os.lstat(absolute)
148
+ info = entry.stat(follow_symlinks=False) if entry is not None else os.lstat(absolute)
148
149
  node.signature = [info.st_dev, info.st_ino, info.st_mode,
149
150
  info.st_size, info.st_mtime_ns, info.st_ctime_ns]
151
+ # Parents were checked before traversal and directory links
152
+ # are never followed. Ordinary files can reuse that location
153
+ # without repeating full boundary/type checks for every leaf.
154
+ # Keep the original classifier for directories, links and
155
+ # special roots (including an invalid trash path below a file).
156
+ ordinary_file = (stat.S_ISREG(info.st_mode)
157
+ and not classifier.protected_ancestor_root(absolute)
158
+ and not (_under(trash, absolute)
159
+ or _under(trash_physical, absolute)))
150
160
  spec = (classifier.classify_paths(["./" + relative], root, root, trash)[0]
151
- if relative != "." else None)
152
- physical = os.path.relpath(os.path.realpath(absolute), root).replace(os.sep, "/")
161
+ if relative != "." and not ordinary_file else None)
162
+ physical = os.path.relpath(
163
+ absolute if ordinary_file else os.path.realpath(absolute), root
164
+ ).replace(os.sep, "/")
153
165
  if ((spec and spec.protected) or set(physical.split("/")) & PROTECTED_NAMES
154
166
  or any(_under(physical, p) for p in protect)
155
167
  or (stat.S_ISLNK(info.st_mode)
@@ -160,20 +172,21 @@ def plan_cleanup(
160
172
  if depth >= max_depth:
161
173
  problem(node, "DEPTH_LIMIT_REACHED")
162
174
  else:
163
- names = []
175
+ children = []
164
176
  with os.scandir(absolute) as entries:
165
- for entry in entries:
166
- if examined + len(names) >= max_entries:
177
+ for child_entry in entries:
178
+ if examined + len(children) >= max_entries:
167
179
  problem(node, "ENTRY_LIMIT_REACHED")
168
180
  break
169
- names.append(entry.name)
170
- for name in sorted(names):
181
+ children.append(child_entry)
182
+ for child_entry in sorted(children, key=lambda item: item.name):
171
183
  if examined >= max_entries:
172
184
  problem(node, "ENTRY_LIMIT_REACHED")
173
185
  break
186
+ name = child_entry.name
174
187
  examined += 1
175
188
  child = visit(name if relative == "." else relative + "/" + name,
176
- depth + 1)
189
+ depth + 1, child_entry)
177
190
  node.children.append(child)
178
191
  node.files.update(child.files)
179
192
  node.complete &= child.complete
@@ -206,6 +219,12 @@ def plan_cleanup(
206
219
  parts = path.split("/")
207
220
  tracked_ancestors.update("/".join(parts[:i]) for i in range(1, len(parts)))
208
221
 
222
+ def git_ignored(workspace, absolute):
223
+ return os.path.relpath(absolute, root).replace(os.sep, "/") in ignored
224
+
225
+ def regenerable(specs, context):
226
+ return policy._regenerable(specs, context, git_ignored)
227
+
209
228
  def row(node: _Node, category: str, reason: str) -> Dict[str, Any]:
210
229
  result = {
211
230
  "path": node.path, "kind": node.kind, "category": category,
@@ -220,7 +239,10 @@ def plan_cleanup(
220
239
  # Concrete, relative spelling also used by the execution CLI.
221
240
  spelling = "./" + node.path
222
241
  specs = classifier.classify_paths([spelling], root, root, trash)
223
- verdict = policy.decide_path_batch(specs, ctx, recursive=True)
242
+ verdict = policy._decide_path_batch(
243
+ specs, ctx, recursive=True,
244
+ config_loader=lambda workspace: delete_config,
245
+ regenerable_check=regenerable)
224
246
  result["policy_code"] = verdict.code
225
247
  literal = (not specs[0].wildcard and not specs[0].indeterminable
226
248
  and specs[0].resolved == os.path.join(root, node.path))