@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
@@ -2,19 +2,32 @@
2
2
 
3
3
  ## Positioning
4
4
 
5
- agent-guard is **Agent Reliability Infrastructure**: it lowers the
6
- probability that an autonomous agent causes irreversible loss through a
7
- misjudged deletion, a mis-expanded command, or mistaken context - and it
8
- leaves a recovery path and an evidence trail when anything destructive does
9
- happen. It is explicitly *not* a sandbox or security boundary (see
10
- `threat-model.md`).
5
+ agent-guard is **Agent Reliability Infrastructure** with three main
6
+ capabilities: Exfil-guard checks text for disclosure risks, Delete-guard
7
+ preserves recovery paths for supported destructive operations, and Guard-lab
8
+ provides controlled experiments with bounded evidence. The
9
+ [threat model](threat-model.md) describes the trust and coverage limits.
11
10
 
12
- The shared Core, Decision Protocol, and Skills are the product boundary.
13
- Harness adapters are replaceable translations onto host-native hooks; DSH,
14
- Claude Code, Codex, or any future host is a compatibility target rather than
15
- the identity of the project.
11
+ The shared Core, Decision Protocol, Skills and Lab CLI define these workflows.
12
+ Adapters connect them to host-native hooks or explicit tools. DSH, Claude
13
+ Code, Codex and other hosts have separate compatibility and coverage evidence;
14
+ see the [capability matrix](../guides/harness-capabilities.md).
16
15
 
17
- ## The four pillars and where they live
16
+ ## Three functional areas
17
+
18
+ | Main capability | Functions and implementation | Contract and guides |
19
+ |---|---|---|
20
+ | **Exfil-guard** | Text detection/redaction in `core/redaction.py`, disclosure decisions in `core/policy.py`, and safe config views in `core/safe_view.py` | [Exfil-guard Skill](../../skills/exfil-guard/SKILL.md) |
21
+ | **Delete-guard** | Classification, authorization, recovery and audit; Cleanup Copilot delegates execution to `safe_delete`; deletion admission applies shared limits; the current MCP adapter exposes deletion/recovery tools and its doctor checks them through read-only queries | [Delete-guard Skill](../../skills/delete-guard/SKILL.md) · [Cleanup](../guides/cleanup-plan.md) · [Limits](../guides/deletion-limits.md) · [MCP](../guides/mcp.md) |
22
+ | **Guard-lab** | `guard_lab.py` and `core/lab.py` provide a user-controlled diagnostic plane: calibration, declared-channel observation and matched comparisons | [Lab workflow and evidence](../lab/guard-lab.md) |
23
+
24
+ Core and adapters provide shared infrastructure. The
25
+ [recovery-audit Skill](../../skills/recovery-audit/SKILL.md) supplies an auxiliary
26
+ workflow for reconstructing workspaces and auditing incident recovery.
27
+
28
+ <a id="the-four-pillars-and-where-they-live"></a>
29
+
30
+ ## Delete-guard's four pillars
18
31
 
19
32
  | Pillar | Question it answers | Component |
20
33
  |---|---|---|
@@ -305,19 +318,32 @@ order of value:
305
318
 
306
319
  ## Delivery status and design directions
307
320
 
308
- The stable release line is 0.2.6. Previous stable 0.2.5, opt-in
309
- 0.2.4-hotfix.1 and prerelease 0.2.5-rc3 retain their separate artifacts.
321
+ Version [0.2.8](../releases/release-notes-0.2.8.md) adds MCP connection
322
+ diagnosis and protocol-interruption validation. The existing five tools,
323
+ deletion policy and recovery format
324
+ retain their contracts. Direct-service diagnosis, actual-host connection,
325
+ model use and native interception have separate evidence requirements.
326
+
327
+ Version [0.2.7](../releases/release-notes-0.2.7.md) introduced reviewed Cleanup
328
+ plans, shared deletion admission and optional local MCP tools. Confirm
329
+ availability through the exact GitHub release and npm
330
+ version links in those notes; a source version does not establish publication.
331
+ Earlier stable 0.2.6/0.2.5, opt-in 0.2.4-hotfix.1 and prerelease 0.2.5-rc3
332
+ retain their separate artifacts and evidence.
310
333
  Version 0.2.5 retains RC recovery, shared audit,
