@mokuyoaxis/agent-guard 0.2.4 → 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.
@@ -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,10 +29,10 @@ 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 |
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 |
34
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
 
@@ -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,5 +1,10 @@
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.
@@ -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
@@ -462,3 +469,80 @@ Regression: `tests/test_restore_boundary.py` (14),
462
469
  `tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
463
470
  These are sequential checks, not atomic same-UID isolation; cross-device
464
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.
@@ -4,7 +4,9 @@
4
4
  observable agent and harness behaviours. It creates disposable bait, watches
5
5
  only declared channels, and produces a bounded report. Its built-in controls
6
6
  call no model; its separate manual probe is designed for a user-run real
7
- harness trial. The first implementation is the `0.2.3-rc2` source candidate.
7
+ harness trial. It was introduced in `0.2.3-rc2` and shipped with `0.2.3`.
8
+ It remains available in stable `0.2.4` and the `0.2.5-rc1` source candidate;
9
+ this candidate's documentation update does not add new model-trial evidence.
8
10
 
9
11
  It is not a Skill for the tested agent, a security boundary, or a certificate
10
12
  that a model or vendor is safe or malicious.
@@ -0,0 +1,91 @@
1
+ # Agent Guard 0.2.5-rc1
2
+
3
+ Maintenance prerelease candidate, prepared 2026-10-08. The stable baseline
4
+ remains [0.2.4](release-notes-0.2.4.md). The release workflow maps this exact
5
+ RC to a GitHub prerelease and npm `rc`, preserving stable `latest` and the
6
+ original 0.2.4 tag/artifact. Publication receipts are the
7
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
8
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1).
9
+
10
+ 本候选合并 10-08 已完成的维护与本轮文档整理,不是仅修改 README。
11
+ 版本由维护者明确选择为 0.2.5-rc1,并授权 GitHub/npm 双推;稳定版范围仍另行决定。
12
+
13
+ ## Changes
14
+
15
+ - **Quarantine controls before housekeeping.** Existing
16
+ `BLOCK_PROTECTED_PATH` wins for root/control files, session state and
17
+ in-workspace storage parents, including reviewed aliases. Opaque quarantine
18
+ globs are refused; safe_delete can enumerate an explicit batch. Ordinary
19
+ unprotected payload housekeeping and validated explicit transaction GC
20
+ remain available.
21
+ - **PURGED history stays out of active GC inventory.** Tombstoned transactions
22
+ are excluded before payload accounting/planning. Historical manifests
23
+ remain intact, failed purges remain active, and this does not prune retained
24
+ Git stashes or claim ownership of recreated directories.
25
+ - **Restore and safe_delete audit minimization.** New writer events retain
26
+ decisions, counts and recovery associations instead of duplicating paths
27
+ and arbitrary error/reason bodies. safe_delete still accepts `--reason`
28
+ but does not persist its text in new audit/transaction metadata.
29
+ CLI results and essential recovery paths/intents stay exact. Old records,
30
+ generic audit writers and automatic session metadata are unchanged.
31
+ - **Exemption configuration diagnostics.** The existing limited parser,
32
+ first-readable-file priority and matching are retained. Checker JSON and
33
+ sanitizer library results gain provenance/count/diagnostic metadata;
34
+ human CLI warnings use stderr. Normal absent/valid configurations stay
35
+ quiet. No full TOML/gitignore parser or configuration migration is added.
36
+ - **Assessment contract.** Advisory checks and deletion dry-runs preserve
37
+ targets while potentially writing metadata/exclude entries. Advisory exit 0
38
+ does not authorize BLOCK/ASK. This is clarification and regression coverage,
39
+ not a new zero-write assessment flag.
40
+ - **Documentation.** Both READMEs introduce recovery protection, disclosure
41
+ checks and guard-lab near the top, with setup moved to a dedicated guide.
42
+ Current contracts distinguish planned emitter/audit integrations from
43
+ implemented CLIs, local metadata from optional provider calls, and observed
44
+ host evidence from candidate validation. Historical results retain their
45
+ original dates, failures and scope.
46
+ - **Documentation resources in the npm package.** Include SECURITY.md and
47
+ the existing community banner assets, which the previous allowlist omitted.
48
+ Runtime entry points and dependency requirements are unchanged.
49
+
50
+ ## Compatibility and version choice
51
+
52
+ Control-path/glob changes make some previously allowed shapes refuse by
53
+ default. The usual 0.x contract classifies that as minor. The maintainer
54
+ explicitly chose 0.2.5-rc1 instead of 0.3.0 as a bounded maintenance exception.
55
+ The prior 0.2.4 exception is not reused as blanket permission.
56
+ See the [compatibility contract](../design/compatibility.md#025-rc1-lifecycle-and-restore-audit-maintenance-source-candidate).
57
+
58
+ Existing decision/reason strings, CLI arguments and exit-code roles remain.
59
+ Consumers should tolerate additive optional fields and stderr diagnostics.
60
+ Audit shapes outside essential recovery manifests are not frozen.
61
+ No production dependency, storage migration, new transaction strategy or
62
+ general output enforcement is introduced. Later stable 0.2.5 scope and
63
+ publication remain separate decisions.
64
+
65
+ ## Evidence and limits
66
+
67
+ Before this version/documentation pass, the combined maintenance worktree
68
+ passed 874 Python tests and both Node adapter smoke groups, plus package,
69
+ offline install and a synthetic deletion/restore round trip. The first full
70
+ run retained one DSH Lab observer-startup timeout; the single-case recheck and
71
+ full rerun passed without changing its timeout. Its root cause remains unknown.
72
+ These are prior-source checkpoints, not this versioned candidate's release gate.
73
+
74
+ The versioned regression checkpoint passed 874 Python tests (821.138 seconds)
75
+ and both Node adapter smoke groups. It preserved 173 public source files
76
+ throughout the run. Afterwards only documentation and the packaging allowlist
77
+ for the two existing resources above changed; runtime code and test cases
78
+ retain those tested bytes. The final metadata/corpus checks, package contents,
79
+ offline installation, documented example and installed Lab calibration are
80
+ verified separately: 13 metadata/corpus checks, a 122-file tarball and offline
81
+ install, all 10 CLI help commands, adapter import, the documented example,
82
+ read-only trash query, a synthetic deletion/restore round trip and all four
83
+ zero-model Lab controls passed. These local checks do not establish publication.
84
+ No new model or native-host trial is started. Existing bounded DSH/PTC and
85
+ Kimi reports do not certify this new candidate. Historical unfinished pairs
86
+ remain pending; quiet or unhealthy baselines do not establish Lab mitigation.
87
+ Concurrency isolation, same-UID control-plane protection, universal egress
88
+ coverage and full Windows-native harness E2E remain outside the guarantee.
89
+
90
+ 发布流程要求精确提交的远端 CI、npm 凭据门禁与两个渠道的工件核查;
91
+ 本地打包通过不能替代这些步骤,具体执行结果以对应 Actions 和发布工件为准。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.4",
4
- "description": "Harness-neutral reliability infrastructure for AI coding agents: reversible destructive actions, pre-emission redaction, recovery evidence, and a shared Decision Protocol with optional native adapters.",
3
+ "version": "0.2.5-rc1",
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",
7
7
  "exports": {
@@ -32,11 +32,13 @@
32
32
  "core",
33
33
  "skills",
34
34
  "docs",
35
+ "assets",
35
36
  "doctor.py",
36
37
  "live_sentinel.py",
37
38
  "guard_lab.py",
38
39
  "LICENSE",
39
40
  "CONTRIBUTING.md",
41
+ "SECURITY.md",
40
42
  "README.md",
41
43
  "README.zh-CN.md",
42
44
  "!**/__pycache__/**",
@@ -16,19 +16,22 @@ enforces and how to work with it productively. The four pillars:
16
16
 
17
17
  - **Scope** - you act inside the workspace; the workspace root, `.git`, and
18
18
  everything outside are never yours to delete.
19
- - **Recoverability** - deletions are compensated (relocated to `.agent-trash/`
20
- with a manifest, or snapshotted as a git stash) before they take effect.
19
+ - **Recoverability** - supported valuable deletions relocate to the selected
20
+ quarantine with a manifest; supported Git overwrites snapshot tracked state.
21
+ Provably regenerable, ignored artifacts may be deleted directly.
21
22
  - **Authorization** - a human decides permission boundaries. You can be
22
23
  *downgraded* to RESTRICTED mode; you can never promote yourself back.
23
- - **Auditability** - every verdict, relocation, and restore is recorded in
24
- JSONL. Nothing is invisible.
24
+ - **Auditability** - supported writers record decision/recovery metadata in
25
+ JSONL according to their CLI contract. Mutation intents must be durable;
26
+ assessment/blocked audit may be best effort, and early no-op paths may not
27
+ write an audit. Calls outside the covered path are not automatically visible.
25
28
 
26
29
  ## The one rule
27
30
 
28
31
  **Prefer `safe_delete` over `rm`.** It applies the guard's recovery policy.
29
32
 
30
33
  ```bash
