@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.
- package/README.md +158 -571
- package/README.zh-CN.md +133 -490
- package/SECURITY.md +53 -0
- package/adapters/INTEGRATION.md +8 -6
- package/adapters/claude/README.md +3 -3
- package/adapters/claude/harness/README.md +1 -1
- package/adapters/codex/harness/README.md +2 -2
- package/adapters/dsh/README.md +17 -6
- package/adapters/dsh/harness/README.md +8 -8
- package/adapters/dsh/harness/guard_lab.py +3 -3
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +7 -7
- package/adapters/kimi-code/harness/README.md +3 -3
- package/adapters/kimi-code/harness/guard_lab.py +1 -1
- package/assets/linux-do-community.svg +19 -0
- package/core/__init__.py +1 -1
- package/core/classifier.py +66 -17
- package/core/policy.py +28 -13
- package/core/recovery.py +261 -24
- package/core/redaction.py +122 -21
- package/core/trash_index.py +193 -0
- package/docs/README.md +113 -0
- package/docs/{architecture.md → design/architecture.md} +51 -12
- package/docs/{compatibility.md → design/compatibility.md} +124 -4
- package/docs/{threat-model.md → design/threat-model.md} +10 -8
- package/docs/guides/getting-started.md +104 -0
- package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +14 -9
- package/docs/guides/trash-index.md +106 -0
- package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
- package/docs/{friction.md → history/friction.md} +123 -0
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +15 -13
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
- package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
- package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
- package/docs/releases/release-notes-0.2.4.md +89 -0
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
- package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
- package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
- package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
- package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
- package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
- package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
- package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
- package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
- package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
- package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
- package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +80 -7
- package/skills/delete-guard/references/policy.md +104 -8
- package/skills/delete-guard/scripts/check.py +22 -0
- package/skills/delete-guard/scripts/restore.py +34 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/delete-guard/scripts/status.py +52 -0
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +9 -2
- package/skills/exfil-guard/references/rules.md +83 -6
- package/skills/exfil-guard/scripts/_payload.py +20 -0
- package/skills/exfil-guard/scripts/check_span.py +5 -1
- package/skills/exfil-guard/scripts/sanitize.py +6 -3
- /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
- /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
- /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
- /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
- /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
- /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
- /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
- /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
- /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
- /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](
|
|
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.
|
|
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:
|
|
14
|
-
|
|
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 |
|
|
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 |
|
|
34
|
-
| 7 | Destructive restore |
|
|
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](
|
|
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 | [
|
|
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](
|
|
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`](
|
|
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.
|