@mokuyoaxis/agent-guard 0.2.5-rc3 → 0.2.5

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.
@@ -0,0 +1,40 @@
1
+ """User-facing storage notices; no policy or execution decisions."""
2
+ from __future__ import annotations
3
+
4
+ from pathlib import Path
5
+ import shlex
6
+ import sys
7
+
8
+
9
+ QUARANTINE_NOTICE = (
10
+ "Files moved to quarantine still use disk space. "
11
+ "Purging permanently removes their recovery copies."
12
+ )
13
+
14
+ HOST_STATUS_NOTICE = (
15
+ "This reports local recovery data, not whether a host loaded the guard. "
16
+ "Check the host's plugin or hook status separately."
17
+ )
18
+
19
+
20
+ def gc_guidance():
21
+ script = Path(__file__).resolve().parent.parent / "skills/delete-guard/scripts/gc.py"
22
+ command = [sys.executable, str(script)]
23
+ return {
24
+ "plan_command": shlex.join(command),
25
+ "purge_eligible_command": shlex.join(
26
+ command + ["--execute", "--all-eligible"]),
27
+ "purge_transaction_command": shlex.join(
28
+ command + ["--execute", "--txid", "<txid>"]),
29
+ "note": "POSIX-shell commands. Review the plan first. Run from the same working directory "
30
+ "with the same AGENT_GUARD_WORKSPACE / AGENT_GUARD_TRASH settings. "
31
+ "Replace <txid> to select one transaction.",
32
+ }
33
+
34
+
35
+ def print_gc_guidance(guidance):
36
+ print(f"GC plan : {guidance['plan_command']}")
37
+ print(f"GC purge : {guidance['purge_eligible_command']}")
38
+ print(" permanently removes eligible recovery copies")
39
+ print(f"GC one : {guidance['purge_transaction_command']}")
40
+ print(guidance["note"])
package/core/policy.py CHANGED
@@ -122,7 +122,8 @@ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
122
122
 
123
123
  # Human-facing one-liners: why the guard cannot just do it (or did do it).
