@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.
- package/README.md +70 -63
- package/README.zh-CN.md +61 -59
- package/adapters/INTEGRATION.md +4 -4
- package/adapters/claude/README.md +3 -3
- package/adapters/claude/harness/README.md +1 -1
- package/adapters/codex/harness/README.md +2 -2
- package/adapters/dsh/README.md +10 -6
- package/adapters/dsh/harness/README.md +8 -8
- package/adapters/dsh/harness/guard_lab.py +3 -3
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +7 -7
- package/adapters/kimi-code/harness/README.md +3 -3
- package/adapters/kimi-code/harness/guard_lab.py +1 -1
- package/core/__init__.py +1 -1
- package/core/classifier.py +66 -17
- package/core/policy.py +28 -13
- package/core/recovery.py +256 -23
- package/core/trash_index.py +193 -0
- package/docs/README.md +104 -0
- package/docs/{architecture.md → design/architecture.md} +31 -6
- package/docs/{compatibility.md → design/compatibility.md} +80 -4
- package/docs/{threat-model.md → design/threat-model.md} +4 -4
- package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
- package/docs/guides/trash-index.md +106 -0
- package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
- package/docs/{friction.md → history/friction.md} +61 -0
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
- package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
- package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
- package/docs/releases/release-notes-0.2.4-hotfix.1.md +75 -0
- package/docs/releases/release-notes-0.2.4.md +89 -0
- package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
- package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
- package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
- package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
- package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
- package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
- package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
- package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
- package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
- package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
- package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
- package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +38 -0
- package/skills/delete-guard/references/policy.md +29 -9
- package/skills/delete-guard/scripts/check.py +19 -0
- package/skills/delete-guard/scripts/restore.py +18 -6
- package/skills/delete-guard/scripts/status.py +52 -0
- package/skills/exfil-guard/references/channels.md +1 -1
- /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
- /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
- /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
- /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
- /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
- /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
- /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
- /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
- /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
- /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
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](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 #
|
|
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`;
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
63
|
-
|
|
64
|
-
|
|
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.
|
|
84
|
-
never install the unscoped package named agent-guard. If 0.2.
|
|
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 (
|
|
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
|
[](.github/workflows/ci.yml)
|
|
448
|
-
[](docs/test-report-codex-gpt-6-astra-high.md)
|
|
449
|
-
[](docs/test-report-dsh-0.1.5-rc.1.md)
|
|
450
|
-
[](docs/test-report-zcode-glm-flash.md)
|
|
451
|
-
[](docs/test-report-claude-code-harness.md)
|
|
452
|
-
[](docs/test-report-kimi-code-block.md)
|
|
453
|
-
[](docs/test-report-workbuddy-windows-core.md)
|
|
454
|
-
[](docs/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
455
|
-
[](docs/test-report-release-readiness-0.2.3.md)
|
|
461
|
+
[](docs/reports/test-report-codex-gpt-6-astra-high.md)
|
|
462
|
+
[](docs/reports/test-report-dsh-0.1.5-rc.1.md)
|
|
463
|
+
[](docs/reports/test-report-zcode-glm-flash.md)
|
|
464
|
+
[](docs/reports/test-report-claude-code-harness.md)
|
|
465
|
+
[](docs/reports/test-report-kimi-code-block.md)
|
|
466
|
+
[](docs/reports/test-report-workbuddy-windows-core.md)
|
|
467
|
+
[](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
468
|
+
[](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/ #
|
|
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
|
-
| [
|
|
540
|
-
| [
|
|
541
|
-
| [
|
|
542
|
-
| [
|
|
543
|
-
| [
|
|
544
|
-
| [
|
|
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.
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
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.
|
|
573
|
-
The [
|
|
574
|
-
[
|
|
575
|
-
[
|
|
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
|
[](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
|
|
5
5
|
[](LICENSE)
|
|
6
6
|
[](https://www.python.org/)
|
|
7
|
-
[](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 #
|
|
34
|
+
git reset --hard → SNAPSHOT # 先检查路径冲突,再保存已跟踪修改
|
|
35
35
|
git push --force → BLOCK # 不自动改写远端历史
|
|
36
36
|
```
|
|
37
37
|
|
|
38
38
|
这是受支持输入的**示意判决**,不是让你执行这些命令,也不表示所有宿主都会
|
|
39
|
-
自动拦截。被忽略且可再生的目标可能判为 `ALLOW`;
|
|
40
|
-
|
|
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.
|
|
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.
|
|
54
|
-
|
|
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.
|
|
73
|
-
agent-guard。若 0.2.
|
|
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 (
|
|
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
|
[](.github/workflows/ci.yml)
|
|
389
|
-
[](docs/test-report-codex-gpt-6-astra-high.md)
|
|
390
|
-
[](docs/test-report-dsh-0.1.5-rc.1.md)
|
|
391
|
-
[](docs/test-report-zcode-glm-flash.md)
|
|
392
|
-
[](docs/test-report-claude-code-harness.md)
|
|
393
|
-
[](docs/test-report-kimi-code-block.md)
|
|
394
|
-
[](docs/test-report-workbuddy-windows-core.md)
|
|
395
|
-
[](docs/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
396
|
-
[](docs/test-report-release-readiness-0.2.3.md)
|
|
399
|
+
[](docs/reports/test-report-codex-gpt-6-astra-high.md)
|
|
400
|
+
[](docs/reports/test-report-dsh-0.1.5-rc.1.md)
|
|
401
|
+
[](docs/reports/test-report-zcode-glm-flash.md)
|
|
402
|
+
[](docs/reports/test-report-claude-code-harness.md)
|
|
403
|
+
[](docs/reports/test-report-kimi-code-block.md)
|
|
404
|
+
[](docs/reports/test-report-workbuddy-windows-core.md)
|
|
405
|
+
[](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
406
|
+
[](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/ #
|
|
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
|
-
| [
|
|
472
|
-
| [
|
|
473
|
-
| [
|
|
474
|
-
| [
|
|
475
|
-
| [
|
|
476
|
-
| [
|
|
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.
|
|
497
|
-
|
|
498
|
-
|
|
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.
|
|
504
|
-
[
|
|
505
|
-
|
|
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` 才可能给出
|
package/adapters/INTEGRATION.md
CHANGED
|
@@ -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
|
|
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
|