@mokuyoaxis/agent-guard 0.2.6 → 0.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +45 -20
- package/README.zh-CN.md +39 -19
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/doctor.py +325 -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 +35 -14
- package/docs/design/architecture.md +42 -16
- package/docs/design/compatibility.md +246 -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 +26 -12
- package/docs/guides/harness-capabilities.md +29 -4
- package/docs/guides/mcp.md +420 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +182 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +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,420 @@
|
|
|
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
|
+
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
|
+
|
|
18
|
+
MCP gives a supporting coding-agent client an explicit way to use the existing
|
|
19
|
+
safe deletion and recovery operations. It does **not** intercept shell `rm`,
|
|
20
|
+
scripts, editor deletion or tools that bypass this server. Keep a compatible
|
|
21
|
+
blocking hook for the paths where automatic interception is required.
|
|
22
|
+
|
|
23
|
+
## Install the optional adapter
|
|
24
|
+
|
|
25
|
+
The Core/CLI still needs Python 3.9+ and Git without third-party Python
|
|
26
|
+
packages. This adapter separately uses the official MIT-licensed Python
|
|
27
|
+
`mcp==2.3.0` SDK. Its release metadata requires Python 3.10+; use a compatible
|
|
28
|
+
interpreter in a dedicated virtual environment. The SDK and its dependencies
|
|
29
|
+
are optional and are not installed by the existing Core/CLI or by npm.
|
|
30
|
+
|
|
31
|
+
From a checkout or package containing `adapters/mcp/`:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
python3 -m venv /absolute/path/to/agent-guard-mcp-venv
|
|
35
|
+
/absolute/path/to/agent-guard-mcp-venv/bin/python -m pip install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
If the existing Python lacks `ensurepip`, and an existing pip supports
|
|
39
|
+
`--python` (pip 22.3+), it can provision the separate environment instead:
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
python3 -m venv --without-pip /absolute/path/to/agent-guard-mcp-venv
|
|
43
|
+
python3 -m pip --python /absolute/path/to/agent-guard-mcp-venv/bin/python install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
The adapter accepts the pinned SDK 2.3.0; other SDK versions are rejected
|
|
47
|
+
until separately validated. Transitive dependency versions are resolved by
|
|
48
|
+
pip; this SDK pin is not a complete cross-platform dependency lock.
|
|
49
|
+
|
|
50
|
+
Use a user-owned path on the Linux filesystem. These POSIX examples do not
|
|
51
|
+
establish Windows, macOS or Android shared-storage compatibility. The SDK
|
|
52
|
+
wheel is platform-independent, but some transitive dependencies contain
|
|
53
|
+
native code; the selected environment must successfully install them.
|
|
54
|
+
Do not replace a working global Python environment to enable this adapter.
|
|
55
|
+
|
|
56
|
+
The local launch command is:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
/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
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The client starts this stdio process. No network listener, cloud account or
|
|
63
|
+
system service is required. Use absolute paths and bind one workspace at
|
|
64
|
+
startup; a tool call cannot change it or select another quarantine. Protocol
|
|
65
|
+
messages use stdout; diagnostics use stderr.
|
|
66
|
+
This adapter binds the workspace-local `.agent-trash/`; it does not adopt an
|
|
67
|
+
ambient custom quarantine or deletion-policy environment override.
|
|
68
|
+
|
|
69
|
+
An optional trusted startup `--session stable-name` selects both the existing
|
|
70
|
+
CLI authorization mode and persistent deletion-budget identity. Without it,
|
|
71
|
+
the adapter uses the legacy CLI state and stable shared default budget bucket.
|
|
72
|
+
To share saved CLI state, the workspace, quarantine location and session
|
|
73
|
+
selection must match. Do not generate a new identity for each call or
|
|
74
|
+
reconnect: it can select different authorization state as well as a different
|
|
75
|
+
budget. Session identity is trusted configuration, not a model-supplied tool
|
|
76
|
+
argument or an independent authentication boundary.
|
|
77
|
+
|
|
78
|
+
This server does not automatically inherit the calling host's native-session
|
|
79
|
+
restrictions or in-memory veto. A host that keeps authoritative restrictions
|
|
80
|
+
in memory needs a trusted bridge to enforce them for MCP calls; registering
|
|
81
|
+
this server alone does not provide that bridge. Existing
|
|
82
|
+
[limits](deletion-limits.md) and the CLI's mode semantics still apply.
|
|
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
|
+
|
|
169
|
+
## Tools and limits
|
|
170
|
+
|
|
171
|
+
| Tool | Inputs | Effect |
|
|
172
|
+
|---|---|---|
|
|
173
|
+
| `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 |
|
|
174
|
+
| `restore` | `txid` | Restore a transaction without force-overwriting an occupant |
|
|
175
|
+
| `transactions` | none | List the selected workspace's recovery transactions |
|
|
176
|
+
| `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
|
|
177
|
+
| `gc_plan` | none | Preview the existing transaction GC plan; never execute it |
|
|
178
|
+
|
|
179
|
+
Paths are literal names, relative to the fixed workspace or absolute; the
|
|
180
|
+
Core still refuses outside targets. Glob characters name actual files rather
|
|
181
|
+
than selecting a pattern; the existing Core may still refuse such names as
|
|
182
|
+
wildcards or indeterminable effects. Literal transport does not relax those
|
|
183
|
+
rules. No shell parses these arguments. Unknown tool
|
|
184
|
+
arguments and incorrect types are refused, including boolean values for
|
|
185
|
+
integer fields.
|
|
186
|
+
Paths that normalize to a name ending in whitespace are refused, because
|
|
187
|
+
the underlying classifier trims that spelling. Existing Core restrictions
|
|
188
|
+
on glob/variable-like filenames still apply; literal passing prevents
|
|
189
|
+
selecting neighboring names but does not relax those refusals.
|
|
190
|
+
|
|
191
|
+
Results carry `tool`, `ok`, `exit_code` and the existing CLI JSON in `result`;
|
|
192
|
+
MCP errors are marked as errors as well. Adapter failures use an `error`
|
|
193
|
+
object with `code`, `message`, `may_have_changed` and inspection-tool guidance.
|
|
194
|
+
Raw non-JSON subprocess stderr is not returned as tool content.
|
|
195
|
+
|
|
196
|
+
Ordinary valuable deletion retains a recovery copy and disk usage; only
|
|
197
|
+
provably regenerable artifacts follow the existing physical-delete rules.
|
|
198
|
+
Dry run is advisory: it preserves source targets and does not debit deletion
|
|
199
|
+
budget, but may initialize normal guard/audit metadata. It is not a zero-write
|
|
200
|
+
scan or an execution grant.
|
|
201
|
+
Tool responses can include workspace paths and recovery metadata; review them
|
|
202
|
+
before sharing logs. MCP does not add file-content disclosure sanitization.
|
|
203
|
+
|
|
204
|
+
The tool schema supplies no workspace/session/environment override, arbitrary
|
|
205
|
+
shell command, force restore, Cleanup approval, budget reset or GC execute
|
|
206
|
+
argument. The MCP safe-delete entry also refuses quarantine targets, so it
|
|
207
|
+
cannot be used as an alternate permanent-GC interface. `gc_plan` is a preview
|
|
208
|
+
restriction of this adapter, not a new claim that the existing GC CLI requires
|
|
209
|
+
a terminal or human confirmation.
|
|
210
|
+
|
|
211
|
+
Large batches remain refused with Cleanup guidance; use the existing
|
|
212
|
+
[reviewed terminal workflow](cleanup-plan.md#confirm-and-execute) when
|
|
213
|
+
authorized. A model-provided `confirm=true`, client tool annotation or
|
|
214
|
+
permissive auto-approval setting does not replace that workflow. Restore
|
|
215
|
+
conflicts require operator review. Changing policy, force restoration,
|
|
216
|
+
executing GC or resetting a budget remains outside this server's tool set.
|
|
217
|
+
|
|
218
|
+
A tool call can fail after a partial mutation. Inspect its structured result,
|
|
219
|
+
reported transaction IDs and `transactions`/`status`; do not assume failure or
|
|
220
|
+
cancellation means nothing moved. Do not automatically retry a mutating call
|
|
221
|
+
after a client timeout or disconnection. The existing recovery, concurrency
|
|
222
|
+
and same-UID boundaries remain; this server is not an OS sandbox.
|
|
223
|
+
|
|
224
|
+
## Configure a client
|
|
225
|
+
|
|
226
|
+
The following examples register a local server; they do not run deletion or
|
|
227
|
+
change existing hooks. Merge the entry into the appropriate configuration
|
|
228
|
+
instead of overwriting other servers. Confirm trust and tool permissions in
|
|
229
|
+
the actual client, then start a fresh connection and inspect discovered tools.
|
|
230
|
+
|
|
231
|
+
### Claude Code
|
|
232
|
+
|
|
233
|
+
From the intended project, register a project-scoped stdio server:
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
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
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
The command changes project MCP configuration; review it before use. Complete
|
|
240
|
+
Claude's normal trust review, then inspect `/mcp`. This setup is an explicit
|
|
241
|
+
MCP tool path and does not extend the separate Claude hook adapter's tested
|
|
242
|
+
versions. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
|
|
243
|
+
|
|
244
|
+
### Cursor
|
|
245
|
+
|
|
246
|
+
Merge into `.cursor/mcp.json` in the intended project:
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"mcpServers": {
|
|
251
|
+
"agent-guard": {
|
|
252
|
+
"type": "stdio",
|
|
253
|
+
"command": "/absolute/path/to/agent-guard-mcp-venv/bin/python",
|
|
254
|
+
"args": [
|
|
255
|
+
"-B",
|
|
256
|
+
"/absolute/path/to/agent-guard/adapters/mcp/server.py",
|
|
257
|
+
"--workspace",
|
|
258
|
+
"/absolute/path/to/your-project"
|
|
259
|
+
]
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Enable and inspect the server in the installed client's MCP settings. This
|
|
266
|
+
local configuration does not make your filesystem available to a remote
|
|
267
|
+
cloud agent. See the [official Cursor MCP guide](https://cursor.com/docs/mcp).
|
|
268
|
+
|
|
269
|
+
### Codex
|
|
270
|
+
|
|
271
|
+
Register the same command through the CLI:
|
|
272
|
+
|
|
273
|
+
```sh
|
|
274
|
+
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
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`codex mcp add` writes Codex configuration. For explicit project scoping in a
|
|
278
|
+
trusted project, merge this entry into `.codex/config.toml` instead:
|
|
279
|
+
|
|
280
|
+
```toml
|
|
281
|
+
[mcp_servers.agent-guard]
|
|
282
|
+
command = "/absolute/path/to/agent-guard-mcp-venv/bin/python"
|
|
283
|
+
args = ["-B", "/absolute/path/to/agent-guard/adapters/mcp/server.py", "--workspace", "/absolute/path/to/your-project"]
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Use `codex mcp list` and `/mcp` in a fresh session to inspect configuration and
|
|
287
|
+
connection state. Configuration being present does not prove a model actually
|
|
288
|
+
called the tool or that all filesystem actions are covered. See the
|
|
289
|
+
[official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?site_variant=chatgpt).
|
|
290
|
+
|
|
291
|
+
These source-based examples were checked against official documentation on
|
|
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.
|
|
294
|
+
Client schemas, approvals and connection behavior can change; verify the
|
|
295
|
+
installed version rather than copying another client's configuration shape.
|
|
296
|
+
|
|
297
|
+
## Verify and report
|
|
298
|
+
|
|
299
|
+
1. Confirm the interpreter starts the server and the client discovers the five
|
|
300
|
+
tools. Check stderr when a dependency or executable cannot be found.
|
|
301
|
+
2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
|
|
302
|
+
preview leaves recovery payloads intact.
|
|
303
|
+
3. Create a small synthetic valuable file, call `safe_delete`, verify a real
|
|
304
|
+
restorable transaction, then `restore` and compare original bytes.
|
|
305
|
+
4. Independently check configured protection and budget refusals preserve
|
|
306
|
+
targets. Confirm forbidden override/force/GC-execute arguments are refused.
|
|
307
|
+
5. Report the client/version, platform, workspace binding, tool calls, actual
|
|
308
|
+
results and unverified paths. A raw protocol test, a real client call and a
|
|
309
|
+
real-model trial are different evidence levels.
|
|
310
|
+
|
|
311
|
+
## Recorded validation and remaining limits
|
|
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
|
+
|
|
343
|
+
The 219-file, versioned **0.2.7 preparation checkpoint** passed local validation on
|
|
344
|
+
2026-10-29: 1129 Python cases and both Node groups in 1194.265 seconds, with
|
|
345
|
+
no failures, errors, skips, timeouts or automatic retries. It used the existing
|
|
346
|
+
diagnostic collector with `npm test` scope and original deadlines rather than
|
|
347
|
+
invoking npm. Its 155-file offline installation passed 12 CLI entry-point and
|
|
348
|
+
actual installed MCP checks, including `serverInfo.version == 0.2.7`, normal
|
|
349
|
+
delete/restore, budget persistence across reconnect, protected/batch refusal
|
|
350
|
+
and read-only tools without workspace writes. Local SDK release-gate checks
|
|
351
|
+
also passed. This 2026-10-29 local checkpoint did not include final-commit
|
|
352
|
+
remote CI or publication; no new real-model trial was run during version
|
|
353
|
+
alignment. See the
|
|
354
|
+
[versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|
|
355
|
+
|
|
356
|
+
The earlier 217-file, 0.2.6-metadata frozen public candidate was tested locally on ARM64/PRoot
|
|
357
|
+
POSIX with Python 3.13.5 and the isolated MCP SDK 2.3.0 environment. Both full
|
|
358
|
+
runs retained the existing 1800-second total budget and per-test deadlines;
|
|
359
|
+
neither changed the runtime/tests or automatically retried a failing case.
|
|
360
|
+
|
|
361
|
+
| Full run | Python | Node groups | Total time | Result |
|
|
362
|
+
|---|---|---|---|---|
|
|
363
|
+
| First | 1123 cases, one error, no assertion failures or skips | Not started after Python failed | 1156.312 seconds | FAIL |
|
|
364
|
+
| Second | 1123 cases, no failures, errors or skips | Both passed | 1143.435 seconds | PASS |
|
|
365
|
+
|
|
366
|
+
The first run's existing DSH Lab case
|
|
367
|
+
`test_native_capture_corruption_is_refused_before_host_result` could not bring
|
|
368
|
+
its observer to READY within the existing five-second startup deadline.
|
|
369
|
+
One separate single-case check with the SDK interpreter and one with system
|
|
370
|
+
Python passed in 4.409 and 2.979 seconds. The cause remains undetermined; these
|
|
371
|
+
checks and the successful second full run do not rewrite the first failure.
|
|
372
|
+
The second run completed without a timeout. Both runs used the existing
|
|
373
|
+
diagnostic unittest result collector with the same scope as `npm test`, then
|
|
374
|
+
the Node commands when Python passed; the npm command itself was not invoked.
|
|
375
|
+
|
|
376
|
+
Without the optional SDK or an explicitly configured MCP test interpreter,
|
|
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.
|
|
386
|
+
|
|
387
|
+
The 154-file offline package matched the frozen source and installed locally.
|
|
388
|
+
All 12 CLI help checks, adapter import, installed stdio handshake and five-tool
|
|
389
|
+
discovery passed. Installed tests covered valuable-file deletion and restore,
|
|
390
|
+
read-only queries, GC preview without payload removal, reconnect-persistent
|
|
391
|
+
budget, protection/batch refusals and refusal of override/force/GC-execute
|
|
392
|
+
parameters. Protocol acceptance exercised the classic `2025-06-18` handshake;
|
|
393
|
+
it does not establish every MCP protocol extension or client version.
|
|
394
|
+
|
|
395
|
+
Three real **Kimi Code 2.3.0 root-agent native MCP** trials passed:
|
|
396
|
+
|
|
397
|
+
| Trial | Time | Real model requests / MCP calls | Observed result |
|
|
398
|
+
|---|---:|---:|---|
|
|
399
|
+
| Ordinary delete/restore | 27.288 seconds | 7 / 6 | Model deleted, obtained a real transaction and restored original bytes |
|
|
400
|
+
| Same-session budget | 26.121 seconds | 7 / 6 | Second delete refused; model restored first file; budget remained charged |
|
|
401
|
+
| Configured protection | 16.814 seconds | 5 / 4 | Delete refused, original bytes retained, no recovery transaction |
|
|
402
|
+
|
|
403
|
+
All 19 configured-route requests returned HTTP 200, with 16 native MCP calls,
|
|
404
|
+
no fixed model replies, automatic trial retries or route switches. Each trial
|
|
405
|
+
used isolated configuration and synthetic files; the model had no Bash tool.
|
|
406
|
+
GC was previewed in all three trials and never executed. Before/after user
|
|
407
|
+
configuration/auth fingerprints and frozen candidate bytes remained equal.
|
|
408
|
+
The existing loopback gateway's actual server-side model identity was not
|
|
409
|
+
independently authenticated.
|
|
410
|
+
|
|
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
|
|
415
|
+
the earlier unexplained project test timeouts remain recorded as unresolved;
|
|
416
|
+
the current successful full run is not evidence of a general timeout fix.
|
|
417
|
+
|
|
418
|
+
The SDK and upstream setup references are primary sources, not this project's
|
|
419
|
+
acceptance results: [official Python SDK](https://github.com/modelcontextprotocol/python-sdk),
|
|
420
|
+
[selected SDK release metadata](https://pypi.org/project/mcp/2.3.0/).
|
package/docs/history/friction.md
CHANGED
|
@@ -9,7 +9,7 @@ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
|
|
|
9
9
|
F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
|
|
10
10
|
observer startup maintenance; publication is checked by its versioned receipts.
|
|
11
11
|
Current scope is in the
|
|
12
|
-
[
|
|
12
|
+
[0.2.7 notes](../releases/release-notes-0.2.7.md); historical failures and
|
|
13
13
|
test counts below are not rewritten by a later success.
|
|
14
14
|
|
|
15
15
|
## Current feedback maintenance · status, explanations and retained storage
|
|
@@ -567,3 +567,101 @@ Exact CLI/recovery paths and error diagnostics remain available, with the
|
|
|
567
567
|
same mutation-intent durability and assessment/outcome failure behavior.
|
|
568
568
|
Historical records, automatic session identity and other audit/output
|
|
569
569
|
writers remain outside this change.
|
|
570
|
+
|
|
571
|
+
<a id="f32-deletion-admission"></a>
|
|
572
|
+
|
|
573
|
+
## F32 · Repeated admitted deletions could keep growing recovery storage
|
|
574
|
+
|
|
575
|
+
The existing recovery path preserved valuable content but had no persistent
|
|
576
|
+
session byte/entry budget, rolling operation rate or same-target-set limit.
|
|
577
|
+
A caller could repeatedly delete/recreate content or launch fresh CLI
|
|
578
|
+
processes while adding more recovery copies. The soft 30-day/5-GiB GC plan
|
|
579
|
+
did not bound new admission and never purged automatically.
|
|
580
|
+
|
|
581
|
+
**0.2.7 change:** covered relocations, Git-clean compensation and
|
|
582
|
+
force-restore occupant preservation now check quarantine admission capacity.
|
|
583
|
+
Regenerable direct deletion also consumes applicable session/rate/repeat
|
|
584
|
+
budgets. Accounting is persisted before the guarded operation under a
|
|
585
|
+
cross-process lock; admitted failures and subsequent restores do not refund
|
|
586
|
+
it. Unnamed CLI processes share a stable bucket instead of receiving a fresh
|
|
587
|
+
budget on every invocation.
|
|
588
|
+
|
|
589
|
+
Defaults are 5 GiB/100000 quarantine entries, 1 GiB/10000 admitted session
|
|
590
|
+
entries, 60 operations per 60 seconds and five admissions of the same
|
|
591
|
+
normalized target set per window. `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`
|
|
592
|
+
and `BLOCK_DELETE_REPEAT` are upgrade-visible refusals. Inspect `status` and
|
|
593
|
+
the caller; rate/repeat windows can expire, while cumulative budgets require
|
|
594
|
+
explicit operator review and interactive `RESET` or a deliberate policy
|
|
595
|
+
adjustment. Do not switch session identity or remove state to bypass them.
|
|
596
|
+
|
|
597
|
+
Capacity pressure never triggers automatic GC or a fallback to permanent
|
|
598
|
+
deletion. Normal restore, explicit transaction GC and unprotected quarantine
|
|
599
|
+
payload housekeeping remain available without a new deletion debit. Existing
|
|
600
|
+
compound ASK and Git snapshots remain outside these counters. Logical
|
|
601
|
+
accounting and same-UID state are accident suppression, not an OS disk quota
|
|
602
|
+
or a complete anomaly detector. See [deletion limits](../guides/deletion-limits.md)
|
|
603
|
+
for metadata/hardlink accounting and fixed inventory bounds.
|
|
604
|
+
|
|
605
|
+
<a id="f33-batch-confirmation"></a>
|
|
606
|
+
|
|
607
|
+
## F33 · Large automated deletion batches had no separate review gate
|
|
608
|
+
|
|
609
|
+
A supported automated command could compensate many concrete targets under
|
|
610
|
+
the existing deletion policy without an additional batch-size review. Looking
|
|
611
|
+
at each segment separately also let one shell request contain several
|
|
612
|
+
individually small deletions whose combined target set was large.
|
|
613
|
+
|
|
614
|
+
**0.2.7 change:** the enforced checker combines covered rm/artifact
|
|
615
|
+
and enumerated Git-clean targets before its first compensation. Operations
|
|
616
|
+
above 256 MiB or 1000 filesystem entries return
|
|
617
|
+
`BLOCK_DELETE_BATCH_CONFIRM`, directing the operator to the reviewed Cleanup
|
|
618
|
+
plan. The default plan only proposes candidates; execution requires exact
|
|
619
|
+
selection and terminal `EXECUTE`, followed by rescan and per-target
|
|
620
|
+
safe_delete calls.
|
|
621
|
+
|
|
622
|
+
Cleanup creates a ten-minute approval bound to the session, effective
|
|
623
|
+
configuration, exact paths and measured metadata. Each path is consumed once;
|
|
624
|
+
stale, changed, expired or replayed approval is refused. This lifts only the
|
|
625
|
+
batch gate, not protection, session/rate/repeat or quarantine capacity.
|
|
626
|
+
There is no new native host ASK/resume protocol; existing compound ASK and
|
|
627
|
+
Git SNAPSHOT behavior remains separate. The optional MCP adapter does not
|
|
628
|
+
expose approval creation or provide a `confirm=true` shortcut. See the
|
|
629
|
+
[Cleanup workflow](../guides/cleanup-plan.md).
|
|
630
|
+
|
|
631
|
+
<a id="f34-deletion-protection"></a>
|
|
632
|
+
|
|
633
|
+
## F34 · Configured evidence and admission controls needed shared protection
|
|
634
|
+
|
|
635
|
+
Existing hard-coded workspace/Git/recovery boundaries did not express
|
|
636
|
+
additional project evidence roots or a shared protected-path list. Artifact
|
|
637
|
+
classification and housekeeping could not rely on such a declaration, and
|
|
638
|
+
new budget/configuration state needed protection from covered deletion.
|
|
639
|
+
|
|
640
|
+
**0.2.7 change:** the optional workspace
|
|
641
|
+
`.agent-guard/delete-policy.json` supplies literal protected paths and limits.
|
|
642
|
+
Protection covers lexical/physical locations, descendants and ancestor
|
|
643
|
+
deletion, before artifact or payload-housekeeping exemptions. The configuration
|
|
644
|
+
directory, `admission.json`, temporary state and `admission.lock` are protected.
|
|
645
|
+
Missing configuration uses documented defaults without creating the file;
|
|
646
|
+
malformed, unreadable or unsupported configuration returns
|
|
647
|
+
`BLOCK_DELETE_CONFIG_INVALID`. Overlap returns `BLOCK_DELETE_PROTECTED`;
|
|
648
|
+
unusable admission inventory, lock or state returns
|
|
649
|
+
`BLOCK_DELETE_STATE_INVALID` instead of silently disabling admission.
|
|
650
|
+
|
|
651
|
+
Fix the reported configuration/storage issue or preserve the protected
|
|
652
|
+
evidence; do not remove controls to make deletion proceed. This is cooperative
|
|
653
|
+
path protection, not legal hold, minimum directory retention or immutable
|
|
654
|
+
storage. Same-UID processes and unobserved writes/deletion channels remain
|
|
655
|
+
outside its authority. Existing recovery format and explicit GC semantics
|
|
656
|
+
are retained.
|
|
657
|
+
|
|
658
|
+
The maintainer selected version 0.2.7 for these F32–F34
|
|
659
|
+
changes as a bounded maintenance-version exception, recorded in
|
|
660
|
+
[compatibility](../design/compatibility.md#027-candidate-bounded-maintainer-selected-exception).
|
|
661
|
+
This does not relax the general minor-release promise for other patches.
|
|
662
|
+
The pre-alignment 1090/1123-case runs and sampled Kimi results keep their
|
|
663
|
+
original scope. At the 2026-10-29 versioned preparation checkpoint, 1129
|
|
664
|
+
Python cases and both Node groups passed in 1194.265 seconds, and the
|
|
665
|
+
155-file offline package passed installed MCP checks. That local checkpoint
|
|
666
|
+
did not include remote CI or publication, and made no new real-model requests.
|
|
667
|
+
See the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|