@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.
- package/README.md +61 -23
- package/README.zh-CN.md +51 -22
- package/adapters/INTEGRATION.md +90 -10
- package/adapters/claude/README.md +6 -0
- package/adapters/dsh/README.md +19 -8
- package/adapters/dsh/compatibility.json +14 -0
- package/adapters/dsh/harness/README.md +11 -0
- package/adapters/dsh/harness/guard_lab.py +42 -14
- package/adapters/kimi-code/README.md +154 -14
- package/adapters/kimi-code/compatibility.json +1 -1
- package/adapters/kimi-code/config.example.toml +18 -6
- package/adapters/kimi-code/hook_bridge.sh +19 -4
- package/adapters/kimi-code/pre_tool_use.py +1 -1
- package/adapters/kimi-code/stop_feedback.py +237 -0
- package/adapters/mcp/__init__.py +1 -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 +25 -7
- package/docs/design/architecture.md +16 -4
- package/docs/design/compatibility.md +230 -6
- package/docs/design/dsh-compatibility.md +65 -0
- 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 +72 -11
- package/docs/guides/harness-capabilities.md +37 -4
- package/docs/guides/host-drift.md +32 -0
- package/docs/guides/mcp.md +293 -0
- package/docs/guides/recovery-feedback.md +29 -1
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.6.md +167 -0
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/unreleased.md +275 -0
- package/docs/reports/test-report-dsh-alpha4.md +102 -0
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +120 -7
- package/doctor.py +175 -28
- package/package.json +13 -2
- 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
|
@@ -18,6 +18,17 @@ that reliability problem; it is not a sandbox or a live-interception proof.
|
|
|
18
18
|
3. It fingerprints the local enforcement path (profile, bridge, adapter,
|
|
19
19
|
shared guard entry point, and Core Python files).
|
|
20
20
|
|
|
21
|
+
In [0.2.6](../releases/release-notes-0.2.6.md), a
|
|
22
|
+
configured optional Kimi Stop adds its normalized
|
|
23
|
+
fields to the configuration fingerprint and `stop_feedback.py` to the runtime
|
|
24
|
+
fingerprint. Adding, removing or changing it can therefore yield `DRIFTED`
|
|
25
|
+
against an earlier baseline. Without agent-guard Stop, the original
|
|
26
|
+
PreToolUse fingerprint remains unchanged. Unrelated Stop commands are ignored.
|
|
27
|
+
|
|
28
|
+
The runtime fingerprint includes `package.json`, so a package version change
|
|
29
|
+
also changes the fingerprint. Compare with the old baseline first; after an
|
|
30
|
+
intentional update, review the change and use a new baseline path.
|
|
31
|
+
|
|
21
32
|
This does not start a model or edit host configuration. The ordinary doctor
|
|
22
33
|
does not execute the host at all; host version discovery is opt-in through
|
|
23
34
|
`--check-drift`, `--baseline`, `--write-baseline`, or `--host-executable`.
|
|
@@ -31,6 +42,10 @@ python3 doctor.py kimi --probe --check-drift --json
|
|
|
31
42
|
when a host is installed under a wrapper name. The selected executable is run
|
|
32
43
|
only with the compatibility profile's version arguments.
|
|
33
44
|
|
|
45
|
+
Automatic discovery uses the doctor's current PATH. An interactive shell or
|
|
46
|
+
wrapper can select another installation. Check the user's actual launcher
|
|
47
|
+
and use `--host-executable` for the intended binary when those paths differ.
|
|
48
|
+
|
|
34
49
|
## Status vocabulary
|
|
35
50
|
|
|
36
51
|
| Status | Meaning |
|
|
@@ -48,6 +63,12 @@ it suitable for a local preflight. `CURRENT` is deliberately weaker than
|
|
|
48
63
|
version command, and local adapter process cannot prove that a live host
|
|
49
64
|
loaded or enforced the hook.
|
|
50
65
|
|
|
66
|
+
A configured Kimi Stop that fails configuration or a requested local probe
|
|
67
|
+
also makes drift `BROKEN`. Absent optional Stop is not a failure. Baseline
|
|
68
|
+
creation requires those requested Stop probes to pass as well; it does not
|
|
69
|
+
certify delivery. The separate `feedback.model_delivery` remains `UNVERIFIED`
|
|
70
|
+
even if the root-agent Bash live sentinel below passes.
|
|
71
|
+
|
|
51
72
|
## Privacy-minimal baselines
|
|
52
73
|
|
|
53
74
|
A baseline is optional. Create one only after reviewing a passing installation:
|
|
@@ -78,6 +99,17 @@ same OS privileges.
|
|
|
78
99
|
Profiles live beside their adapters as `compatibility.json`. They describe
|
|
79
100
|
only the host-facing version command and the narrow contract already covered
|
|
80
101
|
by that adapter. Core policy remains shared and is not copied into profiles.
|
|
102
|
+
|
|
103
|
+
The 0.2.6 Kimi profile lists exact versions `0.42.0`, `2.1.1` and
|
|
104
|
+
`2.3.0`. The [2.3.0 prompt/ACP root-Bash evidence](../reports/test-report-kimi-code-block.md#kimi-230-acceptance)
|
|
105
|
+
does not extend the separately pinned Lab helper, subagent coverage or real-model
|
|
106
|
+
claims. A valid 2.3.0 setup can now be `CURRENT` without a baseline; live
|
|
107
|
+
interception and feedback delivery still retain their independent status.
|
|
108
|
+
Updating the profile changes its runtime fingerprint, so an old baseline can
|
|
109
|
+
report `DRIFTED`. Review that change before selecting a new private baseline;
|
|
110
|
+
the update does not overwrite an existing one. Published 0.2.5 retains its
|
|
111
|
+
earlier list, and unlisted versions remain `STALE`.
|
|
112
|
+
|
|
81
113
|
Adding a profile for an unlisted host does not make it supported: the host
|
|
82
114
|
still needs a blocking pre-tool event and the bounded acceptance evidence in
|
|
83
115
|
the [capability matrix](harness-capabilities.md).
|
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
# Local MCP tools / 本地 MCP 工具
|
|
2
|
+
|
|
3
|
+
This adapter is introduced in **0.2.7** and is absent from 0.2.6. The separate
|
|
4
|
+
0.3.0 plan remains paused. The historical
|
|
5
|
+
protocol/package records and three real Kimi Code trials below belong to the earlier
|
|
6
|
+
2026-10-28 source checkpoint with 0.2.6 package metadata, including a failed
|
|
7
|
+
first full run. They do not certify the new versioned artifact. See the
|
|
8
|
+
[0.2.7 notes](../releases/release-notes-0.2.7.md) for versioned validation and
|
|
9
|
+
exact-version availability checks.
|
|
10
|
+
Configuration examples are not host acceptance.
|
|
11
|
+
|
|
12
|
+
MCP gives a supporting coding-agent client an explicit way to use the existing
|
|
13
|
+
safe deletion and recovery operations. It does **not** intercept shell `rm`,
|
|
14
|
+
scripts, editor deletion or tools that bypass this server. Keep a compatible
|
|
15
|
+
blocking hook for the paths where automatic interception is required.
|
|
16
|
+
|
|
17
|
+
## Install the optional adapter
|
|
18
|
+
|
|
19
|
+
The Core/CLI still needs Python 3.9+ and Git without third-party Python
|
|
20
|
+
packages. This adapter separately uses the official MIT-licensed Python
|
|
21
|
+
`mcp==2.3.0` SDK. Its release metadata requires Python 3.10+; use a compatible
|
|
22
|
+
interpreter in a dedicated virtual environment. The SDK and its dependencies
|
|
23
|
+
are optional and are not installed by the existing Core/CLI or by npm.
|
|
24
|
+
|
|
25
|
+
From a checkout or package containing `adapters/mcp/`:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
python3 -m venv /absolute/path/to/agent-guard-mcp-venv
|
|
29
|
+
/absolute/path/to/agent-guard-mcp-venv/bin/python -m pip install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
If the existing Python lacks `ensurepip`, and an existing pip supports
|
|
33
|
+
`--python` (pip 22.3+), it can provision the separate environment instead:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
python3 -m venv --without-pip /absolute/path/to/agent-guard-mcp-venv
|
|
37
|
+
python3 -m pip --python /absolute/path/to/agent-guard-mcp-venv/bin/python install -r /absolute/path/to/agent-guard/adapters/mcp/requirements.txt
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The adapter accepts the pinned SDK 2.3.0; other SDK versions are rejected
|
|
41
|
+
until separately validated. Transitive dependency versions are resolved by
|
|
42
|
+
pip; this SDK pin is not a complete cross-platform dependency lock.
|
|
43
|
+
|
|
44
|
+
Use a user-owned path on the Linux filesystem. These POSIX examples do not
|
|
45
|
+
establish Windows, macOS or Android shared-storage compatibility. The SDK
|
|
46
|
+
wheel is platform-independent, but some transitive dependencies contain
|
|
47
|
+
native code; the selected environment must successfully install them.
|
|
48
|
+
Do not replace a working global Python environment to enable this adapter.
|
|
49
|
+
|
|
50
|
+
The local launch command is:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
/absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The client starts this stdio process. No network listener, cloud account or
|
|
57
|
+
system service is required. Use absolute paths and bind one workspace at
|
|
58
|
+
startup; a tool call cannot change it or select another quarantine. Protocol
|
|
59
|
+
messages use stdout; diagnostics use stderr.
|
|
60
|
+
This adapter binds the workspace-local `.agent-trash/`; it does not adopt an
|
|
61
|
+
ambient custom quarantine or deletion-policy environment override.
|
|
62
|
+
|
|
63
|
+
An optional trusted startup `--session stable-name` selects both the existing
|
|
64
|
+
CLI authorization mode and persistent deletion-budget identity. Without it,
|
|
65
|
+
the adapter uses the legacy CLI state and stable shared default budget bucket.
|
|
66
|
+
To share saved CLI state, the workspace, quarantine location and session
|
|
67
|
+
selection must match. Do not generate a new identity for each call or
|
|
68
|
+
reconnect: it can select different authorization state as well as a different
|
|
69
|
+
budget. Session identity is trusted configuration, not a model-supplied tool
|
|
70
|
+
argument or an independent authentication boundary.
|
|
71
|
+
|
|
72
|
+
This server does not automatically inherit the calling host's native-session
|
|
73
|
+
restrictions or in-memory veto. A host that keeps authoritative restrictions
|
|
74
|
+
in memory needs a trusted bridge to enforce them for MCP calls; registering
|
|
75
|
+
this server alone does not provide that bridge. Existing
|
|
76
|
+
[limits](deletion-limits.md) and the CLI's mode semantics still apply.
|
|
77
|
+
|
|
78
|
+
## Tools and limits
|
|
79
|
+
|
|
80
|
+
| Tool | Inputs | Effect |
|
|
81
|
+
|---|---|---|
|
|
82
|
+
| `safe_delete` | `paths` (1–1000 literal strings), optional `dry_run` (default false) | Delegate to safe_delete with the existing policy, budget, audit and recovery rules |
|
|
83
|
+
| `restore` | `txid` | Restore a transaction without force-overwriting an occupant |
|
|
84
|
+
| `transactions` | none | List the selected workspace's recovery transactions |
|
|
85
|
+
| `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
|
|
86
|
+
| `gc_plan` | none | Preview the existing transaction GC plan; never execute it |
|
|
87
|
+
|
|
88
|
+
Paths are literal names, relative to the fixed workspace or absolute; the
|
|
89
|
+
Core still refuses outside targets. Glob characters name actual files rather
|
|
90
|
+
than selecting a pattern; the existing Core may still refuse such names as
|
|
91
|
+
wildcards or indeterminable effects. Literal transport does not relax those
|
|
92
|
+
rules. No shell parses these arguments. Unknown tool
|
|
93
|
+
arguments and incorrect types are refused, including boolean values for
|
|
94
|
+
integer fields.
|
|
95
|
+
Paths that normalize to a name ending in whitespace are refused, because
|
|
96
|
+
the underlying classifier trims that spelling. Existing Core restrictions
|
|
97
|
+
on glob/variable-like filenames still apply; literal passing prevents
|
|
98
|
+
selecting neighboring names but does not relax those refusals.
|
|
99
|
+
|
|
100
|
+
Results carry `tool`, `ok`, `exit_code` and the existing CLI JSON in `result`;
|
|
101
|
+
MCP errors are marked as errors as well. Adapter failures use an `error`
|
|
102
|
+
object with `code`, `message`, `may_have_changed` and inspection-tool guidance.
|
|
103
|
+
Raw non-JSON subprocess stderr is not returned as tool content.
|
|
104
|
+
|
|
105
|
+
Ordinary valuable deletion retains a recovery copy and disk usage; only
|
|
106
|
+
provably regenerable artifacts follow the existing physical-delete rules.
|
|
107
|
+
Dry run is advisory: it preserves source targets and does not debit deletion
|
|
108
|
+
budget, but may initialize normal guard/audit metadata. It is not a zero-write
|
|
109
|
+
scan or an execution grant.
|
|
110
|
+
Tool responses can include workspace paths and recovery metadata; review them
|
|
111
|
+
before sharing logs. MCP does not add file-content disclosure sanitization.
|
|
112
|
+
|
|
113
|
+
The tool schema supplies no workspace/session/environment override, arbitrary
|
|
114
|
+
shell command, force restore, Cleanup approval, budget reset or GC execute
|
|
115
|
+
argument. The MCP safe-delete entry also refuses quarantine targets, so it
|
|
116
|
+
cannot be used as an alternate permanent-GC interface. `gc_plan` is a preview
|
|
117
|
+
restriction of this adapter, not a new claim that the existing GC CLI requires
|
|
118
|
+
a terminal or human confirmation.
|
|
119
|
+
|
|
120
|
+
Large batches remain refused with Cleanup guidance; use the existing
|
|
121
|
+
[reviewed terminal workflow](cleanup-plan.md#confirm-and-execute) when
|
|
122
|
+
authorized. A model-provided `confirm=true`, client tool annotation or
|
|
123
|
+
permissive auto-approval setting does not replace that workflow. Restore
|
|
124
|
+
conflicts require operator review. Changing policy, force restoration,
|
|
125
|
+
executing GC or resetting a budget remains outside this server's tool set.
|
|
126
|
+
|
|
127
|
+
A tool call can fail after a partial mutation. Inspect its structured result,
|
|
128
|
+
reported transaction IDs and `transactions`/`status`; do not assume failure or
|
|
129
|
+
cancellation means nothing moved. Do not automatically retry a mutating call
|
|
130
|
+
after a client timeout or disconnection. The existing recovery, concurrency
|
|
131
|
+
and same-UID boundaries remain; this server is not an OS sandbox.
|
|
132
|
+
|
|
133
|
+
## Configure a client
|
|
134
|
+
|
|
135
|
+
The following examples register a local server; they do not run deletion or
|
|
136
|
+
change existing hooks. Merge the entry into the appropriate configuration
|
|
137
|
+
instead of overwriting other servers. Confirm trust and tool permissions in
|
|
138
|
+
the actual client, then start a fresh connection and inspect discovered tools.
|
|
139
|
+
|
|
140
|
+
### Claude Code
|
|
141
|
+
|
|
142
|
+
From the intended project, register a project-scoped stdio server:
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
claude mcp add --transport stdio --scope project agent-guard -- /absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The command changes project MCP configuration; review it before use. Complete
|
|
149
|
+
Claude's normal trust review, then inspect `/mcp`. This setup is an explicit
|
|
150
|
+
MCP tool path and does not extend the separate Claude hook adapter's tested
|
|
151
|
+
versions. See the [official Claude Code MCP guide](https://code.claude.com/docs/en/mcp).
|
|
152
|
+
|
|
153
|
+
### Cursor
|
|
154
|
+
|
|
155
|
+
Merge into `.cursor/mcp.json` in the intended project:
|
|
156
|
+
|
|
157
|
+
```json
|
|
158
|
+
{
|
|
159
|
+
"mcpServers": {
|
|
160
|
+
"agent-guard": {
|
|
161
|
+
"type": "stdio",
|
|
162
|
+
"command": "/absolute/path/to/agent-guard-mcp-venv/bin/python",
|
|
163
|
+
"args": [
|
|
164
|
+
"-B",
|
|
165
|
+
"/absolute/path/to/agent-guard/adapters/mcp/server.py",
|
|
166
|
+
"--workspace",
|
|
167
|
+
"/absolute/path/to/your-project"
|
|
168
|
+
]
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Enable and inspect the server in the installed client's MCP settings. This
|
|
175
|
+
local configuration does not make your filesystem available to a remote
|
|
176
|
+
cloud agent. See the [official Cursor MCP guide](https://cursor.com/docs/mcp).
|
|
177
|
+
|
|
178
|
+
### Codex
|
|
179
|
+
|
|
180
|
+
Register the same command through the CLI:
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
codex mcp add agent-guard -- /absolute/path/to/agent-guard-mcp-venv/bin/python -B /absolute/path/to/agent-guard/adapters/mcp/server.py --workspace /absolute/path/to/your-project
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`codex mcp add` writes Codex configuration. For explicit project scoping in a
|
|
187
|
+
trusted project, merge this entry into `.codex/config.toml` instead:
|
|
188
|
+
|
|
189
|
+
```toml
|
|
190
|
+
[mcp_servers.agent-guard]
|
|
191
|
+
command = "/absolute/path/to/agent-guard-mcp-venv/bin/python"
|
|
192
|
+
args = ["-B", "/absolute/path/to/agent-guard/adapters/mcp/server.py", "--workspace", "/absolute/path/to/your-project"]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Use `codex mcp list` and `/mcp` in a fresh session to inspect configuration and
|
|
196
|
+
connection state. Configuration being present does not prove a model actually
|
|
197
|
+
called the tool or that all filesystem actions are covered. See the
|
|
198
|
+
[official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?site_variant=chatgpt).
|
|
199
|
+
|
|
200
|
+
These source-based examples were checked against official documentation on
|
|
201
|
+
2026-10-28. They are not claims that all three clients were exercised locally.
|
|
202
|
+
Client schemas, approvals and connection behavior can change; verify the
|
|
203
|
+
installed version rather than copying another client's configuration shape.
|
|
204
|
+
|
|
205
|
+
## Verify and report
|
|
206
|
+
|
|
207
|
+
1. Confirm the interpreter starts the server and the client discovers the five
|
|
208
|
+
tools. Check stderr when a dependency or executable cannot be found.
|
|
209
|
+
2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
|
|
210
|
+
preview leaves recovery payloads intact.
|
|
211
|
+
3. Create a small synthetic valuable file, call `safe_delete`, verify a real
|
|
212
|
+
restorable transaction, then `restore` and compare original bytes.
|
|
213
|
+
4. Independently check configured protection and budget refusals preserve
|
|
214
|
+
targets. Confirm forbidden override/force/GC-execute arguments are refused.
|
|
215
|
+
5. Report the client/version, platform, workspace binding, tool calls, actual
|
|
216
|
+
results and unverified paths. A raw protocol test, a real client call and a
|
|
217
|
+
real-model trial are different evidence levels.
|
|
218
|
+
|
|
219
|
+
## Recorded validation and remaining limits
|
|
220
|
+
|
|
221
|
+
The 219-file, versioned **0.2.7 preparation checkpoint** passed local validation on
|
|
222
|
+
2026-10-29: 1129 Python cases and both Node groups in 1194.265 seconds, with
|
|
223
|
+
no failures, errors, skips, timeouts or automatic retries. It used the existing
|
|
224
|
+
diagnostic collector with `npm test` scope and original deadlines rather than
|
|
225
|
+
invoking npm. Its 155-file offline installation passed 12 CLI entry-point and
|
|
226
|
+
actual installed MCP checks, including `serverInfo.version == 0.2.7`, normal
|
|
227
|
+
delete/restore, budget persistence across reconnect, protected/batch refusal
|
|
228
|
+
and read-only tools without workspace writes. Local SDK release-gate checks
|
|
229
|
+
also passed. This 2026-10-29 local checkpoint did not include final-commit
|
|
230
|
+
remote CI or publication; no new real-model trial was run during version
|
|
231
|
+
alignment. See the
|
|
232
|
+
[versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|
|
233
|
+
|
|
234
|
+
The earlier 217-file, 0.2.6-metadata frozen public candidate was tested locally on ARM64/PRoot
|
|
235
|
+
POSIX with Python 3.13.5 and the isolated MCP SDK 2.3.0 environment. Both full
|
|
236
|
+
runs retained the existing 1800-second total budget and per-test deadlines;
|
|
237
|
+
neither changed the runtime/tests or automatically retried a failing case.
|
|
238
|
+
|
|
239
|
+
| Full run | Python | Node groups | Total time | Result |
|
|
240
|
+
|---|---|---|---|---|
|
|
241
|
+
| First | 1123 cases, one error, no assertion failures or skips | Not started after Python failed | 1156.312 seconds | FAIL |
|
|
242
|
+
| Second | 1123 cases, no failures, errors or skips | Both passed | 1143.435 seconds | PASS |
|
|
243
|
+
|
|
244
|
+
The first run's existing DSH Lab case
|
|
245
|
+
`test_native_capture_corruption_is_refused_before_host_result` could not bring
|
|
246
|
+
its observer to READY within the existing five-second startup deadline.
|
|
247
|
+
One separate single-case check with the SDK interpreter and one with system
|
|
248
|
+
Python passed in 4.409 and 2.979 seconds. The cause remains undetermined; these
|
|
249
|
+
checks and the successful second full run do not rewrite the first failure.
|
|
250
|
+
The second run completed without a timeout. Both runs used the existing
|
|
251
|
+
diagnostic unittest result collector with the same scope as `npm test`, then
|
|
252
|
+
the Node commands when Python passed; the npm command itself was not invoked.
|
|
253
|
+
|
|
254
|
+
Without the optional SDK or an explicitly configured MCP test interpreter,
|
|
255
|
+
the default Core suite skips seven real-stdio protocol cases. The two full
|
|
256
|
+
runs above included that SDK and skipped none. A separate CI job now declares
|
|
257
|
+
SDK-backed MCP checks for Python 3.10/3.13; it has not been run remotely in
|
|
258
|
+
this work, and no remote-CI success is claimed.
|
|
259
|
+
|
|
260
|
+
The 154-file offline package matched the frozen source and installed locally.
|
|
261
|
+
All 12 CLI help checks, adapter import, installed stdio handshake and five-tool
|
|
262
|
+
discovery passed. Installed tests covered valuable-file deletion and restore,
|
|
263
|
+
read-only queries, GC preview without payload removal, reconnect-persistent
|
|
264
|
+
budget, protection/batch refusals and refusal of override/force/GC-execute
|
|
265
|
+
parameters. Protocol acceptance exercised the classic `2025-06-18` handshake;
|
|
266
|
+
it does not establish every MCP protocol extension or client version.
|
|
267
|
+
|
|
268
|
+
Three real **Kimi Code 2.3.0 root-agent native MCP** trials passed:
|
|
269
|
+
|
|
270
|
+
| Trial | Time | Real model requests / MCP calls | Observed result |
|
|
271
|
+
|---|---:|---:|---|
|
|
272
|
+
| Ordinary delete/restore | 27.288 seconds | 7 / 6 | Model deleted, obtained a real transaction and restored original bytes |
|
|
273
|
+
| Same-session budget | 26.121 seconds | 7 / 6 | Second delete refused; model restored first file; budget remained charged |
|
|
274
|
+
| Configured protection | 16.814 seconds | 5 / 4 | Delete refused, original bytes retained, no recovery transaction |
|
|
275
|
+
|
|
276
|
+
All 19 configured-route requests returned HTTP 200, with 16 native MCP calls,
|
|
277
|
+
no fixed model replies, automatic trial retries or route switches. Each trial
|
|
278
|
+
used isolated configuration and synthetic files; the model had no Bash tool.
|
|
279
|
+
GC was previewed in all three trials and never executed. Before/after user
|
|
280
|
+
configuration/auth fingerprints and frozen candidate bytes remained equal.
|
|
281
|
+
The existing loopback gateway's actual server-side model identity was not
|
|
282
|
+
independently authenticated.
|
|
283
|
+
|
|
284
|
+
These results do not add native-hook, subagent, Claude/Cursor/Codex or other
|
|
285
|
+
tool coverage. Those three clients' examples were checked against official
|
|
286
|
+
documentation, not exercised as live clients here. Native Windows, macOS and
|
|
287
|
+
Android shared storage have no new validation. The first full-run error and
|
|
288
|
+
the earlier unexplained project test timeouts remain recorded as unresolved;
|
|
289
|
+
the current successful full run is not evidence of a general timeout fix.
|
|
290
|
+
|
|
291
|
+
The SDK and upstream setup references are primary sources, not this project's
|
|
292
|
+
acceptance results: [official Python SDK](https://github.com/modelcontextprotocol/python-sdk),
|
|
293
|
+
[selected SDK release metadata](https://pypi.org/project/mcp/2.3.0/).
|
|
@@ -1,9 +1,11 @@
|
|
|
1
1
|
# Reading guard status and cleanup results
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The CLI/DSH feedback below is included in
|
|
4
4
|
[0.2.5](../releases/release-notes-0.2.5.md).
|
|
5
5
|
They do not change deletion policy, wildcard handling, retention thresholds,
|
|
6
6
|
or the recovery format.
|
|
7
|
+
The final Kimi section describes the additions in
|
|
8
|
+
[0.2.6](../releases/release-notes-0.2.6.md).
|
|
7
9
|
|
|
8
10
|
## What the status establishes
|
|
9
11
|
|
|
@@ -96,3 +98,29 @@ Review the plan and selected transactions before choosing a purge. A manual
|
|
|
96
98
|
`--txid` selection is not limited to age/capacity eligibility. The 30-day and
|
|
97
99
|
5-GiB thresholds do not run GC automatically. `--execute` alone selects
|
|
98
100
|
nothing; GC does not prune Git stash snapshots.
|
|
101
|
+
|
|
102
|
+
## Kimi: tool success and recovery feedback
|
|
103
|
+
|
|
104
|
+
In the sampled Kimi 0.42.0, 2.1.1 and 2.3.0 paths, successful PreToolUse recovery
|
|
105
|
+
explanations did not enter the next model request. A successful Bash result
|
|
106
|
+
alone therefore does not tell the model that files were retained.
|
|
107
|
+
The [2.3.0 observations](../reports/test-report-kimi-code-block.md#kimi-230-acceptance)
|
|
108
|
+
used fixed responses through the actual prompt CLI and ACP host, with no
|
|
109
|
+
external model calls.
|
|
110
|
+
|
|
111
|
+
Version 0.2.6 provides a separate, opt-in POSIX Stop hook. It supplies
|
|
112
|
+
actual transaction IDs, state/restore commands, retained-storage guidance and
|
|
113
|
+
full GC commands, then asks for one extra response after the initial answer.
|
|
114
|
+
The initial answer may already be inaccurate, and the model can still omit
|
|
115
|
+
details. Emission cursors track notices, not model acknowledgement.
|
|
116
|
+
|
|
117
|
+
Restoring files returns them to their original location; it does not free
|
|
118
|
+
total disk space. GC permanently removes recovery copies and remains an
|
|
119
|
+
explicit operation. The Stop hook itself executes no restore or GC.
|
|
120
|
+
Published 0.2.5 lacks the Stop helper. See [setup and limits](../../adapters/kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition)
|
|
121
|
+
and the [bounded real-host report](../reports/test-report-kimi-code-block.md).
|
|
122
|
+
In 0.2.6, the doctor separates PreToolUse from Stop
|
|
123
|
+
configuration and local feedback probes. `--probe` uses isolated synthetic
|
|
124
|
+
records and leaves existing recovery data alone. Stop's `model_delivery`
|
|
125
|
+
remains `UNVERIFIED`; local PASS does not establish model receipt. See the
|
|
126
|
+
[Stop doctor fields](../../adapters/kimi-code/README.md#stop-doctor-checks-unreleased).
|
package/docs/history/friction.md
CHANGED
|
@@ -9,7 +9,7 @@ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
|
|
|
9
9
|
F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
|
|
10
10
|
observer startup maintenance; publication is checked by its versioned receipts.
|
|
11
11
|
Current scope is in the
|
|
12
|
-
[
|
|
12
|
+
[0.2.7 notes](../releases/release-notes-0.2.7.md); historical failures and
|
|
13
13
|
test counts below are not rewritten by a later success.
|
|
14
14
|
|
|
15
15
|
## Current feedback maintenance · status, explanations and retained storage
|
|
@@ -567,3 +567,101 @@ Exact CLI/recovery paths and error diagnostics remain available, with the
|
|
|
567
567
|
same mutation-intent durability and assessment/outcome failure behavior.
|
|
568
568
|
Historical records, automatic session identity and other audit/output
|
|
569
569
|
writers remain outside this change.
|
|
570
|
+
|
|
571
|
+
<a id="f32-deletion-admission"></a>
|
|
572
|
+
|
|
573
|
+
## F32 · Repeated admitted deletions could keep growing recovery storage
|
|
574
|
+
|
|
575
|
+
The existing recovery path preserved valuable content but had no persistent
|
|
576
|
+
session byte/entry budget, rolling operation rate or same-target-set limit.
|
|
577
|
+
A caller could repeatedly delete/recreate content or launch fresh CLI
|
|
578
|
+
processes while adding more recovery copies. The soft 30-day/5-GiB GC plan
|
|
579
|
+
did not bound new admission and never purged automatically.
|
|
580
|
+
|
|
581
|
+
**0.2.7 change:** covered relocations, Git-clean compensation and
|
|
582
|
+
force-restore occupant preservation now check quarantine admission capacity.
|
|
583
|
+
Regenerable direct deletion also consumes applicable session/rate/repeat
|
|
584
|
+
budgets. Accounting is persisted before the guarded operation under a
|
|
585
|
+
cross-process lock; admitted failures and subsequent restores do not refund
|
|
586
|
+
it. Unnamed CLI processes share a stable bucket instead of receiving a fresh
|
|
587
|
+
budget on every invocation.
|
|
588
|
+
|
|
589
|
+
Defaults are 5 GiB/100000 quarantine entries, 1 GiB/10000 admitted session
|
|
590
|
+
entries, 60 operations per 60 seconds and five admissions of the same
|
|
591
|
+
normalized target set per window. `BLOCK_DELETE_LIMIT`, `BLOCK_DELETE_RATE`
|
|
592
|
+
and `BLOCK_DELETE_REPEAT` are upgrade-visible refusals. Inspect `status` and
|
|
593
|
+
the caller; rate/repeat windows can expire, while cumulative budgets require
|
|
594
|
+
explicit operator review and interactive `RESET` or a deliberate policy
|
|
595
|
+
adjustment. Do not switch session identity or remove state to bypass them.
|
|
596
|
+
|
|
597
|
+
Capacity pressure never triggers automatic GC or a fallback to permanent
|
|
598
|
+
deletion. Normal restore, explicit transaction GC and unprotected quarantine
|
|
599
|
+
payload housekeeping remain available without a new deletion debit. Existing
|
|
600
|
+
compound ASK and Git snapshots remain outside these counters. Logical
|
|
601
|
+
accounting and same-UID state are accident suppression, not an OS disk quota
|
|
602
|
+
or a complete anomaly detector. See [deletion limits](../guides/deletion-limits.md)
|
|
603
|
+
for metadata/hardlink accounting and fixed inventory bounds.
|
|
604
|
+
|
|
605
|
+
<a id="f33-batch-confirmation"></a>
|
|
606
|
+
|
|
607
|
+
## F33 · Large automated deletion batches had no separate review gate
|
|
608
|
+
|
|
609
|
+
A supported automated command could compensate many concrete targets under
|
|
610
|
+
the existing deletion policy without an additional batch-size review. Looking
|
|
611
|
+
at each segment separately also let one shell request contain several
|
|
612
|
+
individually small deletions whose combined target set was large.
|
|
613
|
+
|
|
614
|
+
**0.2.7 change:** the enforced checker combines covered rm/artifact
|
|
615
|
+
and enumerated Git-clean targets before its first compensation. Operations
|
|
616
|
+
above 256 MiB or 1000 filesystem entries return
|
|
617
|
+
`BLOCK_DELETE_BATCH_CONFIRM`, directing the operator to the reviewed Cleanup
|
|
618
|
+
plan. The default plan only proposes candidates; execution requires exact
|
|
619
|
+
selection and terminal `EXECUTE`, followed by rescan and per-target
|
|
620
|
+
safe_delete calls.
|
|
621
|
+
|
|
622
|
+
Cleanup creates a ten-minute approval bound to the session, effective
|
|
623
|
+
configuration, exact paths and measured metadata. Each path is consumed once;
|
|
624
|
+
stale, changed, expired or replayed approval is refused. This lifts only the
|
|
625
|
+
batch gate, not protection, session/rate/repeat or quarantine capacity.
|
|
626
|
+
There is no new native host ASK/resume protocol; existing compound ASK and
|
|
627
|
+
Git SNAPSHOT behavior remains separate. The optional MCP adapter does not
|
|
628
|
+
expose approval creation or provide a `confirm=true` shortcut. See the
|
|
629
|
+
[Cleanup workflow](../guides/cleanup-plan.md).
|
|
630
|
+
|
|
631
|
+
<a id="f34-deletion-protection"></a>
|
|
632
|
+
|
|
633
|
+
## F34 · Configured evidence and admission controls needed shared protection
|
|
634
|
+
|
|
635
|
+
Existing hard-coded workspace/Git/recovery boundaries did not express
|
|
636
|
+
additional project evidence roots or a shared protected-path list. Artifact
|
|
637
|
+
classification and housekeeping could not rely on such a declaration, and
|
|
638
|
+
new budget/configuration state needed protection from covered deletion.
|
|
639
|
+
|
|
640
|
+
**0.2.7 change:** the optional workspace
|
|
641
|
+
`.agent-guard/delete-policy.json` supplies literal protected paths and limits.
|
|
642
|
+
Protection covers lexical/physical locations, descendants and ancestor
|
|
643
|
+
deletion, before artifact or payload-housekeeping exemptions. The configuration
|
|
644
|
+
directory, `admission.json`, temporary state and `admission.lock` are protected.
|
|
645
|
+
Missing configuration uses documented defaults without creating the file;
|
|
646
|
+
malformed, unreadable or unsupported configuration returns
|
|
647
|
+
`BLOCK_DELETE_CONFIG_INVALID`. Overlap returns `BLOCK_DELETE_PROTECTED`;
|
|
648
|
+
unusable admission inventory, lock or state returns
|
|
649
|
+
`BLOCK_DELETE_STATE_INVALID` instead of silently disabling admission.
|
|
650
|
+
|
|
651
|
+
Fix the reported configuration/storage issue or preserve the protected
|
|
652
|
+
evidence; do not remove controls to make deletion proceed. This is cooperative
|
|
653
|
+
path protection, not legal hold, minimum directory retention or immutable
|
|
654
|
+
storage. Same-UID processes and unobserved writes/deletion channels remain
|
|
655
|
+
outside its authority. Existing recovery format and explicit GC semantics
|
|
656
|
+
are retained.
|
|
657
|
+
|
|
658
|
+
The maintainer selected version 0.2.7 for these F32–F34
|
|
659
|
+
changes as a bounded maintenance-version exception, recorded in
|
|
660
|
+
[compatibility](../design/compatibility.md#027-candidate-bounded-maintainer-selected-exception).
|
|
661
|
+
This does not relax the general minor-release promise for other patches.
|
|
662
|
+
The pre-alignment 1090/1123-case runs and sampled Kimi results keep their
|
|
663
|
+
original scope. At the 2026-10-29 versioned preparation checkpoint, 1129
|
|
664
|
+
Python cases and both Node groups passed in 1194.265 seconds, and the
|
|
665
|
+
155-file offline package passed installed MCP checks. That local checkpoint
|
|
666
|
+
did not include remote CI or publication, and made no new real-model requests.
|
|
667
|
+
See the [versioned validation record](../releases/release-notes-0.2.7.md#validation-status).
|