@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +127 -83
  2. package/README.zh-CN.md +106 -74
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +24 -15
  8. package/adapters/dsh/harness/README.md +75 -19
  9. package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
  10. package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
  11. package/adapters/dsh/harness/guard_lab.py +194 -32
  12. package/adapters/dsh/harness/native_session.py +41 -20
  13. package/adapters/dsh/harness/profiles.py +74 -22
  14. package/adapters/dsh/lib/index.js +1 -1
  15. package/adapters/kimi-code/README.md +15 -14
  16. package/adapters/kimi-code/harness/README.md +3 -3
  17. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  18. package/core/__init__.py +1 -1
  19. package/core/classifier.py +41 -16
  20. package/core/lab.py +24 -1
  21. package/core/policy.py +11 -4
  22. package/core/recovery.py +256 -23
  23. package/core/redaction.py +157 -55
  24. package/core/trash_index.py +193 -0
  25. package/docs/README.md +104 -0
  26. package/docs/{architecture.md → design/architecture.md} +31 -6
  27. package/docs/{compatibility.md → design/compatibility.md} +54 -4
  28. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  29. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  30. package/docs/guides/trash-index.md +106 -0
  31. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +8 -9
  32. package/docs/{friction.md → history/friction.md} +107 -4
  33. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +23 -22
  34. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +6 -4
  35. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +19 -15
  36. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  37. package/docs/{guard-lab.md → lab/guard-lab.md} +18 -11
  38. package/docs/lab/tasks/guard-lab-read-trial-task.md +7 -0
  39. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +5 -5
  40. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +7 -7
  41. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  42. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +9 -10
  43. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +4 -2
  44. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  45. package/docs/releases/release-notes-0.2.3.md +84 -0
  46. package/docs/releases/release-notes-0.2.4.md +89 -0
  47. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  48. package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
  49. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  50. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  51. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  52. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  53. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  54. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  55. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  56. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
  57. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  58. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
  59. package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
  60. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
  61. package/package.json +1 -1
  62. package/skills/delete-guard/SKILL.md +40 -3
  63. package/skills/delete-guard/references/policy.md +18 -5
  64. package/skills/delete-guard/scripts/check.py +19 -0
  65. package/skills/delete-guard/scripts/restore.py +18 -6
  66. package/skills/delete-guard/scripts/status.py +52 -0
  67. package/skills/exfil-guard/SKILL.md +37 -7
  68. package/skills/exfil-guard/references/channels.md +1 -1
  69. package/skills/exfil-guard/references/rules.md +84 -16
  70. package/skills/exfil-guard/scripts/_payload.py +99 -0
  71. package/skills/exfil-guard/scripts/check_span.py +14 -81
  72. package/skills/exfil-guard/scripts/sanitize.py +113 -34
  73. package/docs/release-notes-0.2.3.md +0 -45
  74. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  75. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  76. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  77. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  78. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  79. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  80. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  81. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -36,7 +36,7 @@ becomes a BLOCK verdict, never a guess.
36
36
  This diagram shows a supported native adapter path. An explicit CLI caller
37
37
  joins at `check.py`, skipping the adapter prefilter. Neither path implies that
38
38
  every harness or tool call is intercepted. Exfil-guard's cooperative text CLI
39
- is separate; see [harness capabilities](harness-capabilities.md).
39
+ is separate; see [harness capabilities](../guides/harness-capabilities.md).
40
40
 
