@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.
- package/README.md +65 -62
- package/README.zh-CN.md +58 -58
- 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 +41 -16
- package/core/policy.py +11 -4
- 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} +54 -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} +39 -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.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 +18 -5
- 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.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 #
|
|
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
|
|
|
@@ -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.
|
|
60
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
|
|
60
61
|
```
|
|
61
62
|
|
|
62
|
-
**0.2.
|
|
63
|
-
|
|
64
|
-
|
|
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.
|
|
84
|
-
never install the unscoped package named agent-guard. If 0.2.
|
|
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 (
|
|
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
|
[](.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)
|
|
457
|
+
[](docs/reports/test-report-codex-gpt-6-astra-high.md)
|
|
458
|
+
[](docs/reports/test-report-dsh-0.1.5-rc.1.md)
|
|
459
|
+
[](docs/reports/test-report-zcode-glm-flash.md)
|
|
460
|
+
[](docs/reports/test-report-claude-code-harness.md)
|
|
461
|
+
[](docs/reports/test-report-kimi-code-block.md)
|
|
462
|
+
[](docs/reports/test-report-workbuddy-windows-core.md)
|
|
463
|
+
[](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
464
|
+
[](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/ #
|
|
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
|
-
| [
|
|
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 |
|
|
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.
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
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.
|
|
573
|
-
The [
|
|
574
|
-
[
|
|
575
|
-
[
|
|
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
|
[](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.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 #
|
|
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
|
|
|
@@ -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.
|
|
51
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
|
|
51
52
|
```
|
|
52
53
|
|
|
53
|
-
**0.2.
|
|
54
|
-
|
|
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.
|
|
73
|
-
agent-guard。若 0.2.
|
|
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 (
|
|
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
|
[](.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)
|
|
397
|
+
[](docs/reports/test-report-codex-gpt-6-astra-high.md)
|
|
398
|
+
[](docs/reports/test-report-dsh-0.1.5-rc.1.md)
|
|
399
|
+
[](docs/reports/test-report-zcode-glm-flash.md)
|
|
400
|
+
[](docs/reports/test-report-claude-code-harness.md)
|
|
401
|
+
[](docs/reports/test-report-kimi-code-block.md)
|
|
402
|
+
[](docs/reports/test-report-workbuddy-windows-core.md)
|
|
403
|
+
[](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
|
|
404
|
+
[](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/ #
|
|
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
|
-
| [
|
|
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 变更、证据等级与已知限制 |
|
|
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.
|
|
497
|
-
|
|
498
|
-
|
|
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.
|
|
504
|
-
[
|
|
505
|
-
|
|
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` 才可能给出
|
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
|
|
@@ -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
|