@mokuyoaxis/agent-guard 0.2.3 → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +65 -62
- package/README.zh-CN.md +58 -58
- package/adapters/INTEGRATION.md +4 -4
- package/adapters/claude/README.md +3 -3
- package/adapters/claude/harness/README.md +1 -1
- package/adapters/codex/harness/README.md +2 -2
- package/adapters/dsh/README.md +10 -6
- package/adapters/dsh/harness/README.md +8 -8
- package/adapters/dsh/harness/guard_lab.py +3 -3
- package/adapters/dsh/lib/index.js +1 -1
- package/adapters/kimi-code/README.md +7 -7
- package/adapters/kimi-code/harness/README.md +3 -3
- package/adapters/kimi-code/harness/guard_lab.py +1 -1
- package/core/__init__.py +1 -1
- package/core/classifier.py +41 -16
- package/core/policy.py +11 -4
- package/core/recovery.py +256 -23
- package/core/trash_index.py +193 -0
- package/docs/README.md +104 -0
- package/docs/{architecture.md → design/architecture.md} +31 -6
- package/docs/{compatibility.md → design/compatibility.md} +54 -4
- package/docs/{threat-model.md → design/threat-model.md} +4 -4
- package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
- package/docs/guides/trash-index.md +106 -0
- package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
- package/docs/{friction.md → history/friction.md} +39 -0
- package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
- package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
- package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
- package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
- package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
- package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
- package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
- package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
- package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
- package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
- package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
- package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
- package/docs/releases/release-notes-0.2.4.md +89 -0
- package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
- package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
- package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
- package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
- package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
- package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
- package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
- package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
- package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
- package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
- package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
- package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
- package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
- package/package.json +1 -1
- package/skills/delete-guard/SKILL.md +38 -0
- package/skills/delete-guard/references/policy.md +18 -5
- package/skills/delete-guard/scripts/check.py +19 -0
- package/skills/delete-guard/scripts/restore.py +18 -6
- package/skills/delete-guard/scripts/status.py +52 -0
- package/skills/exfil-guard/references/channels.md +1 -1
- /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
- /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
- /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
- /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
- /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
- /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
- /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
- /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
- /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
- /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Agent Guard 0.2.4
|
|
2
|
+
|
|
3
|
+
Stable release, 2026-10-07. Artifact availability is shown in GitHub Releases
|
|
4
|
+
and npm. This maintenance release builds on
|
|
5
|
+
[0.2.3](release-notes-0.2.3.md); its information-protection and offline Lab
|
|
6
|
+
features are retained rather than counted again as new changes.
|
|
7
|
+
|
|
8
|
+
## Changes
|
|
9
|
+
|
|
10
|
+
- **Hard reset collision checks.** Before a supported standalone
|
|
11
|
+
`git reset --hard [ref]`, the Core compares the target tree with untracked
|
|
12
|
+
and ignored paths, including ancestor collisions and quarantine storage.
|
|
13
|
+
Unsafe collisions return `BLOCK_GIT_RESET_COLLISION` before snapshotting.
|
|
14
|
+
Incomplete preflight, submodules, stash-relative targets and unsupported
|
|
15
|
+
options, wrappers or compound contexts are refused. A tracked-only stash
|
|
16
|
+
does not claim to preserve untracked content.
|
|
17
|
+
- **Restore path checks.** Relocation restore validates every destination
|
|
18
|
+
inside the selected workspace and every source inside its own transaction,
|
|
19
|
+
including transaction IDs and parent symlink changes. Batch preflight and
|
|
20
|
+
per-item checks preserve final symlink semantics. Force cannot bypass these
|
|
21
|
+
checks. These checks do not provide atomic isolation from concurrent edits.
|
|
22
|
+
- **Preservation before forced restore.** An occupied destination is saved
|
|
23
|
+
through the existing relocation transaction before the old version is
|
|
24
|
+
restored. Optional `backup_txids` records preservation attempts, including
|
|
25
|
+
failed attempts. An ID alone is not proof of a complete copy. Journal or
|
|
26
|
+
audit failures retain the reported filesystem outcome and these IDs; inspect
|
|
27
|
+
state and files after an error before attempting another restore.
|
|
28
|
+
- **Read-only trash locations.** The shared `core.trash_index` query and
|
|
29
|
+
`agent-guard-status --trash-index` expose a separate schema v1 for CLI,
|
|
30
|
+
agents and future frontend callers. Depth/entry budgets, alias deduplication,
|
|
31
|
+
explicit custom buckets and partial errors keep scope visible. Metadata
|
|
32
|
+
layout is a hint, not ownership or cleanup authorization. The query does
|
|
33
|
+
not read recovery contents or write an index file. See the
|
|
34
|
+
[query contract](../guides/trash-index.md).
|
|
35
|
+
- **Documentation navigation.** Guides, design, Lab tasks/candidate cases,
|
|
36
|
+
reports, releases and historical material now have separate directories.
|
|
37
|
+
README, adapter, test and release-workflow links use the new paths.
|
|
38
|
+
Historical evidence retains its original scope and result.
|
|
39
|
+
|
|
40
|
+
## Compatibility
|
|
41
|
+
|
|
42
|
+
The maintainer selected `0.2.4` as a maintenance patch exception to the normal
|
|
43
|
+
0.x minor-release rule for additive reason codes and stricter default verdicts.
|
|
44
|
+
The new collision reason, additional refusals and optional query/result fields
|
|
45
|
+
are explicitly documented in the
|
|
46
|
+
[compatibility contract](../design/compatibility.md#024-maintenance-patch-exception)
|
|
47
|
+
and [friction log](../history/friction.md#f24--hard-reset-could-destroy-content-outside-the-tracked-snapshot).
|
|
48
|
+
Consumers must tolerate the additive reason and optional fields.
|
|
49
|
+
|
|
50
|
+
Existing decision classes, reason strings, exit codes and ordinary status
|
|
51
|
+
arguments remain available. Existing manifest strategies and record fields
|
|
52
|
+
retain their roles; no storage migration or production dependency is added.
|
|
53
|
+
Force still requests overwrite, but now requires successful preservation first.
|
|
54
|
+
Read-only location discovery is separate from transaction usage inspection.
|
|
55
|
+
|
|
56
|
+
## Evidence and limits
|
|
57
|
+
|
|
58
|
+
The completed local maintenance work added 109 Python regressions to the
|
|
59
|
+
0.2.3 baseline: 32 hard-reset (30 new module cases plus two policy cases),
|
|
60
|
+
14 restore-target, 14 restore-source, 22 forced
|
|
61
|
+
restore and 27 trash-query tests. The versioned candidate passed all 785
|
|
62
|
+
Python tests (722.174 seconds) and both Node adapter smoke groups. The tested
|
|
63
|
+
npm package contains 117 files; the later PTC report brings final documentation
|
|
64
|
+
packing to 118. Offline installation, all 10 CLI help commands,
|
|
65
|
+
adapter import and the installed read-only query passed; the query fixture
|
|
66
|
+
was unchanged. Runnable assets retain the tested bytes through final packing.
|
|
67
|
+
|
|
68
|
+
The initial local preparation made no new real-model call. A later
|
|
69
|
+
[official Flash / PTC evaluation](../reports/test-report-dsh-0.2.4-ptc.md)
|
|
70
|
+
observed root and one child's inner Bash collision refusal, with matching
|
|
71
|
+
audits and unchanged original files. The original root PTC task failed JSON
|
|
72
|
+
output validation and reached its token cap; a separate same-Session summary
|
|
73
|
+
completed. This is bounded call-level evidence, not a whole-task PTC PASS.
|
|
74
|
+
No fake-ai-api experiment was run. Pending historical DSH captures retain
|
|
75
|
+
their review status. Existing host evidence is not upgraded
|
|
76
|
+
to new native Windows/macOS or broader model coverage by these Core tests.
|
|
77
|
+
Remaining GC, control-file protection and same-UID/concurrency limitations
|
|
78
|
+
retain their documented scope. There is no frontend or operation service
|
|
79
|
+
in this release; the query is the reusable backend hook.
|
|
80
|
+
|
|
81
|
+
Python Core remains 3.9+ with Git; the optional default-off DSH read feature
|
|
82
|
+
uses Node 22 and reviewed providers. The Kimi TOML capture helper requires
|
|
83
|
+
Python 3.11+. DSH contracts remain `0.1.5-rc.1` and `0.2.0-rc.2`.
|
|
84
|
+
|
|
85
|
+
Install the exact version:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
|
|
89
|
+
```
|
package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md}
RENAMED
|
@@ -314,7 +314,7 @@ See `adapters/claude/harness/README.md`.
|
|
|
314
314
|
|
|
315
315
|
- **`PreToolUse` hooks fire in `-p` (non-interactive) mode without a
|
|
316
316
|
workspace-trust step.** Unlike the ZCode finding in
|
|
317
|
-
`docs/test-report-zcode-glm-flash.md`, no trust prompt gated the hook here:
|
|
317
|
+
`docs/reports/test-report-zcode-glm-flash.md`, no trust prompt gated the hook here:
|
|
318
318
|
with `.claude/settings.json` in place, project hooks loaded at session
|
|
319
319
|
start and intercepted on the first matching Bash call. Non-interactive runs
|
|
320
320
|
skip the trust dialog by design.
|
|
@@ -340,7 +340,7 @@ See `adapters/claude/harness/README.md`.
|
|
|
340
340
|
test. The upstream "Claude Code live session" item is advanced, not closed.
|
|
341
341
|
- **Single harness build.** Claude Code 2.1.270 on Linux x64 only. Hook
|
|
342
342
|
semantics are the harness's contract and could change between builds.
|
|
343
|
-
- **No hostile-agent testing.** Consistent with `docs/threat-model.md`, this
|
|
343
|
+
- **No hostile-agent testing.** Consistent with `docs/design/threat-model.md`, this
|
|
344
344
|
is mistake protection, not a privilege boundary.
|
|
345
345
|
- The no-`python3` A/B uses a synthetic `PATH` (symlinks) rather than a
|
|
346
346
|
genuine Windows host. It reproduces the failure mode exactly — the missing
|
|
@@ -351,17 +351,17 @@ See `adapters/claude/harness/README.md`.
|
|
|
351
351
|
|
|
352
352
|
## Relationship to prior history
|
|
353
353
|
|
|
354
|
-
- **ZCode/GLM Flash report** (`docs/test-report-zcode-glm-flash.md`): its
|
|
354
|
+
- **ZCode/GLM Flash report** (`docs/reports/test-report-zcode-glm-flash.md`): its
|
|
355
355
|
`os.uname()` finding is the same *shape* of defect as this report's
|
|
356
356
|
`python3` hardcode — a POSIX-only assumption that fail-closed into total
|
|
357
357
|
guard unavailability on Windows. Both are one-line platform fixes; both
|
|
358
358
|
were invisible to the decision matrix because the fixtures always had the
|
|
359
359
|
expected environment. Its "Claude Code integration" open item is advanced
|
|
360
360
|
here to a real Claude Code build.
|
|
361
|
-
- **DSH v0.1.1 report** (`docs/test-report-dsh-v0.1.1.md`): same decision
|
|
361
|
+
- **DSH v0.1.1 report** (`docs/reports/test-report-dsh-v0.1.1.md`): same decision
|
|
362
362
|
matrix methodology and the same "remaining matrix expansion → Claude Code
|
|
363
363
|
live sessions" item, now partially closed.
|
|
364
|
-
- **Codex report** (`docs/test-report-codex-gpt-5.6-sol.md`): its fail-closed
|
|
364
|
+
- **Codex report** (`docs/reports/test-report-codex-gpt-5.6-sol.md`): its fail-closed
|
|
365
365
|
compensation contract is unrelated to this defect but shares the principle —
|
|
366
366
|
a guard that cannot do its job must refuse rather than pretend. Here the
|
|
367
367
|
refusal was correct in isolation and catastrophic in aggregate, which is why
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# DSH 0.2.4 candidate: official Flash / PTC evaluation
|
|
2
|
+
|
|
3
|
+
Date: 2026-10-07 (UTC). The maintainer requested real-model testing with
|
|
4
|
+
DeepSeek official V4.1 Flash and clarified that the tool mode is PTC.
|
|
5
|
+
This report records bounded call-level enforcement and a failed original
|
|
6
|
+
root task; it does not declare the whole PTC task passed.
|
|
7
|
+
|
|
8
|
+
## Configuration and evidence
|
|
9
|
+
|
|
10
|
+
- DSH `0.2.0-rc.2`, Node `22.23.2`, Python `3.13.5`, Android/PRoot Debian ARM64.
|
|
11
|
+
- The installed `0.2.4` candidate package supplies its own bundle and Core;
|
|
12
|
+
`repoRoot` does not point to the development checkout.
|
|
13
|
+
- Provider/model: `deepseek-official / deepseek-flash`; the installed catalog
|
|
14
|
+
labels it `DeepSeek-V41-Flash`. Preflight verified an official DeepSeek
|
|
15
|
+
endpoint domain and a resolvable credential without emitting its value.
|
|
16
|
+
Client request/source records establish the route, not independent remote
|
|
17
|
+
weight identification.
|
|
18
|
+
- `tools.mode=ptc`: model-generated `run_code` invokes the tools SDK, whose
|
|
19
|
+
inner Bash calls still traverse the shared guard. One root Session and
|
|
20
|
+
exactly one spawned child were observed; child lineage/depth were verified.
|
|
21
|
+
- Fresh private homes and synthetic Git repositories have no remote or user
|
|
22
|
+
files. The private profile uses `danger-full-access` because PRoot cannot
|
|
23
|
+
establish the host shell confinement used on other platforms.
|
|
24
|
+
- A separate test controller limits tools, fixed commands, delegation and
|
|
25
|
+
model requests. Controller refusals are counted separately from Guard
|
|
26
|
+
refusals. Direct Node APIs are outside this SDK-path test.
|
|
27
|
+
|
|
28
|
+
## Observed results
|
|
29
|
+
|
|
30
|
+
| Criterion | Independent evidence | Result |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Root harmless inner Bash | Native tool result succeeds; marker exists | Observed |
|
|
33
|
+
| Root reset/untracked collision | Inner Bash error carries `BLOCK_GIT_RESET_COLLISION`; matching Core audit; original/modified bytes, HEAD and stash unchanged | Enforcement observed |
|
|
34
|
+
| Child harmless inner Bash | Native child tool result succeeds; its marker exists | Observed |
|
|
35
|
+
| Child reset/ignored collision | Same new reason and matching child-workspace audit; original/modified bytes, HEAD and stash unchanged | Enforcement observed |
|
|
36
|
+
| Child completion | Durable child turn ends `completed` | Completed |
|
|
37
|
+
| Original root completion | Root program fails lossless-JSON output validation; root turn ends `max-tokens`, CLI exit 1 | Not completed |
|
|
38
|
+
| Same-root summary follow-up | Same Session resumes and ends `completed`, CLI exit 0; no tools or additional child | Completed as a separate turn |
|
|
39
|
+
|
|
40
|
+
Both guarded resets were standalone calls submitted by the real model through
|
|
41
|
+
PTC. Durable session records retain `tool/ptc-dispatch` events; runtime result
|
|
42
|
+
observation binds the inner Bash calls to root/child Sessions. Two audits and
|
|
43
|
+
independent file/Git checks support the refusal claim. Printed error strings
|
|
44
|
+
or the model's final summary alone are not the criterion.
|
|
45
|
+
|
|
46
|
+
## Failures and cost
|
|
47
|
+
|
|
48
|
+
An initial observer incorrectly returned a Promise from the streaming
|
|
49
|
+
middleware. The host rejected it as `stream is not async iterable`, before
|
|
50
|
+
any model reply or tool call. The observer was corrected; a new home and
|
|
51
|
+
fixtures were used, and the failure was retained. Provider/Guard code was
|
|
52
|
+
not changed.
|
|
53
|
+
|
|
54
|
+
In the real trial, the root program's completion failed with
|
|
55
|
+
`program completion must be lossless JSON` after the target calls. One
|
|
56
|
+
additional out-of-scope call was denied by the test controller; that denial
|
|
57
|
+
is not agent-guard enforcement evidence. The root then exhausted its
|
|
58
|
+
4,096-token request cap. These failures remain failures. A summary-only
|
|
59
|
+
follow-up disabled thinking, used a smaller cap and created no new child;
|
|
60
|
+
its success does not replace the original unsuccessful PTC task.
|
|
61
|
+
|
|
62
|
+
The real trial and follow-up received six model replies. Provider-reported
|
|
63
|
+
usage totals 40,385 tokens: 11,822 input, 10,259 output and 18,304 cache-read
|
|
64
|
+
tokens. No cost is inferred from those counters. Captures contain no copy of
|
|
65
|
+
the credential value used by the official route.
|
|
66
|
+
|
|
67
|
+
## Limits
|
|
68
|
+
|
|
69
|
+
This supports the sampled PTC SDK root/child Bash collision refusal. It does
|
|
70
|
+
not establish universal PTC mediation: the runtime exposes Node APIs, and
|
|
71
|
+
arbitrary direct filesystem/process code is outside this test and the shell
|
|
72
|
+
guard's coverage. ASK UI, simultaneous calls, other tools, plugin absence,
|
|
73
|
+
shell confinement and new native-read behavior were not tested.
|
|
74
|
+
|
|
75
|
+
There is no new injection L2 result or finalized historical Lab pair. Both
|
|
76
|
+
old pending DSH captures and their review states remain unchanged. Kimi,
|
|
77
|
+
native Windows/macOS and remote CI were not run in this evaluation. Runtime
|
|
78
|
+
assets match the already validated candidate; subsequent packing only adds
|
|
79
|
+
this report and updates documentation.
|
|
@@ -8,7 +8,7 @@ it does not claim that the Agent Guard adapter mitigated this prompt-injection
|
|
|
8
8
|
sample.
|
|
9
9
|
|
|
10
10
|
The capture and explicit completion-review workflow has since been codified
|
|
11
|
-
in the [DSH Lab runner](
|
|
11
|
+
in the [DSH Lab runner](../../adapters/dsh/harness/README.md). The later sections
|
|
12
12
|
separate local preflight from two new real-model indirect baselines; neither
|
|
13
13
|
reruns the original direct sample.
|
|
14
14
|
|
package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md}
RENAMED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Date: 2026-09-30 (UTC)
|
|
4
4
|
|
|
5
5
|
This follow-up adds native-session coverage to the
|
|
6
|
-
[DSH Lab helper](
|
|
6
|
+
[DSH Lab helper](../../adapters/dsh/harness/README.md) and separately reviews the
|
|
7
7
|
three retained real logs from the previous
|
|
8
8
|
[CLI-only baseline series](test-report-dsh-guard-lab.md#indirect-baseline-trials--2026-09-30).
|
|
9
9
|
The retained-log review made **no new model call** and left the original Lab
|
|
@@ -97,7 +97,7 @@ The pinned `read` tool's presentation metadata contains the returned lines.
|
|
|
97
97
|
Replacing only `content` therefore leaves a second copy of read text in the
|
|
98
98
|
private session/UI data.
|
|
99
99
|
|
|
100
|
-
The [native probe](
|
|
100
|
+
The [native probe](../../tests/probes/dsh_result_hook.mjs) instantiates the real
|
|
101
101
|
Cordis, SystemPrompt and ToolRuntime services, registers synthetic tools and
|
|
102
102
|
tests their results without a model, shell, session or network request:
|
|
103
103
|
|
|
@@ -77,7 +77,7 @@ was relaxed to make this real trial pass.
|
|
|
77
77
|
|
|
78
78
|
## Separate direct-read enforcement experiment
|
|
79
79
|
|
|
80
|
-
The shipped [fixture generator](
|
|
80
|
+
The shipped [fixture generator](../../adapters/dsh/harness/read_fixture.py) created
|
|
81
81
|
fresh `dsh-read-redaction-v1` fixtures for clean-off, clean-on, baseline and
|
|
82
82
|
guarded. Each mixed ordinary Chinese configuration, an ordinary random marker,
|
|
83
83
|
a non-credential token matching an existing GitHub secret rule, and a synthetic
|
package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md}
RENAMED
|
@@ -131,4 +131,4 @@ No production dependency, default protection policy, version, commit, push or
|
|
|
131
131
|
release was changed by this implementation.
|
|
132
132
|
|
|
133
133
|
Usage and bounds are documented in the
|
|
134
|
-
[DSH Lab helper instructions](
|
|
134
|
+
[DSH Lab helper instructions](../../adapters/dsh/harness/README.md).
|
|
@@ -20,9 +20,9 @@ blocked, compound shapes escalated to ASK, rooted deletions were quarantined
|
|
|
20
20
|
before the original command ran, and `git reset --hard` snapshotted tracked
|
|
21
21
|
modifications when a commit existed and failed closed when no commit existed.
|
|
22
22
|
|
|
23
|
-
Combined with the earlier DSH `v0.1.0` live session (see `docs/friction.md`,
|
|
23
|
+
Combined with the earlier DSH `v0.1.0` live session (see `docs/history/friction.md`,
|
|
24
24
|
F1–F11) and the Codex `gpt-5.6-sol` paired medium/high evaluation (see
|
|
25
|
-
`docs/test-report-codex-gpt-5.6-sol.md`), the DSH runtime-protection item left
|
|
25
|
+
`docs/reports/test-report-codex-gpt-5.6-sol.md`), the DSH runtime-protection item left
|
|
26
26
|
open in that report is now closed. The validation matrix remains deliberately
|
|
27
27
|
narrow — one model family per harness — so this is evidence of runtime
|
|
28
28
|
protection quality in minimal mode, not a hostile-agent security boundary.
|
|
@@ -101,12 +101,12 @@ verified in the Codex report.
|
|
|
101
101
|
|
|
102
102
|
## Relationship to prior history
|
|
103
103
|
|
|
104
|
-
- **DSH v0.1.0 live session** (`docs/friction.md`): F1–F11 were found live,
|
|
104
|
+
- **DSH v0.1.0 live session** (`docs/history/friction.md`): F1–F11 were found live,
|
|
105
105
|
fixed, and regression-pinned. The v0.1.1 run above re-verified the fixed
|
|
106
106
|
behaviors: compound shapes now ASK instead of mis-resolving targets (F1/F2),
|
|
107
107
|
heredoc bodies are payload (F5/F6/F7), workspace root resolves through
|
|
108
108
|
symlinks (F8), and workdir context is honored (F9).
|
|
109
|
-
- **Codex v0.1.1 evaluation** (`docs/test-report-codex-gpt-5.6-sol.md`):
|
|
109
|
+
- **Codex v0.1.1 evaluation** (`docs/reports/test-report-codex-gpt-5.6-sol.md`):
|
|
110
110
|
P0-1–P0-4, P1, and P2 fixes were the entry criteria for this run. The
|
|
111
111
|
real-shell DSH minimal-mode smoke is the missing live-DSH verification item
|
|
112
112
|
named in that report's "Remaining matrix expansion".
|
|
@@ -54,7 +54,7 @@ guarantee that every agent, model, tool, or future Kimi version is intercepted.
|
|
|
54
54
|
|
|
55
55
|
- Host: `@moonshot-ai/kimi-code` 0.42.0; configured route A.
|
|
56
56
|
- Entry: a `PreToolUse` hook matched to `Bash`, using
|
|
57
|
-
[`adapters/kimi-code/pre_tool_use.py`](
|
|
57
|
+
[`adapters/kimi-code/pre_tool_use.py`](../../adapters/kimi-code/pre_tool_use.py).
|
|
58
58
|
- Workspace: a new isolated, local Git project with no remote and no user
|
|
59
59
|
files. No real push or deletion was attempted.
|
|
60
60
|
- Probe design: the command began with `false &&`, so the potentially
|
|
@@ -117,7 +117,7 @@ validation alone cannot establish interception.
|
|
|
117
117
|
## Shell-bridge follow-up (same host version)
|
|
118
118
|
|
|
119
119
|
The local Kimi configuration was then changed from direct `python3` invocation
|
|
120
|
-
to the [POSIX shell bridge](
|
|
120
|
+
to the [POSIX shell bridge](../../adapters/kimi-code/hook_bridge.sh), with the
|
|
121
121
|
matcher anchored to `^Bash$` and an absolute Python path. Kimi's config
|
|
122
122
|
doctor and `python3 doctor.py kimi --probe` passed. The latter tests the
|
|
123
123
|
bridge locally, including a missing interpreter; it is **not** a host-level
|
|
@@ -174,7 +174,7 @@ old direct-Python hook-startup failure demonstrates a concrete fail-open
|
|
|
174
174
|
boundary; the later bridge trial shows only a bounded mitigation.
|
|
175
175
|
The fixtures and traces were preserved for review. Adapter-level regressions
|
|
176
176
|
for both inert command shapes live in
|
|
177
|
-
[`tests/test_kimi_adapter.py`](
|
|
177
|
+
[`tests/test_kimi_adapter.py`](../../tests/test_kimi_adapter.py).
|
|
178
178
|
|
|
179
179
|
After the live trials, the Kimi adapter was tightened to reject malformed
|
|
180
180
|
`PreToolUse` JSON and missing required Bash fields. Unit tests verify this
|
|
@@ -8,7 +8,7 @@ found a quiet guard-off baseline and therefore did not run a new guarded pair.
|
|
|
8
8
|
|
|
9
9
|
## Recorded real-model pair
|
|
10
10
|
|
|
11
|
-
The [Lab documentation](guard-lab.md#bounded-kimi-reference-trial) records one
|
|
11
|
+
The [Lab documentation](../lab/guard-lab.md#bounded-kimi-reference-trial) records one
|
|
12
12
|
2026-09-28 matched pair with Kimi Code CLI 2.1.1 and the user-declared public
|
|
13
13
|
label `Kimi official OAuth model`. Both runs used the same task SHA-256:
|
|
14
14
|
|
|
@@ -61,7 +61,7 @@ private endpoint details are not copied into this report.
|
|
|
61
61
|
|
|
62
62
|
## Repeatable capture helper and ordered repeat — 2026-09-30
|
|
63
63
|
|
|
64
|
-
The [Kimi capture helper](
|
|
64
|
+
The [Kimi capture helper](../../adapters/kimi-code/harness/README.md) now pins
|
|
65
65
|
2.1.1, uses prompt mode with `stream-json`, derives matched private homes,
|
|
66
66
|
checks non-Guard configuration equality, and separates assistant/tool/meta
|
|
67
67
|
records before scanning. Empty/header-only, unknown, failed, timed-out,
|
|
@@ -113,5 +113,5 @@ The existing native adapter covers `Bash`, and Core `ASK` is mapped to refusal
|
|
|
113
113
|
because the verified host contract cannot enforce it as approval. Missing,
|
|
114
114
|
skipped, unspawned, or timed-out hooks, general file reads, background host
|
|
115
115
|
collection, external receipt, and same-UID tampering retain the
|
|
116
|
-
[adapter limitations](
|
|
116
|
+
[adapter limitations](../../adapters/kimi-code/README.md). Neither the historical
|
|
117
117
|
pair nor a current doctor pass establishes universal protection.
|
|
@@ -157,7 +157,7 @@ Follow the existing candidate sequence: review the exact diff, obtain
|
|
|
157
157
|
authorization to commit/push rc2, run CI for that exact source, then prepare
|
|
158
158
|
the approved `0.2.3` manifest/tests/README versions and validate its final
|
|
159
159
|
artifact before authorizing the stable tag workflow. A
|
|
160
|
-
[stable release-note draft](release-notes-0.2.3.md) is ready for that step.
|
|
160
|
+
[stable release-note draft](../releases/release-notes-0.2.3.md) is ready for that step.
|
|
161
161
|
Remote publication is not authorized by this review.
|
|
162
162
|
|
|
163
163
|
## Stable preparation — 2026-10-03
|
package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md}
RENAMED
|
@@ -29,7 +29,7 @@ The same report observed working quarantine relocation, manifest and audit
|
|
|
29
29
|
records, and restoration with content intact. The resulting
|
|
30
30
|
[Windows Core CI job](https://github.com/mokuyoaxis/agent-guard/blob/main/.github/workflows/ci.yml) covers selected dialect,
|
|
31
31
|
CLI, relocation/restore and exact-byte redaction regressions on Windows.
|
|
32
|
-
See the [rc1 notes](release-notes-0.2.3-rc1.md) for the fix scope.
|
|
32
|
+
See the [rc1 notes](../releases/release-notes-0.2.3-rc1.md) for the fix scope.
|
|
33
33
|
|
|
34
34
|
## Withdrawn redaction finding
|
|
35
35
|
|
|
@@ -218,11 +218,11 @@ predict — the audit trail (`compensations: []`) made the outcome verifiable.
|
|
|
218
218
|
|
|
219
219
|
## Relationship to prior history
|
|
220
220
|
|
|
221
|
-
- **Codex `gpt-5.6-sol` evaluation** (`docs/test-report-codex-gpt-5.6-sol.md`):
|
|
221
|
+
- **Codex `gpt-5.6-sol` evaluation** (`docs/reports/test-report-codex-gpt-5.6-sol.md`):
|
|
222
222
|
the fail-closed compensation contract exercised here (`COMPENSATION_FAILED`
|
|
223
223
|
on empty-repo `git reset --hard`) is the P0-3 remediation that report
|
|
224
224
|
pinned; it held on Windows.
|
|
225
|
-
- **DSH v0.1.1 report** (`docs/test-report-dsh-v0.1.1.md`): same decision
|
|
225
|
+
- **DSH v0.1.1 report** (`docs/reports/test-report-dsh-v0.1.1.md`): same decision
|
|
226
226
|
matrix methodology; its "Remaining matrix expansion" item "other harness
|
|
227
227
|
live sessions" is advanced to a second harness family (ZCode) and a second
|
|
228
228
|
model family (GLM Flash), on a third platform (win32/POSIX shell).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mokuyoaxis/agent-guard",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
4
4
|
"description": "Harness-neutral reliability infrastructure for AI coding agents: reversible destructive actions, pre-emission redaction, recovery evidence, and a shared Decision Protocol with optional native adapters.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./adapters/dsh/lib/index.js",
|
|
@@ -67,6 +67,14 @@ A block is not an error to route around. Retrying the same operation in a
|
|
|
67
67
|
disguised form (`/bin/rm`, `python -c`, a script) is a violation of the
|
|
68
68
|
authorization pillar and is recorded in the audit log.
|
|
69
69
|
|
|
70
|
+
`git reset --hard [commit]` first checks whether its target tree would
|
|
71
|
+
overwrite untracked or ignored content. A tracked-only stash cannot recover
|
|
72
|
+
those paths, so a collision returns `BLOCK_GIT_RESET_COLLISION` without
|
|
73
|
+
moving them or creating a snapshot. Preserve the conflicting content
|
|
74
|
+
separately before retrying. Use a standalone reset without shell wrappers;
|
|
75
|
+
compound commands, submodule effects, unknown options, and stash-relative
|
|
76
|
+
targets are refused as undeterminable. Unrelated untracked files are allowed.
|
|
77
|
+
|
|
70
78
|
## Compensation preflight and verification
|
|
71
79
|
|
|
72
80
|
Before sandboxed use, ensure `.agent-trash/` is already ignored by a tracked
|
|
@@ -81,6 +89,26 @@ stop immediately. Inspect both the origin and `.agent-trash/`; never infer
|
|
|
81
89
|
that an error means no filesystem change occurred. A durable
|
|
82
90
|
`relocate-intent` can keep an interrupted relocation discoverable.
|
|
83
91
|
|
|
92
|
+
## Quarantine location queries
|
|
93
|
+
|
|
94
|
+
When the user asks where quarantines are or how many exist, use the shared
|
|
95
|
+
read-only query with a current-directory or user-selected scope:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --json
|
|
99
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --root <projects> --max-depth 3 --json
|
|
100
|
+
python3 <repo>/skills/delete-guard/scripts/status.py --trash-index --trash <custom-store> --json
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Report the scope, candidate count, metadata-identified count and read/budget
|
|
104
|
+
errors. Do not claim that unconfirmed/unreadable locations are absent or that
|
|
105
|
+
the result covers the whole host. Explain that these are bucket locations,
|
|
106
|
+
not file/transaction totals. If you supplement the result yourself, identify
|
|
107
|
+
that source separately. Existing native status tools may show the current
|
|
108
|
+
project only; use the CLI for this indexed query. Location metadata and cached
|
|
109
|
+
JSON are not authorization to purge, and recovery file contents must not be
|
|
110
|
+
read just to answer a location/count question.
|
|
111
|
+
|
|
84
112
|
## RESTRICTED mode
|
|
85
113
|
|
|
86
114
|
After a human veto, the session runs with narrowed powers: explicit
|
|
@@ -104,5 +132,15 @@ overwrite anything that now exists at the origin unless a human passes
|
|
|
104
132
|
`--force`. Git snapshots are stored as stashes named `agent-guard:<txid>`;
|
|
105
133
|
restore applies them and never drops them.
|
|
106
134
|
|
|
135
|
+
With human `--force`, an existing occupant is first preserved by the normal
|
|
136
|
+
relocation journal in a separate transaction. The result's optional
|
|
137
|
+
`backup_txids` lists preservation attempts; an ID alone does not prove the
|
|
138
|
+
copy completed. Inspect those IDs with `restore.py list --json` and the
|
|
139
|
+
filesystem after any error. A failed old-version move must not be followed
|
|
140
|
+
by deleting the preserved occupant. Restoring a completed backup transaction
|
|
141
|
+
uses the same `restore.py <txid>` command; if the origin is occupied, the
|
|
142
|
+
usual conflict/force rules apply again. Preserved versions consume quarantine
|
|
143
|
+
space and remain subject to its existing explicit GC policy.
|
|
144
|
+
|
|
107
145
|
See `references/policy.md` for the complete rule table, verdict codes, and
|
|
108
146
|
manifest format.
|
|
@@ -51,7 +51,7 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
51
51
|
| 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
|
|
52
52
|
| 2 | unresolvable targets: shell vars, command substitution, unbalanced quotes, `bash -c` with destructive smell, `find -delete`, `find -exec rm`, stdin-fed (`xargs`) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse - allowing it would forfeit the core guarantee |
|
|
53
53
|
| 2a | SHAPE F1: destructive op preceded by `cd` in the same command line, target in-workspace and resolvable | `ASK` (`COMPOUND_CWD_DELETE`) | single-execution authorization; splitting the command avoids the prompt. A shape rule describes *compensation* difficulty, never effect scope: if the target set also trips rule 2, 4, 5 or 6, that BLOCK wins (`tests/test_incident_regression.py`) |
|
|
54
|
-
| 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization;
|
|
54
|
+
| 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; force-push is refused separately. Hard reset in a compound line is effect-uncertain and BLOCKED before shape rules |
|
|
55
55
|
| 2c | target *is* a filesystem root (`/`, `/home`, `/usr`, `/etc`, `/var`, `/tmp`, `/opt`, `/boot`, `$HOME`, ...) | `BLOCK_PROTECTED_ANCESTOR` | refuse. Matched exactly, so paths *under* these roots keep the ordinary codes; enforced by identity rather than workspace geometry, so it holds even when the workspace is `/` |
|
|
56
56
|
| 3 | any target inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | direct delete permitted (housekeeping) |
|
|
57
57
|
| 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
|
|
@@ -64,7 +64,9 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
|
|
|
64
64
|
| 11 | supported `git clean -f...` | `RELOCATE_VIA_CLEAN_ENUMERATE` | enumerate via `clean -n`, decode every Git-quoted path, relocate every match, proceed only on full coverage |
|
|
65
65
|
| 11a | `git clean -ff`, interactive `-i`, or exclude `-e` | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; nested-repository and interactive/exclusion semantics are not safely mirrored |
|
|
66
66
|
| 11b | supported `git clean -f...` whose target set cannot be enumerated (not a repository, `git` cannot run) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; the targets exist but their set is unknowable, so nothing was attempted and nothing may be reported as a failed compensation |
|
|
67
|
-
| 12 | `git reset --hard
|
|
67
|
+
| 12 | supported `git reset --hard [commit]` without untracked/ignored collisions, `git restore <path>`, `git checkout -- <path>` | `SNAPSHOT_GIT_STASH` | hard reset first checks its target tree; `git stash create`+`store` then protects tracked modifications; any create/store failure blocks |
|
|
68
|
+
| 12a | hard reset target overlaps untracked/ignored content or quarantine storage | `BLOCK_GIT_RESET_COLLISION` | refuse before compensation; preserve conflicting paths separately before retrying |
|
|
69
|
+
| 12b | hard reset target cannot be resolved/enumerated, has unsupported options or submodule effects, is stash-relative, or uses shell wrappers/compound commands | `BLOCK_UNDETERMINABLE_EFFECT` | refuse before compensation; use a standalone reset with an explicit stable commit |
|
|
68
70
|
| 13 | all targets git-ignored AND match artifact patterns | `ALLOW_REGENERABLE` | direct delete |
|
|
69
71
|
| 14 | rooted recursive delete | `RELOCATE_TREE` | quarantine whole tree, proceed |
|
|
70
72
|
| 15 | named files/dirs | `RELOCATE_PATHS` | quarantine, proceed |
|
|
@@ -154,8 +156,19 @@ model tool.
|
|
|
154
156
|
|
|
155
157
|
- Command-level interception covers the recognized vocabulary; arbitrary
|
|
156
158
|
scripts that delete internally are invisible to `check.py` (see
|
|
157
|
-
`docs/threat-model.md`).
|
|
158
|
-
- `git stash create` captures tracked modifications
|
|
159
|
-
|
|
159
|
+
`docs/design/threat-model.md`).
|
|
160
|
+
- `git stash create` captures tracked modifications only. `reset --hard`
|
|
161
|
+
can delete untracked and ignored content that obstructs its target tree.
|
|
162
|
+
`check.py` checks file/directory/ancestor collisions and refuses them;
|
|
163
|
+
this version does not automatically archive those paths. It also refuses
|
|
164
|
+
target-tree writes into quarantine. Ordinary unrelated untracked files
|
|
165
|
+
remain allowed. Only `--hard`, optional `-q`/`--quiet`, and at most one
|
|
166
|
+
commit are supported; submodules and stash-relative targets are refused.
|
|
167
|
+
- Hard reset must be standalone without shell wrappers: other segments can
|
|
168
|
+
change its revision or create a collision after preflight; wrappers can
|
|
169
|
+
change its Git environment. The preflight and host execution are separate;
|
|
170
|
+
concurrent changes are not atomically excluded.
|
|
171
|
+
Direct callers of `snapshot_git` receive a tracked-only snapshot and must
|
|
172
|
+
run the hard-reset preflight themselves before authorizing that operation.
|
|
160
173
|
- Windows cmd/PowerShell, databases, cloud resources: future skills
|
|
161
174
|
(`git-guard`, `database-guard`, `cloud-guard`) on the same core.
|
|
@@ -105,6 +105,25 @@ def main() -> int:
|
|
|
105
105
|
specs, parse_error = [], None
|
|
106
106
|
verdicts = [policy.decide_dialect_failure(resolution)]
|
|
107
107
|
|
|
108
|
+
# Preflight every reset before ANY compensation in the line. Advisory
|
|
109
|
+
# and enforced checks agree, and a later unsafe reset cannot leave an
|
|
110
|
+
# earlier filesystem relocation half-applied. Stash create only saves
|
|
111
|
+
# tracked modifications, so it cannot authorize an untracked collision.
|
|
112
|
+
if not policy.worst(verdicts).blocked:
|
|
113
|
+
for index, (spec, verdict) in enumerate(zip(specs, verdicts)):
|
|
114
|
+
if spec.kind != classifier.KIND_GIT_RESET_HARD or \
|
|
115
|
+
verdict.decision != policy.DECISION_SNAPSHOT:
|
|
116
|
+
continue
|
|
117
|
+
collisions, error = engine.preflight_git_reset_hard(
|
|
118
|
+
cwd=base, target=spec.targets[0] if spec.targets else "HEAD")
|
|
119
|
+
if error or collisions:
|
|
120
|
+
verdicts[index] = policy.Verdict(
|
|
121
|
+
policy.DECISION_BLOCK,
|
|
122
|
+
policy.CODE_BLOCK_UNDETERMINABLE_EFFECT if error else
|
|
123
|
+
policy.CODE_BLOCK_GIT_RESET_COLLISION,
|
|
124
|
+
[error or "untracked/ignored or quarantine collision"],
|
|
125
|
+
)
|
|
126
|
+
|
|
108
127
|
top = policy.worst(verdicts)
|
|
109
128
|
latency_ms = round((time.monotonic() - started) * 1000, 1)
|
|
110
129
|
check_id = audit.new_txid()
|
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
restore.py TXID [--force] [--json]
|
|
6
6
|
|
|
7
7
|
Restore is non-destructive by default: it refuses to overwrite anything now
|
|
8
|
-
occupying an origin path. --force
|
|
8
|
+
occupying an origin path. --force preserves that occupant in a separate
|
|
9
|
+
transaction before restoring. Inspect backup_txids after success or failure.
|
|
9
10
|
"""
|
|
10
11
|
from __future__ import annotations
|
|
11
12
|
|
|
@@ -69,20 +70,31 @@ def main() -> int:
|
|
|
69
70
|
|
|
70
71
|
report = engine.restore(args.txid, force=args.force)
|
|
71
72
|
workspace = engine.workspace
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
73
|
+
event = {"event": "restore", "txid": args.txid, "force": args.force,
|
|
74
|
+
"ok": report.get("ok"), "restored": report.get("restored"),
|
|
75
|
+
"conflicts": report.get("conflicts"),
|
|
76
|
+
"errors": report.get("errors")}
|
|
77
|
+
if report.get("backup_txids"):
|
|
78
|
+
event["backup_txids"] = report["backup_txids"]
|
|
79
|
+
try:
|
|
80
|
+
audit.append(event, os.path.join(engine.trash_root, AUDIT_NAME))
|
|
81
|
+
except OSError:
|
|
82
|
+
report["ok"] = False
|
|
83
|
+
report.setdefault("errors", []).append(
|
|
84
|
+
"restore audit could not be stored; inspect filesystem state")
|
|
77
85
|
if args.as_json:
|
|
78
86
|
print(json.dumps(report, ensure_ascii=False, indent=2))
|
|
79
87
|
else:
|
|
88
|
+
for txid in report.get("backup_txids", []):
|
|
89
|
+
print(f"current-version preservation transaction: {txid} (inspect state)")
|
|
80
90
|
for path in report.get("restored", []):
|
|
81
91
|
print(f"restored: {path}")
|
|
82
92
|
for path in report.get("conflicts", []):
|
|
83
93
|
print(f"conflict (exists; use --force): {path}")
|
|
84
94
|
for err in report.get("errors", []):
|
|
85
95
|
print(f"error: {err}", file=sys.stderr)
|
|
96
|
+
if report.get("error"):
|
|
97
|
+
print(f"error: {report['error']}", file=sys.stderr)
|
|
86
98
|
if report.get("errors"):
|
|
87
99
|
return 1
|
|
88
100
|
if report.get("conflicts"):
|
|
@@ -2,6 +2,7 @@
|
|
|
2
2
|
"""status - inspect guard state, quarantine usage, recent decisions.
|
|
3
3
|
|
|
4
4
|
status.py [--json] [--tail N]
|
|
5
|
+
status.py --trash-index [--root PATH ...] [--trash PATH ...] [--json]
|
|
5
6
|
"""
|
|
6
7
|
from __future__ import annotations
|
|
7
8
|
|
|
@@ -21,9 +22,60 @@ def main() -> int:
|
|
|
21
22
|
ap = argparse.ArgumentParser(description=__doc__)
|
|
22
23
|
ap.add_argument("--json", action="store_true", dest="as_json")
|
|
23
24
|
ap.add_argument("--tail", type=int, default=10)
|
|
25
|
+
ap.add_argument("--trash-index", action="store_true",
|
|
26
|
+
help="read-only quarantine locations for agents and future UI")
|
|
27
|
+
ap.add_argument("--root", action="append", default=[],
|
|
28
|
+
help="search root for --trash-index (repeatable)")
|
|
29
|
+
ap.add_argument("--trash", action="append", default=[],
|
|
30
|
+
help="declared external/custom quarantine path (repeatable)")
|
|
31
|
+
ap.add_argument("--max-depth", type=int, default=None,
|
|
32
|
+
help="directory depth below each search root (default 3)")
|
|
33
|
+
ap.add_argument("--max-entries", type=int, default=None,
|
|
34
|
+
help="index directory-entry budget (default 10000)")
|
|
24
35
|
args = ap.parse_args()
|
|
25
36
|
|
|
26
37
|
base = os.getcwd()
|
|
38
|
+
if args.trash_index:
|
|
39
|
+
from core.trash_index import (
|
|
40
|
+
DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENTRIES, list_trash_locations)
|
|
41
|
+
roots, paths = list(args.root), list(args.trash)
|
|
42
|
+
if not roots and not paths:
|
|
43
|
+
roots = [base]
|
|
44
|
+
configured = os.environ.get("AGENT_GUARD_TRASH")
|
|
45
|
+
if configured:
|
|
46
|
+
paths.append(configured)
|
|
47
|
+
try:
|
|
48
|
+
result = list_trash_locations(
|
|
49
|
+
roots, trash_paths=paths,
|
|
50
|
+
max_depth=(DEFAULT_MAX_DEPTH if args.max_depth is None
|
|
51
|
+
else args.max_depth),
|
|
52
|
+
max_entries=(DEFAULT_MAX_ENTRIES if args.max_entries is None
|
|
53
|
+
else args.max_entries))
|
|
54
|
+
except ValueError as exc:
|
|
55
|
+
ap.error(str(exc))
|
|
56
|
+
if args.as_json:
|
|
57
|
+
# ASCII escapes preserve unusual POSIX names in valid UTF-8 JSON.
|
|
58
|
+
print(json.dumps(result, ensure_ascii=True, indent=2))
|
|
59
|
+
else:
|
|
60
|
+
print(f"quarantine locations: {result['count']} candidates, "
|
|
61
|
+
f"{result['identified_count']} with metadata")
|
|
62
|
+
print(f"scope: depth={result['max_depth']} budget={result['max_entries']}")
|
|
63
|
+
for path in result["roots"]:
|
|
64
|
+
print(f" root: {json.dumps(path)}")
|
|
65
|
+
for path in result["trash_paths"]:
|
|
66
|
+
print(f" declared: {json.dumps(path)}")
|
|
67
|
+
for row in result["entries"]:
|
|
68
|
+
print(f" [{row['status']}] {json.dumps(row['trash_root'])}")
|
|
69
|
+
if row["trash_root"] != row["resolved_trash_root"]:
|
|
70
|
+
print(f" resolved: {json.dumps(row['resolved_trash_root'])}")
|
|
71
|
+
for error in result["errors"]:
|
|
72
|
+
print(f" {error['code']}: {json.dumps(error['path'])}")
|
|
73
|
+
if not result["complete"]:
|
|
74
|
+
print("partial index: inspect scope and errors")
|
|
75
|
+
return 0 if result["complete"] else 1
|
|
76
|
+
if (args.root or args.trash or args.max_depth is not None or
|
|
77
|
+
args.max_entries is not None):
|
|
78
|
+
ap.error("index options require --trash-index")
|
|
27
79
|
workspace = classifier.discover_workspace(base)
|
|
28
80
|
trash_root = os.environ.get(
|
|
29
81
|
"AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
|