@mokuyoaxis/agent-guard 0.2.3-rc1 → 0.2.3

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.
Files changed (61) hide show
  1. package/README.md +124 -52
  2. package/README.zh-CN.md +102 -41
  3. package/adapters/dsh/README.md +92 -10
  4. package/adapters/dsh/harness/README.md +384 -0
  5. package/adapters/dsh/harness/baseline.patch.yml +8 -0
  6. package/adapters/dsh/harness/bootstrap.patch.yml +5 -0
  7. package/adapters/dsh/harness/bootstrap_init.mjs +48 -0
  8. package/adapters/dsh/harness/guard_lab.py +771 -0
  9. package/adapters/dsh/harness/native_session.py +503 -0
  10. package/adapters/dsh/harness/profiles.py +212 -0
  11. package/adapters/dsh/harness/read_fixture.py +60 -0
  12. package/adapters/dsh/harness/retry_stream.py +171 -0
  13. package/adapters/dsh/harness/session_decode.mjs +117 -0
  14. package/adapters/dsh/lib/index.js +46 -5
  15. package/adapters/dsh/lib/read_result_guard.js +207 -0
  16. package/adapters/dsh/lib/read_result_guard.py +139 -0
  17. package/adapters/harness_support.py +109 -0
  18. package/adapters/kimi-code/README.md +15 -7
  19. package/adapters/kimi-code/harness/README.md +126 -0
  20. package/adapters/kimi-code/harness/guard_lab.py +430 -0
  21. package/core/lab.py +2396 -0
  22. package/core/redaction.py +157 -55
  23. package/docs/architecture.md +75 -0
  24. package/docs/development-note-unguarded-deletion.md +6 -7
  25. package/docs/friction.md +140 -4
  26. package/docs/guard-lab-clean-task.md +4 -0
  27. package/docs/guard-lab-read-trial-task.md +7 -0
  28. package/docs/guard-lab-trial-task.md +5 -0
  29. package/docs/guard-lab.md +398 -0
  30. package/docs/harness-capabilities.md +8 -5
  31. package/docs/release-notes-0.2.0-rc1.md +2 -2
  32. package/docs/release-notes-0.2.0.md +2 -2
  33. package/docs/release-notes-0.2.2.md +7 -8
  34. package/docs/release-notes-0.2.3-rc1.md +4 -2
  35. package/docs/release-notes-0.2.3-rc2.md +189 -0
  36. package/docs/release-notes-0.2.3.md +84 -0
  37. package/docs/secret-guard-analysis.md +13 -12
  38. package/docs/secret-guard-architecture.md +5 -3
  39. package/docs/secret-guard-design.md +7 -3
  40. package/docs/test-report-codex-gpt-5.6-sol.md +10 -11
  41. package/docs/test-report-dsh-0.2-upgrade.md +142 -0
  42. package/docs/test-report-dsh-guard-lab.md +154 -0
  43. package/docs/test-report-dsh-native-session.md +118 -0
  44. package/docs/test-report-dsh-paired-lab.md +183 -0
  45. package/docs/test-report-dsh-read-redaction.md +114 -0
  46. package/docs/test-report-dsh-real-followup.md +170 -0
  47. package/docs/test-report-dsh-retry-evidence.md +134 -0
  48. package/docs/test-report-kimi-code-block.md +19 -20
  49. package/docs/test-report-kimi-guard-lab.md +117 -0
  50. package/docs/test-report-release-readiness-0.2.3.md +239 -0
  51. package/docs/test-report-workbuddy-windows-core.md +53 -0
  52. package/docs/test-report-zcode-glm-flash.md +9 -9
  53. package/docs/threat-model.md +42 -0
  54. package/guard_lab.py +14 -0
  55. package/package.json +8 -5
  56. package/skills/delete-guard/SKILL.md +2 -3
  57. package/skills/exfil-guard/SKILL.md +37 -7
  58. package/skills/exfil-guard/references/rules.md +84 -16
  59. package/skills/exfil-guard/scripts/_payload.py +99 -0
  60. package/skills/exfil-guard/scripts/check_span.py +14 -81
  61. package/skills/exfil-guard/scripts/sanitize.py +113 -34
