@mokuyoaxis/agent-guard 0.2.7 → 0.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +34 -27
- package/README.zh-CN.md +30 -24
- package/adapters/mcp/doctor.py +325 -0
- package/docs/README.md +29 -13
- package/docs/design/architecture.md +33 -14
- package/docs/design/compatibility.md +69 -4
- package/docs/guides/getting-started.md +7 -6
- package/docs/guides/harness-capabilities.md +14 -4
- package/docs/guides/mcp.md +136 -9
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +44 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +1 -1
package/docs/README.md
CHANGED
|
@@ -1,16 +1,27 @@
|
|
|
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.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and
|
|
20
|
+
recovery validation to the [0.2.7](releases/release-notes-0.2.7.md) baseline
|
|
21
|
+
of Cleanup plans, deletion admission and optional local MCP tools.
|
|
22
|
+
Before installing 0.2.8,
|
|
23
|
+
check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
24
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
14
25
|
for availability. A checkout or manifest does not establish publication or
|
|
15
26
|
the current npm `latest` channel.
|
|
16
27
|
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
@@ -23,7 +34,8 @@ its doctor checks, Kimi 2.3.0 root-Bash compatibility, DSH Lab preflight
|
|
|
23
34
|
diagnostics and alpha.4 default deletion compatibility. Existing 0.2.5 installations
|
|
24
35
|
need an upgrade to acquire those additions; see its [version notes](releases/release-notes-0.2.6.md).
|
|
25
36
|
|
|
26
|
-
|
|
37
|
+
先看入门指南,再按 Exfil-guard、Delete-guard、Guard-lab 三大功能选择入口。
|
|
38
|
+
Cleanup、删除限制与当前 MCP 工具/doctor 归入 Delete-guard。测试报告按所测版本与配置保留;发布记录、
|
|
27
39
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
28
40
|
|
|
29
41
|
| Category / 分类 | Contents / 内容 |
|
|
@@ -45,9 +57,10 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
45
57
|
|---|---|
|
|
46
58
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
47
59
|
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
48
|
-
| [Cleanup Copilot](guides/cleanup-plan.md) | 0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
49
|
-
| [Deletion limits](guides/deletion-limits.md) | 0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
|
|
50
|
-
| [Local MCP tools](guides/mcp.md) | 0.2.7
|
|
60
|
+
| [Cleanup Copilot](guides/cleanup-plan.md) | Delete-guard,0.2.7:零写入计划、四类候选、大小与显式确认执行 |
|
|
61
|
+
| [Deletion limits](guides/deletion-limits.md) | Delete-guard,0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
|
|
62
|
+
| [Local MCP tools](guides/mcp.md) | Delete-guard,0.2.7:本地 stdio 安全删除、普通恢复、事务/状态和 GC 预览;不替代 hook |
|
|
63
|
+
| [MCP diagnosis](guides/mcp.md#diagnose-a-local-service-028) | Delete-guard,0.2.8:选定本地服务的依赖、握手、工作区绑定与只读调用检查 |
|
|
51
64
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
52
65
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
53
66
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
@@ -55,7 +68,9 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
|
55
68
|
| [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
|
|
56
69
|
|
|
57
70
|
Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
|
|
58
|
-
|
|
71
|
+
are documented separately for [Exfil-guard](../skills/exfil-guard/SKILL.md) and
|
|
72
|
+
[Delete-guard](../skills/delete-guard/SKILL.md); the [Guard-lab guide](lab/guard-lab.md)
|
|
73
|
+
describes the user-controlled experiment CLI.
|
|
59
74
|
|
|
60
75
|
We currently focus on DSH and Kimi Code. Claude Code's adapter and past
|
|
61
76
|
reports remain available; testing new Claude versions is paused. For other
|
|
@@ -125,9 +140,10 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
125
140
|
|
|
126
141
|
| Document / 文档 | Scope / 范围 |
|
|
127
142
|
|---|---|
|
|
143
|
+
| [0.2.8](releases/release-notes-0.2.8.md) | MCP 接入诊断、真实协议中断验证、安装与验收边界 |
|
|
128
144
|
| [0.2.7](releases/release-notes-0.2.7.md) | Cleanup、删除准入与MCP的版本范围、升级影响和准备阶段验证 |
|
|
129
145
|
| [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
|
|
130
|
-
| [Changes and maintenance details](releases/unreleased.md) | 0.2.7
|
|
146
|
+
| [Changes and maintenance details](releases/unreleased.md) | 0.2.8 维护、0.2.7 范围及 0.2.6 历史,保留原验收边界 |
|
|
131
147
|
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
132
148
|
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
133
149
|
| [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 delegates execution to `safe_delete`; deletion admission applies shared limits; the current MCP adapter exposes deletion/recovery tools and its doctor checks them through read-only 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
|
|---|---|---|
|
|
@@ -305,9 +318,15 @@ order of value:
|
|
|
305
318
|
|
|
306
319
|
## Delivery status and design directions
|
|
307
320
|
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
321
|
+
Version [0.2.8](../releases/release-notes-0.2.8.md) adds MCP connection
|
|
322
|
+
diagnosis and protocol-interruption validation. The existing five tools,
|
|
323
|
+
deletion policy and recovery format
|
|
324
|
+
retain their contracts. Direct-service diagnosis, actual-host connection,
|
|
325
|
+
model use and native interception have separate evidence requirements.
|
|
326
|
+
|
|
327
|
+
Version [0.2.7](../releases/release-notes-0.2.7.md) introduced reviewed Cleanup
|
|
328
|
+
plans, shared deletion admission and optional local MCP tools. Confirm
|
|
329
|
+
availability through the exact GitHub release and npm
|
|
311
330
|
version links in those notes; a source version does not establish publication.
|
|
312
331
|
Earlier stable 0.2.6/0.2.5, opt-in 0.2.4-hotfix.1 and prerelease 0.2.5-rc3
|
|
313
332
|
retain their separate artifacts and evidence.
|
|
@@ -4,9 +4,11 @@ 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.8](../releases/release-notes-0.2.8.md) adds diagnosis and
|
|
8
|
+
reliability maintenance to the published
|
|
9
|
+
[0.2.7](../releases/release-notes-0.2.7.md) baseline. Use exact GitHub release
|
|
10
|
+
and npm version links to confirm availability; a version in source or a local
|
|
11
|
+
tarball does not establish publication.
|
|
10
12
|
Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
|
|
11
13
|
RC maintenance and the feedback/diagnostic additions below. The opt-in
|
|
12
14
|
prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
|
|
@@ -19,6 +21,9 @@ earlier releases.
|
|
|
19
21
|
The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
|
|
20
22
|
optional MCP tools. The bounded versioning decision is recorded below; the
|
|
21
23
|
separate 0.3.0 plan remains paused.
|
|
24
|
+
The later **0.2.8** selection is independently scoped to MCP diagnosis and
|
|
25
|
+
reliability maintenance, as recorded below; earlier exceptions do not grant
|
|
26
|
+
permission to change unrelated policy under a patch number.
|
|
22
27
|
|
|
23
28
|
RC3 publishes defensive research and an example around the existing four
|
|
24
29
|
zero-model controls. Experimental disclosure labels and private delegation
|
|
@@ -28,6 +33,39 @@ is introduced by the research documentation.
|
|
|
28
33
|
|
|
29
34
|
## The adapter contract (frozen surface)
|
|
30
35
|
|
|
36
|
+
<a id="mcp-doctor-028-development"></a>
|
|
37
|
+
|
|
38
|
+
### MCP doctor (0.2.8)
|
|
39
|
+
|
|
40
|
+
`doctor.py mcp` is an explicit local diagnosis path. It accepts the selected
|
|
41
|
+
Python interpreter, existing workspace, optional reviewed server script and
|
|
42
|
+
a diagnostic timeout; it does not parse or rewrite host configuration. It
|
|
43
|
+
checks the optional pinned SDK and its imports, service handshake/name/version,
|
|
44
|
+
the five-tool set and query annotations, workspace/quarantine binding and
|
|
45
|
+
successful status/transactions/gc_plan calls. The selected service version
|
|
46
|
+
must match the doctor's package version. It does not call a model or execute
|
|
47
|
+
deletion, restore, GC or budget-reset tools.
|
|
48
|
+
|
|
49
|
+
Its independent `schema_version: 1` report uses fixed `status`, `stage`, `code`,
|
|
50
|
+
`message`, `guidance` and `checks` fields rather than raw child stderr,
|
|
51
|
+
configuration contents or recovery/audit records. It keeps `host_connection`,
|
|
52
|
+
`model_delivery` and `host_interception` at `UNVERIFIED`: direct service
|
|
53
|
+
diagnosis cannot certify another client's loading or behavior. Exit `0` means
|
|
54
|
+
PASS, `1` means diagnostic failure and `2` remains argument-usage failure.
|
|
55
|
+
Diagnostic codes belong to this report, not the Decision Protocol reason-code
|
|
56
|
+
namespace. Existing Kimi/Claude doctor interfaces retain their semantics.
|
|
57
|
+
`diagnostic_stderr_bytes` is a count, not raw stderr. A successful status check
|
|
58
|
+
also records `deletion_admission` as `BLOCKED` or `READABLE`; the latter means
|
|
59
|
+
the information was inspected, not that deletion is authorized. A connection
|
|
60
|
+
PASS can coexist with blocked admission, which the text renderer highlights.
|
|
61
|
+
The 5–120 second diagnostic deadline defaults to 30 seconds; service-process
|
|
62
|
+
shutdown can add up to three seconds of process waits and one second of reader-thread waiting.
|
|
63
|
+
|
|
64
|
+
The SDK remains separately optional, including when invoking Core/CLI or
|
|
65
|
+
doctor help. Changing package/helper bytes can change existing doctor runtime
|
|
66
|
+
fingerprints and produce `DRIFTED`; an old baseline is not automatically
|
|
67
|
+
replaced. See [options, result scope and recovery after a lost response](../guides/mcp.md#diagnose-a-local-service-028).
|
|
68
|
+
|
|
31
69
|
<a id="local-mcp-tools-027-candidate"></a>
|
|
32
70
|
|
|
33
71
|
### Local MCP tools (0.2.7)
|
|
@@ -55,7 +93,9 @@ and did not run Node; its cause remains undetermined. The second full run
|
|
|
55
93
|
passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
|
|
56
94
|
failures, errors, skips or timeouts. Neither invoked npm directly or changed
|
|
57
95
|
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
|
|
96
|
+
native-MCP trials passed; at that checkpoint Claude/Cursor/Codex setup examples
|
|
97
|
+
were docs-only. Later Codex 0.165.0 acceptance of the published 0.2.7 package
|
|
98
|
+
is recorded separately in the [MCP guide](../guides/mcp.md#codex-01650-with-published-027).
|
|
59
99
|
Without the optional SDK, seven protocol tests skip. The added SDK-backed
|
|
60
100
|
Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
|
|
61
101
|
preparation checkpoint. See
|
|
@@ -233,6 +273,31 @@ While the major version is `0`:
|
|
|
233
273
|
| check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
|
|
234
274
|
| Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
|
|
235
275
|
|
|
276
|
+
<a id="028-diagnosis-maintenance-decision"></a>
|
|
277
|
+
|
|
278
|
+
### 0.2.8: bounded diagnosis maintenance decision
|
|
279
|
+
|
|
280
|
+
The maintainer selected **0.2.8** for the explicit MCP doctor path, real
|
|
281
|
+
protocol-interruption checks and their documentation. Earlier doctor drift
|
|
282
|
+
and live-sentinel additions were classified as minor below. The new optional
|
|
283
|
+
diagnostic surface is carried as this version's bounded maintenance decision;
|
|
284
|
+
the 0.2.7 exception is not inherited and the general release-class promises
|
|
285
|
+
remain in force.
|
|
286
|
+
|
|
287
|
+
The independent MCP doctor parameters, version-1 diagnosis report and exit
|
|
288
|
+
codes are the upgrade-visible additions. Package/helper changes may affect
|
|
289
|
+
existing doctor fingerprints. The five MCP tools and their arguments,
|
|
290
|
+
Decision classes/reasons, default deletion policy, persistent accounting,
|
|
291
|
+
recovery manifests, ordinary restore and preview-only MCP GC retain their
|
|
292
|
+
contracts. No configuration/storage migration or default SDK installation is
|
|
293
|
+
introduced. The diagnosis checks a selected service; it adds no native host
|
|
294
|
+
interception or client configuration management. The 0.3.0 and commercial
|
|
295
|
+
plans are not resumed.
|
|
296
|
+
|
|
297
|
+
Source validation, installed-package and workflow results retain their
|
|
298
|
+
separate checkpoints in the
|
|
299
|
+
[0.2.8 notes](../releases/release-notes-0.2.8.md#validation-status).
|
|
300
|
+
|
|
236
301
|
<a id="027-candidate-bounded-maintainer-selected-exception"></a>
|
|
237
302
|
|
|
238
303
|
### 0.2.7: bounded maintainer-selected exception
|
|
@@ -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.8](../releases/release-notes-0.2.8.md), with MCP
|
|
14
|
+
connection diagnosis and recovery validation, plus the Cleanup plans,
|
|
15
|
+
deletion admission limits and optional tools introduced in 0.2.7. Confirm the
|
|
16
|
+
exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
17
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
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.8
|
|
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.8.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.8](../releases/release-notes-0.2.8.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,19 @@ 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.
|
|
103
113
|
|
|
104
114
|
## Acceptance for each native adapter
|
|
105
115
|
|
package/docs/guides/mcp.md
CHANGED
|
@@ -9,6 +9,12 @@ first full run. They do not certify the new versioned artifact. See the
|
|
|
9
9
|
exact-version availability checks.
|
|
10
10
|
Configuration examples are not host acceptance.
|
|
11
11
|
|
|
12
|
+
Version **0.2.8** adds [local MCP diagnosis](#diagnose-a-local-service-028)
|
|
13
|
+
and protocol-interruption validation; see the
|
|
14
|
+
[0.2.8 scope and validation status](../releases/release-notes-0.2.8.md).
|
|
15
|
+
The later [Codex 0.165.0 acceptance](#codex-01650-with-published-027) below used
|
|
16
|
+
the published 0.2.7 package and is separate from both development checkpoints.
|
|
17
|
+
|
|
12
18
|
MCP gives a supporting coding-agent client an explicit way to use the existing
|
|
13
19
|
safe deletion and recovery operations. It does **not** intercept shell `rm`,
|
|
14
20
|
scripts, editor deletion or tools that bypass this server. Keep a compatible
|
|
@@ -75,6 +81,91 @@ in memory needs a trusted bridge to enforce them for MCP calls; registering
|
|
|
75
81
|
this server alone does not provide that bridge. Existing
|
|
76
82
|
[limits](deletion-limits.md) and the CLI's mode semantics still apply.
|
|
77
83
|
|
|
84
|
+
<a id="diagnose-a-local-service-028-development"></a>
|
|
85
|
+
|
|
86
|
+
## Diagnose a local service (0.2.8)
|
|
87
|
+
|
|
88
|
+
From a 0.2.8 installation or checkout, run:
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
|
|
92
|
+
--python /absolute/path/to/agent-guard-mcp-venv/bin/python \
|
|
93
|
+
--workspace /absolute/path/to/your-project --json
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The installed CLI entry is `agent-guard-doctor mcp` with the same options.
|
|
97
|
+
`--python` defaults to the interpreter running the doctor; select the separate
|
|
98
|
+
SDK environment explicitly when the Core interpreter has no MCP SDK.
|
|
99
|
+
`--workspace` is required and must already exist. `--server` optionally selects
|
|
100
|
+
another reviewed `server.py`; otherwise the doctor uses its own package's
|
|
101
|
+
adapter. The doctor starts this script with the selected Python, so both are
|
|
102
|
+
trusted executable inputs. It uses no shell and does not discover or rewrite
|
|
103
|
+
client configuration. `--timeout` bounds the diagnostic checks in seconds
|
|
104
|
+
(default 30; accepted range 5–120). Closing the service process can add up to
|
|
105
|
+
three seconds of process waits and one second of reader-thread waiting beyond that deadline.
|
|
106
|
+
|
|
107
|
+
The checks cover:
|
|
108
|
+
|
|
109
|
+
1. The selected interpreter, pinned SDK metadata and actual SDK imports.
|
|
110
|
+
2. A classic `2025-06-18` stdio handshake, the `agent-guard` service identity
|
|
111
|
+
and a service version matching the doctor's package version.
|
|
112
|
+
3. The five expected tools and read-only annotations for the query tools.
|
|
113
|
+
4. Successful `status`, `transactions` and `gc_plan` calls, including the
|
|
114
|
+
requested workspace and its local quarantine binding reported by `status`.
|
|
115
|
+
|
|
116
|
+
No model, deletion, restore, GC execution or dependency installation is part
|
|
117
|
+
of this diagnosis. It does not create host configuration or approve a budget
|
|
118
|
+
reset. A normal service leaves workspace file names and content unchanged
|
|
119
|
+
under these read-only calls; this is not a system-call-level zero-write proof
|
|
120
|
+
for an arbitrary selected script.
|
|
121
|
+
|
|
122
|
+
The independent JSON report has `schema_version: 1`, `harness: "mcp"`,
|
|
123
|
+
`status`, `stage`, `code`, `message`, `guidance` and `checks`. It contains
|
|
124
|
+
fixed diagnostic findings rather than raw service stderr, transaction data,
|
|
125
|
+
audit text, authentication or configuration contents. Exit code `0` means
|
|
126
|
+
the checks passed, `1` means a diagnosis failed, and `2` is a CLI usage error.
|
|
127
|
+
These diagnostic codes are separate from the Decision Protocol reason codes.
|
|
128
|
+
`diagnostic_stderr_bytes` reports only the captured stderr byte count; raw
|
|
129
|
+
stderr is not returned. After a successful status query, `deletion_admission`
|
|
130
|
+
is `BLOCKED` or `READABLE`. `READABLE` records that admission information was
|
|
131
|
+
inspected; it is not permission for a future deletion.
|
|
132
|
+
|
|
133
|
+
Use the returned stage and guidance to fix a missing interpreter/SDK, a
|
|
134
|
+
startup or protocol failure, a version mismatch, an incorrect workspace
|
|
135
|
+
binding or a query failure. A successful `status` can still report blocked
|
|
136
|
+
deletion admission; the text renderer highlights `BLOCKED`, and diagnosis does
|
|
137
|
+
not authorize deleting through that block.
|
|
138
|
+
|
|
139
|
+
`host_connection`, `model_delivery` and `host_interception` stay `UNVERIFIED`.
|
|
140
|
+
A PASS proves the selected service command answered these direct checks.
|
|
141
|
+
Inspect the actual client's connection and use a bounded host acceptance
|
|
142
|
+
trial to establish that a particular host and model used it. The doctor does
|
|
143
|
+
not extend Kimi/Claude hook diagnosis or automatically prove shell protection.
|
|
144
|
+
|
|
145
|
+
## After a lost response or interrupted connection
|
|
146
|
+
|
|
147
|
+
A client deadline, cancellation or process exit can occur after a mutation
|
|
148
|
+
has committed but before its response arrives. It does not roll the files or
|
|
149
|
+
budget back. Stop automatic mutation retries, reconnect to the same reviewed
|
|
150
|
+
workspace/quarantine/session identity, then inspect `status` and `transactions`.
|
|
151
|
+
Check the source and recovery payload before restoring the actual returned or
|
|
152
|
+
listed transaction. Ordinary restoration still refuses an existing occupant
|
|
153
|
+
and does not refund the deletion budget.
|
|
154
|
+
|
|
155
|
+
If evidence is incomplete or an operation may still be running, preserve it
|
|
156
|
+
and resolve the process/transaction state before another mutation. An absent
|
|
157
|
+
response or one empty query is not proof that nothing changed. Changing
|
|
158
|
+
session identity, removing admission state or manufacturing confirmation is
|
|
159
|
+
not recovery.
|
|
160
|
+
|
|
161
|
+
The 0.2.8 interruption checks target four response-loss windows: a client
|
|
162
|
+
deadline, a cancellation notification, stdin EOF and service termination.
|
|
163
|
+
Their controlled barrier is after real safe_delete has committed and before
|
|
164
|
+
the response is sent. They validate recoverability and persistent accounting
|
|
165
|
+
at that boundary, not arbitrary interruption within every multi-file operation
|
|
166
|
+
or atomic rollback. Final candidate results are recorded in the
|
|
167
|
+
[0.2.8 validation status](../releases/release-notes-0.2.8.md#validation-status).
|
|
168
|
+
|
|
78
169
|
## Tools and limits
|
|
79
170
|
|
|
80
171
|
| Tool | Inputs | Effect |
|
|
@@ -198,7 +289,8 @@ called the tool or that all filesystem actions are covered. See the
|
|
|
198
289
|
[official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?site_variant=chatgpt).
|
|
199
290
|
|
|
200
291
|
These source-based examples were checked against official documentation on
|
|
201
|
-
2026-10-28.
|
|
292
|
+
2026-10-28. Claude Code and Cursor remain configuration examples; the later
|
|
293
|
+
Codex acceptance below covers one exact version and selected MCP scenarios.
|
|
202
294
|
Client schemas, approvals and connection behavior can change; verify the
|
|
203
295
|
installed version rather than copying another client's configuration shape.
|
|
204
296
|
|
|
@@ -218,6 +310,36 @@ installed version rather than copying another client's configuration shape.
|
|
|
218
310
|
|
|
219
311
|
## Recorded validation and remaining limits
|
|
220
312
|
|
|
313
|
+
### Codex 0.165.0 with published 0.2.7
|
|
314
|
+
|
|
315
|
+
On 2026-10-29, **Codex CLI 0.165.0** on local ARM64/PRoot exercised the
|
|
316
|
+
published **agent-guard 0.2.7** package through Codex's actual MCP client.
|
|
317
|
+
Three controlled native-client groups, without model turns, covered five-tool
|
|
318
|
+
discovery, queries, deletion/restoration, quarantine/outside-target refusal,
|
|
319
|
+
protection and batch gates, and budget persistence across a fresh Codex
|
|
320
|
+
process. Read-only queries preserved the workspace file inventory and content
|
|
321
|
+
hashes.
|
|
322
|
+
|
|
323
|
+
Three separate real-model tasks using the configured `gpt-6.1-sol / max`
|
|
324
|
+
completed 16 MCP calls: ordinary delete/restore, same-session budget refusal
|
|
325
|
+
and protected-path refusal. Model call arguments and structured results
|
|
326
|
+
matched the recorded stdio requests and responses. Restored files matched
|
|
327
|
+
their original bytes; rejected files remained intact; restoration did not
|
|
328
|
+
refund the admitted budget. The model used only the MCP tools, and GC was
|
|
329
|
+
preview-only. There were no trial timeouts or harness-level automatic retries.
|
|
330
|
+
The client model label was observed; backend model identity was not
|
|
331
|
+
independently authenticated, and no upstream HTTP-request count is claimed.
|
|
332
|
+
|
|
333
|
+
Four native-client recorder exit-metadata files were incomplete. The captured
|
|
334
|
+
tool exchanges supported the reported behavior, and the recorded process IDs
|
|
335
|
+
were absent at the final check; the missing lifecycle metadata was not
|
|
336
|
+
reconstructed. This limitation is separate from the three completed model
|
|
337
|
+
tasks. These results apply to that published 0.2.7 artifact, exact Codex
|
|
338
|
+
version and cooperative MCP path, not the 0.2.8 artifact, native
|
|
339
|
+
shell/editor interception, arbitrary subagents or all Codex releases.
|
|
340
|
+
|
|
341
|
+
### Earlier preparation and Kimi checkpoints
|
|
342
|
+
|
|
221
343
|
The 219-file, versioned **0.2.7 preparation checkpoint** passed local validation on
|
|
222
344
|
2026-10-29: 1129 Python cases and both Node groups in 1194.265 seconds, with
|
|
223
345
|
no failures, errors, skips, timeouts or automatic retries. It used the existing
|
|
@@ -252,10 +374,15 @@ diagnostic unittest result collector with the same scope as `npm test`, then
|
|
|
252
374
|
the Node commands when Python passed; the npm command itself was not invoked.
|
|
253
375
|
|
|
254
376
|
Without the optional SDK or an explicitly configured MCP test interpreter,
|
|
255
|
-
the
|
|
256
|
-
runs above included that SDK and skipped none.
|
|
257
|
-
SDK-backed
|
|
258
|
-
|
|
377
|
+
the original Core checkpoint skipped seven real-stdio protocol cases. The two
|
|
378
|
+
full runs above included that SDK and skipped none. At that local checkpoint,
|
|
379
|
+
the separate SDK-backed Python 3.10/3.13 CI job had not been run remotely.
|
|
380
|
+
Subsequent 0.2.7 release validation for `7431da1` passed its
|
|
381
|
+
[15-job CI](https://github.com/mokuyoaxis/agent-guard/actions/runs/40835352396)
|
|
382
|
+
and [release workflow](https://github.com/mokuyoaxis/agent-guard/actions/runs/40842400686),
|
|
383
|
+
including 1130 Python cases and both Node groups with no release-test skips.
|
|
384
|
+
Those workflows predate the 0.2.8 doctor/interruption additions and do not
|
|
385
|
+
certify the new checks.
|
|
259
386
|
|
|
260
387
|
The 154-file offline package matched the frozen source and installed locally.
|
|
261
388
|
All 12 CLI help checks, adapter import, installed stdio handshake and five-tool
|
|
@@ -281,10 +408,10 @@ configuration/auth fingerprints and frozen candidate bytes remained equal.
|
|
|
281
408
|
The existing loopback gateway's actual server-side model identity was not
|
|
282
409
|
independently authenticated.
|
|
283
410
|
|
|
284
|
-
These results do not add native-hook, subagent, Claude/Cursor/Codex
|
|
285
|
-
tool coverage
|
|
286
|
-
|
|
287
|
-
|
|
411
|
+
These earlier Kimi results do not add native-hook, subagent, Claude/Cursor/Codex
|
|
412
|
+
or other tool coverage; the Codex result is recorded separately above. Claude
|
|
413
|
+
Code and Cursor remain documented examples. Native Windows, macOS and Android
|
|
414
|
+
shared storage have no new local host validation. The first full-run error and
|
|
288
415
|
the earlier unexplained project test timeouts remain recorded as unresolved;
|
|
289
416
|
the current successful full run is not evidence of a general timeout fix.
|
|
290
417
|
|