@mokuyoaxis/agent-guard 0.2.5-rc1 → 0.2.5-rc3

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 (37) hide show
  1. package/CONTRIBUTING.md +24 -0
  2. package/README.md +43 -10
  3. package/README.zh-CN.md +35 -9
  4. package/SECURITY.md +14 -8
  5. package/adapters/dsh/harness/README.md +5 -0
  6. package/adapters/dsh/harness/guard_lab.py +3 -2
  7. package/adapters/kimi-code/harness/README.md +5 -0
  8. package/core/audit.py +170 -25
  9. package/core/lab.py +82 -9
  10. package/docs/README.md +20 -4
  11. package/docs/design/architecture.md +12 -5
  12. package/docs/design/compatibility.md +48 -6
  13. package/docs/guides/audit-metadata.md +77 -0
  14. package/docs/guides/getting-started.md +13 -6
  15. package/docs/guides/harness-capabilities.md +7 -1
  16. package/docs/history/friction.md +4 -3
  17. package/docs/lab/blue-team-calibration.md +45 -0
  18. package/docs/lab/examples/blue-team-calibration.py +53 -0
  19. package/docs/lab/guard-lab.md +20 -2
  20. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  21. package/docs/releases/release-notes-0.2.5-rc3.md +74 -0
  22. package/docs/reports/blue-team-lab-2026-10.md +73 -0
  23. package/docs/research/README.md +41 -0
  24. package/docs/research/content-authorization.md +54 -0
  25. package/docs/research/dataflow-observability.md +48 -0
  26. package/docs/research/delegation-provenance.md +56 -0
  27. package/docs/research/evaluation-method.md +51 -0
  28. package/docs/research/lab-observations-2026-10.json +43 -0
  29. package/guard_lab.py +11 -0
  30. package/package.json +1 -1
  31. package/skills/delete-guard/SKILL.md +6 -3
  32. package/skills/delete-guard/references/policy.md +14 -10
  33. package/skills/delete-guard/scripts/gc.py +18 -3
  34. package/skills/delete-guard/scripts/safe_delete.py +1 -1
  35. package/skills/delete-guard/scripts/status.py +9 -7
  36. package/skills/exfil-guard/SKILL.md +1 -1
  37. package/skills/exfil-guard/references/rules.md +6 -3
package/guard_lab.py CHANGED
@@ -5,6 +5,17 @@ from __future__ import annotations
5
5
 
6
6
  import sys
7
7
 
8
+ if __name__ == "__main__" and len(sys.argv) > 1 and sys.argv[1] == "_observe":
9
+ import time
10
+
11
+ try:
12
+ print(
13
+ f"observer-startup stage=BOOTSTRAP monotonic={time.monotonic():.6f}",
14
+ file=sys.stderr, flush=True,
15
+ )
16
+ except (OSError, ValueError):
17
+ pass
18
+
8
19
  from core.lab import cli_main, observer_cli_main
9
20
 
10
21
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.5-rc1",
3
+ "version": "0.2.5-rc3",
4
4
  "description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
5
5
  "type": "module",
6
6
  "main": "./adapters/dsh/lib/index.js",
