@mokuyoaxis/agent-guard 0.2.3-rc2 → 0.2.4-hotfix.1

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 (82) hide show
  1. package/README.md +132 -84
  2. package/README.zh-CN.md +109 -75
  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 +66 -17
  20. package/core/lab.py +24 -1
  21. package/core/policy.py +28 -13
  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} +80 -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} +129 -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-hotfix.1.md +75 -0
  47. package/docs/releases/release-notes-0.2.4.md +89 -0
  48. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  49. package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +10 -11
  50. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  51. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  52. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  53. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  54. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  55. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  56. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  57. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +22 -23
  58. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  59. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +79 -1
  60. package/docs/reports/test-report-workbuddy-windows-core.md +53 -0
  61. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +11 -11
  62. package/package.json +1 -1
  63. package/skills/delete-guard/SKILL.md +40 -3
  64. package/skills/delete-guard/references/policy.md +29 -9
  65. package/skills/delete-guard/scripts/check.py +19 -0
  66. package/skills/delete-guard/scripts/restore.py +18 -6
  67. package/skills/delete-guard/scripts/status.py +52 -0
  68. package/skills/exfil-guard/SKILL.md +37 -7
  69. package/skills/exfil-guard/references/channels.md +1 -1
  70. package/skills/exfil-guard/references/rules.md +84 -16
  71. package/skills/exfil-guard/scripts/_payload.py +99 -0
  72. package/skills/exfil-guard/scripts/check_span.py +14 -81
  73. package/skills/exfil-guard/scripts/sanitize.py +113 -34
  74. package/docs/release-notes-0.2.3.md +0 -45
  75. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  76. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  77. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  78. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  79. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  80. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  81. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  82. /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
