@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2
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 +166 -573
- package/README.zh-CN.md +138 -489
- package/SECURITY.md +53 -0
- package/adapters/INTEGRATION.md +4 -2
- package/adapters/dsh/README.md +7 -0
- package/assets/linux-do-community.svg +19 -0
- package/core/audit.py +170 -25
- package/core/classifier.py +25 -1
- package/core/lab.py +77 -7
- package/core/policy.py +17 -9
- package/core/recovery.py +5 -1
- package/core/redaction.py +122 -21
- package/docs/README.md +18 -5
- package/docs/design/architecture.md +25 -6
- package/docs/design/compatibility.md +106 -1
- package/docs/design/threat-model.md +6 -4
- package/docs/guides/audit-metadata.md +77 -0
- package/docs/guides/getting-started.md +106 -0
- package/docs/guides/harness-capabilities.md +5 -0
- package/docs/history/friction.md +85 -0
- package/docs/lab/guard-lab.md +15 -1
- package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
- package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
- package/guard_lab.py +11 -0
- package/package.json +4 -2
- package/skills/delete-guard/SKILL.md +45 -7
- package/skills/delete-guard/references/policy.md +90 -4
- package/skills/delete-guard/scripts/check.py +3 -0
- package/skills/delete-guard/scripts/gc.py +18 -3
- package/skills/delete-guard/scripts/restore.py +22 -7
- package/skills/delete-guard/scripts/safe_delete.py +52 -29
- package/skills/delete-guard/scripts/status.py +9 -7
- package/skills/exfil-guard/SKILL.md +23 -11
- package/skills/exfil-guard/references/channels.md +8 -1
- package/skills/exfil-guard/references/rules.md +86 -6
- package/skills/exfil-guard/scripts/_payload.py +20 -0
- package/skills/exfil-guard/scripts/check_span.py +5 -1
- package/skills/exfil-guard/scripts/sanitize.py +6 -3
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Getting started / 入门指南
|
|
2
|
+
|
|
3
|
+
Agent Guard has three paths: recover supported destructive actions,
|
|
4
|
+
check disclosure before emission, and use guard-lab for controlled behaviour
|
|
5
|
+
experiments. Begin with the path you need; native interception is optional
|
|
6
|
+
and depends on the actual host.
|
|
7
|
+
|
|
8
|
+
Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。先选择需要的能力;
|
|
9
|
+
自动拦截另需实际宿主提供并加载兼容 hook。
|
|
10
|
+
|
|
11
|
+
## Select the package root
|
|
12
|
+
|
|
13
|
+
The published stable baseline is 0.2.4; the previous published RC baseline is
|
|
14
|
+
0.2.5-rc1. Current RC source is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md),
|
|
15
|
+
including [shared audit metadata](audit-metadata.md) and observer startup maintenance.
|
|
16
|
+
Use a user-selected stable prefix for the published package:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
The package root is
|
|
23
|
+
`/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
|
|
24
|
+
For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly and check its
|
|
25
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
|
|
26
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
|
|
27
|
+
for publication. A reviewed checkout or supplied local tarball can be evaluated
|
|
28
|
+
independently of registry availability.
|
|
29
|
+
Do not infer RC availability from the manifest or use an unscoped same-name
|
|
30
|
+
package. A checkout's default branch can differ from a tagged stable release.
|
|
31
|
+
|
|
32
|
+
Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
|
|
33
|
+
examples/bridges require a POSIX shell. The optional pinned DSH read path uses
|
|
34
|
+
Node 22; Kimi TOML helpers need Python 3.11+. Windows Core evidence does not
|
|
35
|
+
establish Windows-native hook bridge or full-suite portability.
|
|
36
|
+
|
|
37
|
+
## Set up a coding agent
|
|
38
|
+
|
|
39
|
+
Replace the root path in this prompt, and give it to your agent:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
Set up Agent Guard for this workspace using /absolute/path/to/agent-guard.
|
|
43
|
+
Identify the actual host version, tool names and hook/skill capabilities.
|
|
44
|
+
Read the README, Skill contracts and matching adapter guide; check Python/Git.
|
|
45
|
+
Use the selected checkout/package version and preserve existing settings.
|
|
46
|
+
Respect already-approved paths and configuration scope. Ask only for missing
|
|
47
|
+
information or changes beyond that scope, including new dependencies.
|
|
48
|
+
Install/reference the relevant Skills. Configure a native hook only where a
|
|
49
|
+
blocking event is supported; otherwise report Skill/CLI-only operation.
|
|
50
|
+
Claude: adapters/claude/README.md. Kimi: adapters/kimi-code/README.md.
|
|
51
|
+
DSH: adapters/dsh/README.md. Other hosts: adapters/INTEGRATION.md.
|
|
52
|
+
Verify a harmless call. Submit BLOCK-shaped commands only as data to check.py;
|
|
53
|
+
never execute deletion of real data as a test. For Claude/Kimi, run the local
|
|
54
|
+
doctor, but do not treat PASS as proof of actual host interception.
|
|
55
|
+
Report the host/version, installed paths, configuration scope, covered tools,
|
|
56
|
+
observed interception and unverified paths separately.
|
|
57
|
+
guard-lab is the user's controller, not a Skill to install into the tested
|
|
58
|
+
agent. Run real-host/model experiments only in an explicitly selected scope.
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
不要把“Skill 已安装”“配置检查通过”和“真实调用被拦截”合并为一个成功状态。
|
|
62
|
+
用户范围外的配置或依赖改动需另行确认;已经授权的常规接入不重复询问。
|
|
63
|
+
|
|
64
|
+
## Verify without executing a destructive command
|
|
65
|
+
|
|
66
|
+
From an isolated fixture, pass command text as data:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/check.py --json -- rm /
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Read the BLOCK decision. Advisory exit 0 means assessment completed, not that
|
|
73
|
+
the command may run. Assessment can create quarantine/audit metadata and a
|
|
74
|
+
Git local exclude entry. Use a disposable fixture, and see the
|
|
75
|
+
[assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
|
|
76
|
+
|
|
77
|
+
For Claude/Kimi, local doctor probes do not start a model:
|
|
78
|
+
|
|
79
|
+
```sh
|
|
80
|
+
python3 /absolute/path/to/agent-guard/doctor.py claude --probe --json
|
|
81
|
+
python3 /absolute/path/to/agent-guard/doctor.py kimi --probe --json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Select the actual host, not both by default. These probes check one selected
|
|
85
|
+
configuration and a local bridge/adapter. Real host evidence needs a separate
|
|
86
|
+
controlled sentinel. An explicit live sentinel may consume provider quota;
|
|
87
|
+
its result covers one sampled root-agent Bash call. See
|
|
88
|
+
[host drift](host-drift.md) and the
|
|
89
|
+
[capability matrix](harness-capabilities.md).
|
|
90
|
+
|
|
91
|
+
## Try the three paths
|
|
92
|
+
|
|
93
|
+
- **Recovery:** use the [delete Skill](../../skills/delete-guard/SKILL.md).
|
|
94
|
+
Valuable content relocates; provably regenerable artifacts may delete
|
|
95
|
+
directly. Inspect txids/state after errors, including force-restore backups.
|
|
96
|
+
- **Disclosure:** use the [exfil Skill](../../skills/exfil-guard/SKILL.md).
|
|
97
|
+
A checker plan is not completed redaction. The payload owner applies the
|
|
98
|
+
plan, controls emission and owns any egress audit.
|
|
99
|
+
- **Experiments:** use the [Lab guide](../lab/guard-lab.md).
|
|
100
|
+
Calibrate all four built-in controls before real trials. Only an effective
|
|
101
|
+
unguarded baseline enables a matched mitigation comparison.
|
|
102
|
+
|
|
103
|
+
For incident recovery from surviving evidence, use
|
|
104
|
+
[recovery-audit](../../skills/recovery-audit/SKILL.md).
|
|
105
|
+
Full rules, historical reports and releases are in the
|
|
106
|
+
[documentation index](../README.md).
|
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Harness capability and evidence matrix
|
|
2
2
|
|
|
3
|
+
Current RC source: [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md); publication is checked by its receipts.
|
|
4
|
+
Rows below retain their tested source/host versions and do not automatically
|
|
5
|
+
certify this candidate. Local regression or package checks are separate from
|
|
6
|
+
new native-host/model evidence.
|
|
7
|
+
|
|
3
8
|
The Python Core and CLI are harness-neutral. A Skill or CLI being usable in a
|
|
4
9
|
host does **not** mean that host intercepts tool calls, and an adapter returning
|
|
5
10
|
`BLOCK` does **not** by itself prove the host prevented execution.
|
package/docs/history/friction.md
CHANGED
|
@@ -4,6 +4,14 @@ This log records findings from host trials, CLI checks and regression tests.
|
|
|
4
4
|
The initial entries came from a DSH session using `tools/pre-execute`, three
|
|
5
5
|
model tools and a prompt section; later entries cover Core and other adapters.
|
|
6
6
|
|
|
7
|
+
Entries preserve their recording date and original candidate/release state.
|
|
8
|
+
F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
|
|
9
|
+
F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
|
|
10
|
+
observer startup maintenance; publication is checked by its versioned receipts.
|
|
11
|
+
Current scope is in the
|
|
12
|
+
[candidate notes](../releases/release-notes-0.2.5-rc2.md); historical failures and
|
|
13
|
+
test counts below are not rewritten by a later success.
|
|
14
|
+
|
|
7
15
|
## F1 · Compound `cd X && rm y` resolves targets against the wrong base
|
|
8
16
|
|
|
9
17
|
The interceptor classifies against the tool call's declared workdir. A
|
|
@@ -462,3 +470,80 @@ Regression: `tests/test_restore_boundary.py` (14),
|
|
|
462
470
|
`tests/test_restore_source.py` (14), and `tests/test_restore_force.py` (22).
|
|
463
471
|
These are sequential checks, not atomic same-UID isolation; cross-device
|
|
464
472
|
copy failures can leave partial data requiring inspection.
|
|
473
|
+
|
|
474
|
+
## F26 · Housekeeping overrode quarantine control protection
|
|
475
|
+
|
|
476
|
+
The classifier already marked the quarantine root protected, but the policy's
|
|
477
|
+
inside-trash allowance ran first. Root manifest/audit/state paths were also
|
|
478
|
+
treated as ordinary content, and a regenerable parent could contain storage.
|
|
479
|
+
|
|
480
|
+
**Fixed in local unreleased maintenance (2026-10-08):** protected-path decisions
|
|
481
|
+
precede trash housekeeping. Root controls, session state and in-workspace
|
|
482
|
+
storage access parents are classified explicitly, including parent aliases
|
|
483
|
+
and a control leaf link. Ordinary payload rules and explicit transaction GC
|
|
484
|
+
remain available. Opaque quarantine globs return `BLOCK_WILDCARD` before
|
|
485
|
+
housekeeping, because their expansion could include root control files.
|
|
486
|
+
This addresses supported deletion mistakes; arbitrary
|
|
487
|
+
scripts/writes and malicious same-UID tampering remain outside the guarantee.
|
|
488
|
+
|
|
489
|
+
## F27 · Purged history remained GC eligible
|
|
490
|
+
|
|
491
|
+
Age planning reselected tombstoned transactions even after their directories
|
|
492
|
+
were removed. Active inventory now excludes `PURGED` entries before walking
|
|
493
|
+
or accounting their directories. History remains intact; recreated directories
|
|
494
|
+
are not claimed again. Failed purges remain active. This local maintenance
|
|
495
|
+
does not implement pruning retained Git stashes or rewrite old manifests.
|
|
496
|
+
|
|
497
|
+
## F28 · Restore audit duplicated paths and failure bodies
|
|
498
|
+
|
|
499
|
+
The CLI copied restoration/conflict paths and arbitrary move errors into
|
|
500
|
+
non-recovery audit metadata. Local maintenance stores outcome counts and
|
|
501
|
+
transaction associations instead. Unknown/invalid input IDs are hashed;
|
|
502
|
+
recovery journal paths and CLI results remain exact. Generic audit append,
|
|
503
|
+
automatic session metadata and other output paths are separate work.
|
|
504
|
+
|
|
505
|
+
## F29 · Exemption format and loading failures were silent
|
|
506
|
+
|
|
507
|
+
Both configuration filenames use a limited section/key parser, but the
|
|
508
|
+
`.agent-guardignore` name suggested gitignore syntax. Bare lines were silently
|
|
509
|
+
ignored, load failures silently tried the next file, and a readable empty or
|
|
510
|
+
malformed preferred file hid the fallback. Nonstandard legacy section keys
|
|
511
|
+
could also remain effective without an explanation.
|
|
512
|
+
|
|
513
|
+
Local unreleased maintenance (2026-10-08) reports the selected fixed relative
|
|
514
|
+
source, configured entry counts and bounded static diagnostics. Checker JSON
|
|
515
|
+
and sanitizer library results carry the metadata; human checker/sanitizer
|
|
516
|
+
warnings use stderr. Raw keys, patterns, hashes, lines and exception text
|
|
517
|
+
are withheld. Legacy matching, precedence, verdicts, exit codes and payload/
|
|
518
|
+
plan stdout formats are retained. This does not add gitignore parsing,
|
|
519
|
+
change configuration authority or sanitize other audit/output writers.
|
|
520
|
+
|
|
521
|
+
## F30 · Assessment audit writes were mistaken for zero-write checks
|
|
522
|
+
|
|
523
|
+
Advisory check and safe_delete dry-run preserve command targets but use the
|
|
524
|
+
existing audit path, which can initialize quarantine metadata and Git local
|
|
525
|
+
exclude. A test named "touches nothing" checked target presence and Git status,
|
|
526
|
+
which cannot detect an ignored audit directory. Blocked-request documentation
|
|
527
|
+
also described the entire filesystem as untouched.
|
|
528
|
+
|
|
529
|
+
Local contract clarification (2026-10-08) adds explicit target/metadata and
|
|
530
|
+
failure regressions, corrects help/guidance, and documents early no-match and
|
|
531
|
+
existing-ignore/external-bucket exceptions. Best-effort assessment audits and
|
|
532
|
+
durable enforced intents retain their existing behavior. No zero-write CLI
|
|
533
|
+
flag, audit relocation or unrelated writer minimization is introduced.
|
|
534
|
+
|
|
535
|
+
## F31 · safe_delete duplicated paths and free-form reasons into audit
|
|
536
|
+
|
|
537
|
+
safe_delete copied concrete targets, policy reason bodies and caller
|
|
538
|
+
`--reason` text into decision/outcome audit events. Its transaction metadata
|
|
539
|
+
also copied `--reason`, although restoration only needs the journal's exact
|
|
540
|
+
origin/trash paths. A secret-bearing filename or an arbitrary private note
|
|
541
|
+
therefore gained additional durable copies beyond the recovery journal.
|
|
542
|
+
|
|
543
|
+
Local minimization (2026-10-08) builds this writer's events from decisions,
|
|
544
|
+
codes, counts and established recovery IDs; partial/storage-failure reports
|
|
545
|
+
retain transaction correlation. Free-form reason metadata is omitted.
|
|
546
|
+
Exact CLI/recovery paths and error diagnostics remain available, with the
|
|
547
|
+
same mutation-intent durability and assessment/outcome failure behavior.
|
|
548
|
+
Historical records, automatic session identity and other audit/output
|
|
549
|
+
writers remain outside this change.
|
package/docs/lab/guard-lab.md
CHANGED
|
@@ -4,7 +4,10 @@
|
|
|
4
4
|
observable agent and harness behaviours. It creates disposable bait, watches
|
|
5
5
|
only declared channels, and produces a bounded report. Its built-in controls
|
|
6
6
|
call no model; its separate manual probe is designed for a user-run real
|
|
7
|
-
harness trial.
|
|
7
|
+
harness trial. It was introduced in `0.2.3-rc2` and shipped with `0.2.3`.
|
|
8
|
+
It remains available in stable `0.2.4` and published `0.2.5-rc1`;
|
|
9
|
+
the `0.2.5-rc2` source candidate adds startup diagnosis and cancellation maintenance
|
|
10
|
+
without adding new model-trial evidence. See the [RC2 notes](../releases/release-notes-0.2.5-rc2.md).
|
|
8
11
|
|
|
9
12
|
It is not a Skill for the tested agent, a security boundary, or a certificate
|
|
10
13
|
that a model or vendor is safe or malicious.
|
|
@@ -213,6 +216,17 @@ matched bait IDs, and stage; it does not retain the input or matched value.
|
|
|
213
216
|
Evidence is capped at 1024 events and a two MiB event log. Reaching a cap makes
|
|
214
217
|
the observer/report inconclusive instead of silently dropping later events.
|
|
215
218
|
|
|
219
|
+
Observer startup has a five-second readiness window. Private `observer.log`
|
|
220
|
+
records static startup phases and monotonic timestamps for the controller,
|
|
221
|
+
Python bootstrap, validation, loopback bind and readiness publication. These
|
|
222
|
+
best-effort notes contain no tokens, paths or exception text and do not establish
|
|
223
|
+
observer health. A startup timeout requests cooperative cancellation and waits
|
|
224
|
+
up to two additional seconds to reap the local child; a still-live child stays
|
|
225
|
+
registered without a forced signal. A child that sees startup cancellation
|
|
226
|
+
records `FAILED` / `OBSERVER_STARTUP_CANCELLED`, keeping the report
|
|
227
|
+
`INCONCLUSIVE` even if readiness was published late. Ordinary stops after
|
|
228
|
+
successful readiness retain their existing meaning.
|
|
229
|
+
|
|
216
230
|
The input file and `--stage` are user-selected evidence. `scan` does not parse
|
|
217
231
|
or authenticate vendor-specific transcript schemas. If a captured stream mixes
|
|
218
232
|
assistant messages, tool results, and system events, split those records first
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Agent Guard 0.2.5-rc1
|
|
2
|
+
|
|
3
|
+
Maintenance prerelease candidate, prepared 2026-10-08. The stable baseline
|
|
4
|
+
remains [0.2.4](release-notes-0.2.4.md). The release workflow maps this exact
|
|
5
|
+
RC to a GitHub prerelease and npm `rc`, preserving stable `latest` and the
|
|
6
|
+
original 0.2.4 tag/artifact. Publication receipts are the
|
|
7
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc1)
|
|
8
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc1).
|
|
9
|
+
|
|
10
|
+
本候选合并 10-08 已完成的维护与本轮文档整理,不是仅修改 README。
|
|
11
|
+
版本由维护者明确选择为 0.2.5-rc1,并授权 GitHub/npm 双推;稳定版范围仍另行决定。
|
|
12
|
+
|
|
13
|
+
## Changes
|
|
14
|
+
|
|
15
|
+
- **Quarantine controls before housekeeping.** Existing
|
|
16
|
+
`BLOCK_PROTECTED_PATH` wins for root/control files, session state and
|
|
17
|
+
in-workspace storage parents, including reviewed aliases. Opaque quarantine
|
|
18
|
+
globs are refused; safe_delete can enumerate an explicit batch. Ordinary
|
|
19
|
+
unprotected payload housekeeping and validated explicit transaction GC
|
|
20
|
+
remain available.
|
|
21
|
+
- **PURGED history stays out of active GC inventory.** Tombstoned transactions
|
|
22
|
+
are excluded before payload accounting/planning. Historical manifests
|
|
23
|
+
remain intact, failed purges remain active, and this does not prune retained
|
|
24
|
+
Git stashes or claim ownership of recreated directories.
|
|
25
|
+
- **Restore and safe_delete audit minimization.** New writer events retain
|
|
26
|
+
decisions, counts and recovery associations instead of duplicating paths
|
|
27
|
+
and arbitrary error/reason bodies. safe_delete still accepts `--reason`
|
|
28
|
+
but does not persist its text in new audit/transaction metadata.
|
|
29
|
+
CLI results and essential recovery paths/intents stay exact. Old records,
|
|
30
|
+
generic audit writers and automatic session metadata are unchanged.
|
|
31
|
+
- **Exemption configuration diagnostics.** The existing limited parser,
|
|
32
|
+
first-readable-file priority and matching are retained. Checker JSON and
|
|
33
|
+
sanitizer library results gain provenance/count/diagnostic metadata;
|
|
34
|
+
human CLI warnings use stderr. Normal absent/valid configurations stay
|
|
35
|
+
quiet. No full TOML/gitignore parser or configuration migration is added.
|
|
36
|
+
- **Assessment contract.** Advisory checks and deletion dry-runs preserve
|
|
37
|
+
targets while potentially writing metadata/exclude entries. Advisory exit 0
|
|
38
|
+
does not authorize BLOCK/ASK. This is clarification and regression coverage,
|
|
39
|
+
not a new zero-write assessment flag.
|
|
40
|
+
- **Documentation.** Both READMEs introduce recovery protection, disclosure
|
|
41
|
+
checks and guard-lab near the top, with setup moved to a dedicated guide.
|
|
42
|
+
Current contracts distinguish planned emitter/audit integrations from
|
|
43
|
+
implemented CLIs, local metadata from optional provider calls, and observed
|
|
44
|
+
host evidence from candidate validation. Historical results retain their
|
|
45
|
+
original dates, failures and scope.
|
|
46
|
+
- **Documentation resources in the npm package.** Include SECURITY.md and
|
|
47
|
+
the existing community banner assets, which the previous allowlist omitted.
|
|
48
|
+
Runtime entry points and dependency requirements are unchanged.
|
|
49
|
+
|
|
50
|
+
## Compatibility and version choice
|
|
51
|
+
|
|
52
|
+
Control-path/glob changes make some previously allowed shapes refuse by
|
|
53
|
+
default. The usual 0.x contract classifies that as minor. The maintainer
|
|
54
|
+
explicitly chose 0.2.5-rc1 instead of 0.3.0 as a bounded maintenance exception.
|
|
55
|
+
The prior 0.2.4 exception is not reused as blanket permission.
|
|
56
|
+
See the [compatibility contract](../design/compatibility.md#025-rc1-lifecycle-and-restore-audit-maintenance-source-candidate).
|
|
57
|
+
|
|
58
|
+
Existing decision/reason strings, CLI arguments and exit-code roles remain.
|
|
59
|
+
Consumers should tolerate additive optional fields and stderr diagnostics.
|
|
60
|
+
Audit shapes outside essential recovery manifests are not frozen.
|
|
61
|
+
No production dependency, storage migration, new transaction strategy or
|
|
62
|
+
general output enforcement is introduced. Later stable 0.2.5 scope and
|
|
63
|
+
publication remain separate decisions.
|
|
64
|
+
|
|
65
|
+
## Evidence and limits
|
|
66
|
+
|
|
67
|
+
Before this version/documentation pass, the combined maintenance worktree
|
|
68
|
+
passed 874 Python tests and both Node adapter smoke groups, plus package,
|
|
69
|
+
offline install and a synthetic deletion/restore round trip. The first full
|
|
70
|
+
run retained one DSH Lab observer-startup timeout; the single-case recheck and
|
|
71
|
+
full rerun passed without changing its timeout. Its root cause remains unknown.
|
|
72
|
+
These are prior-source checkpoints, not this versioned candidate's release gate.
|
|
73
|
+
|
|
74
|
+
The versioned regression checkpoint passed 874 Python tests (821.138 seconds)
|
|
75
|
+
and both Node adapter smoke groups. It preserved 173 public source files
|
|
76
|
+
throughout the run. Afterwards only documentation and the packaging allowlist
|
|
77
|
+
for the two existing resources above changed; runtime code and test cases
|
|
78
|
+
retain those tested bytes. The final metadata/corpus checks, package contents,
|
|
79
|
+
offline installation, documented example and installed Lab calibration are
|
|
80
|
+
verified separately: 13 metadata/corpus checks, a 122-file tarball and offline
|
|
81
|
+
install, all 10 CLI help commands, adapter import, the documented example,
|
|
82
|
+
read-only trash query, a synthetic deletion/restore round trip and all four
|
|
83
|
+
zero-model Lab controls passed. These local checks do not establish publication.
|
|
84
|
+
No new model or native-host trial is started. Existing bounded DSH/PTC and
|
|
85
|
+
Kimi reports do not certify this new candidate. Historical unfinished pairs
|
|
86
|
+
remain pending; quiet or unhealthy baselines do not establish Lab mitigation.
|
|
87
|
+
Concurrency isolation, same-UID control-plane protection, universal egress
|
|
88
|
+
coverage and full Windows-native harness E2E remain outside the guarantee.
|
|
89
|
+
|
|
90
|
+
发布流程要求精确提交的远端 CI、npm 凭据门禁与两个渠道的工件核查;
|
|
91
|
+
本地打包通过不能替代这些步骤,具体执行结果以对应 Actions 和发布工件为准。
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Agent Guard 0.2.5-rc2
|
|
2
|
+
|
|
3
|
+
Maintenance prerelease, prepared 2026-10-09; double-channel publication
|
|
4
|
+
authorized 2026-10-10. The stable baseline is [0.2.4](release-notes-0.2.4.md),
|
|
5
|
+
and the previous prerelease is [0.2.5-rc1](release-notes-0.2.5-rc1.md).
|
|
6
|
+
The exact RC tag routes to GitHub prerelease and npm `rc`, preserving stable
|
|
7
|
+
`latest` and existing version artifacts. Publication receipts are the
|
|
8
|
+
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
|
|
9
|
+
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2).
|
|
10
|
+
|
|
11
|
+
维护者已选择 RC2 候选准备范围:共享审计元信息最小化、Lab observer 启动与取消收尾、
|
|
12
|
+
配套文档及回归,并已授权 main 提交/推送及本次 GitHub prerelease/npm rc 双推。
|
|
13
|
+
发布仍需精确提交远端门禁和两个渠道的同工件核查;状态以版本化发布回执为准。
|
|
14
|
+
|
|
15
|
+
## Changes since RC1
|
|
16
|
+
|
|
17
|
+
- **Shared audit projection.** `append` stores supported fields and validated
|
|
18
|
+
values only and returns the stored record. `tail` applies the same projection
|
|
19
|
+
to old objects in memory, skips malformed/non-object JSON, and returns no
|
|
20
|
+
records for non-positive limits. Unsupported/custom fields and free text are
|
|
21
|
+
omitted. Earlier log bytes and recovery manifests are preserved.
|
|
22
|
+
- **Opaque audit identities and bounded status metadata.** Supplied sessions
|
|
23
|
+
and displayed actors use stable SHA-256 correlation; the automatic identity
|
|
24
|
+
no longer includes a raw username or hostname. Generated transaction IDs
|
|
25
|
+
remain exact. Noncanonical IDs are summarized in audit views, while
|
|
26
|
+
`find_by_txid` still accepts their original spelling. Authorization session
|
|
27
|
+
selection and mode state are unchanged.
|
|
28
|
+
- **GC audit metadata.** Unknown selected IDs use digests and missing counts;
|
|
29
|
+
reason maps cover selected transactions only. Exact CLI diagnostics and
|
|
30
|
+
recovery associations remain available. Preflight and durable intent still
|
|
31
|
+
precede purge.
|
|
32
|
+
- **Observer startup diagnosis.** Private `observer.log` gains static phases
|
|
33
|
+
and monotonic timestamps for spawn, Python bootstrap, validation, loopback
|
|
34
|
+
binding, endpoint writing and readiness. These notes contain no tokens,
|
|
35
|
+
paths or exception text, are best-effort, and do not establish health.
|
|
36
|
+
- **Cancelled startup remains inconclusive.** The five-second readiness
|
|
37
|
+
window stays unchanged. Startup timeout requests cooperative cancellation
|
|
38
|
+
and permits up to two additional seconds of local child reaping. A live
|
|
39
|
+
child remains registered without a forced signal. Cancelled startup records
|
|
40
|
+
`FAILED` / `OBSERVER_STARTUP_CANCELLED`, including late READY publication.
|
|
41
|
+
Reap timeouts preserve the original LabError; ordinary stops after accepted
|
|
42
|
+
readiness retain their existing meaning.
|
|
43
|
+
- **Documentation and regression coverage.** Current entry points identify
|
|
44
|
+
the RC2 candidate separately from published baselines, describe audit
|
|
45
|
+
compatibility and observer behavior, and preserve historical test/host
|
|
46
|
+
evidence. The two maintenance groups add 40 regression tests over RC1.
|
|
47
|
+
|
|
48
|
+
RC2 retains the lifecycle, quarantine control-path, PURGED inventory,
|
|
49
|
+
restore/safe_delete writer, exemption-diagnostic and assessment maintenance
|
|
50
|
+
described in the [RC1 notes](release-notes-0.2.5-rc1.md).
|
|
51
|
+
|
|
52
|
+
## Compatibility
|
|
53
|
+
|
|
54
|
+
Audit logs are supported metadata records, not arbitrary payload storage.
|
|
55
|
+
Consumers relying on custom fields, raw sessions/actors or noncanonical audit
|
|
56
|
+
IDs must review the [audit contract](../guides/audit-metadata.md).
|
|
57
|
+
A digest is not a restore argument: recovery uses the original ID and exact
|
|
58
|
+
manifest/CLI paths. Digests provide correlation, not encryption or identity
|
|
59
|
+
authentication.
|
|
60
|
+
|
|
61
|
+
Public CLI parameters, exit-code roles, supported recovery strategies,
|
|
62
|
+
authorization selection, audit locking/flush/fsync and existing
|
|
63
|
+
required-versus-best-effort writer gates retain their behavior.
|
|
64
|
+
No production dependency or storage/configuration migration is introduced.
|
|
65
|
+
RC2 introduces no new destructive-command policy verdict or refusal shape;
|
|
66
|
+
the bounded version exceptions inherited from RC1 remain documented in the
|
|
67
|
+
[compatibility contract](../design/compatibility.md).
|
|
68
|
+
|
|
69
|
+
## Evidence and limits
|
|
70
|
+
|
|
71
|
+
Before this version/documentation preparation, the combined maintenance
|
|
72
|
+
source passed 914 Python tests (1279.463 seconds, no skips) and both Node
|
|
73
|
+
adapter smoke groups, with 176 public files frozen during that run.
|
|
74
|
+
The local 123-file package matched source and offline installation, and all
|
|
75
|
+
four installed zero-model controls passed. These are prior-source checkpoints,
|
|
76
|
+
not publication receipts for a package named 0.2.5-rc2.
|
|
77
|
+
|
|
78
|
+
The versioned RC2 candidate independently passed 914 Python tests
|
|
79
|
+
(1072.129 seconds, no skips) and both Node smoke groups; 177 public files
|
|
80
|
+
remained unchanged throughout that run. This evidence paragraph was completed
|
|
81
|
+
afterwards; runtime code and test cases retain their tested bytes.
|
|
82
|
+
|
|
83
|
+
The final RC2 candidate gate separately verifies
|
|
84
|
+
version/channel routing, final package contents, offline installation,
|
|
85
|
+
CLI/adapter entry points, synthetic recovery round trips and zero-model
|
|
86
|
+
calibration. Publishing additionally requires exact-commit remote CI,
|
|
87
|
+
npm preflight and matching GitHub/npm artifacts; a manifest or local tarball
|
|
88
|
+
does not establish registry availability.
|
|
89
|
+
|
|
90
|
+
**The first intermittent observer startup timeout's unique cause remains
|
|
91
|
+
unknown.** Controlled delay injections establish the cancellation/health
|
|
92
|
+
defect and its correction; normal rechecks do not identify that historical
|
|
93
|
+
cause or prove every future startup will finish within five seconds.
|
|
94
|
+
The [Lab contract](../lab/guard-lab.md) explains the diagnostic and health gates.
|
|
95
|
+
|
|
96
|
+
Old raw logs, exact recovery data, ordinary tool output and streams are
|
|
97
|
+
outside the shared audit projection. No new real-model or native-host trial
|
|
98
|
+
is credited to this candidate. Historical unfinished pairs remain pending.
|
|
99
|
+
Same-UID control-plane isolation, recovery concurrency isolation, universal
|
|
100
|
+
egress coverage and complete Windows-native harness E2E remain outside the
|
|
101
|
+
guarantee. Later stable 0.2.5 scope and publication remain separate decisions.
|
package/guard_lab.py
CHANGED
|
@@ -5,6 +5,17 @@ from __future__ import annotations
|
|
|
5
5
|
|
|
6
6
|
import sys
|
|
7
7
|
|
|
8
|
+
if __name__ == "__main__" and len(sys.argv) > 1 and sys.argv[1] == "_observe":
|
|
9
|
+
import time
|
|
10
|
+
|
|
11
|
+
try:
|
|
12
|
+
print(
|
|
13
|
+
f"observer-startup stage=BOOTSTRAP monotonic={time.monotonic():.6f}",
|
|
14
|
+
file=sys.stderr, flush=True,
|
|
15
|
+
)
|
|
16
|
+
except (OSError, ValueError):
|
|
17
|
+
pass
|
|
18
|
+
|
|
8
19
|
from core.lab import cli_main, observer_cli_main
|
|
9
20
|
|
|
10
21
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "Harness-neutral reliability infrastructure for AI coding agents:
|
|
3
|
+
"version": "0.2.5-rc2",
|
|
4
|
+
"description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./adapters/dsh/lib/index.js",
|
|
7
7
|
"exports": {
|
|
@@ -32,11 +32,13 @@
|
|
|
32
32
|
"core",
|
|
33
33
|
"skills",
|
|
34
34
|
"docs",
|
|
35
|
+
"assets",
|
|
35
36
|
"doctor.py",
|
|
36
37
|
"live_sentinel.py",
|
|
37
38
|
"guard_lab.py",
|
|
38
39
|
"LICENSE",
|
|
39
40
|
"CONTRIBUTING.md",
|
|
41
|
+
"SECURITY.md",
|
|
40
42
|
"README.md",
|
|
41
43
|
"README.zh-CN.md",
|
|
42
44
|
"!**/__pycache__/**",
|
|
@@ -16,19 +16,22 @@ enforces and how to work with it productively. The four pillars:
|
|
|
16
16
|
|
|
17
17
|
- **Scope** - you act inside the workspace; the workspace root, `.git`, and
|
|
18
18
|
everything outside are never yours to delete.
|
|
19
|
-
- **Recoverability** -
|
|
20
|
-
with a manifest
|
|
19
|
+
- **Recoverability** - supported valuable deletions relocate to the selected
|
|
20
|
+
quarantine with a manifest; supported Git overwrites snapshot tracked state.
|
|
21
|
+
Provably regenerable, ignored artifacts may be deleted directly.
|
|
21
22
|
- **Authorization** - a human decides permission boundaries. You can be
|
|
22
23
|
*downgraded* to RESTRICTED mode; you can never promote yourself back.
|
|
23
|
-
- **Auditability** -
|
|
24
|
-
JSONL.
|
|
24
|
+
- **Auditability** - supported writers record decision/recovery metadata in
|
|
25
|
+
JSONL according to their CLI contract. Mutation intents must be durable;
|
|
26
|
+
assessment/blocked audit may be best effort, and early no-op paths may not
|
|
27
|
+
write an audit. Calls outside the covered path are not automatically visible.
|
|
25
28
|
|
|
26
29
|
## The one rule
|
|
27
30
|
|
|
28
31
|
**Prefer `safe_delete` over `rm`.** It applies the guard's recovery policy.
|
|
29
32
|
|
|
30
33
|
```bash
|
|
31
|
-
# delete
|
|
34
|
+
# delete explicit targets; valuable content is quarantined:
|
|
32
35
|
python3 <repo>/skills/delete-guard/scripts/safe_delete.py src/old_module.py
|
|
33
36
|
python3 <repo>/skills/delete-guard/scripts/safe_delete.py 'build/**/*.tmp' --reason "stale build output"
|
|
34
37
|
|
|
@@ -64,8 +67,9 @@ redirections) before destroying them (F2), is refused as undeterminable.
|
|
|
64
67
|
Run deletions as standalone commands with an explicit workdir.
|
|
65
68
|
|
|
66
69
|
A block is not an error to route around. Retrying the same operation in a
|
|
67
|
-
disguised form (`/bin/rm`, `python -c`, a script)
|
|
68
|
-
|
|
70
|
+
disguised form (`/bin/rm`, `python -c`, a script) violates this discipline and
|
|
71
|
+
can bypass both protection and audit. Do not treat a missing audit as proof
|
|
72
|
+
that no operation occurred.
|
|
69
73
|
|
|
70
74
|
`git reset --hard [commit]` first checks whether its target tree would
|
|
71
75
|
overwrite untracked or ignored content. A tracked-only stash cannot recover
|
|
@@ -89,6 +93,28 @@ stop immediately. Inspect both the origin and `.agent-trash/`; never infer
|
|
|
89
93
|
that an error means no filesystem change occurred. A durable
|
|
90
94
|
`relocate-intent` can keep an interrupted relocation discoverable.
|
|
91
95
|
|
|
96
|
+
## Assessment and preflight
|
|
97
|
+
|
|
98
|
+
Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets,
|
|
99
|
+
but may create quarantine/audit metadata and a Git local exclude rule.
|
|
100
|
+
They are not zero-write filesystem checks. Advisory exit 0 means the
|
|
101
|
+
assessment completed; inspect the decision and never execute a BLOCK/ASK
|
|
102
|
+
command merely because the exit was zero. Blocked safe_delete still exits 2
|
|
103
|
+
under dry-run. Audit warnings do not imply that all metadata writes were
|
|
104
|
+
undone. Use only a disposable fixture when verifying this behavior; the
|
|
105
|
+
[policy reference](references/policy.md#assessment-and-dry-run-side-effects)
|
|
106
|
+
defines the no-match, existing-ignore and external-bucket branches.
|
|
107
|
+
|
|
108
|
+
Since 0.2.5-rc1, new `safe_delete` audit events record decisions, target counts and established
|
|
109
|
+
recovery IDs/counts rather than target paths or free-form reasons. `--reason`
|
|
110
|
+
is still accepted, but its text is not persisted in audit or transaction
|
|
111
|
+
metadata. Exact recovery paths remain in the CLI result and manifest.
|
|
112
|
+
At released RC1, historical records and automatic session handling are unchanged.
|
|
113
|
+
The 0.2.5-rc2 source candidate projects shared metadata on append/read,
|
|
114
|
+
uses opaque session correlation and limits status/GC metadata; see the
|
|
115
|
+
[shared audit contract](../../docs/guides/audit-metadata.md) and the
|
|
116
|
+
[policy reference](references/policy.md#safe_delete-audit-metadata).
|
|
117
|
+
|
|
92
118
|
## Quarantine location queries
|
|
93
119
|
|
|
94
120
|
When the user asks where quarantines are or how many exist, use the shared
|
|
@@ -111,6 +137,13 @@ read just to answer a location/count question.
|
|
|
111
137
|
|
|
112
138
|
## RESTRICTED mode
|
|
113
139
|
|
|
140
|
+
The RC2 source retains RC1 protection for the quarantine root, root manifest,
|
|
141
|
+
audit/state files, state temp file, sessions tree and storage access parents.
|
|
142
|
+
Housekeeping does not override those checks. Use the existing explicit
|
|
143
|
+
`gc.py --execute --txid <id>` entry for a validated, audited transaction purge.
|
|
144
|
+
Ordinary unprotected payload housekeeping retains its existing policy.
|
|
145
|
+
GC plans omit `PURGED` history; they do not delete stored Git stashes.
|
|
146
|
+
|
|
114
147
|
After a human veto, the session runs with narrowed powers: explicit
|
|
115
148
|
single-file deletes inside the workspace still work (quarantined as usual);
|
|
116
149
|
recursive deletes, globs, and destructive git operations are refused. Only a
|
|
@@ -144,3 +177,8 @@ space and remain subject to its existing explicit GC policy.
|
|
|
144
177
|
|
|
145
178
|
See `references/policy.md` for the complete rule table, verdict codes, and
|
|
146
179
|
manifest format.
|
|
180
|
+
|
|
181
|
+
The candidate's restore audit records counts and transaction associations rather
|
|
182
|
+
than duplicate paths/error text. CLI results and recovery manifests still
|
|
183
|
+
contain the exact data needed to inspect and restore; a failed CLI result
|
|
184
|
+
must still be checked against the filesystem and preservation attempts.
|