41
41
  ```
42
42
  shell command (from a supported native adapter)
@@ -119,11 +119,11 @@ a harness-owned background sidecar.
119
119
 
120
120
  This layout separates accidental access in the intended workflow, not OS
121
121
  privileges. A same-UID adversary can inspect or alter both sides. See
122
- [guard-lab](guard-lab.md) for the evidence semantics and unsupported channels.
122
+ [guard-lab](../lab/guard-lab.md) for the evidence semantics and unsupported channels.
123
123
 
124
124
  ## Opt-in DSH text-read boundary
125
125
 
126
- The [experimental read prototype](test-report-dsh-read-redaction.md) adds a
126
+ The [experimental read prototype](../reports/test-report-dsh-read-redaction.md) adds a
127
127
  separate post-execute path for reviewed, artifact-pinned native text-read
128
128
  contracts (local FS and DSH `0.2.0-rc.2` sandbox FS):
129
129
  native complete read value → bounded Python stdin worker → existing Core
@@ -134,7 +134,7 @@ reviewed deletion-only Lab profiles keep this path disabled.
134
134
 
135
135
  Native validation uses the actual read, AgentLoop and JSONL backend with a
136
136
  deterministic synthetic stream; it checks next-request content and durable
137
- metadata too; the [current review](test-report-release-readiness-0.2.3.md)
137
+ metadata too; the [current review](../reports/test-report-release-readiness-0.2.3.md)
138
138
  records both new-host providers. Pagination, custom finalizers/unreviewed providers, PTC, other tools and
139
139
  events before this hook remain outside this boundary. No real-model L2
140
140
  evidence follows from the zero-model probe.
@@ -242,9 +242,24 @@ FORBIDDEN (BLOCK, never askable).
242
242
  *snapshot* (`stash create` without touching the tree). Both produce a
243
243
  txid recorded in manifest + audit. Future compensations (database
244
244
  backup/PITR, cloud snapshot) plug into the same slot.
245
+ Hard reset first compares its target tree with untracked and ignored
246
+ paths. Collisions are blocked because the tracked-only stash cannot
247
+ protect them; no automatic untracked archive is created in this version.
245
248
  4. **Restore is non-destructive.** It refuses to overwrite existing origin
246
- paths; `--force` is an explicit human decision. A recovery tool that can
247
- clobber would be a second destruction vector.
249
+ paths; `--force` is an explicit human decision. Relocation paths are checked
250
+ as a batch before mutation and again before each item: destination parent
251
+ chains must stay inside the selected workspace, and source parent chains
252
+ inside their own quarantine transaction. IDs cannot contain path separators
253
+ or traversal; transaction directories cannot redirect to another location.
254
+ The final component is kept unresolved so restoring a symlink restores the
255
+ link. `--force` cannot bypass either boundary check. Before replacing an
256
+ occupant, it uses the existing relocation journal to preserve that version
257
+ in a separate transaction. Preservation failure stops that item; the result
258
+ lists preservation attempts in optional `backup_txids`. Quarantine roots,
259
+ aliases and ancestor paths cannot themselves be moved for preservation.
260
+ This is not an atomic restore: concurrent changes and cross-filesystem
261
+ failures may leave a partial destination, so inspect the reported paths
262
+ and transaction state before retrying.
248
263
  5. **Lexical boundaries.** Workspace containment is decided on normalized
249
264
  paths; deleting a symlink removes the link, never the target, so symlink
250
265
  targets outside the workspace neither leak nor block.
@@ -255,6 +270,16 @@ FORBIDDEN (BLOCK, never askable).
255
270
  feed a Lab observation into Core policy or claim to ban model calls. A real
256
271
  block would require a host hook or request gateway that owns the call.
257
272
 
273
+ ## Read-only quarantine queries
274
+
275
+ core/trash_index.py exposes list_trash_locations for CLI, agent and future
276
+ trusted local frontend callers. status.py --trash-index supplies explicit
277
+ roots or declared buckets and returns schema version 1. This branch executes
278
+ before ordinary status accounting: no RecoveryEngine, Git, audit writes,
279
+ payload traversal or GC planning. Discovery is bounded, prunes quarantine
280
+ subtrees and deduplicates physical addresses. Metadata presence is a layout
281
+ hint; location results are not authorization for later restore or purge.
282
+
258
283
  ## Harness adapter model
259
284
 
260
285
  Any agent harness integrates through three optional points, in increasing
@@ -14,7 +14,7 @@ Harness adapters integrate against exactly four things:
14
14
  `RELOCATE`.)
15
15
  2. **Reason codes** - stable machine-readable strings (`RELOCATE_TREE`,
16
16
  `COMPOUND_CWD_DELETE`, `BLOCK_PROTECTED_PATH`, ...). See
17
- [../skills/delete-guard/references/policy.md](../skills/delete-guard/references/policy.md).
17
+ [../skills/delete-guard/references/policy.md](../../skills/delete-guard/references/policy.md).
18
18
  3. **Explanation field** - human-facing text attached to every verdict.
19
19
  4. **check.py exit codes** - `0` proceed/advisory-ok, `2` blocked,
20
20
  `3` ask, `1` internal error.
@@ -31,7 +31,25 @@ While the major version is `0`:
31
31
  | Manifest record gains a new field | minor (old fields never repurposed) |
32
32
  | Manifest record loses/repurposes a field | major + MIGRATION.md |
33
33
  | check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
34
- | Default policy verdict changes for an existing shape | minor + entry in docs/friction.md |
34
+ | Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
35
+
36
+ ### 0.2.4 maintenance patch exception
37
+
38
+ For this release, the maintainer explicitly selected `0.2.4` for the recovery
39
+ maintenance fixes and read-only trash query. This is a documented exception
40
+ to the minor-release rules above, not a general relaxation of those rules.
41
+ It adds `BLOCK_GIT_RESET_COLLISION` and refuses hard resets whose collision
42
+ preflight or command context cannot safely establish recoverability.
43
+ Relocation restore also refuses invalid source/destination boundaries and
44
+ requires preservation before a forced overwrite. See
45
+ [F24](../history/friction.md#f24--hard-reset-could-destroy-content-outside-the-tracked-snapshot)
46
+ and [F25](../history/friction.md#f25--restore-trusted-paths-and-removed-an-occupied-destination-before-recovery).
47
+
48
+ The reason string is additive; existing strings and decision classes are not
49
+ renamed. Existing CLI parameters and exit codes retain their roles. Optional
50
+ `backup_txids` and the separate trash-query schema are described below.
51
+ No manifest migration or new transaction strategy is introduced. Consumers
52
+ must accept the additional refusal reason and ignore unknown optional fields.
35
53
 
36
54
  ## Additive surfaces since v0.1.1
37
55
 
@@ -93,6 +111,35 @@ cmd/PowerShell execution through each harness, hook-selected dialect wiring,
93
111
  broader UNC/device paths, module auto-loading and full-suite Windows
94
112
  portability remain unverified.
95
113
 
114
+ ### 0.2.4 trash location query
115
+
116
+ status.py --trash-index is an additive read-only mode, with --root, --trash,
117
+ --max-depth and --max-entries. Ordinary status arguments and result fields
118
+ keep their prior behavior. Index-specific options require index mode.
119
+ Its JSON is a separate schema_version=1 contract documented in
120
+ [trash-index.md](../guides/trash-index.md): count is candidate locations,
121
+ identified_count is layout-identified locations, and complete applies only
122
+ to the declared scope. Exit 0 means complete, 1 means partial results with
123
+ errors, and 2 means invalid arguments. The shared core query and this CLI
124
+ are additions in 0.2.4, with no storage or manifest migration.
125
+
126
+ ### 0.2.4 forced-restore preservation
127
+
128
+ Forced relocation restores now preserve an existing occupant with the normal
129
+ relocation transaction and journal before replacing it. Existing CLI parameters,
130
+ exit codes and result fields retain their roles. The JSON result may add
131
+ `backup_txids`, a list of preservation attempts; inspect transaction state and
132
+ files after errors rather than treating an ID as proof of a complete copy.
133
+ Results without a preservation attempt omit this field. Text output identifies
134
+ the same attempts. CLI audit events also include these IDs when present.
135
+
136
+ The preservation transaction uses existing `tx-start`/`relocate-intent`/
137
+ `relocate` records and correlates through the existing `meta` object; no
138
+ manifest migration or new transaction strategy is introduced. Restore journal
139
+ or CLI audit write failure reports a non-success result while retaining the
140
+ filesystem outcome and preservation IDs for inspection. These changes belong
141
+ to 0.2.4; the published `0.2.3` artifact does not include them.
142
+
96
143
  ### PowerShell parameter prefixes
97
144
 
98
145
  PowerShell resolves a parameter by unambiguous prefix, so `ri build -r -fo`
@@ -115,8 +162,9 @@ Every expansion is recorded in the op notes for audit.
115
162
  ## Verdict changes since v0.1.1
116
163
 
117
164
  A changed default verdict for an existing shape is a **minor** release and
118
- requires an entry in [friction.md](friction.md) - never a silent behaviour
119
- shift. Additive reason codes are listed above; this table is for shapes
165
+ requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
166
+ shift. The explicit 0.2.4 exception is recorded above. Additive reason codes
167
+ are listed above; this table is for shapes
120
168
  whose *existing* verdict moved.
121
169
 
122
170
  | Shape | Was | Now | Why |
@@ -125,6 +173,8 @@ whose *existing* verdict moved.
125
173
  | `cd ... && git push --force` | `ASK` / `COMPOUND_CWD_DELETE` | `BLOCK` / `BLOCK_FORCE_PUSH` | A shape rule cannot downgrade a position-independent hard refusal (F1) |
126
174
  | `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
