@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 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,14 +4,15 @@
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.7](https://img.shields.io/badge/version-0.2.7-5B6B7A)](docs/releases/release-notes-0.2.7.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
- **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
9
+ **Disclosure checks · Recoverable deletion · Agent experiments** · [简体中文](README.zh-CN.md)
10
10
 
11
- Agent Guard preserves recovery data before supported destructive actions,
12
- checks text before sending it, and provides a Lab for testing agent and host
13
- behaviour. The shared Python Core can be called through command-line tools
14
- or host adapters.
11
+ Agent Guard has three main capabilities: **Exfil-guard** checks text before
12
+ sending it, **Delete-guard** preserves recovery data before supported destructive
13
+ actions, and **Guard-lab** tests agent and host behaviour through controlled
14
+ experiments. A shared Python Core supports the command-line tools and optional
15
+ host adapters.
15
16
 
16
17
  **AI agents setting up this project:** Before changing configuration or writing
17
18
  a bridge, read the [integration requirements](adapters/INTEGRATION.md), then
@@ -23,18 +24,24 @@ Installed Skills or copied configuration alone do not establish protection.
23
24
  We currently focus on **DSH and Kimi Code** integrations. For other hosts,
24
25
  ask the official coding agent to configure Agent Guard locally.
25
26
 
26
- This documentation covers [0.2.7](docs/releases/release-notes-0.2.7.md), adding
27
- Cleanup plans, deletion admission limits and optional local MCP tools.
28
- Check the exact-version release channels below before installing.
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.
29
34
 
30
- | Capability | What it helps you do | Entry |
35
+ | Main capability | Included functions | Guides |
31
36
  |---|---|---|
32
- | **Recovery protection** | Relocate valuable files before deletion; snapshot tracked state before supported Git overwrites; inspect and restore transactions | [delete-guard](skills/delete-guard/SKILL.md) |
33
- | **Cleanup proposals (0.2.7)** | Review classified workspace candidates, sizes and effects; explicitly confirm selected targets before safe_delete | [Cleanup Copilot](docs/guides/cleanup-plan.md) |
34
- | **Deletion limits (0.2.7)** | Inspect shared protected paths, persistent budgets, rate/repeat limits and large-batch confirmation | [Limits and recovery](docs/guides/deletion-limits.md) |
35
- | **Local MCP tools (0.2.7)** | Call safe_delete, ordinary restore, transaction/status queries and GC preview from a supporting client | [MCP setup](docs/guides/mcp.md) |
36
- | **Disclosure checks** | Detect supported credentials and host-identifying paths; apply a redaction plan or withhold a payload | [exfil-guard](skills/exfil-guard/SKILL.md) |
37
- | **Behaviour experiments** | Calibrate an observer, test a declared exposure channel, then compare matched guard-off/on trials | [guard-lab](docs/lab/guard-lab.md) |
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) |
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) |
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) |
40
+
41
+ Cleanup Copilot, deletion limits and the current MCP tools/doctor belong to
42
+ **Delete-guard**. Core and adapters provide shared infrastructure;
43
+ [recovery-audit](skills/recovery-audit/SKILL.md) supplies an auxiliary workflow
44
+ for reconstructing a workspace and auditing recovery after an incident.
38
45
 
39
46
  A Skill supplies instructions; it does not intercept tool calls. Automatic
40
47
  protection depends on an active, compatible host hook and its covered tools.
@@ -112,28 +119,30 @@ The optional MCP adapter requires Python 3.10+ and a separately installed
112
119
 
113
120
  | Version | Status |
114
121
  |---|---|
115
- | [0.2.7](docs/releases/release-notes-0.2.7.md) | Version documented here; 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 |
124
+ | [0.2.7](docs/releases/release-notes-0.2.7.md) | Earlier release with Cleanup, deletion limits and local MCP tools |
116
125
  | [0.2.6](docs/releases/release-notes-0.2.6.md) | Earlier published release with Kimi feedback and host compatibility updates |
117
126
  | [0.2.5](docs/releases/release-notes-0.2.5.md) | Earlier stable release |
118
127
  | [0.2.4](docs/releases/release-notes-0.2.4.md) | Earlier stable release |
