@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.
- package/README.md +33 -23
- package/README.zh-CN.md +29 -18
- package/SECURITY.md +5 -3
- package/adapters/dsh/README.md +39 -6
- package/adapters/dsh/lib/index.js +127 -33
- package/core/messages.py +40 -0
- package/core/policy.py +2 -1
- package/docs/README.md +16 -7
- package/docs/design/architecture.md +8 -6
- package/docs/design/compatibility.md +37 -4
- package/docs/design/threat-model.md +2 -2
- package/docs/guides/getting-started.md +28 -17
- package/docs/guides/harness-capabilities.md +5 -4
- package/docs/guides/recovery-feedback.md +98 -0
- package/docs/history/friction.md +21 -1
- package/docs/lab/blue-team-calibration.md +1 -1
- package/docs/lab/guard-lab.md +6 -2
- package/docs/releases/release-notes-0.2.5-rc3.md +8 -0
- package/docs/releases/release-notes-0.2.5.md +123 -0
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +30 -13
- package/skills/delete-guard/references/policy.md +16 -3
- package/skills/delete-guard/scripts/check.py +13 -0
- package/skills/delete-guard/scripts/gc.py +4 -2
- package/skills/delete-guard/scripts/safe_delete.py +20 -14
- package/skills/delete-guard/scripts/status.py +9 -0
package/core/messages.py
ADDED
|
@@ -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: "
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
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
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
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
|
-
|
|
8
|
-
the
|
|
9
|
-
|
|
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
|
|
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
|
|
12
|
-
|
|
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
|
|
14
|
-
[0.2.5-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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.
|
|
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
|
-
|
|
27
|
-
[GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-
|
|
28
|
-
and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
|
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.
|
package/docs/history/friction.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
package/docs/lab/guard-lab.md
CHANGED
|
@@ -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-
|
|
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
|
|
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
|
|
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",
|