@mokuyoaxis/agent-guard 0.2.5 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +61 -23
  2. package/README.zh-CN.md +51 -22
  3. package/adapters/INTEGRATION.md +90 -10
  4. package/adapters/claude/README.md +6 -0
  5. package/adapters/dsh/README.md +19 -8
  6. package/adapters/dsh/compatibility.json +14 -0
  7. package/adapters/dsh/harness/README.md +11 -0
  8. package/adapters/dsh/harness/guard_lab.py +42 -14
  9. package/adapters/kimi-code/README.md +154 -14
  10. package/adapters/kimi-code/compatibility.json +1 -1
  11. package/adapters/kimi-code/config.example.toml +18 -6
  12. package/adapters/kimi-code/hook_bridge.sh +19 -4
  13. package/adapters/kimi-code/pre_tool_use.py +1 -1
  14. package/adapters/kimi-code/stop_feedback.py +237 -0
  15. package/adapters/mcp/__init__.py +1 -0
  16. package/adapters/mcp/operations.py +174 -0
  17. package/adapters/mcp/requirements.txt +3 -0
  18. package/adapters/mcp/server.py +126 -0
  19. package/core/admission.py +388 -0
  20. package/core/audit.py +1 -1
  21. package/core/classifier.py +2 -1
  22. package/core/cleanup.py +297 -0
  23. package/core/delete_config.py +153 -0
  24. package/core/policy.py +35 -7
  25. package/core/recovery.py +10 -0
  26. package/docs/README.md +25 -7
  27. package/docs/design/architecture.md +16 -4
  28. package/docs/design/compatibility.md +230 -6
  29. package/docs/design/dsh-compatibility.md +65 -0
  30. package/docs/design/threat-model.md +53 -1
  31. package/docs/guides/cleanup-plan.md +227 -0
  32. package/docs/guides/deletion-limits.md +150 -0
  33. package/docs/guides/getting-started.md +72 -11
  34. package/docs/guides/harness-capabilities.md +37 -4
  35. package/docs/guides/host-drift.md +32 -0
  36. package/docs/guides/mcp.md +293 -0
  37. package/docs/guides/recovery-feedback.md +29 -1
  38. package/docs/history/friction.md +99 -1
  39. package/docs/releases/release-notes-0.2.6.md +167 -0
  40. package/docs/releases/release-notes-0.2.7.md +217 -0
  41. package/docs/releases/unreleased.md +275 -0
  42. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  43. package/docs/reports/test-report-dsh-paired-lab.md +1 -1
  44. package/docs/reports/test-report-kimi-code-block.md +120 -7
  45. package/doctor.py +175 -28
  46. package/package.json +13 -2
  47. package/skills/delete-guard/SKILL.md +69 -1
  48. package/skills/delete-guard/references/policy.md +66 -3
  49. package/skills/delete-guard/scripts/check.py +39 -9
  50. package/skills/delete-guard/scripts/cleanup.py +164 -0
  51. package/skills/delete-guard/scripts/safe_delete.py +22 -4
  52. package/skills/delete-guard/scripts/status.py +77 -1