31
- # delete files/dirs/globs - they are quarantined, not destroyed:
34
+ # delete explicit targets; valuable content is quarantined:
32
35
  python3 <repo>/skills/delete-guard/scripts/safe_delete.py src/old_module.py
33
36
  python3 <repo>/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
34
37
 
@@ -64,8 +67,9 @@ redirections) before destroying them (F2), is refused as undeterminable.
64
67
  Run deletions as standalone commands with an explicit workdir.
65
68
 
66
69
  A block is not an error to route around. Retrying the same operation in a
67
- disguised form (`/bin/rm`, `python -c`, a script) is a violation of the
68
- authorization pillar and is recorded in the audit log.
70
+ disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
71
+ can bypass both protection and audit. Do not treat a missing audit as proof
72
+ that no operation occurred.
69
73
 
70
74
  `git reset --hard [commit]` first checks whether its target tree would
71
75
  overwrite untracked or ignored content. A tracked-only stash cannot recover
@@ -89,6 +93,25 @@ stop immediately. Inspect both the origin and `.agent-trash/`; never infer
89
93
  that an error means no filesystem change occurred. A durable
90
94
  `relocate-intent` can keep an interrupted relocation discoverable.
91
95
 
96
+ ## Assessment and preflight
97
+
98
+ Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets,
99
+ but may create quarantine/audit metadata and a Git local exclude rule.
100
+ They are not zero-write filesystem checks. Advisory exit 0 means the
101
+ assessment completed; inspect the decision and never execute a BLOCK/ASK
102
+ command merely because the exit was zero. Blocked safe_delete still exits 2
103
+ under dry-run. Audit warnings do not imply that all metadata writes were
104
+ undone. Use only a disposable fixture when verifying this behavior; the
105
+ [policy reference](references/policy.md#assessment-and-dry-run-side-effects)
106
+ defines the no-match, existing-ignore and external-bucket branches.
107
+
108
+ In the 0.2.5-rc1 source candidate, new `safe_delete` audit events record decisions, target counts and established
109
+ recovery IDs/counts rather than target paths or free-form reasons. `--reason`
110
+ is still accepted, but its text is not persisted in audit or transaction
111
+ metadata. Exact recovery paths remain in the CLI result and manifest.
112
+ Historical records and automatic session metadata are unchanged; see the
113
+ [policy reference](references/policy.md#safe_delete-audit-metadata).
114
+
92
115
  ## Quarantine location queries
93
116
 
94
117
  When the user asks where quarantines are or how many exist, use the shared
@@ -111,6 +134,13 @@ read just to answer a location/count question.
111
134
 
112
135
  ## RESTRICTED mode
113
136
 
137
+ The 0.2.5-rc1 source candidate protects the quarantine root, root manifest,
138
+ audit/state files, state temp file, sessions tree and storage access parents.
139
+ Housekeeping does not override those checks. Use the existing explicit
140
+ `gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
141
+ Ordinary unprotected payload housekeeping retains its existing policy.
142
+ GC plans omit `PURGED` history; they do not delete stored Git stashes.
143
+
114
144
  After a human veto, the session runs with narrowed powers: explicit
115
145
  single-file deletes inside the workspace still work (quarantined as usual);
116
146
  recursive deletes, globs, and destructive git operations are refused. Only a
@@ -144,3 +174,8 @@ space and remain subject to its existing explicit GC policy.
144
174
 
145
175
  See `references/policy.md` for the complete rule table, verdict codes, and
146
176
  manifest format.
177
+
178
+ The candidate's restore audit records counts and transaction associations rather
179
+ than duplicate paths/error text. CLI results and recovery manifests still
180
+ contain the exact data needed to inspect and restore; a failed CLI result
181
+ must still be checked against the filesystem and preservation attempts.
@@ -1,6 +1,13 @@
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 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.
4
11
 
5
12
  ## Decision Protocol
6
13
 
@@ -25,6 +32,41 @@ RESTRICTED prohibitions) are policy violations and never askable.
25
32
 
26
33
  check.py exit codes: 0 proceed/advisory-ok · 2 blocked · 3 ask · 1 error.
27
34
 
35
+ ### Assessment and dry-run side effects
36
+
37
+ Advisory `check.py` and `safe_delete.py --dry-run` keep command targets
38
+ unchanged. They do not execute the assessed shell text, relocate targets,
39
+ create Git stashes or create recovery transactions. They may still write
40
+ metadata through their existing best-effort audit path:
41
+
42
+ | Invocation | Exit / target behavior | Possible metadata writes |
43
+ |---|---|---|
44
+ | Advisory `check.py`, including ALLOW, ASK or BLOCK | Exit 0 with the actual decision; targets unchanged | Layout initialization and an appended `check` audit |
45
+ | `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 |
46
+ | Policy-blocked `safe_delete.py` before compensation, including dry-run | Exit 2; targets unchanged | Best-effort blocked-decision audit |
47
+ | Unmatched-glob-only `safe_delete.py` | Exit 0 before layout/audit setup | None from that invocation |
48
+ | Non-dry-run `safe_delete.py` with an absent literal / ALLOW_NOOP | Exit 0 without mutation or layout setup | None from that invocation |
49
+
50
+ Layout initialization may create the selected quarantine directory and
51
+ `audit.jsonl`. If a quarantine inside a Git workspace is not already ignored,
52
+ it may append an ignore entry to Git's local `info/exclude`, including the
53
+ resolved exclude path of a linked worktree. It does not edit tracked
54
+ `.gitignore`. A preexisting ignore rule or an external bucket avoids that
55
+ exclude write. Repeated checks append audit lines without duplicating the
56
+ exclude rule; recovery manifests and authorization state are not created by
57
+ these assessment paths. Git status may hide metadata that was previously
58
+ untracked, so an unchanged Git status alone does not prove zero writes.
59
+
60
+ If audit/layout setup fails, assessments retain their decision and report
61
+ an audit warning; partial metadata changes may remain. `ensure_layout`
62
+ establishes the Git ignore rule before creating the bucket. Audit failure
63
+ after that step does not roll it back. This best-effort behavior is distinct
64
+ from enforced execution/ASK intents, which must be durable or execution is
65
+ refused. Advisory exit 0 must never be treated as authorization to run a
66
+ BLOCK or ASK command. Failed real compensations can leave partial target
67
+ changes and recovery IDs; this table does not promise rollback for them.
68
+ No general zero-write assessment flag is introduced.
69
+
28
70
  ### Dialects
29
71
 
30
72
  `check.py` lexes the command line for a shell dialect: `--dialect posix`
@@ -46,6 +88,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
46
88
 
47
89
  ## Rule table (first match wins)
48
90
 
91
+ The quarantine control-path changes below belong to the 0.2.5-rc1 source candidate;
92
+ the published 0.2.4 artifact retains its original housekeeping order.
93
+
49
94
  | # | Condition | Verdict code | Effect |
50
95
  |---|---|---|---|
51
96
  | 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
@@ -53,9 +98,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
53
98
  | 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
99
  | 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
100
  | 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) |
101
+ | 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 |
102
+ | 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
103
  | 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
58
- | 5 | target is workspace root or `.git` (any depth) | `BLOCK_PROTECTED_PATH` | refuse |
59
104
  | 6 | any glob target | `BLOCK_WILDCARD` | refuse; use safe_delete which enumerates |
60
105
  | 7 | RESTRICTED mode, git/remote destructive op | `BLOCK_RESTRICTED_MODE` | refuse |
61
106
  | 8 | RESTRICTED mode, fs delete | narrow files only -> `RELOCATE_NARROW`, else `BLOCK_RESTRICTED_MODE` | refuse or quarantine |
@@ -133,6 +178,44 @@ Soft policy: 30-day retention, 5 GiB cap. Thresholds only MARK transactions
133
178
  `QUARANTINED -> RESTORABLE -> GC_ELIGIBLE -> PURGED`; the audit log itself
134
179
  is never garbage-collected.
135
180
 
181
+ Local maintenance excludes `PURGED` tombstones from active GC inventory and
182
+ age/capacity plans. History remains in the manifest and transaction listing;
183
+ a directory recreated under a purged ID is unmanaged. Failed purges retain
184
+ their prior state and can still be planned. This does not add stash pruning.
185
+
186
+ Restore audit metadata now records `restored_count`, `conflict_count` and
187
+ `error_count` instead of raw path arrays/error bodies. Known `txid`, `force`,
188
+ `ok` and preservation `backup_txids` retain correlation; invalid/unknown input
189
+ 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
+
193
+ ### safe_delete audit metadata
194
+
195
+ New `safe_delete` audit events keep `event`, `tool`, `decision`, `code` and
196
+ `target_count`, plus `phase`/static `outcome` where applicable. Established
197
+ relocation reports add `txid`, `moved_count` and `skipped_count`, including
198
+ partial relocation and storage-failure decisions. `target_count` counts
199
+ classified entries after glob expansion, including absent literals and
200
+ unresolved/rejected entries in a BLOCK assessment; it is not a count of
201
+ existing or deletable files. Unmatched patterns are excluded; duplicate
202
+ input entries remain separate entries.
203
+ `skipped_count` counts the engine's skipped entries, not every target left
204
+ unmoved after a storage failure.
205
+
206
+ Target arrays, policy reason bodies, free-form `--reason` and moved/skipped
207
+ payloads are not copied into these events. `--reason` remains accepted but
208
+ its text is no longer persisted in the audit or `tx-start.meta`. Exact
209
+ origin/trash paths, write-ahead relocation records and failure diagnostics
210
+ stay in the recovery manifest; CLI target/recovery paths and errors stay
211
+ accurate. Those surfaces can still contain sensitive text.
212
+
213
+ Mutation intents remain durable before deletion; assessment and outcome
214
+ 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
+
136
219
  Authority model: `gc.py --execute` is intentionally permitted
137
220
  non-interactively (scheduled maintenance is legitimate; purging
138
221
  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.
@@ -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: