@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.
- package/README.md +45 -20
- package/README.zh-CN.md +39 -19
- package/adapters/INTEGRATION.md +6 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/doctor.py +325 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +35 -14
- package/docs/design/architecture.md +42 -16
- package/docs/design/compatibility.md +246 -7
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +26 -12
- package/docs/guides/harness-capabilities.md +29 -4
- package/docs/guides/mcp.md +420 -0
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/release-notes-0.2.8.md +172 -0
- package/docs/releases/unreleased.md +182 -5
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +1 -1
- package/doctor.py +25 -1
- package/live_sentinel.py +1 -1
- package/package.json +3 -1
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- 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,18 +10,24 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
|
|
|
10
10
|
|
|
11
11
|
## Select the package root
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
13
|
+
This guide covers [0.2.8](../releases/release-notes-0.2.8.md), with MCP
|
|
14
|
+
connection diagnosis and recovery validation, plus the Cleanup plans,
|
|
15
|
+
deletion admission limits and optional tools introduced in 0.2.7. Confirm the
|
|
16
|
+
exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
|
|
17
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
|
|
18
|
+
are available before installing from the registry. A checkout or manifest
|
|
19
|
+
does not establish publication or the current npm `latest` channel.
|
|
20
|
+
|
|
21
|
+
The earlier published [0.2.6](../releases/release-notes-0.2.6.md) includes Kimi
|
|
22
|
+
recovery feedback, diagnostics and reviewed DSH alpha.4/Kimi 2.3.0 Bash compatibility.
|
|
23
|
+
The prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
|
|
15
24
|
The optional [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
16
25
|
backports quarantine protection onto the stable line.
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
Its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)
|
|
20
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6)
|
|
21
|
-
establish package availability. Use a user-selected stable prefix:
|
|
26
|
+
|
|
27
|
+
Once the exact version is available, use a user-selected stable prefix:
|
|
22
28
|
|
|
23
29
|
```sh
|
|
24
|
-
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.
|
|
30
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
|
|
25
31
|
```
|
|
26
32
|
|
|
27
33
|
The package root is
|
|
@@ -33,11 +39,11 @@ identify the published package. For the stable-line fix alone, select
|
|
|
33
39
|
`@mokuyoaxis/agent-guard@0.2.4-hotfix.1`. These opt-in channels do not move
|
|
34
40
|
stable `latest`.
|
|
35
41
|
|
|
36
|
-
|
|
37
|
-
separate prefix:
|
|
42
|
+
If that version is unavailable, use a reviewed source checkout or a checked
|
|
43
|
+
local tarball. Install the tarball into a separate prefix:
|
|
38
44
|
|
|
39
45
|
```sh
|
|
40
|
-
npm install --offline --ignore-scripts --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.
|
|
46
|
+
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.8.tgz
|
|
41
47
|
```
|
|
42
48
|
|
|
43
49
|
The review package root is
|
|
@@ -46,7 +52,12 @@ Keep the selected package/checkout path consistent when configuring the host.
|
|
|
46
52
|
Do not infer publication from a manifest/main commit or use an unscoped
|
|
47
53
|
same-name package. A checkout's default branch can differ from a tagged stable release.
|
|
48
54
|
|
|
49
|
-
The [0.2.
|
|
55
|
+
The [0.2.7 changes](../releases/release-notes-0.2.7.md#upgrade-and-operator-notes)
|
|
56
|
+
add execution-time limits that can refuse previously successful deletions.
|
|
57
|
+
Review the [default budgets and operator recovery](deletion-limits.md) before
|
|
58
|
+
upgrading; normal restore remains available without a new deletion debit.
|
|
59
|
+
|
|
60
|
+
The [0.2.6 additions](../releases/release-notes-0.2.6.md) require an upgraded package
|
|
50
61
|
or a checkout containing the corresponding files. In particular, 0.2.5 lacks
|
|
51
62
|
`adapters/kimi-code/stop_feedback.py`. Check the selected root before configuring
|
|
52
63
|
the optional Stop hook. Installing a new copy does not update another existing
|
|
@@ -66,6 +77,9 @@ Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
|
|
|
66
77
|
examples/bridges require a POSIX shell. The optional pinned DSH read path uses
|
|
67
78
|
Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
|
|
68
79
|
establish Windows-native hook bridge or full-suite portability.
|
|
80
|
+
The optional [MCP adapter](mcp.md) requires Python 3.10+ and its separately
|
|
81
|
+
installed pinned SDK; npm does not install it. MCP exposes explicit tools
|
|
82
|
+
and does not intercept operations that bypass them.
|
|
69
83
|
|
|
70
84
|
## Set up a coding agent
|
|
71
85
|
|
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
# Harness capability and evidence matrix
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
This matrix accompanies [0.2.8](../releases/release-notes-0.2.8.md).
|
|
4
|
+
Confirm availability through the exact GitHub release and npm version links
|
|
5
|
+
in those notes; a source version does not establish publication.
|
|
5
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
|
|
|
11
|
-
[0.2.6](../releases/release-notes-0.2.6.md) adds optional Kimi Stop
|
|
12
|
+
Earlier release [0.2.6](../releases/release-notes-0.2.6.md) adds optional Kimi Stop
|
|
12
13
|
feedback, separate doctor checks, DSH Lab diagnostics, alpha.4 default
|
|
13
14
|
deletion compatibility and Kimi 2.3.0 root-Bash compatibility. These additions
|
|
14
|
-
are absent from 0.2.5. See [
|
|
15
|
+
are absent from 0.2.5. See its [version notes](../releases/release-notes-0.2.6.md).
|
|
15
16
|
|
|
16
17
|
The new [research notes](../research/README.md) describe bounded private
|
|
17
18
|
experiments; their disclosure/delegation methods do not change the supported
|
|
@@ -86,6 +87,30 @@ a CLI/cooperative path and the narrowly scoped, opt-in DSH text-read prototype
|
|
|
86
87
|
above. This table does not imply universal interception of model context,
|
|
87
88
|
uploads, or every output channel.
|
|
88
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. A separate
|
|
101
|
+
[Codex 0.165.0 acceptance](mcp.md#codex-01650-with-published-027) used published
|
|
102
|
+
0.2.7: three actual-client groups and three real-model tasks, with 16 model MCP
|
|
103
|
+
calls. Its recorded results and incomplete native-client exit metadata retain
|
|
104
|
+
their stated limits. These cooperative MCP observations do not expand the
|
|
105
|
+
native-hook rows above or establish live Claude/Cursor, arbitrary subagent,
|
|
106
|
+
other-version or additional-platform coverage. Untested client setup examples
|
|
107
|
+
remain documentation guidance.
|
|
108
|
+
|
|
109
|
+
The [MCP doctor introduced in 0.2.8](mcp.md#diagnose-a-local-service-028)
|
|
110
|
+
checks a selected service through handshake and read-only calls. Its PASS
|
|
111
|
+
does not establish host connection, model use or native interception; those
|
|
112
|
+
remain separate evidence levels.
|
|
113
|
+
|
|
89
114
|
## Acceptance for each native adapter
|
|
90
115
|
|
|
91
116
|
1. Pin host version, profile/configuration, tool name, shell dialect, and
|