311
334
  observer maintenance and [defensive research](../research/README.md), plus
312
335
  clearer local startup/status and retained-storage feedback. Private research
313
336
  methods do not add a general authorization service or production enforcement
314
- point. Deletion rules and execution routes retain their RC behavior.
315
- See [release notes](../releases/release-notes-0.2.6.md) and
337
+ point. Those historical versions retain their RC deletion rules and execution routes.
338
+ See [release notes](../releases/release-notes-0.2.7.md) and
316
339
  [compatibility](compatibility.md) for behaviour and validation boundaries.
317
340
  Release [0.2.6](../releases/release-notes-0.2.6.md) adds
318
341
  optional Kimi Stop feedback, its doctor checks and Lab preflight diagnostics.
319
342
  It also adds reviewed DSH alpha.4 default deletion and Kimi 2.3.0 Bash compatibility.
320
- Core policy is unchanged; scope and delivery limits are tracked in the
343
+ That 0.2.6 maintenance did not change Core policy. Version 0.2.7 adds the
344
+ bounded deletion-admission rules and upgrade-visible refusals recorded in
345
+ the [compatibility contract](compatibility.md#027-bounded-maintainer-selected-exception).
346
+ Historical scope and delivery limits remain in the
321
347
  [maintenance details](../releases/unreleased.md).
322
348
 
323
349
  The milestones below describe historical delivery and future design scope,
@@ -4,13 +4,26 @@ 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.6](../releases/release-notes-0.2.6.md), carrying
8
- the cumulative RC maintenance and the feedback/diagnostic additions below.
9
- The opt-in prerelease remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md),
10
- 0.2.5 is the previous stable, and
7
+ Version [0.2.8](../releases/release-notes-0.2.8.md) adds diagnosis and
8
+ reliability maintenance to the published
9
+ [0.2.7](../releases/release-notes-0.2.7.md) baseline. Use exact GitHub release
10
+ and npm version links to confirm availability; a version in source or a local
11
+ tarball does not establish publication.
12
+ Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
13
+ RC maintenance and the feedback/diagnostic additions below. The opt-in
14
+ prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
15
+ 0.2.5 and the
11
16
  [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
12
- is an opt-in quarantine protection backport. Versioned sections retain the
13
- origin and preparation labels of changes introduced by earlier releases.
17
+ quarantine protection backport retain their separate artifacts. Versioned
18
+ sections retain the origin and preparation labels of changes introduced by
19
+ earlier releases.
20
+
21
+ The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
22
+ optional MCP tools. The bounded versioning decision is recorded below; the
23
+ separate 0.3.0 plan remains paused.
24
+ The later **0.2.8** selection is independently scoped to MCP diagnosis and
25
+ reliability maintenance, as recorded below; earlier exceptions do not grant
26
+ permission to change unrelated policy under a patch number.
14
27
 
15
28
  RC3 publishes defensive research and an example around the existing four
16
29
  zero-model controls. Experimental disclosure labels and private delegation
@@ -20,6 +33,141 @@ is introduced by the research documentation.
20
33
 
21
34
  ## The adapter contract (frozen surface)
22
35
 
36
+ <a id="mcp-doctor-028-development"></a>
37
+
38
+ ### MCP doctor (0.2.8)
39
+
40
+ `doctor.py mcp` is an explicit local diagnosis path. It accepts the selected
41
+ Python interpreter, existing workspace, optional reviewed server script and
42
+ a diagnostic timeout; it does not parse or rewrite host configuration. It
43
+ checks the optional pinned SDK and its imports, service handshake/name/version,
44
+ the five-tool set and query annotations, workspace/quarantine binding and
45
+ successful status/transactions/gc_plan calls. The selected service version
46
+ must match the doctor's package version. It does not call a model or execute
47
+ deletion, restore, GC or budget-reset tools.
48
+
49
+ Its independent `schema_version: 1` report uses fixed `status`, `stage`, `code`,
50
+ `message`, `guidance` and `checks` fields rather than raw child stderr,
51
+ configuration contents or recovery/audit records. It keeps `host_connection`,
52
+ `model_delivery` and `host_interception` at `UNVERIFIED`: direct service
53
+ diagnosis cannot certify another client's loading or behavior. Exit `0` means
54
+ PASS, `1` means diagnostic failure and `2` remains argument-usage failure.
55
+ Diagnostic codes belong to this report, not the Decision Protocol reason-code
56
+ namespace. Existing Kimi/Claude doctor interfaces retain their semantics.
57
+ `diagnostic_stderr_bytes` is a count, not raw stderr. A successful status check
58
+ also records `deletion_admission` as `BLOCKED` or `READABLE`; the latter means
59
+ the information was inspected, not that deletion is authorized. A connection
60
+ PASS can coexist with blocked admission, which the text renderer highlights.
61
+ The 5–120 second diagnostic deadline defaults to 30 seconds; service-process
62
+ shutdown can add up to three seconds of process waits and one second of reader-thread waiting.
63
+
64
+ The SDK remains separately optional, including when invoking Core/CLI or
65
+ doctor help. Changing package/helper bytes can change existing doctor runtime
66
+ fingerprints and produce `DRIFTED`; an old baseline is not automatically
67
+ replaced. See [options, result scope and recovery after a lost response](../guides/mcp.md#diagnose-a-local-service-028).
68
+
69
+ <a id="local-mcp-tools-027-candidate"></a>
70
+
71
+ ### Local MCP tools (0.2.7)
72
+
73
+ The checkout adds an optional local stdio MCP server with five explicit tools:
74
+ safe_delete, ordinary restore, transactions, status and GC-plan preview.
75
+ It invokes existing CLI operations without a shell, preserves policy/audit/
76
+ recovery semantics and binds workspace/session identity at trusted startup.
77
+ Tool calls cannot select a new workspace, session, environment or quarantine.
78
+ `--session` selects both saved CLI authorization mode and deletion budget;
79
+ omission uses legacy CLI state and the shared default bucket. Reusing saved
80
+ state requires matching workspace, quarantine and session. Native host-session
81
+ restrictions/in-memory veto are not inherited without a trusted bridge.
82
+ Quarantine deletion, force restore, GC execution, budget reset and Cleanup
83
+ approval are not exposed. Existing CLI interfaces remain available separately.
84
+
85
+ The optional `mcp==2.3.0` Python SDK and its transitive dependencies install
86
+ into a separate environment; Core/CLI still has no third-party Python
87
+ requirement. This interface is included in 0.2.7 and is absent from published
88
+ 0.2.6. It does not resume 0.3.0. It is a cooperative tool interface, not expanded
89
+ native interception. Existing host-version evidence and doctor scope do not
90
+ automatically cover MCP. On the 2026-10-28 frozen candidate, the first local
91
+ full run completed 1123 Python cases with one existing observer-startup error
92
+ and did not run Node; its cause remains undetermined. The second full run
93
+ passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
94
+ failures, errors, skips or timeouts. Neither invoked npm directly or changed
95
+ the runtime/tests. A 154-file offline installation and three real Kimi 2.3.0
96
+ native-MCP trials passed; at that checkpoint Claude/Cursor/Codex setup examples
97
+ were docs-only. Later Codex 0.165.0 acceptance of the published 0.2.7 package
98
+ is recorded separately in the [MCP guide](../guides/mcp.md#codex-01650-with-published-027).
99
+ Without the optional SDK, seven protocol tests skip. The added SDK-backed
100
+ Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
101
+ preparation checkpoint. See
102
+ [setup, full failure history and platform/tool limits](../guides/mcp.md).
103
+ Those measurements predate the 0.2.7 version/document alignment and are not
104
+ acceptance of the final versioned artifact. The subsequent 219-file 0.2.7
105
+ candidate passed 1129 Python cases and both Node groups in 1194.265 seconds,
106
+ with no failures, errors, skips, timeouts or automatic retries. Its 155-file
107
+ offline package passed 12 CLI entry-point and installed MCP checks, including
108
+ `serverInfo.version == 0.2.7`. Local release-gate checks passed; that local
109
+ preparation checkpoint did not include final-commit remote CI or publication.
110
+ No additional real-model trial was run. See
111
+ the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
112
+
113
+ <a id="deletion-admission-limits-027-candidate"></a>
114
+
115
+ ### Deletion admission limits (0.2.7)
116
+
117
+ The current checkout adds shared deletion configuration, persistent
118
+ per-session admission budgets, rate/repeat limits and quarantine capacity
119
+ checks. `.agent-guard/delete-policy.json` is optional; invalid configuration
120
+ or state fails closed. Configuration paths and the new quarantine
121
+ `admission.json`, temporary state and `admission.lock` are protected. Existing
122
+ recovery manifests and transaction strategies are retained without migration.
123
+
124
+ New reason codes are `BLOCK_DELETE_CONFIG_INVALID`, `BLOCK_DELETE_PROTECTED`,
125
+ `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`, `BLOCK_DELETE_REPEAT`,
126
+ `BLOCK_DELETE_BATCH_CONFIRM` and `BLOCK_DELETE_STATE_INVALID`. Decision classes
127
+ and `check.py` exit codes retain their contracts. Limits are applied at
128
+ execution admission; an earlier advisory assessment is not a capacity grant.
129
+ Covered automatic compensation/artifact paths can newly BLOCK when a
130
+ configured limit is reached. The general versioning promises below classify
131
+ these as minor safety changes. The maintainer selected 0.2.7 for these bounded
132
+ additions as an explicit exception recorded below, not as a change shipped
133
+ in 0.2.6 or a general permission to change policy in patch releases. The
134
+ separate 0.3.0 plan remains paused.
135
+
136
+ Cleanup retains plan schema version 1 and terminal-confirmed execution, then
137
+ issues metadata/session/configuration-bound, ten-minute approval for each
138
+ selected path once. Covered automatic large-delete checks BLOCK with Cleanup guidance;
139
+ there is no new host ASK/resume protocol. `status.py --reset-delete-budget`
140
+ adds explicit interactive reset of the current bucket, not capacity or GC.
141
+ Existing compound-command ASK and Git SNAPSHOT paths remain outside the new
142
+ budget. Normal restore, explicit GC and unprotected quarantine payload
143
+ housekeeping remain exempt; configuration/control-path protection still applies.
144
+ Same-UID state remains advisory; accounting is logical admitted work, not an
145
+ OS quota. New Core bytes change doctor fingerprints. The 2026-10-28 public
146
+ runtime passed three independent 1090-case Python plus two-Node-group runs,
147
+ an offline 149-file package check and three real Kimi 2.3.0 root-Bash scenarios.
148
+ These local POSIX results do not establish new platform or tool coverage;
149
+ previous Cleanup and release evidence keeps its original scope. See
150
+ [defaults, accounting and recovery](../guides/deletion-limits.md).
151
+
152
+ <a id="cleanup-copilot-027-candidate"></a>
153
+
154
+ ### Cleanup Copilot (0.2.7)
155
+
156
+ The checkout adds `core.cleanup` and `agent-guard-cleanup` with read-only
157
+ planning, categorized candidates and explicit terminal-confirmed selection.
158
+ Execution delegates to the existing safe_delete CLI one concrete target at a
159
+ time. Plan JSON has its own `schema_version: 1`; it is not a new Decision
160
+ Protocol surface. The initial Cleanup-only checkpoint retained existing
161
+ deletion policy; the subsequent admission changes are described above.
162
+ Recovery formats, explicit GC and native adapter tools retain their contracts.
163
+ Cleanup itself adds no third-party Core dependency or configuration migration.
164
+ This feature is included in 0.2.7 and is absent from the published 0.2.6 package.
165
+
166
+ The new Core module and package metadata change doctor runtime fingerprints.
167
+ An old baseline can become `DRIFTED`; it is not automatically replaced.
168
+ See [the CLI contract](../guides/cleanup-plan.md) for confirmation, partial
169
+ execution, output privacy, scan limits and the existing concurrency boundary.
170
+
23
171
  <a id="unreleased-feedback-and-diagnostic-maintenance"></a>
24
172
 
25
173
  ### 0.2.6 feedback and diagnostic maintenance
@@ -125,6 +273,93 @@ While the major version is `0`:
125
273
  | check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
126
274
  | Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
127
275
 
276
+ <a id="028-diagnosis-maintenance-decision"></a>
277
+
278
+ ### 0.2.8: bounded diagnosis maintenance decision
279
+
280
+ The maintainer selected **0.2.8** for the explicit MCP doctor path, real
281
+ protocol-interruption checks and their documentation. Earlier doctor drift
282
+ and live-sentinel additions were classified as minor below. The new optional
283
+ diagnostic surface is carried as this version's bounded maintenance decision;
284
+ the 0.2.7 exception is not inherited and the general release-class promises
285
+ remain in force.
286
+
287
+ The independent MCP doctor parameters, version-1 diagnosis report and exit
288
+ codes are the upgrade-visible additions. Package/helper changes may affect
289
+ existing doctor fingerprints. The five MCP tools and their arguments,
290
+ Decision classes/reasons, default deletion policy, persistent accounting,
291
+ recovery manifests, ordinary restore and preview-only MCP GC retain their
292
+ contracts. No configuration/storage migration or default SDK installation is
293
+ introduced. The diagnosis checks a selected service; it adds no native host
294
+ interception or client configuration management. The 0.3.0 and commercial
295
+ plans are not resumed.
296
+
297
+ Source validation, installed-package and workflow results retain their
298
+ separate checkpoints in the
299
+ [0.2.8 notes](../releases/release-notes-0.2.8.md#validation-status).
300
+
301
+ <a id="027-candidate-bounded-maintainer-selected-exception"></a>
302
+
303
+ ### 0.2.7: bounded maintainer-selected exception
304
+
305
+ The maintainer explicitly selected 0.2.7 for the completed Cleanup Copilot,
306
+ deletion-admission hardening and optional local MCP adapter. This version
307
+ is a bounded exception to the general minor-release rules above; the older
308
+ 0.2.4, 0.2.5 and 0.2.6 exceptions do not automatically authorize it. It does
309
+ not relax those rules for other patch releases or resume the 0.3.0 plan.
310
+
311
+ The upgrade-visible changes are explicit:
312
+
313
+ - Covered automated deletion/compensation paths now enforce persistent
314
+ session byte/entry budgets, rate/repeated-target-set limits and quarantine
315
+ admission capacity. Regenerable direct deletion also consumes applicable
316
+ budgets. Failed admitted operations and restores do not refund them.
317
+ - Ordinary large batches now BLOCK with Cleanup guidance before covered
318
+ compensation; reviewed terminal-confirmed Cleanup provides a ten-minute,
319
+ per-path approval for that gate only. It cannot bypass other limits.
320
+ - Optional deletion configuration and configured protected paths precede
321
+ artifact/housekeeping exemptions. Invalid configuration or unavailable
322
+ admission state refuses new covered deletion instead of silently disabling
323
+ the checks. The configuration directory and admission controls are protected.
324
+ - Seven additive reason codes are introduced: `BLOCK_DELETE_CONFIG_INVALID`,
325
+ `BLOCK_DELETE_PROTECTED`, `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`,
326
+ `BLOCK_DELETE_REPEAT`, `BLOCK_DELETE_BATCH_CONFIRM` and
327
+ `BLOCK_DELETE_STATE_INVALID`. Existing code names, decision classes,
328
+ check exit codes, recovery manifests and transaction strategies retain
329
+ their meanings.
330
+ - Cleanup adds explicit plan/selection/terminal confirmation; optional MCP
331
+ adds a separate stdio tool interface and SDK environment, not automatic
332
+ interception or a new host ASK/resume protocol.
333
+
334
+ Default limits are a 5-GiB/100000-entry quarantine admission ceiling,
335
+ 1-GiB/10000-entry cumulative session budget, 60 operations per 60 seconds,
336
+ five admissions of the same target set per window, and batch review above
337
+ 256 MiB or 1000 filesystem entries. These are logical admission figures,
338
+ including directory metadata and conservative hardlink counting, not an OS
339
+ disk quota. See the [limit guide](../guides/deletion-limits.md) for fixed
340
+ inventory bounds and configuration semantics.
341
+
342
+ Normal restore, explicit GC and unprotected quarantine payload housekeeping
343
+ retain their exemptions; existing compound ASK and Git SNAPSHOT paths are
344
+ outside the new budget. Capacity pressure never authorizes automatic GC or
345
+ a permanent-delete fallback. Operators should inspect status and the stated
346
+ reason, review a fresh Cleanup plan for a batch refusal, or explicitly reset
347
+ the current budget with an interactive `RESET` only after investigating the
348
+ caller. Protection/configuration failures require preserving evidence and
349
+ correcting the actual issue, not removing state or changing identity.
350
+
351
+ The changed existing shapes are recorded in
352
+ [F32](../history/friction.md#f32-deletion-admission),
353
+ [F33](../history/friction.md#f33-batch-confirmation) and
354
+ [F34](../history/friction.md#f34-deletion-protection).
355
+ The [0.2.7 version notes](../releases/release-notes-0.2.7.md) describe scope
356
+ and upgrade impact, including the passing local 1129-case/two-Node-group and
357
+ 155-file versioned-package checks. The 2026-10-29 local preparation checkpoint
358
+ did not include remote CI or publication; the earlier 1090/1123-case and
359
+ real-Kimi evidence keeps its original scope.
360
+ No legal hold, directory retention or deletion-certificate capability is
361
+ introduced by this version.
362
+
128
363
  ### 0.2.4 maintenance patch exception
129
364
 
130
365
  For this release, the maintainer explicitly selected `0.2.4` for the recovery
@@ -357,7 +592,8 @@ projection is described above; it does not rewrite manifests or old log bytes.
357
592
 
358
593
  A changed default verdict for an existing shape is a **minor** release and
359
594
  requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
360
- shift. The bounded 0.2.4 and 0.2.5-rc1 exceptions are recorded above. Additive reason codes
595
+ shift. The bounded 0.2.4, 0.2.5-rc1 and 0.2.7 exceptions
596
+ are recorded above. Additive reason codes
361
597
  are listed above; this table is for shapes
362
598
  whose *existing* verdict moved.
363
599
 
@@ -370,6 +606,9 @@ whose *existing* verdict moved.
370
606
  | `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) |
371
607
  | 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) |
372
608
  | 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) |
609
+ | 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) |
610
+ | 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) |
611
+ | 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) |
373
612
 
374
613
  Unchanged on purpose: a genuine compensation fault (`git stash create`
375
614
  failing, a relocation that does not cover every target, an audit intent
@@ -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