@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.5

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.
@@ -32,15 +32,15 @@ enforces and how to work with it productively. The four pillars:
32
32
 
33
33
  ```bash
34
34
  # delete explicit targets; valuable content is quarantined:
35
- python3 <repo>/skills/delete-guard/scripts/safe_delete.py src/old_module.py
36
- python3 <repo>/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
35
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
36
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
37
37
 
38
38
  # undo a transaction (list first if unsure):
39
- python3 <repo>/skills/delete-guard/scripts/restore.py list
40
- python3 <repo>/skills/delete-guard/scripts/restore.py <txid>
39
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
40
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py '<txid>'
41
41
 
42
42
  # current guard state:
43
- python3 <repo>/skills/delete-guard/scripts/status.py
43
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py
44
44
  ```
45
45
 
46
46
  Globs passed to `safe_delete` are expanded explicitly before anything moves.
@@ -54,7 +54,9 @@ can receive:
54
54
 
55
55
  | Verdict | Meaning | Your move |
56
56
  |---|---|---|
57
- | `ALLOW` (harness may show `PROCEED`) | safe as-is or compensation already applied | continue; record and verify any `txid` |
57
+ | `ALLOW` | no recovery action for recognized operations; unrecognized effects are unchecked | continue only within the authorized scope; do not infer that scripts or overwrites are safe |
58
+ | `RELOCATE` / `SNAPSHOT` (harness may show `PROCEED` after compensation) | quarantine or tracked Git snapshot required | record and verify the resulting `txid` before continuing |
59
+ | `ASK` | this understood operation needs single-execution approval | use the host's human approval path; if unavailable, stop or split the command |
58
60
  | `BLOCK_UNDETERMINABLE_EFFECT` | targets unresolvable (`$VAR`, `bash -c`, `find -delete`, `xargs`) | restate with explicit paths, or use `safe_delete` |
59
61
  | `BLOCK_WILDCARD` | glob target set is opaque | use `safe_delete` with the glob |
60
62
  | `BLOCK_OUT_OF_WORKSPACE` / `BLOCK_PROTECTED_PATH` / `BLOCK_PROTECTED_ANCESTOR` | outside boundary, workspace root, `.git`, or a filesystem root (`/`, `/home`, `/usr`, `$HOME`) | do not retry; this is a hard boundary. Ask the human if it is truly needed |
@@ -63,8 +65,10 @@ can receive:
63
65
 
64
66
  Shape rules on compound commands: a single line that `cd`s anywhere before a
65
67
  destructive op (F1), or that creates files (`touch/mkdir/cp/mv/tee`,
66
- redirections) before destroying them (F2), is refused as undeterminable.
67
- Run deletions as standalone commands with an explicit workdir.
68
+ redirections) before destroying them (F2), can return `ASK` when its targets
69
+ are resolvable and within policy boundaries. Unresolvable effects and hard
70
+ boundaries still return `BLOCK`; hosts without a usable approval path deny
71
+ the `ASK` call. Run deletions as standalone commands with an explicit workdir.
68
72
 
69
73
  A block is not an error to route around. Retrying the same operation in a
70
74
  disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
@@ -117,13 +121,26 @@ uses opaque session correlation and limits status/GC metadata; see the
117
121
 
118
122
  ## Quarantine location queries
119
123
 
124
+ In 0.2.5, deletion/status results explain
125
+ retained storage and include GC commands. Moving files to quarantine keeps
126
+ their data on disk. Review the plan before choosing `--execute --all-eligible`
127
+ or a specific `--execute --txid`; use the same working directory and workspace/
128
+ trash settings. Age/size thresholds do not perform automatic cleanup.
129
+
130
+ `status.py` reports local recovery data and does not verify host activation.
131
+ DSH's status tool separately reports the plugin process startup check and
132
+ listener registration, with live interception still `UNVERIFIED`. A missing
133
+ plugin cannot supply its own status tool. `ALLOW_NOOP` does not certify
134
+ unrecognized script/interpreter effects. See the
135
+ [feedback guide](../../docs/guides/recovery-feedback.md).
136
+
120
137
  When the user asks where quarantines are or how many exist, use the shared
121
138
  read-only query with a current-directory or user-selected scope:
122
139
 
123
140
  ```bash
124
- python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --json
125
- python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --root <projects> --max-depth 3 --json
126
- python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --trash <custom-store> --json
141
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --json
142
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --root /absolute/path/to/projects --max-depth 3 --json
143
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/status.py --trash-index --trash /absolute/path/to/custom-store --json
127
144
  ```
128
145
 
129
146
  Report the scope, candidate count, metadata-identified count and read/budget
@@ -137,10 +154,10 @@ read just to answer a location/count question.
137
154
 
138
155
  ## RESTRICTED mode
139
156
 
140
- RC2 and RC3 retain RC1 protection for the quarantine root, root manifest,
157
+ Version 0.2.5 retains RC1 protection for the quarantine root, root manifest,
141
158
  audit/state files, state temp file, sessions tree and storage access parents.
142
159
  Housekeeping does not override those checks. Use the existing explicit
143
- `gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
160
+ `gc.py --execute --txid '<txid>'` entry for a validated, audited transaction purge.
144
161
  Ordinary unprotected payload housekeeping retains its existing policy.
145
162
  GC plans omit `PURGED` history; they do not delete stored Git stashes.
146
163
 
@@ -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)}")