@@ -0,0 +1,102 @@
1
+ # DSH alpha.4 default deletion adapter
2
+
3
+ Tested 2026-10-22 on ARM64/PRoot Debian with Node v22.23.2 and Python 3.13.5.
4
+ At validation, the selected Agent Guard checkout identified as 0.2.6 and was
5
+ unpublished. The tested additions now ship in [0.2.6](../releases/release-notes-0.2.6.md).
6
+ This report adds default deletion evidence for DSH `0.2.1-alpha.4`; the
7
+ [compatibility page](../design/dsh-compatibility.md) states the separate
8
+ optional-read and Lab boundaries.
9
+
10
+ ## Actual CLI and bundle loading
11
+
12
+ Three isolated runs launched the actual DSH CLI using an owned profile with
13
+ `dsh-base` and a local link to this checkout's package. Python Core came from
14
+ that selected package, with no `repoRoot` override. Homes, settings, profiles,
15
+ Git workspaces and recovery directories belonged to the trials. No user
16
+ profile was updated, and no DSH/dependency installation was performed.
17
+
18
+ The CLI roots were `0.1.5-rc.1`, `0.2.0-rc.2` and `0.2.1-alpha.4`.
19
+ The legacy root's key SDK packages are `0.1.5-rc.2`; root and SDK versions
20
+ were not assumed interchangeable. All three completed the following seven
21
+ checks through the real Profile/Boot and native Bash/shell services:
22
+
23
+ - Load the selected bundle and register its three recovery tools.
24
+ - Execute a harmless command.
25
+ - Reject a force-push-shaped command before its harmless bypass marker runs.
26
+ - Reject a wildcard deletion shape, preserving the owned log file.
27
+ - Reject an ASK when the direct call has no agent/approval route.
28
+ - Query status without promoting `host_interception` above `UNVERIFIED`.
29
+ - Quarantine an owned valuable file, report retained disk use and GC guidance,
30
+ then restore its original bytes through the registered tool.
31
+
32
+ ## Root and native child agents on alpha.4
33
+
34
+ The actual AgentLoop and native continuable subagent service ran five actors.
35
+ A local scripted LLM adapter emitted 15 fixed streams and ten Bash calls;
36
+ there were no external model requests. Bash, the deletion guard and the native
37
+ approval service were not replaced.
38
+
39
+ | Actor | Observed result |
40
+ |---|---|
41
+ | Root BLOCK | Benign command executed; force-push-shaped call refused; bypass marker absent |
42
+ | Native child BLOCK | Depth 1 and parent lineage recorded; same refusal and absent marker |
43
+ | Root ASK with policy `never` | Native approval rejected the call; marker absent |
44
+ | Native child ASK | Native delegated approval policy rejected the call; marker absent |
45
+ | Root ASK with fixed local answerer | Native approval recorded `allowed-once`; only the owned harmless approval marker ran |
46
+
47
+ The approval grant used a deterministic answerer for one owned sentinel.
48
+ It does not establish interactive approval UI behavior. The first attempt used
49
+ the older `subagents.start` API: its root case passed, then the child driver
50
+ failed because alpha.4 exposes `startActivation` instead. That failed attempt
51
+ was retained. Updating the test driver to the actual SDK interface required
52
+ no product adapter change.
53
+
54
+ Observe-only instrumentation checked each of the five checker requests against
55
+ the invoking agent session's native resolved policy. Workspace, signal and
56
+ the existing 90-second timeout were retained. Native execution used
57
+ `danger-full-access`. Unit checks additionally alternate distinct root/child
58
+ `read-only` and `workspace-write` policies to detect caching across callers.
59
+ These are forwarding checks, not an OS sandbox-confinement certification.
60
+
61
+ ## Loading failures and feature separation
62
+
63
+ Three additional alpha.4 CLI trials confirmed:
64
+
65
+ - Injected startup Python failure reports `GUARD_STARTUP_FAILED`, contributes
66
+ no guard tools and leaves the host able to run other tools.
67
+ - An absent bundle contributes no interception; the harmless marker runs.
68
+ - Explicitly enabling optional read redaction on alpha.4 reports
69
+ `READ_GUARD_STARTUP_REFUSED` and contributes no deletion/read guard from
70
+ that failed plugin row. Leave it disabled on alpha.4.
71
+
72
+ The default version expansion does not update native-read artifact hashes or
73
+ Lab session/config parsers. Their previous two-host contracts remain intact.
74
+
75
+ ## Manifest and regression scope
76
+
77
+ The default adapter's three-version profile matches top-level `engines.dsh`,
78
+ the optional DSH peer and nested `dsh.engines.dsh`. Actual rc.2 and alpha.4
79
+ compatibility helpers accepted all three declared versions and rejected twelve
80
+ unlisted versions each: six accept and 24 rejection checks, without exemptions.
81
+ The optional peer supplies compatibility metadata without installing DSH.
82
+ The legacy loader was checked through actual Profile/Boot rather than a
83
+ modern helper it does not provide.
84
+
85
+ The broader 12-version SDK experiment used controlled shell/synthetic Bash
86
+ tool bodies. Its remaining nine versions were not promoted into the published
87
+ declaration. This report's CLI checks use real native execution.
88
+
89
+ Package-manifest and DSH smoke/regression checks accompany this change.
90
+ The previous 974-test full run predates this expansion and is not its full-suite
91
+ result. Core decisions, command recognition, rm wildcard refusal, compensation,
92
+ recovery formats and the production JavaScript adapter retain their bytes.
93
+ Existing Kimi maintenance changes are separate from this DSH addition.
94
+
95
+ ## Limits
96
+
97
+ No external model, graphical UI, arbitrary PTC/API calls or concurrent-agent
98
+ trial was run. Policy forwarding does not prove OS sandbox enforcement.
99
+ Agent-less checks do not imply subagent coverage; the separate native child
100
+ cases above supply that bounded evidence. Package version, local test success
101
+ and a running host do not establish publication or activation in a user's
102
+ existing profile. Tag and release decisions remain pending.
@@ -97,7 +97,7 @@ The pinned `read` tool's presentation metadata contains the returned lines.
97
97
  Replacing only `content` therefore leaves a second copy of read text in the
98
98
  private session/UI data.
99
99
 
100
- The [native probe](../../tests/probes/dsh_result_hook.mjs) instantiates the real
100
+ The [native probe](https://github.com/mokuyoaxis/agent-guard/blob/e73101666288735880d4ff70bb0a20a025d426b0/tests/probes/dsh_result_hook.mjs) instantiates the real
101
101
  Cordis, SystemPrompt and ToolRuntime services, registers synthetic tools and
102
102
  tests their results without a model, shell, session or network request:
103
103
 
@@ -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
 
@@ -174,7 +287,7 @@ old direct-Python hook-startup failure demonstrates a concrete fail-open
174
287
  boundary; the later bridge trial shows only a bounded mitigation.
175
288
  The fixtures and traces were preserved for review. Adapter-level regressions
176
289
  for both inert command shapes live in
177
- [`tests/test_kimi_adapter.py`](../../tests/test_kimi_adapter.py).
290
+ [`tests/test_kimi_adapter.py`](https://github.com/mokuyoaxis/agent-guard/blob/75b51b888279583541792e00b14a4ceaf2a59fba/tests/test_kimi_adapter.py).
178
291
 
179
292
  After the live trials, the Kimi adapter was tightened to reject malformed
180
293
  `PreToolUse` JSON and missing required Bash fields. Unit tests verify this
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