175
  | 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 |
176
+ | `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) |
177
+ | 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) |
128
178
 
129
179
  Unchanged on purpose: a genuine compensation fault (`git stash create`
130
180
  failing, a relocation that does not cover every target, an audit intent
@@ -31,7 +31,7 @@ bypass. Therefore:
31
31
  | 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
32
  | 5 | Symlink confusion (delete link vs target, trailing slash dereference) | Lexical boundary analysis; link relocation preserves the link; realpath recorded | Low |
33
33
  | 6 | TOCTOU between classification and execution | Window is milliseconds inside one process; adapters that need more should classify-and-execute atomically | Small, acknowledged |
34
- | 7 | Destructive restore | Restore refuses overwrites without explicit human `--force`; all restores audited | Low |
34
+ | 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
35
  | 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
36
 
37
37
  ## guard-lab diagnostic boundary
@@ -55,15 +55,15 @@ the integrity of a single run's evidence, not real credentials.
55
55
  | 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
56
 
57
57
  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
58
+ secrets or irreplaceable work in its fixture. See [guard-lab](../lab/guard-lab.md) for
59
59
  the exact observation and report semantics.
60
60
 
61
61
  ## Experimental DSH text-read redaction
62
62
 
63
- The default-off [native read prototype](test-report-dsh-read-redaction.md)
63
+ The default-off [native read prototype](../reports/test-report-dsh-read-redaction.md)
64
64
  mediates complete text-read results in reviewed, artifact-pinned local-FS and
65
65
  DSH `0.2.0-rc.2` sandbox-FS compositions; see the
66
- [current review](test-report-release-readiness-0.2.3.md). It
66
+ [current review](../reports/test-report-release-readiness-0.2.3.md). It
67
67
  uses Core patterns, replaces structured values and regenerates model content
68
68
  and presentation metadata. Its actual AgentLoop/JSONL probe uses synthetic
69
69
  streams and establishes no real-model L2 mitigation result.
@@ -3,7 +3,7 @@
3
3
  The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
4
4
  host does **not** mean that host intercepts tool calls, and an adapter returning
5
5
  `BLOCK` does **not** by itself prove the host prevented execution.
6
- For an unlisted host, use the [self-adaptation guide](../adapters/INTEGRATION.md)
6
+ For an unlisted host, use the [self-adaptation guide](../../adapters/INTEGRATION.md)
7
7
  and keep its native-interception status `UNVERIFIED` until independently tested.
8
8
 
9
9
  ## Evidence levels
@@ -42,14 +42,14 @@ bounded "Enforcement observed" evidence only for that root-agent Bash call.
42
42
 
43
43
  | Host / tested version | Entry and scope | ASK mapping | Highest evidence for current path | Important gap |
44
44
  |---|---|---|---|---|
45
- | Claude Code 2.1.270 / 2.1.273 (post-0.2.0 bridge) | `PreToolUse` for `Bash`; shared Core via Python and POSIX startup bridge | Native `permissionDecision: ask` (headless runs need an approver) | Real CLI/hook with scripted model endpoint: ALLOW, BLOCK, headless ASK, injected Python failure; see [report](test-report-claude-code-harness.md) | Hook absence/timeout, Windows bridge, other tools, arbitrary subagents and real model behavior are not covered. |
46
- | DSH 0.1.5-rc.1 | `tools/pre-execute` for `bash`, plus model tools and prompt section | `kind: ask` | [Real host, no-model packaged-plugin probe](test-report-dsh-0.1.5-rc.1.md): benign execution, Core `BLOCK`, absent bypass marker, durable audit, and loaded-adapter Core-startup failure. A separate [real-model Lab baseline](test-report-dsh-guard-lab.md) stayed quiet with guard off, so it produced no L2 claim. | Model-proposed destructive `bash` enforcement, subagents, concurrency, ASK UI, hook absence and host upgrades remain unverified. The opt-in read path has separate evidence below. |
47
- | DSH CLI 0.1.5-rc.1 / tools and FS 0.1.5-rc.2 / Node 22 | Default-off prototype for complete native text `read`; replaces structured value | Core ASK/BLOCK withheld | [Zero-model native probe](test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](test-report-dsh-real-followup.md): supported synthetic secrets absent from guarded content/meta/session; useful config and line numbers preserved | Injection L2, pagination, custom finalizers/providers, PTC, early events, original tool arguments and other tools are outside this claim. Outgoing real-provider request bytes were not independently captured. |
48
- | DSH 0.2.0-rc.2 / Node 22 | Default deletion adapter; optional complete text-read protection on reviewed local/sandbox FS | Native ASK; Core read ASK/BLOCK withheld | [Fresh native review](test-report-release-readiness-0.2.3.md): deletion marker/audit checks, read value/content/meta, next synthetic AgentLoop request and durable JSONL; zero external model calls | Web agent activation, model-proposed destructive calls and injection L2 remain unverified. Lab admits native v4 but refuses surface replay/images; a retained real-model clean trial remains inconclusive. |
49
- | Kimi Code 0.42.0 / 2.1.1 | `PreToolUse` for `Bash`; reuses Claude mapping with a host-specific ASK override | Adapter hard-denies ASK; live ASK behavior was sampled only on 0.42.0 | [Bounded host-level tests](test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash sentinel PASS on an OAuth official model and maintainer-confirmed official K3 relay; older 0.42.0 root/subagent BLOCK, recoverable deletion/restore and pre-adapter Python-failure refusal | The client cannot independently attest opaque relay weights. 2.1.1 subagents, concurrency, ASK UI and fault injection remain unverified; hook absence/timeout/bridge-spawn failure and non-Bash tools remain outside the claim. |
50
- | Codex CLI 0.154.0 (tested session) | Skill and production CLI on older source; no native interception adapter in this repository | CLI reports ASK; agent/user must decide | CLI acceptance only; see [report](test-report-codex-gpt-6-astra-high.md) | No automatic tool-call enforcement claim. |
51
- | ZCode (Windows session; host version unrecorded) | Historical Skill/CLI and process-type `PreToolUse` trial | One ASK prompted the user; persistent approval then skipped the hook | [Windows evaluation](test-report-zcode-glm-flash.md) | No current-version native enforcement claim; the observed permission bypass and real Windows end-to-end gaps remain. |
52
- | Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
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](../reports/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](../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. |
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](../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. |
48
+ | 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. |
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](../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. |
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](../reports/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](../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. |
52
+ | Other / unlisted hosts | No supported adapter by default | Host-specific | [Self-adaptation checklist](../../adapters/INTEGRATION.md), not a verification result | Requires a blocking pre-tool contract and independent host evidence; otherwise Skill/CLI only. |
53
53
 
54
54
  The default adapters address destructive **shell** calls. Exfil-guard also has
55
55
  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
+ 本接口不改变分散存储布局,也不读取配置或恢复文件中的秘密值。
@@ -67,7 +67,7 @@ policy. This is an integration gap, not a classifier false negative.
67
67
  ### 3.2 Automatic approval removed the human boundary
68
68
 
69
69
  The session could execute shell operations without a contemporaneous human
70
- decision. In such a host, `ASK` cannot honestly mean “ask once.” It must degrade
70
+ decision. In such a host, `ASK` cannot request human approval. It must degrade
71
71
  to `BLOCK`, or the host must provide a real approval callback.
72
72
 
73
73
  ### 3.3 Shape classification could precede hard boundaries
@@ -105,7 +105,7 @@ Collapsing these labels makes a green build look stronger than the evidence
105
105
  supports. A trustworthy recovery therefore needs an evidence ledger, replay
106
106
  reports, deterministic reruns, and explicit gap markers.
107
107
 
108
- These requirements became the [`recovery-audit`](../skills/recovery-audit/SKILL.md)
108
+ These requirements became the [`recovery-audit`](../../skills/recovery-audit/SKILL.md)
109
109
  Skill. It complements `delete-guard` and `exfil-guard`:
110
110
 
111
111
  ```text