+ [![0.2.4-hotfix.1 source](https://img.shields.io/badge/Hotfix-0.2.4--hotfix.1-5B6B7A)](docs/releases/release-notes-0.2.4-hotfix.1.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -38,33 +38,38 @@ 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
- Pinned npm installation into a stable, user-owned prefix:
57
+ After publication, install the exact hotfix 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-hotfix.1
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-hotfix.1** is an opt-in maintenance hotfix based on 0.2.4, adding
64
+ quarantine root/control-path protection. It retains the baseline's hard-reset,
65
+ restore and read-only trash-query behavior. It uses the
66
+ separate npm `hotfix` channel; `latest`, `rc` and the cumulative 0.2.5 RC line
67
+ keep their existing roles. SemVer ranks this suffix below 0.2.4, so users
68
+ must explicitly select the hotfix version or channel. See the
69
+ [hotfix notes](docs/releases/release-notes-0.2.4-hotfix.1.md) for scope and
70
+ validation. The npm badge and
71
+ [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
72
+ which artifacts are available.
68
73
 
69
74
  The package root is then
70
75
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
@@ -81,8 +86,10 @@ the host's hook support. Then give your coding agent the following setup prompt
81
86
 
82
87
  ```text
83
88
  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
89
+ the exact scoped npm package @mokuyoaxis/agent-guard@0.2.4-hotfix.1;
90
+ never install the unscoped package named agent-guard. If 0.2.4-hotfix.1 is unavailable,
91
+ report that and use the existing checkout or ask me to choose a published
92
+ version. Before installing, ask me to choose and
86
93
  approve a stable user-owned prefix. Treat the checkout or installed package
87
94
  root as /absolute/path/to/agent-guard below.
88
95
  First identify the current harness and its actual hook/skill capabilities;
@@ -103,7 +110,7 @@ intercepted, and any unverified paths.
103
110
  ```
104
111
 
105
112
  For manual setup and evidence limits, see the
106
- [adapter matrix](docs/harness-capabilities.md) and the adapter README for your
113
+ [adapter matrix](docs/guides/harness-capabilities.md) and the adapter README for your
107
114
  host.
108
115
 
109
116
  ## Design principles
@@ -213,7 +220,7 @@ DSH also offers a [default-off text-read redaction prototype](adapters/dsh/READM
213
220
  for complete native reads in a pinned composition. It reuses Core and
214
221
  regenerates both rendered text and presentation metadata; a zero-model native
215
222
  probe covers the next request and durable JSONL log. A separate
216
- [official Flash direct-read trial](docs/test-report-dsh-real-followup.md)
223
+ [official Flash direct-read trial](docs/reports/test-report-dsh-real-followup.md)
217
224
  observed supported synthetic-secret redaction while useful config stayed readable.
218
225
 
219
226
  It is a prevention and redaction guard, not a compensation engine: after an
@@ -236,19 +243,27 @@ cannot rewrite what it did not write):
236
243
 
237
244
  ### What is detected
238
245
 
239
- **T1 vendor credential patterns** (`secret/*`, deterministic, near-zero
240
- false positives). Rule ids: `secret/openai-key`, `secret/github-token`,
246
+ **T1 vendor credential patterns** (`secret/*`). These rules use known formats;
247
+ documented placeholders and negative examples constrain false positives.
248
+ Rule ids: `secret/openai-key`, `secret/github-token`,
241
249
  `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
250
+ `secret/stripe-key` (live keys only — `sk_test_` is exempt),
251
+ `secret/pypi-token`, `secret/jwt` (structural: the header must decode to JSON
252
+ with a nonempty ASCII string `alg`), and
244
253
  `secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
245
254
  redacted in one piece). See
246
255
  [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
247
- for the frozen table.
256
+ for the rule table and remaining ambiguities.
257
+
258
+ `secret/connection-password` also detects nonempty passwords in URI userinfo.
259
+ It redacts only the password, preserving the scheme, account and host for
260
+ diagnostics. Percent-encoded passwords and JSON-escaped scheme slashes are
261
+ supported; this does not hide network topology or scan every DSN format.
248
262
 
249
263
  **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*
264
+ classifies complete components in an environment variable's *name* (such as
265
+ `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CRED`, or `AUTH`) and a
266
+ secret-store *file name*
252
267
  (`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
253
268
  whole-environment expansions (`printenv`, `env | ...`, `cat
254
269
  /proc/self/environ`). This scanner **does not resolve the variable value**;
@@ -304,6 +319,28 @@ Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
304
319
  and placeholders only — **never the matched bytes**), and `--path` to enable
305
320
  the repo-local exemption file for the file being written.
306
321
 
322
+ `sanitize.py` enforces the same exit codes: ASK/BLOCK and errors emit no
323
+ payload on stdout. It validates an external `--plan` against the current scan
324
+ and rescans the rewritten text before emitting. Both CLIs use the same default
325
+ workspace and host-side mode; stdin is bounded to the scan cap (4 MiB by default)
326
+ during reading, as is an external plan file. A checker plan produced with an
327
+ explicit mode or path exemption must still satisfy the sanitizer's current
328
+ policy; the plan itself does not authorize emission.
329
+
330
+ Credential detection covers classic and stateless `ghs_APPID_JWT` GitHub
331
+ installation tokens, including long signatures and credentials next to CJK
332
+ prose. Placeholder exemptions require whole shapes; incidental example words
333
+ inside a token do not exempt it. Secret variable references are classified by
334
+ complete name components, preserving ordinary identifiers such as `MONKEY`
335
+ and metadata such as `TOKEN_COUNT`. See the [rule reference](skills/exfil-guard/references/rules.md)
336
+ for supported forms and limitations.
337
+
338
+ PyPI publishing tokens are also detected with their documented prefix and
339
+ minimum body shape, with complete redaction of long tokens. AWS group/user/
340
+ role/policy IDs are kept distinct from access-key IDs; JWT headers require
341
+ the declared nonempty ASCII string `alg`. Public-key variable names and the
342
+ broad legacy `sk-` shape retain their documented conservative boundaries.
343
+
307
344
  ### Read a config without printing its values
308
345
 
309
346
  Introduced in the `0.2.0` source; this CLI is **not** in the earlier
@@ -353,14 +390,14 @@ is a false security claim:
353
390
  call with no proxy, the model's own tool calls, content produced *inside* a
354
391
  program, and the human clipboard get **no verdict at all** — no coverage is
355
392
  claimed there. See `references/channels.md` and
356
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 for
393
+ [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 for
357
394
  the reachability table this claim is traceable to.
358
395
  - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
359
396
  guard can see *on the way out*.
360
397
  - **No history rewriting.** Detecting a secret already in Git history is a
361
398
  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.
399
+ - **No T3 entropy detector in this release.** Random-looking text alone is
400
+ insufficient evidence of a credential; ordinary identifiers stay readable.
364
401
 
365
402
  ## Manual, harness-neutral usage
366
403
 
@@ -373,6 +410,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
373
410
 
374
411
  # inspect and undo:
375
412
  python3 skills/delete-guard/scripts/status.py
413
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
376
414
  python3 skills/delete-guard/scripts/restore.py list
377
415
  python3 skills/delete-guard/scripts/restore.py <txid>
378
416
 
@@ -380,6 +418,11 @@ python3 skills/delete-guard/scripts/restore.py <txid>
380
418
  python3 skills/delete-guard/scripts/gc.py
381
419
  ```
382
420
 
421
+ The local [trash location query](docs/guides/trash-index.md) provides a shared
422
+ read-only JSON interface for agents and future UI callers. It reports scoped
423
+ location candidates and layout hints; it neither scans recovery contents nor
424
+ grants cleanup permission. It is included in 0.2.4.
425
+
383
426
  A harness adapter can invoke the guard before a supported shell command and
384
427
  map its exit status to the host's own tool decision:
385
428
 
@@ -394,7 +437,7 @@ exit 1 → guard error; fail closed
394
437
  ## What gets protected
395
438
 
396
439
  These examples assume the command reaches the guard and its targets meet the
397
- stated conditions; see the [capability matrix](docs/harness-capabilities.md)
440
+ stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
398
441
  for what each host has actually demonstrated.
399
442
 
400
443
  ```text
@@ -405,7 +448,8 @@ rm *.log → BLOCK (opaque glob; safe_delete expands it)
405
448
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
406
449
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
407
450
  git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
408
- git reset --hard → SNAPSHOT (when a Git snapshot can be made)
451
+ git reset --hard → SNAPSHOT (collision preflight + tracked snapshot)
452
+ reset with collisions → BLOCK (preserve untracked/ignored paths first)
409
453
  git push --force → BLOCK (remote history is never automated)
410
454
  node_modules/ (ignored) → ALLOW (provably regenerable)
411
455
  quarantine full → BLOCK (never fall back to permanent delete)
@@ -413,12 +457,18 @@ quarantine full → BLOCK (never fall back to permanent delete)
413
457
 
414
458
  ## Integration and validation matrix
415
459
 
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)
460
+ [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
461
+ [![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)
462
+ [![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)
463
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
464
+ [![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)
465
+ [![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)
466
+ [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
467
+ [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
468
+ [![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)
469
+
470
+ These badges link to scoped evidence; they do not certify every tool or model.
471
+ The DSH text-read feature is optional and off by default.
422
472
 
423
473
  "The Core works", "a Skill-guided agent used it", and "the harness
424
474
  intercepts every matching tool call" are separate claims. This table keeps
@@ -426,13 +476,14 @@ those evidence levels explicit:
426
476
 
427
477
  | Harness / tested version | Integration path | Evidence and limit |
428
478
  |---|---|---|
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. |
479
+ | **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. |
480
+ | **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. |
481
+ | **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. |
482
+ | **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. |
483
+ | **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. |
484
+ | **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. |
485
+ | **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. |
486
+ | **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
487
  | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
437
488
 
438
489
  For agent-led setup: identify the actual host version and tool names, follow
@@ -456,7 +507,7 @@ configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
456
507
  `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
457
508
  evidence, not interception proof. Optional create-new baselines contain only
458
509
  the parsed version and SHA-256 fingerprints. See the
459
- [host drift guide](docs/host-drift.md) for the status and baseline contract.
510
+ [host drift guide](docs/guides/host-drift.md) for the status and baseline contract.
460
511
  An explicit `--live-sentinel` can then spend one configured model call in a
461
512
  private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
462
513
  `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
@@ -466,7 +517,7 @@ The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
466
517
  hook adapter continue to support Python 3.9+.
467
518
  See the [Kimi](adapters/kimi-code/README.md) and
468
519
  [Claude](adapters/claude/README.md) adapter guides.
469
- See [harness capabilities and evidence levels](docs/harness-capabilities.md)
520
+ See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
470
521
  for the per-host scope and execution-level acceptance criteria.
471
522
 
472
523
  ## Repository layout
@@ -486,7 +537,7 @@ agent-guard/
486
537
  ├── adapters/dsh/ # DeepSeek Harness integration bridge
487
538
  ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
488
539
  ├── tests/ # unittest suites incl. cross-harness conformance
489
- └── docs/ # architecture · threat-model · friction log
540
+ └── docs/ # guides · design · Lab · reports · releases · history
490
541
  ```
491
542
 
492
543
  Skills guide agent behavior; constraints live in Core. Future
@@ -495,25 +546,19 @@ compensation engine without restructuring.
495
546
 
496
547
  ## Documentation
497
548
 
549
+ The [documentation index](docs/README.md) lists every document by purpose.
550
+ Historical reports retain their tested versions and evidence limits.
551
+
498
552
  | Read | For |
499
553
  |---|---|
500
554
  | [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 |
555
+ | [Guides](docs/README.md#guides) | current harness capabilities, host drift and maintainer guidance |
556
+ | [Design and contracts](docs/README.md#design) | architecture, threat model and compatibility |
557
+ | [Lab](docs/README.md#lab) | experiment guide, task templates and candidate attack references |
558
+ | [Test reports](docs/README.md#reports) | versioned Core, CLI, hook and Lab evidence |
559
+ | [Release notes](docs/README.md#releases) | stable and prerelease scopes |
560
+ | [Historical design and findings](docs/README.md#history) | early proposals, friction log and incident exploration |
509
561
  | [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
562
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
518
563
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
519
564
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
@@ -521,37 +566,40 @@ compensation engine without restructuring.
521
566
 
522
567
  ## Status & roadmap
523
568
 
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.
569
+ **v0.2.4** adds focused recovery maintenance and the trash query
570
+ to 0.2.3. It refuses hard-reset collisions with untracked/ignored content,
571
+ checks restore sources and destinations, and preserves an occupied destination
572
+ before a forced restore. The query supplies a shared CLI/agent/future UI
573
+ contract. Existing text redaction, safe config inspection, offline Lab,
574
+ Claude/Kimi bridges, doctor, host-drift checks and live sentinel remain available.
575
+ The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
576
+ its optional text-read protection remains off by default.
577
+
578
+ The [0.2.4 notes](docs/releases/release-notes-0.2.4.md) describe this release's scope.
579
+ The [0.2.3](docs/releases/release-notes-0.2.3.md),
580
+ [rc2](docs/releases/release-notes-0.2.3-rc2.md),
581
+ [rc1](docs/releases/release-notes-0.2.3-rc1.md), and
582
+ [0.2.2](docs/releases/release-notes-0.2.2.md) notes retain their historical scope.
583
+ Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
584
+ and npm for published artifacts.
585
+
586
+ The Core and Decision Protocol are shared across harnesses. DSH, Claude and
587
+ Kimi adapters, together with Codex/WorkBuddy/ZCode acceptance records, are documented in
588
+ one compatibility matrix.
541
589
  The Kimi result includes sampled hook-compensation and execution-level BLOCK
542
590
  paths, not proof that its host enforces every BLOCK or that arbitrary agent
543
591
  actions are protected. A tested direct-Python hook startup failure was
544
592
  fail-open. The optional shell bridge blocked a sampled Python startup failure
545
593
  in a real Kimi host session, but only when the bridge itself ran; config
546
594
  validation alone cannot prove that the hook is live.
547
- The candidate adds a focused real-Windows Core gate for Issue #7, but native
595
+ The release adds a focused real-Windows Core gate for Issue #7, but native
548
596
  cmd/PowerShell execution through every harness and general concurrent-subagent
549
597
  safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
550
598
  `cloud-guard`) reuse the same protocol and compensation engine.
551
599
 
552
- ## 0.2.3-rc2 source candidate: guard-lab
600
+ ## guard-lab
553
601
 
554
- The current source adds an opt-in, offline honeytoken MVP using disposable
602
+ The opt-in, offline honeytoken Lab uses disposable
555
603
  projects and synthetic, non-secret markers. Its `clean`, `mock-positive`,
556
604
  `mock-injection`, and `snapshot-positive` controls call no model and make no
557
605
  external request. A bounded loopback observer records the fake Lab stub, bait
@@ -560,10 +608,10 @@ canary in selected output without retaining the raw value.
560
608
 
561
609
  The user keeps the true controller and evidence outside the fixture shown to
562
610
  the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
563
- never an optimistic pass. This first candidate cannot observe ordinary file
611
+ never an optimistic pass. The Lab cannot observe ordinary file
564
612
  reads, prove remote transfer, universally block LLM calls, or resist a same-UID
565
613
  adversary. Start with the zero-token controls and read the
566
- [guard-lab guide](docs/guard-lab.md) before involving a real harness.
614
+ [guard-lab guide](docs/lab/guard-lab.md) before involving a real harness.
567
615
  The built-in cases report `CALIBRATION_ONLY`. A separate manual
568
616
  `injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
569
617
  accepts a mitigation result only after an effective unguarded baseline and a