124
124
  EXPLANATIONS: Dict[str, str] = {
125
- CODE_ALLOW_NOOP: "Nothing to delete; command may run unchanged.",
125
+ CODE_ALLOW_NOOP: "No recovery action is needed for the recognized operations. "
126
+ "Unrecognized command effects have not been checked.",
126
127
  CODE_ALLOW_REGENERABLE: "All targets are git-ignored and match known "
127
128
  "artifact patterns; deleted directly.",
128
129
  CODE_ALLOW_TRASH_GC: "Targets live inside the quarantine; housekeeping "
package/docs/README.md CHANGED
@@ -7,12 +7,15 @@ setup. The three main paths are [recovery protection](../skills/delete-guard/SKI
7
7
  [harness capability matrix](guides/harness-capabilities.md) for observed coverage
8
8
  and the [architecture](design/architecture.md) for the shared Core.
9
9
 
10
- Published RC baseline: [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md).
11
- Published stable baseline: [0.2.4](releases/release-notes-0.2.4.md).
12
- Source candidate: [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), with
13
- [blue-team research](research/README.md) and a [four-control example](lab/blue-team-calibration.md).
14
- Evaluate the source preview through a reviewed checkout or tarball;
15
- GitHub/npm package publication needs separate versioned receipts.
10
+ Stable release line: [0.2.5](releases/release-notes-0.2.5.md), combining
11
+ RC1–RC3 and clearer startup, command and storage feedback. The exact
12
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
13
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
14
+ establish publication and npm `latest` availability; 0.2.4 is the previous stable.
15
+ The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
16
+ opt-in [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
17
+ quarantine protection backport. The [getting-started guide](guides/getting-started.md)
18
+ explains exact-version and local-package installation.
16
19
 
17
20
  先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
18
21
  历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
@@ -29,9 +32,13 @@ GitHub/npm package publication needs separate versioned receipts.
29
32
 
30
33
  ## Guides
31
34
 
35
+ 当前源码中的[状态与清理反馈](guides/recovery-feedback.md)说明本地 Python/Hook/宿主验证的区别、
36
+ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
37
+
32
38
  | Document / 文档 | Scope / 范围 |
33
39
  |---|---|
34
40
  | [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
41
+ | [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
35
42
  | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
36
43
  | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
37
44
  | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
@@ -103,7 +110,9 @@ coverage rather than treating every historical result as current acceptance.
103
110
 
104
111
  | Document / 文档 | Scope / 范围 |
105
112
  |---|---|
106
- | [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 蓝队研究/文档源码候选与零模型示例;包发布另行核查 |
113
+ | [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
114
+ | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
115
+ | [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
107
116
  | [0.2.5-rc2](releases/release-notes-0.2.5-rc2.md) | 已发布的维护 RC;共享审计、observer 维护与兼容边界 |
108
117
  | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 已发布的维护预发布基线、文档整理与版本例外 |
109
118
  | [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
@@ -305,12 +305,14 @@ order of value:
305
305
 
306
306
  ## Delivery status and design directions
307
307
 
308
- The current source candidate is 0.2.5-rc3; stable 0.2.4 and published RC2 remain
309
- baselines. It retains the recovery, shared audit and observer maintenance,
310
- and adds [defensive research](../research/README.md) plus an example using the
311
- existing zero-model controls. Private research methods do not add a general
312
- authorization service or new production enforcement point.
313
- See [candidate notes](../releases/release-notes-0.2.5-rc3.md) and
308
+ The stable release line is 0.2.5. Previous stable 0.2.4, opt-in
309
+ 0.2.4-hotfix.1 and prerelease 0.2.5-rc3 retain their separate artifacts.
310
+ Version 0.2.5 retains RC recovery, shared audit,
311
+ observer maintenance and [defensive research](../research/README.md), plus
312
+ clearer local startup/status and retained-storage feedback. Private research
313
+ methods do not add a general authorization service or production enforcement
314
+ point. Deletion rules and execution routes retain their RC behavior.
315
+ See [candidate notes](../releases/release-notes-0.2.5.md) and
314
316
  [compatibility](compatibility.md) for behaviour and validation boundaries.
315
317
 
316
318
  The milestones below describe historical delivery and future design scope,
@@ -4,18 +4,51 @@ agent-guard's promise is recoverability. A promise is only as good as its
4
4
  stability over time - this page states exactly what may change and what
5
5
  may not, per release class.
6
6
 
7
- Current source candidate is [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md);
8
- the published RC baseline is [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md).
9
- Versioned sections retain the origin of changes introduced by earlier releases.
7
+ The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), carrying
8
+ the cumulative RC maintenance below. The opt-in prerelease remains
9
+ [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), 0.2.4 is the previous stable, and
10
+ [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
11
+ is an opt-in quarantine protection backport. Versioned sections retain the
12
+ origin and preparation labels of changes introduced by earlier releases.
10
13
 
11
14
  RC3 publishes defensive research and an example around the existing four
12
15
  zero-model controls. Experimental disclosure labels and private delegation
13
16
  methods are not additions to the Decision Protocol or native-hook contract.
14
17
  No production dependency, policy verdict or storage/configuration migration
15
- is introduced by this preparation.
18
+ is introduced by the research documentation.
16
19
 
17
20
  ## The adapter contract (frozen surface)
18
21
 
22
+ ### 0.2.5 feedback maintenance
23
+
24
+ Deletion rules, wildcard refusal, Decision/reason codes, CLI flags and exit
25
+ roles retain their contracts. `ALLOW_NOOP` receives a clearer explanation;
26
+ human check output displays explanations. Optional `storage_notice`/`gc`
27
+ metadata describes actual retained files and maintenance commands without
28
+ entering the shared audit payload. Status gains a local-versus-host notice.
29
+
30
+ The DSH adapter now checks local Python/checker imports before registration
31
+ and reports startup failure explicitly rather than returning silently when
32
+ shell/script dependencies are missing. This changes plugin lifecycle
33
+ diagnostics, not the Core policy or the host's ability to continue other
34
+ tools. Python must also be available on the plugin process PATH for this
35
+ startup probe. Its scope is the plugin process; live interception remains
36
+ `UNVERIFIED`. Status adds adapter facts and static runtime diagnostics.
37
+ Failed status queries return `ok: false`, `report: null` and `STATUS_*`
38
+ diagnostics for execution failure, timeout, unsuccessful exit or unusable
39
+ reports. Partial relocation failures preserve the existing failure/exit
40
+ semantics and expose their transaction IDs and retained-storage guidance.
41
+ No storage/configuration migration, new dependency or rm execution route is
42
+ introduced. Details are in the [feedback guide](../guides/recovery-feedback.md).
43
+
44
+ The maintainer selected 0.2.5 for the cumulative RC1–RC3 maintenance and this
45
+ feedback work. It carries forward the bounded RC1 maintenance exception
46
+ documented below. Quarantine control-path refusals inherited from RC1 and
47
+ explicit DSH initialization failure are upgrade-visible changes. This choice
48
+ does not permit unrelated verdict changes under the patch versioning rules.
49
+
50
+ ### Existing decision surface
51
+
19
52
  Harness adapters integrate against exactly four things:
20
53
 
21
54
  1. **Decision classes** - `ALLOW`, `SANITIZE`, `RELOCATE`, `SNAPSHOT`,
@@ -8,8 +8,8 @@ bypass. Therefore:
8
8
 
9
9
  - agent-guard is **reliability infrastructure**, not a security boundary.
10
10
  It defends against *mistakes*: misjudged context, mis-expanded commands,
11
- wrong working directory, hallucinated paths - which is what essentially
12
- all real-world "agent deleted my data" incidents are.
11
+ wrong working directory and hallucinated paths. It does not cover every
12
+ cause of data loss or every destructive operation.
13
13
  - You may claim: recovery for supported valuable deletions, explicit audit
14
14
  contracts for observed calls, graded authorization discipline, and reduced
15
15
  blast radius of common accidents. Regenerable artifacts may be deleted
@@ -10,29 +10,40 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- The published stable baseline is 0.2.4; the published RC baseline is
14
- [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md), including
15
- [shared audit metadata](audit-metadata.md) and observer startup maintenance.
16
- The [RC3 source candidate](../releases/release-notes-0.2.5-rc3.md) adds defensive
17
- research and a [zero-model calibration example](../lab/blue-team-calibration.md).
18
- Use a user-selected stable prefix for the published package:
13
+ The stable release line is [0.2.5](../releases/release-notes-0.2.5.md), and the
14
+ prerelease line remains [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
15
+ The optional [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1)
16
+ backports quarantine protection onto the stable line.
17
+ Version 0.2.5 combines RC1–RC3 and clearer status, command and storage feedback.
18
+ Its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
19
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5)
20
+ establish package availability. Use a user-selected stable prefix:
19
21
 
20
22
  ```sh
21
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
23
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.5
22
24
  ```
23
25
 
24
26
  The package root is
25
27
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
26
- For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly and check its
27
- [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
28
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
29
- for publication. A reviewed checkout or supplied local tarball can be evaluated
30
- independently of registry availability.
31
- Do not infer RC availability from the manifest or use an unscoped same-name
32
- package. A checkout's default branch can differ from a tagged stable release.
33
-
34
- Evaluate RC3 from a reviewed source checkout or supplied review tarball.
35
- Its manifest or a main-branch commit does not establish registry availability.
28
+ To select the prerelease, use `@mokuyoaxis/agent-guard@0.2.5-rc3` explicitly;
29
+ its [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
30
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3)
31
+ identify the published package. For the stable-line fix alone, select
32
+ `@mokuyoaxis/agent-guard@0.2.4-hotfix.1`. These opt-in channels do not move
33
+ stable `latest`.
34
+
35
+ For a reviewed local checkout or explicitly selected local tarball, use a
36
+ separate prefix:
37
+
38
+ ```sh
39
+ npm install --offline --ignore-scripts --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.5.tgz
40
+ ```
41
+
42
+ The review package root is
43
+ `/absolute/path/to/agent-guard-review/node_modules/@mokuyoaxis/agent-guard`.
44
+ Keep the selected package/checkout path consistent when configuring the host.
45
+ Do not infer publication from a manifest/main commit or use an unscoped
46
+ same-name package. A checkout's default branch can differ from a tagged stable release.
36
47
 
37
48
  Core needs Python 3.9+ and Git, with no third-party Python packages. POSIX
38
49
  examples/bridges require a POSIX shell. The optional pinned DSH read path uses
@@ -1,10 +1,11 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
- Source candidate: [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), with
4
- defensive research and an existing-control example. Published RC baseline:
5
- [0.2.5-rc2](../releases/release-notes-0.2.5-rc2.md).
3
+ Stable release line: [0.2.5](../releases/release-notes-0.2.5.md).
4
+ It retains RC1–RC3 and adds clearer startup, command and storage
5
+ feedback. Published prerelease, checked on 2026-10-19:
6
+ [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md).
6
7
  Rows below retain their tested source/host versions and do not automatically
7
- certify this candidate. Local regression or package checks are separate from
8
+ certify a later release. Local regression or package checks are separate from
8
9
  new native-host/model evidence.
9
10
 
10
11
  The new [research notes](../research/README.md) describe bounded private
@@ -0,0 +1,98 @@
1
+ # Reading guard status and cleanup results
2
+
3
+ These feedback changes are included in
4
+ [0.2.5](../releases/release-notes-0.2.5.md).
5
+ They do not change deletion policy, wildcard handling, retention thresholds,
6
+ or the recovery format.
7
+
8
+ ## What the status establishes
9
+
10
+ The DSH adapter runs `python3 check.py --help` before registering its tools
11
+ and Hook. This checks that Python and the checker imports run in the plugin
12
+ process environment; `python3` must be on that process's PATH as well as
13
+ available to the actual executor. It evaluates no command and writes no guard metadata.
14
+ It does not test the caller's shell, sandbox, or live host interception.
15
+
16
+ `agent_guard_status` adds an `adapter` object alongside the Core report:
17
+
18
+ | Field | Meaning |
19
+ |---|---|
20
+ | `startup_check` | The local checker startup check passed |
21
+ | `startup_scope` | `plugin_process`; the environment actually checked |
22
+ | `hook_registered` | This plugin registered its pre-execute listener |
23
+ | `last_checker_result` | `NOT_RUN`, `OK`, or the most recent checker infrastructure diagnostic; a policy refusal can still be an `OK` check |
24
+ | `host_interception` | `UNVERIFIED`; registration and local queries do not certify a live host path |
25
+
26
+ Missing shell service, missing checker, Python launch/import failure, a
27
+ 10-second startup timeout, or excessive startup output now fails plugin initialization explicitly.
28
+ The default path reports `GUARD_STARTUP_FAILED`; the optional read guard
29
+ retains `READ_GUARD_STARTUP_REFUSED`. Check the host's plugin status for
30
+ successful activation. If the plugin is absent or inactive, its own status
31
+ tool may not exist. A running host or a CLI status result is insufficient:
32
+ the host can continue running other tools after this plugin fails.
33
+
34
+ If the status script fails after registration, the model tool returns
35
+ `ok: false` and `report: null` with its adapter facts. It omits raw process
36
+ exceptions and unusable process output. These diagnostics describe the status
37
+ query; they do not overwrite the last command-checker result.
38
+
39
+ | Diagnostic | Meaning |
40
+ |---|---|
41
+ | `STATUS_EXECUTION_FAILED` | The caller's shell could not start or finish the status process |
42
+ | `STATUS_TIMEOUT` | The status process timed out, even if it produced output |
43
+ | `STATUS_PROCESS_FAILED` | The status process exited unsuccessfully |
44
+ | `STATUS_INVALID_OUTPUT` | A zero exit status did not provide a usable recovery report |
45
+
46
+ Once a command reaches the checker, process failure, timeout and unusable
47
+ output remain denials. Static `CHECKER_*` diagnostics distinguish these
48
+ failures from a Core policy refusal without copying private command text or
49
+ raw process errors into adapter logs.
50
+
51
+ ## What ALLOW_NOOP means
52
+
53
+ `ALLOW_NOOP` keeps its original decision and reason code. Its explanation is:
54
+
55
+ > No recovery action is needed for the recognized operations. Unrecognized command effects have not been checked.
56
+
57
+ For an unrecognized script or interpreter command, this is not a claim that
58
+ the operation is harmless. Scripts, overwrites and other uncovered paths
59
+ retain their existing limits. See the [threat model](../design/threat-model.md).
60
+
61
+ ## Moving a file does not remove its recovery copy
62
+
63
+ A successful relocation now reports `storage_notice` and `gc` guidance in
64
+ CLI JSON and displays the same information in terminal output. Enforced
65
+ checks and `safe_delete` also report retained data after a partial relocation,
66
+ including a storage failure after some files moved. The failed decision stays
67
+ unchanged; both JSON and terminal output include the recovery transaction ID.
68
+ A storage failure before any move does not claim retained data. Direct artifact
69
+ deletion, a no-match result and a deletion dry-run do not claim a relocation.
70
+ The DSH model-facing preview puts adapter/storage feedback before long
71
+ target or audit arrays within the existing preview limit.
72
+
73
+ Quarantined data still uses storage. Cross-filesystem moves and actual free
74
+ blocks depend on the filesystem; no exact freed-space measurement is claimed.
75
+ Status uses the existing size accounting and eligibility plan. Regenerable
76
+ artifacts still require the existing ignored-path and artifact-pattern rules.
77
+
78
+ Run maintenance from the same working directory with the same
79
+ `AGENT_GUARD_WORKSPACE` and `AGENT_GUARD_TRASH` settings as the operation.
80
+ Replace the package path below with your installation; CLI results supply
81
+ POSIX-shell-quoted commands for that package and Python interpreter. Use a
82
+ POSIX shell for these command strings; their quoting is not PowerShell or CMD syntax.
83
+
84
+ ```sh
85
+ # Inspect the plan; this removes nothing.
86
+ python3 /absolute/agent-guard/skills/delete-guard/scripts/gc.py
87
+
88
+ # Permanently remove the recovery copies selected by the plan.
89
+ python3 /absolute/agent-guard/skills/delete-guard/scripts/gc.py --execute --all-eligible
90
+
91
+ # Or explicitly select one transaction, including one not yet eligible.
92
+ python3 /absolute/agent-guard/skills/delete-guard/scripts/gc.py --execute --txid '<txid>'
93
+ ```
94
+
95
+ Review the plan and selected transactions before choosing a purge. A manual
96
+ `--txid` selection is not limited to age/capacity eligibility. The 30-day and
97
+ 5-GiB thresholds do not run GC automatically. `--execute` alone selects
98
+ nothing; GC does not prune Git stash snapshots.
@@ -9,9 +9,29 @@ F21–F23 changes subsequently shipped in 0.2.3; F24–F25 shipped in 0.2.4.
9
9
  F26–F31 subsequently shipped in 0.2.5-rc1. RC2 adds shared audit metadata and
10
10
  observer startup maintenance; publication is checked by its versioned receipts.
11
11
  Current scope is in the
12
- [candidate notes](../releases/release-notes-0.2.5-rc3.md); historical failures and
12
+ [candidate notes](../releases/release-notes-0.2.5.md); historical failures and
13
13
  test counts below are not rewritten by a later success.
14
14
 
15
+ ## Current feedback maintenance · status, explanations and retained storage
16
+
17
+ 2026-10-19: this feedback work is included in 0.2.5.
18
+ The recording below describes the implementation work on 2026-10-18.
19
+
20
+ 2026-10-18, unreleased 0.2.5 work: script existence was only a file check,
21
+ default DSH startup could return without registering protection, and generic
22
+ runtime errors did not explain what failed. A local Python/import probe and
23
+ explicit initialization failures now separate local readiness from listener
24
+ registration and unverified live-host interception. Runtime failures retain
25
+ deny behavior and report static diagnostics.
26
+
27
+ `ALLOW_NOOP` previously said “Nothing to delete” for commands whose effects
28
+ were not recognized. Its explanation now describes that limitation, without
29
+ changing the reason code or verdict. Relocation results/status/GC plans explain
30
+ retained storage and explicit plan/selection commands. They do not add
31
+ automatic purge or alter rm/glob policy. See the
32
+ [feedback guide](../guides/recovery-feedback.md) for current semantics;
33
+ historical test evidence below retains its original scope.
34
+
15
35
  ## F1 · Compound `cd X && rm y` resolves targets against the wrong base
16
36
 
17
37
  The interceptor classifies against the tool call's declared workdir. A
@@ -1,6 +1,6 @@
1
1
  # 蓝队零模型校准 / Blue-team calibration
2
2
 
3
- RC3 提供一个便携示例,将现有四种 Lab 控制依次运行并保存简短摘要。
3
+ RC3 引入的便携示例保留在 0.2.5 中,将现有四种 Lab 控制依次运行并保存简短摘要。
4
4
  它复用已交付的 Core,不需要 DSH、Kimi、模型账户、私有 home 或新的 Python 依赖。
5
5
  需要 Python 3.9+,并允许本机 IPv4 回环监听;完整 Core 安装仍按[入门指南](../guides/getting-started.md)检查。
6
6
 
@@ -5,16 +5,20 @@ 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
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-rc2`;
8
+ It remains available in stable `0.2.4` and published `0.2.5-rc3`;
9
9
  RC2 introduced startup diagnosis and cancellation maintenance
10
10
  without adding new model-trial evidence. See the [RC2 notes](../releases/release-notes-0.2.5-rc2.md).
11
11
 
12
- The [RC3 source candidate](../releases/release-notes-0.2.5-rc3.md) includes
12
+ The [RC3 prerelease](../releases/release-notes-0.2.5-rc3.md) includes
13
13
  [blue-team research](../research/README.md), sanitized historical observations
14
14
  and a [portable four-control example](blue-team-calibration.md).
15
15
  Its private research methods do not expand this controller's supported
16
16
  channels, evidence levels or native-host coverage.
17
17
 
18
+ Version [0.2.5](../releases/release-notes-0.2.5.md) retains
19
+ these controls and limits. Its status and storage explanations do not add
20
+ new model trials or production interception channels.
21
+
18
22
  It is not a Skill for the tested agent, a security boundary, or a certificate
19
23
  that a model or vendor is safe or malicious.
20
24
 
@@ -1,5 +1,13 @@
1
1
  # Agent Guard 0.2.5-rc3
2
2
 
3
+ Publication status checked 2026-10-19: RC3 was published on 2026-10-14 as a
4
+ [GitHub prerelease](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc3)
5
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc3).
6
+ The next stable release line is [0.2.5](release-notes-0.2.5.md).
7
+ The following preparation snapshot retains its original results and limits.
8
+
9
+ ## Preparation snapshot · 2026-10-13
10
+
3
11
  Source candidate prepared 2026-10-13. Published baselines remain stable
4
12
  [0.2.4](release-notes-0.2.4.md) and prerelease
5
13
  [0.2.5-rc2](release-notes-0.2.5-rc2.md). The maintainer authorized the normal
@@ -0,0 +1,123 @@
1
+ # Agent Guard 0.2.5
2
+
3
+ Stable maintenance release, prepared 2026-10-19. Version 0.2.5 combines
4
+ the maintenance and research delivered in RC1–RC3 with clearer feedback about
5
+ runtime readiness, command coverage and recovery storage.
6
+
7
+ The exact tag routes to a GitHub release and npm `latest`. Availability is
8
+ established by the [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5)
9
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5).
10
+ RC3 and 0.2.4-hotfix.1 retain their independent opt-in channels and artifacts.
11
+
12
+ 0.2.5 正式版汇合 RC1—RC3 与明确反馈维护;GitHub/npm 的实际发布结果以精确版本回执为准。
13
+ 本版不自动升级用户已有安装,不改变 rm 通配符规则或执行路径。
14
+
15
+ ## What users will see
16
+
17
+ - **Startup checks run Python.** Before registering its tools and listener,
18
+ the DSH adapter runs `python3 check.py --help` in the plugin process.
19
+ Missing dependencies, an import/process failure or a 10-second startup
20
+ timeout now produces an explicit initialization failure. The host can
21
+ continue running other tools, so inspect the plugin's activation status.
22
+ - **Local readiness and host interception are separate.** DSH status shows
23
+ the startup check, listener registration and most recent checker result.
24
+ Live interception remains `UNVERIFIED`; local CLI status reports recovery
25
+ data only. A plugin that never loaded may provide no status tool.
26
+ - **Unrecognized effects are identified.** `ALLOW_NOOP` now explains:
27
+ “No recovery action is needed for the recognized operations. Unrecognized
28
+ command effects have not been checked.” Its verdict and reason code stay
29
+ the same. Script/interpreter effects are not certified as harmless.
30
+ - **Relocation explains retained storage.** Successful moves and partial
31
+ failures with moved files report that the data still uses disk space,
32
+ retain the recovery transaction ID, and provide GC commands. A dry-run,
33
+ no-match or direct artifact deletion does not claim a relocation.
34
+ - **GC guidance selects an actual action.** Results provide a plan command,
35
+ `--execute --all-eligible`, and explicit `--execute --txid '<txid>'` guidance.
36
+ Keep the same working directory and workspace/trash settings. The 30-day
37
+ and 5-GiB thresholds do not run cleanup automatically; `--execute` alone
38
+ selects nothing. Purge removes recovery copies permanently and does not
39
+ prune Git stash snapshots.
40
+ - **Failures explain the affected step.** Static `CHECKER_*` and `STATUS_*`
41
+ diagnostics distinguish execution, timeout, process and output failures
42
+ from policy refusals. Checker infrastructure failures still deny the call.
43
+ A failed status query returns `ok: false` and `report: null`, retaining
44
+ adapter facts without replacing the last command-checker result or copying
45
+ raw process errors into diagnostics.
46
+
47
+ 这些反馈不扩大自动拦截范围。Python 在插件进程中可运行,不代表调用者的 shell/sandbox
48
+ 已经验证;Hook 已注册也不代表实际调用经过它。迁入回收站是保留恢复副本,数据仍占空间。
49
+ 具体字段、故障标签及 GC 示例见[状态与清理反馈](../guides/recovery-feedback.md)。
50
+
51
+ ## Included from the prereleases
52
+
53
+ - [RC1](release-notes-0.2.5-rc1.md): quarantine control-path protection,
54
+ PURGED-history exclusion from active GC planning, minimized restore and
55
+ safe_delete audit writers, exemption diagnostics and assessment clarification.
56
+ - [RC2](release-notes-0.2.5-rc2.md): shared audit metadata projection, opaque
57
+ session correlation, bounded legacy status/GC metadata, observer startup
58
+ diagnostics and cancellation accounting.
59
+ - [RC3](release-notes-0.2.5-rc3.md): defensive research, sanitized bounded
60
+ observations and the portable four-control calibration example. Private
61
+ experimental methods do not become production authorization features.
62
+
63
+ ## Upgrade impact
64
+
65
+ | Starting point | What to review |
66
+ |---|---|
67
+ | 0.2.4 | Quarantine control paths can now be refused before housekeeping. Review RC audit field changes and explicit DSH initialization failures. |
68
+ | 0.2.4-hotfix.1 | Control-path protection is already backported. The remaining RC maintenance, research and feedback are additional. |
69
+ | 0.2.5-rc1 / rc2 | Later RC content and the feedback changes above are cumulative. |
70
+ | 0.2.5-rc3 | Review the new startup/status diagnostics, `ALLOW_NOOP` explanation and retained-storage/GC guidance. |
71
+
72
+ Consumers must tolerate optional result fields. Audit records are supported
73
+ metadata, not arbitrary payload storage: raw/custom audit fields may be
74
+ omitted or projected, including in-memory views of old records. Earlier log
75
+ bytes are not rewritten. Recovery IDs and manifest/CLI paths remain exact;
76
+ an audit correlation digest is not a restore argument. See the
77
+ [audit contract](../guides/audit-metadata.md).
78
+
79
+ The default DSH lifecycle changes from log-only inactivity to explicit
80
+ initialization failure. Python must be on the plugin process PATH and
81
+ available to the actual executor. Existing admitted host versions remain
82
+ `0.1.5-rc.1` and `0.2.0-rc.2`; optional read redaction stays off by default
83
+ and keeps its existing artifact pins and coverage limits.
84
+
85
+ The maintainer selected 0.2.5 for this cumulative maintenance, carrying
86
+ forward RC1's documented versioning exception. Decision/reason strings,
87
+ public CLI parameters and exit-code roles, recovery strategies and formats
88
+ retain their contracts. No production dependency or configuration/storage
89
+ migration is introduced. See the [compatibility contract](../design/compatibility.md).
90
+
91
+ 本轮没有改动 rm 通配符、变量、管道、find 或工作区边界规则,也没有新增替代执行路径。
92
+ `safe_delete` 仍按原规则显式展开自己的参数;这不放宽 `rm` 的通配符判定。
93
+
94
+ ## Validation and limits
95
+
96
+ Before the version-only promotion, the feedback-maintenance checkout passed
97
+ one complete `npm test` on 2026-10-19: 933 Python tests and both Node adapter
98
+ groups, with original assertions and timeouts. Eleven actual CLI scenarios,
99
+ feedback/audit checks, bounded zero-model DSH runtime checks for both admitted
100
+ versions, and source/tarball/offline-install equality also passed. This is
101
+ local maintenance evidence, separate from versioned remote release gates.
102
+
103
+ The versioned 0.2.5 checkpoint separately passed one complete `npm test`:
104
+ 933 Python tests (835.794 seconds, no skips) and both Node groups, with
105
+ 192 public files unchanged throughout the run. The 137-file local package
106
+ matched source and offline installation; ten CLI entries, adapter import,
107
+ synthetic recovery, explicit GC guidance and unchanged wildcard refusal passed.
108
+ After that run, only release-status documentation and this evidence paragraph
109
+ changed. Runtime and test bytes retain the verified checkpoint; final
110
+ source/package/installation equality is checked again for publication.
111
+
112
+ Earlier intermittent subprocess timeouts remain recorded as failures. Their
113
+ historical cause is unresolved; later successful checks do not establish a
114
+ root-cause fix. The [capability matrix](../guides/harness-capabilities.md)
115
+ retains each host report's tested versions and scope. This preparation adds
116
+ no real-model trial, UI/sandbox certification or general subagent guarantee.
117
+ Full Windows-native harness E2E, universal egress protection and isolation
118
+ against same-UID processes remain outside the guarantee.
119
+
120
+ Install the exact version or use a reviewed checkout/tarball following
121
+ [getting started](../guides/getting-started.md). Publication requires the
122
+ final commit's CI, npm credential preflight and matching GitHub/npm artifacts.
123
+ Local checks do not establish those remote receipts or registry availability.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.5-rc3",
3
+ "version": "0.2.5",
4
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",