@@ -118,7 +118,7 @@ after an incident -> recovery-audit
118
118
 
119
119
  ### Immediate
120
120
 
121
- 1. Treat harness coverage as a first-class compatibility claim. “The CLI
121
+ 1. Document harness interception separately from CLI compatibility. “The CLI
122
122
  works” and “the harness intercepts every destructive shell call” are
123
123
  different statements.
124
124
  2. Evaluate protected roots, workspace escape, and undeterminable targets
@@ -136,7 +136,7 @@ after an incident -> recovery-audit
136
136
  - an adapter conformance probe that deliberately submits safe, non-executed
137
137
  destructive samples and verifies they reach the shared policy core;
138
138
  - protected ancestor roots independent of workspace configuration;
139
- - first-class detection of parent traversal in destructive targets;
139
+ - explicit detection of parent traversal in destructive targets;
140
140
  - a local incident bundle containing hashes, verdicts, and redacted metadata,
141
141
  but never credential material;
142
142
  - deterministic recovery replay with machine-readable coverage reports.
@@ -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
 
@@ -181,7 +181,6 @@ not byte-equivalent to it.
181
181
 
182
182
  The incident changes the roadmap in a small but important way: adapter coverage
183
183
  and recovery provenance are now product features, not only operational notes.
184
- The near-term goal is not to add more command patterns. It is to prove that the
185
- same policy reaches every advertised harness, fails closed when human approval
186
- is unavailable, and leaves enough evidence to recover honestly when prevention
187
- fails.
184
+ The near-term goal is to verify that the same policy reaches each advertised
185
+ harness, refuses operations when human approval is required but unavailable,
186
+ and records enough evidence to assess recovery after a failure.
@@ -1,8 +1,8 @@
1
- # Friction log — real-agent validation (DSH adapter, first live session)
1
+ # Friction log — implementation findings and fixes
2
2
 
