@mokuyoaxis/agent-guard 0.2.5 → 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.
Files changed (52) hide show
  1. package/README.md +61 -23
  2. package/README.zh-CN.md +51 -22
  3. package/adapters/INTEGRATION.md +90 -10
  4. package/adapters/claude/README.md +6 -0
  5. package/adapters/dsh/README.md +19 -8
  6. package/adapters/dsh/compatibility.json +14 -0
  7. package/adapters/dsh/harness/README.md +11 -0
  8. package/adapters/dsh/harness/guard_lab.py +42 -14
  9. package/adapters/kimi-code/README.md +154 -14
  10. package/adapters/kimi-code/compatibility.json +1 -1
  11. package/adapters/kimi-code/config.example.toml +18 -6
  12. package/adapters/kimi-code/hook_bridge.sh +19 -4
  13. package/adapters/kimi-code/pre_tool_use.py +1 -1
  14. package/adapters/kimi-code/stop_feedback.py +237 -0
  15. package/adapters/mcp/__init__.py +1 -0
  16. package/adapters/mcp/operations.py +174 -0
  17. package/adapters/mcp/requirements.txt +3 -0
  18. package/adapters/mcp/server.py +126 -0
  19. package/core/admission.py +388 -0
  20. package/core/audit.py +1 -1
  21. package/core/classifier.py +2 -1
  22. package/core/cleanup.py +297 -0
  23. package/core/delete_config.py +153 -0
  24. package/core/policy.py +35 -7
  25. package/core/recovery.py +10 -0
  26. package/docs/README.md +25 -7
  27. package/docs/design/architecture.md +16 -4
  28. package/docs/design/compatibility.md +230 -6
  29. package/docs/design/dsh-compatibility.md +65 -0
  30. package/docs/design/threat-model.md +53 -1
  31. package/docs/guides/cleanup-plan.md +227 -0
  32. package/docs/guides/deletion-limits.md +150 -0
  33. package/docs/guides/getting-started.md +72 -11
  34. package/docs/guides/harness-capabilities.md +37 -4
  35. package/docs/guides/host-drift.md +32 -0
  36. package/docs/guides/mcp.md +293 -0
  37. package/docs/guides/recovery-feedback.md +29 -1
  38. package/docs/history/friction.md +99 -1
  39. package/docs/releases/release-notes-0.2.6.md +167 -0
  40. package/docs/releases/release-notes-0.2.7.md +217 -0
  41. package/docs/releases/unreleased.md +275 -0
  42. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  43. package/docs/reports/test-report-dsh-paired-lab.md +1 -1
  44. package/docs/reports/test-report-kimi-code-block.md +120 -7
  45. package/doctor.py +175 -28
  46. package/package.json +13 -2
  47. package/skills/delete-guard/SKILL.md +69 -1
  48. package/skills/delete-guard/references/policy.md +66 -3
  49. package/skills/delete-guard/scripts/check.py +39 -9
  50. package/skills/delete-guard/scripts/cleanup.py +164 -0
  51. package/skills/delete-guard/scripts/safe_delete.py +22 -4
  52. package/skills/delete-guard/scripts/status.py +77 -1
@@ -18,6 +18,17 @@ that reliability problem; it is not a sandbox or a live-interception proof.
18
18
  3. It fingerprints the local enforcement path (profile, bridge, adapter,
19
19
  shared guard entry point, and Core Python files).
20
20
 
21
+ In [0.2.6](../releases/release-notes-0.2.6.md), a
22
+ configured optional Kimi Stop adds its normalized
23
+ fields to the configuration fingerprint and `stop_feedback.py` to the runtime
24
+ fingerprint. Adding, removing or changing it can therefore yield `DRIFTED`
25
+ against an earlier baseline. Without agent-guard Stop, the original
26
+ PreToolUse fingerprint remains unchanged. Unrelated Stop commands are ignored.
27
+
28
+ The runtime fingerprint includes `package.json`, so a package version change
29
+ also changes the fingerprint. Compare with the old baseline first; after an
30
+ intentional update, review the change and use a new baseline path.
31
+
21
32
  This does not start a model or edit host configuration. The ordinary doctor
22
33
  does not execute the host at all; host version discovery is opt-in through
23
34
  `--check-drift`, `--baseline`, `--write-baseline`, or `--host-executable`.
@@ -31,6 +42,10 @@ python3 doctor.py kimi --probe --check-drift --json
31
42
  when a host is installed under a wrapper name. The selected executable is run
32
43
  only with the compatibility profile's version arguments.
33
44
 
45
+ Automatic discovery uses the doctor's current PATH. An interactive shell or
46
+ wrapper can select another installation. Check the user's actual launcher
47
+ and use `--host-executable` for the intended binary when those paths differ.
48
+
34
49
  ## Status vocabulary