119
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` |
120
129
  | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | Published prerelease, including RC1/RC2 maintenance; npm `rc` |
121
130
 
122
- Before installing 0.2.7, confirm availability through its exact
123
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
124
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7).
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).
125
134
  A checkout or manifest alone does not establish package availability.
126
135
 
127
136
  If that version is unavailable, use reviewed source or a locally built
128
- tarball following the [version notes](docs/releases/release-notes-0.2.7.md).
129
- Versioned tests and package checks are recorded separately from the historical
130
- 0.2.6-metadata source results. Existing successful deletes can newly be
131
- refused by the [admission limits](docs/guides/deletion-limits.md).
137
+ tarball following the [version notes](docs/releases/release-notes-0.2.9.md).
138
+ Versioned tests and package checks retain their original checkpoints.
139
+ The [admission limits](docs/guides/deletion-limits.md) introduced in 0.2.7 can
140
+ refuse previously successful deletions and remain in effect in 0.2.9.
132
141
 
133
142
  Once the exact version is available, install to a chosen, stable user-owned prefix:
134
143
 
135
144
  ```sh
136
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
145
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
137
146
  ```
138
147
 
139
148
  The package root is
@@ -252,7 +261,8 @@ tool paths. Other combinations need their own checks.
252
261
  | Claude Code | Retained reference; new version validation paused. Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
253
262
  | Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. Version 0.2.6 adds 2.3.0 prompt/ACP root-Bash evidence with fixed responses. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
254
263
  | DSH | Default deletion paths on 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4. Optional native read and Lab retain their two-version boundaries. [Compatibility](docs/design/dsh-compatibility.md) · [Setup](adapters/dsh/README.md) |
255
- | Codex / other hosts | Use the official coding agent for version-specific local hook setup; verify blocking before claiming native interception. Without a blocking hook, explicit Skill/CLI remains cooperative. [Adaptation guide](adapters/INTEGRATION.md) |
264
+ | Codex | Codex 0.165.0 exercised published 0.2.7 through actual-client and real-model MCP trials. This covers explicit tools; native Shell/editor interception needs separate verification. [MCP evidence and limits](docs/guides/mcp.md#codex-01650-with-published-027) |
265
+ | Other hosts | Use the official coding agent for version-specific local setup; verify blocking before claiming native interception. Explicit Skill/CLI/MCP use remains cooperative without a blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
256
266
 
257
267
  Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
258
268
  for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
@@ -282,7 +292,7 @@ reconstruction and known gaps. It cannot recreate bytes that no source kept.
282
292
  | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
283
293
  | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
284
294
  | [Blue-team research](docs/research/README.md) | Defensive methods, sanitized results and a zero-model starting point |
285
- | [0.2.7 notes](docs/releases/release-notes-0.2.7.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 |
286
296
 
287
297
  ## Contributing
288
298
 
package/README.zh-CN.md CHANGED
@@ -4,13 +4,13 @@
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.7](https://img.shields.io/badge/version-0.2.7-5B6B7A)](docs/releases/release-notes-0.2.7.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
- **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
9
+ **外发检查 · 可恢复删除 · Agent 验测** · [English](README.md)
10
10
 
11
- Agent Guard 在受支持的删除、覆盖操作前保留恢复数据,检查待外发文本中的
12
- 敏感信息,并提供 Lab 来测试 Agent 和宿主的实际行为。共享 Python Core
13
- 可通过命令行工具或宿主适配器调用。
11
+ Agent Guard 提供三大功能:**Exfil-guard** 检查待外发文本,**Delete-guard**
12
+ 在受支持的破坏性操作前保留恢复数据,**Guard-lab** 通过受控实验测试 Agent
13
+ 和宿主的实际行为。共享 Python Core 支撑命令行工具与可选宿主适配器。
14
14
 
15
15
  **负责接入本项目的 AI agent:** 修改配置或编写桥接前,必须先读取
16
16
  [适配要求](adapters/INTEGRATION.md),再阅读
@@ -21,17 +21,21 @@ Agent Guard 在受支持的删除、覆盖操作前保留恢复数据,检查
21
21
  目前主要维护 **DSH 和 Kimi Code** 的接入。其他宿主建议交给对应的官方
22
22
  编码 Agent 在本地配置。
23
23
 
24
- 本文档覆盖 [0.2.7](docs/releases/release-notes-0.2.7.md),新增 Cleanup 计划、
25
- 删除准入限制与可选本地 MCP 工具。安装前请通过下方精确版本渠道确认可用性。
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 包是否可用。
26
29
 
27
- | 能力 | 能帮助你做什么 | 入口 |
30
+ | 主要功能 | 下属功能 | 对应链接 |
28
31
  |---|---|---|
29
- | **恢复保护** | 删除前迁移有价值的文件;受支持的 Git 覆盖前快照 tracked 状态;查询和恢复事务 | [delete-guard](skills/delete-guard/SKILL.md) |
30
- | **清理提议(0.2.7)** | 扫描候选、分类、大小与实际执行方式;显式选择并确认后交给 safe_delete | [Cleanup Copilot](docs/guides/cleanup-plan.md) |
31
- | **删除限制(0.2.7)** | 查询共享保护路径、持久预算、速率/重复限制与大批量确认 | [限制与恢复](docs/guides/deletion-limits.md) |
32
- | **本地 MCP 工具(0.2.7)** | 在支持的客户端中调用 safe_delete、普通恢复、事务/状态查询和 GC 预览 | [MCP 接入](docs/guides/mcp.md) |
33
- | **外发检测** | 检测受支持的凭据和本机标识路径;应用脱敏计划或拒绝输出 | [exfil-guard](skills/exfil-guard/SKILL.md) |
34
- | **行为验测** | 校准观察器,验证声明信道的暴露,再比较匹配的关闭/开启防护试次 | [guard-lab](docs/lab/guard-lab.md) |
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) |
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) |
34
+ | **Guard-lab** | 四项零模型校准对照;合成标记与声明信道观察;证据和观察器健康检查;有效基线成立后的关闭/开启防护配对比较 | [Lab 流程](docs/lab/guard-lab.md) · [四控制示例](docs/lab/blue-team-calibration.md) · [证据等级](docs/lab/guard-lab.md#evidence-levels) |
35
+
36
+ Cleanup Copilot、删除限制以及当前 MCP 工具/doctor 均归属 **Delete-guard**。
37
+ Core 与适配器提供共享基础设施;[recovery-audit](skills/recovery-audit/SKILL.md)
38
+ 提供事故后的工作区重建与恢复审计辅助流程。
35
39
 
36
40
  Skill 提供操作纪律,不会自行拦截工具调用。自动保护依赖宿主实际加载了
37
41
  兼容 hook,且调用位于其覆盖范围内。Agent Guard 不是抵抗同权限恶意进程的
@@ -96,26 +100,29 @@ Core 需要 Python 3.9+ 和 Git。示例采用 POSIX Shell;原生桥接和可
96
100
 
97
101
  | 版本 | 状态 |
98
102
  |---|---|
99
- | [0.2.7](docs/releases/release-notes-0.2.7.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 接入诊断与恢复验证 |
105
+ | [0.2.7](docs/releases/release-notes-0.2.7.md) | 历史版本,包含 Cleanup、删除限制与本地 MCP 工具 |
100
106
  | [0.2.6](docs/releases/release-notes-0.2.6.md) | 历史已发布版本,包含 Kimi 反馈与宿主兼容性更新 |
101
107
  | [0.2.5](docs/releases/release-notes-0.2.5.md) | 更早稳定版 |
102
108
  | [0.2.4](docs/releases/release-notes-0.2.4.md) | 更早稳定版 |
103
109
  | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 显式选择的回收站保护回补;npm `hotfix` |
104
110
  | [0.2.5-rc3](docs/releases/release-notes-0.2.5-rc3.md) | 已发布预发布版,包含 RC1/RC2 维护;npm `rc` |
105
111
 
106
- 安装 0.2.7 前,请通过精确版本的
107
- [GitHub Release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)和
108
- [npm 版本页](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)确认可用性,
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)确认可用性,
109
115
  checkout 或 manifest 本身不代表包已可安装。
110
116
 
111
- 若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.7.md)使用经复核的
112
- 源码或本地构建 tarball。版本化测试和包核验已单独记录,不能沿用旧 0.2.6 元数据
113
- 候选的通过结论。此前可执行的删除可能被新的[准入限制](docs/guides/deletion-limits.md)拒绝。
117
+ 若该版本尚不可用,请按[版本说明](docs/releases/release-notes-0.2.9.md)使用经复核的
118
+ 源码或本地构建 tarball。版本化测试和包核验保留各自检查点。
119
+ 自 0.2.7 引入的[准入限制](docs/guides/deletion-limits.md)可能拒绝此前可执行的删除,
120
+ 这些限制在 0.2.9 中继续生效。
114
121
 
115
122
  确认精确版本可用后,可安装到用户选定的长期目录:
116
123
 
117
124
  ```sh
