@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2

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 (38) hide show
  1. package/README.md +166 -573
  2. package/README.zh-CN.md +138 -489
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +4 -2
  5. package/adapters/dsh/README.md +7 -0
  6. package/assets/linux-do-community.svg +19 -0
  7. package/core/audit.py +170 -25
  8. package/core/classifier.py +25 -1
  9. package/core/lab.py +77 -7
  10. package/core/policy.py +17 -9
  11. package/core/recovery.py +5 -1
  12. package/core/redaction.py +122 -21
  13. package/docs/README.md +18 -5
  14. package/docs/design/architecture.md +25 -6
  15. package/docs/design/compatibility.md +106 -1
  16. package/docs/design/threat-model.md +6 -4
  17. package/docs/guides/audit-metadata.md +77 -0
  18. package/docs/guides/getting-started.md +106 -0
  19. package/docs/guides/harness-capabilities.md +5 -0
  20. package/docs/history/friction.md +85 -0
  21. package/docs/lab/guard-lab.md +15 -1
  22. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  23. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  24. package/guard_lab.py +11 -0
  25. package/package.json +4 -2
  26. package/skills/delete-guard/SKILL.md +45 -7
  27. package/skills/delete-guard/references/policy.md +90 -4
  28. package/skills/delete-guard/scripts/check.py +3 -0
  29. package/skills/delete-guard/scripts/gc.py +18 -3
  30. package/skills/delete-guard/scripts/restore.py +22 -7
  31. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  32. package/skills/delete-guard/scripts/status.py +9 -7
  33. package/skills/exfil-guard/SKILL.md +23 -11
  34. package/skills/exfil-guard/references/channels.md +8 -1
  35. package/skills/exfil-guard/references/rules.md +86 -6
  36. package/skills/exfil-guard/scripts/_payload.py +20 -0
  37. package/skills/exfil-guard/scripts/check_span.py +5 -1
  38. package/skills/exfil-guard/scripts/sanitize.py +6 -3
@@ -1,6 +1,14 @@
1
1
  # delete-guard policy reference (V1)
2
2
 
3
- Platforms: Linux/macOS shells + git. Windows (cmd/PowerShell) is out of V1.
3
+ The shared Core supports POSIX/cmd/PowerShell command facts. Full suites run
4
+ on Linux/macOS; focused Windows Core evidence is available, while complete
5
+ native Windows harness execution remains unverified. POSIX hook bridges have
6
+ their own platform requirements. See the
7
+ [compatibility contract](../../../docs/design/compatibility.md).
8
+
9
+ This reference covers the 0.2.5-rc2 source candidate, including 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.
4
12
 
5
13
  ## Decision Protocol
6
14
 
@@ -25,6 +33,41 @@ RESTRICTED prohibitions) are policy violations and never askable.
25
33
 
26
34
  check.py exit codes: 0 proceed/advisory-ok · 2 blocked · 3 ask · 1 error.
27
35
 
36
+ ### Assessment and dry-run side effects
37
+
38
+ Advisory `check.py` and `safe_delete.py --dry-run` keep command targets
39
+ unchanged. They do not execute the assessed shell text, relocate targets,
40
+ create Git stashes or create recovery transactions. They may still write
41
+ metadata through their existing best-effort audit path:
42
+
43
+ | Invocation | Exit / target behavior | Possible metadata writes |
44
+ |---|---|---|
45
+ | Advisory `check.py`, including ALLOW, ASK or BLOCK | Exit 0 with the actual decision; targets unchanged | Layout initialization and an appended `check` audit |
46
+ | `safe_delete.py --dry-run` with concrete targets, including absent literals | Exit 0 unless BLOCK; targets unchanged | An advisory audit, or a blocked-decision audit |
47
+ | Policy-blocked `safe_delete.py` before compensation, including dry-run | Exit 2; targets unchanged | Best-effort blocked-decision audit |
48
+ | Unmatched-glob-only `safe_delete.py` | Exit 0 before layout/audit setup | None from that invocation |
49
+ | Non-dry-run `safe_delete.py` with an absent literal / ALLOW_NOOP | Exit 0 without mutation or layout setup | None from that invocation |
50
+
51
+ Layout initialization may create the selected quarantine directory and
52
+ `audit.jsonl`. If a quarantine inside a Git workspace is not already ignored,
53
+ it may append an ignore entry to Git's local `info/exclude`, including the
54
+ resolved exclude path of a linked worktree. It does not edit tracked
55
+ `.gitignore`. A preexisting ignore rule or an external bucket avoids that
56
+ exclude write. Repeated checks append audit lines without duplicating the
57
+ exclude rule; recovery manifests and authorization state are not created by
58
+ these assessment paths. Git status may hide metadata that was previously
59
+ untracked, so an unchanged Git status alone does not prove zero writes.
60
+
61
+ If audit/layout setup fails, assessments retain their decision and report
62
+ an audit warning; partial metadata changes may remain. `ensure_layout`
63
+ establishes the Git ignore rule before creating the bucket. Audit failure
64
+ after that step does not roll it back. This best-effort behavior is distinct
65
+ from enforced execution/ASK intents, which must be durable or execution is
66
+ refused. Advisory exit 0 must never be treated as authorization to run a
67
+ BLOCK or ASK command. Failed real compensations can leave partial target
68
+ changes and recovery IDs; this table does not promise rollback for them.
69
+ No general zero-write assessment flag is introduced.
70
+
28
71
  ### Dialects
