@mokuyoaxis/agent-guard 0.2.5 → 0.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -23
- package/README.zh-CN.md +51 -22
- package/adapters/INTEGRATION.md +90 -10
- package/adapters/claude/README.md +6 -0
- package/adapters/dsh/README.md +19 -8
- package/adapters/dsh/compatibility.json +14 -0
- package/adapters/dsh/harness/README.md +11 -0
- package/adapters/dsh/harness/guard_lab.py +42 -14
- package/adapters/kimi-code/README.md +154 -14
- package/adapters/kimi-code/compatibility.json +1 -1
- package/adapters/kimi-code/config.example.toml +18 -6
- package/adapters/kimi-code/hook_bridge.sh +19 -4
- package/adapters/kimi-code/pre_tool_use.py +1 -1
- package/adapters/kimi-code/stop_feedback.py +237 -0
- package/adapters/mcp/__init__.py +1 -0
- package/adapters/mcp/operations.py +174 -0
- package/adapters/mcp/requirements.txt +3 -0
- package/adapters/mcp/server.py +126 -0
- package/core/admission.py +388 -0
- package/core/audit.py +1 -1
- package/core/classifier.py +2 -1
- package/core/cleanup.py +297 -0
- package/core/delete_config.py +153 -0
- package/core/policy.py +35 -7
- package/core/recovery.py +10 -0
- package/docs/README.md +25 -7
- package/docs/design/architecture.md +16 -4
- package/docs/design/compatibility.md +230 -6
- package/docs/design/dsh-compatibility.md +65 -0
- package/docs/design/threat-model.md +53 -1
- package/docs/guides/cleanup-plan.md +227 -0
- package/docs/guides/deletion-limits.md +150 -0
- package/docs/guides/getting-started.md +72 -11
- package/docs/guides/harness-capabilities.md +37 -4
- package/docs/guides/host-drift.md +32 -0
- package/docs/guides/mcp.md +293 -0
- package/docs/guides/recovery-feedback.md +29 -1
- package/docs/history/friction.md +99 -1
- package/docs/releases/release-notes-0.2.6.md +167 -0
- package/docs/releases/release-notes-0.2.7.md +217 -0
- package/docs/releases/unreleased.md +275 -0
- package/docs/reports/test-report-dsh-alpha4.md +102 -0
- package/docs/reports/test-report-dsh-paired-lab.md +1 -1
- package/docs/reports/test-report-kimi-code-block.md +120 -7
- package/doctor.py +175 -28
- package/package.json +13 -2
- package/skills/delete-guard/SKILL.md +69 -1
- package/skills/delete-guard/references/policy.md +66 -3
- package/skills/delete-guard/scripts/check.py +39 -9
- package/skills/delete-guard/scripts/cleanup.py +164 -0
- package/skills/delete-guard/scripts/safe_delete.py +22 -4
- package/skills/delete-guard/scripts/status.py +77 -1
|
@@ -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](
|
|
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
|
-
|
|
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
|
|
|
@@ -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`](
|
|
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
|
-
|
|
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
|
|