@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
@@ -6,9 +6,10 @@ native Windows harness execution remains unverified. POSIX hook bridges have
6
6
  their own platform requirements. See the
7
7
  [compatibility contract](../../../docs/design/compatibility.md).
8
8
 
9
- This reference covers the 0.2.5-rc3 source candidate, retaining RC1 maintenance
10
- and shared audit metadata projection. The published 0.2.4 baseline lacks the RC's
11
- control-path, GC and audit-writer maintenance.
9
+ This reference covers 0.2.5, retaining RC1–RC3
10
+ maintenance and shared audit metadata projection. The original published
11
+ 0.2.4 baseline lacks the RC's control-path, GC and audit-writer maintenance;
12
+ the opt-in 0.2.4-hotfix.1 backports only control-path protection.
12
13
 
13
14
  ## Decision Protocol
14
15
 
@@ -34,6 +35,12 @@ RESTRICTED prohibitions) are policy violations and never askable.
34
35
 
35
36
  check.py exit codes: 0 proceed/advisory-ok · 2 blocked · 3 ask · 1 error.
36
37
 
38
+ The 0.2.5 feedback maintenance changes explanations and optional
39
+ result metadata, not this decision table. `ALLOW_NOOP` means no recovery
40
+ action for recognized operations; it does not establish that unrecognized
41
+ commands are harmless. Human check output now includes the explanation.
42
+ See [status and cleanup feedback](../../../docs/guides/recovery-feedback.md).
43
+
37
44
  ### Assessment and dry-run side effects
38
45
 
39
46
  Advisory `check.py` and `safe_delete.py --dry-run` keep command targets
@@ -174,6 +181,12 @@ Retention/GC is intentionally manual in V1; `restore.py list` distinguishes
174
181
 
175
182
  ## Retention / GC (B4)
176
183
 
184
+ Successful relocations report retained storage and GC commands; enforced
185
+ partial relocations retain their failed outcome and recovery association.
186
+ The same working directory and workspace/trash environment settings must be
187
+ used for maintenance. The `gc` command hints are optional result metadata,
188
+ not new audit fields, automatic execution, or permission to purge.
189
+
177
190
  Soft policy: 30-day retention, 5 GiB cap. Thresholds only MARK transactions
178
191
  `GC_ELIGIBLE` (oldest first under the cap); purging is an explicit
179
192
  `gc.py --execute` maintenance action. Lifecycle is fully audited:
@@ -31,6 +31,7 @@ import _bootstrap # noqa: F401
31
31
 
32
32
  from core import AUDIT_NAME, TRASH_DIRNAME
33
33
  from core import audit, classifier, dialects, policy, recovery
34
+ from core.messages import QUARANTINE_NOTICE, gc_guidance, print_gc_guidance
34
35
 
35
36
 
36
37
  _REDACTED_COMMAND = "<redacted>"
@@ -165,13 +166,25 @@ def main() -> int:
165
166
 
166
167
  def finish(code):
167
168
  out["exit"] = code
169
+ retained = [item for item in out.get("compensations", [])
170
+ if item["strategy"] in ("relocate", "clean-enumerate")
171
+ and item.get("moved", 0) > 0]
172
+ if retained:
173
+ out["storage_notice"] = QUARANTINE_NOTICE
174
+ out["gc"] = gc_guidance()
168
175
  if args.as_json:
169
176
  print(json.dumps(out, ensure_ascii=False, indent=2))
170
177
  else:
171
178
  summary = f"{out['decision']} [{out['code']}]"
172
179
  print(summary)
180
+ print(out["explanation"])
173
181
  for reason in out["reasons"][:4]:
174
182
  print(f" - {reason}")
183
+ for item in retained:
184
+ print(f" retained: {item['moved']} target(s), txid={item['txid']}")
185
+ if retained:
186
+ print(out["storage_notice"])
187
+ print_gc_guidance(out["gc"])
175
188
  return code
176
189
 
177
190
  def record(entry, required=False):
@@ -31,6 +31,7 @@ import _bootstrap # noqa: F401
31
31
 
32
32
  from core import AUDIT_NAME, TRASH_DIRNAME, audit
33
33
  from core import classifier, recovery
34
+ from core.messages import gc_guidance, print_gc_guidance
34
35
 
35
36
 
36
37
  def main() -> int:
@@ -52,7 +53,7 @@ def main() -> int:
52
53
  plan = engine.gc_plan()
53
54
 
54
55
  if not args.execute:
55
- payload = {"mode": "plan", **plan}
56
+ payload = {"mode": "plan", **plan, "gc": gc_guidance()}
56
57
  if args.as_json:
57
58
  print(json.dumps(payload, ensure_ascii=False, indent=2))
58
59
  else:
@@ -63,7 +64,8 @@ def main() -> int:
63
64
  f"{entry['bytes']}B {entry['items']} items")
64
65
  if not plan["eligible"]:
65
66
  print(" nothing eligible")
66
- print("(dry plan; pass --execute to purge)")
67
+ print("Dry plan. No recovery copies were removed.")
68
+ print_gc_guidance(payload["gc"])
67
69
  return 0
68
70
 
69
71
  txids = list(args.txid)
@@ -25,6 +25,7 @@ import _bootstrap # noqa: F401
25
25
 
26
26
  from core import AUDIT_NAME, TRASH_DIRNAME, audit
27
27
  from core import classifier, policy, recovery
28
+ from core.messages import QUARANTINE_NOTICE, gc_guidance, print_gc_guidance
28
29
 
29
30
 
30
31
  def expand_globs(patterns):