29
72
 
30
73
  `check.py` lexes the command line for a shell dialect: `--dialect posix`
@@ -46,6 +89,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
46
89
 
47
90
  ## Rule table (first match wins)
48
91
 
92
+ The quarantine control-path changes below were introduced in 0.2.5-rc1;
93
+ the published 0.2.4 artifact retains its original housekeeping order.
94
+
49
95
  | # | Condition | Verdict code | Effect |
50
96
  |---|---|---|---|
51
97
  | 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
@@ -53,9 +99,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
53
99
  | 2a | SHAPE F1: destructive op preceded by `cd` in the same command line, target in-workspace and resolvable | `ASK` (`COMPOUND_CWD_DELETE`) | single-execution authorization; splitting the command avoids the prompt. A shape rule describes *compensation* difficulty, never effect scope: if the target set also trips rule 2, 4, 5 or 6, that BLOCK wins (`tests/test_incident_regression.py`) |
54
100
  | 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; force-push is refused separately. Hard reset in a compound line is effect-uncertain and BLOCKED before shape rules |
55
101
  | 2c | target *is* a filesystem root (`/`, `/home`, `/usr`, `/etc`, `/var`, `/tmp`, `/opt`, `/boot`, `$HOME`, ...) | `BLOCK_PROTECTED_ANCESTOR` | refuse. Matched exactly, so paths *under* these roots keep the ordinary codes; enforced by identity rather than workspace geometry, so it holds even when the workspace is `/` |
56
- | 3 | any target inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | direct delete permitted (housekeeping) |
102
+ | 5 | workspace root, `.git` metadata, quarantine root/control paths, or an in-workspace parent containing configured storage | `BLOCK_PROTECTED_PATH` | refuse before the housekeeping exemption; root manifest/audit/state, state temp and sessions are control paths |
103
+ | 3 | explicit ordinary unprotected payload inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | opaque globs BLOCK_WILDCARD; safe_delete may enumerate first, and an audited transaction purge uses gc.py --execute |
57
104
  | 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
58
- | 5 | target is workspace root or `.git` (any depth) | `BLOCK_PROTECTED_PATH` | refuse |
59
105
  | 6 | any glob target | `BLOCK_WILDCARD` | refuse; use safe_delete which enumerates |
60
106
  | 7 | RESTRICTED mode, git/remote destructive op | `BLOCK_RESTRICTED_MODE` | refuse |
61
107
  | 8 | RESTRICTED mode, fs delete | narrow files only -> `RELOCATE_NARROW`, else `BLOCK_RESTRICTED_MODE` | refuse or quarantine |
@@ -100,7 +146,7 @@ a portable fallback.
100
146
  |---|---|
101
147
  | `AGENT_GUARD_WORKSPACE` | override workspace boundary discovery |
102
148
  | `AGENT_GUARD_TRASH` | override quarantine location |
103
- | `AGENT_GUARD_SESSION` | session identity recorded in audit/manifest |
149
+ | `AGENT_GUARD_SESSION` | selects session authorization state; RC2 audit metadata uses opaque correlation |
104
150
  | `AGENT_GUARD_ARTIFACTS` | `os.pathsep`-joined extra artifact patterns |
105
151
  | `AGENT_GUARD_ALLOW_REGENERABLE` | `0` disables direct deletion of artifacts |
106
152
 
@@ -133,6 +179,46 @@ Soft policy: 30-day retention, 5 GiB cap. Thresholds only MARK transactions
133
179
  `QUARANTINED -> RESTORABLE -> GC_ELIGIBLE -> PURGED`; the audit log itself
134
180
  is never garbage-collected.
135
181
 
