@mokuyoaxis/agent-guard 0.2.3 → 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 (69) hide show
  1. package/README.md +65 -62
  2. package/README.zh-CN.md +58 -58
  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 +41 -16
  16. package/core/policy.py +11 -4
  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} +54 -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} +39 -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.md +89 -0
  40. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  41. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  42. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  43. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  44. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  45. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  46. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  47. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  48. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  49. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  50. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  51. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  52. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  53. package/package.json +1 -1
  54. package/skills/delete-guard/SKILL.md +38 -0
  55. package/skills/delete-guard/references/policy.md +18 -5
  56. package/skills/delete-guard/scripts/check.py +19 -0
  57. package/skills/delete-guard/scripts/restore.py +18 -6
  58. package/skills/delete-guard/scripts/status.py +52 -0
  59. package/skills/exfil-guard/references/channels.md +1 -1
  60. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  61. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  62. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  63. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  64. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  65. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  66. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  67. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  68. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  69. /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
+ [![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,15 +38,16 @@ 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
 
@@ -56,12 +57,13 @@ Use the scoped npm package or a stable Git checkout. The unscoped
56
57
  Pinned npm installation 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
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** 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
65
67
  [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
66
68
  which artifacts are available.
67
69
 
@@ -80,8 +82,8 @@ the host's hook support. Then give your coding agent the following setup prompt
80
82
 
81
83
  ```text
82
84
  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,
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,
85
87
  report that and use the existing checkout or ask me to choose a published
86
88
  version. Before installing, ask me to choose and
87
89
  approve a stable user-owned prefix. Treat the checkout or installed package
@@ -104,7 +106,7 @@ intercepted, and any unverified paths.
104
106
  ```
105
107
 
106
108
  For manual setup and evidence limits, see the
107
- [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
108
110
  host.
109
111
 
110
112
  ## Design principles
@@ -214,7 +216,7 @@ DSH also offers a [default-off text-read redaction prototype](adapters/dsh/READM
214
216
  for complete native reads in a pinned composition. It reuses Core and
215
217
  regenerates both rendered text and presentation metadata; a zero-model native
216
218
  probe covers the next request and durable JSONL log. A separate
217
- [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)
218
220
  observed supported synthetic-secret redaction while useful config stayed readable.
219
221
 
220
222
  It is a prevention and redaction guard, not a compensation engine: after an
@@ -384,7 +386,7 @@ is a false security claim:
384
386
  call with no proxy, the model's own tool calls, content produced *inside* a
385
387
  program, and the human clipboard get **no verdict at all** — no coverage is
386
388
  claimed there. See `references/channels.md` and
387
- [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
388
390
  the reachability table this claim is traceable to.
389
391
  - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
390
392
  guard can see *on the way out*.
@@ -404,6 +406,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
404
406
 
405
407
  # inspect and undo:
406
408
  python3 skills/delete-guard/scripts/status.py
409
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
407
410
  python3 skills/delete-guard/scripts/restore.py list
408
411
  python3 skills/delete-guard/scripts/restore.py <txid>
409
412
 
@@ -411,6 +414,11 @@ python3 skills/delete-guard/scripts/restore.py <txid>
411
414
  python3 skills/delete-guard/scripts/gc.py
412
415
  ```
413
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
+
414
422
  A harness adapter can invoke the guard before a supported shell command and
415
423
  map its exit status to the host's own tool decision:
416
424
 
@@ -425,7 +433,7 @@ exit 1 → guard error; fail closed
425
433
  ## What gets protected
426
434
 
427
435
  These examples assume the command reaches the guard and its targets meet the
428
- stated conditions; see the [capability matrix](docs/harness-capabilities.md)
436
+ stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
429
437
  for what each host has actually demonstrated.
430
438
 
431
439
  ```text
@@ -436,7 +444,8 @@ rm *.log → BLOCK (opaque glob; safe_delete expands it)
436
444
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
437
445
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
438
446
  git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
439
- 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)
440
449
  git push --force → BLOCK (remote history is never automated)
441
450
  node_modules/ (ignored) → ALLOW (provably regenerable)
442
451
  quarantine full → BLOCK (never fall back to permanent delete)
@@ -445,14 +454,14 @@ quarantine full → BLOCK (never fall back to permanent delete)
445
454
  ## Integration and validation matrix
446
455
 
447
456
  [![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)
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)
456
465
 
457
466
  These badges link to scoped evidence; they do not certify every tool or model.
458
467
  The DSH text-read feature is optional and off by default.
@@ -463,14 +472,14 @@ those evidence levels explicit:
463
472
 
464
473
  | Harness / tested version | Integration path | Evidence and limit |
465
474
  |---|---|---|
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. |
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. |
474
483
  | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
475
484
 
476
485
  For agent-led setup: identify the actual host version and tool names, follow
@@ -494,7 +503,7 @@ configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
494
503
  `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
495
504
  evidence, not interception proof. Optional create-new baselines contain only
496
505
  the parsed version and SHA-256 fingerprints. See the
497
- [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.
498
507
  An explicit `--live-sentinel` can then spend one configured model call in a
499
508
  private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
500
509
  `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
@@ -504,7 +513,7 @@ The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
504
513
  hook adapter continue to support Python 3.9+.
505
514
  See the [Kimi](adapters/kimi-code/README.md) and
506
515
  [Claude](adapters/claude/README.md) adapter guides.
507
- See [harness capabilities and evidence levels](docs/harness-capabilities.md)
516
+ See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
508
517
  for the per-host scope and execution-level acceptance criteria.
509
518
 
510
519
  ## Repository layout
@@ -524,7 +533,7 @@ agent-guard/
524
533
  ├── adapters/dsh/ # DeepSeek Harness integration bridge
525
534
  ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
526
535
  ├── tests/ # unittest suites incl. cross-harness conformance
527
- └── docs/ # architecture · threat-model · friction log
536
+ └── docs/ # guides · design · Lab · reports · releases · history
528
537
  ```
529
538
 
530
539
  Skills guide agent behavior; constraints live in Core. Future
@@ -533,27 +542,19 @@ compensation engine without restructuring.
533
542
 
534
543
  ## Documentation
535
544
 
545
+ The [documentation index](docs/README.md) lists every document by purpose.
546
+ Historical reports retain their tested versions and evidence limits.
547
+
536
548
  | Read | For |
537
549
  |---|---|
538
550
  | [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 |
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 |
548
557
  | [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
558
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
558
559
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
559
560
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
@@ -561,18 +562,20 @@ compensation engine without restructuring.
561
562
 
562
563
  ## Status & roadmap
563
564
 
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.
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.
569
571
  The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
570
572
  its optional text-read protection remains off by default.
571
573
 
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.
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.
576
579
  Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
577
580
  and npm for published artifacts.
578
581
 
@@ -604,7 +607,7 @@ the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
604
607
  never an optimistic pass. The Lab cannot observe ordinary file
605
608
  reads, prove remote transfer, universally block LLM calls, or resist a same-UID
606
609
  adversary. Start with the zero-token controls and read the
607
- [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.
608
611
  The built-in cases report `CALIBRATION_ONLY`. A separate manual
609
612
  `injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
610
613
  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
+ [![v0.2.4 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.4-5B6B7A)](docs/releases/release-notes-0.2.4.md)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -31,13 +31,14 @@ 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
 
@@ -47,11 +48,12 @@ git push --force → BLOCK # 不自动改写远端历史
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
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** 包含 hard reset 碰撞检查、restore 来源/目标
55
+ 验证、强制恢复时保留当前版本,以及垃圾桶只读位置查询。
56
+ 本次行为变化与证据边界见 [发布说明](docs/releases/release-notes-0.2.4.md);
55
57
  npm 徽章和 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
56
58
  展示实际可用的发布工件。
57
59
 
@@ -69,8 +71,8 @@ Core 需要 Python 3.9+ 和 Git;是否能自动拦截取决于宿主是否提
69
71
 
70
72
  ```text
71
73
  请为当前工作区接入 agent-guard。只使用现有 Git checkout,或精确的 scoped
72
- npm 包 @mokuyoaxis/agent-guard@0.2.3;不要安装无作用域的同名
73
- agent-guard。若 0.2.3 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
74
+ npm 包 @mokuyoaxis/agent-guard@0.2.4;不要安装无作用域的同名
75
+ agent-guard。若 0.2.4 尚不可用,说明情况,使用现有 checkout 或让我选择已发布版本。
74
76
  安装前先让我选择并批准一个稳定的用户目录,然后把 checkout 或 npm 安装后的
75
77
  包根目录作为下文的 /absolute/path/to/agent-guard。
76
78
  先识别当前 harness 实际支持的 hook 与 Skill,阅读本 README 和对应 adapter
@@ -85,7 +87,7 @@ adapters/kimi-code/README.md,DSH 参考 adapters/dsh/README.md。
85
87
  拦截证明。最后报告宿主版本、工具范围、实际安装内容、确实拦截的调用和未验证路径。
86
88
  ```
87
89
 
88
- 手动接入与证据边界见 [harness 能力矩阵](docs/harness-capabilities.md)
90
+ 手动接入与证据边界见 [harness 能力矩阵](docs/guides/harness-capabilities.md)
89
91
  及对应的 adapter README。
90
92
 
91
93
  ## 设计原则
@@ -184,7 +186,7 @@ DSH 的 `PreToolDecision`、Claude Code PreToolUse 的 `ask`,或在不支持
184
186
  DSH 另有[默认关闭的文本 `read` 脱敏原型](adapters/dsh/README.md#experimental-text-read-redaction),
185
187
  仅覆盖版本门控下的完整原生读取。它复用同一 Core,并让 DSH 同时重新生成
186
188
  返回文本和展示元数据;零模型原生验证已覆盖下一次请求和 JSONL 落盘。
187
- 另一次[官方 Flash 真实直接读取对照](docs/test-report-dsh-real-followup.md)
189
+ 另一次[官方 Flash 真实直接读取对照](docs/reports/test-report-dsh-real-followup.md)
188
190
  观察到支持规则的合成秘密被脱敏,同时保留有用配置;这不是提示注入 L2 结论。
189
191
 
190
192
  它做的是预防和脱敏,不是补偿:内容发出去后就不能撤销。它也**不是
@@ -327,7 +329,7 @@ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config
327
329
  - **没有 hook 的信道在结构上不可达。** 无代理的托管模型调用、模型自身的
328
330
  工具调用、程序内部产生的内容、人类剪贴板,一律**不给判决**——不作任何
329
331
  覆盖声明。详见 `references/channels.md` 与
330
- [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 的
332
+ [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 的
331
333
  可达性表。
332
334
  - **不是文件扫描器。** 它不是 gitleaks 的替代品;它扫描 Guard 在**发出
333
335
  路径上**能看到的内容。
@@ -346,6 +348,7 @@ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
346
348
 
347
349
  # 查看状态与恢复:
348
350
  python3 skills/delete-guard/scripts/status.py
351
+ python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
349
352
  python3 skills/delete-guard/scripts/restore.py list
350
353
  python3 skills/delete-guard/scripts/restore.py <txid>
351
354
 
@@ -353,6 +356,10 @@ python3 skills/delete-guard/scripts/restore.py <txid>
353
356
  python3 skills/delete-guard/scripts/gc.py
354
357
  ```
355
358
 
359
+ 本地新增的[垃圾桶位置查询](docs/guides/trash-index.md)提供 Agent 与未来前端
360
+ 共用的只读 JSON 接口,报告指定范围内的位置候选与布局标识;不读取恢复内容,
361
+ 地址也不代表清理授权。这项能力包含在 0.2.4 中。
362
+
356
363
  受支持的 harness 适配器可在 shell 命令执行前调用 Guard,再将退出码映射
357
364
  为宿主自己的工具判决:
358
365
 
@@ -367,7 +374,7 @@ python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
367
374
  ## 受保护行为一览
368
375
 
369
376
  下列是命令确实进入 Guard、且目标符合所述条件时的示意结果;各宿主实际
370
- 验证到的范围见 [能力矩阵](docs/harness-capabilities.md)。
377
+ 验证到的范围见 [能力矩阵](docs/guides/harness-capabilities.md)。
371
378
 
372
379
  ```text
373
380
  rm -rf build/ → RELOCATE (整树隔离后放行)
@@ -377,7 +384,8 @@ rm *.log → BLOCK (不透明通配;safe_delete 会显式展
377
384
  cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
378
385
  touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
379
386
  git clean -fd → RELOCATE (先 -n 枚举迁移再放行)
380
- git reset --hard → SNAPSHOT (Git 状态允许建立快照时)
387
+ git reset --hard → SNAPSHOT (路径冲突预检 + 已跟踪修改快照)
388
+ reset 覆盖未跟踪内容 → BLOCK (先单独保存冲突内容)
381
389
  git push --force → BLOCK (远端历史不交给 Agent 自动处理)
382
390
  node_modules/(已 ignore) → ALLOW (可证明可再生)
383
391
  隔离区写满 → BLOCK (绝不回退到永久删除)
@@ -386,14 +394,14 @@ node_modules/(已 ignore) → ALLOW (可证明可再生)
386
394
  ## 接入与验证矩阵
387
395
 
388
396
  [![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)
397
+ [![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)
398
+ [![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)
399
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
400
+ [![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)
401
+ [![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)
402
+ [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
403
+ [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
404
+ [![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
405
 
398
406
  徽章链接到各自范围内的证据,不代表所有工具和模型均已通过。
399
407
  DSH 文本读取脱敏是可选功能,默认关闭。
@@ -403,14 +411,14 @@ DSH 文本读取脱敏是可选功能,默认关闭。
403
411
 
404
412
  | Harness/实测版本 | 接入路径 | 证据与边界 |
405
413
  |---|---|---|
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 缺席/超时仍可能放行。 |
414
+ | **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 启动故障;其他工具未验证。 |
415
+ | **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` 时的强制执行仍未验证。单独开启的读取脱敏路径见下一行。 |
416
+ | **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 结论。 |
417
+ | **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 结果。 |
418
+ | **Codex CLI 0.154.0(所测会话)** | [Skill + 生产 CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | 较早源码的合作式验收;不声称原生 hook。 |
419
+ | **WorkBuddy(版本未记录;Windows 11)** | [Core/CLI](docs/reports/test-report-workbuddy-windows-core.md) | 社区在 0.2.2 上发现两个 Core 缺陷,现有回归与聚焦 Windows CI 覆盖;没有 WorkBuddy adapter 或原生 hook 验证。 |
420
+ | **ZCode(版本未记录;win32)** | [历史 Skill/CLI+hook 试次](docs/reports/test-report-zcode-glm-flash.md) | 旧报告记录了持久许可绕过 hook;当前版本未验证。 |
421
+ | **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
422
  | **其他/未列出宿主** | [自适配指南](adapters/INTEGRATION.md) | 未独立验证调用前阻断与目标未执行前,不作原生支持声明。 |
415
423
 
416
424
  由 Agent 协助接入时,先识别真实宿主版本与工具名称,阅读上表对应指南,
@@ -431,14 +439,14 @@ Kimi 或 Claude 安装可分别运行 `python3 doctor.py kimi --probe`、
431
439
  Agent Guard 运行路径生成去敏指纹;结果使用 `CURRENT`、`STALE`、
432
440
  `DRIFTED`、`BROKEN` 或 `UNVERIFIED`。即使是 `CURRENT` 也只代表静态预检,
433
441
  不是实时拦截证明。可选基线只保存解析后的版本和 SHA-256 指纹,详见
434
- [宿主漂移检查说明](docs/host-drift.md)。显式 `--live-sentinel` 可在私有空白
442
+ [宿主漂移检查说明](docs/guides/host-drift.md)。显式 `--live-sentinel` 可在私有空白
435
443
  夹具中消耗一次已配置模型调用,按 `PASS`、`FAIL`、`INCONCLUSIVE` 返回
436
444
  `NONE`/`NOTICE`、`CRITICAL` 或 `WARNING` 报警;仅仅“标记不存在”绝不算
437
445
  通过。它保留哈希化/去敏结果而不保留模型原始输出。这是可信提供方下的
438
446
  可靠性探针,不是针对恶意模型的沙盒。Kimi 的可选 doctor 因 TOML 解析需要 Python 3.11+;Core 与
439
447
  hook adapter 仍支持 Python 3.9+。
440
448
  各宿主的覆盖范围、证据等级和执行级验收条件见
441
- [harness 能力矩阵](docs/harness-capabilities.md)。
449
+ [harness 能力矩阵](docs/guides/harness-capabilities.md)。
442
450
 
443
451
  ## 目录结构
444
452
 
@@ -457,7 +465,7 @@ agent-guard/
457
465
  ├── adapters/dsh/ # DeepSeek Harness 接入桥
458
466
  ├── adapters/codex/harness/# CLI 验收 driver;不是原生 hook
459
467
  ├── tests/ # unittest 测试套件,含跨 harness 一致性
460
- └── docs/ # architecture · threat-model · friction log
468
+ └── docs/ # 使用指南 · 架构 · Lab · 测试报告 · 发布记录 · 历史设计
461
469
  ```
462
470
 
463
471
  Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`、
@@ -465,27 +473,18 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
465
473
 
466
474
  ## 文档
467
475
 
476
+ [文档导航](docs/README.md)按用途列出全部文档。历史报告保留所测版本与证据边界。
477
+
468
478
  | 阅读 | 内容 |
469
479
  |---|---|
470
480
  | [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 变更、证据等级与已知限制 |
481
+ | [使用指南](docs/README.md#guides) | 当前宿主能力、漂移检查与维护操作 |
482
+ | [架构与契约](docs/README.md#design) | 数据流、威胁模型与兼容约定 |
483
+ | [Lab](docs/README.md#lab) | 实验指南、任务模板与候选攻击素材 |
484
+ | [测试报告](docs/README.md#reports) | 按版本记录的 Core、CLI、hook 与 Lab 证据 |
485
+ | [发布记录](docs/README.md#releases) | 正式版与预览版各自的范围 |
486
+ | [历史设计与经验](docs/README.md#history) | 早期方案、实现教训与事故探索 |
480
487
  | [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
488
  | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | 证据优先级、确定性回放、恢复与落地门禁 |
490
489
  | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | 完整规则表与判决码 |
491
490
  | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil 规则表、reason code、豁免格式与审计结构 |
@@ -493,16 +492,17 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
493
492
 
494
493
  ## 状态与路线图
495
494
 
496
- **v0.2.3** 合并 Windows/Core 修复和离线 guard-lab
497
- MVP,并增强文本脱敏执行与校验、URI 口令识别、PyPI/新版 GitHub 令牌保护,
498
- 收窄部分误伤边界。已有的恢复工具、配置安全视图、Claude/Kimi 接入桥、
499
- doctor、宿主漂移检查与实时哨兵继续提供。
495
+ **v0.2.4** 在 0.2.3 上增加恢复维护与 trash 查询:拒绝 hard reset 与
496
+ 未跟踪/ignored 内容的碰撞,检查恢复来源和目标,强制恢复前先保存占位版本。
497
+ 只读查询提供 CLI、Agent 和未来前端共用的契约。已有文本脱敏、配置安全视图、
498
+ 离线 Lab、Claude/Kimi 接入桥、doctor、宿主漂移检查与实时哨兵继续提供。
500
499
  DSH 接入支持已复核的 `0.1.5-rc.1` 和 `0.2.0-rc.2` 契约;可选文本读取
501
500
  保护仍默认关闭。
502
501
 
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) 说明保留各自历史范围。
502
+ [0.2.4 说明](docs/releases/release-notes-0.2.4.md)记录本次范围;
503
+ [0.2.3](docs/releases/release-notes-0.2.3.md)、
504
+ [rc2](docs/releases/release-notes-0.2.3-rc2.md)、[rc1](docs/releases/release-notes-0.2.3-rc1.md)
505
+ 和 [0.2.2](docs/releases/release-notes-0.2.2.md) 说明保留各自历史范围。
506
506
  已发布工件以 [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
507
507
  和 npm 为准。
508
508
 
@@ -528,7 +528,7 @@ Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证
528
528
  事件链有问题时只报 `INCONCLUSIVE`。Lab 不能看到普通文件读取,不能证明数据
529
529
  已经外发,不能普遍封禁 LLM 调用,也不能抵抗同一系统用户权限下的对手。
530
530
  涉及真实 harness 前,请先跑零 Token 对照并阅读
531
- [guard-lab 指南](docs/guard-lab.md)。
531
+ [guard-lab 指南](docs/lab/guard-lab.md)。
532
532
  这些内建 case 只报 `CALIBRATION_ONLY`。另设的手动 `injection-probe` 会把诱饵
533
533
  命中记为 `EXPOSURE_OBSERVED`;只有未防护基线确实中招,并与相同协议、
534
534
  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
@@ -78,11 +78,11 @@ prompt.
78
78
  A passing check does **not** inspect Claude's merged settings, prove a
79
79
  running session loaded the hook, or verify host-level interception. For
80
80
  those claims, use the isolated host acceptance in the
81
- [capability matrix](../../docs/harness-capabilities.md).
81
+ [capability matrix](../../docs/guides/harness-capabilities.md).
82
82
  Add `--check-drift` to compare the installed Claude Code version with the
83
83
  shipped profile and compute privacy-safe configuration/runtime
84
84
  fingerprints. `CURRENT` still does not prove live interception; see the
85
- [drift status contract](../../docs/host-drift.md).
85
+ [drift status contract](../../docs/guides/host-drift.md).
86
86
  An explicit `--live-sentinel` may then use one configured model call in a
87
87
  private fixture and requires adapter, audit, host-feedback, and marker
88
88
  evidence. It keeps `dontAsk` and never enables permission bypass.
@@ -126,7 +126,7 @@ returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
126
126
  Validated end-to-end against real Claude Code sessions (2.1.270 and 2.1.273) with a
127
127
  scripted mock Anthropic endpoint standing in for the model, plus the
128
128
  `python3`-free regression tests. See
129
- [`docs/test-report-claude-code-harness.md`](../../docs/test-report-claude-code-harness.md)
129
+ [`docs/reports/test-report-claude-code-harness.md`](../../docs/reports/test-report-claude-code-harness.md)
130
130
  and the shipped harness in [`harness/`](harness/README.md).
131
131
 
132
132
  The guard child is spawned with `sys.executable`, never `python3` from