@@ -0,0 +1,239 @@
1
+ # 0.2.3 contract and release readiness review
2
+
3
+ Date: 2026-09-30 (UTC). Initial checkpoint: the uncommitted `0.2.3-rc2`
4
+ worktree on `31a8874`. The candidate push continuation below records the
5
+ subsequent CI finding and correction. This report does not describe a
6
+ published stable `0.2.3` artifact.
7
+
8
+ ## DSH impact and admitted contracts
9
+
10
+ Most [DSH rc.2 release changes](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.2.0-rc.2)
11
+ concern desktop/UI behavior. However, the installed upgrade from
12
+ `0.1.5-rc.1` to `0.2.0-rc.2` changes Shell execution and native session
13
+ contracts used by this adapter. Core policy does not need to follow the UI;
14
+ adapter translation and evidence interpretation do need verification.
15
+
16
+ | Surface | Current implementation | Fresh evidence / limit |
17
+ |---|---|---|
18
+ | Package admission | Exactly `0.1.5-rc.1` or `0.2.0-rc.2` | Manifest and Lab preflight agree |
19
+ | Default deletion | New `execute(spec).result()`; legacy `run(spec)` when the new method is absent | Both installed hosts pass harmless execution, marker absence and Core block audit; execution failures do not retry the legacy method |
20
+ | Optional text-read guard | Node 22, exact versions/artifact hashes and native read binding | New local and sandbox FS pass actual ToolRuntime, AgentLoop and JSONL probes |
21
+ | Native Lab capture | Old host: native v3 / receipt v4; new host: native v4 / receipt v5; parser v2 | Fresh boot-free checks and four-home preparation pass; unsupported sessions remain inconclusive |
22
+ | Historical evidence | Original receipt/parser/format interpretation retained | No historical receipt, report or real-model outcome was upgraded |
23
+ | Running Web agent | Separate installed deployment | This checkout's activation and agent scope remain unverified |
24
+
25
+ The [initial upgrade report](test-report-dsh-0.2-upgrade.md) remains a historical
26
+ snapshot. Its statements that package/read/Lab pins still reject the new host
27
+ were true then and are superseded by the current source and checks above.
28
+
29
+ ## Fresh native verification
30
+
31
+ Environment: Android/PRoot Debian ARM64, Node `22.23.2`, Python `3.13.5`.
32
+ No new production dependency, external model call or live Web configuration
33
+ change was made. Synthetic fixtures and evidence are private and outside
34
+ the repository.
35
+
36
+ - Default deletion probes on old and new hosts pass. A further new-host probe
37
+ with `readResultGuard` explicitly enabled also passes and does not report
38
+ startup refusal. In each probe a benign marker exists, the blocked marker
39
+ does not, and a durable `BLOCK_UNDETERMINABLE_EFFECT` audit exists.
40
+ - The deletion probes use `danger-full-access` only in fresh private profiles
41
+ because Android/PRoot lacks the host's shell confinement backend. They do
42
+ not verify workspace-write shell confinement or alter a user's deployment.
43
+ - New local and sandbox FS read probes each pass all 10 withheld-result
44
+ cases, plugin load/startup/disposal checks, scoped-shadow denial, version
45
+ and artifact drift refusal. Protected synthetic values are absent from
46
+ guarded value/content/meta, the next synthetic request and full durable
47
+ JSONL. Ordinary config, Chinese text, line numbers and a random marker stay
48
+ readable. Each uses two deterministic streams and zero external model,
49
+ network or shell calls. The sandbox FS result is a filesystem-provider
50
+ check, not a shell sandbox acceptance result.
51
+ - The new result-hook probe confirms that replacing only content retains
52
+ original presentation metadata; replacing the value regenerates metadata;
53
+ a later finalizer can reintroduce content. This justifies the pinned binding
54
+ checks and does not establish arbitrary plugin containment.
55
+ - Old and new boot-free Lab preflights pass. The new four-home pair preparation
56
+ reports `READY`, equal scoped non-Guard fingerprints and
57
+ `host_tasks_launched=0`; no model trial was launched.
58
+ - The local old installation's `dsh-tool-fs` entry hash differs from the
59
+ reviewed old artifact. Its optional read guard correctly refuses startup.
60
+ This is an installation-drift limit, not a passing legacy read re-test; its
61
+ default deletion path passes independently. No installed code or pin was
62
+ changed to force admission.
63
+
64
+ ## Real-model follow-up is incomplete
65
+
66
+ The retained new-host direct-read experiment has only the `clean-off`
67
+ capture and no completed review/off-on result. Its receipt reports
68
+ `UNSUPPORTED_SURFACE_REPLAY`, `recognized=false` and
69
+ `composition_unchanged=false`. Exit zero does not clear these gates. The
70
+ current parser intentionally refuses v4 surface replay and image offload;
71
+ passing synthetic v4/retry tests does not make this real trial complete.
72
+
73
+ Prior official Flash direct-read results and Kimi/DSH Lab results retain their
74
+ original host versions and observation channels. No new DSH injection L2
75
+ claim follows from this review. Repairing replay interpretation or adding a
76
+ read-redaction injection protocol is separate work, rather than a requirement
77
+ for the originally planned offline Lab MVP.
78
+
79
+ ## Local regression and package gate
80
+
81
+ The first fresh full suite ran 595 tests in 670.686 seconds and had one error:
82
+ an observer did not become ready within the existing five-second startup
83
+ bound. The runner then attempted to stop the unarmed observer, masking the
84
+ original error. The isolated original test passed on repeat; that does not
85
+ turn the failed full run into a passing gate.
86
+
87
+ Both DSH and Kimi runners now enter host-execution cleanup only after observer
88
+ startup succeeds. Startup keeps its own bounded stop-request handling. Two
89
+ new regressions confirm that the original error survives, no host task starts,
90
+ no capture receipt is credited and the report remains inconclusive. Those
91
+ regressions plus the original test passed together (3 tests, 3.377 seconds).
92
+ The startup deadline, Core policy and observer success criteria were not
93
+ relaxed. This fixes error preservation, not a guarantee of startup under any
94
+ system load.
95
+
96
+ - After the correction, full `npm test` passed all 597 Python tests in
97
+ 1026.421 seconds, followed by both Node adapter/read-worker smoke suites.
98
+ - Python syntax (63 public source files), JavaScript syntax, LF/trailing
99
+ whitespace, `git diff --check` and 240 local links in 56 Markdown files pass.
100
+ Shared Core/skill sources have no reverse DSH/adapter imports.
101
+ - The candidate package contains 107 files. Package scanning found no private
102
+ captures/controllers, tests, bytecode, local account paths or supported
103
+ credential-shaped values. Packaged files were checked against the worktree.
104
+ - Offline isolated installation of the local tarball passes all 10 public
105
+ CLI help checks and adapter import without DSH. All four deterministic Lab
106
+ cases return `COMPLETE/PASS`, L0 `CALIBRATION_ONLY`, observer `STOPPED` and
107
+ `external-boundary=UNSUPPORTED`.
108
+ - Final documentation is repacked after recording these results; its runnable
109
+ assets are compared byte-for-byte with the package exercised above. Final
110
+ checksums and source inventory are retained in private review evidence.
111
+
112
+ This is completed local regression, not hosted CI or a passing new-host
113
+ real-model trial. Native Windows/PowerShell and macOS were not run locally.
114
+
115
+ ## Candidate push continuation
116
+
117
+ The maintainer subsequently authorized the complete rc2 GitHub/npm push.
118
+ The candidate source was committed and pushed as `e731016`. Its
119
+ [npm credential/package preflight](https://github.com/mokuyoaxis/agent-guard/actions/runs/36750990598)
120
+ passed without publishing. Its
121
+ [first CI run](https://github.com/mokuyoaxis/agent-guard/actions/runs/36750957084)
122
+ passed the five Linux Python versions, Windows Core, DSH adapter and native
123
+ Lab jobs, but failed all five macOS Python jobs. The macOS Python 3.11 run
124
+ finished 597 tests in 513.107 seconds with 5 failures and 81 errors, all
125
+ concentrated on the observer's five-second READY startup gate. No rc2 tag
126
+ was pushed against that failing source.
127
+
128
+ Inspection found that the standard-library `HTTPServer.server_bind` calls
129
+ `socket.getfqdn` even when binding the numeric loopback address. That lookup
130
+ is unnecessary for this offline observer and can block startup on an offline
131
+ or slow resolver. A regression reproduces the dependency by making hostname
132
+ resolution unavailable; the original code raises the injected error. The
133
+ observer now binds through `TCPServer` and retains its numeric server address
134
+ and actual port. The same regression completes the observer lifecycle and
135
+ report without querying DNS. READY timing, loopback scope, route tokens and
136
+ evidence criteria are unchanged. Exact-source CI and npm preflight must pass
137
+ again before the tag workflow may publish.
138
+
139
+ The local correction gate passed 11 focused tests in 21.029 seconds: DNS
140
+ unavailability, all four deterministic cases, detached arm/stop and snapshot
141
+ CLI lifecycles, DSH/Kimi clean capture and both startup-error regressions.
142
+
143
+ ## Initial release decision (historical checkpoint)
144
+
145
+ The planned `0.2.3` scope is the rc1 Windows/Core fix plus the offline
146
+ guard-lab MVP. It does not require UI parity with DSH, universal host
147
+ adaptation, a new real-model mitigation claim or live Web deployment changes.
148
+ The current source has those planned features and scoped new-host support.
149
+
150
+ Direct stable publication is not yet cleared: this worktree is still
151
+ `0.2.3-rc2`, and hosted CI covers only `31a8874` before the Lab/DSH additions.
152
+ The read-only Actions check confirms the old run's 12 jobs passed, including
153
+ Windows Core. It supplies no CI evidence for the current additions. Registry
154
+ dist-tags still read `latest=0.2.2`, `rc=0.2.3-rc1`.
155
+
156
+ Follow the existing candidate sequence: review the exact diff, obtain
157
+ authorization to commit/push rc2, run CI for that exact source, then prepare
158
+ the approved `0.2.3` manifest/tests/README versions and validate its final
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.
161
+ Remote publication is not authorized by this review.
162
+
163
+ ## Stable preparation — 2026-10-03
164
+
165
+ The maintainer authorized README polishing and preparation for stable 0.2.3
166
+ and a dsh-market listing. The local manifest is now `0.2.3`; committing,
167
+ pushing, tagging, npm/GitHub publication and the catalog PR are subsequent
168
+ steps. At this preparation checkpoint, registry checks showed
169
+ `latest=0.2.2`, `rc=0.2.3-rc2`, with no
170
+ published 0.2.3 package. Earlier sections retain their checkpoint dates.
171
+
172
+ The current source adds validated sanitizer execution and external plans,
173
+ bounded UTF-8 input, URI password detection, newer GitHub and PyPI token
174
+ coverage, complete-name/placeholder boundaries and targeted AWS/JWT noise
175
+ corrections. No production dependency or shared channel policy was added.
176
+ The native capture helpers now use receipt v6 / parser v3, with source-call
177
+ correlation and initialized isolated-profile fingerprints; old evidence keeps
178
+ its original interpretation. Pending Lab trials are not recorded as complete,
179
+ and no new injection L2 claim follows from this preparation.
180
+
181
+ Earlier checks on 2026-10-03 exercised installed DSH 0.2.0-rc.2 local/sandbox
182
+ read probes with the Core rules preserved in this candidate: protected
183
+ synthetic values were absent from guarded
184
+ value/content/meta, the next deterministic request and full JSONL, while
185
+ normal configuration, resource IDs and Unicode stayed readable. Those probes
186
+ made zero external model, network or shell calls. They validate reviewed
187
+ native providers, not universal output interception or shell sandboxing.
188
+
189
+ Two earlier 676-case full local runs each had a different startup/subprocess
190
+ timeout; both isolated cases subsequently passed. Those failed runs remain
191
+ failed. This preparation's 14-case preflight passed in 18.645 seconds,
192
+ including package/release checks and both previously timed-out cases.
193
+ The complete local candidate gate then passed all 676 Python tests in
194
+ 729.911 seconds, followed by both Node adapter/read-worker smoke suites.
195
+ The environment was Python 3.13.5 / Node 22.23.2 on ARM64/PRoot. The full pass
196
+ does not identify the cause of the earlier transient timeouts; no safety or
197
+ timing threshold was relaxed.
198
+
199
+ The candidate tarball contains 112 files, including the new WorkBuddy summary
200
+ and all public CLI/adapter assets. It excludes internal evidence, tests and
201
+ caches. Offline isolated installation with scripts disabled passed all ten
202
+ CLI help checks and adapter import without an installed DSH dependency.
203
+ Packaged files matched the worktree byte-for-byte. Final documentation is
204
+ repacked after recording these results; its runnable assets must match that
205
+ validated tarball. All 58 public Markdown files, 266 local links, 64 Python
206
+ syntax trees and the LF/diff checks passed; supported secret-pattern scanning
207
+ found no hits in those Markdown files.
208
+
209
+ Native Windows/macOS cannot be revalidated on this local host. The eventual
210
+ exact-source hosted CI and npm credential preflight remain required before
211
+ tagging. This preparation launched no new real-host/model trial and made no
212
+ remote repository, registry or catalog change.
213
+
214
+ The [WorkBuddy summary](test-report-workbuddy-windows-core.md) records
215
+ community Core/CLI feedback without claiming a native hook. Both READMEs
216
+ preserve their section order, add scoped evidence badges and distinguish the
217
+ prepared source from published artifacts.
218
+
219
+ dsh-market reads the community
220
+ [awesome-dsh-plugin catalog](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin/blob/main/contributing.md).
221
+ The checked catalog does not yet contain this project. A one-file bilingual
222
+ `security` entry and PR copy are prepared locally. Package-to-repository
223
+ mapping and the existing DSH bundle are already present; listing and
224
+ publication remain separate actions.
225
+
226
+ ## Publication authorization — 2026-10-03
227
+
228
+ The maintainer subsequently authorized the complete three-part publication:
229
+ GitHub Release, npm and the dsh-market catalog submission. The README and
230
+ stable notes now use release wording, while registry availability is shown by
231
+ the npm badge and Releases. This documentation pass changes no runnable asset
232
+ from the locally validated candidate.
233
+
234
+ The release sequence requires the exact pushed source to pass the 13-job CI
235
+ and npm credential preflight before the `0.2.3` tag starts publication.
236
+ The existing tag workflow creates a stable GitHub Release and publishes its
237
+ same checksummed tarball to npm `latest` with provenance. The catalog PR uses
238
+ the verified package and changes one entry; submission is distinct from
239
+ upstream acceptance and appearance in dsh-market.
@@ -0,0 +1,53 @@
1
+ # WorkBuddy on Windows: community Core/CLI feedback
2
+
3
+ Report date: 2026-09-27. Summary reviewed: 2026-10-03.
4
+
5
+ [Issue #7](https://github.com/mokuyoaxis/agent-guard/issues/7) records a community
6
+ run against Agent Guard `0.2.2`, commit `274127e`, on Windows 11 with Git Bash,
7
+ Python 3.13.15 and Git 2.55.0.windows.3. The reporter
8
+ [identified the executor as WorkBuddy](https://github.com/mokuyoaxis/agent-guard/issues/7#issuecomment-5857388494):
9
+ an AI coding agent invoked the repository's Python CLI directly.
10
+
11
+ No adapter, harness wrapper or `PreToolUse` hook was involved. This is evidence
12
+ about Core behavior in a real Windows environment, not WorkBuddy native-hook
13
+ support. The WorkBuddy version and model were not recorded. This summary does
14
+ not represent a new maintainer-run WorkBuddy trial.
15
+
16
+ ## Confirmed findings and regressions
17
+
18
+ | Finding | Resulting behavior | Regression |
19
+ |---|---|---|
20
+ | Known destructive vocabulary disappeared under a mismatched dialect; `rm -rf .` became `ALLOW_NOOP` under `cmd` | The unparsed destructive segment becomes non-compensable `UNKNOWN`, producing `BLOCK_UNDETERMINABLE_EFFECT` | [Core CLI tests](https://github.com/mokuyoaxis/agent-guard/blob/main/tests/test_delete.py), `CheckCLI.test_cmd_dialect_cannot_turn_rm_root_delete_into_noop` |
21
+ | Windows target separators could be consumed or handled differently depending on the classifier host OS | Supported Windows-native targets normalize consistently; actual target fixtures relocate instead of falling through as a no-op | [Dialect tests](https://github.com/mokuyoaxis/agent-guard/blob/main/tests/test_dialects.py), `DefaultPathUnchanged`; [CLI tests](https://github.com/mokuyoaxis/agent-guard/blob/main/tests/test_delete.py), `WindowsVerbNoDialect` |
22
+
23
+ The reporter's [final correction](https://github.com/mokuyoaxis/agent-guard/issues/7#issuecomment-5857694703)
24
+ narrows the second finding: matching `del` with cmd or `Remove-Item` with
25
+ PowerShell already worked. A missing target correctly produces a no-op, so
26
+ regressions must create the target and preserve the exact command bytes.
27
+
28
+ The same report observed working quarantine relocation, manifest and audit
29
+ records, and restoration with content intact. The resulting
30
+ [Windows Core CI job](https://github.com/mokuyoaxis/agent-guard/blob/main/.github/workflows/ci.yml) covers selected dialect,
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.
33
+
34
+ ## Withdrawn redaction finding
35
+
36
+ The original third finding was
37
+ [withdrawn](https://github.com/mokuyoaxis/agent-guard/issues/7#issuecomment-5857658162).
38
+ Git Bash input construction had altered backslashes and a newline before the
39
+ payload reached the scanner. Direct Python subprocess input confirmed the
40
+ existing Windows path detection and redaction.
41
+
42
+ The candidate added an exact-byte synthetic-path regression in
43
+ [test_exfil_sanitize.py](https://github.com/mokuyoaxis/agent-guard/blob/main/tests/test_exfil_sanitize.py),
44
+ `FormatPreservation.test_native_windows_user_path_uses_exact_bytes_and_sanitizes`.
45
+ This is an input-contract regression, not a third confirmed exfil fix.
46
+
47
+ ## Evidence boundary
48
+
49
+ This feedback supports Windows Core/CLI evaluation and the two resulting
50
+ fixes. It does not establish a WorkBuddy adapter, mandatory interception of
51
+ WorkBuddy tools, all Windows command execution, or protection against an
52
+ agent with equal OS privileges. Personal host paths and unrelated local
53
+ configuration are omitted from this summary.
@@ -12,11 +12,11 @@ acted as the forward-test agent inside its own session
12
12
  **Platform:** Windows 10.0.26200 (win32), Python 3.13.15, git 2.55.0.windows.4, Bash via
13
13
  Git Bash (POSIX shell)
14
14
 
15
- ## Executive summary
15
+ ## Assessment
16
16
 
17
17
  agent-guard `v0.1.1` did **not** work on Windows out of the box: the Python core
18
- uses `os.uname()`, which does not exist on win32, and because the audit log is
19
- the durability pillar, every mutation failed closed — `safe_delete.py` blocked
18
+ uses `os.uname()`, which does not exist on win32. The required audit write
19
+ therefore failed, and every mutation failed closed — `safe_delete.py` blocked
20
20
  **all** deletions and `restore.py` raised `module 'os' has no attribute
21
21
  'uname'`. The test suite scored 79/84.
22
22
 
@@ -30,12 +30,12 @@ ZCode's `process`-type hook semantics.
30
30
 
31
31
  One ZCode integration property could not be exercised in the original run
32
32
  session (project-scope hooks load at session start), so the workspace trust was
33
- granted and a **trusted live fire was completed in a follow-up session**: the
33
+ granted and a **hook test ran in a separate trusted session**: the
34
34
  hook intercepted a real destructive command, surfaced its ASK decision as a
35
35
  ZCode permission prompt, audited the verdict, and executed only after human
36
36
  approval — confirming that ZCode accepts the adapter's
37
37
  `hookSpecificOutput` JSON schema. One significant ZCode-side caveat was found
38
- in the same live pass: clicking **"Always allow" (Approved for this project)**
38
+ in the same test: clicking **"Always allow" (Approved for this project)**
39
39
  on that prompt saves a project permission rule that makes ZCode skip the
40
40
  PreToolUse hook entirely for subsequent Bash commands — including commands the
41
41
  guard would hard-BLOCK. agent-guard itself behaved correctly at every point;
@@ -65,7 +65,7 @@ hostile-agent security boundary.
65
65
  with stderr fed back to the model). The model decided the cleanup
66
66
  strategy and responded to guard feedback without prior knowledge of
67
67
  expected verdicts.
68
- 6. A live-fire attempt of the real hook inside the running session, with ZCode
68
+ 6. A real-hook test inside the running session, with ZCode
69
69
  log analysis to explain the outcome.
70
70
 
71
71
  No source files were modified during behavioral testing. All destructive
@@ -132,10 +132,10 @@ machine running Core and pins them in a focused Windows CI job.
132
132
  trusted — installation must precede the session, and trust must be granted
133
133
  once. Any ZCode setup guide for agent-guard must state both.
134
134
 
135
- ### Trusted live fire (follow-up session, post-trust)
135
+ ### Hook test after workspace trust (follow-up session)
136
136
 
137
137
  With trust granted, the same session that could not fire the hook earlier was
138
- followed by a live pass. The model submitted a real destructive compound
138
+ followed by a hook test. The model submitted a real destructive compound
139
139
  command (`mkdir -p <fixture>/build && echo payload > ... && rm -rf <fixture>`)
140
140
  through its own Bash tool:
141
141
 
@@ -230,7 +230,7 @@ predict — the audit trail (`compensations: []`) made the outcome verifiable.
230
230
  ## Remaining matrix expansion
231
231
 
232
232
  - Behavior of the hook under permission modes where no project allow rule
233
- exists (this report's live pass ran under a saved "Approved for this
233
+ exists (this report's hook test ran under a saved "Approved for this
234
234
  project" rule; hook firing for every Bash call in rule-free sessions is
235
235
  inferred from the trust-gate session, not yet exhaustively measured).
236
236
  - Additional model families per harness; non-minimal compositions.
@@ -34,6 +34,48 @@ bypass. Therefore:
34
34
  | 7 | Destructive restore | Restore refuses overwrites without explicit human `--force`; all restores audited | Low |
35
35
  | 8 | Quarantine bloat turns `.agent-trash` into a liability (exfil via packaging, disk exhaustion) | Existing `.gitignore` or `.git/info/exclude`; `status.py` exposes size; 30-day/5-GiB soft eligibility with explicit audited purge | A human or scheduler must execute purge; audit is retained |
36
36
 
37
+ ## guard-lab diagnostic boundary
38
+
39
+ `guard-lab` introduces synthetic bait for controlled experiments; it does not
40
+ upgrade the enforcement boundary above. Its assets are disposable markers and
41
+ the integrity of a single run's evidence, not real credentials.
42
+
43
+ | Vector | MVP treatment | Residual risk |
44
+ |---|---|---|
45
+ | Tested agent invokes the fake Lab | Stub can only notify a run-specific loopback endpoint and return fixed text | Contact shows invocation, not intent or compromise |
46
+ | Tested agent reads a marker | Only an explicitly selected input/output can be scanned for that marker | Ordinary file reads and background indexing remain invisible |
47
+ | Snapshot calibration includes synthetic sources | Exact fixture members and four markers are validated at a bounded `127.0.0.1` sink; the body is discarded | Inclusion is not syscall-level read telemetry, and loopback receipt is not external exfiltration |
48
+ | Observer fails or evidence is changed | Positive control, control-file hash, event hash chain; unhealthy evidence becomes `INCONCLUSIVE` | Same-UID attacker can rewrite data and hashes |
49
+ | Harness sends data elsewhere | No external callback is used by default | Loopback contact cannot prove remote exfiltration |
50
+ | Harness sidecar bypasses tool hooks | General file reads and the external boundary remain `UNSUPPORTED` | Existing PreToolUse adapters cannot mediate activity that never becomes an agent tool call |
51
+ | Model recognizes the honeypot | Per-run markers, separate clean/positive cases, multiple bait shapes and short windows | A sufficiently informed or controller-aware adversary can selectively behave |
52
+ | Tested agent finds the controller | Fixture omits controller paths/tokens; user is told to expose only the fixture | Process/filesystem access under the same OS identity can still discover it |
53
+ | A quiet or mismatched run is presented as mitigation | Attack probes distinguish exposure from calibration; `compare` requires an effective unguarded baseline and matching protocol/task/trial identity | Harness, model, guard state, task delivery, and equality of unrelated host settings are not independently bound; one matched task does not generalize |
54
+ | A failed host run looks quiet and is credited as protection | Manual real-model reports require a create-once `HOST_RESULT=COMPLETED`; failed, timed-out, missing, or malformed results are inconclusive | Completion is user-declared; Lab does not authenticate or fully parse arbitrary host transcripts |
55
+ | A mixed harness transcript is mislabeled as model output | Documentation requires role/channel separation before scanning; reports disclose that scan input and stage are user-selected | Generic Lab does not authenticate vendor-specific transcript provenance |
56
+
57
+ The Lab controller is user-facing and is not an agent Skill. Never place real
58
+ secrets or irreplaceable work in its fixture. See [guard-lab](guard-lab.md) for
59
+ the exact observation and report semantics.
60
+
61
+ ## Experimental DSH text-read redaction
62
+
63
+ The default-off [native read prototype](test-report-dsh-read-redaction.md)
64
+ mediates complete text-read results in reviewed, artifact-pinned local-FS and
65
+ DSH `0.2.0-rc.2` sandbox-FS compositions; see the
66
+ [current review](test-report-release-readiness-0.2.3.md). It
67
+ uses Core patterns, replaces structured values and regenerates model content
68
+ and presentation metadata. Its actual AgentLoop/JSONL probe uses synthetic
69
+ streams and establishes no real-model L2 mitigation result.
70
+
71
+ The controller worker is trusted local Python code fed through bounded stdin;
72
+ it reads no target file and is independent of the model-facing shell executor.
73
+ Other plugins and the OS identity remain trusted. Arbitrary custom/later
74
+ finalizers, PTC, early events, call arguments, unreviewed providers and other
75
+ tool results are outside its scope. Complete-read restrictions withhold
76
+ pagination and truncation rather than certifying partial context. This adds
77
+ no general file-read telemetry or external-network containment.
78
+
37
79
  ## What would upgrade this to a security boundary
38
80
 
39
81
  Real containment requires enforcement below the agent's privilege level:
package/guard_lab.py ADDED
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env python3
2
+ """Offline synthetic honeytoken lab for Agent Guard."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import sys
7
+
8
+ from core.lab import cli_main, observer_cli_main
9
+
10
+
11
+ if __name__ == "__main__":
12
+ if len(sys.argv) > 1 and sys.argv[1] == "_observe":
13
+ raise SystemExit(observer_cli_main(sys.argv[2:]))
14
+ raise SystemExit(cli_main(sys.argv[1:]))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.3-rc1",
3
+ "version": "0.2.3",
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",
@@ -13,6 +13,7 @@
13
13
  "bin": {
14
14
  "agent-guard-doctor": "./doctor.py",
15
15
  "agent-guard-live-sentinel": "./live_sentinel.py",
16
+ "agent-guard-lab": "./guard_lab.py",
16
17
  "agent-guard-check": "./skills/delete-guard/scripts/check.py",
17
18
  "agent-guard-safe-delete": "./skills/delete-guard/scripts/safe_delete.py",
18
19
  "agent-guard-restore": "./skills/delete-guard/scripts/restore.py",
@@ -22,8 +23,8 @@
22
23
  "agent-guard-config-view": "./skills/exfil-guard/scripts/view.py"
23
24
  },
24
25
  "scripts": {
25
- "test": "python3 -m unittest discover tests -v && node tests/test_dsh_adapter.mjs",
26
- "test:dsh": "node tests/test_dsh_adapter.mjs",
26
+ "test": "python3 -m unittest discover tests -v && node tests/test_dsh_adapter.mjs && node tests/test_dsh_read_result.mjs",
27
+ "test:dsh": "node tests/test_dsh_adapter.mjs && node tests/test_dsh_read_result.mjs",
27
28
  "prepublishOnly": "npm test"
28
29
  },
29
30
  "files": [
@@ -33,6 +34,7 @@
33
34
  "docs",
34
35
  "doctor.py",
35
36
  "live_sentinel.py",
37
+ "guard_lab.py",
36
38
  "LICENSE",
37
39
  "CONTRIBUTING.md",
38
40
  "README.md",
@@ -42,7 +44,7 @@
42
44
  ],
43
45
  "dsh": {
44
46
  "engines": {
45
- "dsh": "0.1.5-rc.1"
47
+ "dsh": "0.1.5-rc.1 || 0.2.0-rc.2"
46
48
  },
47
49
  "bundle": {
48
50
  "patch": "./adapters/dsh/cordis.patch.yml"
@@ -51,7 +53,8 @@
51
53
  "keywords": [
52
54
  "agent-guard", "ai-agents", "coding-agents", "agent-skills",
53
55
  "llm-tools", "reliability", "recovery", "destructive-actions",
54
- "redaction", "quarantine", "audit", "git", "safety",
56
+ "redaction", "quarantine", "audit", "honeytoken",
57
+ "prompt-injection-testing", "git", "safety",
55
58
  "deepseek-harness", "dsh", "dsh-plugin", "cordis"
56
59
  ],
57
60
  "license": "MIT",
@@ -25,8 +25,7 @@ enforces and how to work with it productively. The four pillars:
25
25
 
26
26
  ## The one rule
27
27
 
28
- **Prefer `safe_delete` over `rm`. It is not slower for you - it is the
29
- supported path.**
28
+ **Prefer `safe_delete` over `rm`.** It applies the guard's recovery policy.
30
29
 
31
30
  ```bash
32
31
  # delete files/dirs/globs - they are quarantined, not destroyed:
@@ -87,7 +86,7 @@ that an error means no filesystem change occurred. A durable
87
86
  After a human veto, the session runs with narrowed powers: explicit
88
87
  single-file deletes inside the workspace still work (quarantined as usual);
89
88
  recursive deletes, globs, and destructive git operations are refused. Only a
90
- human can restore NORMAL. If a task genuinely requires more, say so plainly
89
+ human can restore NORMAL. If a task requires more, say so plainly
91
90
  and ask.
92
91
 
93
92
  ## Regenerable artifacts
@@ -44,6 +44,11 @@ python3 <repo>/skills/exfil-guard/scripts/sanitize.py --channel file-write < dra
44
44
  never writes, never rewrites, and never prints the match. Exit codes are the
45
45
  contract: `0` allow/sanitize, `2` block, `3` ask, `1` error.
46
46
 
47
+ `sanitize.py` uses the same exit codes and emits no payload on ASK/BLOCK or
48
+ error. Both CLIs bound stdin while reading (4 MiB by default), support UTF-8,
49
+ and resolve the same default workspace/host-side mode. The first-byte wait is
50
+ bounded; it is not a deadline for a producer that has already started writing.
51
+
47
52
  ## Safe config view
48
53
 
49
54
  When you need to learn a JSON or dotenv config's shape, use the explicit
@@ -74,7 +79,7 @@ intercept a harness's ordinary file-read tool.
74
79
  | `ASK` (`ASK_SECRET_EMISSION` / `ASK_PATH_EMISSION`) | the channel cannot be rewritten and cannot be taken back (a terminal transcript cannot be un-printed) | stop and ask a human; do not silently proceed |
75
80
  | `BLOCK` (`BLOCK_SECRET_EMISSION` / `BLOCK_PATH_EMISSION`) | the channel is immutable or remote history (commit message, push payload) | **do not retry.** Remove the value and redo the message/commit |
76
81
  | `BLOCK_SECRET_SOURCE_DUMP` | the payload reads a whole secret store (`cat .env`, `printenv`) whose content the guard never saw | stop; emit an explicit, reviewed value instead |
77
- | `BLOCK_OUTPUT_UNSCANNABLE` | the payload was never scanned (too large, non-ASCII, unknown channel, scanner error) | an unscanned egress is not a clean egress. Do not route around it |
82
+ | `BLOCK_OUTPUT_UNSCANNABLE` | the payload was never scanned (too large, unknown channel, scanner error) | an unscanned egress is not a clean egress. Do not route around it |
78
83
 
79
84
  A `BLOCK` is not an obstacle to work around. Re-encoding a payload, splitting
80
85
  a secret across lines, or piping through a tool the guard does not scan is a
@@ -84,10 +89,17 @@ violation of the authorization pillar and is recorded in the audit log.
84
89
 
85
90
  The guard deliberately does not rewrite your payload - you hold it. Apply
86
91
  the plan back to front so offsets stay valid, or let `sanitize.py` do it.
87
- Redaction **preserves format**: `sk-proj-Ab…` becomes `sk-proj-<REDACTED>`
92
+ Redaction **preserves format**: `sk-proj-Ab…` becomes `sk-<REDACTED>`
88
93
  (so a reviewer can still see *which kind* of credential leaked), and a host
89
94
  path becomes `<PATH>`.
90
95
 
96
+ An external `--plan` is checked against a fresh scan, including offsets,
97
+ placeholders and any supplied rule metadata. A partial, stale or arbitrary plan
98
+ is refused; the rewritten payload must pass another scan. A plan made with
99
+ checker-specific mode/path overrides still has to satisfy current sanitizer
100
+ policy. URI passwords use `<REDACTED>` while retaining scheme/account/host;
101
+ this is credential redaction, not network-topology hiding or an editable URI.
102
+
91
103
  If you decline to apply a plan on a rewritable channel, the API contract is
92
104
  "you were told": the audit records `sanitize-declined`. That is a choice
93
105
  with a record, not a default.
@@ -95,16 +107,34 @@ with a record, not a default.
95
107
  ## Value-free detection (why `echo "$TOKEN"` is caught)
96
108
 
97
109
  The guard detects a secret *reference* without ever reading the secret. It
98
- classifies a variable's **name** (`*KEY*`, `*TOKEN*`, `*SECRET*`,
99
- `*PASSWORD*`, `*CRED*`, `*AUTH*`) and a secret-store **file name**
110
+ classifies a variable's **name** by complete credential components (`KEY`,
111
+ `TOKEN`, `SECRET`, `PASSWORD`, `CRED`, `AUTH`, including underscores and
112
+ camelCase), and a secret-store **file name**
100
113
  (`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, …), never a value.
101
114
  This keeps this scanner from creating a second value copy; it does not
102
115
  certify unrelated CLI output or existing audit records as secret-free.
103
116
 
104
117
  Consequence you will notice: if `$OPENAI_API_KEY` actually holds `"test"`,
105
- the guard still ASKs. That is intentional. The cost of a false ASK is one
106
- keystroke; the cost of a false ALLOW is permanent. Do not attempt to
107
- "resolve" the variable to reduce prompts.
118
+ the guard still BLOCKs its uninspectable source reference. Do not attempt to
119
+ resolve the variable to soften that decision. `MONKEY`/`API_KEYBOARD` are
120
+ ordinary names, and terminal `COUNT`/`LENGTH`/`ENABLED` denotes metadata.
121
+ Public-key names retain conservative handling pending separate review.
122
+ Bare lower/title-case `key` is too ambiguous to classify without an explicit
123
+ environment reference; uppercase `KEY` and qualified `apiKey` remain protected.
124
+
125
+ Placeholder exemptions require a whole documented shape or an exact static
126
+ example; incidental words inside random credentials do not exempt them.
127
+ Vendor credentials adjacent to CJK prose are scanned with original offsets.
128
+ GitHub installation credentials support both classic and `ghs_APPID_JWT`
129
+ shapes, with complete redaction of long tokens. These are shape facts, not
130
+ authentication or token-validity checks. See [rules.md](references/rules.md).
131
+
132
+ PyPI token bodies follow the documented `pypi-` scanner shape and are redacted
133
+ in full, including long bodies. AWS access-key IDs use AKIA/ASIA; IAM resource
134
+ IDs have separate types and do not match that credential rule. Generic JWT
135
+ headers require a nonempty ASCII string `alg`. Public-key variable names and
136
+ the broad legacy `sk-` shape retain conservative handling where their purpose
137
+ or complete format has not been established.
108
138
 
109
139
  ## Path rules
110
140