@@ -80,6 +81,16 @@ def safe_delete_audit_event(event, decision, code, target_count, *,
80
81
  return entry
81
82
 
82
83
 
84
+ def print_result(result, as_json):
85
+ if as_json:
86
+ print(json.dumps(result, ensure_ascii=False, indent=2))
87
+ return
88
+ print(result["outcome"] + (f" txid={result['txid']}" if result.get("txid") else ""))
89
+ if "storage_notice" in result:
90
+ print(result["storage_notice"])
91
+ print_gc_guidance(result["gc"])
92
+
93
+
83
94
  def main() -> int:
84
95
  ap = argparse.ArgumentParser(description=__doc__)
85
96
  ap.add_argument("paths", nargs="+", help="paths or globs to delete")
@@ -216,6 +227,12 @@ def main() -> int:
216
227
  report = engine.relocate(specs, meta={
217
228
  "tool": "safe_delete", "code": verdict.code})
218
229
  relocation_report = report
230
+ result["txid"] = report["txid"]
231
+ result["moved"] = report["moved"]
232
+ result["skipped"] = report["skipped"]
233
+ if report["moved"]:
234
+ result["storage_notice"] = QUARANTINE_NOTICE
235
+ result["gc"] = gc_guidance()
219
236
  if report.get("storage_failure"):
220
237
  # Hard principle: capacity limits never downgrade to deletion.
221
238
  result["verdict"] = {
@@ -229,8 +246,7 @@ def main() -> int:
229
246
  record(safe_delete_audit_event(
230
247
  "decision", "BLOCK", policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
231
248
  len(specs), report=report))
232
- print(json.dumps(result, ensure_ascii=False, indent=2)
233
- if args.as_json else result["outcome"])
249
+ print_result(result, args.as_json)
234
250
  return 2
235
251
  if report.get("skipped"):
236
252
  result["verdict"] = {
@@ -243,20 +259,13 @@ def main() -> int:
243
259
  }
244
260
  result["outcome"] = (
245
261
  "BLOCKED: partial relocation remains recoverable")
246
- result["txid"] = report["txid"]
247
- result["moved"] = report["moved"]
248
- result["skipped"] = report["skipped"]
249
262
  result["exit"] = 2
250
263
  record(safe_delete_audit_event(
251
264
  "decision", "BLOCK", policy.CODE_BLOCK_COMPENSATION_FAILED,
252
265
  len(specs), report=report))
253
- print(json.dumps(result, ensure_ascii=False, indent=2)
254
- if args.as_json else result["outcome"])
266
+ print_result(result, args.as_json)
255
267
  return 2
256
268
  result["outcome"] = "relocated to quarantine"
257
- result["txid"] = report["txid"]
258
- result["moved"] = report["moved"]
259
- result["skipped"] = report["skipped"]
260
269
 
261
270
  if not args.dry_run and verdict.code != policy.CODE_ALLOW_NOOP:
262
271
  record(safe_delete_audit_event(
@@ -264,10 +273,7 @@ def main() -> int:
264
273
  phase="complete", report=relocation_report,
265
274
  outcome=result.get("outcome")))
266
275
  result["exit"] = 0
267
- if args.as_json:
268
- print(json.dumps(result, ensure_ascii=False, indent=2))
269
- else:
270
- print(result["outcome"] + (f" txid={result['txid']}" if result.get("txid") else ""))
276
+ print_result(result, args.as_json)
271
277
  return 0
272
278
 
273
279
 
@@ -16,6 +16,8 @@ import _bootstrap # noqa: F401
16
16
 
17
17
  from core import AUDIT_NAME, TRASH_DIRNAME
18
18
  from core import audit, classifier, policy, recovery
19
+ from core.messages import (
20
+ HOST_STATUS_NOTICE, QUARANTINE_NOTICE, gc_guidance, print_gc_guidance)
19
21
 
20
22
 
21
23
  def main() -> int:
@@ -113,6 +115,9 @@ def main() -> int:
113
115
  "guard_snapshots": stash_count,
114
116
  "decisions": decision_stats(engine.trash_root),
115
117
  "recent_audit": audit_tail(engine.trash_root, args.tail),
118
+ "host_status_notice": HOST_STATUS_NOTICE,
119
+ "storage_notice": QUARANTINE_NOTICE,
120
+ "gc": gc_guidance(),
116
121
  }
117
122
  if args.as_json:
118
123
  print(json.dumps(info, ensure_ascii=False, indent=2))
@@ -123,6 +128,7 @@ def main() -> int:
123
128
  + (f" (since {info['mode_since']} by {info['mode_set_by']})"
124
129
  if info["mode_since"] else ""))
125
130
  print(f"quarantine: {trash_root}")
131
+ print(info["host_status_notice"])
126
132
  print(f"usage : {usage['files']} files, {usage['bytes']} bytes, "
127
133
  f"{usage['transactions']} transactions "
128
134
  f"({usage['restorable_transactions']} restorable)")
@@ -131,6 +137,9 @@ def main() -> int:
131
137
  print(f"retention : soft {ret['soft_days']}d / "
132
138
  f"{ret['soft_limit_bytes'] // (1024**3)}GiB; "
133
139
  f"{len(ret['gc_eligible'])} GC-eligible")
140
+ print(info["storage_notice"])
141
+ print("GC is manual; age and size thresholds do not trigger deletion.")
142
+ print_gc_guidance(info["gc"])
134
143
  stats = info["decisions"]
135
144
  if stats:
136
145
  print(f"decisions : {top_codes(stats)}")