182
+ Local maintenance excludes `PURGED` tombstones from active GC inventory and
183
+ age/capacity plans. History remains in the manifest and transaction listing;
184
+ a directory recreated under a purged ID is unmanaged. Failed purges retain
185
+ their prior state and can still be planned. This does not add stash pruning.
186
+
187
+ Restore audit metadata now records `restored_count`, `conflict_count` and
188
+ `error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
189
+ `ok` and preservation `backup_txids` retain correlation; invalid/unknown input
190
+ IDs use `txid_sha256`. Exact restoration paths and errors remain in the
191
+ recovery journal and CLI result. Historical audit lines are not rewritten.
192
+ At released RC1, automatic session/generic handling is unchanged; the RC2
193
+ [shared projection](../../../docs/guides/audit-metadata.md) extends it.
194
+
195
+ ### safe_delete audit metadata
196
+
197
+ New `safe_delete` audit events keep `event`, `tool`, `decision`, `code` and
198
+ `target_count`, plus `phase`/static `outcome` where applicable. Established
199
+ relocation reports add `txid`, `moved_count` and `skipped_count`, including
200
+ partial relocation and storage-failure decisions. `target_count` counts
201
+ classified entries after glob expansion, including absent literals and
202
+ unresolved/rejected entries in a BLOCK assessment; it is not a count of
203
+ existing or deletable files. Unmatched patterns are excluded; duplicate
204
+ input entries remain separate entries.
205
+ `skipped_count` counts the engine's skipped entries, not every target left
206
+ unmoved after a storage failure.
207
+
208
+ Target arrays, policy reason bodies, free-form `--reason` and moved/skipped
209
+ payloads are not copied into these events. `--reason` remains accepted but
210
+ its text is no longer persisted in the audit or `tx-start.meta`. Exact
211
+ origin/trash paths, write-ahead relocation records and failure diagnostics
212
+ stay in the recovery manifest; CLI target/recovery paths and errors stay
213
+ accurate. Those surfaces can still contain sensitive text.
214
+
215
+ Mutation intents remain durable before deletion; assessment and outcome
216
+ audits retain their existing best-effort behavior. Historical audit lines
217
+ and manifest metadata are not rewritten. At released RC1, automatic session
218
+ and generic append/tail handling is unchanged. The later unreleased
219
+ [shared projection](../../../docs/guides/audit-metadata.md) limits these fields
220
+ and legacy reads, while raw historical files and recovery surfaces remain.
221
+
136
222
  Authority model: `gc.py --execute` is intentionally permitted
137
223
  non-interactively (scheduled maintenance is legitimate; purging
138
224
  already-quarantined evidence is lower-risk than capability escalation,
@@ -6,6 +6,9 @@
6
6
 
7
7
  Advisory mode (default): prints the verdict and does not mutate command
8
8
  targets. It records the assessment when audit storage is available.
9
+ Audit setup may create the quarantine, append audit.jsonl, and add a Git
10
+ local exclude rule. Advisory exit 0 is not execution authorization; inspect
11
+ the decision. It creates no relocation, snapshot or recovery transaction.
9
12
  --enforce: performs the compensations first (relocate targets / git snapshot
10
13
  / git-clean enumeration+relocation) and tells the caller to PROCEED, or
11
14
  refuses with BLOCKED. Any BLOCK in the line means nothing is executed.
@@ -22,6 +22,7 @@ CODE_RELOCATE_FAILED_STORAGE.
22
22
  from __future__ import annotations
23
23
 
24
24
  import argparse
25
+ import hashlib
25
26
  import json
26
27
  import os
27
28
  import sys
@@ -76,13 +77,27 @@ def main() -> int:
76
77
  # Preflight both identity and audit durability before irreversible purge.
77
78
  # A failed final receipt still leaves this intent plus manifest tombstones.
78
79
  engine.validate_gc_targets(txids)
79
- audit.append({"event": "gc-intent", "txids": txids},
80
+ known = engine.transactions()
81
+
82
+ def selection_metadata(selected):
83
+ return {
84
+ "txids": [txid for txid in selected if txid in known],
85
+ "missing_txid_sha256": [hashlib.sha256(
86
+ txid.encode("utf-8", errors="surrogatepass")).hexdigest()
87
+ for txid in selected if txid not in known],
88
+ }
89
+
90
+ audit.append({"event": "gc-intent", "target_count": len(txids),
91
+ **selection_metadata(txids)},
80
92
  os.path.join(trash_root, AUDIT_NAME))
81
93
  report = engine.gc_execute(txids)
94
+ missing = selection_metadata(report["missing"])
82
95
  audit.append({"event": "gc", "action": "PURGED",
83
- "purged": report["purged"], "missing": report["missing"],
96
+ "purged": report["purged"], "missing": missing["txids"],
97
+ "missing_count": len(report["missing"]),
98
+ "missing_txid_sha256": missing["missing_txid_sha256"],
84
99
  "plan_reasons": {e["txid"]: e["reason"]
85
- for e in plan["eligible"]}},
100
+ for e in plan["eligible"] if e["txid"] in txids}},
86
101
  os.path.join(trash_root, AUDIT_NAME))
87
102
  if args.as_json:
88
103
  print(json.dumps({"mode": "execute", **report}, ensure_ascii=False,
@@ -11,6 +11,7 @@ transaction before restoring. Inspect backup_txids after success or failure.
11
11
  from __future__ import annotations
12
12
 
13
13
  import argparse
14
+ import hashlib
14
15
  import json
15
16
  import os
16
17
  import sys
@@ -29,6 +30,26 @@ def context():
29
30
  return recovery.RecoveryEngine(workspace, trash_root)
30
31
 
31
32
 
33
+ def restore_audit_event(txid, force, report):
34
+ """Non-recovery metadata only; exact paths/errors stay in the result/journal."""
35
+ event = {
36
+ "event": "restore", "force": force, "ok": report.get("ok"),
37
+ "restored_count": len(report.get("restored", [])),
38
+ "conflict_count": len(report.get("conflicts", [])),
39
+ "error_count": len(report.get("errors", [])) + bool(report.get("error")),
40
+ }
41
+ if report.get("error"):
42
+ # Invalid/unknown caller input is not an established transaction ID.
43
+ # Keep correlation without copying arbitrary input into the audit log.
44
+ event["txid_sha256"] = hashlib.sha256(
45
+ txid.encode("utf-8", errors="surrogatepass")).hexdigest()
46
+ else:
47
+ event["txid"] = txid
48
+ if report.get("backup_txids"):
49
+ event["backup_txids"] = report["backup_txids"]
50
+ return event
51
+
52
+
32
53
  def main() -> int:
33
54
  ap = argparse.ArgumentParser(description=__doc__)
34
55
  sub = ap.add_subparsers(dest="cmd", required=True)
@@ -69,13 +90,7 @@ def main() -> int:
69
90
  return 0
70
91
 
71
92
  report = engine.restore(args.txid, force=args.force)
72
- workspace = engine.workspace
73
- event = {"event": "restore", "txid": args.txid, "force": args.force,
74
- "ok": report.get("ok"), "restored": report.get("restored"),
75
- "conflicts": report.get("conflicts"),
76
- "errors": report.get("errors")}
77
- if report.get("backup_txids"):
78
- event["backup_txids"] = report["backup_txids"]
93
+ event = restore_audit_event(args.txid, args.force, report)
79
94
  try:
80
95
  audit.append(event, os.path.join(engine.trash_root, AUDIT_NAME))
81
96
  except OSError:
@@ -4,8 +4,13 @@
4
4
  safe_delete.py [--json] [--dry-run] [--reason TEXT] PATH...
5
5
 
6
6
  Globs are expanded here, explicitly, before classification: an opaque
7
- wildcard never reaches the filesystem unexamined. Every verdict is audited.
8
- Blocked requests exit 2 and leave the filesystem untouched.
7
+ wildcard never reaches the filesystem unexamined. Assessments are best-effort
8
+ audited; an unmatched glob returns before audit setup. --dry-run and policy
9
+ refusals before compensation leave command targets unchanged, but may create
10
+ quarantine/audit metadata and a Git local exclude rule. Policy blocks exit 2
11
+ even in dry-run. A failed real compensation can leave partial target changes.
12
+ New audit events contain decisions, counts and recovery IDs, not target paths
13
+ or free-form --reason text. Exact recovery paths stay in the manifest/result.
9
14
  """
10
15
  from __future__ import annotations
11
16
 
@@ -53,12 +58,35 @@ def delete_directly(spec):
53
58
  return "absent"
54
59
 
55
60
 
61
+ def safe_delete_audit_event(event, decision, code, target_count, *,
62
+ phase=None, report=None, outcome=None):
63
+ """Build this writer's metadata; never copy input paths/reasons/errors.
64
+
65
+ Codes and outcome labels come from this CLI. Transaction IDs come from
66
+ the recovery engine; exact moved/skipped payloads stay in its journal
67
+ and the CLI result. core.audit projects automatic session metadata.
68
+ """
69
+ entry = {"event": event, "tool": "safe_delete", "decision": decision,
70
+ "code": code, "target_count": target_count}
71
+ if phase is not None:
72
+ entry["phase"] = phase
73
+ if outcome is not None:
74
+ entry["outcome"] = outcome
75
+ if report is not None:
76
+ if report.get("txid"):
77
+ entry["txid"] = report["txid"]
78
+ entry["moved_count"] = len(report.get("moved", []))
79
+ entry["skipped_count"] = len(report.get("skipped", []))
80
+ return entry
81
+
82
+
56
83
  def main() -> int:
57
84
  ap = argparse.ArgumentParser(description=__doc__)
58
85
  ap.add_argument("paths", nargs="+", help="paths or globs to delete")
59
86
  ap.add_argument("--json", action="store_true", dest="as_json")
60
87
  ap.add_argument("--dry-run", action="store_true")
61
- ap.add_argument("--reason", default="", help="why this deletion is needed")
88
+ ap.add_argument("--reason", default="",
89
+ help="why this deletion is needed (text is not persisted)")
62
90
  args = ap.parse_args()
63
91
 
64
92
  base = os.getcwd()
@@ -88,6 +116,7 @@ def main() -> int:
88
116
  return 0
89
117
  verdict = policy.decide_path_batch(specs, ctx, recursive=True)
90
118
  engine = recovery.RecoveryEngine(workspace, trash_root)
119
+ relocation_report = None
91
120
 
92
121
  result = {
93
122
  "tool": "safe_delete",
@@ -119,10 +148,8 @@ def main() -> int:
119
148
  return False
120
149
 
121
150
  if verdict.blocked:
122
- record({"event": "decision", "tool": "safe_delete",
123
- "decision": "BLOCK", "code": verdict.code,
124
- "reasons": verdict.reasons, "targets": result["targets"],
125
- "reason": args.reason})
151
+ record(safe_delete_audit_event(
152
+ "decision", "BLOCK", verdict.code, len(specs)))
126
153
  result["exit"] = 2
127
154
  print(json.dumps(result, ensure_ascii=False, indent=2) if args.as_json
128
155
  else f"BLOCKED [{verdict.code}]: {verdict.reasons}")
@@ -151,16 +178,14 @@ def main() -> int:
151
178
  # Authorization/intent must be durable before direct deletion. Dry-run
152
179
  # assessments are best-effort audited but never fail for audit storage.
153
180
  if args.dry_run:
154
- record({"event": "decision", "tool": "safe_delete",
155
- "decision": verdict.decision, "code": verdict.code,
156
- "targets": result["targets"], "phase": "advisory",
157
- "reason": args.reason})
181
+ record(safe_delete_audit_event(
182
+ "decision", verdict.decision, verdict.code, len(specs),
183
+ phase="advisory"))
158
184
  elif verdict.code != policy.CODE_ALLOW_NOOP:
159
185
  try:
160
- record({"event": "decision", "tool": "safe_delete",
161
- "decision": verdict.decision, "code": verdict.code,
162
- "targets": result["targets"], "phase": "intent",
163
- "reason": args.reason}, required=True)
186
+ record(safe_delete_audit_event(
187
+ "decision", verdict.decision, verdict.code, len(specs),
188
+ phase="intent"), required=True)
164
189
  except Exception as exc:
165
190
  result["verdict"] = {
166
191
  "decision": "BLOCK",
@@ -189,7 +214,8 @@ def main() -> int:
189
214
  result["deleted"] = deleted
190
215
  else: # RELOCATE_*
191
216
  report = engine.relocate(specs, meta={
192
- "tool": "safe_delete", "code": verdict.code, "reason": args.reason})
217
+ "tool": "safe_delete", "code": verdict.code})
218
+ relocation_report = report
193
219
  if report.get("storage_failure"):
194
220
  # Hard principle: capacity limits never downgrade to deletion.
195
221
  result["verdict"] = {
@@ -200,10 +226,9 @@ def main() -> int:
200
226
  }
201
227
  result["outcome"] = "BLOCKED: quarantine cannot accept relocation"
202
228
  result["exit"] = 2
203
- record({"event": "decision", "tool": "safe_delete",
204
- "decision": "BLOCK",
205
- "code": policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
206
- "targets": result["targets"], "reason": args.reason})
229
+ record(safe_delete_audit_event(
230
+ "decision", "BLOCK", policy.CODE_BLOCK_RELOCATE_FAILED_STORAGE,
231
+ len(specs), report=report))
207
232
  print(json.dumps(result, ensure_ascii=False, indent=2)
208
233
  if args.as_json else result["outcome"])
209
234
  return 2
@@ -222,11 +247,9 @@ def main() -> int:
222
247
  result["moved"] = report["moved"]
223
248
  result["skipped"] = report["skipped"]
224
249
  result["exit"] = 2
225
- record({"event": "decision", "tool": "safe_delete",
226
- "decision": "BLOCK",
227
- "code": policy.CODE_BLOCK_COMPENSATION_FAILED,
228
- "targets": result["targets"], "txid": report["txid"],
229
- "reason": args.reason})
250
+ record(safe_delete_audit_event(
251
+ "decision", "BLOCK", policy.CODE_BLOCK_COMPENSATION_FAILED,
252
+ len(specs), report=report))
230
253
  print(json.dumps(result, ensure_ascii=False, indent=2)
231
254
  if args.as_json else result["outcome"])
232
255
  return 2
@@ -236,10 +259,10 @@ def main() -> int:
236
259
  result["skipped"] = report["skipped"]
237
260
 
238
261
  if not args.dry_run and verdict.code != policy.CODE_ALLOW_NOOP:
239
- record({"event": "outcome", "tool": "safe_delete",
240
- "targets": result["targets"], "txid": result.get("txid"),
241
- "outcome": result.get("outcome"), "phase": "complete",
242
- "reason": args.reason})
262
+ record(safe_delete_audit_event(
263
+ "outcome", verdict.decision, verdict.code, len(specs),
264
+ phase="complete", report=relocation_report,
265
+ outcome=result.get("outcome")))
243
266
  result["exit"] = 0
244
267
  if args.as_json:
245
268
  print(json.dumps(result, ensure_ascii=False, indent=2))
@@ -81,6 +81,8 @@ def main() -> int:
81
81
  "AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
82
82
  engine = recovery.RecoveryEngine(workspace, trash_root)
83
83
  state = policy.load_mode(trash_root)
84
+ # Project display-only identity/time metadata, never authorization state.
85
+ mode_metadata = audit.project({"ts": state["since"], "session": state["set_by"]})
84
86
  usage = engine.usage()
85
87
 
86
88
  stash_count = 0
@@ -96,8 +98,8 @@ def main() -> int:
96
98
  info = {
97
99
  "workspace": workspace,
98
100
  "mode": state["mode"],
99
- "mode_since": state["since"],
100
- "mode_set_by": state["set_by"],
101
+ "mode_since": mode_metadata.get("ts"),
102
+ "mode_set_by": mode_metadata.get("session"),
101
103
  "trash_root": trash_root,
102
104
  "usage": usage,
103
105
  "retention": {
@@ -118,7 +120,8 @@ def main() -> int:
118
120
 
119
121
  print(f"workspace : {info['workspace']}")
120
122
  print(f"mode : {info['mode']}"
121
- + (f" (since {state['since']} by {state['set_by']})" if state["since"] else ""))
123
+ + (f" (since {info['mode_since']} by {info['mode_set_by']})"
124
+ if info["mode_since"] else ""))
122
125
  print(f"quarantine: {trash_root}")
123
126
  print(f"usage : {usage['files']} files, {usage['bytes']} bytes, "
124
127
  f"{usage['transactions']} transactions "
@@ -140,8 +143,8 @@ def main() -> int:
140
143
 
141
144
 
142
145
  def audit_tail(trash_root, n):
143
- # Historical append-only records can contain raw commands. Never copy
144
- # their free-form fields into an agent-visible status result.
146
+ # core.audit projects both historical field names and values. Status
147
+ # exposes a smaller summary, with no session or compensation details.
145
148
  fields = ("ts", "event", "action", "decision", "code", "txid",
146
149
  "check_id", "guard_latency_ms")
147
150
  return [{key: record[key] for key in fields if key in record}
@@ -153,8 +156,7 @@ DECISION_EVENTS = {"check", "enforce-block", "enforce-proceed", "ask",
153
156
 
154
157
 
155
158
  def decision_stats(trash_root):
156
- """Local-only aggregation of recorded decisions (nothing leaves the
157
- machine). Counts reason codes across all decision-bearing events; ask
159
+ """Aggregate projected reason codes for the status result; ask
158
160
  OUTCOMES are not visible to the guard and are therefore not claimed
159
161
  here."""
160
162
  import collections
@@ -18,13 +18,14 @@ leave?". The four pillars, restated for egress:
18
18
  - **Scope** - the egress boundary. The workspace is exempt; everything
19
19
  outside it is a host identifier until proven otherwise.
20
20
  - **Recoverability** - **weak, and do not pretend otherwise.** There is no
21
- undo for a sent payload. The guard returns a *redaction plan* and an audit
22
- record; it cannot un-send anything.
23
- - **Authorization** - unchanged. `NORMAL`/`RESTRICTED` is reused; rule
24
- configuration is host-side, so you cannot disable a rule.
25
- - **Auditability** - every verdict is recorded as rule id, offsets and
26
- length. **Never the matched bytes** - not even a hash, which would be
27
- offline-crackable for a low-entropy secret.
21
+ undo for a sent payload. The checker returns a *redaction plan* and safe
22
+ verdict metadata; it cannot un-send anything.
23
+ - **Authorization** - `NORMAL`/`RESTRICTED` is reused. Do not weaken the
24
+ user's rules or exemptions. Workspace configuration remains writable by
25
+ same-UID processes; its location is not a security boundary.
26
+ - **Auditability** - trusted callers can persist safe rule ids, offsets and
27
+ lengths. The text CLIs do not automatically append an egress audit.
28
+ Matched bytes or hashes of low-entropy secrets must not be recorded.
28
29
 
29
30
  ## The one rule
30
31
 
@@ -83,7 +84,8 @@ intercept a harness's ordinary file-read tool.
83
84
 
84
85
  A `BLOCK` is not an obstacle to work around. Re-encoding a payload, splitting
85
86
  a secret across lines, or piping through a tool the guard does not scan is a
86
- violation of the authorization pillar and is recorded in the audit log.
87
+ violation of this discipline and can bypass both detection and any caller's
88
+ audit. An absent record does not establish that no emission occurred.
87
89
 
88
90
  ## Applying a redaction plan
89
91
 
@@ -100,9 +102,10 @@ checker-specific mode/path overrides still has to satisfy current sanitizer
100
102
  policy. URI passwords use `<REDACTED>` while retaining scheme/account/host;
101
103
  this is credential redaction, not network-topology hiding or an editable URI.
102
104
 
103
- If you decline to apply a plan on a rewritable channel, the API contract is
104
- "you were told": the audit records `sanitize-declined`. That is a choice
105
- with a record, not a default.
105
+ The checker does not observe whether its plan was applied or declined.
106
+ `sanitize-declined` is a proposed integration event, not an event automatically
107
+ written by either text CLI. A trusted emitter must own enforcement and any
108
+ recording; a checker SANITIZE decision alone is not completed redaction.
106
109
 
107
110
  ## Value-free detection (why `echo "$TOKEN"` is caught)
108
111
 
@@ -169,5 +172,14 @@ host-side file: read from the workspace root, not settable per call. If a
169
172
  scan hits something you believe is benign, report it - do not weaken the
170
173
  rule, and do not route around the guard.
171
174
 
175
+ Since 0.2.5-rc1, both configuration filenames use the same limited section/key grammar;
176
+ `.agent-guardignore` is not a gitignore file. The first readable UTF-8 file
177
+ wins, including an empty or malformed preferred file. Inspect the checker's
178
+ `exemption.source`, counts and diagnostics before assuming a configuration
179
+ was applied; `exempted` counts actual removed spans. Human checker and
180
+ sanitizer warnings use stderr and contain no configuration values. A warning
181
+ can coexist with effective legacy entries and does not authorize changing
182
+ the file or weakening a rule.
183
+
172
184
  See `references/rules.md` for the frozen rule table, the exemption format and
173
185
  the audit record shape; `references/channels.md` for the egress taxonomy.
@@ -43,7 +43,14 @@ Per `docs/design/threat-model.md`, the guard "may not claim" prevention of
43
43
  adversarial exfiltration, and per design 4.4 an unreachable channel gets
44
44
  **no verdict at all**.
45
45
 
46
- ## Adapter mapping (design 4.5)
46
+ ## Proposed emitter integration mapping (design 4.5)
47
+
48
+ The following is a design contract for integrations that own the payload,
49
+ not a shipped host-support table. The default Claude/Kimi/DSH shell hooks
50
+ handle delete-guard decisions and do not implement general pre-write or
51
+ pre-request rewriting. The optional DSH complete text-read prototype uses a
52
+ separate post-execute path. Actual support and evidence are listed in the
53
+ [capability matrix](../../../docs/guides/harness-capabilities.md).
47
54
 
48
55
  | Core decision | Claude Code (`PreToolUse`) | DSH (`PreToolDecision`) | No-hook harness |
49
56
  |---|---|---|---|
@@ -186,6 +186,10 @@ facts still apply to variable templates.
186
186
 
187
187
  ## Configuration (environment)
188
188
 
189
+ The RC2 source retains the provenance/count diagnostics introduced in RC1 for the existing
190
+ exemption parser. Matching and file priority remain unchanged; the published
191
+ 0.2.4 package does not include these diagnostic fields and warnings.
192
+
189
193
  | Variable | Meaning |
190
194
  |---|---|
191
195
  | `AGENT_GUARD_EXFIL_CHANNEL` | default egress channel for both text CLIs |
@@ -198,21 +202,87 @@ facts still apply to variable templates.
198
202
 
199
203
  ## Repo-local exemptions (design 5.2)
200
204
 
201
- `.agent-guard/exfil-allow.toml` (or `.agent-guardignore`) is read from the
202
- **workspace root only**, so an agent cannot add one on the fly.
205
+ `.agent-guard/exfil-allow.toml` (or `.agent-guardignore`) is read by the local
206
+ guard from the **workspace root only**, not supplied as a per-call option.
207
+ This location does not make the file read-only: a process with workspace
208
+ write access can change exemptions. The host/operator must control its
209
+ contents; this is not a same-UID isolation boundary.
210
+
211
+ Both filenames use the same small `key = value` grammar. The `.toml`
212
+ extension does not promise a full TOML parser, and `.agent-guardignore` does
213
+ not accept gitignore-style bare paths or `!` re-inclusion rules.
203
214
 
204
- ```toml
215
+ ```ini
205
216
  [rules]
206
217
  disable = [] # rule-id globs; [] means none
207
218
  [values]
208
219
  sha256 = # exempt a literal WITHOUT tracking it
209
- sha256:8ab1...e7
220
+ sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
210
221
  [paths]
211
222
  ignore = # path globs skipped entirely
212
223
  docs/*.md
213
224
  tests/fixtures/secrets/*
214
225
  ```
