@mokuyoaxis/agent-guard 0.2.6 → 0.2.7

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.
@@ -0,0 +1,150 @@
1
+ # Deletion limits / 删除准入与预算
2
+
3
+ These limits are introduced in **0.2.7** and are absent from 0.2.6. The
4
+ separate 0.3.0 plan remains paused. Versioned validation and exact-version
5
+ availability checks are tracked in the [0.2.7 notes](../releases/release-notes-0.2.7.md);
6
+ the following results retain their earlier deletion-hardening checkpoint,
7
+ which used 0.2.6 package metadata rather than the final 0.2.7 artifact.
8
+ On 2026-10-28, the same frozen public runtime passed three independent full
9
+ runs: each contained 1090 Python cases and both Node groups, taking 1061.017,
10
+ 1025.315 and 1042.145 seconds. No failures, errors, skips, timeouts or automatic
11
+ retries occurred. The existing diagnostic unittest result collector preserved
12
+ the scope and deadlines of `npm test`; the npm command itself was not invoked.
13
+ An offline 149-file package and three real Kimi Code 2.3.0 scenarios also
14
+ passed: recoverable deletion, same-session budget refusal and configured-path
15
+ protection. Nine configured-route model requests returned HTTP 200. The
16
+ loopback gateway's server-side model identity was not independently verified.
17
+ Tests ran on ARM64/PRoot POSIX, Python 3.13.5 and Node 22.23.4; native Windows,
18
+ macOS, PowerShell and Android shared storage were not exercised. Kimi coverage
19
+ is limited to the observed root Bash hook and optional Stop, not other tools
20
+ or subagents. Historical Cleanup/release evidence keeps its original scope;
21
+ the earlier npm timeout remains unexplained and did not recur in these runs.
22
+
23
+ ## Configuration and defaults
24
+
25
+ The optional workspace file `.agent-guard/delete-policy.json` overrides the
26
+ defaults below. An absent file uses defaults without creating configuration.
27
+ The configuration directory is always protected. Unknown or duplicate keys,
28
+ invalid JSON, unreadable configuration and invalid values block new deletion.
29
+
30
+ | Field | Default | Meaning |
31
+ |---|---|---|
32
+ | `quarantine_max_bytes` | 5368709120 (5 GiB) | Admission ceiling for measured existing quarantine plus incoming content |
33
+ | `quarantine_max_entries` | 100000 | Same ceiling in filesystem entries |
34
+ | `session_max_bytes` | 1073741824 (1 GiB) | Cumulative logical bytes admitted for this session |
35
+ | `session_max_entries` | 10000 | Cumulative filesystem entries admitted for this session |
36
+ | `rate_window_seconds` | 60 | Rolling admission window |
37
+ | `rate_max_operations` | 60 | Admitted operations in that window |
38
+ | `repeat_max_operations` | 5 | Admissions of the same normalized target set in that window |
39
+ | `batch_max_bytes` | 268435456 (256 MiB) | Larger operations require confirmed Cleanup execution |
40
+ | `batch_max_entries` | 1000 | Same confirmation threshold in filesystem entries |
41
+ | `protected_paths` | `[]` | Additional literal workspace paths to preserve |
42
+
43
+ Numbers must be integers through `2**63 - 1`; booleans and numeric strings
44
+ are invalid. Byte limits may be zero, meaning no byte allowance, not unlimited.
45
+ Other numeric limits must be positive. Configuration files larger than 1 MiB are rejected.
46
+ Protected paths may be workspace-relative or absolute inside the workspace;
47
+ they may name future paths, but cannot escape through an external directory
48
+ link. A final outward-pointing link itself can be protected.
49
+
50
+ For example, an operator can choose stricter limits and preserve evidence:
51
+
52
+ ```json
53
+ {
54
+ "session_max_bytes": 536870912,
55
+ "rate_max_operations": 30,
56
+ "protected_paths": ["evidence", "backups/current"]
57
+ }
58
+ ```
59
+
60
+ Protection covers named and physical locations, descendants and deletion of
61
+ an ancestor that would remove a protected path. It precedes regenerable and
62
+ quarantine-housekeeping exemptions. Cleanup's `--protect` remains an extra
63
+ invocation-only planning option; use the configuration for shared protection.
64
+
65
+ ## Accounting and execution
66
+
67
+ `core.admission` stores counters and short-lived approvals in the selected
68
+ quarantine's `admission.json`, with `admission.lock` for cross-process
69
+ serialization. Measurement, durable debit and guarded mutation share the
70
+ lock. Missing state starts empty; malformed or unavailable state, lock or
71
+ inventory blocks admission. State, its temporary file and lock are protected
72
+ control files, alongside the existing recovery evidence.
73
+
74
+ `AGENT_GUARD_SESSION` selects a persistent budget within that quarantine;
75
+ its value is hashed for storage. Unnamed CLI processes share one stable
76
+ default bucket, including Cleanup's child processes. Counters charge
77
+ **admitted work**, before mutation. Failed operations and later restores do
78
+ not refund it. The rate and repeat windows expire, but cumulative session
79
+ bytes and entries do not silently renew. The same-target-set rule is a
80
+ simple delete/recreate loop signal, not general anomaly classification.
81
+
82
+ Inventories use bounded `lstat` traversal, count directory metadata and
83
+ links themselves, and conservatively count hardlinks per entry. Capacity
84
+ compares existing quarantine and incoming logical bytes/entries. These
85
+ figures differ from Cleanup's displayed, hardlink-deduplicated candidate
86
+ sizes and from physical disk blocks. Scan errors or changed directories
87
+ are refusals, never zero-size estimates.
88
+
89
+ Raising policy numbers does not raise the implementation's inventory bounds:
90
+ 200000 entries per scan, depth 128, 1024 stored sessions, 32 outstanding
91
+ approvals, 10000 window events per session and 8 MiB of state. A higher
92
+ configured rate still caps at 10000 events. Reaching a bound refuses work;
93
+ it does not silently discard counters. Scanning existing quarantine is
94
+ proportional to its entries, with no guaranteed wall-clock completion time.
95
+
96
+ Relocations, including Git clean compensation and force-restore occupant
97
+ preservation, check capacity. Regenerable direct deletion also checks session,
98
+ rate, repeat and batch limits. Covered automatic native-hook paths charge
99
+ admission before returning control to the host; they cannot prove the host
100
+ subsequently performed the delete.
101
+ Normal restore, explicit transaction GC and existing unprotected quarantine
102
+ payload housekeeping remain available without a new session/rate/batch debit.
103
+ Configuration and control-file protection still applies to housekeeping.
104
+ No limit triggers automatic GC or a fallback to permanent
105
+ deletion. Already completed earlier operations remain completed after a later
106
+ refusal; inspect reported transaction IDs.
107
+
108
+ Large deletions on the automated rm, Git-clean and artifact paths through
109
+ `check --enforce` or `safe_delete` return
110
+ `BLOCK_DELETE_BATCH_CONFIRM`, directing the operator to
111
+ [Cleanup Copilot](cleanup-plan.md#confirm-and-execute), rather than host `ASK`.
112
+ The enforced shell checker combines deletion targets across the request,
113
+ including enumerated Git clean targets, before its first compensation.
114
+ After terminal confirmation and a fresh plan check, Cleanup creates an approval
115
+ valid for ten minutes. It binds the session, configuration, exact paths and
116
+ measured metadata. Each selected path is consumed once before its operation;
117
+ failure does not restore approval. Changed, expired or replayed approvals are
118
+ refused. Approval lifts only the batch-confirmation gate: protection, budgets,
119
+ rate and capacity still apply.
120
+
121
+ Existing compound-command `ASK` paths return to host authorization before
122
+ automatic compensation and do not consume this admission budget. Existing
123
+ Git reset/restore/checkout snapshots also use their separate Git storage,
124
+ outside this quarantine budget. This change adds no new coverage or bound
125
+ for those paths; Git snapshot storage can still grow.
126
+
127
+ ## Status and operator recovery
128
+
129
+ Inspect effective limits and current-session counters with `status.py --json`.
130
+ The [policy reference](../../skills/delete-guard/references/policy.md#unreleased-execution-admission)
131
+ defines the new machine-readable refusal codes.
132
+ After investigating a stopped loop, an operator may run:
133
+
134
+ ```sh
135
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --reset-delete-budget
136
+ ```
137
+
138
+ This requires an interactive terminal and typing `RESET`. It clears only the
139
+ current bucket's counters, short-window events and outstanding approvals.
140
+ It does not purge recovery copies, reset quarantine capacity or alter limits.
141
+ An agent must leave this confirmation to the operator. Corrupt state is a
142
+ diagnostic failure, not an instruction to delete or silently reinitialize it.
143
+
144
+ These checks suppress accidents on covered paths; they are not an OS disk
145
+ quota or authenticated human authority. Same-UID processes can change local
146
+ configuration/state, change session identity or allocate a terminal. Audit,
147
+ manifest and new directory metadata, concurrent unrelated writers and writes
148
+ outside guarded paths can still grow storage. Existing 30-day/5-GiB GC
149
+ eligibility remains a separate soft planning rule. Review its explicit plan
150
+ using the [storage and GC guide](recovery-feedback.md).
@@ -10,18 +10,23 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- The stable release line is [0.2.6](../releases/release-notes-0.2.6.md), and the
14
- prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
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)
17
+ are available before installing from the registry. A checkout or manifest
18
+ does not establish publication or the current npm `latest` channel.
19
+
20
+ The earlier published [0.2.6](../releases/release-notes-0.2.6.md) includes Kimi
21
+ recovery feedback, diagnostics and reviewed DSH alpha.4/Kimi 2.3.0 Bash compatibility.
22
+ The prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
15
23
  The optional [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
16
24
  backports quarantine protection onto the stable line.
17
- Version 0.2.6 adds Kimi recovery feedback and diagnostics to the 0.2.5 base,
18
- plus reviewed DSH alpha.4 and Kimi 2.3.0 Bash compatibility.
19
- Its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)
20
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6)
21
- establish package availability. Use a user-selected stable prefix:
25
+
26
+ Once the exact version is available, use a user-selected stable prefix:
22
27
 