@@ -105,11 +105,14 @@ undone. Use only a disposable fixture when verifying this behavior; the
105
105
  [policy reference](references/policy.md#assessment-and-dry-run-side-effects)
106
106
  defines the no-match, existing-ignore and external-bucket branches.
107
107
 
108
- In the 0.2.5-rc1 source candidate, new `safe_delete` audit events record decisions, target counts and established
108
+ Since 0.2.5-rc1, new `safe_delete` audit events record decisions, target counts and established
109
109
  recovery IDs/counts rather than target paths or free-form reasons. `--reason`
110
110
  is still accepted, but its text is not persisted in audit or transaction
111
111
  metadata. Exact recovery paths remain in the CLI result and manifest.
112
- Historical records and automatic session metadata are unchanged; see the
112
+ At released RC1, historical records and automatic session handling are unchanged.
113
+ Since RC2, the shared audit layer projects supported metadata on append/read,
114
+ uses opaque session correlation and limits status/GC metadata; see the
115
+ [shared audit contract](../../docs/guides/audit-metadata.md) and the
113
116
  [policy reference](references/policy.md#safe_delete-audit-metadata).
114
117
 
115
118
  ## Quarantine location queries
@@ -134,7 +137,7 @@ read just to answer a location/count question.
134
137
 
135
138
  ## RESTRICTED mode
136
139
 
137
- The 0.2.5-rc1 source candidate protects the quarantine root, root manifest,
140
+ RC2 and RC3 retain RC1 protection for the quarantine root, root manifest,
138
141
  audit/state files, state temp file, sessions tree and storage access parents.
139
142
  Housekeeping does not override those checks. Use the existing explicit
140
143
  `gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
@@ -6,13 +6,15 @@ 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 describes the 0.2.5-rc1 source candidate. The published 0.2.4
10
- baseline does not include its control-path, GC and audit-writer maintenance.
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.
11
12
 
12
13
  ## Decision Protocol
13
14
 
14
15
  The stable cross-harness interface is Decision + ReasonCode + Explanation
15
- (+ RecoveryPlan in payload). Five decision classes:
16
+ (+ RecoveryPlan in payload). The deletion path uses the five classes below;
17
+ the shared text policy also supports `SANITIZE`.
16
18
 
17
19
  | Decision | Meaning | Interaction tier |
18
20
  |---|---|---|
@@ -88,7 +90,7 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
88
90
 
89
91
  ## Rule table (first match wins)
90
92
 
91
- The quarantine control-path changes below belong to the 0.2.5-rc1 source candidate;
93
+ The quarantine control-path changes below were introduced in 0.2.5-rc1;
92
94
  the published 0.2.4 artifact retains its original housekeeping order.
93
95
 
94
96
  | # | Condition | Verdict code | Effect |
@@ -145,7 +147,7 @@ a portable fallback.
145
147
  |---|---|
146
148
  | `AGENT_GUARD_WORKSPACE` | override workspace boundary discovery |
147
149
  | `AGENT_GUARD_TRASH` | override quarantine location |
148
- | `AGENT_GUARD_SESSION` | session identity recorded in audit/manifest |
150
+ | `AGENT_GUARD_SESSION` | selects session authorization state; RC2 audit metadata uses opaque correlation |
149
151
  | `AGENT_GUARD_ARTIFACTS` | `os.pathsep`-joined extra artifact patterns |
150
152
  | `AGENT_GUARD_ALLOW_REGENERABLE` | `0` disables direct deletion of artifacts |
151
153
 
@@ -187,8 +189,9 @@ Restore audit metadata now records `restored_count`, `conflict_count` and
187
189
  `error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
188
190
  `ok` and preservation `backup_txids` retain correlation; invalid/unknown input
189
191
  IDs use `txid_sha256`. Exact restoration paths and errors remain in the
190
- recovery journal and CLI result. Historical audit lines are not rewritten;
191
- automatic session metadata and other generic audit writers are unchanged.
192
+ recovery journal and CLI result. Historical audit lines are not rewritten.
193
+ At released RC1, automatic session/generic handling is unchanged; the RC2
194
+ [shared projection](../../../docs/guides/audit-metadata.md) extends it.
192
195
 
193
196
  ### safe_delete audit metadata
194
197
 
@@ -212,9 +215,10 @@ accurate. Those surfaces can still contain sensitive text.
212
215
 
213
216
  Mutation intents remain durable before deletion; assessment and outcome
214
217
  audits retain their existing best-effort behavior. Historical audit lines
215
- and manifest metadata are not rewritten. Automatic `ts`/`session` fields
216
- and generic `core.audit.append`/`tail` behavior are unchanged; this writer's
217
- minimization is not a guarantee that every audit field is sanitized.
218
+ and manifest metadata are not rewritten. At released RC1, automatic session
219
+ and generic append/tail handling is unchanged. The
220
+ [shared projection](../../../docs/guides/audit-metadata.md) introduced in RC2 limits these fields
221
+ and legacy reads, while raw historical files and recovery surfaces remain.
218
222
 
219
223
  Authority model: `gc.py --execute` is intentionally permitted
220
224
  non-interactively (scheduled maintenance is legitimate; purging
@@ -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,
@@ -64,7 +64,7 @@ def safe_delete_audit_event(event, decision, code, target_count, *,
64
64
 
65
65
  Codes and outcome labels come from this CLI. Transaction IDs come from
66
66
  the recovery engine; exact moved/skipped payloads stay in its journal
67
- and the CLI result. Automatic audit session metadata is unchanged.
67
+ and the CLI result. core.audit projects automatic session metadata.
68
68
  """
69
69
  entry = {"event": event, "tool": "safe_delete", "decision": decision,
70
70
  "code": code, "target_count": target_count}
@@ -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
@@ -172,7 +172,7 @@ host-side file: read from the workspace root, not settable per call. If a
172
172
  scan hits something you believe is benign, report it - do not weaken the
173
173
  rule, and do not route around the guard.
174
174
 
175
- In the 0.2.5-rc1 source candidate, both configuration filenames use the same limited section/key grammar;
175
+ Since 0.2.5-rc1, both configuration filenames use the same limited section/key grammar;
176
176
  `.agent-guardignore` is not a gitignore file. The first readable UTF-8 file
177
177
  wins, including an empty or malformed preferred file. Inspect the checker's
178
178
  `exemption.source`, counts and diagnostics before assuming a configuration
@@ -186,7 +186,7 @@ facts still apply to variable templates.
186
186
 
187
187
  ## Configuration (environment)
188
188
 
189
- The 0.2.5-rc1 candidate adds provenance/count diagnostics to the existing
189
+ RC2 and RC3 retain the provenance/count diagnostics introduced in RC1 for the existing
190
190
  exemption parser. Matching and file priority remain unchanged; the published
191
191
  0.2.4 package does not include these diagnostic fields and warnings.
192
192
 
@@ -306,8 +306,11 @@ corpus.
306
306
  This is a safe record shape for a trusted integration that chooses to persist
307
307
  egress evidence. `check_span.py` and `sanitize.py` do not automatically append
308
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. Generic `core.audit` also adds
310
- session metadata; that metadata and existing logs require their own review.
309
+ that every egress decision has a durable record. Since RC2, shared audit
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.
311
314
 
312
315
  ```json
313
316
  {"event":"exfil-sanitize","rule_id":"secret/openai-key",