@mokuyoaxis/agent-guard 0.2.3 → 0.2.5-rc1

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 (80) hide show
  1. package/README.md +158 -571
  2. package/README.zh-CN.md +133 -490
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +8 -6
  5. package/adapters/claude/README.md +3 -3
  6. package/adapters/claude/harness/README.md +1 -1
  7. package/adapters/codex/harness/README.md +2 -2
  8. package/adapters/dsh/README.md +17 -6
  9. package/adapters/dsh/harness/README.md +8 -8
  10. package/adapters/dsh/harness/guard_lab.py +3 -3
  11. package/adapters/dsh/lib/index.js +1 -1
  12. package/adapters/kimi-code/README.md +7 -7
  13. package/adapters/kimi-code/harness/README.md +3 -3
  14. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  15. package/assets/linux-do-community.svg +19 -0
  16. package/core/__init__.py +1 -1
  17. package/core/classifier.py +66 -17
  18. package/core/policy.py +28 -13
  19. package/core/recovery.py +261 -24
  20. package/core/redaction.py +122 -21
  21. package/core/trash_index.py +193 -0
  22. package/docs/README.md +113 -0
  23. package/docs/{architecture.md → design/architecture.md} +51 -12
  24. package/docs/{compatibility.md → design/compatibility.md} +124 -4
  25. package/docs/{threat-model.md → design/threat-model.md} +10 -8
  26. package/docs/guides/getting-started.md +104 -0
  27. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +14 -9
  28. package/docs/guides/trash-index.md +106 -0
  29. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  30. package/docs/{friction.md → history/friction.md} +123 -0
  31. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  32. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  33. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  34. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  35. package/docs/{guard-lab.md → lab/guard-lab.md} +15 -13
  36. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  37. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  38. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  39. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  40. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  41. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  42. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  43. package/docs/releases/release-notes-0.2.4.md +89 -0
  44. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  45. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  46. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  47. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  48. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  49. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  50. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  51. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  52. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  53. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  54. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  55. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  56. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  57. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  58. package/package.json +4 -2
  59. package/skills/delete-guard/SKILL.md +80 -7
  60. package/skills/delete-guard/references/policy.md +104 -8
  61. package/skills/delete-guard/scripts/check.py +22 -0
  62. package/skills/delete-guard/scripts/restore.py +34 -7
  63. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  64. package/skills/delete-guard/scripts/status.py +52 -0
  65. package/skills/exfil-guard/SKILL.md +23 -11
  66. package/skills/exfil-guard/references/channels.md +9 -2
  67. package/skills/exfil-guard/references/rules.md +83 -6
  68. package/skills/exfil-guard/scripts/_payload.py +20 -0
  69. package/skills/exfil-guard/scripts/check_span.py +5 -1
  70. package/skills/exfil-guard/scripts/sanitize.py +6 -3
  71. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  72. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  73. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  74. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  75. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  76. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  77. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  78. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  79. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  80. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -14,7 +14,7 @@ Harness adapters integrate against exactly four things:
14
14
  `RELOCATE`.)
15
15
  2. **Reason codes** - stable machine-readable strings (`RELOCATE_TREE`,
16
16
  `COMPOUND_CWD_DELETE`, `BLOCK_PROTECTED_PATH`, ...). See
17
- [../skills/delete-guard/references/policy.md](../skills/delete-guard/references/policy.md).
17
+ [../skills/delete-guard/references/policy.md](../../skills/delete-guard/references/policy.md).
18
18
  3. **Explanation field** - human-facing text attached to every verdict.
19
19
  4. **check.py exit codes** - `0` proceed/advisory-ok, `2` blocked,
20
20
  `3` ask, `1` internal error.
@@ -31,7 +31,25 @@ While the major version is `0`:
31
31
  | Manifest record gains a new field | minor (old fields never repurposed) |
32
32
  | Manifest record loses/repurposes a field | major + MIGRATION.md |
33
33
  | check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
