@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
@@ -0,0 +1,227 @@
1
+ # Cleanup Copilot / 工作区清理计划
2
+
3
+ Cleanup Copilot is introduced in **0.2.7** and is absent from 0.2.6. Run the
4
+ Python script from the selected package or reviewed checkout; the package
5
+ also exposes `agent-guard-cleanup`. The shared
6
+ [deletion admission rules](deletion-limits.md) also apply when executing it.
7
+ See the [0.2.7 notes](../releases/release-notes-0.2.7.md) for upgrade effects,
8
+ versioned validation and exact-version availability checks. Source/package
9
+ metadata alone does not establish publication.
10
+
11
+ Cleanup Copilot scans workspace metadata and proposes concrete cleanup
12
+ targets. The default command writes no files, audit records, quarantine
13
+ layout or Git exclude rules. It also suppresses project bytecode creation.
14
+ Planning does not call `safe_delete --dry-run`, whose metadata side effects
15
+ remain documented in the [policy reference](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
16
+
17
+ ## Review a plan
18
+
19
+ From the intended workspace, run:
20
+
21
+ ```sh
22
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py
23
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json
24
+ ```
25
+
26
+ `--root /absolute/path/to/workspace` explicitly chooses the workspace
27
+ boundary. Otherwise the command uses the existing workspace discovery and
28
+ `AGENT_GUARD_WORKSPACE` setting. Existing trash, session mode and artifact
29
+ settings and shared deletion configuration are respected. Git supplies ignore/tracking facts; without usable
30
+ Git facts no target is proposed as regenerable.
31
+
32
+ | Category | Evidence | Default handling |
33
+ |---|---|---|
34
+ | 可再生 / `regenerable` | Git-ignored, matches an existing artifact pattern, and no tracked descendants | Selectable if existing policy permits; inspect `effect` |
35
+ | 明确废弃 / `discarded` | Caller explicitly declared the path/subtree with `--discard PATH` | Selectable if existing policy permits; ordinary content goes to quarantine |
36
+ | 不确定 / `uncertain` | No sufficient regeneration or discard evidence, or incomplete scan | Review only |
37
+ | 受保护 / `protected` | `.git`, `.internal`, quarantine names/boundaries, explicit protected paths or special entries | Keep; do not traverse |
38
+
39
+ Age, being untracked, or being ignored alone never means discarded.
40
+ Declare known disposable paths and additional evidence/backup roots explicitly:
41
+
42
+ ```sh
43
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
44
+ --discard old-output --protect backups --protect evidence
45
+ ```
46
+
47
+ These flags are invocation options, not persisted cleanup rules. Shared
48
+ `.agent-guard/delete-policy.json` protection is also applied, and its directory
49
+ is always protected. Discard
50
+ declarations must exist and stay within the workspace; the workspace root
51
+ cannot be declared discarded. Protection overrides discard declarations and
52
+ artifact names. Protected descendants prevent selection of their ancestor;
53
+ eligible siblings may remain visible as individual entries. Existing Core
54
+ protection can prune an entire parent containing a recovery bucket.
55
+
56
+ Declared protection covers both the supplied path and its physical location
57
+ inside the workspace. A newly discovered nested protected symlink whose
58
+ physical location was not declared makes the plan incomplete with
59
+ `PROTECTED_ALIAS_REQUIRES_EXPLICIT_PROTECT`. Repeat the plan with
60
+ `--protect` naming that link before selecting other targets.
61
+
62
+ Unknown subtrees collapse into review rows unless generated, discarded or
63
+ protected descendants need to be shown. Candidate directories and their
64
+ children are not offered as overlapping selections.
65
+
66
+ ## Confirm and execute
67
+
68
+ Copy the plan's full `plan_id`, select exact rows marked `selectable`, and
69
+ repeat the same root, discard, protect and scan-limit options:
70
+
71
+ ```sh
72
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
73
+ --discard old-output --protect backups --protect evidence \
74
+ --execute --plan-id '<plan-id>' --select build --select old-output
75
+ ```
76
+
77
+ The example assumes `build` and `old-output` actually appear as selectable
78
+ entries in your reviewed plan. Paths passed to `--select` are literal,
79
+ workspace-relative paths, not patterns. Quote spaces and use `--select=-name`
80
+ for a leading dash.
81
+
82
+ The command checks the current plan against the supplied ID, prints the
83
+ selected paths, sizes and effects, then asks the operator to type
84
+ `EXECUTE` in an interactive terminal. Any other answer or EOF
85
+ cancels without creating guard metadata. Piped/noninteractive execution is
86
+ refused; there is no `--yes` flag. Agents may propose a plan and explain it;
87
+ they must leave the confirmation response to the human operator. No new
88
+ native host tool or host approval integration is supplied.
89
+
90
+ After confirmation, the command rescans and checks the plan again before
91
+ the first mutation. The ID covers workspace, options, metadata/membership,
92
+ policy projections, mode, artifact settings and deletion configuration.
93
+ Changed plans require fresh review. It is not a content hash or an atomic filesystem snapshot; concurrent
94
+ changes during execution retain the existing Core's TOCTOU limits. Terminal
95
+ acknowledgement is a workflow check, not proof of human identity against a
96
+ same-UID process. See the [threat model](../design/threat-model.md).
97
+
98
+ The subsequent deletion hardening creates a ten-minute approval only after
99
+ this confirmation and rescan. It binds exact selected paths and their measured
100
+ metadata to the current session and deletion configuration; each path is
101
+ consumed once before execution. Changed, expired or replayed approval fails.
102
+ Approval satisfies the batch-review gate but does not bypass capacity,
103
+ session budget, rate/repeat rules or protected paths. Ordinary large deletes
104
+ through `check --enforce` or `safe_delete` BLOCK with Cleanup guidance rather
105
+ than entering a new host ASK flow. This gate covers automated deletion paths;
106
+ existing compound ASK, Git snapshots and quarantine housekeeping retain their
107
+ separate rules. See [deletion limits](deletion-limits.md).
108
+
109
+ Execution invokes existing `safe_delete` once per concrete target:
110
+
111
+ - `effect: delete`: current policy will physically delete the target. This
112
+ commonly applies to ignored build outputs. There is no recovery copy.
113
+ - `effect: quarantine`: current policy will relocate content and return a
114
+ transaction ID. Data remains on disk. Use the existing restore or explicit
115
+ GC workflow in the [feedback guide](recovery-feedback.md).
116
+ - `effect: blocked`, `keep` or `review`: not selectable. Existing mode and
117
+ boundary refusals cannot be overridden by confirmation.
118
+
119
+ An explicit discard declaration does not force a particular deletion
120
+ method; the actual `effect` and `policy_code` come from existing policy.
121
+ Separate invocations preserve each row's effect when a selection mixes
122
+ generated and ordinary targets. On a child failure, execution stops and
123
+ keeps earlier and partial transaction reports. Inspect those IDs before
124
+ retrying. No automatic purge or rollback runs.
125
+
126
+ ## Sizes, limits and output
127
+
128
+ Sizes are logical file bytes, with hardlinks counted once per entry and per
129
+ category summary. Directory metadata is omitted; links use their own size
130
+ and directory links are not traversed. Protected subtree sizes are unknown.
131
+ Hardlinks shared across categories may appear in both category totals.
132
+ These values do not predict freed blocks, sparse-file allocation or storage
133
+ released by quarantine. Errors retain partial observations.
134
+
135
+ Execution admission measures directory metadata too and conservatively counts
136
+ hardlinks per filesystem entry. Its budget/capacity figures can therefore be
137
+ larger than these displayed plan sizes. A selectable plan is not a reservation
138
+ of capacity or session budget.
139
+
140
+ The default budget is 10,000 entries and depth 32 below the workspace.
141
+ `--max-entries` must be positive; `--max-depth` accepts 1–128. A reached limit,
142
+ unreadable subtree or observed directory mutation makes `complete: false`
143
+ and prevents execution. Increase the scope limits only after reviewing the
144
+ reported partial scan. Protected exclusions are part of the declared scan,
145
+ not incomplete traversal errors.
146
+
147
+ JSON uses `schema_version: 1`, a stable `plan_id`, `summary`, `entries`, scan
148
+ `errors`/`warnings`, options and workspace/trash context. Entry fields include
149
+ `path`, `category`, `size_bytes`, `size_complete`, `reason`, `selectable`,
150
+ `effect`, `policy_code` and an opaque metadata fingerprint. Paths remain
151
+ exact local paths and can be private; review output before sharing it.
152
+ Planning itself persists none of this output. Executing retains existing
153
+ safe_delete audit and recovery contracts.
154
+
155
+ When saving a plan, write it outside the scanned workspace or into a
156
+ protected subtree. Creating or updating an ordinary output file inside the
157
+ scan changes the workspace metadata and can invalidate the saved plan ID.
158
+
159
+ Exit 0 means a complete plan, cancellation, or completed execution. Exit 1
160
+ means an incomplete default scan. Exit 2 means invalid options, refusal or
161
+ stopped execution; inspect `reports` for partial effects.
162
+
163
+ Names unsupported by the existing concrete path API, including glob
164
+ characters, substitution syntax or trailing whitespace, remain blocked as
165
+ individual selections. Ordinary spaces and leading dashes are supported.
166
+ No rm wildcard rule, recovery format, GC policy or production dependency
167
+ changes. Adding the Core module and package command changes doctor runtime
168
+ fingerprints, so older baselines can become `DRIFTED`; review and validate
169
+ before writing a new baseline at a new path.
170
+
171
+ ## 中文摘要
172
+
173
+ 本功能自 0.2.7 加入。默认扫描只输出计划,不修改工作区;“明确废弃”仅来自
174
+ 调用者显式声明,旧文件/未跟踪文件不会自动变为垃圾。执行必须提供计划 ID、选定
175
+ 具体条目并由操作者在终端确认,确认后复查,再逐项走现有 safe_delete。普通文件
176
+ 隔离后仍占空间,可再生产物符合现有规则时直接物理删除。保护项、不完整或过期的
177
+ 计划不能执行;不提供自动清理或新的宿主原生工具。
178
+
179
+ ## Validation scope
180
+
181
+ The following historical checkpoints used 0.2.6 package metadata. They do not
182
+ certify the versioned 0.2.7 artifact; its separate validation is tracked
183
+ in the [0.2.7 notes](../releases/release-notes-0.2.7.md).
184
+
185
+ On 2026-10-28, the subsequent shared configuration, admission limits and
186
+ operation-bound approvals passed three independent full runs on one frozen
187
+ public runtime: 1090 Python cases and both Node groups per run, in 1061.017,
188
+ 1025.315 and 1042.145 seconds. There were no failures, errors, skips, timeouts
189
+ or automatic retries, and frozen source bytes remained unchanged. The
190
+ existing diagnostic collector preserved `npm test` scope and deadlines;
191
+ the npm command itself was not invoked.
192
+
193
+ The 149-file offline package passed installed CLI, real terminal confirmation,
194
+ mixed physical deletion/quarantine/restore, budget/reset, loop, capacity,
195
+ protection and compound-batch checks. Three real Kimi Code 2.3.0 root-Bash
196
+ scenarios passed: recoverable deletion, same-session budget refusal and
197
+ configured protection. Nine configured-route requests returned HTTP 200;
198
+ the loopback gateway's server-side model identity was not independently
199
+ authenticated. See [deletion limits](deletion-limits.md) for scope and exceptions.
200
+ Acceptance receipts were then updated in documentation without changing runtime
201
+ or tests. The following results retain the earlier Cleanup-only checkpoint.
202
+
203
+ On 2026-10-28, the Cleanup-only public runtime passed one continuous full-suite
204
+ run: 1012 Python cases and both Node groups in 979.997 seconds, within the
205
+ original 1800-second budget. There were no failures, errors, skips or
206
+ retries. The local environment was ARM64/PRoot POSIX with Python 3.13.5
207
+ and Node 22.23.4.
208
+
209
+ This run used the existing diagnostic unittest result collector and then
210
+ both Node commands, preserving the test scope, assertions and deadlines
211
+ from `npm test`. It did not invoke the npm command itself. An earlier
212
+ literal `npm test` run timed out after 653 logged completions; follow-up
213
+ checks covered the remaining cases. That timeout is retained, its cause
214
+ remains unresolved, and it did not recur during the continuous rerun.
215
+
216
+ Focused checks passed all 37 cleanup cases and 9 package-manifest cases.
217
+ An offline package installation verified 146 file contents, all 11 CLI
218
+ entry points, actual pseudo-terminal confirmation, physical artifact
219
+ removal, ordinary-file quarantine/restore and noninteractive refusal.
220
+ Planning also passed a write audit; cancelled/stale plans and protected
221
+ symlink paths have regression coverage. That earlier Cleanup-only checkpoint
222
+ made no external model calls.
223
+
224
+ Workspace-alias checks ran locally. Native macOS, native Windows, shared
225
+ Android storage and new host approval integrations were not exercised.
226
+ The existing release matrix and historical host reports retain their own
227
+ version/scope boundaries.
@@ -0,0 +1,150 @@
1
+ # Deletion limits / 删除准入与预算
2
+
3
+ These limits are introduced in **0.2.7** and are absent from 0.2.6. The
4
+ separate 0.3.0 plan remains paused. Versioned validation and exact-version
5
+ availability checks are tracked in the [0.2.7 notes](../releases/release-notes-0.2.7.md);
6
+ the following results retain their earlier deletion-hardening checkpoint,
7
+ which used 0.2.6 package metadata rather than the final 0.2.7 artifact.
8
+ On 2026-10-28, the same frozen public runtime passed three independent full
9
+ runs: each contained 1090 Python cases and both Node groups, taking 1061.017,
10
+ 1025.315 and 1042.145 seconds. No failures, errors, skips, timeouts or automatic
11
+ retries occurred. The existing diagnostic unittest result collector preserved
12
+ the scope and deadlines of `npm test`; the npm command itself was not invoked.
13
+ An offline 149-file package and three real Kimi Code 2.3.0 scenarios also
14
+ passed: recoverable deletion, same-session budget refusal and configured-path
15
+ protection. Nine configured-route model requests returned HTTP 200. The
16
+ loopback gateway's server-side model identity was not independently verified.
17
+ Tests ran on ARM64/PRoot POSIX, Python 3.13.5 and Node 22.23.4; native Windows,
18
+ macOS, PowerShell and Android shared storage were not exercised. Kimi coverage
19
+ is limited to the observed root Bash hook and optional Stop, not other tools
20
+ or subagents. Historical Cleanup/release evidence keeps its original scope;
21
+ the earlier npm timeout remains unexplained and did not recur in these runs.
22
+
23
+ ## Configuration and defaults
24
+
25
+ The optional workspace file `.agent-guard/delete-policy.json` overrides the
26
+ defaults below. An absent file uses defaults without creating configuration.
27
+ The configuration directory is always protected. Unknown or duplicate keys,
28
+ invalid JSON, unreadable configuration and invalid values block new deletion.
29
+
30
+ | Field | Default | Meaning |
31
+ |---|---|---|
32
+ | `quarantine_max_bytes` | 5368709120 (5 GiB) | Admission ceiling for measured existing quarantine plus incoming content |
33
+ | `quarantine_max_entries` | 100000 | Same ceiling in filesystem entries |
34
+ | `session_max_bytes` | 1073741824 (1 GiB) | Cumulative logical bytes admitted for this session |
35
+ | `session_max_entries` | 10000 | Cumulative filesystem entries admitted for this session |
36
+ | `rate_window_seconds` | 60 | Rolling admission window |
37
+ | `rate_max_operations` | 60 | Admitted operations in that window |
38
+ | `repeat_max_operations` | 5 | Admissions of the same normalized target set in that window |
39
+ | `batch_max_bytes` | 268435456 (256 MiB) | Larger operations require confirmed Cleanup execution |
40
+ | `batch_max_entries` | 1000 | Same confirmation threshold in filesystem entries |
41
+ | `protected_paths` | `[]` | Additional literal workspace paths to preserve |
42
+
43
+ Numbers must be integers through `2**63 - 1`; booleans and numeric strings
44
+ are invalid. Byte limits may be zero, meaning no byte allowance, not unlimited.
45
+ Other numeric limits must be positive. Configuration files larger than 1 MiB are rejected.
46
+ Protected paths may be workspace-relative or absolute inside the workspace;
47
+ they may name future paths, but cannot escape through an external directory
48
+ link. A final outward-pointing link itself can be protected.
49
+
50
+ For example, an operator can choose stricter limits and preserve evidence:
51
+
52
+ ```json
53
+ {
54
+ "session_max_bytes": 536870912,
55
+ "rate_max_operations": 30,
56
+ "protected_paths": ["evidence", "backups/current"]
57
+ }
58
+ ```
59
+
60
+ Protection covers named and physical locations, descendants and deletion of
61
+ an ancestor that would remove a protected path. It precedes regenerable and
62
+ quarantine-housekeeping exemptions. Cleanup's `--protect` remains an extra
63
+ invocation-only planning option; use the configuration for shared protection.
64
+
65
+ ## Accounting and execution
66
+
67
+ `core.admission` stores counters and short-lived approvals in the selected
68
+ quarantine's `admission.json`, with `admission.lock` for cross-process
69
+ serialization. Measurement, durable debit and guarded mutation share the
70
+ lock. Missing state starts empty; malformed or unavailable state, lock or
71
+ inventory blocks admission. State, its temporary file and lock are protected
72
+ control files, alongside the existing recovery evidence.
73
+
74
+ `AGENT_GUARD_SESSION` selects a persistent budget within that quarantine;
75
+ its value is hashed for storage. Unnamed CLI processes share one stable
76
+ default bucket, including Cleanup's child processes. Counters charge
77
+ **admitted work**, before mutation. Failed operations and later restores do
78
+ not refund it. The rate and repeat windows expire, but cumulative session
79
+ bytes and entries do not silently renew. The same-target-set rule is a
80
+ simple delete/recreate loop signal, not general anomaly classification.
81
+
82
+ Inventories use bounded `lstat` traversal, count directory metadata and
83
+ links themselves, and conservatively count hardlinks per entry. Capacity
84
+ compares existing quarantine and incoming logical bytes/entries. These
85
+ figures differ from Cleanup's displayed, hardlink-deduplicated candidate
86
+ sizes and from physical disk blocks. Scan errors or changed directories
87
+ are refusals, never zero-size estimates.
88
+
89
+ Raising policy numbers does not raise the implementation's inventory bounds:
90
+ 200000 entries per scan, depth 128, 1024 stored sessions, 32 outstanding
91
+ approvals, 10000 window events per session and 8 MiB of state. A higher
92
+ configured rate still caps at 10000 events. Reaching a bound refuses work;
93
+ it does not silently discard counters. Scanning existing quarantine is
94
+ proportional to its entries, with no guaranteed wall-clock completion time.
95
+
96
+ Relocations, including Git clean compensation and force-restore occupant
97
+ preservation, check capacity. Regenerable direct deletion also checks session,
98
+ rate, repeat and batch limits. Covered automatic native-hook paths charge
99
+ admission before returning control to the host; they cannot prove the host
100
+ subsequently performed the delete.
101
+ Normal restore, explicit transaction GC and existing unprotected quarantine
102
+ payload housekeeping remain available without a new session/rate/batch debit.
103
+ Configuration and control-file protection still applies to housekeeping.
104
+ No limit triggers automatic GC or a fallback to permanent
105
+ deletion. Already completed earlier operations remain completed after a later
106
+ refusal; inspect reported transaction IDs.
107
+
108
+ Large deletions on the automated rm, Git-clean and artifact paths through
109
+ `check --enforce` or `safe_delete` return
110
+ `BLOCK_DELETE_BATCH_CONFIRM`, directing the operator to
111
+ [Cleanup Copilot](cleanup-plan.md#confirm-and-execute), rather than host `ASK`.
112
+ The enforced shell checker combines deletion targets across the request,
113
+ including enumerated Git clean targets, before its first compensation.
114
+ After terminal confirmation and a fresh plan check, Cleanup creates an approval
115
+ valid for ten minutes. It binds the session, configuration, exact paths and
116
+ measured metadata. Each selected path is consumed once before its operation;
117
+ failure does not restore approval. Changed, expired or replayed approvals are
118
+ refused. Approval lifts only the batch-confirmation gate: protection, budgets,
119
+ rate and capacity still apply.
120
+
121
+ Existing compound-command `ASK` paths return to host authorization before
122
+ automatic compensation and do not consume this admission budget. Existing
123
+ Git reset/restore/checkout snapshots also use their separate Git storage,
124
+ outside this quarantine budget. This change adds no new coverage or bound
125
+ for those paths; Git snapshot storage can still grow.
126
+
127
+ ## Status and operator recovery
128
+
129
+ Inspect effective limits and current-session counters with `status.py --json`.
130
+ The [policy reference](../../skills/delete-guard/references/policy.md#unreleased-execution-admission)
131
+ defines the new machine-readable refusal codes.
132
+ After investigating a stopped loop, an operator may run:
133
+
134
+ ```sh
135
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --reset-delete-budget
136
+ ```
137
+
138
+ This requires an interactive terminal and typing `RESET`. It clears only the
139
+ current bucket's counters, short-window events and outstanding approvals.
140
+ It does not purge recovery copies, reset quarantine capacity or alter limits.
141
+ An agent must leave this confirmation to the operator. Corrupt state is a
142
+ diagnostic failure, not an instruction to delete or silently reinitialize it.
143
+
144
+ These checks suppress accidents on covered paths; they are not an OS disk
145
+ quota or authenticated human authority. Same-UID processes can change local
146
+ configuration/state, change session identity or allocate a terminal. Audit,
147
+ manifest and new directory metadata, concurrent unrelated writers and writes
148
+ outside guarded paths can still grow storage. Existing 30-day/5-GiB GC
149
+ eligibility remains a separate soft planning rule. Review its explicit plan
150
+ using the [storage and GC guide](recovery-feedback.md).
@@ -10,17 +10,23 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), and the
14
- prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
13
+ This guide covers [0.2.7](../releases/release-notes-0.2.7.md), with Cleanup
14
+ plans, deletion admission limits and optional local MCP tools. Confirm the
15
+ exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
16
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
17
+ are available before installing from the registry. A checkout or manifest
18
+ does not establish publication or the current npm `latest` channel.
19
+
20
+ The earlier published [0.2.6](../releases/release-notes-0.2.6.md) includes Kimi
21
+ recovery feedback, diagnostics and reviewed DSH alpha.4/Kimi 2.3.0 Bash compatibility.
22
+ The prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
15
23
  The optional [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
16
24
  backports quarantine protection onto the stable line.
17
- Version 0.2.5 combines RC1–RC3 and clearer status, command and storage feedback.
18
- Its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
19
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
20
- establish package availability. Use a user-selected stable prefix:
25
+
26
+ Once the exact version is available, use a user-selected stable prefix:
21
27
 
22
28
  ```sh
23
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
29
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
24
30
  ```
25
31
 
26
32
  The package root is
@@ -32,11 +38,11 @@ identify the published package. For the stable-line fix alone, select
32
38
  `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`. These opt-in channels do not move
33
39
  stable `latest`.
34
40
 
35
- For a reviewed local checkout or explicitly selected local tarball, use a
36
- separate prefix:
41
+ If that version is unavailable, use a reviewed source checkout or a checked
42
+ local tarball. Install the tarball into a separate prefix:
37
43
 
38
44
  ```sh
39
- npm install --offline --ignore-scripts --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.5.tgz
45
+ npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.7.tgz
40
46
  ```
41
47
 
42
48
  The review package root is
@@ -45,31 +51,78 @@ Keep the selected package/checkout path consistent when configuring the host.
45
51
  Do not infer publication from a manifest/main commit or use an unscoped
46
52
  same-name package. A checkout's default branch can differ from a tagged stable release.
47
53
 
54
+ The [0.2.7 changes](../releases/release-notes-0.2.7.md#upgrade-and-operator-notes)
55
+ add execution-time limits that can refuse previously successful deletions.
56
+ Review the [default budgets and operator recovery](deletion-limits.md) before
57
+ upgrading; normal restore remains available without a new deletion debit.
58
+
59
+ The [0.2.6 additions](../releases/release-notes-0.2.6.md) require an upgraded package
60
+ or a checkout containing the corresponding files. In particular, 0.2.5 lacks
61
+ `adapters/kimi-code/stop_feedback.py`. Check the selected root before configuring
62
+ the optional Stop hook. Installing a new copy does not update another existing
63
+ installation or its host configuration.
64
+
65
+ Version 0.2.6 adds DSH `0.2.1-alpha.4` for the default deletion adapter.
66
+ Version 0.2.5 retains its earlier host declaration. Optional native read and Lab keep
67
+ their separate two-version scope. Check [DSH compatibility](../design/dsh-compatibility.md)
68
+ before enabling a profile.
69
+
70
+ The 0.2.6 Kimi Bash profile also adds exact version `2.3.0`, based on
71
+ [prompt CLI and ACP trials](../reports/test-report-kimi-code-block.md#kimi-230-acceptance).
72
+ Published 0.2.5 retains its earlier list. The Kimi Lab capture helper remains
73
+ pinned to 2.1.1; updating the Bash profile does not update that separate path.
74
+
48
75
  Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
49
76
  examples/bridges require a POSIX shell. The optional pinned DSH read path uses
50
77
  Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
51
78
  establish Windows-native hook bridge or full-suite portability.
79
+ The optional [MCP adapter](mcp.md) requires Python 3.10+ and its separately
80
+ installed pinned SDK; npm does not install it. MCP exposes explicit tools
81
+ and does not intercept operations that bypass them.
52
82
 
53
83
  ## Set up a coding agent
54
84
 
55
- Replace the root path in this prompt, and give it to your agent:
85
+ Replace the root path below with your installation path, then give the prompt
86
+ to your host's official coding agent. The
87
+ [integration guide](../../adapters/INTEGRATION.md) covers the hook requirements
88
+ and checks it should follow for the installed version.
89
+
90
+ We currently focus on DSH and Kimi Code. The Claude Code adapter remains a
91
+ reference; testing new Claude versions is paused. Other hosts are configured
92
+ locally by their official agents.
56
93
 
57
94
  ```text
58
95
  Set up Agent Guard for this workspace using /absolute/path/to/agent-guard.
96
+ Before changing anything, read adapters/INTEGRATION.md in full, including
97
+ its verification and evidence requirements. Do this even if an adapter exists.
98
+ Read this host's current official hook documentation and inspect its installed version.
59
99
  Identify the actual host version, tool names and hook/skill capabilities.
60
100
  Read the README, Skill contracts and matching adapter guide; check Python/Git.
61
101
  Use the selected checkout/package version and preserve existing settings.
102
+ For a host outside the DSH/Kimi maintenance focus, keep any new bridge and
103
+ configuration local; reuse the shared Core and versioned references.
104
+ Check which verification files that root includes. The npm package omits
105
+ tests/; use its local doctor/probes and report source unit tests as NOT_INCLUDED.
62
106
  Respect already-approved paths and configuration scope. Ask only for missing
63
107
  information or changes beyond that scope, including new dependencies.
64
108
  Install/reference the relevant Skills. Configure a native hook only where a
65
109
  blocking event is supported; otherwise report Skill/CLI-only operation.
110
+ Reuse the shared Core and its decisions; do not copy or relax its policy.
111
+ Check required project/hook trust through the host's normal review flow
112
+ within the authorized scope. Report activation as pending until it is complete.
113
+ Keep the user's selected account/provider; report model checks that cannot run.
66
114
  Claude: adapters/claude/README.md. Kimi: adapters/kimi-code/README.md.
67
115
  DSH: adapters/dsh/README.md. Other hosts: adapters/INTEGRATION.md.
68
116
  Verify a harmless call. Submit BLOCK-shaped commands only as data to check.py;
69
117
  never execute deletion of real data as a test. For Claude/Kimi, run the local
70
118
  doctor, but do not treat PASS as proof of actual host interception.
119
+ Finish configuration and local probes with a clear handoff before fresh-host
120
+ verification. Report startup/reload requirements and preserve a checkpoint if
121
+ the step budget ends. UNVERIFIED host-interception/model-delivery fields are
122
+ expected local-doctor results; repeating the same probes will not clear them.
71
123
  Report the host/version, installed paths, configuration scope, covered tools,
72
124
  observed interception and unverified paths separately.
125
+ Use the handoff format in section 4 of adapters/INTEGRATION.md.
73
126
  guard-lab is the user's controller, not a Skill to install into the tested
74
127
  agent. Run real-host/model experiments only in an explicitly selected scope.
75
128
  ```
@@ -104,6 +157,14 @@ its result covers one sampled root-agent Bash call. See
104
157
  [host drift](host-drift.md) and the
105
158
  [capability matrix](harness-capabilities.md).
106
159
 
160
+ For Kimi's optional Stop feedback, choose whether the extra response is
161
+ wanted, follow the [separate setup](../../adapters/kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition),
162
+ and start a new session. In 0.2.6, the doctor reports Stop
163
+ configuration and local execution separately under `feedback`. An absent Stop
164
+ is optional; a configured but invalid or failing Stop exits 1. `--probe` uses
165
+ synthetic records in temporary storage. `feedback.model_delivery` remains
166
+ `UNVERIFIED`; local PASS does not establish model receipt.
167
+
107
168
  ## Try the three paths
108
169
 
109
170
  - **Recovery:** use the [delete Skill](../../skills/delete-guard/SKILL.md).
@@ -1,13 +1,19 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
- Stable release line: [0.2.5](../releases/release-notes-0.2.5.md).
4
- It retains RC1–RC3 and adds clearer startup, command and storage
5
- feedback. Published prerelease, checked on 2026-10-19:
3
+ This matrix accompanies [0.2.7](../releases/release-notes-0.2.7.md).
4
+ Confirm availability through the exact GitHub release and npm version links
5
+ in those notes; a source version does not establish publication.
6
+ Published prerelease, checked on 2026-10-19:
6
7
  [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
7
8
  Rows below retain their tested source/host versions and do not automatically
8
9
  certify a later release. Local regression or package checks are separate from
9
10
  new native-host/model evidence.
10
11
 
12
+ Earlier release [0.2.6](../releases/release-notes-0.2.6.md) adds optional Kimi Stop
13
+ feedback, separate doctor checks, DSH Lab diagnostics, alpha.4 default
14
+ deletion compatibility and Kimi 2.3.0 root-Bash compatibility. These additions
15
+ are absent from 0.2.5. See its [version notes](../releases/release-notes-0.2.6.md).
16
+
11
17
  The new [research notes](../research/README.md) describe bounded private
12
18
  experiments; their disclosure/delegation methods do not change the supported
13
19
  production coverage in this matrix.
@@ -18,6 +24,10 @@ host does **not** mean that host intercepts tool calls, and an adapter returning
18
24
  For an unlisted host, use the [self-adaptation guide](../../adapters/INTEGRATION.md)
19
25
  and keep its native-interception status `UNVERIFIED` until independently tested.
20
26
 
27
+ We currently focus on DSH and Kimi Code. Claude Code's adapter and past
28
+ results remain available; testing new Claude versions is paused. For other
29
+ hosts, ask the official agent to configure and test the integration locally.
30
+
21
31
  ## Evidence levels
22
32
 
23
33
  | Level | Meaning |
@@ -39,6 +49,12 @@ host-settings check; `local_probe: PASS` is not host interception. The doctor
39
49
  always reports `host_interception: UNVERIFIED`. Only a separate real-host
40
50
  trial with an independent non-execution check can establish the bounded
41
51
  "Enforcement observed" level above. Neither doctor mode starts a model.
52
+ In 0.2.6, a separate Kimi `feedback` object checks optional
53
+ Stop configuration and, with `--probe`, synthetic feedback in temporary
54
+ storage. Missing Stop is `NOT_CONFIGURED` and does not fail the doctor;
55
+ configured Stop failures exit 1. Unreadable configuration is `UNVERIFIED`.
56
+ `feedback.model_delivery` stays `UNVERIFIED`, including after a Bash live
57
+ sentinel. See the [Stop doctor fields](../../adapters/kimi-code/README.md#stop-doctor-checks-unreleased).
42
58
  The optional `--check-drift` mode additionally compares the installed host
43
59
  version with a shipped compatibility profile and computes privacy-safe
44
60
  configuration/runtime fingerprints. Its `CURRENT` status is static preflight
@@ -58,7 +74,10 @@ bounded "Enforcement observed" evidence only for that root-agent Bash call.
58
74
  | DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](../reports/test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](../reports/test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
59
75
  | DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](../reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](../reports/test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
60
76
  | DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS; sampled PTC SDK Bash calls | Native ASK; Core read ASK/BLOCK withheld | [0.2.3 native review](../reports/test-report-release-readiness-0.2.3.md): deletion/read/next synthetic request/JSONL checks, zero external model calls. [0.2.4 official Flash PTC](../reports/test-report-dsh-0.2.4-ptc.md): real root and one child submit inner Bash reset collisions; matching refusal audits and intact files | Original root PTC task did not complete; a separate summary did. Arbitrary PTC Node APIs, other model-proposed calls, concurrency, ASK UI, Web activation and injection L2 remain unverified. Historical pending captures remain inconclusive. |
61
- | Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](../reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and a second configured model route; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | Client records identify the requested route, not the remote model weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
77
+ | DSH 0.2.1-alpha.4 / Node 22 (Agent Guard 0.2.6) | Default deletion adapter; three recovery tools and prompt guidance | Native approval service; sampled rejection and fixed answerer grant | [Native CLI report](../reports/test-report-dsh-alpha4.md): actual Profile/Boot, Bash allow/block, quarantine/restore, root/child BLOCK and ASK, per-session policy forwarding; no external model calls | No optional read or Lab admission. Interactive approval UI, OS sandbox confinement, arbitrary PTC, concurrent agents, GUI activation and real-model behavior are unverified. |
78
+ | Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK sampled on 0.42.0 | [Bounded report](../reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinels; older 0.42.0 root/subagent enforcement; later actual-CLI fixed-loopback fault cases on both versions | 2.1.1 subagents, concurrency and live ASK UI remain unverified. Missing/timed-out hooks allowed tools in the fault cases; other tools and arbitrary spawn failures remain uncovered. Client route labels do not identify remote model weights. |
79
+ | Kimi Code 2.3.0 (Agent Guard 0.2.6) | Root `Bash` PreToolUse in prompt CLI and ACP; ACP uses Kimi's local executor | Adapter hard-denies ASK | [Sixteen actual-host loopback trials](../reports/test-report-kimi-code-block.md#kimi-230-acceptance): allow/BLOCK/ASK, Python startup refusal, absence control, recovery; ACP process/payload cwd matched the session workspace despite a different service startup cwd | No external model calls. Subagents, other tools, client-provided terminals, concurrency, background execution and host-timeout behavior remain unverified. Hook absence allowed the inert marker. Web checks covered startup/status/shutdown only. |
80
+ | Kimi optional Stop, 0.42.0 / 2.1.1 / 2.3.0; Agent Guard 0.2.6 | Recovery guidance after the initial answer; separately configured POSIX hook | No additional approval path | [Feedback follow-up](../reports/test-report-kimi-code-block.md#recovery-feedback-follow-up-2026-10-20-unreleased-source): actual-CLI fixed-loopback delivery and one bounded 2.1.1 real-model session. [2.3.0 prompt/ACP follow-up](../reports/test-report-kimi-code-block.md#kimi-230-acceptance): actual txids, storage/GC guidance and byte-exact recovery with fixed responses | Adds a response after new compensation records. The initial answer may be inaccurate; emission is not acknowledgement. Shared-session actors, exhausted budgets and broader model/scheduling behavior retain their limits. |
62
81
  | Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](../reports/test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
63
82
  | ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](../reports/test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
64
83
  | Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
@@ -68,6 +87,20 @@ a CLI/cooperative path and the narrowly scoped, opt-in DSH text-read prototype
68
87
  above. This table does not imply universal interception of model context,
69
88
  uploads, or every output channel.
70
89
 
90
+ ## Local MCP tools introduced in 0.2.7
91
+
92
+ The optional [local stdio MCP adapter](mcp.md) provides explicit safe_delete,
93
+ ordinary restore, transaction/status queries and GC preview under one
94
+ startup-bound workspace/session. It does not intercept shell, script or
95
+ editor operations that bypass those tools. Its Python 3.10+ SDK environment
96
+ is separate from the standard-library Core/CLI requirements.
97
+
98
+ The guide records the 0.2.7 installed-package/protocol checks and the earlier
99
+ bounded Kimi Code 2.3.0 root-agent native-MCP trials with their original
100
+ checkpoint and gateway limits. These observations do not expand the native
101
+ hook rows above or establish live Claude/Cursor/Codex, subagent or additional
102
+ platform coverage. Client setup examples remain documentation guidance.
103
+
71
104
  ## Acceptance for each native adapter
72
105
 
73
106
  1. Pin host version, profile/configuration, tool name, shell dialect, and