@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +64 -34
  2. package/README.zh-CN.md +53 -27
  3. package/SECURITY.md +5 -3
  4. package/adapters/INTEGRATION.md +84 -10
  5. package/adapters/claude/README.md +6 -0
  6. package/adapters/dsh/README.md +51 -7
  7. package/adapters/dsh/compatibility.json +14 -0
  8. package/adapters/dsh/harness/README.md +11 -0
  9. package/adapters/dsh/harness/guard_lab.py +42 -14
  10. package/adapters/dsh/lib/index.js +127 -33
  11. package/adapters/kimi-code/README.md +154 -14
  12. package/adapters/kimi-code/compatibility.json +1 -1
  13. package/adapters/kimi-code/config.example.toml +18 -6
  14. package/adapters/kimi-code/hook_bridge.sh +19 -4
  15. package/adapters/kimi-code/pre_tool_use.py +1 -1
  16. package/adapters/kimi-code/stop_feedback.py +237 -0
  17. package/core/messages.py +40 -0
  18. package/core/policy.py +2 -1
  19. package/docs/README.md +30 -8
  20. package/docs/design/architecture.md +13 -6
  21. package/docs/design/compatibility.md +87 -4
  22. package/docs/design/dsh-compatibility.md +65 -0
  23. package/docs/design/threat-model.md +2 -2
  24. package/docs/guides/getting-started.md +76 -17
  25. package/docs/guides/harness-capabilities.md +24 -5
  26. package/docs/guides/host-drift.md +32 -0
  27. package/docs/guides/recovery-feedback.md +126 -0
  28. package/docs/history/friction.md +21 -1
  29. package/docs/lab/blue-team-calibration.md +1 -1
  30. package/docs/lab/guard-lab.md +6 -2
  31. package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
  32. package/docs/releases/release-notes-0.2.5.md +123 -0
  33. package/docs/releases/release-notes-0.2.6.md +167 -0
  34. package/docs/releases/unreleased.md +141 -0
  35. package/docs/reports/test-report-dsh-alpha4.md +102 -0
  36. package/docs/reports/test-report-kimi-code-block.md +119 -6
  37. package/doctor.py +175 -28
  38. package/package.json +11 -2
  39. package/skills/delete-guard/SKILL.md +30 -13
  40. package/skills/delete-guard/references/policy.md +16 -3
  41. package/skills/delete-guard/scripts/check.py +13 -0
  42. package/skills/delete-guard/scripts/gc.py +4 -2
  43. package/skills/delete-guard/scripts/safe_delete.py +20 -14
  44. package/skills/delete-guard/scripts/status.py +9 -0
@@ -1,7 +1,8 @@
1
1
  # Kimi Code adapter - agent-guard
2
2
  #
3
- # Append to ~/.kimi-code/config.toml. Hooks are read at session start, so
4
- # restart the session after editing.
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
- timeout = 90
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: surface the raw Core verdict on stderr for troubleshooting.
25
- # [experimental]
26
- # agent_guard_debug = true
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 [ "$#" -ne 1 ]; then
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/pre_tool_use.py"
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); refusing tool call\n' "$status" >&2
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 = 90
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)
@@ -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: "Nothing to delete; command may run unchanged.",
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
- Published RC baseline: [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md).
11
- Published stable baseline: [0.2.4](releases/release-notes-0.2.4.md).
12
- Source candidate: [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), with
13
- [blue-team research](research/README.md) and a [four-control example](lab/blue-team-calibration.md).
14
- Evaluate the source preview through a reviewed checkout or tarball;
15
- GitHub/npm package publication needs separate versioned receipts.
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) | 所测版本的 Bash BLOCK 与故障路径 |
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.5-rc3](releases/release-notes-0.2.5-rc3.md) | 蓝队研究/文档源码候选与零模型示例;包发布另行核查 |
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 current source candidate is 0.2.5-rc3; stable 0.2.4 and published RC2 remain
309
- baselines. It retains the recovery, shared audit and observer maintenance,
310
- and adds [defensive research](../research/README.md) plus an example using the
311
- existing zero-model controls. Private research methods do not add a general
312
- authorization service or new production enforcement point.
313
- See [candidate notes](../releases/release-notes-0.2.5-rc3.md) and
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
- Current source candidate is [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md);
8
- the published RC baseline is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md).
9
- Versioned sections retain the origin of changes introduced by earlier releases.
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 this preparation.
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)