215
226
 
227
+ ### Supported format and precedence
228
+
229
+ | Section | Recommended key | Top-level aliases retained for compatibility |
230
+ |---|---|---|
231
+ | `[rules]` | `disable` | `rule`, `rules`, `disable` |
232
+ | `[paths]` | `ignore` | `path`, `paths`, `ignore` |
233
+ | `[values]` | `sha256` | `sha256`, `hash`, `hashes` |
234
+
235
+ Keys and section names are case-insensitive. Values are separated by commas
236
+ or whitespace; surrounding list brackets and single/double quotes are
237
+ stripped. A subsequent line without `=` or a section header continues the
238
+ previous key; indentation is recommended but is not required. Empty values
239
+ and `[]` add no entries. Everything after the first `#` is a comment, even
240
+ inside quotes. Escaped strings, patterns containing spaces or `#`, TOML
241
+ multiline arrays, and gitignore negation are not supported. Patterns use
242
+ Python `fnmatch`, whose `*` can match a slash; this is not gitignore matching.
243
+ Value digests must be `sha256:` followed by 64 lowercase hexadecimal digits.
244
+
245
+ The first readable UTF-8 file wins: `.agent-guard/exfil-allow.toml`, then
246
+ `.agent-guardignore`. They are never merged. A readable empty or malformed
247
+ preferred file still takes precedence; it does not activate the fallback.
248
+ Missing, unreadable or non-UTF-8 files allow the next candidate to be tried.
249
+ When neither can be loaded, no configured exemption applies and scanning
250
+ continues. The lower-priority file is not read when the preferred one loads.
251
+
252
+ ### Configuration diagnostics
253
+
254
+ After a successful scan, `check_span.py --json` adds an `exemption` object:
255
+ `source`, `active`, `counts` (`rules`/`paths`/`hashes`), `diagnostics`, and
256
+ `diagnostics_omitted`. `source` is one of the two fixed relative filenames,
257
+ `null` when none was loaded, or `<provided>` for an explicit library object.
258
+ Counts are configured entries, not proof that a pattern matched; existing
259
+ `exempted` reports the number of payload spans actually removed.
260
+ An input/channel refusal before configuration loading may omit this object.
261
+
262
+ Diagnostics contain only a static `code`, a fixed relative `source` and an
263
+ optional 1-based `line`. They never copy keys, patterns, hashes, raw lines,
264
+ workspace addresses or exception text. At most 32 are retained; the omitted
265
+ count records the remainder. Human checker warnings and all sanitizer CLI
266
+ warnings go to stderr. JSON checker stdout remains one object; sanitizer
267
+ stdout remains the payload or, under `--dry-run`, the JSON plan. Library
268
+ `sanitize_text` returns the same safe metadata without printing warnings.
269
+
270
+ | Code | Meaning |
271
+ |---|---|
272
+ | `EXEMPTION_IGNORED_LINE` | No assignment or prior key; bare gitignore lines have no effect |
273
+ | `EXEMPTION_UNKNOWN_KEY` | Unrecognized top-level key; its values have no effect |
274
+ | `EXEMPTION_UNKNOWN_SECTION` | Unknown section; recognized legacy keys may still work |
275
+ | `EXEMPTION_LEGACY_SECTION_KEY` | Nonstandard key still uses the existing section fallback |
276
+ | `EXEMPTION_MALFORMED_SECTION` | Malformed header still uses existing parsing |
277
+ | `EXEMPTION_INVALID_HASH` | Entry cannot match the required lowercase digest format |
278
+ | `EXEMPTION_UNSUPPORTED_NEGATION` | `!` is literal, not an exclusion/re-inclusion operator |
279
+ | `EXEMPTION_READ_FAILED` / `EXEMPTION_ENCODING_INVALID` | Try the next file; raw errors are withheld |
280
+ | `EXEMPTION_SHADOWED` | A present fallback file is not loaded because the preferred file was readable |
281
+
282
+ These diagnostics do not change verdicts, matching or exit codes. Legacy
283
+ parsing can retain valid entries alongside ignored input or warnings; a
284
+ warning is neither whole-file rejection nor a trust/permission check.
285
+
216
286
  Three properties matter:
