@mokuyoaxis/agent-guard 0.2.3 → 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 (70) hide show
  1. package/README.md +70 -63
  2. package/README.zh-CN.md +61 -59
  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 +10 -6
  8. package/adapters/dsh/harness/README.md +8 -8
  9. package/adapters/dsh/harness/guard_lab.py +3 -3
  10. package/adapters/dsh/lib/index.js +1 -1
  11. package/adapters/kimi-code/README.md +7 -7
  12. package/adapters/kimi-code/harness/README.md +3 -3
  13. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  14. package/core/__init__.py +1 -1
  15. package/core/classifier.py +66 -17
  16. package/core/policy.py +28 -13
  17. package/core/recovery.py +256 -23
  18. package/core/trash_index.py +193 -0
  19. package/docs/README.md +104 -0
  20. package/docs/{architecture.md → design/architecture.md} +31 -6
  21. package/docs/{compatibility.md → design/compatibility.md} +80 -4
  22. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  23. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  24. package/docs/guides/trash-index.md +106 -0
  25. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  26. package/docs/{friction.md → history/friction.md} +61 -0
  27. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  28. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  29. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  30. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  31. package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
  32. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  33. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  34. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  35. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  36. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  37. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  38. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  39. package/docs/releases/release-notes-0.2.4-hotfix.1.md +75 -0
  40. package/docs/releases/release-notes-0.2.4.md +89 -0
  41. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  42. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  43. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  44. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  45. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  46. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  47. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  48. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  49. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  50. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  51. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  52. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  53. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  54. package/package.json +1 -1
  55. package/skills/delete-guard/SKILL.md +38 -0
  56. package/skills/delete-guard/references/policy.md +29 -9
  57. package/skills/delete-guard/scripts/check.py +19 -0
  58. package/skills/delete-guard/scripts/restore.py +18 -6
  59. package/skills/delete-guard/scripts/status.py +52 -0
  60. package/skills/exfil-guard/references/channels.md +1 -1
  61. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  62. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  63. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  64. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  65. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  66. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  67. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  68. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  69. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  70. /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 source](https://img.shields.io/badge/Source-v0.2.3-5B6B7A)](docs/release-notes-0.2.3.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,30 +38,36 @@ 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
54
  Use the scoped npm package or a stable Git checkout. The unscoped
54
55
  `agent-guard` package is unrelated to this project.
55
56
 
56
- Pinned npm installation into a stable, user-owned prefix:
57
+ After publication, install the exact hotfix into a stable, user-owned prefix:
57
58
 
58
59
  ```sh
59
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.3
60
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4-hotfix.1
60
61
  ```
61
62
 
62
- **0.2.3** combines Windows/Core fixes, information-protection improvements
63
- and the offline guard-lab MVP. See the [release notes](docs/release-notes-0.2.3.md)
64
- for scope and evidence limits. The npm badge and
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
65
71
  [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
66
72
  which artifacts are available.
67
73
 
@@ -80,8 +86,8 @@ the host's hook support. Then give your coding agent the following setup prompt
80
86
 
81
87
  ```text
82
88
  Set up agent-guard for this workspace. Use either an existing Git checkout or
83
- the exact scoped npm package @mokuyoaxis/agent-guard@0.2.3;
84
- never install the unscoped package named agent-guard. If 0.2.3 is unavailable,
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,
85
91
  report that and use the existing checkout or ask me to choose a published
86
92
  version. Before installing, ask me to choose and
87
93
  approve a stable user-owned prefix. Treat the checkout or installed package
@@ -104,7 +110,7 @@ intercepted, and any unverified paths.
104
110
  ```
105
111
 
106
112
  For manual setup and evidence limits, see the
107
- [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
108
114
  host.
109
115
 
110
116
  ## Design principles
@@ -214,7 +220,7 @@ DSH also offers a [default-off text-read redaction prototype](adapters/dsh/READM
214
220
  for complete native reads in a pinned composition. It reuses Core and
215
221
  regenerates both rendered text and presentation metadata; a zero-model native
216
222
  probe covers the next request and durable JSONL log. A separate
217
- [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)
218
224
  observed supported synthetic-secret redaction while useful config stayed readable.
219
225
 
220
226
  It is a prevention and redaction guard, not a compensation engine: after an
@@ -384,7 +390,7 @@ is a false security claim:
384
390
  call with no proxy, the model's own tool calls, content produced *inside* a
385
391
  program, and the human clipboard get **no verdict at all** — no coverage is
386
392
  claimed there. See `references/channels.md` and
387
- [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
388
394
  the reachability table this claim is traceable to.
389
395
  - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
390
396
  guard can see *on the way out*.
@@ -404,6 +410,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
404
410
 
405
411
  # inspect and undo:
406
412
  python3 skills/delete-guard/scripts/status.py
413
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
407
414
  python3 skills/delete-guard/scripts/restore.py list
408
415
  python3 skills/delete-guard/scripts/restore.py <txid>
409
416
 
@@ -411,6 +418,11 @@ python3 skills/delete-guard/scripts/restore.py <txid>
411
418
  python3 skills/delete-guard/scripts/gc.py
412
419
  ```
413
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
+
414
426
  A harness adapter can invoke the guard before a supported shell command and
415
427
  map its exit status to the host's own tool decision:
416
428
 
@@ -425,7 +437,7 @@ exit 1 → guard error; fail closed
425
437
  ## What gets protected
426
438
 
427
439
  These examples assume the command reaches the guard and its targets meet the
428
- stated conditions; see the [capability matrix](docs/harness-capabilities.md)
440
+ stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
429
441
  for what each host has actually demonstrated.
430
442
 
431
443
  ```text
@@ -436,7 +448,8 @@ rm *.log → BLOCK (opaque glob; safe_delete expands it)
436
448
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
437
449
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
438
450
  git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
439
- 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)
440
453
  git push --force → BLOCK (remote history is never automated)
441
454
  node_modules/ (ignored) → ALLOW (provably regenerable)
442
455
  quarantine full → BLOCK (never fall back to permanent delete)
@@ -445,14 +458,14 @@ quarantine full → BLOCK (never fall back to permanent delete)
445
458
  ## Integration and validation matrix
446
459
 
447
460
  [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
448
- [![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)
449
- [![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)
450
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
451
- [![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)
452
- [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
453
- [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/test-report-workbuddy-windows-core.md)
454
- [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/release-notes-0.2.3-rc1.md#focused-windows-ci)
455
- [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/test-report-release-readiness-0.2.3.md)
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)
456
469
 
457
470
  These badges link to scoped evidence; they do not certify every tool or model.
458
471
  The DSH text-read feature is optional and off by default.
@@ -463,14 +476,14 @@ those evidence levels explicit:
463
476
 
464
477
  | Harness / tested version | Integration path | Evidence and limit |
465
478
  |---|---|---|
466
- | **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. |
467
- | **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. |
468
- | **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. |
469
- | **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. |
470
- | **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. |
471
- | **WorkBuddy (version not recorded; Windows 11)** | [Core / CLI](docs/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. |
472
- | **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. |
473
- | **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 a second configured model route; 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. |
474
487
  | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
475
488
 
476
489
  For agent-led setup: identify the actual host version and tool names, follow
@@ -494,7 +507,7 @@ configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
494
507
  `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
495
508
  evidence, not interception proof. Optional create-new baselines contain only
496
509
  the parsed version and SHA-256 fingerprints. See the
497
- [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.
498
511
  An explicit `--live-sentinel` can then spend one configured model call in a
499
512
  private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
500
513
  `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
@@ -504,7 +517,7 @@ The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
504
517
  hook adapter continue to support Python 3.9+.
505
518
  See the [Kimi](adapters/kimi-code/README.md) and
506
519
  [Claude](adapters/claude/README.md) adapter guides.
507
- See [harness capabilities and evidence levels](docs/harness-capabilities.md)
520
+ See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
508
521
  for the per-host scope and execution-level acceptance criteria.
509
522
 
510
523
  ## Repository layout
@@ -524,7 +537,7 @@ agent-guard/
524
537
  ├── adapters/dsh/ # DeepSeek Harness integration bridge
525
538
  ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
526
539
  ├── tests/ # unittest suites incl. cross-harness conformance
527
- └── docs/ # architecture · threat-model · friction log
540
+ └── docs/ # guides · design · Lab · reports · releases · history
528
541
  ```
529
542
 
530
543
  Skills guide agent behavior; constraints live in Core. Future
@@ -533,27 +546,19 @@ compensation engine without restructuring.
533
546
 
534
547
  ## Documentation
535
548
 
549
+ The [documentation index](docs/README.md) lists every document by purpose.
550
+ Historical reports retain their tested versions and evidence limits.
551
+
536
552
  | Read | For |
537
553
  |---|---|
538
554
  | [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
539
- | [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
540
- | [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
541
- | [docs/guard-lab.md](docs/guard-lab.md) | synthetic Lab workflow, evidence semantics, and unsupported channels |
542
- | [docs/release-notes-0.2.3.md](docs/release-notes-0.2.3.md) | 0.2.3 stable-release scope and evidence limits |
543
- | [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | published prerelease: offline guard-lab and reviewed DSH contracts |
544
- | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed candidate and prerelease channel |
545
- | [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 |
546
- | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
547
- | [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 |
548
561
  | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
549
- | [docs/threat-model.md](docs/threat-model.md) | honest limits: what this is and is not |
550
- | [docs/friction.md](docs/friction.md) | what real agents and host processes taught us (F1–F20) |
551
- | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | de-identified incident exploration and the recovery-aware direction |
552
- | [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) |
553
- | [docs/test-report-workbuddy-windows-core.md](docs/test-report-workbuddy-windows-core.md) | community Windows Core/CLI feedback and resulting regressions |
554
- | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | DSH 0.1.5-rc.1 packaged-plugin and execution-level `bash` acceptance |
555
- | [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | bounded DSH real-model Lab baseline; no L2 claim |
556
- | [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) |
557
562
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
558
563
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
559
564
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
@@ -561,18 +566,20 @@ compensation engine without restructuring.
561
566
 
562
567
  ## Status & roadmap
563
568
 
564
- **v0.2.3** combines the Windows/Core
565
- fixes and offline guard-lab MVP with validated text redaction, URI password
566
- detection, PyPI and newer GitHub token support, and narrower false-positive
567
- boundaries. Existing recovery tools, safe config inspection, Claude/Kimi
568
- bridges, doctor, host-drift checks and live sentinel remain available.
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.
569
575
  The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
570
576
  its optional text-read protection remains off by default.
571
577
 
572
- The [0.2.3 notes](docs/release-notes-0.2.3.md) describe this release's scope.
573
- The [rc2](docs/release-notes-0.2.3-rc2.md),
574
- [rc1](docs/release-notes-0.2.3-rc1.md), and
575
- [0.2.2](docs/release-notes-0.2.2.md) notes retain their historical scope.
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.
576
583
  Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
577
584
  and npm for published artifacts.
578
585
 
@@ -604,7 +611,7 @@ the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
604
611
  never an optimistic pass. The Lab cannot observe ordinary file
605
612
  reads, prove remote transfer, universally block LLM calls, or resist a same-UID
606
613
  adversary. Start with the zero-token controls and read the
607
- [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.
608
615
  The built-in cases report `CALIBRATION_ONLY`. A separate manual
609
616
  `injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
610
617
  accepts a mitigation result only after an effective unguarded baseline and a
package/README.zh-CN.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm 版本](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 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.3-5B6B7A)](docs/release-notes-0.2.3.md)
7
+ [![0.2.4-hotfix.1 热修复](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
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -31,27 +31,31 @@ Core、决策协议与 Skills 是产品本体,适配器只是可替换的接
31
31
  ```text
32
32
  rm -rf build/ → RELOCATE # 工作区内目录先迁入隔离区
33
33
  rm -rf . → BLOCK # 保护工作区根目录
34
- git reset --hard → SNAPSHOT # Git 状态允许时先做快照
34
+ git reset --hard → SNAPSHOT # 先检查路径冲突,再保存已跟踪修改
35
35
  git push --force → BLOCK # 不自动改写远端历史
36
36
  ```
37
37
 
38
38
  这是受支持输入的**示意判决**,不是让你执行这些命令,也不表示所有宿主都会
39
- 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;Git 快照无法建立时会
40
- 保守拒绝。能恢复或安全改写时,Agent 可以继续工作;否则交给人或阻断。
39
+ 自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;hard reset 的目标树与未跟踪
40
+ 或忽略内容冲突,或无法完成预检/快照时,会保守拒绝。能恢复或安全改写时,
41
+ Agent 可以继续工作;否则交给人或阻断。
41
42
 
42
43
  ## 让编码 Agent 帮你接入
43
44
 
44
45
  可以安装带作用域的 npm 包,也可以保留一个稳定的 Git checkout。
45
46
  无作用域的同名 `agent-guard` 包与本项目无关。
46
47
 
47
- 把固定版本安装到用户选择的稳定路径:
48
+ 发布后,把热修复的固定版本安装到用户选择的稳定路径:
48
49
 
49
50
  ```sh
50
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.3
51
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4-hotfix.1
51
52
  ```
52
53
 
53
- **0.2.3** 合并 Windows/Core 修复、信息保护增强和离线 guard-lab MVP。
54
- 本次范围与证据边界见 [发布说明](docs/release-notes-0.2.3.md);
54
+ **0.2.4-hotfix.1** 是基于 0.2.4 的可选热修复,仅增加回收站根/控制路径保护,
55
+ 保留基线的 hard reset、restore 和垃圾桶只读查询行为。使用独立 npm `hotfix`
56
+ 渠道,`latest`、`rc` 及现有 0.2.5 RC 累计内容保持各自路线。按 SemVer,此后缀
57
+ 排序低于 0.2.4,需要显式选择热修复版本或渠道。
58
+ 本次行为变化与验证范围见 [热修复说明](docs/releases/release-notes-0.2.4-hotfix.1.md);
55
59
  npm 徽章和 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
56
60
  展示实际可用的发布工件。
57
61
 
@@ -69,8 +73,8 @@ Core 需要 Python 3.9+ 和 Git;是否能自动拦截取决于宿主是否提
69
73
 
70
74
  ```text
71
75
  请为当前工作区接入 agent-guard。只使用现有 Git checkout,或精确的 scoped
72
- npm 包 @mokuyoaxis/agent-guard@0.2.3;不要安装无作用域的同名
73
- agent-guard。若 0.2.3 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
76
+ npm 包 @mokuyoaxis/agent-guard@0.2.4-hotfix.1;不要安装无作用域的同名
77
+ agent-guard。若 0.2.4-hotfix.1 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
74
78
  安装前先让我选择并批准一个稳定的用户目录,然后把 checkout 或 npm 安装后的
75
79
  包根目录作为下文的 /absolute/path/to/agent-guard。
76
80
  先识别当前 harness 实际支持的 hook 与 Skill,阅读本 README 和对应 adapter
@@ -85,7 +89,7 @@ adapters/kimi-code/README.md,DSH 参考 adapters/dsh/README.md。
85
89
  拦截证明。最后报告宿主版本、工具范围、实际安装内容、确实拦截的调用和未验证路径。
86
90
  ```
87
91
 
88
- 手动接入与证据边界见 [harness 能力矩阵](docs/harness-capabilities.md)
92
+ 手动接入与证据边界见 [harness 能力矩阵](docs/guides/harness-capabilities.md)
89
93
  及对应的 adapter README。
90
94
 
91
95
  ## 设计原则
@@ -184,7 +188,7 @@ DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
184
188
  DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#experimental-text-read-redaction),
185
189
  仅覆盖版本门控下的完整原生读取。它复用同一 Core,并让 DSH 同时重新生成
186
190
  返回文本和展示元数据;零模型原生验证已覆盖下一次请求和 JSONL 落盘。
187
- 另一次[官方 Flash 真实直接读取对照](docs/test-report-dsh-real-followup.md)
191
+ 另一次[官方 Flash 真实直接读取对照](docs/reports/test-report-dsh-real-followup.md)
188
192
  观察到支持规则的合成秘密被脱敏,同时保留有用配置;这不是提示注入 L2 结论。
189
193
 
190
194
  它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
@@ -327,7 +331,7 @@ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config
327
331
  - **没有 hook 的信道在结构上不可达。** 无代理的托管模型调用、模型自身的
328
332
  工具调用、程序内部产生的内容、人类剪贴板,一律**不给判决**——不作任何
329
333
  覆盖声明。详见 `references/channels.md` 与
330
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 的
334
+ [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 的
331
335
  可达性表。
332
336
  - **不是文件扫描器。** 它不是 gitleaks 的替代品;它扫描 Guard 在**发出
333
337
  路径上**能看到的内容。
@@ -346,6 +350,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
346
350
 
347
351
  # 查看状态与恢复:
348
352
  python3 skills/delete-guard/scripts/status.py
353
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
349
354
  python3 skills/delete-guard/scripts/restore.py list
350
355
  python3 skills/delete-guard/scripts/restore.py <txid>
351
356
 
@@ -353,6 +358,10 @@ python3 skills/delete-guard/scripts/restore.py <txid>
353
358
  python3 skills/delete-guard/scripts/gc.py
354
359
  ```
355
360
 
361
+ 本地新增的[垃圾桶位置查询](docs/guides/trash-index.md)提供 Agent 与未来前端
362
+ 共用的只读 JSON 接口,报告指定范围内的位置候选与布局标识;不读取恢复内容,
363
+ 地址也不代表清理授权。这项能力包含在 0.2.4 中。
364
+
356
365
  受支持的 harness 适配器可在 shell 命令执行前调用 Guard,再将退出码映射
357
366
  为宿主自己的工具判决:
358
367
 
@@ -367,7 +376,7 @@ python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
367
376
  ## 受保护行为一览
368
377
 
369
378
  下列是命令确实进入 Guard、且目标符合所述条件时的示意结果;各宿主实际
370
- 验证到的范围见 [能力矩阵](docs/harness-capabilities.md)。
379
+ 验证到的范围见 [能力矩阵](docs/guides/harness-capabilities.md)。
371
380
 
372
381
  ```text
373
382
  rm -rf build/ → RELOCATE (整树隔离后放行)
@@ -377,7 +386,8 @@ rm *.log → BLOCK (不透明通配;safe_delete 会显式展
377
386
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
378
387
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
379
388
  git clean -fd → RELOCATE (先 -n 枚举迁移再放行)
380
- git reset --hard → SNAPSHOT (Git 状态允许建立快照时)
389
+ git reset --hard → SNAPSHOT (路径冲突预检 + 已跟踪修改快照)
390
+ reset 覆盖未跟踪内容 → BLOCK (先单独保存冲突内容)
381
391
  git push --force → BLOCK (远端历史不交给 Agent 自动处理)
382
392
  node_modules/(已 ignore) → ALLOW (可证明可再生)
383
393
  隔离区写满 → BLOCK (绝不回退到永久删除)
@@ -386,14 +396,14 @@ node_modules/(已 ignore) → ALLOW (可证明可再生)
386
396
  ## 接入与验证矩阵
387
397
 
388
398
  [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
389
- [![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)
390
- [![DSH 0.1.5-rc.1 宿主 BLOCK 实测](https://img.shields.io/badge/DSH%200.1.5--rc.1-%E5%AE%BF%E4%B8%BB%20BLOCK%20%E5%AE%9E%E6%B5%8B-4D6BFE)](docs/test-report-dsh-0.1.5-rc.1.md)
391
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
392
- [![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)
393
- [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
394
- [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/test-report-workbuddy-windows-core.md)
395
- [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/release-notes-0.2.3-rc1.md#focused-windows-ci)
396
- [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/test-report-release-readiness-0.2.3.md)
399
+ [![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)
400
+ [![DSH 0.1.5-rc.1 宿主 BLOCK 实测](https://img.shields.io/badge/DSH%200.1.5--rc.1-%E5%AE%BF%E4%B8%BB%20BLOCK%20%E5%AE%9E%E6%B5%8B-4D6BFE)](docs/reports/test-report-dsh-0.1.5-rc.1.md)
401
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
402
+ [![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)
403
+ [![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)
404
+ [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
405
+ [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
406
+ [![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)
397
407
 
398
408
  徽章链接到各自范围内的证据,不代表所有工具和模型均已通过。
399
409
  DSH 文本读取脱敏是可选功能,默认关闭。
@@ -403,14 +413,14 @@ DSH 文本读取脱敏是可选功能,默认关闭。
403
413
 
404
414
  | Harness/实测版本 | 接入路径 | 证据与边界 |
405
415
  |---|---|---|
406
- | **Claude Code 2.1.270 / 2.1.273** | [Bash 原生 `PreToolUse`](adapters/claude/README.md) | [真实 CLI+脚本模型](docs/test-report-claude-code-harness.md):抽样 allow/ask/deny 与 Python 启动故障;其他工具未验证。 |
407
- | **DSH 0.1.5-rc.1** | [原生 pre-execute adapter](adapters/dsh/README.md) | [真实宿主打包插件探针](docs/test-report-dsh-0.1.5-rc.1.md):执行级 `BLOCK` 与已加载 adapter 的 Core 故障拒绝。另一次[真实模型 Lab 基线](docs/test-report-dsh-guard-lab.md)在 guard-off 下未触发诱饵,故没有 L2 缓解结论;模型主动提出破坏性 `bash` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
408
- | **DSH CLI rc.1/工具与 FS rc.2/Node 22** | [实验性文本读取脱敏](adapters/dsh/README.md#experimental-text-read-redaction),默认关闭 | [零模型原生验证](docs/test-report-dsh-read-redaction.md):下一次请求和 JSONL 落盘。[官方 Flash 真实读取 off/on](docs/test-report-dsh-real-followup.md):支持规则的合成秘密在工具内容/元数据/会话中被脱敏,有用配置保留;无提示注入 L2 结论。 |
409
- | **DSH 0.2.0-rc.2/Node 22** | [默认删除与可选文本读取 adapter](adapters/dsh/README.md) | [最新契约复核](docs/test-report-release-readiness-0.2.3.md):原生删除阻断、已审阅本地/沙箱 FS 的读取脱敏、下一次合成请求与 JSONL 落盘。原生 v4 Lab 支持仍有范围限制;没有新的真实模型 L2 结果。 |
410
- | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
411
- | **WorkBuddy(版本未记录;Windows 11)** | [Core/CLI](docs/test-report-workbuddy-windows-core.md) | 社区在 0.2.2 上发现两个 Core 缺陷,现有回归与聚焦 Windows CI 覆盖;没有 WorkBuddy adapter 或原生 hook 验证。 |
412
- | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
413
- | **Kimi Code 0.42.0 / 2.1.1** | [Bash 原生 `PreToolUse`](adapters/kimi-code/README.md) | [有界实测](docs/test-report-kimi-code-block.md):2.1.1 在 OAuth 官方模型和另一条已配置模型路由上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
416
+ | **Claude Code 2.1.270 / 2.1.273** | [Bash 原生 `PreToolUse`](adapters/claude/README.md) | [真实 CLI+脚本模型](docs/reports/test-report-claude-code-harness.md):抽样 allow/ask/deny 与 Python 启动故障;其他工具未验证。 |
417
+ | **DSH 0.1.5-rc.1** | [原生 pre-execute adapter](adapters/dsh/README.md) | [真实宿主打包插件探针](docs/reports/test-report-dsh-0.1.5-rc.1.md):执行级 `BLOCK` 与已加载 adapter 的 Core 故障拒绝。另一次[真实模型 Lab 基线](docs/reports/test-report-dsh-guard-lab.md)在 guard-off 下未触发诱饵,故没有 L2 缓解结论;模型主动提出破坏性 `bash` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
418
+ | **DSH CLI rc.1/工具与 FS rc.2/Node 22** | [实验性文本读取脱敏](adapters/dsh/README.md#experimental-text-read-redaction),默认关闭 | [零模型原生验证](docs/reports/test-report-dsh-read-redaction.md):下一次请求和 JSONL 落盘。[官方 Flash 真实读取 off/on](docs/reports/test-report-dsh-real-followup.md):支持规则的合成秘密在工具内容/元数据/会话中被脱敏,有用配置保留;无提示注入 L2 结论。 |
419
+ | **DSH 0.2.0-rc.2/Node 22** | [默认删除与可选文本读取 adapter](adapters/dsh/README.md) | [最新契约复核](docs/reports/test-report-release-readiness-0.2.3.md):原生删除阻断、已审阅本地/沙箱 FS 的读取脱敏、下一次合成请求与 JSONL 落盘。原生 v4 Lab 支持仍有范围限制;没有新的真实模型 L2 结果。 |
420
+ | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
421
+ | **WorkBuddy(版本未记录;Windows 11)** | [Core/CLI](docs/reports/test-report-workbuddy-windows-core.md) | 社区在 0.2.2 上发现两个 Core 缺陷,现有回归与聚焦 Windows CI 覆盖;没有 WorkBuddy adapter 或原生 hook 验证。 |
422
+ | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/reports/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
423
+ | **Kimi Code 0.42.0 / 2.1.1** | [Bash 原生 `PreToolUse`](adapters/kimi-code/README.md) | [有界实测](docs/reports/test-report-kimi-code-block.md):2.1.1 在 OAuth 官方模型和另一条已配置模型路由上均取得根 Bash PASS;0.42.0 另有主/子代理 BLOCK、ASK 硬拒绝和 Python 故障拒绝。hook 缺席/超时仍可能放行。 |
414
424
  | **其他/未列出宿主** | [自适配指南](adapters/INTEGRATION.md) | 未独立验证调用前阻断与目标未执行前,不作原生支持声明。 |
415
425
 
416
426
  由 Agent 协助接入时,先识别真实宿主版本与工具名称,阅读上表对应指南,
@@ -431,14 +441,14 @@ Kimi 或 Claude 安装可分别运行 `python3 doctor.py kimi --probe`、
431
441
  Agent Guard 运行路径生成去敏指纹;结果使用 `CURRENT`、`STALE`、
432
442
  `DRIFTED`、`BROKEN` 或 `UNVERIFIED`。即使是 `CURRENT` 也只代表静态预检,
433
443
  不是实时拦截证明。可选基线只保存解析后的版本和 SHA-256 指纹,详见
434
- [宿主漂移检查说明](docs/host-drift.md)。显式 `--live-sentinel` 可在私有空白
444
+ [宿主漂移检查说明](docs/guides/host-drift.md)。显式 `--live-sentinel` 可在私有空白
435
445
  夹具中消耗一次已配置模型调用,按 `PASS`、`FAIL`、`INCONCLUSIVE` 返回
436
446
  `NONE`/`NOTICE`、`CRITICAL` 或 `WARNING` 报警;仅仅“标记不存在”绝不算
437
447
  通过。它保留哈希化/去敏结果而不保留模型原始输出。这是可信提供方下的
438
448
  可靠性探针,不是针对恶意模型的沙盒。Kimi 的可选 doctor 因 TOML 解析需要 Python 3.11+;Core 与
439
449
  hook adapter 仍支持 Python 3.9+。
440
450
  各宿主的覆盖范围、证据等级和执行级验收条件见
441
- [harness 能力矩阵](docs/harness-capabilities.md)。
451
+ [harness 能力矩阵](docs/guides/harness-capabilities.md)。
442
452
 
443
453
  ## 目录结构
444
454
 
@@ -457,7 +467,7 @@ agent-guard/
457
467
  ├── adapters/dsh/ # DeepSeek Harness 接入桥
458
468
  ├── adapters/codex/harness/# CLI 验收 driver;不是原生 hook
459
469
  ├── tests/ # unittest 测试套件,含跨 harness 一致性
460
- └── docs/ # architecture · threat-model · friction log
470
+ └── docs/ # 使用指南 · 架构 · Lab · 测试报告 · 发布记录 · 历史设计
461
471
  ```
462
472
 
463
473
  Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`、
@@ -465,27 +475,18 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
465
475
 
466
476
  ## 文档
467
477
 
478
+ [文档导航](docs/README.md)按用途列出全部文档。历史报告保留所测版本与证据边界。
479
+
468
480
  | 阅读 | 内容 |
469
481
  |---|---|
470
482
  | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
471
- | [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
472
- | [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
473
- | [docs/guard-lab.md](docs/guard-lab.md) | 合成 Lab 流程、证据语义与不支持的信道 |
474
- | [docs/release-notes-0.2.3.md](docs/release-notes-0.2.3.md) | 0.2.3 正式版范围与证据边界 |
475
- | [docs/release-notes-0.2.3-rc2.md](docs/release-notes-0.2.3-rc2.md) | 已发布预览版:离线 guard-lab 与已复核 DSH 契约 |
476
- | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
477
- | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
478
- | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
479
- | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
483
+ | [使用指南](docs/README.md#guides) | 当前宿主能力、漂移检查与维护操作 |
484
+ | [架构与契约](docs/README.md#design) | 数据流、威胁模型与兼容约定 |
485
+ | [Lab](docs/README.md#lab) | 实验指南、任务模板与候选攻击素材 |
486
+ | [测试报告](docs/README.md#reports) | 按版本记录的 Core、CLI、hook 与 Lab 证据 |
487
+ | [发布记录](docs/README.md#releases) | 正式版与预览版各自的范围 |
488
+ | [历史设计与经验](docs/README.md#history) | 早期方案、实现教训与事故探索 |
480
489
  | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | 未列出宿主的自适配检查清单 |
481
- | [docs/threat-model.md](docs/threat-model.md) | 诚实边界:它是什么、不是什么 |
482
- | [docs/friction.md](docs/friction.md) | 真实 Agent 与宿主进程撞出来的教训(F1–F20) |
483
- | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | 去标识化事故探索与面向恢复的后续方向 |
484
- | [docs/test-report-codex-gpt-5.6-sol.md](docs/test-report-codex-gpt-5.6-sol.md) | v0.1.1 Codex 评估(medium + high) |
485
- | [docs/test-report-workbuddy-windows-core.md](docs/test-report-workbuddy-windows-core.md) | 社区 Windows Core/CLI 反馈与对应回归 |
486
- | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | DSH 0.1.5-rc.1 打包插件与执行级 `bash` 验收 |
487
- | [docs/test-report-dsh-guard-lab.md](docs/test-report-dsh-guard-lab.md) | DSH 真实模型有界 Lab 基线;无 L2 结论 |
488
- | [docs/test-report-dsh-v0.1.1.md](docs/test-report-dsh-v0.1.1.md) | v0.1.1 DSH 真机测试(DeepSeek V4 Pro high,极简模式) |
489
490
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
490
491
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
491
492
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil 规则表、reason code、豁免格式与审计结构 |
@@ -493,16 +494,17 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
493
494
 
494
495
  ## 状态与路线图
495
496
 
496
- **v0.2.3** 合并 Windows/Core 修复和离线 guard-lab
497
- MVP,并增强文本脱敏执行与校验、URI 口令识别、PyPI/新版 GitHub 令牌保护,
498
- 收窄部分误伤边界。已有的恢复工具、配置安全视图、Claude/Kimi 接入桥、
499
- doctor、宿主漂移检查与实时哨兵继续提供。
497
+ **v0.2.4** 在 0.2.3 上增加恢复维护与 trash 查询:拒绝 hard reset 与
498
+ 未跟踪/ignored 内容的碰撞,检查恢复来源和目标,强制恢复前先保存占位版本。
499
+ 只读查询提供 CLI、Agent 和未来前端共用的契约。已有文本脱敏、配置安全视图、
500
+ 离线 Lab、Claude/Kimi 接入桥、doctor、宿主漂移检查与实时哨兵继续提供。
500
501
  DSH 接入支持已复核的 `0.1.5-rc.1` 和 `0.2.0-rc.2` 契约;可选文本读取
501
502
  保护仍默认关闭。
502
503
 
503
- [0.2.3 说明](docs/release-notes-0.2.3.md)记录本次范围;
504
- [rc2](docs/release-notes-0.2.3-rc2.md)、[rc1](docs/release-notes-0.2.3-rc1.md)
505
- 和 [0.2.2](docs/release-notes-0.2.2.md) 说明保留各自历史范围。
504
+ [0.2.4 说明](docs/releases/release-notes-0.2.4.md)记录本次范围;
505
+ [0.2.3](docs/releases/release-notes-0.2.3.md)、
506
+ [rc2](docs/releases/release-notes-0.2.3-rc2.md)、[rc1](docs/releases/release-notes-0.2.3-rc1.md)
507
+ 和 [0.2.2](docs/releases/release-notes-0.2.2.md) 说明保留各自历史范围。
506
508
  已发布工件以 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
507
509
  和 npm 为准。
508
510
 
@@ -528,7 +530,7 @@ Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证
528
530
  事件链有问题时只报 `INCONCLUSIVE`。Lab 不能看到普通文件读取,不能证明数据
529
531
  已经外发,不能普遍封禁 LLM 调用,也不能抵抗同一系统用户权限下的对手。
530
532
  涉及真实 harness 前,请先跑零 Token 对照并阅读
531
- [guard-lab 指南](docs/guard-lab.md)。
533
+ [guard-lab 指南](docs/lab/guard-lab.md)。
532
534
  这些内建 case 只报 `CALIBRATION_ONLY`。另设的手动 `injection-probe` 会把诱饵
533
535
  命中记为 `EXPOSURE_OBSERVED`;只有未防护基线确实中招,并与相同协议、
534
536
  harness/版本/模型、实验组和任务哈希的开启防护试次配对,`compare` 才可能给出
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is a checklist for a user or their agent, **not** a claim that an
4
4
  unlisted host is supported. Start with the [capability and evidence
5
- matrix](../docs/harness-capabilities.md). A prompt, Skill, CLI call, or
5
+ matrix](../docs/guides/harness-capabilities.md). A prompt, Skill, CLI call, or
6
6
  adapter exit code alone does not prove automatic tool interception.
7
7
 
8
8
  ## 1. Identify the actual boundary
@@ -33,7 +33,7 @@ or a public report. If the host contract or version is unclear, mark it
33
33
  second copy of the rule table. Inspect the [Claude](claude/pre_tool_use.py),
34
34
  [Kimi](kimi-code/pre_tool_use.py), and [DSH](dsh/lib/index.js) adapters as
35
35
  examples of host-specific mapping, not drop-in templates.
36
- - **No verified blocking event:** use the [Skills](../skills/) and explicit
36
+ - **No verified blocking event:** use the [Skills](../skills) and explicit
37
37
  CLI cooperatively. Say `Skill/CLI only`; do not claim native interception.
38
38
  A hook limited to some tools does not cover other tools or hidden uploads.
39
39
 
@@ -73,7 +73,7 @@ For those two hosts, `--check-drift` adds local version/profile comparison and
73
73
  privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
74
74
  version change; it does not assert incompatibility. `CURRENT` still does not
75
75
  promote `host_interception` above `UNVERIFIED`. See the
76
- [host drift contract](../docs/host-drift.md).
76
+ [host drift contract](../docs/guides/host-drift.md).
77
77
 
78
78
  An explicit `--live-sentinel` can spend one configured model call to test one
79
79
  real root-agent Bash path in a private fixture. PASS requires a hashed exact
@@ -87,7 +87,7 @@ Report the host/version, tool and event, config scope, root/subagent path,
87
87
  dialect, model setup if one was used, the Core decision, host outcome, and
88
88
  independent non-execution observation. Label evidence as `CLI`, `Adapter`,
89
89
  `Hook observed`, or `Enforcement observed` using the
90
- [matrix definitions](../docs/harness-capabilities.md#evidence-levels).
90
+ [matrix definitions](../docs/guides/harness-capabilities.md#evidence-levels).
91
91
  Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
92
92
  `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
93
93
  evidence, not an independent security boundary against that same agent or a