@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/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 paths are [recovery protection](../skills/delete-guard/SKILL.md),
5
- [disclosure checks](../skills/exfil-guard/SKILL.md), and
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
- This documentation covers [0.2.7](releases/release-notes-0.2.7.md): Cleanup
11
- plans, deletion admission and optional local MCP tools. Before installing,
12
- check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
13
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
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
- 先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
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本地stdio:安全删除、普通恢复、事务/状态和GC预览;不替代hook |
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
- remain in [skills/](../skills/delete-guard/SKILL.md).
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增量及0.2.6维护历史,保留原验收边界 |
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**: it lowers the
6
- probability that an autonomous agent causes irreversible loss through a
7
- misjudged deletion, a mis-expanded command, or mistaken context - and it
8
- leaves a recovery path and an evidence trail when anything destructive does
9
- happen. It is explicitly *not* a sandbox or security boundary (see
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 Skills are the product boundary.
13
- Harness adapters are replaceable translations onto host-native hooks; DSH,
14
- Claude Code, Codex, or any future host is a compatibility target rather than
15
- the identity of the project.
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
- ## The four pillars and where they live
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
- This document covers version [0.2.7](../releases/release-notes-0.2.7.md), which
309
- adds reviewed Cleanup plans, shared deletion admission and optional local
310
- MCP tools. Confirm availability through the exact GitHub release and npm
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
- This contract covers [0.2.7](../releases/release-notes-0.2.7.md). Use its exact
8
- GitHub release and npm version links to confirm availability; a version in
9
- source or a local tarball does not establish publication.
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 remain docs-only.
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.7](../releases/release-notes-0.2.7.md), with Cleanup
14
- plans, deletion admission limits and optional local MCP tools. Confirm the
15
- exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
16
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
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.7
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.7.tgz
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.7](../releases/release-notes-0.2.7.md).
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. These observations do not expand the native
101
- hook rows above or establish live Claude/Cursor/Codex, subagent or additional
102
- platform coverage. Client setup examples remain documentation guidance.
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
 
@@ -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. They are not claims that all three clients were exercised locally.
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 default Core suite skips seven real-stdio protocol cases. The two full
256
- runs above included that SDK and skipped none. A separate CI job now declares
257
- SDK-backed MCP checks for Python 3.10/3.13; it has not been run remotely in
258
- this work, and no remote-CI success is claimed.
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 or other
285
- tool coverage. Those three clients' examples were checked against official
286
- documentation, not exercised as live clients here. Native Windows, macOS and
287
- Android shared storage have no new validation. The first full-run error and
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