217
287
 
218
288
  1. **Value exemptions are by hash.** A human who needs one specific literal
@@ -221,8 +291,9 @@ Three properties matter:
221
291
  2. **Path exemptions, not rule amnesty.** Scoping an exemption to a path
222
292
  keeps the rule fully active everywhere else. Disabling the rule wholesale
223
293
  is what would blind the guard.
224
- 3. **A broken allowfile fails closed.** Malformed input is ignored and the
225
- rules stay on - never the reverse.
294
+ 3. **Unrecognized input does not add exemptions.** Ignored lines and unknown
295
+ top-level keys leave scanning active; any recognized legacy entries still
296
+ follow the behavior documented above. Diagnostics expose this distinction.
226
297
 
227
298
  This repository ships such a file for its own documentation and fixtures,
228
299
  exactly as `SECURITY.md` documents "Expected scanner hits on this
@@ -232,6 +303,15 @@ corpus.
232
303
 
233
304
  ## Audit record shape
234
305
 
306
+ This is a safe record shape for a trusted integration that chooses to persist
307
+ egress evidence. `check_span.py` and `sanitize.py` do not automatically append
308
+ these events, and cannot observe a caller declining a plan. It is not a claim
309
+ that every egress decision has a durable record. The RC2 source candidate
310
+ projects supported metadata on append/read, including opaque session
311
+ correlation and value-free source-key context. See the
312
+ [shared audit contract](../../../docs/guides/audit-metadata.md); direct reads of
313
+ old log bytes and other output channels remain outside that projection.
314
+
235
315
  ```json
236
316
  {"event":"exfil-sanitize","rule_id":"secret/openai-key",
237
317
  "confidence":"deterministic","channel":"file-write",