3
- The adapter plugin (`tools/pre-execute` interception + three model tools +
4
- prompt section) was pointed at a live coding agent performing real
5
- destructive operations. Findings, in the order they hurt.
3
+ This log records findings from host trials, CLI checks and regression tests.
4
+ The initial entries came from a DSH session using `tools/pre-execute`, three
5
+ model tools and a prompt section; later entries cover Core and other adapters.
6
6
 
7
7
  ## F1 · Compound `cd X && rm y` resolves targets against the wrong base
8
8
 
@@ -359,3 +359,106 @@ observer stops. Only user-verified `COMPLETED` permits a conclusive criterion;
359
359
  `INCONCLUSIVE` and makes a pair `INCOMPARABLE`. The optional process exit code
360
360
  is evidence, not the verdict. Completion remains user-declared because the
361
361
  generic Lab cannot safely parse and authenticate every harness transcript.
362
+
363
+ ## F21 · A sanitizer could return BLOCK and still emit the original payload
364
+
365
+ A synthetic credential on `git-push-payload` reproduced a policy/CLI split:
366
+ `sanitize_text` returned BLOCK, but its text remained unchanged and the CLI
367
+ printed it with exit zero. An external `--plan` could also replace the scanner's
368
+ derived plan without checking coverage or overlapping offsets. Passing existing
369
+ classifier/policy tests had not established actual payload withholding.
370
+
371
+ **Fixed in the local source update (2026-10-02, unreleased):** ASK/BLOCK return
372
+ empty library text and no CLI stdout payload, with exit 3/2. Plans are checked
373
+ against a current scan, ranges are validated before output construction, and
374
+ rewritten text must pass a second scan using the same exemption snapshot/mode.
375
+ Both text CLIs now bound input during reading and share default context
376
+ resolution. Regression tests exercise library and CLI refusals, dry runs,
377
+ malformed/stale/partial plans, UTF-8, oversize input and an open unwritten pipe.
378
+
379
+ The same update adds URI password spans with original offsets, preserving
380
+ accounts/hosts. Source-reference BLOCK facts remain effective even when they
381
+ overlap a URI password. This is Core/CLI evidence and does not establish new
382
+ model-request interception, live-host enforcement or adversarial containment.
383
+
384
+ ## F22 · Credential markers and variable names had inconsistent boundaries
385
+
386
+ An exact-name variable such as `TOKEN` was missed, while a normal name such
387
+ as `MONKEY` matched the keyword substring. Incidental `xxx`/`dummy` text or
388
+ an `example` suffix could exempt a whole credential. Unicode word boundaries
389
+ missed vendor tokens adjacent to CJK prose. The fixed 36-character `ghs_`
390
+ shape also missed the new GitHub installation wrapper.
391
+
392
+ **Fixed in the local source update (2026-10-03, unreleased):** variable names
393
+ use complete components and explicit metadata suffixes; whole placeholder
394
+ shapes and exact public examples replace broad word exemptions. ASCII
395
+ identifier boundaries preserve CJK detection and ordinary English identifiers.
396
+ The installation rule retains the complete long token and validates only
397
+ its wrapper/header shape. Channel decisions and source-reference refusal
398
+ remain unchanged. Regression pairs cover literal protection, ordinary names,
399
+ templates, complete ranges, CLI withholding and Core-backed read projection.
400
+ The repository noise check also exposed ordinary `${key}` interpolations:
401
+ bare lower/title-case `key` is kept ambiguous, while uppercase `KEY`, qualified
402
+ `apiKey` and explicit environment syntax remain protected. Source files and
403
+ template expressions receive no blanket exemption.
404
+ Generic password/PII rules, public-key-name policy and broader `sk-`/AWS
405
+ classification remain separate work.
406
+
407
+ ## F23 · Resource identifiers and malformed JWS headers matched credential rules
408
+
409
+ The access-key pattern included IAM group/user/role/policy prefixes, and a
410
+ generic JWT header needed only an `alg` field, allowing `alg: null` to match.
411
+ These are classification errors in the synthetic inventory, independent of
412
+ the sanitizer's output-withholding contract.
413
+
414
+ **Fixed in the local source update (2026-10-03, unreleased):** AWS access-key
415
+ facts now use AKIA/ASIA only; JWS headers require a nonempty ASCII string alg.
416
+ Resource spellings used as URI passwords still receive credential redaction.
417
+ PyPI's documented scanner shape adds an independent rule with whole long-body
418
+ replacement and shared placeholder/boundary handling. Channel decisions,
419
+ source-reference refusal and dependency count remain unchanged.
420
+
421
+ Public-key variable names cannot establish that an unseen value is public,
422
+ and the legacy broad sk- format has no complete issuance contract established
423
+ in this review. Those boundaries retain protection and remain explicit review
424
+ items. The narrowed structural rules do not certify a token's signature,
425
+ claims, actual issuance or authorization.
426
+
427
+ ## F24 · Hard reset could destroy content outside the tracked snapshot
428
+
429
+ A tracked-only stash does not contain untracked or ignored bytes. Git can
430
+ remove those bytes when the reset target replaces a file or an ancestor
431
+ directory, including quarantine storage. The 2026-10-05 independent review
432
+ reproduced this with disposable fixtures; no user worktree was reset.
433
+
434
+ **Fixed in 0.2.4:** read-only preflight checks the target tree
435
+ against untracked/ignored paths before compensation. Collisions yield
436
+ `BLOCK_GIT_RESET_COLLISION`; incomplete enumeration, submodules and unsupported
437
+ compound/wrapper contexts yield `BLOCK_UNDETERMINABLE_EFFECT`. Supported
438
+ standalone collision-free reset still snapshots tracked changes first.
439
+ There is no automatic untracked archive. Regression:
440
+ `tests/test_git_reset_safety.py` (30 cases) and two added policy cases.
441
+
442
+ This deliberately tightens default behavior and adds a reason string.
443
+ The maintainer-selected 0.2.4 patch exception is recorded in the
444
+ [compatibility contract](../design/compatibility.md#024-maintenance-patch-exception).
445
+
446
+ ## F25 · Restore trusted paths and removed an occupied destination before recovery
447
+
448
+ A changed parent symlink could redirect a recorded source or destination;
449
+ transaction IDs and directories also needed containment checks. Forced
450
+ restore removed the current occupant before attempting recovery, so a later
451
+ move failure could lose the current version.
452
+
453
+ **Fixed in 0.2.4:** restore preflights the selected workspace,
454
+ transaction directory and source parent chains, then checks each item again.
455
+ Final symlinks retain their own location semantics. Force cannot override
456
+ containment; an occupied destination is preserved in a normal relocation
457
+ transaction before recovery. Preservation failure stops that item. Returned
458
+ `backup_txids` includes attempted backups, not a guarantee that each completed.
459
+ Journal/audit errors preserve the filesystem report and IDs for inspection.
460
+
461
+ Regression: `tests/test_restore_boundary.py` (14),
462
+ `tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
463
+ These are sequential checks, not atomic same-UID isolation; cross-device
464
+ copy failures can leave partial data requiring inspection.