34
- | Default policy verdict changes for an existing shape | minor + entry in docs/friction.md |
34
+ | Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
35
+
36
+ ### 0.2.4 maintenance patch exception
37
+
38
+ For this release, the maintainer explicitly selected `0.2.4` for the recovery
39
+ maintenance fixes and read-only trash query. This is a documented exception
40
+ to the minor-release rules above, not a general relaxation of those rules.
41
+ It adds `BLOCK_GIT_RESET_COLLISION` and refuses hard resets whose collision
42
+ preflight or command context cannot safely establish recoverability.
43
+ Relocation restore also refuses invalid source/destination boundaries and
44
+ requires preservation before a forced overwrite. See
45
+ [F24](../history/friction.md#f24--hard-reset-could-destroy-content-outside-the-tracked-snapshot)
46
+ and [F25](../history/friction.md#f25--restore-trusted-paths-and-removed-an-occupied-destination-before-recovery).
47
+
48
+ The reason string is additive; existing strings and decision classes are not
49
+ renamed. Existing CLI parameters and exit codes retain their roles. Optional
50
+ `backup_txids` and the separate trash-query schema are described below.
51
+ No manifest migration or new transaction strategy is introduced. Consumers
52
+ must accept the additional refusal reason and ignore unknown optional fields.
35
53
 
36
54
  ## Additive surfaces since v0.1.1
37
55
 
@@ -56,6 +74,44 @@ While the major version is `0`:
56
74
  | `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 |
57
75
  | 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 |
58
76
 
77
+ ### 0.2.5-rc1 assessment contract clarification (source candidate)
78
+
79
+ Advisory and dry-run retain their existing best-effort audit behavior and
80
+ metadata side effects. Tests and documentation distinguish unchanged command
81
+ targets from zero filesystem writes, and advisory exit 0 from execution
82
+ authorization. No flag, result field, policy decision, audit storage location
83
+ or exit code changes. See the [assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
84
+
85
+ ### 0.2.5-rc1 safe_delete audit minimization (source candidate)
86
+
87
+ New safe_delete audit events replace raw target/reason payloads with
88
+ `target_count`; established relocation reports retain `txid` and add
89
+ `moved_count`/`skipped_count`, including storage-failure decisions. Decision
90
+ codes, phases and static outcome labels remain available. Free-form
91
+ `--reason` stays accepted but is omitted from new audit events and
92
+ `tx-start.meta`. Essential recovery paths/intents, CLI result fields,
93
+ verdicts, exit codes and durability gates retain their behavior.
94
+ Audit event shapes are not frozen. Historical records are not rewritten,
95
+ and generic audit writers, automatic session identity and other output
96
+ surfaces are unchanged. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
97
+
98
+ ### 0.2.5-rc1 exemption configuration diagnostics (source candidate)
99
+
100
+ The existing limited parser, first-readable-file precedence and exemption
101
+ matching are retained. No full TOML/gitignore parser, configuration migration,
102
+ production dependency or new policy reason is added. Unknown top-level keys
103
+ and bare lines remain ineffective; recognized legacy entries may still apply
104
+ alongside warnings. Diagnostics do not change verdicts or exit codes.
105
+
106
+ Successful text scans may add `exemption` provenance/count/diagnostic metadata
107
+ to checker JSON and the sanitizer library result. Human checker and sanitizer
108
+ CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
109
+ keep their respective formats. Normal missing/valid configurations remain
110
+ quiet. Diagnostic codes are configuration metadata, not Decision Protocol
111
+ reason codes. Consumers should tolerate the additive fields and warnings;
112
+ the manifest is 0.2.5-rc1, selected as a prerelease candidate. The diagnostic
113
+ grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
114
+
59
115
  ### 0.2.0 check output minimization
60
116
 
61
117
  `check.py` still returns the same decision class, reason code, static
@@ -93,6 +149,35 @@ cmd/PowerShell execution through each harness, hook-selected dialect wiring,
93
149
  broader UNC/device paths, module auto-loading and full-suite Windows
94
150
  portability remain unverified.
95
151
 
152
+ ### 0.2.4 trash location query
153
+
154
+ status.py --trash-index is an additive read-only mode, with --root, --trash,
155
+ --max-depth and --max-entries. Ordinary status arguments and result fields
156
+ keep their prior behavior. Index-specific options require index mode.
157
+ Its JSON is a separate schema_version=1 contract documented in
158
+ [trash-index.md](../guides/trash-index.md): count is candidate locations,
159
+ identified_count is layout-identified locations, and complete applies only
160
+ to the declared scope. Exit 0 means complete, 1 means partial results with
161
+ errors, and 2 means invalid arguments. The shared core query and this CLI
162
+ are additions in 0.2.4, with no storage or manifest migration.
163
+
164
+ ### 0.2.4 forced-restore preservation
165
+
166
+ Forced relocation restores now preserve an existing occupant with the normal
167
+ relocation transaction and journal before replacing it. Existing CLI parameters,
168
+ exit codes and result fields retain their roles. The JSON result may add
169
+ `backup_txids`, a list of preservation attempts; inspect transaction state and
170
+ files after errors rather than treating an ID as proof of a complete copy.
171
+ Results without a preservation attempt omit this field. Text output identifies
172
+ the same attempts. CLI audit events also include these IDs when present.
173
+
174
+ The preservation transaction uses existing `tx-start`/`relocate-intent`/
175
+ `relocate` records and correlates through the existing `meta` object; no
176
+ manifest migration or new transaction strategy is introduced. Restore journal
177
+ or CLI audit write failure reports a non-success result while retaining the
178
+ filesystem outcome and preservation IDs for inspection. These changes belong
179
+ to 0.2.4; the published `0.2.3` artifact does not include them.
180
+
96
181
  ### PowerShell parameter prefixes
97
182
 
98
183
  PowerShell resolves a parameter by unambiguous prefix, so `ri build -r -fo`
@@ -114,9 +199,41 @@ Every expansion is recorded in the op notes for audit.
114
199
 
115
200
  ## Verdict changes since v0.1.1
116
201
 
202
+ ### 0.2.5-rc1 lifecycle and restore-audit maintenance (source candidate)
203
+
204
+ Existing `BLOCK_PROTECTED_PATH` now wins before `ALLOW_TRASH_GC` for
205
+ workspace/Git and quarantine control paths. Quarantine root metadata,
206
+ session state and in-workspace storage parents are protected. Ordinary
207
+ unprotected explicit payload housekeeping and the explicit GC CLI remain
208
+ available. Opaque quarantine globs now return `BLOCK_WILDCARD`; safe_delete
209
+ can enumerate a concrete batch before policy checks.
210
+ See [F26](../history/friction.md#f26--housekeeping-overrode-quarantine-control-protection).
211
+ This changes default verdicts and would ordinarily follow the minor-release
212
+ contract. The maintainer explicitly selected 0.2.5-rc1 for this maintenance
213
+ candidate instead of 0.3.0. This is a new, bounded exception for the existing
214
+ control-path/glob, PURGED inventory, audit-writer and exemption-diagnostic
215
+ maintenance, not an extension of the prior 0.2.4 exception to arbitrary changes.
216
+ Existing decision/reason strings, CLI arguments and exit codes retain their
217
+ roles. There is no manifest migration or production dependency. Publication,
218
+ and any later stable 0.2.5 decision, remain separate from candidate preparation.
219
+ The exact -rcN tag maps to GitHub prerelease and npm rc, preserving stable latest.
220
+ See the [candidate notes](../releases/release-notes-0.2.5-rc1.md).
221
+
222
+ Active `tx_inventory` and GC plans now omit `PURGED` history, while
223
+ `transactions` and manifests retain it. Failed/unpurged transactions retain
224
+ their prior eligibility rules; no stash deletion or storage migration is added.
225
+
226
+ Restore audit records replace `restored`/`conflicts`/`errors` payload copies
227
+ with `restored_count`/`conflict_count`/`error_count`. Established IDs and backup
228
+ attempt IDs stay correlated; invalid/unknown caller IDs use `txid_sha256`.
229
+ Audit shapes beyond manifests are not frozen. CLI parameters, exit codes,
230
+ recovery manifests and returned recovery paths/errors retain their roles.
231
+ This is one writer's minimization, not general recursive audit sanitization.
232
+
117
233
  A changed default verdict for an existing shape is a **minor** release and
118
- requires an entry in [friction.md](friction.md) - never a silent behaviour
119
- shift. Additive reason codes are listed above; this table is for shapes
234
+ requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
235
+ shift. The bounded 0.2.4 and 0.2.5-rc1 exceptions are recorded above. Additive reason codes
236
+ are listed above; this table is for shapes
120
237
  whose *existing* verdict moved.
121
238
 
122
239
  | Shape | Was | Now | Why |
@@ -125,6 +242,9 @@ whose *existing* verdict moved.
125
242
  | `cd ... && git push --force` | `ASK` / `COMPOUND_CWD_DELETE` | `BLOCK` / `BLOCK_FORCE_PUSH` | A shape rule cannot downgrade a position-independent hard refusal (F1) |
126
243
  | `cd ... && rm` with an out-of-workspace, protected, or unknowable target | `ASK` / `COMPOUND_CWD_DELETE` | The applicable hard `BLOCK` | F1 describes compensation difficulty, not permission to cross a boundary |
127
244
  | Attached or newline-separated destructive commands (`echo ok;rm ...`, `echo ok` followed by newline and `rm ...`) | Could miss the destructive segment | Classifies and applies its normal policy | POSIX command boundaries must be preserved by the lexer |
245
+ | `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
246
+ | Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
247
+ | Quarantine root/control paths, protected metadata inside trash, or an in-workspace storage parent | Could be allowed as housekeeping or regenerable content | `BLOCK_PROTECTED_PATH` | Recovery/state evidence protection precedes housekeeping (0.2.5-rc1 candidate, F26) |
128
248
 
129
249
  Unchanged on purpose: a genuine compensation fault (`git stash create`
130
250
  failing, a relocation that does not cover every target, an audit intent
@@ -10,8 +10,10 @@ bypass. Therefore:
10
10
  It defends against *mistakes*: misjudged context, mis-expanded commands,
11
11
  wrong working directory, hallucinated paths - which is what essentially
12
12
  all real-world "agent deleted my data" incidents are.
13
- - You may claim: default-recoverable deletions, full decision audit, graded
14
- authorization, reduced blast radius of common accidents.
13
+ - You may claim: recovery for supported valuable deletions, explicit audit
14
+ contracts for observed calls, graded authorization discipline, and reduced
15
+ blast radius of common accidents. Regenerable artifacts may be deleted
16
+ directly; best-effort audit and bypassed calls are not complete visibility.
15
17
  - You must NOT claim: sandboxing, containment of malicious agents,
16
18
  prevention of determined bypass.
17
19
 
@@ -27,11 +29,11 @@ bypass. Therefore:
27
29
  |---|---|---|---|
28
30
  | 1 | Agent deletes via unrecognized channel: its own script calling `unlink()`, `python -c`, `node -e` | Out of scope for command classification; prompt layer forbids circumvention; audit records what was seen | Real. Upgrade path: kernel-side enforcement (fanotify/eBPF/sandbox) or intercepting the FS service rather than the shell |
29
31
  | 2 | Agent tampers with `.agent-trash/state.json` to self-promote mode | Portable file is advisory by design; harness adapters SHOULD hold the authoritative mode in host memory the agent's shell cannot reach | Accepted for pure-CLI usage; documented |
30
- | 3 | Agent allocates a PTY to pass the `isatty()` human check | Documented heuristic; adapters enforce promotion out-of-band (human-only UI/command) | Heuristic, not cryptographic |
32
+ | 3 | Agent allocates a PTY to pass the `isatty()` human check | The CLI check is a heuristic. An integration requiring human-only promotion must provide independent host authority; the shipped adapters do not supply isolated mode storage | Same-UID configuration/state remain writable; no authenticated human identity guarantee |
31
33
  | 4 | Agent edits/removes `manifest.jsonl` to hide provenance | Append-only by convention; audit log is separate; adapters may ship both off-box | Tamper-evident only if exported |
32
34
  | 5 | Symlink confusion (delete link vs target, trailing slash dereference) | Lexical boundary analysis; link relocation preserves the link; realpath recorded | Low |
33
- | 6 | TOCTOU between classification and execution | Window is milliseconds inside one process; adapters that need more should classify-and-execute atomically | Small, acknowledged |
34
- | 7 | Destructive restore | Restore refuses overwrites without explicit human `--force`; all restores audited | Low |
35
+ | 6 | TOCTOU between classification and execution | Checks and moves are not atomic. Native hooks run Core before handing control back to host execution; there is no promised maximum gap | Concurrent changes can invalidate facts or affect later execution. Atomic isolation remains unimplemented |
36
+ | 7 | Destructive restore | Relocation destinations and sources are checked against the workspace and their quarantine transaction. IDs and directory locations are validated; leaf symlinks retain their semantics. Human `--force` preserves an occupant through a separate relocation transaction before replacement; failed preservation stops that item | Checks and moves are not atomic against concurrent changes. Cross-filesystem failures may leave a partial destination or backup; inspect the filesystem and reported transaction IDs. Preserved versions add storage use and follow existing explicit GC |
35
37
  | 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; `status.py` exposes size; 30-day/5-GiB soft eligibility with explicit audited purge | A human or scheduler must execute purge; audit is retained |
36
38
 
37
39
  ## guard-lab diagnostic boundary
@@ -55,15 +57,15 @@ the integrity of a single run's evidence, not real credentials.
55
57
  | A mixed harness transcript is mislabeled as model output | Documentation requires role/channel separation before scanning; reports disclose that scan input and stage are user-selected | Generic Lab does not authenticate vendor-specific transcript provenance |
56
58
 
57
59
  The Lab controller is user-facing and is not an agent Skill. Never place real
58
- secrets or irreplaceable work in its fixture. See [guard-lab](guard-lab.md) for
60
+ secrets or irreplaceable work in its fixture. See [guard-lab](../lab/guard-lab.md) for
59
61
  the exact observation and report semantics.
60
62
 
61
63
  ## Experimental DSH text-read redaction
62
64
 
63
- The default-off [native read prototype](test-report-dsh-read-redaction.md)
65
+ The default-off [native read prototype](../reports/test-report-dsh-read-redaction.md)
64
66
  mediates complete text-read results in reviewed, artifact-pinned local-FS and
65
67
  DSH `0.2.0-rc.2` sandbox-FS compositions; see the
66
- [current review](test-report-release-readiness-0.2.3.md). It
68
+ [current review](../reports/test-report-release-readiness-0.2.3.md). It
67
69
  uses Core patterns, replaces structured values and regenerates model content
68
70
  and presentation metadata. Its actual AgentLoop/JSONL probe uses synthetic
69
71
  streams and establishes no real-model L2 mitigation result.
@@ -0,0 +1,104 @@
1
+ # Getting started / 入门指南
2
+
3
+ Agent Guard has three paths: recover supported destructive actions,
4
+ check disclosure before emission, and use guard-lab for controlled behaviour
5
+ experiments. Begin with the path you need; native interception is optional
6
+ and depends on the actual host.
7
+
8
+ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。先选择需要的能力;
9
+ 自动拦截另需实际宿主提供并加载兼容 hook。
10
+
11
+ ## Select the package root
12
+
13
+ The published stable baseline is 0.2.4. The current source candidate is
14
+ 0.2.5-rc1; see its [scope and status](../releases/release-notes-0.2.5-rc1.md).
15
+ Use a user-selected stable prefix for the published package:
16
+
17
+ ```sh
18
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
19
+ ```
20
+
21
+ The package root is
22
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
23
+ For the RC, select `@mokuyoaxis/agent-guard@0.2.5-rc1` explicitly and check its
24
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
25
+ or [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1)
26
+ for publication. Its reviewed checkout or local tarball is also usable.
27
+ Do not infer RC availability from the manifest or use an unscoped same-name
28
+ package. A checkout's default branch can differ from a tagged stable release.
29
+
30
+ Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
31
+ examples/bridges require a POSIX shell. The optional pinned DSH read path uses
32
+ Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
33
+ establish Windows-native hook bridge or full-suite portability.
34
+
35
+ ## Set up a coding agent
36
+
37
+ Replace the root path in this prompt, and give it to your agent:
38
+
39
+ ```text
40
+ Set up Agent Guard for this workspace using /absolute/path/to/agent-guard.
41
+ Identify the actual host version, tool names and hook/skill capabilities.
42
+ Read the README, Skill contracts and matching adapter guide; check Python/Git.
43
+ Use the selected checkout/package version and preserve existing settings.
44
+ Respect already-approved paths and configuration scope. Ask only for missing
45
+ information or changes beyond that scope, including new dependencies.
46
+ Install/reference the relevant Skills. Configure a native hook only where a
47
+ blocking event is supported; otherwise report Skill/CLI-only operation.
48
+ Claude: adapters/claude/README.md. Kimi: adapters/kimi-code/README.md.
49
+ DSH: adapters/dsh/README.md. Other hosts: adapters/INTEGRATION.md.
50
+ Verify a harmless call. Submit BLOCK-shaped commands only as data to check.py;
51
+ never execute deletion of real data as a test. For Claude/Kimi, run the local
52
+ doctor, but do not treat PASS as proof of actual host interception.
53
+ Report the host/version, installed paths, configuration scope, covered tools,
54
+ observed interception and unverified paths separately.
55
+ guard-lab is the user's controller, not a Skill to install into the tested
56
+ agent. Run real-host/model experiments only in an explicitly selected scope.
57
+ ```
58
+
59
+ 不要把“Skill 已安装”“配置检查通过”和“真实调用被拦截”合并为一个成功状态。
60
+ 用户范围外的配置或依赖改动需另行确认;已经授权的常规接入不重复询问。
61
+
62
+ ## Verify without executing a destructive command
63
+
64
+ From an isolated fixture, pass command text as data:
65
+
66
+ ```sh
67
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/check.py --json -- rm /
68
+ ```
69
+
70
+ Read the BLOCK decision. Advisory exit 0 means assessment completed, not that
71
+ the command may run. Assessment can create quarantine/audit metadata and a
72
+ Git local exclude entry. Use a disposable fixture, and see the
73
+ [assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
74
+
75
+ For Claude/Kimi, local doctor probes do not start a model:
76
+
77
+ ```sh
78
+ python3 /absolute/path/to/agent-guard/doctor.py claude --probe --json
79
+ python3 /absolute/path/to/agent-guard/doctor.py kimi --probe --json
80
+ ```
81
+
82
+ Select the actual host, not both by default. These probes check one selected
83
+ configuration and a local bridge/adapter. Real host evidence needs a separate
84
+ controlled sentinel. An explicit live sentinel may consume provider quota;
85
+ its result covers one sampled root-agent Bash call. See
86
+ [host drift](host-drift.md) and the
87
+ [capability matrix](harness-capabilities.md).
88
+
89
+ ## Try the three paths
90
+
91
+ - **Recovery:** use the [delete Skill](../../skills/delete-guard/SKILL.md).
92
+ Valuable content relocates; provably regenerable artifacts may delete
93
+ directly. Inspect txids/state after errors, including force-restore backups.
94
+ - **Disclosure:** use the [exfil Skill](../../skills/exfil-guard/SKILL.md).
95
+ A checker plan is not completed redaction. The payload owner applies the
96
+ plan, controls emission and owns any egress audit.
97
+ - **Experiments:** use the [Lab guide](../lab/guard-lab.md).
98
+ Calibrate all four built-in controls before real trials. Only an effective
99
+ unguarded baseline enables a matched mitigation comparison.
100
+
101
+ For incident recovery from surviving evidence, use
102
+ [recovery-audit](../../skills/recovery-audit/SKILL.md).
103
+ Full rules, historical reports and releases are in the
104
+ [documentation index](../README.md).
@@ -1,9 +1,14 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
+ Current source: [0.2.5-rc1 candidate](../releases/release-notes-0.2.5-rc1.md).
4
+ Rows below retain their tested source/host versions and do not automatically
5
+ certify this candidate. Local regression or package checks are separate from
6
+ new native-host/model evidence.
7
+
3
8
  The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
4
9
  host does **not** mean that host intercepts tool calls, and an adapter returning
5
10
  `BLOCK` does **not** by itself prove the host prevented execution.
6
- For an unlisted host, use the [self-adaptation guide](../adapters/INTEGRATION.md)
11
+ For an unlisted host, use the [self-adaptation guide](../../adapters/INTEGRATION.md)
7
12
  and keep its native-interception status `UNVERIFIED` until independently tested.
8
13
 
9
14
  ## Evidence levels
@@ -42,14 +47,14 @@ bounded "Enforcement observed" evidence only for that root-agent Bash call.
42
47
 
43
48
  | Host / tested version | Entry and scope | ASK mapping | Highest evidence for current path | Important gap |
44
49
  |---|---|---|---|---|
45
- | Claude Code 2.1.270 / 2.1.273 (post-0.2.0 bridge) | `PreToolUse` for `Bash`; shared Core via Python and POSIX startup bridge | Native `permissionDecision: ask` (headless runs need an approver) | Real CLI/hook with scripted model endpoint: ALLOW, BLOCK, headless ASK, injected Python failure; see [report](test-report-claude-code-harness.md) | Hook absence/timeout, Windows bridge, other tools, arbitrary subagents and real model behavior are not covered. |
46
- | DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
47
- | DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
48
- | DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS | Native ASK; Core read ASK/BLOCK withheld | [Fresh native review](test-report-release-readiness-0.2.3.md): deletion marker/audit checks, read value/content/meta, next synthetic AgentLoop request and durable JSONL; zero external model calls | Web agent activation, model-proposed destructive calls and injection L2 remain unverified. Lab admits native v4 but refuses surface replay/images; a retained real-model clean trial remains inconclusive. |
49
- | Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and a second configured model route; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | Client records identify the requested route, not the remote model weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
50
- | Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
51
- | ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
52
- | Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
50
+ | Claude Code 2.1.270 / 2.1.273 (post-0.2.0 bridge) | `PreToolUse` for `Bash`; shared Core via Python and POSIX startup bridge | Native `permissionDecision: ask` (headless runs need an approver) | Real CLI/hook with scripted model endpoint: ALLOW, BLOCK, headless ASK, injected Python failure; see [report](../reports/test-report-claude-code-harness.md) | Hook absence/timeout, Windows bridge, other tools, arbitrary subagents and real model behavior are not covered. |
51
+ | DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](../reports/test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](../reports/test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
52
+ | DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](../reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](../reports/test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
53
+ | DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS; sampled PTC SDK Bash calls | Native ASK; Core read ASK/BLOCK withheld | [0.2.3 native review](../reports/test-report-release-readiness-0.2.3.md): deletion/read/next synthetic request/JSONL checks, zero external model calls. [0.2.4 official Flash PTC](../reports/test-report-dsh-0.2.4-ptc.md): real root and one child submit inner Bash reset collisions; matching refusal audits and intact files | Original root PTC task did not complete; a separate summary did. Arbitrary PTC Node APIs, other model-proposed calls, concurrency, ASK UI, Web activation and injection L2 remain unverified. Historical pending captures remain inconclusive. |
54
+ | Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](../reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and a second configured model route; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | Client records identify the requested route, not the remote model weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
55
+ | Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](../reports/test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
56
+ | ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](../reports/test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
57
+ | Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
53
58
 
54
59
  The default adapters address destructive **shell** calls. Exfil-guard also has
55
60
  a CLI/cooperative path and the narrowly scoped, opt-in DSH text-read prototype
@@ -0,0 +1,106 @@
1
+ # Read-only trash locations / 垃圾桶只读位置查询
2
+
3
+ This is the 0.2.4 query interface for CLI, agent and future frontend
4
+ callers. It lists locations within a declared scope, without reading recovery
5
+ contents or changing storage. The published 0.2.3 artifact does not include it.
6
+
7
+ 这是 0.2.4 的查询接口,可从安装后的 CLI 或本地源码使用。
8
+ 用户可直接查看,Agent 可解释同一份结果,未来前端
9
+ 可复用相同函数/JSON。当前不提供页面或操作服务,索引地址不代表清理授权。
10
+
11
+ ## CLI
12
+
13
+ The existing status command keeps its current-project mode. Add --trash-index
14
+ for the location query; an installed command uses the same flags.
15
+
16
+ ```bash
17
+ # Default: current directory, depth 3, 10000 examined entries.
18
+ python3 skills/delete-guard/scripts/status.py --trash-index
19
+
20
+ # A specific project collection; repeated roots are allowed.
21
+ agent-guard-status --trash-index --root ~/projects --max-depth 3 --json
22
+
23
+ # Declare a custom/external bucket; with only --trash, no root is walked.
24
+ agent-guard-status --trash-index --trash /path/to/custom-store --json
25
+ ```
26
+
27
+ 默认搜索当前目录;若没有 --root 或 --trash,可纳入当前 AGENT_GUARD_TRASH
28
+ 配置。显式 --root 不附加环境中的其他位置;需要外部桶时使用 --trash。
29
+
30
+ max_depth counts directories below each root. At depth 0, the root's own
31
+ .agent-trash is still checked. Found buckets are pruned, including an explicit
32
+ root named .agent-trash. Ordinary child directory symlinks are not walked;
33
+ explicit roots/buckets may be aliases, and results deduplicate physical paths.
34
+
35
+ 默认跳过 .git、node_modules、.internal、__pycache__ 子目录。显式将这些目录
36
+ 作为 root 时会按所给范围检查。max_entries 限制检查的路径/目录项数;触及
37
+ 限制会保留部分结果并报告错误。它不是文件系统调用的墙钟超时。
38
+
39
+ No payload, transaction, byte-size or GC eligibility scan is performed.
40
+ Expected manifest/audit/state files and the sessions directory are only
41
+ lstat'ed. These are layout hints, not authenticated ownership or complete
42
+ backup evidence. A linked marker file alone is not accepted as a regular marker.
43
+
44
+ 退出码:0 完整查询;1 部分结果(读取/路径/预算错误);2 参数错误。
45
+ complete 只指声明深度、排除项和范围内的读取完成,不代表全机覆盖或原子快照。
46
+
47
+ ## Shared backend hook
48
+
49
+ ```python
50
+ from core.trash_index import list_trash_locations
51
+
52
+ result = list_trash_locations(
53
+ ["/path/to/projects"],
54
+ trash_paths=["/path/to/custom-store"],
55
+ max_depth=3,
56
+ max_entries=10000,
57
+ )
58
+ ```
59
+
60
+ Provide a sequence of text paths or Path objects. The function validates
61
+ limits and paths before traversal and raises ValueError for invalid input.
62
+ It has no environment-selected default roots; the CLI supplies its context.
63
+ It creates no layout, modifies no Git metadata, writes no audit and constructs
64
+ no RecoveryEngine. Backend callers must choose their own trusted scope.
65
+
66
+ ## JSON schema version 1
67
+
68
+ | Field | Meaning |
69
+ |---|---|
70
+ | schema_version | 1; callers should tolerate additive fields |
71
+ | roots / trash_paths | Normalized absolute search roots / declared buckets |
72
+ | max_depth / max_entries | Requested bounds |
73
+ | excluded_dirs | Names pruned below roots |
74
+ | examined | Charged paths/directory entries, bounded by max_entries |
75
+ | complete | No read/path/budget errors within the declared scope |
76
+ | count | Unique location candidates, including unconfirmed/unreadable rows |
77
+ | identified_count | Rows with status metadata_present |
78
+ | entries | Deterministically ordered rows |
79
+ | errors | Partial-query errors as path + static code |
80
+
81
+ Each row contains trash_root (first sorted location spelling),
82
+ resolved_trash_root, directory (that spelling's parent), locations (all
83
+ encountered aliases), sources (declared/discovered) and status.
84
+ directory is a location hint, not verified workspace ownership.
85
+
86
+ | Status | Meaning |
87
+ |---|---|
88
+ | metadata_present | At least one expected regular marker file or sessions directory exists |
89
+ | unconfirmed | A named/declared directory exists, but no usable marker was found |
90
+ | unreadable | Marker inspection failed; identification is unknown |
91
+
92
+ Error codes: NOT_FOUND, NOT_DIRECTORY, PERMISSION_DENIED, IO_ERROR,
93
+ ENTRY_LIMIT_REACHED. Errors contain paths but no raw OS exception text.
94
+ Missing or non-directory requested locations appear in errors and are not
95
+ counted. Concurrent filesystem changes can affect a query snapshot.
96
+
97
+ ## Agent and future UI usage
98
+
99
+ 用户问“有哪些垃圾桶/有多少/在哪”时,Agent 应按当前目录或用户指定范围
100
+ 查询,分别报告候选数量、布局识别数量和错误。无法检查不能说成不存在;自己
101
+ 补查的信息应区分来源。Native status tools that lack index flags remain
102
+ current-project tools; invoke this CLI for a cross-project location query.
103
+
104
+ 未来只读界面直接读取上述 JSON。恢复或清理应走独立操作入口,重新验证可信
105
+ workspace、trash、事务、当前路径和权限;不能将扫描地址或缓存 JSON 当作授权。
106
+ 本接口不改变分散存储布局,也不读取配置或恢复文件中的秘密值。
@@ -105,7 +105,7 @@ Collapsing these labels makes a green build look stronger than the evidence
105
105
  supports. A trustworthy recovery therefore needs an evidence ledger, replay
106
106
  reports, deterministic reruns, and explicit gap markers.
107
107
 
108
- These requirements became the [`recovery-audit`](../skills/recovery-audit/SKILL.md)
108
+ These requirements became the [`recovery-audit`](../../skills/recovery-audit/SKILL.md)
109
109
  Skill. It complements `delete-guard` and `exfil-guard`:
110
110
 
111
111
  ```text
@@ -153,7 +153,7 @@ after an incident -> recovery-audit
153
153
 
154
154
  The project should continue to describe itself as reliability infrastructure
155
155
  with human escalation, not as a boundary against a malicious or fully
156
- privileged process. See [`docs/threat-model.md`](threat-model.md).
156
+ privileged process. See [`docs/design/threat-model.md`](../design/threat-model.md).
157
157
 
158
158
  ## 7. Public evidence policy
159
159
 
@@ -4,6 +4,13 @@ This log records findings from host trials, CLI checks and regression tests.
4
4
  The initial entries came from a DSH session using `tools/pre-execute`, three
5
5
  model tools and a prompt section; later entries cover Core and other adapters.
6
6
 
7
+ Entries preserve their recording date and original candidate/release state.
8
+ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
9
+ F26–F31 are now included in the 0.2.5-rc1 source candidate, with publication
10
+ still separate. Current version scope is in the
11
+ [candidate notes](../releases/release-notes-0.2.5-rc1.md); historical failures and
12
+ test counts below are not rewritten by a later success.
13
+
7
14
  ## F1 · Compound `cd X && rm y` resolves targets against the wrong base
8
15
 
9
16
  The interceptor classifies against the tool call's declared workdir. A
@@ -423,3 +430,119 @@ and the legacy broad sk- format has no complete issuance contract established
423
430
  in this review. Those boundaries retain protection and remain explicit review
424
431
  items. The narrowed structural rules do not certify a token's signature,
425
432
  claims, actual issuance or authorization.
433
+
434
+ ## F24 · Hard reset could destroy content outside the tracked snapshot
435
+
436
+ A tracked-only stash does not contain untracked or ignored bytes. Git can
437
+ remove those bytes when the reset target replaces a file or an ancestor
438
+ directory, including quarantine storage. The 2026-10-05 independent review
439
+ reproduced this with disposable fixtures; no user worktree was reset.
440
+
441
+ **Fixed in 0.2.4:** read-only preflight checks the target tree
442
+ against untracked/ignored paths before compensation. Collisions yield
443
+ `BLOCK_GIT_RESET_COLLISION`; incomplete enumeration, submodules and unsupported
444
+ compound/wrapper contexts yield `BLOCK_UNDETERMINABLE_EFFECT`. Supported
445
+ standalone collision-free reset still snapshots tracked changes first.
446
+ There is no automatic untracked archive. Regression:
447
+ `tests/test_git_reset_safety.py` (30 cases) and two added policy cases.
448
+
449
+ This deliberately tightens default behavior and adds a reason string.
450
+ The maintainer-selected 0.2.4 patch exception is recorded in the
451
+ [compatibility contract](../design/compatibility.md#024-maintenance-patch-exception).
452
+
453
+ ## F25 · Restore trusted paths and removed an occupied destination before recovery
454
+
455
+ A changed parent symlink could redirect a recorded source or destination;
456
+ transaction IDs and directories also needed containment checks. Forced
457
+ restore removed the current occupant before attempting recovery, so a later
458
+ move failure could lose the current version.
459
+
460
+ **Fixed in 0.2.4:** restore preflights the selected workspace,
461
+ transaction directory and source parent chains, then checks each item again.
462
+ Final symlinks retain their own location semantics. Force cannot override
463
+ containment; an occupied destination is preserved in a normal relocation
464
+ transaction before recovery. Preservation failure stops that item. Returned
465
+ `backup_txids` includes attempted backups, not a guarantee that each completed.
466
+ Journal/audit errors preserve the filesystem report and IDs for inspection.
467
+
468
+ Regression: `tests/test_restore_boundary.py` (14),
469
+ `tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
470
+ These are sequential checks, not atomic same-UID isolation; cross-device
471
+ copy failures can leave partial data requiring inspection.
472
+
473
+ ## F26 · Housekeeping overrode quarantine control protection
474
+
475
+ The classifier already marked the quarantine root protected, but the policy's
476
+ inside-trash allowance ran first. Root manifest/audit/state paths were also
477
+ treated as ordinary content, and a regenerable parent could contain storage.
478
+
479
+ **Fixed in local unreleased maintenance (2026-10-08):** protected-path decisions
480
+ precede trash housekeeping. Root controls, session state and in-workspace
481
+ storage access parents are classified explicitly, including parent aliases
482
+ and a control leaf link. Ordinary payload rules and explicit transaction GC
483
+ remain available. Opaque quarantine globs return `BLOCK_WILDCARD` before
484
+ housekeeping, because their expansion could include root control files.
485
+ This addresses supported deletion mistakes; arbitrary
486
+ scripts/writes and malicious same-UID tampering remain outside the guarantee.
487
+
488
+ ## F27 · Purged history remained GC eligible
489
+
490
+ Age planning reselected tombstoned transactions even after their directories
491
+ were removed. Active inventory now excludes `PURGED` entries before walking
492
+ or accounting their directories. History remains intact; recreated directories
493
+ are not claimed again. Failed purges remain active. This local maintenance
494
+ does not implement pruning retained Git stashes or rewrite old manifests.
495
+
496
+ ## F28 · Restore audit duplicated paths and failure bodies
497
+
498
+ The CLI copied restoration/conflict paths and arbitrary move errors into
499
+ non-recovery audit metadata. Local maintenance stores outcome counts and
500
+ transaction associations instead. Unknown/invalid input IDs are hashed;
501
+ recovery journal paths and CLI results remain exact. Generic audit append,
502
+ automatic session metadata and other output paths are separate work.
503
+
504
+ ## F29 · Exemption format and loading failures were silent
505
+
506
+ Both configuration filenames use a limited section/key parser, but the
507
+ `.agent-guardignore` name suggested gitignore syntax. Bare lines were silently
508
+ ignored, load failures silently tried the next file, and a readable empty or
509
+ malformed preferred file hid the fallback. Nonstandard legacy section keys
510
+ could also remain effective without an explanation.
511
+
512
+ Local unreleased maintenance (2026-10-08) reports the selected fixed relative
513
+ source, configured entry counts and bounded static diagnostics. Checker JSON
514
+ and sanitizer library results carry the metadata; human checker/sanitizer
515
+ warnings use stderr. Raw keys, patterns, hashes, lines and exception text
516
+ are withheld. Legacy matching, precedence, verdicts, exit codes and payload/
517
+ plan stdout formats are retained. This does not add gitignore parsing,
518
+ change configuration authority or sanitize other audit/output writers.
519
+
520
+ ## F30 · Assessment audit writes were mistaken for zero-write checks
521
+
522
+ Advisory check and safe_delete dry-run preserve command targets but use the
523
+ existing audit path, which can initialize quarantine metadata and Git local
524
+ exclude. A test named "touches nothing" checked target presence and Git status,
525
+ which cannot detect an ignored audit directory. Blocked-request documentation
526
+ also described the entire filesystem as untouched.
527
+
528
+ Local contract clarification (2026-10-08) adds explicit target/metadata and
529
+ failure regressions, corrects help/guidance, and documents early no-match and
530
+ existing-ignore/external-bucket exceptions. Best-effort assessment audits and
531
+ durable enforced intents retain their existing behavior. No zero-write CLI
532
+ flag, audit relocation or unrelated writer minimization is introduced.
533
+
534
+ ## F31 · safe_delete duplicated paths and free-form reasons into audit
535
+
536
+ safe_delete copied concrete targets, policy reason bodies and caller
537
+ `--reason` text into decision/outcome audit events. Its transaction metadata
538
+ also copied `--reason`, although restoration only needs the journal's exact
539
+ origin/trash paths. A secret-bearing filename or an arbitrary private note
540
+ therefore gained additional durable copies beyond the recovery journal.
541
+
542
+ Local minimization (2026-10-08) builds this writer's events from decisions,
543
+ codes, counts and established recovery IDs; partial/storage-failure reports
544
+ retain transaction correlation. Free-form reason metadata is omitted.
545
+ Exact CLI/recovery paths and error diagnostics remain available, with the
546
+ same mutation-intent durability and assessment/outcome failure behavior.
547
+ Historical records, automatic session identity and other audit/output
548
+ writers remain outside this change.