35
50
 
36
51
  | Status | Meaning |
@@ -48,6 +63,12 @@ it suitable for a local preflight. `CURRENT` is deliberately weaker than
48
63
  version command, and local adapter process cannot prove that a live host
49
64
  loaded or enforced the hook.
50
65
 
66
+ A configured Kimi Stop that fails configuration or a requested local probe
67
+ also makes drift `BROKEN`. Absent optional Stop is not a failure. Baseline
68
+ creation requires those requested Stop probes to pass as well; it does not
69
+ certify delivery. The separate `feedback.model_delivery` remains `UNVERIFIED`
70
+ even if the root-agent Bash live sentinel below passes.
71
+
51
72
  ## Privacy-minimal baselines
52
73
 
53
74
  A baseline is optional. Create one only after reviewing a passing installation:
@@ -78,6 +99,17 @@ same OS privileges.
78
99
  Profiles live beside their adapters as `compatibility.json`. They describe
79
100
  only the host-facing version command and the narrow contract already covered
80
101
  by that adapter. Core policy remains shared and is not copied into profiles.
102
+
103
+ The 0.2.6 Kimi profile lists exact versions `0.42.0`, `2.1.1` and
104
+ `2.3.0`. The [2.3.0 prompt/ACP root-Bash evidence](../reports/test-report-kimi-code-block.md#kimi-230-acceptance)
105
+ does not extend the separately pinned Lab helper, subagent coverage or real-model
106
+ claims. A valid 2.3.0 setup can now be `CURRENT` without a baseline; live
107
+ interception and feedback delivery still retain their independent status.
108
+ Updating the profile changes its runtime fingerprint, so an old baseline can
109
+ report `DRIFTED`. Review that change before selecting a new private baseline;
110
+ the update does not overwrite an existing one. Published 0.2.5 retains its
111
+ earlier list, and unlisted versions remain `STALE`.
112
+
81
113
  Adding a profile for an unlisted host does not make it supported: the host
82
114
  still needs a blocking pre-tool event and the bounded acceptance evidence in
83
115
  the [capability matrix](harness-capabilities.md).
@@ -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/).
@@ -1,9 +1,11 @@
1
1
  # Reading guard status and cleanup results
2
2
 
3
- These feedback changes are included in
3
+ The CLI/DSH feedback below is included in
4
4
  [0.2.5](../releases/release-notes-0.2.5.md).
5
5
  They do not change deletion policy, wildcard handling, retention thresholds,
6
6
  or the recovery format.
7
+ The final Kimi section describes the additions in
8
+ [0.2.6](../releases/release-notes-0.2.6.md).
7
9
 
8
10
  ## What the status establishes
9
11
 
@@ -96,3 +98,29 @@ Review the plan and selected transactions before choosing a purge. A manual
96
98
  `--txid` selection is not limited to age/capacity eligibility. The 30-day and
97
99
  5-GiB thresholds do not run GC automatically. `--execute` alone selects
98
100
  nothing; GC does not prune Git stash snapshots.
101
+
102
+ ## Kimi: tool success and recovery feedback
103
+
104
+ In the sampled Kimi 0.42.0, 2.1.1 and 2.3.0 paths, successful PreToolUse recovery
105
+ explanations did not enter the next model request. A successful Bash result
106
+ alone therefore does not tell the model that files were retained.
107
+ The [2.3.0 observations](../reports/test-report-kimi-code-block.md#kimi-230-acceptance)
108
+ used fixed responses through the actual prompt CLI and ACP host, with no
109
+ external model calls.
110
+
111
+ Version 0.2.6 provides a separate, opt-in POSIX Stop hook. It supplies
112
+ actual transaction IDs, state/restore commands, retained-storage guidance and
113
+ full GC commands, then asks for one extra response after the initial answer.
114
+ The initial answer may already be inaccurate, and the model can still omit
115
+ details. Emission cursors track notices, not model acknowledgement.
116
+
117
+ Restoring files returns them to their original location; it does not free
118
+ total disk space. GC permanently removes recovery copies and remains an
119
+ explicit operation. The Stop hook itself executes no restore or GC.
120
+ Published 0.2.5 lacks the Stop helper. See [setup and limits](../../adapters/kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition)
121
+ and the [bounded real-host report](../reports/test-report-kimi-code-block.md).
122
+ In 0.2.6, the doctor separates PreToolUse from Stop
123
+ configuration and local feedback probes. `--probe` uses isolated synthetic
124
+ records and leaves existing recovery data alone. Stop's `model_delivery`
125
+ remains `UNVERIFIED`; local PASS does not establish model receipt. See the
126
+ [Stop doctor fields](../../adapters/kimi-code/README.md#stop-doctor-checks-unreleased).
@@ -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).