118
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
125
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
119
126
  ```
120
127
 
121
128
  包根目录是
@@ -216,7 +223,8 @@ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
216
223
  | Claude Code | 保留参考实现,暂缓新版本验收。Bash 原生 `PreToolUse`;2.1.270/2.1.273 的受限脚本宿主拦截记录。[接入](adapters/claude/README.md) |
217
224
  | Kimi Code | Bash 原生 `PreToolUse`;0.42.0 的有限主/子路径及 2.1.1 的根代理 Bash 记录。0.2.6 新增 2.3.0 prompt/ACP 根代理 Bash 固定响应证据。ASK 拒绝;缺失/超时 hook 不覆盖。[接入](adapters/kimi-code/README.md) |
218
225
  | DSH | 默认删除适配覆盖 0.1.5-rc.1/0.2.0-rc.2/0.2.1-alpha.4。可选原生 read 与 Lab 保留各自的两版边界。[兼容范围](docs/design/dsh-compatibility.md) · [接入](adapters/dsh/README.md) |
219
- | Codex/其他宿主 | 推荐官方 Agent 按当前版本完成本地 hook 接入,并验证确实阻止执行。没有阻塞 hook 时,Skill/CLI 仍属于协作式使用。[适配指南](adapters/INTEGRATION.md) |
226
+ | Codex | Codex 0.165.0 已通过已发布 0.2.7 的实际客户端与真实模型 MCP 试次。证据覆盖显式工具;原生 Shell/编辑器拦截仍需单独验证。[MCP 证据与限制](docs/guides/mcp.md#codex-01650-with-published-027) |
227
+ | 其他宿主 | 推荐官方 Agent 按当前版本完成本地接入,并验证确实阻止执行后再声明原生拦截。没有阻塞 hook 时,Skill/CLI/MCP 仍属于协作式使用。[适配指南](adapters/INTEGRATION.md) |
220
228
 
221
229
  精确版本、试验与缺口统一见[完整能力矩阵](docs/guides/harness-capabilities.md)。
222
230
  `doctor.py kimi|claude --probe` 只检查选定配置和本地适配路径;PASS 不证明
@@ -244,7 +252,7 @@ Git/会话/缓存证据恢复项目,区分原文、重建与确认缺失
244
252
  | [威胁模型](docs/design/threat-model.md) | 信任假设与尚未解决的边界 |
245
253
  | [兼容契约](docs/design/compatibility.md) | 接口与发布约定 |
246
254
  | [蓝队研究](docs/research/README.md) | 防守方法、去敏结果与零模型起点 |
247
- | [0.2.7 说明](docs/releases/release-notes-0.2.7.md) | 版本范围、升级影响与验证边界 |
255
+ | [0.2.9 说明](docs/releases/release-notes-0.2.9.md) | 清理盘点、扫描提速与升级说明 |
248
256
 
249
257
  ## 参与贡献
250
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
@@ -0,0 +1,326 @@
1
+ """Read-only diagnostics for one explicitly selected local MCP service.
2
+
3
+ Only the selected child interpreter needs the optional SDK. This module is
4
+ stdlib-only so the ordinary doctor and its help remain usable without it.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import json
9
+ import math
10
+ import os
11
+ from pathlib import Path
12
+ import queue
13
+ import shutil
14
+ import subprocess
15
+ import sys
16
+ import tempfile
17
+ import threading
18
+ import time
19
+
20
+
21
+ ROOT = Path(__file__).resolve().parents[2]
22
+ SERVER = ROOT / "adapters/mcp/server.py"
23
+ SDK_VERSION = "2.3.0"
24
+ PROTOCOL_VERSION = "2025-06-18"
25
+ TOOLS = frozenset(("safe_delete", "restore", "transactions", "status", "gc_plan", "cleanup_discover", "cleanup_measure"))
26
+ READ_ONLY = ("status", "transactions", "gc_plan")
27
+ READ_ONLY_TOOLS = frozenset(READ_ONLY) | {"cleanup_discover", "cleanup_measure"}
28
+ MAX_MESSAGE_BYTES = 2 * 1024 * 1024
29
+
30
+ PROBLEMS = {
31
+ "MCP_DOCTOR_WORKSPACE": ("Select an existing non-root workspace directory.",
32
+ "Check the requested workspace path before reconnecting."),
33
+ "MCP_DOCTOR_SERVER": ("The selected server script is unavailable.",
34
+ "Select the reviewed agent-guard adapters/mcp/server.py file."),
35
+ "MCP_DOCTOR_PYTHON": ("The selected Python executable could not start.",
36
+ "Check the selected interpreter path and execution permission."),
37
+ "MCP_DOCTOR_SDK_MISSING": ("The optional MCP SDK is not installed in the selected interpreter.",
38
+ "Use a separate environment with adapters/mcp/requirements.txt."),
39
+ "MCP_DOCTOR_SDK_VERSION": ("The selected interpreter has an unsupported MCP SDK version.",
40
+ "Use the pinned SDK from adapters/mcp/requirements.txt."),
41
+ "MCP_DOCTOR_SDK_IMPORT": ("The selected interpreter could not import the MCP SDK dependencies.",
42
+ "Check that the selected SDK environment is complete and runnable."),
43
+ "MCP_DOCTOR_SDK_CHECK": ("The selected interpreter did not complete the SDK check.",
44
+ "Check the interpreter and its installed environment directly."),
45
+ "MCP_DOCTOR_STARTUP": ("The selected service could not start.",
46
+ "Check the reviewed server script and selected interpreter."),
47
+ "MCP_DOCTOR_TIMEOUT": ("The diagnostic deadline expired.",
48
+ "Inspect the failed stage and service startup; reconnect explicitly after investigation."),
49
+ "MCP_DOCTOR_EOF": ("The service closed its protocol output before completing the check.",
50
+ "Inspect the selected service startup and optional SDK environment."),
51
+ "MCP_DOCTOR_PROTOCOL": ("The service returned an invalid or unsupported protocol response.",
52
+ "Use the reviewed agent-guard stdio service; stdout must contain protocol messages only."),
53
+ "MCP_DOCTOR_IDENTITY": ("The service identity or version does not match this installation.",
54
+ "Select a server script from the same agent-guard version as this doctor."),
55
+ "MCP_DOCTOR_TOOLS": ("The service tool set or read-only annotations do not match this installation's contract.",
56
+ "Check the selected service version and tool definitions."),
57
+ "MCP_DOCTOR_QUERY": ("A read-only tool returned an unsuccessful or invalid result.",
58
+ "Inspect the failed tool and local recovery state before any mutation."),
59
+ "MCP_DOCTOR_BINDING": ("The service status does not match the requested workspace and quarantine.",
60
+ "Correct the trusted service workspace binding before using its tools."),
61
+ }
62
+
63
+
64
+ class _Failure(Exception):
65
+ def __init__(self, code):
66
+ self.code = code
67
+
68
+
69
+ def _remaining(deadline):
70
+ remaining = deadline - time.monotonic()
71
+ if remaining <= 0:
72
+ raise _Failure("MCP_DOCTOR_TIMEOUT")
73
+ return remaining
74
+
75
+
76
+ def _environment():
77
+ env = {key: value for key, value in os.environ.items()
78
+ if not key.startswith(("AGENT_GUARD_", "GIT_"))
79
+ and key not in ("PYTHONPATH", "PYTHONHOME")}
80
+ env["PYTHONDONTWRITEBYTECODE"] = "1"
81
+ return env
82
+
83
+
84
+ def _check_sdk(python, deadline, env, diagnostics):
85
+ # Fixed exit codes avoid exposing import exceptions, paths or environment
86
+ # contents. This is a trusted interpreter, not a sandbox for hostile code.
87
+ code = (
88
+ "import importlib.metadata, sys\n"
89
+ "try: version = importlib.metadata.version('mcp')\n"
90
+ "except importlib.metadata.PackageNotFoundError: sys.exit(10)\n"
91
+ "if version != '2.3.0': sys.exit(11)\n"
92
+ "try: import mcp.server, mcp.server.stdio, mcp_types, anyio\n"
93
+ "except (ImportError, OSError): sys.exit(12)\n"
94
+ )
95
+ try:
96
+ child = subprocess.run([python, "-B", "-c", code], cwd=ROOT, env=env,
97
+ stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
98
+ stderr=diagnostics, timeout=_remaining(deadline), shell=False)
99
+ except subprocess.TimeoutExpired:
100
+ raise _Failure("MCP_DOCTOR_TIMEOUT") from None
101
+ except OSError:
102
+ raise _Failure("MCP_DOCTOR_PYTHON") from None
103
+ if child.returncode:
104
+ raise _Failure({10: "MCP_DOCTOR_SDK_MISSING", 11: "MCP_DOCTOR_SDK_VERSION",
105
+ 12: "MCP_DOCTOR_SDK_IMPORT"}.get(child.returncode, "MCP_DOCTOR_SDK_CHECK"))
106
+
107
+
108
+ class _Connection:
109
+ def __init__(self, python, server, workspace, env, deadline, diagnostics):
110
+ self.deadline = deadline
111
+ self.counter = 0
112
+ self.messages = queue.Queue(maxsize=8)
113
+ self.stopped = threading.Event()
114
+ try:
115
+ self.child = subprocess.Popen([python, "-B", str(server), "--workspace", str(workspace)],
116
+ cwd=workspace, env=env, stdin=subprocess.PIPE,
117
+ stdout=subprocess.PIPE, stderr=diagnostics, shell=False)
118
+ except OSError:
119
+ raise _Failure("MCP_DOCTOR_STARTUP") from None
120
+
121
+ def enqueue(value):
122
+ while not self.stopped.is_set():
123
+ try:
124
+ self.messages.put(value, timeout=0.1)
125
+ return
126
+ except queue.Full:
127
+ continue
128
+
129
+ def read():
130
+ while not self.stopped.is_set():
131
+ line = self.child.stdout.readline(MAX_MESSAGE_BYTES + 1)
132
+ if not line:
133
+ enqueue(_Failure("MCP_DOCTOR_EOF"))
134
+ return
135
+ if len(line) > MAX_MESSAGE_BYTES or not line.endswith(b"\n"):
136
+ enqueue(_Failure("MCP_DOCTOR_PROTOCOL"))
137
+ return
138
+ try:
139
+ value = json.loads(line.decode("utf-8"))
140
+ except (UnicodeError, ValueError, RecursionError):
141
+ enqueue(_Failure("MCP_DOCTOR_PROTOCOL"))
142
+ return
143
+ enqueue(value)
144
+
145
+ self.reader = threading.Thread(target=read, daemon=True)
146
+ self.reader.start()
147
+
148
+ def send(self, value):
149
+ _remaining(self.deadline)
150
+ try:
151
+ self.child.stdin.write((json.dumps(value) + "\n").encode("utf-8"))
152
+ self.child.stdin.flush()
153
+ except (OSError, ValueError):
154
+ raise _Failure("MCP_DOCTOR_EOF") from None
155
+
156
+ def request(self, method, params):
157
+ self.counter += 1
158
+ self.send({"jsonrpc": "2.0", "id": self.counter, "method": method, "params": params})
159
+ # The selected service does not need client-side tools, sampling or
160
+ # approval. Notifications may occur but cannot extend the deadline.
161
+ for _ in range(32):
162
+ try:
163
+ value = self.messages.get(timeout=_remaining(self.deadline))
164
+ except queue.Empty:
165
+ raise _Failure("MCP_DOCTOR_TIMEOUT") from None
166
+ if isinstance(value, _Failure):
167
+ raise value
168
+ if not isinstance(value, dict) or value.get("jsonrpc") != "2.0":
169
+ raise _Failure("MCP_DOCTOR_PROTOCOL")
170
+ if "id" not in value and isinstance(value.get("method"), str):
171
+ if value["method"].startswith("notifications/"):
172
+ continue
173
+ if type(value.get("id")) is not int or value["id"] != self.counter or "error" in value:
174
+ raise _Failure("MCP_DOCTOR_PROTOCOL")
175
+ if "method" in value or not isinstance(value.get("result"), dict):
176
+ raise _Failure("MCP_DOCTOR_PROTOCOL")
177
+ return value["result"]
178
+ raise _Failure("MCP_DOCTOR_PROTOCOL")
179
+
180
+ def close(self):
181
+ self.stopped.set()
182
+ try:
183
+ self.child.stdin.close()
184
+ except OSError:
185
+ pass
186
+ try:
187
+ self.child.wait(timeout=1)
188
+ except subprocess.TimeoutExpired:
189
+ self.child.terminate()
190
+ try:
191
+ self.child.wait(timeout=1)
192
+ except subprocess.TimeoutExpired:
193
+ self.child.kill()
194
+ self.child.wait(timeout=1)
195
+ self.child.stdout.close()
196
+ self.reader.join(timeout=1)
197
+
198
+
199
+ def _tool_result(value, name):
200
+ content = value.get("structuredContent")
201
+ if (value.get("isError", False) is not False or not isinstance(content, dict)
202
+ or content.get("tool") != name or content.get("ok") is not True
203
+ or type(content.get("exit_code")) is not int or content["exit_code"] != 0
204
+ or not isinstance(content.get("result"), dict)):
205
+ raise _Failure("MCP_DOCTOR_QUERY")
206
+ return content["result"]
207
+
208
+
209
+ def diagnose(python, workspace, *, server=None, timeout=30):
210
+ """Check a trusted local service, without returning its private responses.
211
+
212
+ ``timeout`` is the total diagnostic deadline (5..120 seconds); closing
213
+ this invocation's own service can add three seconds of process waits
214
+ and one second waiting for its reader thread.
215
+ Python paths retain their symlink spelling so virtual environments work.
216
+ """
217
+ if type(timeout) not in (int, float) or not math.isfinite(timeout) or not 5 <= timeout <= 120:
218
+ raise ValueError("MCP doctor timeout must be from 5 to 120 seconds")
219
+ python = os.fspath(python)
220
+ if not python or "\0" in python:
221
+ raise ValueError("MCP doctor needs a nonempty interpreter")
222
+ python = os.path.expanduser(python)
223
+ if os.path.dirname(python):
224
+ python = os.path.abspath(python)
225
+ else:
226
+ python = shutil.which(python) or python
227
+ expected_version = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["version"]
228
+ report = {"schema_version": 1, "harness": "mcp", "status": "FAIL", "stage": "workspace",
229
+ "checks": [], "host_connection": "UNVERIFIED", "model_delivery": "UNVERIFIED",
230
+ "host_interception": "UNVERIFIED"}
231
+ stage = "workspace"
232
+ connection = None
233
+ deadline = time.monotonic() + timeout
234
+ with tempfile.TemporaryFile() as diagnostics:
235
+ try:
236
+ try:
237
+ selected = Path(workspace).expanduser().resolve(strict=True)
238
+ valid = selected.is_dir() and selected.parent != selected
239
+ except (OSError, ValueError):
240
+ valid = False
241
+ if not valid:
242
+ raise _Failure("MCP_DOCTOR_WORKSPACE")
243
+ report["checks"].append({"stage": stage, "status": "PASS"})
244
+ stage = "server"
245
+ try:
246
+ selected_server = Path(server if server is not None else SERVER).expanduser().absolute()
247
+ valid = selected_server.is_file()
248
+ except (OSError, ValueError):
249
+ valid = False
250
+ if not valid:
251
+ raise _Failure("MCP_DOCTOR_SERVER")
252
+ report["checks"].append({"stage": stage, "status": "PASS"})
253
+ env = _environment()
254
+ stage = "sdk"
255
+ _check_sdk(python, deadline, env, diagnostics)
256
+ report["sdk_version"] = SDK_VERSION
257
+ report["checks"].append({"stage": stage, "status": "PASS"})
258
+ stage = "initialize"
259
+ connection = _Connection(python, selected_server, selected, env, deadline, diagnostics)
260
+ initialized = connection.request("initialize", {"protocolVersion": PROTOCOL_VERSION,
261
+ "capabilities": {}, "clientInfo": {"name": "agent-guard-doctor", "version": expected_version}})
262
+ identity = initialized.get("serverInfo")
263
+ if (not isinstance(identity, dict) or identity.get("name") != "agent-guard"
264
+ or identity.get("version") != expected_version):
265
+ raise _Failure("MCP_DOCTOR_IDENTITY")
266
+ if initialized.get("protocolVersion") != PROTOCOL_VERSION:
267
+ raise _Failure("MCP_DOCTOR_PROTOCOL")
268
+ connection.send({"jsonrpc": "2.0", "method": "notifications/initialized"})
269
+ report["server"] = {"name": "agent-guard", "version": expected_version,
270
+ "protocol_version": PROTOCOL_VERSION}
271
+ report["checks"].append({"stage": stage, "status": "PASS"})
272
+ stage = "tools"
273
+ listing = connection.request("tools/list", {})
274
+ tools = listing.get("tools")
275
+ if (not isinstance(tools, list) or len(tools) != len(TOOLS)
276
+ or any(not isinstance(tool, dict) or not isinstance(tool.get("name"), str) for tool in tools)
277
+ or {tool["name"] for tool in tools} != TOOLS or listing.get("nextCursor") is not None):
278
+ raise _Failure("MCP_DOCTOR_TOOLS")
279
+ for tool in tools:
280
+ annotations = tool.get("annotations")
281
+ if (not isinstance(annotations, dict) or
282
+ annotations.get("readOnlyHint") is not (tool["name"] in READ_ONLY_TOOLS)):
283
+ raise _Failure("MCP_DOCTOR_TOOLS")
284
+ report["tools"] = sorted(TOOLS)
285
+ report["checks"].append({"stage": stage, "status": "PASS"})
286
+ for name in READ_ONLY:
287
+ stage = name
288
+ result = _tool_result(connection.request("tools/call", {
289
+ "name": name, "arguments": {"tail": 0} if name == "status" else {}}), name)
290
+ if name == "status":
291
+ if (result.get("workspace") != str(selected)
292
+ or result.get("trash_root") != str(selected / ".agent-trash")):
293
+ raise _Failure("MCP_DOCTOR_BINDING")
294
+ admission = result.get("delete_admission")
295
+ if not isinstance(admission, dict):
296
+ raise _Failure("MCP_DOCTOR_QUERY")
297
+ report["deletion_admission"] = "BLOCKED" if admission.get("status") == "BLOCKED" else "READABLE"
298
+ elif name == "transactions" and not isinstance(result.get("transactions"), list):
299
+ raise _Failure("MCP_DOCTOR_QUERY")
300
+ elif name == "gc_plan" and (result.get("mode") != "plan" or not isinstance(result.get("eligible"), list)):
301
+ raise _Failure("MCP_DOCTOR_QUERY")
302
+ report["checks"].append({"stage": stage, "status": "PASS"})
303
+ report.update(status="PASS", stage="complete", code="MCP_DOCTOR_READY",
304
+ message="The selected local service passed handshake, binding and read-only tool checks.",
305
+ guidance="Inspect the actual client's MCP connection and permissions before using its tools.")
306
+ except _Failure as failure:
307
+ message, guidance = PROBLEMS[failure.code]
308
+ report.update(stage=stage, code=failure.code, message=message, guidance=guidance)
309
+ report["checks"].append({"stage": stage, "status": "FAIL", "code": failure.code})
310
+ finally:
311
+ if connection is not None:
312
+ connection.close()
313
+ diagnostics.flush()
314
+ report["diagnostic_stderr_bytes"] = diagnostics.tell()
315
+ return report
316
+
317
+
318
+ def render(report):
319
+ """Render only fixed report fields; private MCP tool content is absent."""
320
+ lines = [report["status"] + ": " + report["code"], report["message"]]
321
+ lines.extend(" " + check["stage"] + ": " + check["status"] for check in report["checks"])
322
+ if report.get("deletion_admission") == "BLOCKED":
323
+ lines.append("DELETION_ADMISSION: BLOCKED (connection checks do not grant deletion permission)")
324
+ lines.extend([report["guidance"],
325
+ "HOST_CONNECTION: UNVERIFIED; MODEL_DELIVERY: UNVERIFIED; HOST_INTERCEPTION: UNVERIFIED"])
326
+ return "\n".join(lines) + "\n"