@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -34
- package/README.zh-CN.md +53 -27
- package/SECURITY.md +5 -3
- package/adapters/INTEGRATION.md +84 -10
- package/adapters/claude/README.md +6 -0
- package/adapters/dsh/README.md +51 -7
- package/adapters/dsh/compatibility.json +14 -0
- package/adapters/dsh/harness/README.md +11 -0
- package/adapters/dsh/harness/guard_lab.py +42 -14
- package/adapters/dsh/lib/index.js +127 -33
- package/adapters/kimi-code/README.md +154 -14
- package/adapters/kimi-code/compatibility.json +1 -1
- package/adapters/kimi-code/config.example.toml +18 -6
- package/adapters/kimi-code/hook_bridge.sh +19 -4
- package/adapters/kimi-code/pre_tool_use.py +1 -1
- package/adapters/kimi-code/stop_feedback.py +237 -0
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +30 -8
- package/docs/design/architecture.md +13 -6
- package/docs/design/compatibility.md +87 -4
- package/docs/design/dsh-compatibility.md +65 -0
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +76 -17
- package/docs/guides/harness-capabilities.md +24 -5
- package/docs/guides/host-drift.md +32 -0
- package/docs/guides/recovery-feedback.md +126 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +1 -1
- package/docs/lab/guard-lab.md +6 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/docs/releases/release-notes-0.2.6.md +167 -0
- package/docs/releases/unreleased.md +141 -0
- package/docs/reports/test-report-dsh-alpha4.md +102 -0
- package/docs/reports/test-report-kimi-code-block.md +119 -6
- package/doctor.py +175 -28
- package/package.json +11 -2
- package/skills/delete-guard/SKILL.md +30 -13
- package/skills/delete-guard/references/policy.md +16 -3
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
# Kimi Code adapter - agent-guard
|
|
2
2
|
#
|
|
3
|
-
#
|
|
4
|
-
#
|
|
3
|
+
# Merge into ~/.kimi-code/config.toml; do not append this whole file.
|
|
4
|
+
# Put extraSkillDirs before the first [table], or extend its existing array.
|
|
5
|
+
# The [[hooks]] blocks can go at the end. Restart the session after editing.
|
|
5
6
|
#
|
|
6
7
|
# `matcher` is a REGULAR EXPRESSION tested against the tool name
|
|
7
8
|
# (`matches()` in the Kimi Code bundle uses `new RegExp(pattern).test(value)`;
|
|
@@ -19,8 +20,19 @@ matcher = "^Bash$"
|
|
|
19
20
|
# Replace all three paths for your machine. Use an absolute POSIX sh and Python.
|
|
20
21
|
# The shell bridge turns Python launch failures into Kimi's blocking exit 2.
|
|
21
22
|
command = "/bin/sh /absolute/path/to/agent-guard/adapters/kimi-code/hook_bridge.sh /absolute/path/to/python3"
|
|
22
|
-
|
|
23
|
+
# The adapter waits up to 90s for the guard. Leave time for Python startup
|
|
24
|
+
# and returning exit 2: a host timeout allows the tool instead of blocking it.
|
|
25
|
+
timeout = 120
|
|
23
26
|
|
|
24
|
-
# Optional
|
|
25
|
-
#
|
|
26
|
-
#
|
|
27
|
+
# Optional recovery feedback (unreleased checkout addition, POSIX only).
|
|
28
|
+
# Kimi ignores successful PreToolUse feedback. This Stop hook requests one
|
|
29
|
+
# extra model response AFTER the initial answer when new recovery records exist.
|
|
30
|
+
# Uncomment only if that extra response is wanted. The PreToolUse hook above
|
|
31
|
+
# remains required for interception; this Stop hook only reports saved data.
|
|
32
|
+
# [[hooks]]
|
|
33
|
+
# event = "Stop"
|
|
34
|
+
# command = "/bin/sh /absolute/path/to/agent-guard/adapters/kimi-code/hook_bridge.sh /absolute/path/to/python3 --stop-feedback"
|
|
35
|
+
# timeout = 30
|
|
36
|
+
|
|
37
|
+
# Optional debug: start Kimi with AGENT_GUARD_DEBUG=1 in its environment.
|
|
38
|
+
# There is no adapter-specific TOML debug option.
|
|
@@ -3,11 +3,26 @@
|
|
|
3
3
|
# bridge alive long enough to turn a failed Python launch into an explicit 2.
|
|
4
4
|
# A missing/unmatched hook or a host timeout is still fail-open.
|
|
5
5
|
|
|
6
|
-
if [ "$#" -
|
|
7
|
-
printf '%s\n' '[agent-guard] Kimi hook bridge needs one absolute Python path' >&2
|
|
6
|
+
if [ "$#" -lt 1 ] || [ "$#" -gt 2 ]; then
|
|
7
|
+
printf '%s\n' '[agent-guard] Kimi hook bridge needs one absolute Python path and optional --stop-feedback' >&2
|
|
8
8
|
exit 2
|
|
9
9
|
fi
|
|
10
10
|
|
|
11
|
+
hook_script=pre_tool_use.py
|
|
12
|
+
refusal='refusing tool call'
|
|
13
|
+
if [ "$#" -eq 2 ]; then
|
|
14
|
+
case "$2" in
|
|
15
|
+
--stop-feedback)
|
|
16
|
+
hook_script=stop_feedback.py
|
|
17
|
+
refusal='recovery feedback unavailable; inspect restore.py list'
|
|
18
|
+
;;
|
|
19
|
+
*)
|
|
20
|
+
printf '%s\n' '[agent-guard] Kimi hook bridge: unknown option' >&2
|
|
21
|
+
exit 2
|
|
22
|
+
;;
|
|
23
|
+
esac
|
|
24
|
+
fi
|
|
25
|
+
|
|
11
26
|
case "$1" in
|
|
12
27
|
/*) python_bin=$1 ;;
|
|
13
28
|
*)
|
|
@@ -21,12 +36,12 @@ bridge_dir=$(CDPATH= cd -P "$(dirname "$0")" 2>/dev/null && pwd -P) || {
|
|
|
21
36
|
exit 2
|
|
22
37
|
}
|
|
23
38
|
|
|
24
|
-
"$python_bin" "$bridge_dir
|
|
39
|
+
"$python_bin" "$bridge_dir/$hook_script"
|
|
25
40
|
status=$?
|
|
26
41
|
case "$status" in
|
|
27
42
|
0|2) exit "$status" ;;
|
|
28
43
|
*)
|
|
29
|
-
printf '[agent-guard] Kimi hook process failed (exit %s);
|
|
44
|
+
printf '[agent-guard] Kimi hook process failed (exit %s); %s\n' "$status" "$refusal" >&2
|
|
30
45
|
exit 2
|
|
31
46
|
;;
|
|
32
47
|
esac
|
|
@@ -33,7 +33,7 @@ to the observed root Bash call recorded in the public test report.
|
|
|
33
33
|
event = "PreToolUse"
|
|
34
34
|
matcher = "^Bash$" # regular expression over the tool name
|
|
35
35
|
command = "/bin/sh /path/to/agent-guard/adapters/kimi-code/hook_bridge.sh /absolute/path/to/python3"
|
|
36
|
-
timeout =
|
|
36
|
+
timeout = 120 # outer hook timeout; the inner guard deadline is 90s
|
|
37
37
|
|
|
38
38
|
Because the two contracts match, this adapter **delegates to the shared
|
|
39
39
|
Claude adapter** rather than reimplementing the payload -> core -> decision
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Optional POSIX Kimi Stop hook: report this session's recovery records once.
|
|
3
|
+
|
|
4
|
+
Reads existing guard audit metadata; never authorizes or executes a command.
|
|
5
|
+
Exit 2 asks Kimi for one additional answer after its initial response. The
|
|
6
|
+
cursor records emission, not acknowledgement by the model or the user.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import hashlib
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
from pathlib import Path
|
|
14
|
+
import re
|
|
15
|
+
import shlex
|
|
16
|
+
import stat
|
|
17
|
+
import sys
|
|
18
|
+
import tempfile
|
|
19
|
+
|
|
20
|
+
ROOT = Path(__file__).resolve().parents[2]
|
|
21
|
+
if str(ROOT) not in sys.path:
|
|
22
|
+
sys.path.insert(0, str(ROOT))
|
|
23
|
+
|
|
24
|
+
from core import AUDIT_NAME, MANIFEST_NAME, TRASH_DIRNAME, audit, classifier # noqa: E402
|
|
25
|
+
from core.messages import QUARANTINE_NOTICE # noqa: E402
|
|
26
|
+
|
|
27
|
+
_TXID = re.compile(r"[0-9]{8}-[0-9]{6}-[0-9a-f]{8}\Z")
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def incomplete_compensations(trash, check_ids):
|
|
31
|
+
"""Failed audit records omit compensations; correlate existing journal IDs.
|
|
32
|
+
|
|
33
|
+
Read only transaction headers and count journal events. Exact target paths,
|
|
34
|
+
commands and failure reasons never enter the feedback projection.
|
|
35
|
+
"""
|
|
36
|
+
if not check_ids:
|
|
37
|
+
return {}
|
|
38
|
+
try:
|
|
39
|
+
manifest = (trash / MANIFEST_NAME).open("rb")
|
|
40
|
+
except FileNotFoundError:
|
|
41
|
+
return {}
|
|
42
|
+
records = {}
|
|
43
|
+
with manifest:
|
|
44
|
+
for line in manifest:
|
|
45
|
+
if not line.endswith(b"\n"):
|
|
46
|
+
break
|
|
47
|
+
try:
|
|
48
|
+
row = json.loads(line)
|
|
49
|
+
except (json.JSONDecodeError, UnicodeDecodeError):
|
|
50
|
+
continue
|
|
51
|
+
if not isinstance(row, dict):
|
|
52
|
+
continue
|
|
53
|
+
txid = row.get("txid")
|
|
54
|
+
if not isinstance(txid, str) or not _TXID.fullmatch(txid):
|
|
55
|
+
continue
|
|
56
|
+
meta = row.get("meta")
|
|
57
|
+
check_id = meta.get("check_id") if isinstance(meta, dict) else None
|
|
58
|
+
related = isinstance(check_id, str) and check_id in check_ids
|
|
59
|
+
if row.get("type") == "tx-start" and related and row.get("strategy") == "relocate":
|
|
60
|
+
records[txid] = {"txid": txid, "strategy": "relocate", "status": "incomplete", "moved": 0}
|
|
61
|
+
elif row.get("type") == "snapshot" and related:
|
|
62
|
+
records[txid] = {"txid": txid, "strategy": "snapshot", "status": "incomplete"}
|
|
63
|
+
elif txid in records:
|
|
64
|
+
if row.get("type") == "relocate":
|
|
65
|
+
records[txid]["moved"] += 1
|
|
66
|
+
return records
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def recovery_message(records):
|
|
70
|
+
"""Only projected IDs/counts/statuses, never commands or target paths."""
|
|
71
|
+
lines = ["[agent-guard] Recovery records for this session:"]
|
|
72
|
+
has_files = False
|
|
73
|
+
has_snapshot = False
|
|
74
|
+
incomplete = False
|
|
75
|
+
restore = [sys.executable, str(ROOT / "skills/delete-guard/scripts/restore.py")]
|
|
76
|
+
gc = [sys.executable, str(ROOT / "skills/delete-guard/scripts/gc.py")]
|
|
77
|
+
for item in records:
|
|
78
|
+
snapshot = item["strategy"] == "snapshot"
|
|
79
|
+
incomplete |= item.get("status") != "complete"
|
|
80
|
+
label = "Git snapshot" if snapshot else "File relocation"
|
|
81
|
+
line = f"- {label}: txid={item['txid']}; status={item.get('status', 'unknown')}"
|
|
82
|
+
if not snapshot:
|
|
83
|
+
line += f"; moved={item.get('moved', 0)}; skipped={item.get('skipped', 'not recorded')}"
|
|
84
|
+
has_files |= item.get("moved", 0) > 0
|
|
85
|
+
has_snapshot |= snapshot
|
|
86
|
+
lines.append(line)
|
|
87
|
+
lines.append(" Restore after checking its current state: " +
|
|
88
|
+
shlex.join(restore + [item["txid"]]))
|
|
89
|
+
if not snapshot and item.get("moved", 0) > 0:
|
|
90
|
+
lines.append(" GC permanent purge after preview: " +
|
|
91
|
+
shlex.join(gc + ["--execute", "--txid", item["txid"]]))
|
|
92
|
+
lines += [
|
|
93
|
+
"Recorded before Bash, not confirmation that Bash ran.",
|
|
94
|
+
"Inspect current recovery state: " + shlex.join(restore + ["list", "--json"]),
|
|
95
|
+
]
|
|
96
|
+
if incomplete:
|
|
97
|
+
lines.append("Incomplete or failed records do not guarantee a recoverable copy.")
|
|
98
|
+
if has_files:
|
|
99
|
+
lines += [
|
|
100
|
+
QUARANTINE_NOTICE,
|
|
101
|
+
"Restoring files moves them back; it does not free total disk space.",
|
|
102
|
+
"Already restored or purged records may no longer have a copy in quarantine.",
|
|
103
|
+
"GC preview: " + shlex.join(gc),
|
|
104
|
+
]
|
|
105
|
+
if has_snapshot:
|
|
106
|
+
lines.append("GC does not remove Git stash snapshots.")
|
|
107
|
+
lines += [
|
|
108
|
+
"Use the same working directory and AGENT_GUARD_WORKSPACE / AGENT_GUARD_TRASH settings.",
|
|
109
|
+
"Supplement or correct the previous answer in at most three short bullets: "
|
|
110
|
+
"recovery result and txid, disk space, and the commands. "
|
|
111
|
+
"Copy commands verbatim on separate lines; do not abbreviate paths or replace txids. "
|
|
112
|
+
"Do not repeat the destructive command or restore/purge data for this feedback.",
|
|
113
|
+
]
|
|
114
|
+
return "\n".join(lines)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
def save_cursor(path, state):
|
|
118
|
+
"""Replace the checkpoint atomically while its separate lock stays held."""
|
|
119
|
+
with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=path.parent,
|
|
120
|
+
prefix=path.stem + ".", suffix=".tmp", delete=False) as temporary:
|
|
121
|
+
temporary_path = Path(temporary.name)
|
|
122
|
+
try:
|
|
123
|
+
json.dump(state, temporary)
|
|
124
|
+
temporary.flush()
|
|
125
|
+
os.fsync(temporary.fileno())
|
|
126
|
+
os.replace(temporary_path, path)
|
|
127
|
+
finally:
|
|
128
|
+
temporary_path.unlink(missing_ok=True)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def pending_feedback(cwd, session):
|
|
132
|
+
"""Consume complete audit lines under a per-workspace/session cursor lock."""
|
|
133
|
+
workspace = classifier.discover_workspace(cwd)
|
|
134
|
+
trash = Path(os.environ.get("AGENT_GUARD_TRASH", str(Path(workspace) / TRASH_DIRNAME)))
|
|
135
|
+
if not trash.is_absolute():
|
|
136
|
+
trash = Path(cwd) / trash
|
|
137
|
+
audit_path = trash / AUDIT_NAME
|
|
138
|
+
try:
|
|
139
|
+
source = audit_path.open("rb")
|
|
140
|
+
except FileNotFoundError:
|
|
141
|
+
return None
|
|
142
|
+
|
|
143
|
+
session_key = audit.correlation_id(session)
|
|
144
|
+
identity = json.dumps([os.path.realpath(workspace), str(trash.resolve()), session_key])
|
|
145
|
+
name = hashlib.sha256(identity.encode("utf-8")).hexdigest() + ".json"
|
|
146
|
+
home = Path(os.environ.get("KIMI_CODE_HOME", str(Path.home() / ".kimi-code")))
|
|
147
|
+
cursors = home / "agent-guard-feedback"
|
|
148
|
+
with source:
|
|
149
|
+
# This optional integration is POSIX-only, matching its shell bridge.
|
|
150
|
+
import fcntl
|
|
151
|
+
|
|
152
|
+
cursors.mkdir(mode=0o700, parents=True, exist_ok=True)
|
|
153
|
+
flags = os.O_RDWR | getattr(os, "O_NOFOLLOW", 0)
|
|
154
|
+
descriptor = os.open(cursors / (name + ".lock"), flags | os.O_CREAT, 0o600)
|
|
155
|
+
with os.fdopen(descriptor, "r+", encoding="utf-8") as lock:
|
|
156
|
+
if not stat.S_ISREG(os.fstat(lock.fileno()).st_mode):
|
|
157
|
+
raise ValueError("feedback lock is not a regular file")
|
|
158
|
+
fcntl.flock(lock, fcntl.LOCK_EX)
|
|
159
|
+
info = os.fstat(source.fileno())
|
|
160
|
+
try:
|
|
161
|
+
descriptor = os.open(cursors / name, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
|
|
162
|
+
except FileNotFoundError:
|
|
163
|
+
offset = 0
|
|
164
|
+
else:
|
|
165
|
+
with os.fdopen(descriptor, "r", encoding="utf-8") as cursor:
|
|
166
|
+
if not stat.S_ISREG(os.fstat(cursor.fileno()).st_mode):
|
|
167
|
+
raise ValueError("feedback cursor is not a regular file")
|
|
168
|
+
saved = json.load(cursor)
|
|
169
|
+
if (not isinstance(saved, dict)
|
|
170
|
+
or set(saved) != {"device", "inode", "offset"}
|
|
171
|
+
or any(type(saved[key]) is not int or saved[key] < 0 for key in saved)
|
|
172
|
+
or saved["device"] != info.st_dev or saved["inode"] != info.st_ino
|
|
173
|
+
or saved["offset"] > info.st_size):
|
|
174
|
+
raise ValueError("feedback cursor does not match the append-only audit")
|
|
175
|
+
offset = saved["offset"]
|
|
176
|
+
source.seek(offset)
|
|
177
|
+
records = {}
|
|
178
|
+
failed_checks = set()
|
|
179
|
+
while True:
|
|
180
|
+
line = source.readline()
|
|
181
|
+
if not line or not line.endswith(b"\n"):
|
|
182
|
+
break # An incomplete append must be read again next time.
|
|
183
|
+
offset = source.tell()
|
|
184
|
+
try:
|
|
185
|
+
raw = json.loads(line)
|
|
186
|
+
except (json.JSONDecodeError, UnicodeDecodeError):
|
|
187
|
+
continue # Same malformed-line rule as the shared audit reader.
|
|
188
|
+
if not isinstance(raw, dict):
|
|
189
|
+
continue
|
|
190
|
+
record = audit.project(raw)
|
|
191
|
+
if (record.get("session") != session_key
|
|
192
|
+
or record.get("event") not in {"enforce-proceed", "enforce-error", "enforce-block"}):
|
|
193
|
+
continue
|
|
194
|
+
if (not record.get("compensations") and record.get("check_id")
|
|
195
|
+
and record.get("event") in {"enforce-error", "enforce-block"}):
|
|
196
|
+
failed_checks.add(record["check_id"])
|
|
197
|
+
for item in record.get("compensations", []):
|
|
198
|
+
txid = item.get("txid", "")
|
|
199
|
+
if not _TXID.fullmatch(txid):
|
|
200
|
+
continue
|
|
201
|
+
strategy = item.get("strategy")
|
|
202
|
+
if (strategy == "snapshot" and (item.get("sha") or item.get("status") != "complete")
|
|
203
|
+
or strategy in {"relocate", "clean-enumerate"}
|
|
204
|
+
and (item.get("moved", 0) > 0 or item.get("status") != "complete")):
|
|
205
|
+
records[txid] = item
|
|
206
|
+
for txid, item in incomplete_compensations(trash, failed_checks).items():
|
|
207
|
+
records.setdefault(txid, item)
|
|
208
|
+
message = recovery_message(records.values()) if records else None
|
|
209
|
+
save_cursor(cursors / name, {"device": info.st_dev, "inode": info.st_ino, "offset": offset})
|
|
210
|
+
return message
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def main():
|
|
214
|
+
payload = json.load(sys.stdin)
|
|
215
|
+
if (not isinstance(payload, dict) or payload.get("hook_event_name") != "Stop"
|
|
216
|
+
or not isinstance(payload.get("cwd"), str) or not payload["cwd"].strip()
|
|
217
|
+
or not isinstance(payload.get("session_id"), str) or not payload["session_id"].strip()
|
|
218
|
+
or type(payload.get("stop_hook_active")) is not bool):
|
|
219
|
+
raise ValueError("invalid Stop hook payload")
|
|
220
|
+
if payload["stop_hook_active"]:
|
|
221
|
+
return 0
|
|
222
|
+
message = pending_feedback(payload["cwd"], payload["session_id"])
|
|
223
|
+
if message:
|
|
224
|
+
sys.stderr.write(message + "\n")
|
|
225
|
+
return 2
|
|
226
|
+
return 0
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
if __name__ == "__main__":
|
|
230
|
+
try:
|
|
231
|
+
sys.exit(main())
|
|
232
|
+
except (OSError, ValueError, ImportError) as error:
|
|
233
|
+
sys.stderr.write(
|
|
234
|
+
f"[agent-guard] Recovery feedback unavailable ({type(error).__name__}). "
|
|
235
|
+
"Inspect restore.py list from the original workspace; "
|
|
236
|
+
"this does not mean no files were preserved.\n")
|
|
237
|
+
sys.exit(2)
|
package/core/messages.py
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""User-facing storage notices; no policy or execution decisions."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
import shlex
|
|
6
|
+
import sys
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
QUARANTINE_NOTICE = (
|
|
10
|
+
"Files moved to quarantine still use disk space. "
|
|
11
|
+
"Purging permanently removes their recovery copies."
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
HOST_STATUS_NOTICE = (
|
|
15
|
+
"This reports local recovery data, not whether a host loaded the guard. "
|
|
16
|
+
"Check the host's plugin or hook status separately."
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def gc_guidance():
|
|
21
|
+
script = Path(__file__).resolve().parent.parent / "skills/delete-guard/scripts/gc.py"
|
|
22
|
+
command = [sys.executable, str(script)]
|
|
23
|
+
return {
|
|
24
|
+
"plan_command": shlex.join(command),
|
|
25
|
+
"purge_eligible_command": shlex.join(
|
|
26
|
+
command + ["--execute", "--all-eligible"]),
|
|
27
|
+
"purge_transaction_command": shlex.join(
|
|
28
|
+
command + ["--execute", "--txid", "<txid>"]),
|
|
29
|
+
"note": "POSIX-shell commands. Review the plan first. Run from the same working directory "
|
|
30
|
+
"with the same AGENT_GUARD_WORKSPACE / AGENT_GUARD_TRASH settings. "
|
|
31
|
+
"Replace <txid> to select one transaction.",
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def print_gc_guidance(guidance):
|
|
36
|
+
print(f"GC plan : {guidance['plan_command']}")
|
|
37
|
+
print(f"GC purge : {guidance['purge_eligible_command']}")
|
|
38
|
+
print(" permanently removes eligible recovery copies")
|
|
39
|
+
print(f"GC one : {guidance['purge_transaction_command']}")
|
|
40
|
+
print(guidance["note"])
|
package/core/policy.py
CHANGED
|
@@ -122,7 +122,8 @@ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
|
|
|
122
122
|
|
|
123
123
|
# Human-facing one-liners: why the guard cannot just do it (or did do it).
|
|
124
124
|
EXPLANATIONS: Dict[str, str] = {
|
|
125
|
-
CODE_ALLOW_NOOP: "
|
|
125
|
+
CODE_ALLOW_NOOP: "No recovery action is needed for the recognized operations. "
|
|
126
|
+
"Unrecognized command effects have not been checked.",
|
|
126
127
|
CODE_ALLOW_REGENERABLE: "All targets are git-ignored and match known "
|
|
127
128
|
"artifact patterns; deleted directly.",
|
|
128
129
|
CODE_ALLOW_TRASH_GC: "Targets live inside the quarantine; housekeeping "
|
package/docs/README.md
CHANGED
|
@@ -7,12 +7,20 @@ setup. The three main paths are [recovery protection](../skills/delete-guard/SKI
|
|
|
7
7
|
[harness capability matrix](guides/harness-capabilities.md) for observed coverage
|
|
8
8
|
and the [architecture](design/architecture.md) for the shared Core.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
10
|
+
Stable release line: [0.2.6](releases/release-notes-0.2.6.md), building on
|
|
11
|
+
0.2.5 with Kimi feedback, diagnostics and reviewed host compatibility. The exact
|
|
12
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.6)
|
|
13
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.6)
|
|
14
|
+
establish publication and npm `latest` availability; 0.2.5 is the previous stable.
|
|
15
|
+
The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
|
|
16
|
+
opt-in [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
17
|
+
quarantine protection backport. The [getting-started guide](guides/getting-started.md)
|
|
18
|
+
explains exact-version and local-package installation.
|
|
19
|
+
|
|
20
|
+
[0.2.6](releases/release-notes-0.2.6.md) covers Kimi Stop feedback,
|
|
21
|
+
its doctor checks, Kimi 2.3.0 root-Bash compatibility, DSH Lab preflight
|
|
22
|
+
diagnostics and alpha.4 default deletion compatibility. Existing 0.2.5 installations
|
|
23
|
+
need an upgrade to acquire these additions; see [maintenance details](releases/unreleased.md).
|
|
16
24
|
|
|
17
25
|
先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
|
|
18
26
|
历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
|
|
@@ -29,9 +37,13 @@ GitHub/npm package publication needs separate versioned receipts.
|
|
|
29
37
|
|
|
30
38
|
## Guides
|
|
31
39
|
|
|
40
|
+
当前源码中的[状态与清理反馈](guides/recovery-feedback.md)说明本地 Python/Hook/宿主验证的区别、
|
|
41
|
+
ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
|
|
42
|
+
|
|
32
43
|
| Document / 文档 | Scope / 范围 |
|
|
33
44
|
|---|---|
|
|
34
45
|
| [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
|
|
46
|
+
| [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
|
|
35
47
|
| [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
|
|
36
48
|
| [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
|
|
37
49
|
| [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
|
|
@@ -41,6 +53,11 @@ GitHub/npm package publication needs separate versioned receipts.
|
|
|
41
53
|
Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
|
|
42
54
|
remain in [skills/](../skills/delete-guard/SKILL.md).
|
|
43
55
|
|
|
56
|
+
We currently focus on DSH and Kimi Code. Claude Code's adapter and past
|
|
57
|
+
reports remain available; testing new Claude versions is paused. For other
|
|
58
|
+
hosts, ask the official agent to follow the
|
|
59
|
+
[integration requirements](../adapters/INTEGRATION.md) and configure Agent Guard locally.
|
|
60
|
+
|
|
44
61
|
## Design
|
|
45
62
|
|
|
46
63
|
| Document / 文档 | Scope / 范围 |
|
|
@@ -83,11 +100,12 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
83
100
|
| [0.2.3 contract review](reports/test-report-release-readiness-0.2.3.md) | 发布前契约复核与 DSH 原生验收 |
|
|
84
101
|
| [0.2.4 official Flash / PTC](reports/test-report-dsh-0.2.4-ptc.md) | 实模主/子代理碰撞拒绝;原始主 PTC 任务失败与独立收尾分别记录 |
|
|
85
102
|
| [Claude Code harness](reports/test-report-claude-code-harness.md) | 脚本模型驱动的真实宿主 hook 验证 |
|
|
86
|
-
| [Kimi Code blocking](reports/test-report-kimi-code-block.md) |
|
|
103
|
+
| [Kimi Code blocking and feedback](reports/test-report-kimi-code-block.md) | 0.42.0/2.1.1 历史试次与 2.3.0 根代理 CLI/ACP 固定响应复验,含 Stop 和 cwd 边界 |
|
|
87
104
|
| [Kimi Code Lab](reports/test-report-kimi-guard-lab.md) | 历史配对试次与后续本地复核 |
|
|
88
105
|
| [Codex / GPT-6 Astra](reports/test-report-codex-gpt-6-astra-high.md) | Skill/CLI 验收,不声明原生拦截 |
|
|
89
106
|
| [Codex / GPT-5.6 Sol](reports/test-report-codex-gpt-5.6-sol.md) | v0.1.1 历史 Skill/CLI 评估 |
|
|
90
107
|
| [DSH 0.1.5-rc.1](reports/test-report-dsh-0.1.5-rc.1.md) | 打包插件与执行级 Bash 验收 |
|
|
108
|
+
| [DSH alpha.4 compatibility](reports/test-report-dsh-alpha4.md) | 默认删除适配的真实 Profile/Bash/主子代理、恢复和审批;可选 read/Lab 不扩展 |
|
|
91
109
|
| [DSH 0.2 upgrade](reports/test-report-dsh-0.2-upgrade.md) | 升级初期兼容快照,后续状态见契约复核 |
|
|
92
110
|
| [DSH Lab baseline](reports/test-report-dsh-guard-lab.md) | 真实模型基线;未形成 L2 结论 |
|
|
93
111
|
| [DSH native sessions](reports/test-report-dsh-native-session.md) | 原生工具结果捕获与保留日志复核 |
|
|
@@ -103,7 +121,11 @@ coverage rather than treating every historical result as current acceptance.
|
|
|
103
121
|
|
|
104
122
|
| Document / 文档 | Scope / 范围 |
|
|
105
123
|
|---|---|
|
|
106
|
-
| [0.2.
|
|
124
|
+
| [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
|
|
125
|
+
| [0.2.6 maintenance details](releases/unreleased.md) | 原未发布维护页,保留 0.2.6 功能说明与历史验收边界 |
|
|
126
|
+
| [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
|
|
127
|
+
| [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
|
|
128
|
+
| [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
|
|
107
129
|
| [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md) | 已发布的维护 RC;共享审计、observer 维护与兼容边界 |
|
|
108
130
|
| [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 已发布的维护预发布基线、文档整理与版本例外 |
|
|
109
131
|
| [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
|
|
@@ -305,13 +305,20 @@ order of value:
|
|
|
305
305
|
|
|
306
306
|
## Delivery status and design directions
|
|
307
307
|
|
|
308
|
-
The
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
308
|
+
The stable release line is 0.2.6. Previous stable 0.2.5, opt-in
|
|
309
|
+
0.2.4-hotfix.1 and prerelease 0.2.5-rc3 retain their separate artifacts.
|
|
310
|
+
Version 0.2.5 retains RC recovery, shared audit,
|
|
311
|
+
observer maintenance and [defensive research](../research/README.md), plus
|
|
312
|
+
clearer local startup/status and retained-storage feedback. Private research
|
|
313
|
+
methods do not add a general authorization service or production enforcement
|
|
314
|
+
point. Deletion rules and execution routes retain their RC behavior.
|
|
315
|
+
See [release notes](../releases/release-notes-0.2.6.md) and
|
|
314
316
|
[compatibility](compatibility.md) for behaviour and validation boundaries.
|
|
317
|
+
Release [0.2.6](../releases/release-notes-0.2.6.md) adds
|
|
318
|
+
optional Kimi Stop feedback, its doctor checks and Lab preflight diagnostics.
|
|
319
|
+
It also adds reviewed DSH alpha.4 default deletion and Kimi 2.3.0 Bash compatibility.
|
|
320
|
+
Core policy is unchanged; scope and delivery limits are tracked in the
|
|
321
|
+
[maintenance details](../releases/unreleased.md).
|
|
315
322
|
|
|
316
323
|
The milestones below describe historical delivery and future design scope,
|
|
317
324
|
not a committed schedule or a guarantee that new compensation types need no
|
|
@@ -4,18 +4,100 @@ agent-guard's promise is recoverability. A promise is only as good as its
|
|
|
4
4
|
stability over time - this page states exactly what may change and what
|
|
5
5
|
may not, per release class.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
the
|
|
9
|
-
|
|
7
|
+
The stable release line is [0.2.6](../releases/release-notes-0.2.6.md), carrying
|
|
8
|
+
the cumulative RC maintenance and the feedback/diagnostic additions below.
|
|
9
|
+
The opt-in prerelease remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md),
|
|
10
|
+
0.2.5 is the previous stable, and
|
|
11
|
+
[0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
|
|
12
|
+
is an opt-in quarantine protection backport. Versioned sections retain the
|
|
13
|
+
origin and preparation labels of changes introduced by earlier releases.
|
|
10
14
|
|
|
11
15
|
RC3 publishes defensive research and an example around the existing four
|
|
12
16
|
zero-model controls. Experimental disclosure labels and private delegation
|
|
13
17
|
methods are not additions to the Decision Protocol or native-hook contract.
|
|
14
18
|
No production dependency, policy verdict or storage/configuration migration
|
|
15
|
-
is introduced by
|
|
19
|
+
is introduced by the research documentation.
|
|
16
20
|
|
|
17
21
|
## The adapter contract (frozen surface)
|
|
18
22
|
|
|
23
|
+
<a id="unreleased-feedback-and-diagnostic-maintenance"></a>
|
|
24
|
+
|
|
25
|
+
### 0.2.6 feedback and diagnostic maintenance
|
|
26
|
+
|
|
27
|
+
Release [0.2.6](../releases/release-notes-0.2.6.md) adds an opt-in POSIX Kimi
|
|
28
|
+
Stop hook after the existing PreToolUse path. It may request an extra response
|
|
29
|
+
after new compensation records. It does not change the earlier tool result,
|
|
30
|
+
Core verdicts, recovery format or deletion rules; it stores separate local
|
|
31
|
+
emission cursors. Existing PreToolUse setups keep their behavior until Stop
|
|
32
|
+
is explicitly configured. The current example recommends an outer 120-second
|
|
33
|
+
PreToolUse timeout, leaving margin around the existing 90-second guard check.
|
|
34
|
+
|
|
35
|
+
DSH Lab version/config preflight errors gain a JSON diagnostic suffix after
|
|
36
|
+
the stage-specific text, with fixed reason categories, child exit status,
|
|
37
|
+
timing and captured byte counts. The Lab CLI still reports errors on stderr
|
|
38
|
+
and exits 1; normal receipts, supported host versions and the 10/15-second
|
|
39
|
+
budgets retain their contracts. Consumers should not match the entire older
|
|
40
|
+
generic error sentence. Raw host/configuration output is not included.
|
|
41
|
+
The Kimi CLI doctor adds the separate `feedback` result described below.
|
|
42
|
+
An absent optional Stop passes; a configured Stop that fails configuration
|
|
43
|
+
or a requested probe exits 1 and makes drift `BROKEN`. This is an
|
|
44
|
+
upgrade-visible diagnostic change. Existing top-level fields and the
|
|
45
|
+
importable `check_kimi()` wrapper retain PreToolUse scope; Claude output is
|
|
46
|
+
unchanged. Configured Stop fields/helper bytes join the existing fingerprints.
|
|
47
|
+
The runtime fingerprint also includes package metadata, so version changes
|
|
48
|
+
can produce `DRIFTED` against an older baseline. Model delivery remains
|
|
49
|
+
`UNVERIFIED` even after a Bash live sentinel.
|
|
50
|
+
|
|
51
|
+
The Kimi Bash profile also adds exact `2.3.0` alongside `0.42.0` and `2.1.1`
|
|
52
|
+
after bounded prompt-CLI/ACP root-Bash trials. This is a declaration change;
|
|
53
|
+
the Core, adapter and bridge stay unchanged. Unlisted versions remain
|
|
54
|
+
`STALE`; a changed profile fingerprint can make an older baseline `DRIFTED`.
|
|
55
|
+
The separately pinned 2.1.1 Lab helper and subagent coverage do not expand.
|
|
56
|
+
See the [2.3.0 evidence](../reports/test-report-kimi-code-block.md#kimi-230-acceptance).
|
|
57
|
+
|
|
58
|
+
The later DSH compatibility work adds `0.2.1-alpha.4` to the default deletion
|
|
59
|
+
adapter alongside the two existing exact versions. Top-level engines and an
|
|
60
|
+
optional DSH peer align with the nested declaration, so the reviewed loaders
|
|
61
|
+
can enforce the list. This installs no production dependency and changes no
|
|
62
|
+
Core policy. Optional native-read fingerprints and Lab host formats remain
|
|
63
|
+
separately pinned. See [DSH compatibility](dsh-compatibility.md) and the
|
|
64
|
+
[native report](../reports/test-report-dsh-alpha4.md).
|
|
65
|
+
|
|
66
|
+
The maintainer selected 0.2.6 for this bounded feedback/diagnostic maintenance;
|
|
67
|
+
the additive surfaces below are carried as an explicit maintenance-version
|
|
68
|
+
exception. This does not relax the general minor-release rules or authorize
|
|
69
|
+
Core policy changes. These additions are absent from published 0.2.5.
|
|
70
|
+
|
|
71
|
+
### 0.2.5 feedback maintenance
|
|
72
|
+
|
|
73
|
+
Deletion rules, wildcard refusal, Decision/reason codes, CLI flags and exit
|
|
74
|
+
roles retain their contracts. `ALLOW_NOOP` receives a clearer explanation;
|
|
75
|
+
human check output displays explanations. Optional `storage_notice`/`gc`
|
|
76
|
+
metadata describes actual retained files and maintenance commands without
|
|
77
|
+
entering the shared audit payload. Status gains a local-versus-host notice.
|
|
78
|
+
|
|
79
|
+
The DSH adapter now checks local Python/checker imports before registration
|
|
80
|
+
and reports startup failure explicitly rather than returning silently when
|
|
81
|
+
shell/script dependencies are missing. This changes plugin lifecycle
|
|
82
|
+
diagnostics, not the Core policy or the host's ability to continue other
|
|
83
|
+
tools. Python must also be available on the plugin process PATH for this
|
|
84
|
+
startup probe. Its scope is the plugin process; live interception remains
|
|
85
|
+
`UNVERIFIED`. Status adds adapter facts and static runtime diagnostics.
|
|
86
|
+
Failed status queries return `ok: false`, `report: null` and `STATUS_*`
|
|
87
|
+
diagnostics for execution failure, timeout, unsuccessful exit or unusable
|
|
88
|
+
reports. Partial relocation failures preserve the existing failure/exit
|
|
89
|
+
semantics and expose their transaction IDs and retained-storage guidance.
|
|
90
|
+
No storage/configuration migration, new dependency or rm execution route is
|
|
91
|
+
introduced. Details are in the [feedback guide](../guides/recovery-feedback.md).
|
|
92
|
+
|
|
93
|
+
The maintainer selected 0.2.5 for the cumulative RC1–RC3 maintenance and this
|
|
94
|
+
feedback work. It carries forward the bounded RC1 maintenance exception
|
|
95
|
+
documented below. Quarantine control-path refusals inherited from RC1 and
|
|
96
|
+
explicit DSH initialization failure are upgrade-visible changes. This choice
|
|
97
|
+
does not permit unrelated verdict changes under the patch versioning rules.
|
|
98
|
+
|
|
99
|
+
### Existing decision surface
|
|
100
|
+
|
|
19
101
|
Harness adapters integrate against exactly four things:
|
|
20
102
|
|
|
21
103
|
1. **Decision classes** - `ALLOW`, `SANITIZE`, `RELOCATE`, `SNAPSHOT`,
|
|
@@ -82,6 +164,7 @@ must accept the additional refusal reason and ignore unknown optional fields.
|
|
|
82
164
|
| `.agent-guard/exfil-allow.toml` exemption file | minor | Read from the workspace root only; values exempted by `sha256:...`, never by value |
|
|
83
165
|
| `doctor.py --check-drift` report and adapter `compatibility.json` profiles | minor | Additive local preflight. Without drift flags the doctor keeps its previous process-execution and exit behavior; `CURRENT` never promotes live interception above `UNVERIFIED` |
|
|
84
166
|
| `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
|
|
167
|
+
| Kimi doctor `feedback` object (0.2.6) | additive diagnostic | Existing top-level fields retain PreToolUse scope; optional Stop has separate configuration/local results and always-unverified model delivery. Absent Stop passes; a configured Stop failure exits 1 and prevents baseline creation/live sentinel. Configured Stop fields/helper join drift fingerprints. `check_kimi()` retains its PreToolUse-only contract; Claude output is unchanged. |
|
|
85
168
|
| Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
|
|
86
169
|
|
|
87
170
|
### 0.2.5-rc1 assessment contract clarification (source candidate)
|