23
28
  ```sh
24
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.6
29
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
25
30
  ```
26
31
 
27
32
  The package root is
@@ -33,11 +38,11 @@ identify the published package. For the stable-line fix alone, select
33
38
  `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`. These opt-in channels do not move
34
39
  stable `latest`.
35
40
 
36
- For a reviewed local checkout or explicitly selected local tarball, use a
37
- separate prefix:
41
+ If that version is unavailable, use a reviewed source checkout or a checked
42
+ local tarball. Install the tarball into a separate prefix:
38
43
 
39
44
  ```sh
40
- npm install --offline --ignore-scripts --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.6.tgz
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
41
46
  ```
42
47
 
43
48
  The review package root is
@@ -46,7 +51,12 @@ Keep the selected package/checkout path consistent when configuring the host.
46
51
  Do not infer publication from a manifest/main commit or use an unscoped
47
52
  same-name package. A checkout's default branch can differ from a tagged stable release.
48
53
 
49
- The [0.2.6 additions](../releases/unreleased.md) require an upgraded package
54
+ The [0.2.7 changes](../releases/release-notes-0.2.7.md#upgrade-and-operator-notes)
55
+ add execution-time limits that can refuse previously successful deletions.
56
+ Review the [default budgets and operator recovery](deletion-limits.md) before
57
+ upgrading; normal restore remains available without a new deletion debit.
58
+
59
+ The [0.2.6 additions](../releases/release-notes-0.2.6.md) require an upgraded package
50
60
  or a checkout containing the corresponding files. In particular, 0.2.5 lacks
51
61
  `adapters/kimi-code/stop_feedback.py`. Check the selected root before configuring
52
62
  the optional Stop hook. Installing a new copy does not update another existing
@@ -66,6 +76,9 @@ Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
66
76
  examples/bridges require a POSIX shell. The optional pinned DSH read path uses
67
77
  Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
68
78
  establish Windows-native hook bridge or full-suite portability.
79
+ The optional [MCP adapter](mcp.md) requires Python 3.10+ and its separately
80
+ installed pinned SDK; npm does not install it. MCP exposes explicit tools
81
+ and does not intercept operations that bypass them.
69
82
 
70
83
  ## Set up a coding agent
71
84
 
@@ -1,17 +1,18 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
- Stable release line: [0.2.6](../releases/release-notes-0.2.6.md).
4
- It retains RC1–RC3 and 0.2.5 feedback, with the additions described below.
3
+ This matrix accompanies [0.2.7](../releases/release-notes-0.2.7.md).
4
+ Confirm availability through the exact GitHub release and npm version links
5
+ in those notes; a source version does not establish publication.
5
6
  Published prerelease, checked on 2026-10-19:
6
7
  [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
7
8
  Rows below retain their tested source/host versions and do not automatically
8
9
  certify a later release. Local regression or package checks are separate from
9
10
  new native-host/model evidence.
10
11
 
11
- [0.2.6](../releases/release-notes-0.2.6.md) adds optional Kimi Stop
12
+ Earlier release [0.2.6](../releases/release-notes-0.2.6.md) adds optional Kimi Stop
12
13
  feedback, separate doctor checks, DSH Lab diagnostics, alpha.4 default
13
14
  deletion compatibility and Kimi 2.3.0 root-Bash compatibility. These additions
14
- are absent from 0.2.5. See [maintenance details](../releases/unreleased.md).
15
+ are absent from 0.2.5. See its [version notes](../releases/release-notes-0.2.6.md).
15
16
 
16
17
  The new [research notes](../research/README.md) describe bounded private
17
18
  experiments; their disclosure/delegation methods do not change the supported
@@ -86,6 +87,20 @@ a CLI/cooperative path and the narrowly scoped, opt-in DSH text-read prototype
86
87
  above. This table does not imply universal interception of model context,
87
88
  uploads, or every output channel.
88
89
 
90
+ ## Local MCP tools introduced in 0.2.7
91
+
92
+ The optional [local stdio MCP adapter](mcp.md) provides explicit safe_delete,
93
+ ordinary restore, transaction/status queries and GC preview under one
94
+ startup-bound workspace/session. It does not intercept shell, script or
95
+ editor operations that bypass those tools. Its Python 3.10+ SDK environment
96
+ is separate from the standard-library Core/CLI requirements.
97
+
98
+ The guide records the 0.2.7 installed-package/protocol checks and the earlier
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.
103
+
89
104
  ## Acceptance for each native adapter
90
105
 
91
106
  1. Pin host version, profile/configuration, tool name, shell dialect, and
@@ -0,0 +1,293 @@
1
+ # Local MCP tools / 本地 MCP 工具
2
+
3
+ This adapter is introduced in **0.2.7** and is absent from 0.2.6. The separate
4
+ 0.3.0 plan remains paused. The historical
5
+ protocol/package records and three real Kimi Code trials below belong to the earlier
6
+ 2026-10-28 source checkpoint with 0.2.6 package metadata, including a failed
7
+ first full run. They do not certify the new versioned artifact. See the
8
+ [0.2.7 notes](../releases/release-notes-0.2.7.md) for versioned validation and
9
+ exact-version availability checks.
10
+ Configuration examples are not host acceptance.
11
+
12
+ MCP gives a supporting coding-agent client an explicit way to use the existing
13
+ safe deletion and recovery operations. It does **not** intercept shell `rm`,
14
+ scripts, editor deletion or tools that bypass this server. Keep a compatible
15
+ blocking hook for the paths where automatic interception is required.
16
+
17
+ ## Install the optional adapter
18
+
19
+ The Core/CLI still needs Python 3.9+ and Git without third-party Python
20
+ packages. This adapter separately uses the official MIT-licensed Python
21
+ `mcp==2.3.0` SDK. Its release metadata requires Python 3.10+; use a compatible
22
+ interpreter in a dedicated virtual environment. The SDK and its dependencies
23
+ are optional and are not installed by the existing Core/CLI or by npm.
24
+
25
+ From a checkout or package containing `adapters/mcp/`:
26
+
27
+ ```sh
28
+ python3 -m venv /absolute/path/to/agent-guard-mcp-venv
29
+ /absolute/path/to/agent-guard-mcp-venv/bin/python -m pip install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
30
+ ```
31
+
32
+ If the existing Python lacks `ensurepip`, and an existing pip supports
33
+ `--python` (pip 22.3+), it can provision the separate environment instead:
34
+
35
+ ```sh
36
+ python3 -m venv --without-pip /absolute/path/to/agent-guard-mcp-venv
37
+ python3 -m pip --python /absolute/path/to/agent-guard-mcp-venv/bin/python install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
38
+ ```
39
+
40
+ The adapter accepts the pinned SDK 2.3.0; other SDK versions are rejected
41
+ until separately validated. Transitive dependency versions are resolved by
42
+ pip; this SDK pin is not a complete cross-platform dependency lock.
43
+
44
+ Use a user-owned path on the Linux filesystem. These POSIX examples do not
45
+ establish Windows, macOS or Android shared-storage compatibility. The SDK
46
+ wheel is platform-independent, but some transitive dependencies contain
47
+ native code; the selected environment must successfully install them.
48
+ Do not replace a working global Python environment to enable this adapter.
49
+
50
+ The local launch command is:
51
+
52
+ ```sh
53
+ /absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
54
+ ```
55
+
56
+ The client starts this stdio process. No network listener, cloud account or
57
+ system service is required. Use absolute paths and bind one workspace at
58
+ startup; a tool call cannot change it or select another quarantine. Protocol
59
+ messages use stdout; diagnostics use stderr.
60
+ This adapter binds the workspace-local `.agent-trash/`; it does not adopt an
61
+ ambient custom quarantine or deletion-policy environment override.
62
+
63
+ An optional trusted startup `--session stable-name` selects both the existing
64
+ CLI authorization mode and persistent deletion-budget identity. Without it,
65
+ the adapter uses the legacy CLI state and stable shared default budget bucket.
66
+ To share saved CLI state, the workspace, quarantine location and session
67
+ selection must match. Do not generate a new identity for each call or
68
+ reconnect: it can select different authorization state as well as a different
69
+ budget. Session identity is trusted configuration, not a model-supplied tool
70
+ argument or an independent authentication boundary.
71
+
72
+ This server does not automatically inherit the calling host's native-session
73
+ restrictions or in-memory veto. A host that keeps authoritative restrictions
74
+ in memory needs a trusted bridge to enforce them for MCP calls; registering
75
+ this server alone does not provide that bridge. Existing
76
+ [limits](deletion-limits.md) and the CLI's mode semantics still apply.
77
+
78
+ ## Tools and limits
79
+
80
+ | Tool | Inputs | Effect |
81
+ |---|---|---|
82
+ | `safe_delete` | `paths` (1–1000 literal strings), optional `dry_run` (default false) | Delegate to safe_delete with the existing policy, budget, audit and recovery rules |
83
+ | `restore` | `txid` | Restore a transaction without force-overwriting an occupant |
84
+ | `transactions` | none | List the selected workspace's recovery transactions |
85
+ | `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
86
+ | `gc_plan` | none | Preview the existing transaction GC plan; never execute it |
87
+
88
+ Paths are literal names, relative to the fixed workspace or absolute; the
89
+ Core still refuses outside targets. Glob characters name actual files rather
90
+ than selecting a pattern; the existing Core may still refuse such names as
91
+ wildcards or indeterminable effects. Literal transport does not relax those
92
+ rules. No shell parses these arguments. Unknown tool
93
+ arguments and incorrect types are refused, including boolean values for
94
+ integer fields.
95
+ Paths that normalize to a name ending in whitespace are refused, because
96
+ the underlying classifier trims that spelling. Existing Core restrictions
97
+ on glob/variable-like filenames still apply; literal passing prevents
98
+ selecting neighboring names but does not relax those refusals.
99
+
100
+ Results carry `tool`, `ok`, `exit_code` and the existing CLI JSON in `result`;
101
+ MCP errors are marked as errors as well. Adapter failures use an `error`
102
+ object with `code`, `message`, `may_have_changed` and inspection-tool guidance.
103
+ Raw non-JSON subprocess stderr is not returned as tool content.
104
+
105
+ Ordinary valuable deletion retains a recovery copy and disk usage; only
106
+ provably regenerable artifacts follow the existing physical-delete rules.
107
+ Dry run is advisory: it preserves source targets and does not debit deletion
108
+ budget, but may initialize normal guard/audit metadata. It is not a zero-write
109
+ scan or an execution grant.
110
+ Tool responses can include workspace paths and recovery metadata; review them
111
+ before sharing logs. MCP does not add file-content disclosure sanitization.
112
+
113
+ The tool schema supplies no workspace/session/environment override, arbitrary
114
+ shell command, force restore, Cleanup approval, budget reset or GC execute
115
+ argument. The MCP safe-delete entry also refuses quarantine targets, so it
116
+ cannot be used as an alternate permanent-GC interface. `gc_plan` is a preview
117
+ restriction of this adapter, not a new claim that the existing GC CLI requires
118
+ a terminal or human confirmation.
119
+
120
+ Large batches remain refused with Cleanup guidance; use the existing
121
+ [reviewed terminal workflow](cleanup-plan.md#confirm-and-execute) when
122
+ authorized. A model-provided `confirm=true`, client tool annotation or
123
+ permissive auto-approval setting does not replace that workflow. Restore
124
+ conflicts require operator review. Changing policy, force restoration,
125
+ executing GC or resetting a budget remains outside this server's tool set.
126
+
127
+ A tool call can fail after a partial mutation. Inspect its structured result,
128
+ reported transaction IDs and `transactions`/`status`; do not assume failure or
129
+ cancellation means nothing moved. Do not automatically retry a mutating call
130
+ after a client timeout or disconnection. The existing recovery, concurrency
131
+ and same-UID boundaries remain; this server is not an OS sandbox.
132
+
133
+ ## Configure a client
134
+
135
+ The following examples register a local server; they do not run deletion or
136
+ change existing hooks. Merge the entry into the appropriate configuration
137
+ instead of overwriting other servers. Confirm trust and tool permissions in
138
+ the actual client, then start a fresh connection and inspect discovered tools.
139
+
140
+ ### Claude Code
141
+
142
+ From the intended project, register a project-scoped stdio server:
143
+
144
+ ```sh
145
+ claude mcp add --transport stdio --scope project agent-guard -- /absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
146
+ ```
147
+
148
+ The command changes project MCP configuration; review it before use. Complete
149
+ Claude's normal trust review, then inspect `/mcp`. This setup is an explicit
150
+ MCP tool path and does not extend the separate Claude hook adapter's tested
151
+ versions. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
152
+
153
+ ### Cursor
154
+
155
+ Merge into `.cursor/mcp.json` in the intended project:
156
+
157
+ ```json
158
+ {
159
+ "mcpServers": {
160
+ "agent-guard": {
161
+ "type": "stdio",
162
+ "command": "/absolute/path/to/agent-guard-mcp-venv/bin/python",
163
+ "args": [
164
+ "-B",
165
+ "/absolute/path/to/agent-guard/adapters/mcp/server.py",
166
+ "--workspace",
167
+ "/absolute/path/to/your-project"
168
+ ]
169
+ }
170
+ }
171
+ }
172
+ ```
173
+
174
+ Enable and inspect the server in the installed client's MCP settings. This
175
+ local configuration does not make your filesystem available to a remote
176
+ cloud agent. See the [official Cursor MCP guide](https://cursor.com/docs/mcp).
177
+
178
+ ### Codex
179
+
180
+ Register the same command through the CLI:
181
+
182
+ ```sh
183
+ codex mcp add agent-guard -- /absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
184
+ ```
185
+
186
+ `codex mcp add` writes Codex configuration. For explicit project scoping in a
187
+ trusted project, merge this entry into `.codex/config.toml` instead:
188
+
189
+ ```toml
190
+ [mcp_servers.agent-guard]
191
+ command = "/absolute/path/to/agent-guard-mcp-venv/bin/python"
192
+ args = ["-B", "/absolute/path/to/agent-guard/adapters/mcp/server.py", "--workspace", "/absolute/path/to/your-project"]
193
+ ```
194
+
195
+ Use `codex mcp list` and `/mcp` in a fresh session to inspect configuration and
196
+ connection state. Configuration being present does not prove a model actually
197
+ called the tool or that all filesystem actions are covered. See the
198
+ [official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?site_variant=chatgpt).
199
+
200
+ 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.
202
+ Client schemas, approvals and connection behavior can change; verify the
203
+ installed version rather than copying another client's configuration shape.
204
+
205
+ ## Verify and report
206
+
207
+ 1. Confirm the interpreter starts the server and the client discovers the five
208
+ tools. Check stderr when a dependency or executable cannot be found.
209
+ 2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
210
+ preview leaves recovery payloads intact.
211
+ 3. Create a small synthetic valuable file, call `safe_delete`, verify a real
212
+ restorable transaction, then `restore` and compare original bytes.
213
+ 4. Independently check configured protection and budget refusals preserve
214
+ targets. Confirm forbidden override/force/GC-execute arguments are refused.
215
+ 5. Report the client/version, platform, workspace binding, tool calls, actual
216
+ results and unverified paths. A raw protocol test, a real client call and a
217
+ real-model trial are different evidence levels.
218
+
219
+ ## Recorded validation and remaining limits
220
+
221
+ The 219-file, versioned **0.2.7 preparation checkpoint** passed local validation on
222
+ 2026-10-29: 1129 Python cases and both Node groups in 1194.265 seconds, with
223
+ no failures, errors, skips, timeouts or automatic retries. It used the existing
224
+ diagnostic collector with `npm test` scope and original deadlines rather than
225
+ invoking npm. Its 155-file offline installation passed 12 CLI entry-point and
226
+ actual installed MCP checks, including `serverInfo.version == 0.2.7`, normal
227
+ delete/restore, budget persistence across reconnect, protected/batch refusal
228
+ and read-only tools without workspace writes. Local SDK release-gate checks
229
+ also passed. This 2026-10-29 local checkpoint did not include final-commit
230
+ remote CI or publication; no new real-model trial was run during version
231
+ alignment. See the
232
+ [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
233
+
234
+ The earlier 217-file, 0.2.6-metadata frozen public candidate was tested locally on ARM64/PRoot
235
+ POSIX with Python 3.13.5 and the isolated MCP SDK 2.3.0 environment. Both full
236
+ runs retained the existing 1800-second total budget and per-test deadlines;
237
+ neither changed the runtime/tests or automatically retried a failing case.
238
+
239
+ | Full run | Python | Node groups | Total time | Result |
240
+ |---|---|---|---|---|
241
+ | First | 1123 cases, one error, no assertion failures or skips | Not started after Python failed | 1156.312 seconds | FAIL |
242
+ | Second | 1123 cases, no failures, errors or skips | Both passed | 1143.435 seconds | PASS |
243
+
244
+ The first run's existing DSH Lab case
245
+ `test_native_capture_corruption_is_refused_before_host_result` could not bring
246
+ its observer to READY within the existing five-second startup deadline.
247
+ One separate single-case check with the SDK interpreter and one with system
248
+ Python passed in 4.409 and 2.979 seconds. The cause remains undetermined; these
249
+ checks and the successful second full run do not rewrite the first failure.
250
+ The second run completed without a timeout. Both runs used the existing
251
+ diagnostic unittest result collector with the same scope as `npm test`, then
252
+ the Node commands when Python passed; the npm command itself was not invoked.
253
+
254
+ 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.
259
+
260
+ The 154-file offline package matched the frozen source and installed locally.
261
+ All 12 CLI help checks, adapter import, installed stdio handshake and five-tool
262
+ discovery passed. Installed tests covered valuable-file deletion and restore,
263
+ read-only queries, GC preview without payload removal, reconnect-persistent
264
+ budget, protection/batch refusals and refusal of override/force/GC-execute
265
+ parameters. Protocol acceptance exercised the classic `2025-06-18` handshake;
266
+ it does not establish every MCP protocol extension or client version.
267
+
268
+ Three real **Kimi Code 2.3.0 root-agent native MCP** trials passed:
269
+
270
+ | Trial | Time | Real model requests / MCP calls | Observed result |
271
+ |---|---:|---:|---|
272
+ | Ordinary delete/restore | 27.288 seconds | 7 / 6 | Model deleted, obtained a real transaction and restored original bytes |
273
+ | Same-session budget | 26.121 seconds | 7 / 6 | Second delete refused; model restored first file; budget remained charged |
274
+ | Configured protection | 16.814 seconds | 5 / 4 | Delete refused, original bytes retained, no recovery transaction |
275
+
276
+ All 19 configured-route requests returned HTTP 200, with 16 native MCP calls,
277
+ no fixed model replies, automatic trial retries or route switches. Each trial
278
+ used isolated configuration and synthetic files; the model had no Bash tool.
279
+ GC was previewed in all three trials and never executed. Before/after user
280
+ configuration/auth fingerprints and frozen candidate bytes remained equal.
281
+ The existing loopback gateway's actual server-side model identity was not
282
+ independently authenticated.
283
+
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
288
+ the earlier unexplained project test timeouts remain recorded as unresolved;
289
+ the current successful full run is not evidence of a general timeout fix.
290
+
291
+ The SDK and upstream setup references are primary sources, not this project's
292
+ acceptance results: [official Python SDK](https://github.com/modelcontextprotocol/python-sdk),
293
+ [selected SDK release metadata](https://pypi.org/project/mcp/2.3.0/).