@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
@@ -305,15 +305,27 @@ order of value:
305
305
 
306
306
  ## Delivery status and design directions
307
307
 
308
- The stable release line is 0.2.5. Previous stable 0.2.4, opt-in
309
- 0.2.4-hotfix.1 and prerelease 0.2.5-rc3 retain their separate artifacts.
308
+ This document covers version [0.2.7](../releases/release-notes-0.2.7.md), which
309
+ adds reviewed Cleanup plans, shared deletion admission and optional local
310
+ MCP tools. Confirm availability through the exact GitHub release and npm
311
+ version links in those notes; a source version does not establish publication.
312
+ Earlier stable 0.2.6/0.2.5, opt-in 0.2.4-hotfix.1 and prerelease 0.2.5-rc3
313
+ retain their separate artifacts and evidence.
310
314
  Version 0.2.5 retains RC recovery, shared audit,
311
315
  observer maintenance and [defensive research](../research/README.md), plus
312
316
  clearer local startup/status and retained-storage feedback. Private research
313
317
  methods do not add a general authorization service or production enforcement
314
- point. Deletion rules and execution routes retain their RC behavior.
315
- See [candidate notes](../releases/release-notes-0.2.5.md) and
318
+ point. Those historical versions retain their RC deletion rules and execution routes.
319
+ See [release notes](../releases/release-notes-0.2.7.md) and
316
320
  [compatibility](compatibility.md) for behaviour and validation boundaries.
