@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.
Files changed (44) hide show
  1. package/README.md +64 -34
  2. package/README.zh-CN.md +53 -27
  3. package/SECURITY.md +5 -3
  4. package/adapters/INTEGRATION.md +84 -10
  5. package/adapters/claude/README.md +6 -0
  6. package/adapters/dsh/README.md +51 -7
  7. package/adapters/dsh/compatibility.json +14 -0
  8. package/adapters/dsh/harness/README.md +11 -0
  9. package/adapters/dsh/harness/guard_lab.py +42 -14
  10. package/adapters/dsh/lib/index.js +127 -33
  11. package/adapters/kimi-code/README.md +154 -14
  12. package/adapters/kimi-code/compatibility.json +1 -1
  13. package/adapters/kimi-code/config.example.toml +18 -6
  14. package/adapters/kimi-code/hook_bridge.sh +19 -4
  15. package/adapters/kimi-code/pre_tool_use.py +1 -1
  16. package/adapters/kimi-code/stop_feedback.py +237 -0
  17. package/core/messages.py +40 -0
  18. package/core/policy.py +2 -1
  19. package/docs/README.md +30 -8
  20. package/docs/design/architecture.md +13 -6
  21. package/docs/design/compatibility.md +87 -4
  22. package/docs/design/dsh-compatibility.md +65 -0
  23. package/docs/design/threat-model.md +2 -2
  24. package/docs/guides/getting-started.md +76 -17
  25. package/docs/guides/harness-capabilities.md +24 -5
  26. package/docs/guides/host-drift.md +32 -0
  27. package/docs/guides/recovery-feedback.md +126 -0
  28. package/docs/history/friction.md +21 -1
  29. package/docs/lab/blue-team-calibration.md +1 -1
  30. package/docs/lab/guard-lab.md +6 -2
  31. package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
  32. package/docs/releases/release-notes-0.2.5.md +123 -0
  33. package/docs/releases/release-notes-0.2.6.md +167 -0
  34. package/docs/releases/unreleased.md +141 -0
  35. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  36. package/docs/reports/test-report-kimi-code-block.md +119 -6
  37. package/doctor.py +175 -28
  38. package/package.json +11 -2
  39. package/skills/delete-guard/SKILL.md +30 -13
  40. package/skills/delete-guard/references/policy.md +16 -3
  41. package/skills/delete-guard/scripts/check.py +13 -0
  42. package/skills/delete-guard/scripts/gc.py +4 -2
  43. package/skills/delete-guard/scripts/safe_delete.py +20 -14
  44. 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
- ## Current-host live sentinel: Kimi Code 2.1.1
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 current-host evidence covers one root-agent `Bash` call. It does not add
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. Those remain separate
40
- from the broader historical 0.42.0 observations below.
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
- return {
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(harness: str, profile: HostProfile) -> str:
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 = dict(os.environ)
261
- probe_env.pop("AGENT_GUARD_DIALECT", None)
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
- problems, bridge_command, configuration_fingerprint = (
519
- _check_kimi_config(config_path) if harness == "kimi"
520
- else _check_claude_config(config_path)
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(harness, profile)
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.problems:
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 for callers using the original Kimi checker."""
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.problems or write_error or (
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
- print(f"PASS: {args.harness} selected hook configuration shape checked ({config_path})")
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.problems or write_error or (
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.5-rc3",
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 <repo>/skills/delete-guard/scripts/safe_delete.py src/old_module.py
36
- python3 <repo>/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
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 <repo>/skills/delete-guard/scripts/restore.py list
40
- python3 <repo>/skills/delete-guard/scripts/restore.py <txid>
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 <repo>/skills/delete-guard/scripts/status.py
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` (harness may show `PROCEED`) | safe as-is or compensation already applied | continue; record and verify any `txid` |
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), is refused as undeterminable.
67
- Run deletions as standalone commands with an explicit workdir.
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 <repo>/skills/delete-guard/scripts/status.py --trash-index --json
125
- python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --root <projects> --max-depth 3 --json
126
- python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --trash <custom-store> --json
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
- RC2 and RC3 retain RC1 protection for the quarantine root, root manifest,
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 <id>` entry for a validated, audited transaction purge.
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