@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
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm version](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![v0.2.3-rc2 source](https://img.shields.io/badge/Source-v0.2.3--rc2-5B6B7A)](docs/release-notes-0.2.3-rc2.md)
7
+ [![v0.2.4 source](https://img.shields.io/badge/Source-v0.2.4-5B6B7A)](docs/releases/release-notes-0.2.4.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -38,33 +38,34 @@ integration bridges rather than the product boundary.
38
38
  ```text
39
39
  rm -rf build/ → RELOCATE # an in-scope tree moves to quarantine
40
40
  rm -rf . → BLOCK # the workspace root is protected
41
- git reset --hard → SNAPSHOT # snapshot first when Git state supports it
41
+ git reset --hard → SNAPSHOT # after collision preflight, snapshot tracked changes
42
42
  git push --force → BLOCK # remote history is not automated
43
43
  ```
44
44
 
45
45
  These are illustrative verdicts for supported inputs, not commands to run or
46
46
  proof that every harness intercepts them. Ignored, regenerable targets may be
47
- `ALLOW`; a Git snapshot that cannot be made fails closed. When recovery or safe
48
- rewriting is possible, the agent can keep working. Otherwise, the guard asks
49
- the human or blocks the operation.
47
+ `ALLOW`; hard reset is blocked if its target tree would overwrite untracked
48
+ or ignored content, or if its preflight/snapshot cannot be completed. When
49
+ recovery or safe rewriting is possible, the agent can keep working. Otherwise,
50
+ the guard asks the human or blocks the operation.
50
51
 
51
52
  ## Quick start with your coding agent
52
53
 
53
- Use the scoped npm package after it is available in the registry, or keep a
54
- stable Git checkout. Never substitute the unrelated unscoped `agent-guard`
55
- package.
54
+ Use the scoped npm package or a stable Git checkout. The unscoped
55
+ `agent-guard` package is unrelated to this project.
56
56
 
57
57
  Pinned npm installation into a stable, user-owned prefix:
58
58
 
59
59
  ```sh
60
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
60
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
61
61
  ```
62
62
 
63
- `0.2.2` remains the stable recommendation. The published prerelease
64
- `@mokuyoaxis/agent-guard@0.2.3-rc1` is also available through npm `@rc`, but
65
- does not contain guard-lab. This checkout is the `0.2.3-rc2` source candidate;
66
- check Releases and npm before assuming rc2 is published. Prereleases do not
67
- replace npm `latest`.
63
+ **0.2.4** adds hard-reset collision checks,
64
+ restore path validation, current-version preservation on forced restore, and
65
+ a read-only trash location query. See the [release notes](docs/releases/release-notes-0.2.4.md)
66
+ for behavior changes and evidence limits. The npm badge and
67
+ [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
68
+ which artifacts are available.
68
69
 
69
70
  The package root is then
70
71
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
@@ -81,8 +82,10 @@ the host's hook support. Then give your coding agent the following setup prompt
81
82
 
82
83
  ```text
83
84
  Set up agent-guard for this workspace. Use either an existing Git checkout or
84
- the exact scoped npm package @mokuyoaxis/agent-guard@0.2.2; never install the
85
- unscoped package named agent-guard. Before installing, ask me to choose and
85
+ the exact scoped npm package @mokuyoaxis/agent-guard@0.2.4;
86
+ never install the unscoped package named agent-guard. If 0.2.4 is unavailable,
87
+ report that and use the existing checkout or ask me to choose a published
88
+ version. Before installing, ask me to choose and
86
89
  approve a stable user-owned prefix. Treat the checkout or installed package
87
90
  root as /absolute/path/to/agent-guard below.
88
91
  First identify the current harness and its actual hook/skill capabilities;
@@ -103,7 +106,7 @@ intercepted, and any unverified paths.
103
106
  ```
104
107
 
105
108
  For manual setup and evidence limits, see the
106
- [adapter matrix](docs/harness-capabilities.md) and the adapter README for your
109
+ [adapter matrix](docs/guides/harness-capabilities.md) and the adapter README for your
107
110
  host.
108
111
 
109
112
  ## Design principles
@@ -213,7 +216,7 @@ DSH also offers a [default-off text-read redaction prototype](adapters/dsh/READM
213
216
  for complete native reads in a pinned composition. It reuses Core and
214
217
  regenerates both rendered text and presentation metadata; a zero-model native
215
218
  probe covers the next request and durable JSONL log. A separate
216
- [official Flash direct-read trial](docs/test-report-dsh-real-followup.md)
219
+ [official Flash direct-read trial](docs/reports/test-report-dsh-real-followup.md)
217
220
  observed supported synthetic-secret redaction while useful config stayed readable.
218
221
 
219
222
  It is a prevention and redaction guard, not a compensation engine: after an
@@ -236,19 +239,27 @@ cannot rewrite what it did not write):
236
239
 
237
240
  ### What is detected
238
241
 
239
- **T1 vendor credential patterns** (`secret/*`, deterministic, near-zero
240
- false positives). Rule ids: `secret/openai-key`, `secret/github-token`,
242
+ **T1 vendor credential patterns** (`secret/*`). These rules use known formats;
243
+ documented placeholders and negative examples constrain false positives.
244
+ Rule ids: `secret/openai-key`, `secret/github-token`,
241
245
  `secret/aws-access-key-id`, `secret/gitlab-token`, `secret/slack-token`,
242
- `secret/stripe-key` (live keys only — `sk_test_` is exempt), `secret/jwt`
243
- (structural: the header must base64-decode to JSON containing `alg`), and
246
+ `secret/stripe-key` (live keys only — `sk_test_` is exempt),
247
+ `secret/pypi-token`, `secret/jwt` (structural: the header must decode to JSON
248
+ with a nonempty ASCII string `alg`), and
244
249
  `secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
245
250
  redacted in one piece). See
246
251
  [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
247
- for the frozen table.
252
+ for the rule table and remaining ambiguities.
253
+
254
+ `secret/connection-password` also detects nonempty passwords in URI userinfo.
255
+ It redacts only the password, preserving the scheme, account and host for
256
+ diagnostics. Percent-encoded passwords and JSON-escaped scheme slashes are
257
+ supported; this does not hide network topology or scan every DSN format.
248
258
 
249
259
  **Value-free secret references** (`secret/source-reference`). The guard
250
- classifies an environment variable's *name* (`*KEY*`, `*TOKEN*`,
251
- `*SECRET*`, `*PASSWORD*`, `*CRED*`, `*AUTH*`) and a secret-store *file name*
260
+ classifies complete components in an environment variable's *name* (such as
261
+ `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CRED`, or `AUTH`) and a
262
+ secret-store *file name*
252
263
  (`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
253
264
  whole-environment expansions (`printenv`, `env | ...`, `cat
254
265
  /proc/self/environ`). This scanner **does not resolve the variable value**;
@@ -304,6 +315,28 @@ Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
304
315
  and placeholders only — **never the matched bytes**), and `--path` to enable
305
316
  the repo-local exemption file for the file being written.
306
317
 
318
+ `sanitize.py` enforces the same exit codes: ASK/BLOCK and errors emit no
319
+ payload on stdout. It validates an external `--plan` against the current scan
320
+ and rescans the rewritten text before emitting. Both CLIs use the same default
321
+ workspace and host-side mode; stdin is bounded to the scan cap (4 MiB by default)
322
+ during reading, as is an external plan file. A checker plan produced with an
323
+ explicit mode or path exemption must still satisfy the sanitizer's current
324
+ policy; the plan itself does not authorize emission.
325
+
326
+ Credential detection covers classic and stateless `ghs_APPID_JWT` GitHub
327
+ installation tokens, including long signatures and credentials next to CJK
328
+ prose. Placeholder exemptions require whole shapes; incidental example words
329
+ inside a token do not exempt it. Secret variable references are classified by
330
+ complete name components, preserving ordinary identifiers such as `MONKEY`
331
+ and metadata such as `TOKEN_COUNT`. See the [rule reference](skills/exfil-guard/references/rules.md)
332
+ for supported forms and limitations.
333
+
334
+ PyPI publishing tokens are also detected with their documented prefix and
335
+ minimum body shape, with complete redaction of long tokens. AWS group/user/
336
+ role/policy IDs are kept distinct from access-key IDs; JWT headers require
337
+ the declared nonempty ASCII string `alg`. Public-key variable names and the
338
+ broad legacy `sk-` shape retain their documented conservative boundaries.
339
+
307
340
  ### Read a config without printing its values
308
341
 
309
342
  Introduced in the `0.2.0` source; this CLI is **not** in the earlier
@@ -353,14 +386,14 @@ is a false security claim:
353
386
  call with no proxy, the model's own tool calls, content produced *inside* a
354
387
  program, and the human clipboard get **no verdict at all** — no coverage is
355
388
  claimed there. See `references/channels.md` and
356
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 for
389
+ [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 for
357
390
  the reachability table this claim is traceable to.
358
391
  - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
359
392
  guard can see *on the way out*.
360
393
  - **No history rewriting.** Detecting a secret already in Git history is a
361
394
  report at most. Rewriting history is a human action with its own risks.
362
- - **No T3 entropy detector in this release.** It is the single largest
363
- false-positive source, and the named scenarios do not require it.
395
+ - **No T3 entropy detector in this release.** Random-looking text alone is
396
+ insufficient evidence of a credential; ordinary identifiers stay readable.
364
397
 
365
398
  ## Manual, harness-neutral usage
366
399
 
@@ -373,6 +406,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
373
406
 
374
407
  # inspect and undo:
375
408
  python3 skills/delete-guard/scripts/status.py
409
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
376
410
  python3 skills/delete-guard/scripts/restore.py list
377
411
  python3 skills/delete-guard/scripts/restore.py <txid>
378
412
 
@@ -380,6 +414,11 @@ python3 skills/delete-guard/scripts/restore.py <txid>
380
414
  python3 skills/delete-guard/scripts/gc.py
381
415
  ```
382
416
 
417
+ The local [trash location query](docs/guides/trash-index.md) provides a shared
418
+ read-only JSON interface for agents and future UI callers. It reports scoped
419
+ location candidates and layout hints; it neither scans recovery contents nor
420
+ grants cleanup permission. It is included in 0.2.4.
421
+
383
422
  A harness adapter can invoke the guard before a supported shell command and
384
423
  map its exit status to the host's own tool decision:
385
424
 
@@ -394,7 +433,7 @@ exit 1 → guard error; fail closed
394
433
  ## What gets protected
395
434
 
396
435
  These examples assume the command reaches the guard and its targets meet the
397
- stated conditions; see the [capability matrix](docs/harness-capabilities.md)
436
+ stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
398
437
  for what each host has actually demonstrated.
399
438
 
400
439
  ```text
@@ -405,7 +444,8 @@ rm *.log → BLOCK (opaque glob; safe_delete expands it)
405
444
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
406
445
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
407
446
  git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
408
- git reset --hard → SNAPSHOT (when a Git snapshot can be made)
447
+ git reset --hard → SNAPSHOT (collision preflight + tracked snapshot)
448
+ reset with collisions → BLOCK (preserve untracked/ignored paths first)
409
449
  git push --force → BLOCK (remote history is never automated)
410
450
  node_modules/ (ignored) → ALLOW (provably regenerable)
411
451
  quarantine full → BLOCK (never fall back to permanent delete)
@@ -413,12 +453,18 @@ quarantine full → BLOCK (never fall back to permanent delete)
413
453
 
414
454
  ## Integration and validation matrix
415
455
 
416
- [![Node.js 20 smoke](https://img.shields.io/badge/Node.js-20%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
417
- [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/test-report-codex-gpt-6-astra-high.md)
418
- [![DSH 0.1.5-rc.1 host BLOCK tested](https://img.shields.io/badge/DSH%200.1.5--rc.1-host%20BLOCK%20tested-4D6BFE)](docs/test-report-dsh-0.1.5-rc.1.md)
419
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
420
- [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/test-report-claude-code-harness.md)
421
- [![Kimi Code 2.1.1 K3 Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-K3%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
456
+ [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
457
+ [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/reports/test-report-codex-gpt-6-astra-high.md)
458
+ [![DSH 0.1.5-rc.1 host BLOCK tested](https://img.shields.io/badge/DSH%200.1.5--rc.1-host%20BLOCK%20tested-4D6BFE)](docs/reports/test-report-dsh-0.1.5-rc.1.md)
459
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
460
+ [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/reports/test-report-claude-code-harness.md)
461
+ [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/reports/test-report-kimi-code-block.md)
462
+ [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
463
+ [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
464
+ [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/reports/test-report-release-readiness-0.2.3.md)
465
+
466
+ These badges link to scoped evidence; they do not certify every tool or model.
467
+ The DSH text-read feature is optional and off by default.
422
468
 
423
469
  "The Core works", "a Skill-guided agent used it", and "the harness
424
470
  intercepts every matching tool call" are separate claims. This table keeps
@@ -426,13 +472,14 @@ those evidence levels explicit:
426
472
 
427
473
  | Harness / tested version | Integration path | Evidence and limit |
428
474
  |---|---|---|
429
- | **Claude Code 2.1.270 / 2.1.273** | [Native `PreToolUse` for Bash](adapters/claude/README.md) | [Real CLI + scripted model](docs/test-report-claude-code-harness.md): sampled allow/ask/deny and Python-startup failure; other tools unverified. |
430
- | **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host packaged-plugin probe](docs/test-report-dsh-0.1.5-rc.1.md): execution-level `BLOCK` and loaded-adapter Core failure. A [real-model Lab baseline](docs/test-report-dsh-guard-lab.md) stayed quiet with guard off, so no L2 mitigation claim exists; model-proposed destructive `bash` enforcement remains unverified. The separate opt-in read path is listed below. |
431
- | **DSH CLI rc.1 / tools and FS rc.2 / Node 22** | [Experimental text-read redaction](adapters/dsh/README.md#experimental-text-read-redaction), default off | [Zero-model native probe](docs/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](docs/test-report-dsh-real-followup.md): supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim. |
432
- | **DSH 0.2.0-rc.2 / Node 22** | [Default deletion and optional text-read adapter](adapters/dsh/README.md) | [Fresh contract review](docs/test-report-release-readiness-0.2.3.md): native deletion blocking, read redaction on reviewed local/sandbox FS, next synthetic request and durable JSONL. Native v4 Lab support remains bounded; no new real-model L2 result. |
433
- | **Codex CLI 0.154.0 (tested session)** | [Skill + production CLI](docs/test-report-codex-gpt-6-astra-high.md) | Older-source cooperative acceptance; no native hook claim. |
434
- | **ZCode (version unrecorded; win32)** | [Historical Skill/CLI + hook trial](docs/test-report-zcode-glm-flash.md) | Older hook observation includes a persistent-permission bypass; current version unverified. |
435
- | **Kimi Code 0.42.0 / 2.1.1** | [Native `PreToolUse` for Bash](adapters/kimi-code/README.md) | [Bounded tests](docs/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash PASS on an OAuth official model and maintainer-confirmed official K3 relay; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
475
+ | **Claude Code 2.1.270 / 2.1.273** | [Native `PreToolUse` for Bash](adapters/claude/README.md) | [Real CLI + scripted model](docs/reports/test-report-claude-code-harness.md): sampled allow/ask/deny and Python-startup failure; other tools unverified. |
476
+ | **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host packaged-plugin probe](docs/reports/test-report-dsh-0.1.5-rc.1.md): execution-level `BLOCK` and loaded-adapter Core failure. A [real-model Lab baseline](docs/reports/test-report-dsh-guard-lab.md) stayed quiet with guard off, so no L2 mitigation claim exists; model-proposed destructive `bash` enforcement remains unverified. The separate opt-in read path is listed below. |
477
+ | **DSH CLI rc.1 / tools and FS rc.2 / Node 22** | [Experimental text-read redaction](adapters/dsh/README.md#experimental-text-read-redaction), default off | [Zero-model native probe](docs/reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](docs/reports/test-report-dsh-real-followup.md): supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim. |
478
+ | **DSH 0.2.0-rc.2 / Node 22** | [Default deletion and optional text-read adapter](adapters/dsh/README.md) | [Fresh contract review](docs/reports/test-report-release-readiness-0.2.3.md): native deletion blocking, read redaction on reviewed local/sandbox FS, next synthetic request and durable JSONL. Native v4 Lab support remains bounded; no new real-model L2 result. |
479
+ | **Codex CLI 0.154.0 (tested session)** | [Skill + production CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | Older-source cooperative acceptance; no native hook claim. |
480
+ | **WorkBuddy (version not recorded; Windows 11)** | [Core / CLI](docs/reports/test-report-workbuddy-windows-core.md) | Community feedback on 0.2.2 found two Core defects now covered by regressions and focused Windows CI; no WorkBuddy adapter or native-hook validation. |
481
+ | **ZCode (version unrecorded; win32)** | [Historical Skill/CLI + hook trial](docs/reports/test-report-zcode-glm-flash.md) | Older hook observation includes a persistent-permission bypass; current version unverified. |
482
+ | **Kimi Code 0.42.0 / 2.1.1** | [Native `PreToolUse` for Bash](adapters/kimi-code/README.md) | [Bounded tests](docs/reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash PASS on an OAuth official model and a second configured model route; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
436
483
  | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
437
484
 
438
485
  For agent-led setup: identify the actual host version and tool names, follow
@@ -456,7 +503,7 @@ configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
456
503
  `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
457
504
  evidence, not interception proof. Optional create-new baselines contain only
458
505
  the parsed version and SHA-256 fingerprints. See the
459
- [host drift guide](docs/host-drift.md) for the status and baseline contract.
506
+ [host drift guide](docs/guides/host-drift.md) for the status and baseline contract.
460
507
  An explicit `--live-sentinel` can then spend one configured model call in a
461
508
  private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
462
509
  `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
@@ -466,7 +513,7 @@ The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
466
513
  hook adapter continue to support Python 3.9+.
467
514
  See the [Kimi](adapters/kimi-code/README.md) and
468
515
  [Claude](adapters/claude/README.md) adapter guides.
469
- See [harness capabilities and evidence levels](docs/harness-capabilities.md)
516
+ See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
470
517
  for the per-host scope and execution-level acceptance criteria.
471
518
 
472
519
  ## Repository layout
@@ -486,7 +533,7 @@ agent-guard/
486
533
  ├── adapters/dsh/ # DeepSeek Harness integration bridge
487
534
  ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
488
535
  ├── tests/ # unittest suites incl. cross-harness conformance
489
- └── docs/ # architecture · threat-model · friction log
536
+ └── docs/ # guides · design · Lab · reports · releases · history
490
537
  ```
491
538
 
492
539
  Skills guide agent behavior; constraints live in Core. Future
@@ -495,25 +542,19 @@ compensation engine without restructuring.
495
542
 
496
543
  ## Documentation
497
544
 
545
+ The [documentation index](docs/README.md) lists every document by purpose.
546
+ Historical reports retain their tested versions and evidence limits.
547
+
498
548
  | Read | For |
499
549
  |---|---|
500
550
  | [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
501
- | [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
502
- | [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
503
- | [docs/guard-lab.md](docs/guard-lab.md) | synthetic Lab workflow, evidence semantics, and unsupported channels |
504
- | [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | offline guard-lab source candidate |
505
- | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed candidate and prerelease channel |
506
- | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 host drift, live sentinel and DSH package acceptance |
507
- | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
508
- | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
551
+ | [Guides](docs/README.md#guides) | current harness capabilities, host drift and maintainer guidance |
552
+ | [Design and contracts](docs/README.md#design) | architecture, threat model and compatibility |
553
+ | [Lab](docs/README.md#lab) | experiment guide, task templates and candidate attack references |
554
+ | [Test reports](docs/README.md#reports) | versioned Core, CLI, hook and Lab evidence |
555
+ | [Release notes](docs/README.md#releases) | stable and prerelease scopes |
556
+ | [Historical design and findings](docs/README.md#history) | early proposals, friction log and incident exploration |
509
557
  | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
510
- | [docs/threat-model.md](docs/threat-model.md) | honest limits: what this is and is not |
511
- | [docs/friction.md](docs/friction.md) | what real agents and host processes taught us (F1–F20) |
512
- | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | de-identified incident exploration and the recovery-aware direction |
513
- | [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex evaluation (medium + high) |
514
- | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | current DSH packaged-plugin and execution-level `bash` acceptance |
515
- | [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | bounded DSH real-model Lab baseline; no L2 claim |
516
- | [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH live test (DeepSeek V4 Pro high, minimal mode) |
517
558
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
518
559
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
519
560
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
@@ -521,37 +562,40 @@ compensation engine without restructuring.
521
562
 
522
563
  ## Status & roadmap
523
564
 
524
- The source version is **v0.2.3-rc2**; the latest stable release remains
525
- **v0.2.2**. The published `v0.2.0` baseline includes
526
- recoverable destructive actions, cmd/PowerShell dialect parsing, the
527
- `exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
528
- Later source releases add Claude/Kimi POSIX hook bridges, bounded host
529
- evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
530
- current DSH package acceptance. The rc2 source additionally contains the
531
- offline guard-lab MVP described below. See the
532
- [0.2.3-rc2 notes](docs/release-notes-0.2.3-rc2.md) for its source scope,
533
- [0.2.3-rc1 notes](docs/release-notes-0.2.3-rc1.md) for the published candidate,
534
- [0.2.2 notes](docs/release-notes-0.2.2.md) for the stable scope, and
535
- [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
536
- publication status; a source version is not itself a published Release.
537
-
538
- The release identity is harness-neutral. Existing DSH and Claude adapters,
539
- Codex/ZCode acceptance evidence, and the bounded Kimi exercise are entries
540
- in a growing compatibility matrix, not separate definitions of the product.
565
+ **v0.2.4** adds focused recovery maintenance and the trash query
566
+ to 0.2.3. It refuses hard-reset collisions with untracked/ignored content,
567
+ checks restore sources and destinations, and preserves an occupied destination
568
+ before a forced restore. The query supplies a shared CLI/agent/future UI
569
+ contract. Existing text redaction, safe config inspection, offline Lab,
570
+ Claude/Kimi bridges, doctor, host-drift checks and live sentinel remain available.
571
+ The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
572
+ its optional text-read protection remains off by default.
573
+
574
+ The [0.2.4 notes](docs/releases/release-notes-0.2.4.md) describe this release's scope.
575
+ The [0.2.3](docs/releases/release-notes-0.2.3.md),
576
+ [rc2](docs/releases/release-notes-0.2.3-rc2.md),
577
+ [rc1](docs/releases/release-notes-0.2.3-rc1.md), and
578
+ [0.2.2](docs/releases/release-notes-0.2.2.md) notes retain their historical scope.
579
+ Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
580
+ and npm for published artifacts.
581
+
582
+ The Core and Decision Protocol are shared across harnesses. DSH, Claude and
583
+ Kimi adapters, together with Codex/WorkBuddy/ZCode acceptance records, are documented in
584
+ one compatibility matrix.
541
585
  The Kimi result includes sampled hook-compensation and execution-level BLOCK
542
586
  paths, not proof that its host enforces every BLOCK or that arbitrary agent
543
587
  actions are protected. A tested direct-Python hook startup failure was
544
588
  fail-open. The optional shell bridge blocked a sampled Python startup failure
545
589
  in a real Kimi host session, but only when the bridge itself ran; config
546
590
  validation alone cannot prove that the hook is live.
547
- The candidate adds a focused real-Windows Core gate for Issue #7, but native
591
+ The release adds a focused real-Windows Core gate for Issue #7, but native
548
592
  cmd/PowerShell execution through every harness and general concurrent-subagent
549
593
  safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
550
594
  `cloud-guard`) reuse the same protocol and compensation engine.
551
595
 
552
- ## 0.2.3-rc2 source candidate: guard-lab
596
+ ## guard-lab
553
597
 
554
- The current source adds an opt-in, offline honeytoken MVP using disposable
598
+ The opt-in, offline honeytoken Lab uses disposable
555
599
  projects and synthetic, non-secret markers. Its `clean`, `mock-positive`,
556
600
  `mock-injection`, and `snapshot-positive` controls call no model and make no
557
601
  external request. A bounded loopback observer records the fake Lab stub, bait
@@ -560,10 +604,10 @@ canary in selected output without retaining the raw value.
560
604
 
561
605
  The user keeps the true controller and evidence outside the fixture shown to
562
606
  the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
563
- never an optimistic pass. This first candidate cannot observe ordinary file
607
+ never an optimistic pass. The Lab cannot observe ordinary file
564
608
  reads, prove remote transfer, universally block LLM calls, or resist a same-UID
565
609
  adversary. Start with the zero-token controls and read the
566
- [guard-lab guide](docs/guard-lab.md) before involving a real harness.
610
+ [guard-lab guide](docs/lab/guard-lab.md) before involving a real harness.
567
611
  The built-in cases report `CALIBRATION_ONLY`. A separate manual
568
612
  `injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
569
613
  accepts a mitigation result only after an effective unguarded baseline and a