321
+ Release [0.2.6](../releases/release-notes-0.2.6.md) adds
322
+ optional Kimi Stop feedback, its doctor checks and Lab preflight diagnostics.
323
+ It also adds reviewed DSH alpha.4 default deletion and Kimi 2.3.0 Bash compatibility.
324
+ That 0.2.6 maintenance did not change Core policy. Version 0.2.7 adds the
325
+ bounded deletion-admission rules and upgrade-visible refusals recorded in
326
+ the [compatibility contract](compatibility.md#027-bounded-maintainer-selected-exception).
327
+ Historical scope and delivery limits remain in the
328
+ [maintenance details](../releases/unreleased.md).
317
329
 
318
330
  The milestones below describe historical delivery and future design scope,
319
331
  not a committed schedule or a guarantee that new compensation types need no
@@ -4,12 +4,21 @@ agent-guard's promise is recoverability. A promise is only as good as its
4
4
  stability over time - this page states exactly what may change and what
5
5
  may not, per release class.
6
6
 
7
- The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), carrying
8
- the cumulative RC maintenance below. The opt-in prerelease remains
9
- [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), 0.2.4 is the previous stable, and
7
+ This contract covers [0.2.7](../releases/release-notes-0.2.7.md). Use its exact
8
+ GitHub release and npm version links to confirm availability; a version in
9
+ source or a local tarball does not establish publication.
10
+ Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
11
+ RC maintenance and the feedback/diagnostic additions below. The opt-in
12
+ prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
13
+ 0.2.5 and the
10
14
  [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
11
- is an opt-in quarantine protection backport. Versioned sections retain the
12
- origin and preparation labels of changes introduced by earlier releases.
15
+ quarantine protection backport retain their separate artifacts. Versioned
16
+ sections retain the origin and preparation labels of changes introduced by
17
+ earlier releases.
18
+
19
+ The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
20
+ optional MCP tools. The bounded versioning decision is recorded below; the
21
+ separate 0.3.0 plan remains paused.
13
22
 
14
23
  RC3 publishes defensive research and an example around the existing four
15
24
  zero-model controls. Experimental disclosure labels and private delegation
@@ -19,6 +28,154 @@ is introduced by the research documentation.
19
28
 
20
29
  ## The adapter contract (frozen surface)
21
30
 
31
+ <a id="local-mcp-tools-027-candidate"></a>
32
+
33
+ ### Local MCP tools (0.2.7)
34
+
35
+ The checkout adds an optional local stdio MCP server with five explicit tools:
36
+ safe_delete, ordinary restore, transactions, status and GC-plan preview.
37
+ It invokes existing CLI operations without a shell, preserves policy/audit/
38
+ recovery semantics and binds workspace/session identity at trusted startup.
39
+ Tool calls cannot select a new workspace, session, environment or quarantine.
40
+ `--session` selects both saved CLI authorization mode and deletion budget;
41
+ omission uses legacy CLI state and the shared default bucket. Reusing saved
42
+ state requires matching workspace, quarantine and session. Native host-session
43
+ restrictions/in-memory veto are not inherited without a trusted bridge.
44
+ Quarantine deletion, force restore, GC execution, budget reset and Cleanup
45
+ approval are not exposed. Existing CLI interfaces remain available separately.
46
+
47
+ The optional `mcp==2.3.0` Python SDK and its transitive dependencies install
48
+ into a separate environment; Core/CLI still has no third-party Python
49
+ requirement. This interface is included in 0.2.7 and is absent from published
50
+ 0.2.6. It does not resume 0.3.0. It is a cooperative tool interface, not expanded
51
+ native interception. Existing host-version evidence and doctor scope do not
52
+ automatically cover MCP. On the 2026-10-28 frozen candidate, the first local
53
+ full run completed 1123 Python cases with one existing observer-startup error
54
+ and did not run Node; its cause remains undetermined. The second full run
55
+ passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
56
+ failures, errors, skips or timeouts. Neither invoked npm directly or changed
57
+ the runtime/tests. A 154-file offline installation and three real Kimi 2.3.0
58
+ native-MCP trials passed; Claude/Cursor/Codex setup examples remain docs-only.
59
+ Without the optional SDK, seven protocol tests skip. The added SDK-backed
60
+ Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
61
+ preparation checkpoint. See
62
+ [setup, full failure history and platform/tool limits](../guides/mcp.md).
63
+ Those measurements predate the 0.2.7 version/document alignment and are not
64
+ acceptance of the final versioned artifact. The subsequent 219-file 0.2.7
65
+ candidate passed 1129 Python cases and both Node groups in 1194.265 seconds,
66
+ with no failures, errors, skips, timeouts or automatic retries. Its 155-file
67
+ offline package passed 12 CLI entry-point and installed MCP checks, including
68
+ `serverInfo.version == 0.2.7`. Local release-gate checks passed; that local
69
+ preparation checkpoint did not include final-commit remote CI or publication.
70
+ No additional real-model trial was run. See
71
+ the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
72
+
73
+ <a id="deletion-admission-limits-027-candidate"></a>
74
+
75
+ ### Deletion admission limits (0.2.7)
76
+
77
+ The current checkout adds shared deletion configuration, persistent
78
+ per-session admission budgets, rate/repeat limits and quarantine capacity
79
+ checks. `.agent-guard/delete-policy.json` is optional; invalid configuration
80
+ or state fails closed. Configuration paths and the new quarantine
81
+ `admission.json`, temporary state and `admission.lock` are protected. Existing
82
+ recovery manifests and transaction strategies are retained without migration.
83
+
84
+ New reason codes are `BLOCK_DELETE_CONFIG_INVALID`, `BLOCK_DELETE_PROTECTED`,
85
+ `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`, `BLOCK_DELETE_REPEAT`,
86
+ `BLOCK_DELETE_BATCH_CONFIRM` and `BLOCK_DELETE_STATE_INVALID`. Decision classes
87
+ and `check.py` exit codes retain their contracts. Limits are applied at
88
+ execution admission; an earlier advisory assessment is not a capacity grant.
89
+ Covered automatic compensation/artifact paths can newly BLOCK when a
90
+ configured limit is reached. The general versioning promises below classify
91
+ these as minor safety changes. The maintainer selected 0.2.7 for these bounded
92
+ additions as an explicit exception recorded below, not as a change shipped
93
+ in 0.2.6 or a general permission to change policy in patch releases. The
94
+ separate 0.3.0 plan remains paused.
95
+
96
+ Cleanup retains plan schema version 1 and terminal-confirmed execution, then
97
+ issues metadata/session/configuration-bound, ten-minute approval for each
98
+ selected path once. Covered automatic large-delete checks BLOCK with Cleanup guidance;
99
+ there is no new host ASK/resume protocol. `status.py --reset-delete-budget`
100
+ adds explicit interactive reset of the current bucket, not capacity or GC.
101
+ Existing compound-command ASK and Git SNAPSHOT paths remain outside the new
102
+ budget. Normal restore, explicit GC and unprotected quarantine payload
103
+ housekeeping remain exempt; configuration/control-path protection still applies.
104
+ Same-UID state remains advisory; accounting is logical admitted work, not an
105
+ OS quota. New Core bytes change doctor fingerprints. The 2026-10-28 public
106
+ runtime passed three independent 1090-case Python plus two-Node-group runs,
107
+ an offline 149-file package check and three real Kimi 2.3.0 root-Bash scenarios.
108
+ These local POSIX results do not establish new platform or tool coverage;
109
+ previous Cleanup and release evidence keeps its original scope. See
110
+ [defaults, accounting and recovery](../guides/deletion-limits.md).
111
+
112
+ <a id="cleanup-copilot-027-candidate"></a>
113
+
114
+ ### Cleanup Copilot (0.2.7)
115
+
116
+ The checkout adds `core.cleanup` and `agent-guard-cleanup` with read-only
117
+ planning, categorized candidates and explicit terminal-confirmed selection.
118
+ Execution delegates to the existing safe_delete CLI one concrete target at a
119
+ time. Plan JSON has its own `schema_version: 1`; it is not a new Decision
120
+ Protocol surface. The initial Cleanup-only checkpoint retained existing
121
+ deletion policy; the subsequent admission changes are described above.
122
+ Recovery formats, explicit GC and native adapter tools retain their contracts.
123
+ Cleanup itself adds no third-party Core dependency or configuration migration.
124
+ This feature is included in 0.2.7 and is absent from the published 0.2.6 package.
125
+
126
+ The new Core module and package metadata change doctor runtime fingerprints.
127
+ An old baseline can become `DRIFTED`; it is not automatically replaced.
128
+ See [the CLI contract](../guides/cleanup-plan.md) for confirmation, partial
129
+ execution, output privacy, scan limits and the existing concurrency boundary.
130
+
131
+ <a id="unreleased-feedback-and-diagnostic-maintenance"></a>
132
+
133
+ ### 0.2.6 feedback and diagnostic maintenance
134
+
135
+ Release [0.2.6](../releases/release-notes-0.2.6.md) adds an opt-in POSIX Kimi
136
+ Stop hook after the existing PreToolUse path. It may request an extra response
137
+ after new compensation records. It does not change the earlier tool result,
138
+ Core verdicts, recovery format or deletion rules; it stores separate local
139
+ emission cursors. Existing PreToolUse setups keep their behavior until Stop
140
+ is explicitly configured. The current example recommends an outer 120-second
141
+ PreToolUse timeout, leaving margin around the existing 90-second guard check.
142
+
143
+ DSH Lab version/config preflight errors gain a JSON diagnostic suffix after
144
+ the stage-specific text, with fixed reason categories, child exit status,
145
+ timing and captured byte counts. The Lab CLI still reports errors on stderr
146
+ and exits 1; normal receipts, supported host versions and the 10/15-second
147
+ budgets retain their contracts. Consumers should not match the entire older
148
+ generic error sentence. Raw host/configuration output is not included.
149
+ The Kimi CLI doctor adds the separate `feedback` result described below.
150
+ An absent optional Stop passes; a configured Stop that fails configuration
151
+ or a requested probe exits 1 and makes drift `BROKEN`. This is an
152
+ upgrade-visible diagnostic change. Existing top-level fields and the
153
+ importable `check_kimi()` wrapper retain PreToolUse scope; Claude output is
154
+ unchanged. Configured Stop fields/helper bytes join the existing fingerprints.
155
+ The runtime fingerprint also includes package metadata, so version changes
156
+ can produce `DRIFTED` against an older baseline. Model delivery remains
157
+ `UNVERIFIED` even after a Bash live sentinel.
158
+
159
+ The Kimi Bash profile also adds exact `2.3.0` alongside `0.42.0` and `2.1.1`
160
+ after bounded prompt-CLI/ACP root-Bash trials. This is a declaration change;
161
+ the Core, adapter and bridge stay unchanged. Unlisted versions remain
162
+ `STALE`; a changed profile fingerprint can make an older baseline `DRIFTED`.
163
+ The separately pinned 2.1.1 Lab helper and subagent coverage do not expand.
164
+ See the [2.3.0 evidence](../reports/test-report-kimi-code-block.md#kimi-230-acceptance).
165
+
166
+ The later DSH compatibility work adds `0.2.1-alpha.4` to the default deletion
167
+ adapter alongside the two existing exact versions. Top-level engines and an
168
+ optional DSH peer align with the nested declaration, so the reviewed loaders
169
+ can enforce the list. This installs no production dependency and changes no
170
+ Core policy. Optional native-read fingerprints and Lab host formats remain
171
+ separately pinned. See [DSH compatibility](dsh-compatibility.md) and the
172
+ [native report](../reports/test-report-dsh-alpha4.md).
173
+
174
+ The maintainer selected 0.2.6 for this bounded feedback/diagnostic maintenance;
175
+ the additive surfaces below are carried as an explicit maintenance-version
176
+ exception. This does not relax the general minor-release rules or authorize
177
+ Core policy changes. These additions are absent from published 0.2.5.
178
+
22
179
  ### 0.2.5 feedback maintenance
23
180
 
24
181
  Deletion rules, wildcard refusal, Decision/reason codes, CLI flags and exit
@@ -76,6 +233,68 @@ While the major version is `0`:
76
233
  | check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
77
234
  | Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
78
235
 
236
+ <a id="027-candidate-bounded-maintainer-selected-exception"></a>
237
+
238
+ ### 0.2.7: bounded maintainer-selected exception
239
+
240
+ The maintainer explicitly selected 0.2.7 for the completed Cleanup Copilot,
241
+ deletion-admission hardening and optional local MCP adapter. This version
242
+ is a bounded exception to the general minor-release rules above; the older
243
+ 0.2.4, 0.2.5 and 0.2.6 exceptions do not automatically authorize it. It does
244
+ not relax those rules for other patch releases or resume the 0.3.0 plan.
245
+
246
+ The upgrade-visible changes are explicit:
247
+
248
+ - Covered automated deletion/compensation paths now enforce persistent
249
+ session byte/entry budgets, rate/repeated-target-set limits and quarantine
250
+ admission capacity. Regenerable direct deletion also consumes applicable
251
+ budgets. Failed admitted operations and restores do not refund them.
252
+ - Ordinary large batches now BLOCK with Cleanup guidance before covered
253
+ compensation; reviewed terminal-confirmed Cleanup provides a ten-minute,
254
+ per-path approval for that gate only. It cannot bypass other limits.
255
+ - Optional deletion configuration and configured protected paths precede
256
+ artifact/housekeeping exemptions. Invalid configuration or unavailable
257
+ admission state refuses new covered deletion instead of silently disabling
258
+ the checks. The configuration directory and admission controls are protected.
259
+ - Seven additive reason codes are introduced: `BLOCK_DELETE_CONFIG_INVALID`,
260
+ `BLOCK_DELETE_PROTECTED`, `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`,
261
+ `BLOCK_DELETE_REPEAT`, `BLOCK_DELETE_BATCH_CONFIRM` and
262
+ `BLOCK_DELETE_STATE_INVALID`. Existing code names, decision classes,
263
+ check exit codes, recovery manifests and transaction strategies retain
264
+ their meanings.
265
+ - Cleanup adds explicit plan/selection/terminal confirmation; optional MCP
266
+ adds a separate stdio tool interface and SDK environment, not automatic
267
+ interception or a new host ASK/resume protocol.
268
+
269
+ Default limits are a 5-GiB/100000-entry quarantine admission ceiling,
270
+ 1-GiB/10000-entry cumulative session budget, 60 operations per 60 seconds,
271
+ five admissions of the same target set per window, and batch review above
272
+ 256 MiB or 1000 filesystem entries. These are logical admission figures,
273
+ including directory metadata and conservative hardlink counting, not an OS
274
+ disk quota. See the [limit guide](../guides/deletion-limits.md) for fixed
275
+ inventory bounds and configuration semantics.
276
+
277
+ Normal restore, explicit GC and unprotected quarantine payload housekeeping
278
+ retain their exemptions; existing compound ASK and Git SNAPSHOT paths are
279
+ outside the new budget. Capacity pressure never authorizes automatic GC or
280
+ a permanent-delete fallback. Operators should inspect status and the stated
281
+ reason, review a fresh Cleanup plan for a batch refusal, or explicitly reset
282
+ the current budget with an interactive `RESET` only after investigating the
283
+ caller. Protection/configuration failures require preserving evidence and
284
+ correcting the actual issue, not removing state or changing identity.
285
+
286
+ The changed existing shapes are recorded in
287
+ [F32](../history/friction.md#f32-deletion-admission),
288
+ [F33](../history/friction.md#f33-batch-confirmation) and
289
+ [F34](../history/friction.md#f34-deletion-protection).
290
+ The [0.2.7 version notes](../releases/release-notes-0.2.7.md) describe scope
291
+ and upgrade impact, including the passing local 1129-case/two-Node-group and
292
+ 155-file versioned-package checks. The 2026-10-29 local preparation checkpoint
293
+ did not include remote CI or publication; the earlier 1090/1123-case and
294
+ real-Kimi evidence keeps its original scope.
295
+ No legal hold, directory retention or deletion-certificate capability is
296
+ introduced by this version.
297
+
79
298
  ### 0.2.4 maintenance patch exception
80
299
 
81
300
  For this release, the maintainer explicitly selected `0.2.4` for the recovery
@@ -115,6 +334,7 @@ must accept the additional refusal reason and ignore unknown optional fields.
115
334
  | `.agent-guard/exfil-allow.toml` exemption file | minor | Read from the workspace root only; values exempted by `sha256:...`, never by value |
116
335
  | `doctor.py --check-drift` report and adapter `compatibility.json` profiles | minor | Additive local preflight. Without drift flags the doctor keeps its previous process-execution and exit behavior; `CURRENT` never promotes live interception above `UNVERIFIED` |
117
336
  | `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
337
+ | Kimi doctor `feedback` object (0.2.6) | additive diagnostic | Existing top-level fields retain PreToolUse scope; optional Stop has separate configuration/local results and always-unverified model delivery. Absent Stop passes; a configured Stop failure exits 1 and prevents baseline creation/live sentinel. Configured Stop fields/helper join drift fingerprints. `check_kimi()` retains its PreToolUse-only contract; Claude output is unchanged. |
118
338
  | Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
119
339
 
120
340
  ### 0.2.5-rc1 assessment contract clarification (source candidate)
@@ -307,7 +527,8 @@ projection is described above; it does not rewrite manifests or old log bytes.
307
527
 
308
528
  A changed default verdict for an existing shape is a **minor** release and
309
529
  requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
310
- shift. The bounded 0.2.4 and 0.2.5-rc1 exceptions are recorded above. Additive reason codes
530
+ shift. The bounded 0.2.4, 0.2.5-rc1 and 0.2.7 exceptions
531
+ are recorded above. Additive reason codes
311
532
  are listed above; this table is for shapes
312
533
  whose *existing* verdict moved.
313
534
 
@@ -320,6 +541,9 @@ whose *existing* verdict moved.
320
541
  | `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
321
542
  | Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
322
543
  | Quarantine root/control paths, protected metadata inside trash, or an in-workspace storage parent | Could be allowed as housekeeping or regenerable content | `BLOCK_PROTECTED_PATH` | Recovery/state evidence protection precedes housekeeping (introduced in 0.2.5-rc1, F26) |
544
+ | Covered deletion/compensation after session, rate, repeated-target-set or quarantine admission limits are reached | Could continue through existing relocation or artifact policy | `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE` or `BLOCK_DELETE_REPEAT` | Persistent admission suppresses repeated deletion and storage growth (0.2.7 exception, F32) |
545
+ | Covered automated request above the batch threshold, or changed/expired Cleanup approval | Could compensate or directly delete under existing policy | `BLOCK_DELETE_BATCH_CONFIRM` | Review a fresh plan and confirm selected paths through Cleanup; approval lifts only this gate (F33) |
546
+ | Configured protected paths/configuration directory, malformed deletion policy or unusable admission state | Could follow ordinary artifact/relocation policy without these checks | `BLOCK_DELETE_PROTECTED`, `BLOCK_DELETE_CONFIG_INVALID` or `BLOCK_DELETE_STATE_INVALID` | Protection and usable admission evidence precede covered execution; no silent bypass (F34) |
323
547
 
324
548
  Unchanged on purpose: a genuine compensation fault (`git stash create`
325
549
  failing, a relocation that does not cover every target, an audit intent
@@ -0,0 +1,65 @@
1
+ # DSH compatibility
2
+
3
+ The default deletion adapter in Agent Guard 0.2.6 admits three
4
+ exact DSH versions:
5
+
6
+ - `0.1.5-rc.1`
7
+ - `0.2.0-rc.2`
8
+ - `0.2.1-alpha.4`
9
+
10
+ Version 0.2.5 retains its two-version declaration. For alpha.4, upgrade to
11
+ 0.2.6 or use a reviewed checkout containing the new declaration.
12
+
13
+ ## Separate feature boundaries
14
+
15
+ | Feature | Admitted hosts | Additional conditions |
16
+ |---|---|---|
17
+ | Default deletion interception, recovery tools and prompt guidance | The three exact versions above | Python 3.9+ and Git; successful plugin activation |
18
+ | Optional native text-read redaction | `0.1.5-rc.1`, `0.2.0-rc.2` | Node 22, reviewed SDK file hashes, tool/provider shape and explicit opt-in |
19
+ | Lab native capture and paired review | `0.1.5-rc.1`, `0.2.0-rc.2` | Separate native-format/config contracts and operator review |
20
+
21
+ Alpha.4 support concerns the default deletion adapter. It does not admit
22
+ alpha.4 to the read prototype or Lab. The other versions examined during SDK
23
+ research remain candidates, including alpha.1–alpha.3; adjacent prereleases
24
+ and future versions are not implicitly supported.
25
+
26
+ ## Declarations and loading
27
+
28
+ [`adapters/dsh/compatibility.json`](../../adapters/dsh/compatibility.json)
29
+ records the default adapter's exact tested versions and scope. Manifest tests
30
+ require its list to match all three declarations in `package.json`:
31
+
32
+ - Top-level `engines.dsh`, used preferentially by alpha.4's loader.
33
+ - Optional `peerDependencies["@deepseek-ai/dsh"]`, used by the older rc.2
34
+ compatibility checker. npm does not install this optional peer for the user.
35
+ - Nested `dsh.engines.dsh`, retained as bundle metadata.
36
+
37
+ The nested field alone did not enforce host-version admission. The two
38
+ reviewed compatibility helpers accept the three declared versions and reject
39
+ the tested unlisted versions without exemptions. Older loaders without that
40
+ helper still require the user to check this list and successful activation.
41
+ No adapter fallback bypasses a host compatibility rejection.
42
+
43
+ Resolve SDK packages from the selected DSH package's module context: SDKs may
44
+ be hoisted, and their versions can differ from the CLI root. The reviewed
45
+ legacy installation pairs root `0.1.5-rc.1` with key SDK `0.1.5-rc.2` artifacts.
46
+
47
+ ## Evidence and limits
48
+
49
+ The [alpha.4 report](../reports/test-report-dsh-alpha4.md) records real CLI
50
+ Profile/Boot, native Bash, recovery and scripted root/child-agent checks.
51
+ The same source was checked on both previously admitted versions. These runs
52
+ made no external model requests and used isolated homes/profiles/workspaces.
53
+
54
+ The existing shell bridge already selects `execute().result()` when available
55
+ and retains the legacy `run()` path. Verdicts, compensation, rm wildcard
56
+ refusal and recovery formats are unchanged. A checker failure after the hook
57
+ registers denies the matched call. Missing/failed plugin initialization still
58
+ does not stop the host's other tools.
59
+
60
+ Native policy-forwarding checks used `danger-full-access`; unit coverage also
61
+ checks distinct root/child policies. This does not certify OS sandbox
62
+ confinement. Interactive approval UI, arbitrary PTC calls, concurrent agents,
63
+ other tools, GUI activation and real-model behavior require separate evidence.
64
+ `agent_guard_status` continues to distinguish local registration from live
65
+ interception and does not promote itself to a host certificate.
@@ -17,6 +17,12 @@ bypass. Therefore:
17
17
  - You must NOT claim: sandboxing, containment of malicious agents,
18
18
  prevention of determined bypass.
19
19
 
20
+ Version **0.2.7** adds the bounded deletion-admission and optional MCP surfaces
21
+ below. Confirm package availability through the exact GitHub release and npm
22
+ version links in the [version notes](../releases/release-notes-0.2.7.md).
23
+ This version does not add legal hold,
24
+ directory retention or deletion certificates, or resume the 0.3.0 plan.
25
+
20
26
  ## Assets
21
27
 
22
28
  1. User data inside the workspace (tracked, untracked, ignored).
@@ -34,7 +40,53 @@ bypass. Therefore:
34
40
  | 5 | Symlink confusion (delete link vs target, trailing slash dereference) | Lexical boundary analysis; link relocation preserves the link; realpath recorded | Low |
35
41
  | 6 | TOCTOU between classification and execution | Checks and moves are not atomic. Native hooks run Core before handing control back to host execution; there is no promised maximum gap | Concurrent changes can invalidate facts or affect later execution. Atomic isolation remains unimplemented |
36
42
  | 7 | Destructive restore | Relocation destinations and sources are checked against the workspace and their quarantine transaction. IDs and directory locations are validated; leaf symlinks retain their semantics. Human `--force` preserves an occupant through a separate relocation transaction before replacement; failed preservation stops that item | Checks and moves are not atomic against concurrent changes. Cross-filesystem failures may leave a partial destination or backup; inspect the filesystem and reported transaction IDs. Preserved versions add storage use and follow existing explicit GC |
37
- | 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; `status.py` exposes size; 30-day/5-GiB soft eligibility with explicit audited purge | A human or scheduler must execute purge; audit is retained |
43
+ | 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; size/status and explicit GC. Version 0.2.7 adds cross-process capacity admission, persistent session budgets, rate/repeat limits and confirmed large batches | Logical admission is not an OS quota. Audit, directory metadata and unrelated writers can still grow storage; failures/restores do not refund session charges; GC stays explicit. Same-UID configuration/state/session changes remain possible |
44
+ | 9 | Agent deletes configured evidence or resets its own deletion budget | Shared protection in 0.2.7 covers configured paths and ancestors before artifact/housekeeping exemptions; configuration and admission control files are protected. CLI budget reset requires terminal acknowledgement | Portable protection and TTY are not independent authority against same-UID processes; no authenticated human guarantee |
45
+
46
+ The 0.2.7 admission rules are described in the
47
+ [deletion limits guide](../guides/deletion-limits.md), including measured
48
+ three-run, package and real Kimi validation and its platform/tool limits.
49
+ The published 0.2.6 baseline has only the existing soft retention/GC mechanism.
50
+
51
+ ## Optional local MCP boundary
52
+
53
+ The 0.2.7 [MCP adapter](../guides/mcp.md) offers explicit tools under one
54
+ startup-bound workspace and stable budget identity. It reuses the CLI policy,
55
+ audit and recovery paths; tool arguments cannot change the binding or enable
56
+ force restore, GC execution, budget reset or Cleanup approval. Safe-delete
57
+ quarantine targets are refused to keep that API from becoming a permanent-GC
58
+ shortcut. Tool annotations and client approval settings are hints, not server
59
+ authorization or authenticated human identity.
60
+ Startup session selection controls both existing CLI authorization mode and
61
+ deletion budget; omission uses legacy CLI state and the shared default bucket.
62
+ Saved restrictions are reused only with the same workspace, quarantine and
63
+ session. The caller's native-session restrictions or in-memory veto are not
64
+ automatically transferred; those require trusted host-side bridging.
65
+
66
+ This service does not intercept shell/script/editor operations that bypass
67
+ its tools. Same-UID processes can still edit state or launch another service.
68
+ Client cancellation, disconnects and timeouts do not prove rollback or lack
69
+ of mutation; inspect recovery transactions before retrying. Results may
70
+ contain local paths and metadata and are not a general disclosure-sanitization
71
+ channel. The optional SDK adds its own dependency surface; a local stdio
72
+ server exposes no network listener.
73
+
74
+ The local 2026-10-28 candidate's first full run had one unresolved observer
75
+ READY-startup error; the second passed 1123 Python cases and both Node groups
76
+ without failures, errors, skips or timeouts. A 154-file offline installation
77
+ and three real Kimi 2.3.0 root-MCP trials passed. These observations do not
78
+ establish a timeout fix, remote-CI success, native Windows/macOS/shared-storage
79
+ compatibility or live Claude/Cursor/Codex support. See the guide for the full
80
+ failure history, optional-SDK test skips and measured scope; older hook and
81
+ release evidence remains separate.
82
+ Those are pre-version-alignment observations. The subsequent 0.2.7 candidate
83
+ passed 1129 Python cases and both Node groups without failures, errors, skips
84
+ or timeouts; its 155-file offline package passed installed MCP checks with
85
+ matching 0.2.7 service identity. See the
86
+ [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
87
+ This is local protocol/package evidence, with no new real-model trial or
88
+ expanded host/platform coverage. The 2026-10-29 local preparation checkpoint
89
+ did not include remote CI or publication.
38
90
 
39
91
  ## guard-lab diagnostic boundary
40
92