@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.
Files changed (39) hide show
  1. package/README.md +45 -20
  2. package/README.zh-CN.md +39 -19
  3. package/adapters/INTEGRATION.md +6 -0
  4. package/adapters/mcp/__init__.py +1 -0
  5. package/adapters/mcp/doctor.py +325 -0
  6. package/adapters/mcp/operations.py +174 -0
  7. package/adapters/mcp/requirements.txt +3 -0
  8. package/adapters/mcp/server.py +126 -0
  9. package/core/admission.py +388 -0
  10. package/core/audit.py +1 -1
  11. package/core/classifier.py +2 -1
  12. package/core/cleanup.py +297 -0
  13. package/core/delete_config.py +153 -0
  14. package/core/policy.py +35 -7
  15. package/core/recovery.py +10 -0
  16. package/docs/README.md +35 -14
  17. package/docs/design/architecture.md +42 -16
  18. package/docs/design/compatibility.md +246 -7
  19. package/docs/design/threat-model.md +53 -1
  20. package/docs/guides/cleanup-plan.md +227 -0
  21. package/docs/guides/deletion-limits.md +150 -0
  22. package/docs/guides/getting-started.md +26 -12
  23. package/docs/guides/harness-capabilities.md +29 -4
  24. package/docs/guides/mcp.md +420 -0
  25. package/docs/history/friction.md +99 -1
  26. package/docs/releases/release-notes-0.2.7.md +217 -0
  27. package/docs/releases/release-notes-0.2.8.md +172 -0
  28. package/docs/releases/unreleased.md +182 -5
  29. package/docs/reports/test-report-dsh-paired-lab.md +1 -1
  30. package/docs/reports/test-report-kimi-code-block.md +1 -1
  31. package/doctor.py +25 -1
  32. package/live_sentinel.py +1 -1
  33. package/package.json +3 -1
  34. package/skills/delete-guard/SKILL.md +69 -1
  35. package/skills/delete-guard/references/policy.md +66 -3
  36. package/skills/delete-guard/scripts/check.py +39 -9
  37. package/skills/delete-guard/scripts/cleanup.py +164 -0
  38. package/skills/delete-guard/scripts/safe_delete.py +22 -4
  39. 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/).
@@ -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
- [candidate notes](../releases/release-notes-0.2.5.md); historical failures and
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).