@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.
- package/README.md +28 -10
- package/README.zh-CN.md +24 -10
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +14 -9
- package/docs/design/architecture.md +12 -5
- package/docs/design/compatibility.md +181 -7
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +25 -12
- package/docs/guides/harness-capabilities.md +19 -4
- package/docs/guides/mcp.md +293 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/unreleased.md +139 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/package.json +3 -1
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- package/skills/delete-guard/scripts/status.py +77 -1
|
@@ -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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
18
|
-
|
|
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.
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
4
|
-
|
|
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 [
|
|
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/).
|