@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.6
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 +64 -34
- package/README.zh-CN.md +53 -27
- package/SECURITY.md +5 -3
- package/adapters/INTEGRATION.md +84 -10
- package/adapters/claude/README.md +6 -0
- package/adapters/dsh/README.md +51 -7
- 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/dsh/lib/index.js +127 -33
- 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/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +30 -8
- package/docs/design/architecture.md +13 -6
- package/docs/design/compatibility.md +87 -4
- package/docs/design/dsh-compatibility.md +65 -0
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +76 -17
- package/docs/guides/harness-capabilities.md +24 -5
- package/docs/guides/host-drift.md +32 -0
- package/docs/guides/recovery-feedback.md +126 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +1 -1
- package/docs/lab/guard-lab.md +6 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/docs/releases/release-notes-0.2.6.md +167 -0
- package/docs/releases/unreleased.md +141 -0
- package/docs/reports/test-report-dsh-alpha4.md +102 -0
- package/docs/reports/test-report-kimi-code-block.md +119 -6
- package/doctor.py +175 -28
- package/package.json +11 -2
- package/skills/delete-guard/SKILL.md +30 -13
- package/skills/delete-guard/references/policy.md +16 -3
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
|
@@ -1,6 +1,118 @@
|
|
|
1
|
-
# Kimi Code 0.42.0 / 2.1.1: bounded Bash enforcement tests
|
|
2
|
-
|
|
3
|
-
|
|
1
|
+
# Kimi Code 0.42.0 / 2.1.1 / 2.3.0: bounded Bash enforcement tests
|
|
2
|
+
|
|
3
|
+
The Stop helper, separate doctor checks and 2.3.0 Bash profile ship in
|
|
4
|
+
[0.2.6](../releases/release-notes-0.2.6.md). Dated sections retain the source's
|
|
5
|
+
publication state at the time of each trial; their evidence limits are unchanged.
|
|
6
|
+
|
|
7
|
+
<a id="kimi-230-acceptance"></a>
|
|
8
|
+
|
|
9
|
+
## Kimi 2.3.0 follow-up (2026-10-22, unpublished checkout)
|
|
10
|
+
|
|
11
|
+
The actual npm Kimi Code **2.3.0** CLI ran sixteen isolated trials with the
|
|
12
|
+
unpublished 0.2.6 checkout's existing PreToolUse bridge and optional Stop
|
|
13
|
+
helper. Eight used prompt CLI; eight used ACP with the service launched from
|
|
14
|
+
directory A and a session created in directory B. Each fixture had its own
|
|
15
|
+
home, configuration and Git workspace. Fixed OpenAI-compatible loopback
|
|
16
|
+
responses drove Bash calls: **36 loopback model-protocol requests, zero external
|
|
17
|
+
model calls**, and no production credentials. The environment was Linux
|
|
18
|
+
ARM64/PRoot Debian with Node 22.23.4.
|
|
19
|
+
|
|
20
|
+
The ACP client did not advertise a terminal capability, so Kimi executed
|
|
21
|
+
Bash locally. The hook observer recorded the original payload, process cwd,
|
|
22
|
+
bridge exit code and output without changing the decision. All invoked ACP
|
|
23
|
+
hooks ran in B and carried B as payload cwd, independently of startup in A.
|
|
24
|
+
|
|
25
|
+
| Case, run once through both prompt CLI and ACP | Observation |
|
|
26
|
+
|---|---|
|
|
27
|
+
| Harmless allow | Hook exited 0; the owned marker was created; empty Stop added no request. |
|
|
28
|
+
| Policy BLOCK | Core reported `BLOCK_FORCE_PUSH`; exit 2 blocked the inert command and its bypass marker was absent. |
|
|
29
|
+
| Core ASK | The adapter hard-refused with exit 2; the bypass marker was absent. This was no approval-UI test. |
|
|
30
|
+
| Missing Python after the shell bridge started | The bridge converted startup failure to exit 2; the marker was absent. |
|
|
31
|
+
| No hook configured | No hook receipt; the harmless bypass marker was created. This remains an uncovered path. |
|
|
32
|
+
| Recoverable deletion | The owned file was relocated; Stop supplied its actual txid, retained-space notice and complete GC commands in the next request; restoration matched the original bytes. |
|
|
33
|
+
| Partial compensation | The call was refused after a recorded move; Stop supplied the incomplete status and recovery guidance; the moved file restored exactly. |
|
|
34
|
+
| Same recoverable call without Stop | The file remained recoverable, but no recovery explanation entered a later request. |
|
|
35
|
+
|
|
36
|
+
Successful PreToolUse recovery output still did not reach the first request
|
|
37
|
+
after Bash. Stop added a third request in the two compensation cases. These
|
|
38
|
+
fixed responses establish delivery into a request, not a real model's
|
|
39
|
+
understanding or accurate final wording. No purge was run.
|
|
40
|
+
|
|
41
|
+
The `km` Web wrapper was separately checked with a private configuration:
|
|
42
|
+
2.3.0 startup, HTTP 200, status recognition and shutdown passed. That was
|
|
43
|
+
not a Web-session tool-call trial. Normal/login Bash, an inherited old PATH,
|
|
44
|
+
and repeated configuration loading selected the updated executable; this is
|
|
45
|
+
local launcher evidence, not a new portable shell-configuration feature.
|
|
46
|
+
|
|
47
|
+
The unpublished checkout now lists exact version 2.3.0 in the
|
|
48
|
+
[Bash compatibility profile](../../adapters/kimi-code/compatibility.json).
|
|
49
|
+
The shared Core, payload mapping and bridge were unchanged. This admits the
|
|
50
|
+
observed root Bash contract; it does not establish 2.3.0 subagent, background,
|
|
51
|
+
concurrent, other-tool, client-provided terminal, timeout-failure or real-model
|
|
52
|
+
coverage. The [Lab capture helper](../../adapters/kimi-code/harness/README.md)
|
|
53
|
+
remains pinned to 2.1.1. Published 0.2.5 keeps its recorded version list.
|
|
54
|
+
The historical observations below retain their original versions and limits.
|
|
55
|
+
|
|
56
|
+
## Recovery-feedback follow-up (2026-10-20, unreleased source)
|
|
57
|
+
|
|
58
|
+
A new Kimi 2.1.1 session used the checkout's PreToolUse 120-second hook and
|
|
59
|
+
optional Stop 30-second hook, with an isolated HOME, skills directory,
|
|
60
|
+
workspace and model budget. One configured model route completed three
|
|
61
|
+
requests, all HTTP 200. The client route does not independently identify
|
|
62
|
+
remote model weights; private connection and transaction identifiers are omitted.
|
|
63
|
+
|
|
64
|
+
The session performed one guarded deletion of a synthetic valuable file.
|
|
65
|
+
Stop supplied the recorded transaction ID and the full state, restore and
|
|
66
|
+
GC commands. The final supplement stated that retained files occupy storage
|
|
67
|
+
and restoration does not free total disk space. After the model stopped,
|
|
68
|
+
the controller restored the exact original bytes, confirmed RESTORED, and
|
|
69
|
+
verified a repeated Stop emitted no duplicate notice. The model did not
|
|
70
|
+
execute restore or purge itself.
|
|
71
|
+
|
|
72
|
+
The initial answer still appeared before Stop. This passing final supplement
|
|
73
|
+
does not guarantee every model's wording or cover the user's full daily
|
|
74
|
+
configuration, background work, shared-session actors or long conversations.
|
|
75
|
+
Fixed loopback normal/blocked calls separately confirmed ordinary commands
|
|
76
|
+
without compensations require no extra reply, and refused calls did not create
|
|
77
|
+
their inert markers.
|
|
78
|
+
|
|
79
|
+
This helper is absent from published 0.2.5. See [unreleased availability](../releases/unreleased.md)
|
|
80
|
+
and [setup and delivery limits](../../adapters/kimi-code/README.md#optional-recovery-feedback-unreleased-checkout-addition).
|
|
81
|
+
|
|
82
|
+
## Hook failure audit (2026-10-20, local checkout)
|
|
83
|
+
|
|
84
|
+
Fourteen isolated trials used the actual 0.42.0 and 2.1.1 CLIs, native Bash
|
|
85
|
+
and the current checkout's bridge. Each CLI ran the seven cases below.
|
|
86
|
+
Thirty-two model-protocol requests received fixed loopback responses;
|
|
87
|
+
there were no external model calls or production credentials. These tests
|
|
88
|
+
establish hook behavior, not a real model's interpretation of feedback.
|
|
89
|
+
|
|
90
|
+
| Case, independently tested on both versions | Observed result |
|
|
91
|
+
|---|---|
|
|
92
|
+
| Started guard, process-local invalid dialect | Exit-2 refusal reached the host; inert Bash marker absent |
|
|
93
|
+
| Started bridge, missing Python interpreter | Exit-2 refusal; marker absent |
|
|
94
|
+
| Hook command does not exist | Bash ran and created the marker; no adapter started |
|
|
95
|
+
| Started hook delayed past a one-second host timeout | Bash ran and created the marker |
|
|
96
|
+
| Recoverable deletion and optional Stop feedback | Real txid, retained-space notice and complete GC commands entered the next request; public restore returned the original bytes |
|
|
97
|
+
| Stop Python startup failure | One feedback-unavailable continuation; the earlier successful Bash marker remained |
|
|
98
|
+
| Stop without compensation records | No additional model request |
|
|
99
|
+
|
|
100
|
+
The PreToolUse example now uses `timeout = 120`. Its previous 90-second
|
|
101
|
+
outer timeout matched the adapter's inner 90-second guard deadline and
|
|
102
|
+
left no startup/return margin. The one-second timeout probe demonstrates
|
|
103
|
+
the host's timeout behavior; it does not claim a measured 90-second race.
|
|
104
|
+
The longer example timeout reduces that race, while missing hooks and host
|
|
105
|
+
timeouts still allow tools. Local doctor checks do not exercise deadline
|
|
106
|
+
exhaustion or certify live interception.
|
|
107
|
+
|
|
108
|
+
The optional Stop addition is **not in the published 0.2.5 package**.
|
|
109
|
+
These new records supplement the earlier authenticated live trials below;
|
|
110
|
+
they do not replace their model, tool, subagent or failure limits. User
|
|
111
|
+
configuration, deletion policy and recovery formats were unchanged.
|
|
112
|
+
|
|
113
|
+
<a id="current-host-live-sentinel-kimi-code-211"></a>
|
|
114
|
+
|
|
115
|
+
## Live sentinel (2026-09-27, Kimi Code 2.1.1)
|
|
4
116
|
|
|
5
117
|
On 2026-09-27, the checksum-verified official Linux ARM64 build of Kimi Code
|
|
6
118
|
CLI 2.1.1 ran two authenticated model routes in new isolated fixtures:
|
|
@@ -34,10 +146,11 @@ cwd, and a timed-out host is always `INCONCLUSIVE` even if block evidence was
|
|
|
34
146
|
already present. The second route's prompt also forbids retrying after a block.
|
|
35
147
|
Only the post-fix, exact-command, normally exited runs are counted as PASS.
|
|
36
148
|
|
|
37
|
-
This
|
|
149
|
+
This sentinel evidence covers one root-agent `Bash` call. It does not add
|
|
38
150
|
2.1.1 evidence for subagents, concurrent calls, ASK behavior, non-`Bash`
|
|
39
|
-
tools, hook absence/timeouts or adapter-startup faults.
|
|
40
|
-
|
|
151
|
+
tools, hook absence/timeouts or adapter-startup faults. The later fixed-loopback
|
|
152
|
+
failure audit above provides separate, bounded fault observations for both
|
|
153
|
+
versions; the broader historical 0.42.0 observations follow below.
|
|
41
154
|
|
|
42
155
|
## Historical Kimi Code 0.42.0 trials
|
|
43
156
|
|
package/doctor.py
CHANGED
|
@@ -22,6 +22,7 @@ from core.dialects import resolve_dialect
|
|
|
22
22
|
|
|
23
23
|
ROOT = Path(__file__).resolve().parent
|
|
24
24
|
KIMI_BRIDGE = ROOT / "adapters" / "kimi-code" / "hook_bridge.sh"
|
|
25
|
+
KIMI_FEEDBACK = ROOT / "adapters" / "kimi-code" / "stop_feedback.py"
|
|
25
26
|
CLAUDE_BRIDGE = ROOT / "adapters" / "claude" / "hook_bridge.sh"
|
|
26
27
|
PROFILE_PATHS = {
|
|
27
28
|
"kimi": ROOT / "adapters" / "kimi-code" / "compatibility.json",
|
|
@@ -41,6 +42,29 @@ class HostProfile:
|
|
|
41
42
|
path: Path
|
|
42
43
|
|
|
43
44
|
|
|
45
|
+
@dataclass
|
|
46
|
+
class FeedbackDiagnosis:
|
|
47
|
+
configured: Optional[bool]
|
|
48
|
+
configuration: str
|
|
49
|
+
local_probe: str
|
|
50
|
+
problems: list[str]
|
|
51
|
+
command: Optional[tuple[Path, Path, Path]] = None
|
|
52
|
+
fingerprint: Optional[str] = None
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def failed(self) -> bool:
|
|
56
|
+
return self.configuration == "FAIL" or self.local_probe == "FAIL"
|
|
57
|
+
|
|
58
|
+
def as_dict(self) -> dict:
|
|
59
|
+
return {
|
|
60
|
+
"configured": self.configured,
|
|
61
|
+
"configuration": self.configuration,
|
|
62
|
+
"local_probe": self.local_probe,
|
|
63
|
+
"model_delivery": "UNVERIFIED",
|
|
64
|
+
"problems": self.problems,
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
|
|
44
68
|
@dataclass
|
|
45
69
|
class Diagnosis:
|
|
46
70
|
harness: str
|
|
@@ -55,9 +79,14 @@ class Diagnosis:
|
|
|
55
79
|
runtime_fingerprint: Optional[str] = None
|
|
56
80
|
drift_problems: Optional[list[str]] = None
|
|
57
81
|
baseline_written: bool = False
|
|
82
|
+
feedback: Optional[FeedbackDiagnosis] = None
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
def failed(self) -> bool:
|
|
86
|
+
return bool(self.problems or self.feedback and self.feedback.failed)
|
|
58
87
|
|
|
59
88
|
def as_dict(self) -> dict:
|
|
60
|
-
|
|
89
|
+
report = {
|
|
61
90
|
"harness": self.harness,
|
|
62
91
|
"configuration": self.configuration,
|
|
63
92
|
"local_probe": self.local_probe,
|
|
@@ -71,6 +100,9 @@ class Diagnosis:
|
|
|
71
100
|
"drift_problems": self.drift_problems or [],
|
|
72
101
|
"baseline_written": self.baseline_written,
|
|
73
102
|
}
|
|
103
|
+
if self.feedback is not None:
|
|
104
|
+
report["feedback"] = self.feedback.as_dict()
|
|
105
|
+
return report
|
|
74
106
|
|
|
75
107
|
|
|
76
108
|
def _load_profile(harness: str) -> HostProfile:
|
|
@@ -119,7 +151,9 @@ def _fingerprint(value: Any) -> str:
|
|
|
119
151
|
return "sha256:" + hashlib.sha256(encoded).hexdigest()
|
|
120
152
|
|
|
121
153
|
|
|
122
|
-
def _runtime_fingerprint(
|
|
154
|
+
def _runtime_fingerprint(
|
|
155
|
+
harness: str, profile: HostProfile, include_feedback: bool = False,
|
|
156
|
+
) -> str:
|
|
123
157
|
paths = {
|
|
124
158
|
ROOT / "package.json",
|
|
125
159
|
profile.path,
|
|
@@ -138,6 +172,8 @@ def _runtime_fingerprint(harness: str, profile: HostProfile) -> str:
|
|
|
138
172
|
ROOT / "adapters" / "kimi-code" / "pre_tool_use.py",
|
|
139
173
|
ROOT / "adapters" / "claude" / "pre_tool_use.py",
|
|
140
174
|
})
|
|
175
|
+
if include_feedback:
|
|
176
|
+
paths.add(KIMI_FEEDBACK)
|
|
141
177
|
digest = hashlib.sha256()
|
|
142
178
|
for path in sorted(paths, key=lambda item: str(item.relative_to(ROOT))):
|
|
143
179
|
relative = str(path.relative_to(ROOT)).encode("utf-8")
|
|
@@ -218,7 +254,7 @@ def _executable(path: Path) -> bool:
|
|
|
218
254
|
|
|
219
255
|
|
|
220
256
|
def _bridge_command(
|
|
221
|
-
command: object, expected_bridge: Path,
|
|
257
|
+
command: object, expected_bridge: Path, *, stop_feedback: bool = False,
|
|
222
258
|
) -> tuple[list[str], Optional[tuple[Path, Path, Path]]]:
|
|
223
259
|
if not isinstance(command, str):
|
|
224
260
|
return ["hook command must be a string"], None
|
|
@@ -226,6 +262,10 @@ def _bridge_command(
|
|
|
226
262
|
tokens = _command_tokens(command)
|
|
227
263
|
except ValueError:
|
|
228
264
|
return ["hook command has invalid shell quoting"], None
|
|
265
|
+
if stop_feedback:
|
|
266
|
+
if len(tokens) != 4 or tokens[-1] != "--stop-feedback":
|
|
267
|
+
return ["Stop command must be: ABSOLUTE_SH ABSOLUTE_BRIDGE ABSOLUTE_PYTHON --stop-feedback"], None
|
|
268
|
+
tokens = tokens[:-1]
|
|
229
269
|
if len(tokens) != 3 or not all(Path(part).is_absolute() for part in tokens):
|
|
230
270
|
return ["hook command must be: ABSOLUTE_SH ABSOLUTE_BRIDGE ABSOLUTE_PYTHON"], None
|
|
231
271
|
|
|
@@ -257,10 +297,10 @@ def _probe(harness: str, shell: Path, bridge: Path, python: Path) -> list[str]:
|
|
|
257
297
|
"tool_input": {"command": "touch .guard-doctor-ask && rm .guard-doctor-ask"},
|
|
258
298
|
"cwd": cwd,
|
|
259
299
|
})
|
|
260
|
-
probe_env =
|
|
261
|
-
|
|
262
|
-
probe_env.pop("AGENT_GUARD_SESSION", None)
|
|
300
|
+
probe_env = {key: value for key, value in os.environ.items()
|
|
301
|
+
if not key.startswith("AGENT_GUARD_")}
|
|
263
302
|
probe_env["AGENT_GUARD_WORKSPACE"] = cwd
|
|
303
|
+
probe_env["AGENT_GUARD_TRASH"] = str(Path(cwd) / ".agent-trash")
|
|
264
304
|
cases = (
|
|
265
305
|
(python, payload, 0, "valid Bash payload", None, None),
|
|
266
306
|
(python, "{", 2, "malformed payload", None, "malformed hook payload"),
|
|
@@ -327,36 +367,85 @@ def _dialect_problems() -> list[str]:
|
|
|
327
367
|
return []
|
|
328
368
|
|
|
329
369
|
|
|
370
|
+
def _probe_feedback(shell: Path, bridge: Path, python: Path) -> list[str]:
|
|
371
|
+
from core import AUDIT_NAME, audit
|
|
372
|
+
|
|
373
|
+
with tempfile.TemporaryDirectory(prefix="agent-guard-doctor-feedback-") as temporary:
|
|
374
|
+
workspace = Path(temporary)
|
|
375
|
+
home, trash = workspace / "home", workspace / "trash"
|
|
376
|
+
home.mkdir()
|
|
377
|
+
trash.mkdir()
|
|
378
|
+
env = {key: value for key, value in os.environ.items()
|
|
379
|
+
if not key.startswith("AGENT_GUARD_")}
|
|
380
|
+
env.update(HOME=str(home), KIMI_CODE_HOME=str(home / "kimi"),
|
|
381
|
+
AGENT_GUARD_WORKSPACE=temporary, AGENT_GUARD_TRASH=str(trash))
|
|
382
|
+
session = "agent-guard-doctor-feedback-probe"
|
|
383
|
+
txid = "20000101-000000-00000000"
|
|
384
|
+
record = json.dumps({
|
|
385
|
+
"event": "enforce-proceed", "session": audit.correlation_id(session),
|
|
386
|
+
"compensations": [{"strategy": "relocate", "txid": txid,
|
|
387
|
+
"status": "complete", "moved": 1, "skipped": 0}],
|
|
388
|
+
}) + "\n"
|
|
389
|
+
audit_path = trash / AUDIT_NAME
|
|
390
|
+
for label, active, expected in (
|
|
391
|
+
("no records", False, 0), ("active Stop", True, 0),
|
|
392
|
+
("synthetic recovery feedback", False, 2), ("repeat Stop", False, 0)):
|
|
393
|
+
if active:
|
|
394
|
+
audit_path.write_text(record, encoding="utf-8")
|
|
395
|
+
payload = json.dumps({"hook_event_name": "Stop", "cwd": temporary,
|
|
396
|
+
"session_id": session, "stop_hook_active": active})
|
|
397
|
+
try:
|
|
398
|
+
result = subprocess.run(
|
|
399
|
+
[str(shell), str(bridge), str(python), "--stop-feedback"],
|
|
400
|
+
input=payload, text=True, capture_output=True, cwd=temporary,
|
|
401
|
+
env=env, timeout=15, errors="replace")
|
|
402
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
403
|
+
return [f"{label}: Stop bridge could not finish"]
|
|
404
|
+
if result.returncode != expected:
|
|
405
|
+
return [f"{label}: expected exit {expected}, got {result.returncode}"]
|
|
406
|
+
if result.stdout:
|
|
407
|
+
return [f"{label}: Stop wrote unexpected stdout"]
|
|
408
|
+
if expected == 0 and result.stderr:
|
|
409
|
+
return [f"{label}: expected silent Stop"]
|
|
410
|
+
if expected == 2 and not all(marker in result.stderr for marker in (
|
|
411
|
+
"[agent-guard] Recovery records", txid, "still use disk space",
|
|
412
|
+
"GC preview:", "--execute --txid " + txid)):
|
|
413
|
+
return [f"{label}: expected transaction, retained-space and complete GC guidance"]
|
|
414
|
+
if audit_path.read_text(encoding="utf-8") != record:
|
|
415
|
+
return ["Stop probe changed its synthetic recovery audit"]
|
|
416
|
+
return []
|
|
417
|
+
|
|
418
|
+
|
|
330
419
|
def _check_kimi_config(
|
|
331
420
|
config_path: Path,
|
|
332
|
-
) -> tuple[list[str], Optional[tuple[Path, Path, Path]], Optional[str]]:
|
|
421
|
+
) -> tuple[list[str], Optional[tuple[Path, Path, Path]], Optional[str], Optional[dict]]:
|
|
333
422
|
problems: list[str] = []
|
|
334
423
|
problems.extend(_dialect_problems())
|
|
335
424
|
try:
|
|
336
425
|
import tomllib
|
|
337
426
|
except ImportError:
|
|
338
|
-
return ["doctor kimi requires Python 3.11+ (the hook adapter does not)"], None, None
|
|
427
|
+
return ["doctor kimi requires Python 3.11+ (the hook adapter does not)"], None, None, None
|
|
339
428
|
|
|
340
429
|
try:
|
|
341
430
|
with config_path.open("rb") as config_file:
|
|
342
431
|
config = tomllib.load(config_file)
|
|
343
432
|
except OSError:
|
|
344
|
-
return problems + [f"cannot read Kimi config: {config_path}"], None, None
|
|
345
|
-
except tomllib.TOMLDecodeError:
|
|
346
|
-
return problems + [f"Kimi config is not valid TOML: {config_path}"], None, None
|
|
433
|
+
return problems + [f"cannot read Kimi config: {config_path}"], None, None, None
|
|
434
|
+
except (tomllib.TOMLDecodeError, UnicodeError):
|
|
435
|
+
return problems + [f"Kimi config is not valid TOML: {config_path}"], None, None, None
|
|
347
436
|
|
|
348
437
|
hooks = config.get("hooks", [])
|
|
349
438
|
if not isinstance(hooks, list):
|
|
350
|
-
return problems + ["Kimi config `hooks` must be an array"], None, None
|
|
439
|
+
return problems + ["Kimi config `hooks` must be an array"], None, None, config
|
|
351
440
|
candidates = [hook for hook in hooks
|
|
352
441
|
if isinstance(hook, dict)
|
|
353
442
|
and hook.get("event") == "PreToolUse"
|
|
354
443
|
and any(marker in str(hook.get("command", ""))
|
|
355
444
|
for marker in ("hook_bridge.sh", "pre_tool_use.py"))]
|
|
356
445
|
if not candidates:
|
|
357
|
-
return problems + ["no agent-guard PreToolUse hook found in Kimi config"], None, None
|
|
446
|
+
return problems + ["no agent-guard PreToolUse hook found in Kimi config"], None, None, config
|
|
358
447
|
if len(candidates) != 1:
|
|
359
|
-
return problems + ["expected exactly one agent-guard PreToolUse hook"], None, None
|
|
448
|
+
return problems + ["expected exactly one agent-guard PreToolUse hook"], None, None, config
|
|
360
449
|
|
|
361
450
|
hook = candidates[0]
|
|
362
451
|
if hook.get("matcher") != "^Bash$":
|
|
@@ -382,7 +471,45 @@ def _check_kimi_config(
|
|
|
382
471
|
"timeout": timeout,
|
|
383
472
|
"dialect": dialect,
|
|
384
473
|
})
|
|
385
|
-
return problems, bridge_command, fingerprint
|
|
474
|
+
return problems, bridge_command, fingerprint, config
|
|
475
|
+
|
|
476
|
+
|
|
477
|
+
def _check_kimi_feedback(config: Optional[dict]) -> FeedbackDiagnosis:
|
|
478
|
+
if config is None or not isinstance(config.get("hooks", []), list):
|
|
479
|
+
return FeedbackDiagnosis(None, "UNVERIFIED", "NOT_RUN", [
|
|
480
|
+
"optional Stop could not be checked because the Kimi config is unreadable or invalid"])
|
|
481
|
+
candidates = [hook for hook in config.get("hooks", [])
|
|
482
|
+
if isinstance(hook, dict) and (
|
|
483
|
+
any(marker in str(hook.get("command", ""))
|
|
484
|
+
for marker in ("stop_feedback.py", "--stop-feedback"))
|
|
485
|
+
or hook.get("event") == "Stop"
|
|
486
|
+
and "hook_bridge.sh" in str(hook.get("command", "")))]
|
|
487
|
+
if not candidates:
|
|
488
|
+
return FeedbackDiagnosis(False, "NOT_CONFIGURED", "NOT_RUN", [])
|
|
489
|
+
if len(candidates) != 1:
|
|
490
|
+
return FeedbackDiagnosis(True, "FAIL", "NOT_RUN", [
|
|
491
|
+
"expected exactly one agent-guard Stop hook"])
|
|
492
|
+
hook = candidates[0]
|
|
493
|
+
problems, command = _bridge_command(
|
|
494
|
+
hook.get("command"), KIMI_BRIDGE, stop_feedback=True)
|
|
495
|
+
if hook.get("event") != "Stop":
|
|
496
|
+
problems.append("recovery feedback hook event must be exactly Stop")
|
|
497
|
+
if "matcher" in hook and hook["matcher"] != "":
|
|
498
|
+
problems.append("Stop matcher must be absent or empty; Bash filters do not cover Stop")
|
|
499
|
+
timeout = hook.get("timeout", 30)
|
|
500
|
+
if type(timeout) is not int or not 1 <= timeout <= 600:
|
|
501
|
+
problems.append("Stop timeout must be an integer from 1 to 600 seconds")
|
|
502
|
+
if not KIMI_FEEDBACK.is_file():
|
|
503
|
+
problems.append("stop_feedback.py is missing from this installation")
|
|
504
|
+
fingerprint = None
|
|
505
|
+
if not problems:
|
|
506
|
+
assert command is not None
|
|
507
|
+
fingerprint = _fingerprint({
|
|
508
|
+
"event": "Stop", "command_tokens": [str(part) for part in command] + ["--stop-feedback"],
|
|
509
|
+
"matcher": hook.get("matcher", ""), "timeout": timeout,
|
|
510
|
+
})
|
|
511
|
+
return FeedbackDiagnosis(True, "FAIL" if problems else "PASS", "NOT_RUN",
|
|
512
|
+
problems, command, fingerprint)
|
|
386
513
|
|
|
387
514
|
|
|
388
515
|
def _check_claude_config(
|
|
@@ -484,7 +611,7 @@ def _load_baseline(path: Path, harness: str) -> tuple[Optional[dict], list[str]]
|
|
|
484
611
|
|
|
485
612
|
|
|
486
613
|
def _write_baseline(path: Path, diagnosis: Diagnosis) -> Optional[str]:
|
|
487
|
-
if (diagnosis.drift_status != "CURRENT"
|
|
614
|
+
if (diagnosis.failed or diagnosis.drift_status != "CURRENT"
|
|
488
615
|
or diagnosis.local_probe != "PASS"
|
|
489
616
|
or not diagnosis.profile
|
|
490
617
|
or not diagnosis.host_version
|
|
@@ -514,11 +641,22 @@ def _diagnose(
|
|
|
514
641
|
harness: str, config_path: Path, run_probe: bool,
|
|
515
642
|
check_drift: bool = False, host_executable: Optional[str] = None,
|
|
516
643
|
baseline_path: Optional[Path] = None,
|
|
644
|
+
*, include_feedback: bool = True,
|
|
517
645
|
) -> Diagnosis:
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
646
|
+
feedback = None
|
|
647
|
+
if harness == "kimi":
|
|
648
|
+
problems, bridge_command, configuration_fingerprint, config = _check_kimi_config(config_path)
|
|
649
|
+
if include_feedback:
|
|
650
|
+
feedback = _check_kimi_feedback(config)
|
|
651
|
+
if feedback.configuration == "PASS" and configuration_fingerprint:
|
|
652
|
+
configuration_fingerprint = _fingerprint({
|
|
653
|
+
"pre_tool_use": configuration_fingerprint, "feedback": feedback.fingerprint})
|
|
654
|
+
if feedback.configuration == "PASS" and run_probe:
|
|
655
|
+
assert feedback.command is not None
|
|
656
|
+
feedback.problems = _probe_feedback(*feedback.command)
|
|
657
|
+
feedback.local_probe = "FAIL" if feedback.problems else "PASS"
|
|
658
|
+
else:
|
|
659
|
+
problems, bridge_command, configuration_fingerprint = _check_claude_config(config_path)
|
|
522
660
|
if problems:
|
|
523
661
|
diagnosis = Diagnosis(
|
|
524
662
|
harness, config_path, "FAIL", "NOT_RUN", problems,
|
|
@@ -534,6 +672,7 @@ def _diagnose(
|
|
|
534
672
|
harness, config_path, "PASS",
|
|
535
673
|
"FAIL" if probe_problems else "PASS", probe_problems,
|
|
536
674
|
configuration_fingerprint=configuration_fingerprint)
|
|
675
|
+
diagnosis.feedback = feedback
|
|
537
676
|
|
|
538
677
|
if not check_drift:
|
|
539
678
|
return diagnosis
|
|
@@ -549,7 +688,8 @@ def _diagnose(
|
|
|
549
688
|
|
|
550
689
|
diagnosis.profile = profile.profile_id
|
|
551
690
|
try:
|
|
552
|
-
diagnosis.runtime_fingerprint = _runtime_fingerprint(
|
|
691
|
+
diagnosis.runtime_fingerprint = _runtime_fingerprint(
|
|
692
|
+
harness, profile, bool(feedback and feedback.configured))
|
|
553
693
|
except OSError:
|
|
554
694
|
drift_problems.append("runtime fingerprint could not be computed")
|
|
555
695
|
|
|
@@ -565,7 +705,7 @@ def _diagnose(
|
|
|
565
705
|
drift_problems.extend(baseline_problems)
|
|
566
706
|
baseline_invalid = baseline is None
|
|
567
707
|
|
|
568
|
-
if diagnosis.
|
|
708
|
+
if diagnosis.failed:
|
|
569
709
|
diagnosis.drift_status = "BROKEN"
|
|
570
710
|
elif baseline_invalid:
|
|
571
711
|
diagnosis.drift_status = "UNVERIFIED"
|
|
@@ -599,8 +739,8 @@ def _diagnose(
|
|
|
599
739
|
|
|
600
740
|
|
|
601
741
|
def check_kimi(config_path: Path, run_probe: bool = False) -> list[str]:
|
|
602
|
-
"""Compatibility wrapper
|
|
603
|
-
return _diagnose("kimi", config_path, run_probe).problems
|
|
742
|
+
"""Compatibility wrapper retaining the original PreToolUse-only check."""
|
|
743
|
+
return _diagnose("kimi", config_path, run_probe, include_feedback=False).problems
|
|
604
744
|
|
|
605
745
|
|
|
606
746
|
def check_claude(config_path: Path, run_probe: bool = False) -> list[str]:
|
|
@@ -682,7 +822,7 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
682
822
|
sentinel_result = None
|
|
683
823
|
sentinel_report = None
|
|
684
824
|
if args.live_sentinel:
|
|
685
|
-
if (diagnosis.configuration != "PASS"
|
|
825
|
+
if (diagnosis.failed or diagnosis.configuration != "PASS"
|
|
686
826
|
or diagnosis.local_probe != "PASS"):
|
|
687
827
|
sentinel_report = {
|
|
688
828
|
"status": "INCONCLUSIVE", "alarm": "WARNING",
|
|
@@ -718,18 +858,25 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
718
858
|
print(json.dumps(report, ensure_ascii=False))
|
|
719
859
|
if sentinel_report is not None:
|
|
720
860
|
return {"PASS": 0, "FAIL": 2}.get(sentinel_report["status"], 1)
|
|
721
|
-
return 1 if (diagnosis.
|
|
861
|
+
return 1 if (diagnosis.failed or write_error or (
|
|
722
862
|
check_drift and diagnosis.drift_status != "CURRENT")) else 0
|
|
723
863
|
if diagnosis.problems:
|
|
724
864
|
for problem in diagnosis.problems:
|
|
725
865
|
print(f"FAIL: {problem}", file=sys.stderr)
|
|
726
866
|
else:
|
|
727
|
-
|
|
867
|
+
scope = "PreToolUse" if args.harness == "kimi" else "selected hook"
|
|
868
|
+
print(f"PASS: {args.harness} {scope} configuration shape checked ({config_path})")
|
|
728
869
|
if diagnosis.local_probe == "PASS":
|
|
729
870
|
print("PASS: local Bash allow, malformed refusal, Core policy refusal, "
|
|
730
871
|
"ASK mapping, and failed-interpreter probes")
|
|
731
872
|
else:
|
|
732
873
|
print(f"LOCAL_PROBE: {diagnosis.local_probe}")
|
|
874
|
+
if diagnosis.feedback is not None:
|
|
875
|
+
print(f"FEEDBACK_CONFIGURATION: {diagnosis.feedback.configuration} (optional Kimi Stop)")
|
|
876
|
+
print(f"FEEDBACK_LOCAL_PROBE: {diagnosis.feedback.local_probe}")
|
|
877
|
+
for problem in diagnosis.feedback.problems:
|
|
878
|
+
print(f"FEEDBACK_FAIL: {problem}", file=sys.stderr)
|
|
879
|
+
print("MODEL_DELIVERY: UNVERIFIED (local Stop checks do not prove model receipt)")
|
|
733
880
|
print("HOST_INTERCEPTION: UNVERIFIED (the selected file and local bridge "
|
|
734
881
|
"do not prove a live host loaded or enforced this hook)")
|
|
735
882
|
if check_drift:
|
|
@@ -748,7 +895,7 @@ def main(argv: Optional[list[str]] = None) -> int:
|
|
|
748
895
|
if sentinel_report["status"] != "PASS":
|
|
749
896
|
print("WARNING: live host protection was not verified", file=sys.stderr)
|
|
750
897
|
return {"PASS": 0, "FAIL": 2}.get(sentinel_report["status"], 1)
|
|
751
|
-
return 1 if (diagnosis.
|
|
898
|
+
return 1 if (diagnosis.failed or write_error or (
|
|
752
899
|
check_drift and diagnosis.drift_status != "CURRENT")) else 0
|
|
753
900
|
|
|
754
901
|
|
package/package.json
CHANGED
|
@@ -1,8 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.6",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
|
+
"engines": {
|
|
7
|
+
"dsh": "0.1.5-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.4"
|
|
8
|
+
},
|
|
9
|
+
"peerDependencies": {
|
|
10
|
+
"@deepseek-ai/dsh": "0.1.5-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.4"
|
|
11
|
+
},
|
|
12
|
+
"peerDependenciesMeta": {
|
|
13
|
+
"@deepseek-ai/dsh": { "optional": true }
|
|
14
|
+
},
|
|
6
15
|
"main": "./adapters/dsh/lib/index.js",
|
|
7
16
|
"exports": {
|
|
8
17
|
".": "./adapters/dsh/lib/index.js",
|
|
@@ -46,7 +55,7 @@
|
|
|
46
55
|
],
|
|
47
56
|
"dsh": {
|
|
48
57
|
"engines": {
|
|
49
|
-
"dsh": "0.1.5-rc.1 || 0.2.0-rc.2"
|
|
58
|
+
"dsh": "0.1.5-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.4"
|
|
50
59
|
},
|
|
51
60
|
"bundle": {
|
|
52
61
|
"patch": "./adapters/dsh/cordis.patch.yml"
|
|
@@ -32,15 +32,15 @@ enforces and how to work with it productively. The four pillars:
|
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
34
|
# delete explicit targets; valuable content is quarantined:
|
|
35
|
-
python3
|
|
36
|
-
python3
|
|
35
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
36
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
|
|
37
37
|
|
|
38
38
|
# undo a transaction (list first if unsure):
|
|
39
|
-
python3
|
|
40
|
-
python3
|
|
39
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
|
|
40
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
|
|
41
41
|
|
|
42
42
|
# current guard state:
|
|
43
|
-
python3
|
|
43
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py
|
|
44
44
|
```
|
|
45
45
|
|
|
46
46
|
Globs passed to `safe_delete` are expanded explicitly before anything moves.
|
|
@@ -54,7 +54,9 @@ can receive:
|
|
|
54
54
|
|
|
55
55
|
| Verdict | Meaning | Your move |
|
|
56
56
|
|---|---|---|
|
|
57
|
-
| `ALLOW`
|
|
57
|
+
| `ALLOW` | no recovery action for recognized operations; unrecognized effects are unchecked | continue only within the authorized scope; do not infer that scripts or overwrites are safe |
|
|
58
|
+
| `RELOCATE` / `SNAPSHOT` (harness may show `PROCEED` after compensation) | quarantine or tracked Git snapshot required | record and verify the resulting `txid` before continuing |
|
|
59
|
+
| `ASK` | this understood operation needs single-execution approval | use the host's human approval path; if unavailable, stop or split the command |
|
|
58
60
|
| `BLOCK_UNDETERMINABLE_EFFECT` | targets unresolvable (`$VAR`, `bash -c`, `find -delete`, `xargs`) | restate with explicit paths, or use `safe_delete` |
|
|
59
61
|
| `BLOCK_WILDCARD` | glob target set is opaque | use `safe_delete` with the glob |
|
|
60
62
|
| `BLOCK_OUT_OF_WORKSPACE` / `BLOCK_PROTECTED_PATH` / `BLOCK_PROTECTED_ANCESTOR` | outside boundary, workspace root, `.git`, or a filesystem root (`/`, `/home`, `/usr`, `$HOME`) | do not retry; this is a hard boundary. Ask the human if it is truly needed |
|
|
@@ -63,8 +65,10 @@ can receive:
|
|
|
63
65
|
|
|
64
66
|
Shape rules on compound commands: a single line that `cd`s anywhere before a
|
|
65
67
|
destructive op (F1), or that creates files (`touch/mkdir/cp/mv/tee`,
|
|
66
|
-
redirections) before destroying them (F2),
|
|
67
|
-
|
|
68
|
+
redirections) before destroying them (F2), can return `ASK` when its targets
|
|
69
|
+
are resolvable and within policy boundaries. Unresolvable effects and hard
|
|
70
|
+
boundaries still return `BLOCK`; hosts without a usable approval path deny
|
|
71
|
+
the `ASK` call. Run deletions as standalone commands with an explicit workdir.
|
|
68
72
|
|
|
69
73
|
A block is not an error to route around. Retrying the same operation in a
|
|
70
74
|
disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
|
|
@@ -117,13 +121,26 @@ uses opaque session correlation and limits status/GC metadata; see the
|
|
|
117
121
|
|
|
118
122
|
## Quarantine location queries
|
|
119
123
|
|
|
124
|
+
In 0.2.5, deletion/status results explain
|
|
125
|
+
retained storage and include GC commands. Moving files to quarantine keeps
|
|
126
|
+
their data on disk. Review the plan before choosing `--execute --all-eligible`
|
|
127
|
+
or a specific `--execute --txid`; use the same working directory and workspace/
|
|
128
|
+
trash settings. Age/size thresholds do not perform automatic cleanup.
|
|
129
|
+
|
|
130
|
+
`status.py` reports local recovery data and does not verify host activation.
|
|
131
|
+
DSH's status tool separately reports the plugin process startup check and
|
|
132
|
+
listener registration, with live interception still `UNVERIFIED`. A missing
|
|
133
|
+
plugin cannot supply its own status tool. `ALLOW_NOOP` does not certify
|
|
134
|
+
unrecognized script/interpreter effects. See the
|
|
135
|
+
[feedback guide](../../docs/guides/recovery-feedback.md).
|
|
136
|
+
|
|
120
137
|
When the user asks where quarantines are or how many exist, use the shared
|
|
121
138
|
read-only query with a current-directory or user-selected scope:
|
|
122
139
|
|
|
123
140
|
```bash
|
|
124
|
-
python3
|
|
125
|
-
python3
|
|
126
|
-
python3
|
|
141
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --json
|
|
142
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --root /absolute/path/to/projects --max-depth 3 --json
|
|
143
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --trash /absolute/path/to/custom-store --json
|
|
127
144
|
```
|
|
128
145
|
|
|
129
146
|
Report the scope, candidate count, metadata-identified count and read/budget
|
|
@@ -137,10 +154,10 @@ read just to answer a location/count question.
|
|
|
137
154
|
|
|
138
155
|
## RESTRICTED mode
|
|
139
156
|
|
|
140
|
-
|
|
157
|
+
Version 0.2.5 retains RC1 protection for the quarantine root, root manifest,
|
|
141
158
|
audit/state files, state temp file, sessions tree and storage access parents.
|
|
142
159
|
Housekeeping does not override those checks. Use the existing explicit
|
|
143
|
-
`gc.py --execute --txid <
|
|
160
|
+
`gc.py --execute --txid '<txid>'` entry for a validated, audited transaction purge.
|
|
144
161
|
Ordinary unprotected payload housekeeping retains its existing policy.
|
|
145
162
|
GC plans omit `PURGED` history; they do not delete stored Git stashes.
|
|
146
163
|
|