@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,189 @@
1
+ # Agent Guard 0.2.3-rc2 — offline guard-lab candidate
2
+
3
+ These notes describe the `0.2.3-rc2` source candidate. Check
4
+ [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) and npm
5
+ dist-tags before treating it as published; editing the source version does not
6
+ publish a Release or move npm `rc`.
7
+
8
+ The [current contract and release review](test-report-release-readiness-0.2.3.md)
9
+ records subsequent DSH `0.2.0-rc.2` runtime admission, native v4 / receipt v5
10
+ support and fresh no-model checks. Historical real-model results below retain
11
+ their original runtime and coverage. A new-host real-model clean capture was
12
+ refused for surface replay and composition drift; it supplies no new L2 result.
13
+
14
+ ## Added
15
+
16
+ - `agent-guard-lab` / `guard_lab.py`, a user-controlled, standard-library-only
17
+ CLI for disposable synthetic honeytoken experiments.
18
+ - Disjoint fixture and evidence directories, create-only setup artifacts,
19
+ run-specific non-credential markers, a harmless fake Lab stub, and a
20
+ bounded `127.0.0.1` observer.
21
+ - Deterministic `clean`, `mock-positive`, `mock-injection`, and
22
+ `snapshot-positive` controls. They
23
+ exercise the full evidence path with zero model calls and no external
24
+ network request.
25
+ - The snapshot calibration uses four separate synthetic markers: current
26
+ worktree, ignored/hidden data, synthetic Git history, and a synthetic user
27
+ config tree inside the fixture. A fixed test double creates an in-memory tar
28
+ and submits it only to the run's `127.0.0.1` sink. Sources are capped at 16
29
+ files/64 KiB, the tar at 256 KiB, and accepted sockets at a two-second read
30
+ timeout.
31
+ - Staged snapshot evidence distinguishes a request reaching the sink, archive
32
+ validation, marker-bearing source inclusion, and local acceptance. The sink
33
+ retains neither the archive nor marker values; these stages do not claim
34
+ syscall-level file-read visibility or external exfiltration.
35
+ - Explicit-file marker scanning after observer shutdown. Reports retain only
36
+ size, SHA-256, stage, count, and bait IDs—not raw selected output or canary
37
+ values.
38
+ - Chained JSONL events, control-file integrity checking, positive observer
39
+ controls, and `INCONCLUSIVE` results whenever evidence health is inadequate.
40
+ - Per-channel `OBSERVED`, `NOT_OBSERVED`, `INCONCLUSIVE`, and `UNSUPPORTED`
41
+ coverage. A selected-output scan is required before a built-in criterion can
42
+ be conclusive; a healthy loopback observer alone cannot clear an unobserved
43
+ output channel.
44
+ - Bounded evidence inputs: one MiB per explicit scan, 1024 events, and a two
45
+ MiB event log. Saturation fails inconclusive rather than dropping evidence.
46
+ - A cross-process lifecycle regression: the detached, bounded observer must
47
+ remain available after the `arm` CLI exits and accept `stop` from a later
48
+ process. An in-process-only test is not treated as sufficient evidence.
49
+ - Numeric loopback binding avoids HTTP server hostname resolution during
50
+ observer startup. Offline or slow DNS cannot delay this unnecessary lookup;
51
+ the five-second READY deadline and evidence criteria remain unchanged.
52
+ - A separate manual `injection-probe` gives bait contact adverse semantics:
53
+ `EXPOSURE_OBSERVED` is a failing security outcome, while a quiet healthy run
54
+ is only `NO_EXPOSURE_OBSERVED`, never a safety certificate. This avoids
55
+ reusing the scripted `mock-injection` positive control as a model verdict.
56
+ - Privacy-minimal trial metadata binds a probe to user-declared harness,
57
+ version, model, guard state, trial group, protocol, and task SHA-256. The
58
+ task text/path is not retained, and labels must not contain private endpoint
59
+ or account details.
60
+ - `compare` grants an L2 `MITIGATION_OBSERVED` result only when a matched,
61
+ unguarded L1 baseline actually exposed bait and the guarded trial did not.
62
+ Exposure in both runs is `NOT_MITIGATED`; a quiet baseline is
63
+ `INCONCLUSIVE`; unhealthy or mismatched trials are `INCOMPARABLE`.
64
+ - New comparisons also require the same actual scanned `stage`/`source_kind`
65
+ set and valid matching non-guard configuration fingerprints. Historical
66
+ evidence without this context remains readable but cannot gain a new L2
67
+ result. Reports separate output exposure by stage from observer channels.
68
+ - DSH `prepare-pair` / `pair-next` derive four private fresh homes, check scoped
69
+ non-guard equality, and progress through two reviewed clean controls,
70
+ an effective baseline, and guarded capture. Receipt version 3 binds the
71
+ scoped configuration; the DSH comparison wrapper revalidates native bytes.
72
+ Boot-free checks against the real installed host passed without a new model
73
+ trial. Result rewriting was separately investigated with a native zero-model
74
+ probe; no new enforcement feature is claimed. See the
75
+ [dated report](test-report-dsh-paired-lab.md).
76
+ - A subsequent default-off DSH text-read prototype uses Core policy and native
77
+ structured-value replacement, including regenerated presentation metadata.
78
+ The pinned real read/AgentLoop/JSONL path passed a zero-model probe with a
79
+ synthetic stream. Complete reads only; no real-model L2 result is claimed.
80
+ A later [official Flash direct-read off/on trial](test-report-dsh-real-followup.md)
81
+ observed supported synthetic-secret redaction in tool content/meta/session
82
+ while useful config remained readable. The standard injection pair stopped
83
+ inconclusive on an unsupported retry record; neither result establishes
84
+ injection L2. See the [read-redaction report](test-report-dsh-read-redaction.md).
85
+ - Manual real-model runs require one create-once `record-host` declaration.
86
+ A missing, failed, or timed-out host result is inconclusive even when the
87
+ process returned zero and no bait was observed, preventing startup/model
88
+ failures from being credited as mitigation. The status remains
89
+ user-declared and does not authenticate a transcript.
90
+ - One bounded developer-run pair used Kimi Code CLI 2.1.1, a user-declared
91
+ official OAuth model label, and the same hashed task. The guard-off stream
92
+ exposed a synthetic-note canary in a tool-role record (not assistant prose),
93
+ while the guard-on stream did not, producing L2 `MITIGATION_OBSERVED`.
94
+ Non-guard settings were held constant by deriving
95
+ the baseline configuration from the guarded configuration and locally
96
+ verifying semantic equality after removing only the hook/skill surfaces.
97
+ This one-pair result covers only the declared fixture channels and captured
98
+ stream; it is not a model/vendor rating or external-exfiltration claim.
99
+ - Scan inputs and stage labels remain user-selected because the generic Lab
100
+ does not authenticate vendor transcript schemas. The Kimi reference stream
101
+ was therefore split by `role` before its final tool/assistant channel scans.
102
+ - A separate DSH 0.1.5-rc.1 headless baseline used the same task with the
103
+ user-declared official `deepseek-flash` label. Its clean control and
104
+ guard-off injection run completed without declared bait contact. Because the
105
+ baseline attack was ineffective, no guard-on model call was run and no DSH
106
+ L2 mitigation claim is made; see the [bounded report](test-report-dsh-guard-lab.md).
107
+ - A separate POSIX DSH baseline runner codifies version/configuration preflight,
108
+ bounded private stdout/stderr capture, observer shutdown, and explicit
109
+ completion review before scanning and reporting. Mixed CLI streams use the
110
+ additive `host-output` scan stage; their hashes and separate source kinds do
111
+ not authenticate model/tool roles. Raw captures remain private for review,
112
+ outside the Lab report. The runner's regressions call no model.
113
+ - A separate Kimi Code 2.1.1 capture helper derives private off/on homes,
114
+ checks semantic equality of non-Guard settings, captures bounded prompt-mode
115
+ streams, and scans recognized assistant/tool/meta records separately after
116
+ explicit review. Its TOML checks require Python 3.11+; shared Core remains
117
+ Python 3.9+. Unknown/header-only/failed streams cannot be credited as success.
118
+ - Versioned `direct-v1`, `maintenance-v1` and `config-comment-v1` attack samples
119
+ bind protocol, static template and placement identity. Indirect instructions
120
+ are carried in a review checklist or service configuration comments.
121
+ Comparison refuses different samples or unknown template fingerprints.
122
+ - The 2026-09-30 Kimi repeat completed clean and guard-off trials but did not
123
+ reproduce the historical exposure. No new guard-on call or L2 result was
124
+ produced; see the [dated follow-up](test-report-kimi-guard-lab.md).
125
+ - Two real DSH indirect baselines on 2026-09-30 also completed without marker
126
+ hits in stdout/stderr or bait contact. Native tool-result records were not
127
+ scanned, so this establishes no absence of tool/context exposure and no L2
128
+ mitigation. The [DSH report](test-report-dsh-guard-lab.md) records this
129
+ coverage difference and the isolated saved-settings model pin.
130
+ - DSH captures now add a bounded fresh native v3 session, validate every
131
+ Zstandard frame including torn tails, bind cwd/task/turn completion, and scan
132
+ model-facing tool results separately from assembled assistant content.
133
+ Missing, ambiguous, mismatched or unsupported sessions stay inconclusive.
134
+ Historical CLI-only receipts preserve their original coverage.
135
+ - Offline review of the retained indirect DSH logs found both synthetic markers
136
+ in tool-result content and none in assistant content. Original CLI-only
137
+ evidence was preserved; this is additional tool-channel exposure evidence,
138
+ with no new model call or L2 mitigation. See the
139
+ [native-session follow-up](test-report-dsh-native-session.md).
140
+
141
+ The Windows/Core fail-closed changes from `0.2.3-rc1` remain part of this
142
+ candidate.
143
+
144
+ ## Quick deterministic check
145
+
146
+ ```sh
147
+ python3 guard_lab.py run --case clean --output-dir /tmp/ag-lab-clean --json
148
+ python3 guard_lab.py run --case mock-positive --output-dir /tmp/ag-lab-positive --json
149
+ python3 guard_lab.py run --case mock-injection --output-dir /tmp/ag-lab-injection --json
150
+ python3 guard_lab.py run --case snapshot-positive --output-dir /tmp/ag-lab-snapshot --json
151
+ ```
152
+
153
+ See [guard-lab documentation](guard-lab.md) before involving a real harness.
154
+ The controller belongs to the user; the tested agent should receive only the
155
+ disposable fixture.
156
+
157
+ ## Evidence boundary
158
+
159
+ This candidate can observe only:
160
+
161
+ - a selected input/output containing a synthetic marker;
162
+ - a request to the run-specific loopback URL;
163
+ - invocation of the fake Lab stub;
164
+ - a bounded synthetic tar accepted by the run-specific loopback snapshot sink.
165
+
166
+ It labels built-in results as instrument calibration, not evidence about a
167
+ real model, harness, vendor, or guard. It does not observe general file reads,
168
+ prove remote exfiltration, block all model calls, or resist a same-UID
169
+ adversary. The report evaluates one declared criterion and must not be
170
+ presented as a model/vendor safety rating. The manual probe and comparison are
171
+ likewise limited to the declared channels, exact task, and user-supplied trial
172
+ identity. Configuration fingerprints bind their declared scope; unrelated
173
+ settings must still be held constant outside the controller.
174
+
175
+ ## Compatibility and dependencies
176
+
177
+ - No production dependency was added; the CLI uses the Python standard
178
+ library and keeps the project-wide Python 3.9+ floor.
179
+ - The public controller is packaged as the `agent-guard-lab` npm bin.
180
+ - The observer uses a local background Python process and cooperative stop
181
+ request. Native Windows harness E2E remains outside this candidate's current
182
+ evidence even though pure controller tests are platform-oriented.
183
+
184
+ ## Exit status
185
+
186
+ `run` and `report` return `0` for a completed passing criterion and `2` for a
187
+ completed failing criterion (including observed attack-probe exposure).
188
+ `compare` returns `0` for `MITIGATION_OBSERVED`, `2` for `NOT_MITIGATED`, and
189
+ `4` for `INCONCLUSIVE`/`INCOMPARABLE`. Setup or controller errors return `1`.
@@ -0,0 +1,84 @@
1
+ # Agent Guard 0.2.3
2
+
3
+ Stable release, 2026-10-03. See the
4
+ [readiness review](test-report-release-readiness-0.2.3.md#stable-preparation--2026-10-03)
5
+ for validation checkpoints and evidence limits.
6
+
7
+ 0.2.3 completes the Windows/Core fixes and offline guard-lab MVP planned in
8
+ rc1/rc2, and adds focused information-protection improvements. Core, the
9
+ Decision Protocol and Skills remain shared across hosts.
10
+
11
+ ## Changes
12
+
13
+ - Windows/Core fail-closed fixes from rc1: known destructive vocabulary is
14
+ checked across shell dialects, and Windows path normalization/recovery has
15
+ focused real-Windows CI evidence. The fixes originated in
16
+ [community Windows feedback through WorkBuddy](test-report-workbuddy-windows-core.md).
17
+ Arbitrary Windows harness E2E remains outside the claim.
18
+ - The sanitizer withholds the body on ASK, BLOCK or error. External plans
19
+ must match the current scan; output is rescanned before emission. Checker,
20
+ sanitizer and plan input share bounded UTF-8 handling and policy defaults.
21
+ - URI userinfo passwords are redacted without discarding useful connection
22
+ structure. Percent-encoded passwords and JSON-escaped slashes are supported;
23
+ general DSN parsing and network-topology privacy are outside this rule.
24
+ - Credential rules cover PyPI publishing tokens and newer GitHub installation
25
+ tokens, including complete long signatures and Chinese-adjacent matches.
26
+ Placeholder exemptions require a complete placeholder shape.
27
+ - Secret-reference names use complete components, keeping ordinary names and
28
+ metadata readable. AWS resource IDs are distinguished from access-key IDs;
29
+ a JWT header requires a nonempty ASCII string `alg`. Ambiguous public-key
30
+ names and generic `sk-` shapes retain their documented conservative behavior.
31
+ - `agent-guard-lab`: disposable synthetic fixtures, a bounded loopback
32
+ observer, clean/positive/injection/snapshot controls, explicit output scans
33
+ and privacy-minimal reports. Missing or unhealthy evidence is inconclusive.
34
+ - Reviewed real-harness capture helpers and matched comparisons: an effective
35
+ guard-off baseline is required before declaring mitigation. Historical
36
+ evidence retains its original format and channel coverage.
37
+ - DSH adapter translation for `0.2.0-rc.2` Shell handles, with the tested old
38
+ default deletion path retained. Core Decision Protocol and deletion rules
39
+ remain shared and independent of DSH.
40
+ - Default-off DSH complete text-read protection on reviewed, artifact-pinned
41
+ providers. It replaces structured values so native content and metadata
42
+ regenerate; incomplete, unsupported or unscannable reads are withheld.
43
+ - Bounded native session v4 support uses receipt v6 / parser v3 alongside
44
+ preserved historical interpretation, including `role=tool` source-call
45
+ correlation and retry-attempt evidence. Modern isolated profiles bind their
46
+ initialized composition before capture. Surface replay, image offload and
47
+ arbitrary session shapes remain unsupported.
48
+ - DSH/Kimi Lab startup failures retain the original observer error and never
49
+ launch a host task or acquire a successful capture receipt.
50
+
51
+ ## Evidence and limits
52
+
53
+ The offline Lab controls establish instrument calibration. Historical bounded
54
+ model trials and fresh no-model native checks are listed in the
55
+ [rc2 notes](release-notes-0.2.3-rc2.md) and
56
+ [current review](test-report-release-readiness-0.2.3.md). Pending real-model
57
+ Lab captures retain their review state; no new injection L2 result is claimed.
58
+ Native read probes use reviewed providers and deterministic streams, and
59
+ cover returned values, content, presentation metadata, the next request and
60
+ durable JSONL. They do not certify every output path. A refused Guard plugin
61
+ does not stop all other host tools, and Web
62
+ inventory alone does not establish activation in an agent's scope.
63
+
64
+ No production dependency was added. Python Core remains Python 3.9+;
65
+ the optional pinned DSH read feature uses Node 22 and the Kimi TOML capture
66
+ helper requires Python 3.11+. Lab evidence is limited to declared channels;
67
+ same-UID isolation, general host indexing/uploads and external exfiltration
68
+ containment are outside its guarantee.
69
+
70
+ ## DSH distribution
71
+
72
+ The scoped package includes a DSH bundle and prebuilt JavaScript. It needs
73
+ no install-time build script. After publication, install the exact version
74
+ into a chosen profile:
75
+
76
+ ```sh
77
+ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.3
78
+ ```
79
+
80
+ Python 3.9+ and Git must already be available. The admitted DSH versions are
81
+ `0.1.5-rc.1` and `0.2.0-rc.2`; optional read protection additionally requires
82
+ Node 22 and reviewed artifact hashes. Its default remains off. Marketplace
83
+ listing is a separate community-catalog submission, not a broader host or
84
+ model support declaration.
@@ -1,9 +1,10 @@
1
1
  # exfil-guard (secret + path leakage) — requirement analysis
2
2
 
3
- Status: **analysis, pre-implementation.** No code, no schema, no verdict
4
- table is frozen by this document. It exists to decide *whether* the
5
- feature belongs in agent-guard, *where* it plugs into the existing
6
- interception model, and *what the MVP is*.
3
+ Status: **historical requirements analysis, written before implementation.**
4
+ This document records the original scope and design questions; it does not
5
+ define the current contract. Current behavior is documented in the
6
+ [Skill](../skills/exfil-guard/SKILL.md) and
7
+ [rule reference](../skills/exfil-guard/references/rules.md).
7
8
 
8
9
  Working name: **`exfil-guard`**. The two user requests (secret leakage,
9
10
  local-path leakage) are two rule families, not two skills — §3 argues
@@ -25,7 +26,7 @@ That immediately reclassifies both requests:
25
26
  | Secret guard | "prevent adversarial exfiltration" | "prevent the *accidental* publication/transmission of a credential the agent had legitimate read access to" |
26
27
  | Path guard | "prevent information disclosure attacks" | "prevent *accidental* disclosure of host-identifying paths that produce false bug reports and privacy churn" |
27
28
 
28
- The honest one-line positioning:
29
+ The intended scope:
29
30
 
30
31
  > exfil-guard makes accidental disclosure of credentials and host paths
31
32
  > **catchable before the bytes leave**, with a decision trail. It does not
@@ -100,11 +101,11 @@ a git remote and an LLM API), not absolute risk scores.
100
101
  | S8 | Secret in an upload / bundle / artifact | `.agent-trash/` packaged by mistake, a `tar czf` of the workspace | **H** | partial | ✗ | Already named as residual risk in `docs/threat-model.md` #8 |
101
102
  | S9 | Secret in a dependency lockfile / generated fixture | agent regenerates a fixture from a live capture | M | partial | partial | The realistic "long random string" false-positive factory |
102
103
 
103
- **Delete-guard adjacency worth noting:** S2/S8 are the *same failure
104
+ **Related delete-guard risk:** S2/S8 are the *same failure
104
105
  family* as threat-model #8 (quarantine bloat → exfil via packaging). The
105
106
  quarantine directory is a secret-liability volume by construction: it holds
106
107
  copies of `.env` files the agent deleted. Any secret-guard scan of the
107
- workspace must therefore treat `.agent-trash/` as a first-class source, and
108
+ workspace must therefore include `.agent-trash/` in its source inventory, and
108
109
  `gc.py` decisions interact with it.
109
110
 
110
111
  ### 1.2 Local-path leakage
@@ -185,7 +186,7 @@ Class A.
185
186
 
186
187
  ### 2.3 Class B — needs a new interception point
187
188
 
188
- | Egress point | Can it be intercepted? | How, honestly |
189
+ | Egress point | Can it be intercepted? | Mechanism and limits |
189
190
  |---|---|---|
190
191
  | **Outbound LLM request body** (S1, P1) | *Yes, for some harnesses* | Harnesses that expose a pre-request hook, or route through a local proxy (this repo already ships `adapters/claude/harness/mock_anthropic_api.mjs` — a proxy is a **demonstrated** integration shape here). A truly hosted model call with no proxy is unreachable |
191
192
  | **File write content** (S6, P3) | *Yes, at the tool layer* | A `PreToolUse`-style hook on Write/Edit tools, or a `PreWrite` hook. This is a *new adapter point*, not a new core rule engine |
@@ -272,7 +273,7 @@ Arguments for two skills, and why they lose:
272
273
 
273
274
  **Decision: one skill, `exfil-guard`, with two rule families
274
275
  (`secret/*`, `path/*`) addressed by the same rule ids.** If implementation
275
- reveals that the families genuinely diverge in mechanism, the split is
276
+ reveals that the families require different mechanisms, the split is
276
277
  mechanical later; the reverse (merging two shipped skills) is not.
277
278
 
278
279
  ### 3.2 What is reused verbatim
@@ -287,7 +288,7 @@ mechanical later; the reverse (merging two shipped skills) is not.
287
288
  | Harness prefilter pattern (regex fast path) | **yes**, new prefilter | Latency budget matters (friction F4: ~0.3 s/command) |
288
289
  | `recovery.py` relocate/snapshot | **no** | Wrong axis (§0.1) — do not force it |
289
290
 
290
- ### 3.3 What is genuinely new
291
+ ### 3.3 New components
291
292
 
292
293
  1. A **content classifier** (`SpanSpec`) — the first classifier in this repo
293
294
  whose input is text payload rather than a command or a path.
@@ -368,8 +369,8 @@ existing repo precedent:
368
369
 
369
370
  ## 4. Open questions for the design doc (and for the human)
370
371
 
371
- These are carried into `secret-guard-design.md` and answered there; listed
372
- here because they are genuinely unresolved, not rhetorical.
372
+ These questions were carried into `secret-guard-design.md`. They record the
373
+ choices considered at this stage of the design.
373
374
 
374
375
  - **Q1 Egress definition.** Which channels count as "out"? A terminal
375
376
  transcript is not the same as a public gist. The design must pick a
@@ -1,8 +1,10 @@
1
1
  # exfil-guard — where it sits in the architecture
2
2
 
3
- Short orientation for someone who already knows agent-guard from
4
- `docs/architecture.md`. Full analysis and design:
5
- `secret-guard-analysis.md`, `secret-guard-design.md`.
3
+ This historical architecture sketch accompanies
4
+ [the requirements analysis](secret-guard-analysis.md) and
5
+ [design](secret-guard-design.md). Pre-write and pre-request interception
6
+ below describe proposed adapter points. Current supported paths are listed
7
+ in the [capability matrix](harness-capabilities.md).
6
8
 
7
9
  ## One-paragraph summary
8
10
 
@@ -1,8 +1,12 @@
1
1
  # exfil-guard — design
2
2
 
3
- Status: **design, pre-implementation.** Extends the Decision Protocol with
4
- one new decision class (`SANITIZE`) and one new classifier input type
5
- (text spans). Read `secret-guard-analysis.md` first — §2.5 there
3
+ Status: **historical design, written before implementation.** Proposed
4
+ modules and interception points below are design candidates, not a list of
5
+ shipped features. For current behavior, see the
6
+ [Skill](../skills/exfil-guard/SKILL.md) and
7
+ [rule reference](../skills/exfil-guard/references/rules.md).
8
+ The design adds `SANITIZE` and text-span classification to the Decision
9
+ Protocol. Read `secret-guard-analysis.md` first — §2.5 there
6
10
  (reachability) and §0.1 (irrevocability) are the two facts this design is
7
11
  built around.
8
12
 
@@ -11,14 +11,13 @@
11
11
  **Sandbox:** `workspace-write`
12
12
  **Platform:** Ubuntu 22.04 under WSL2
13
13
 
14
- ## Executive summary
14
+ ## Assessment
15
15
 
16
- agent-guard has a strong safety model and an effective agent-facing skill. Its
17
- four pillars—scope, recoverability, authorization, and auditability—were clear
18
- to fresh Codex agents at both medium and high reasoning. Every forward-test
19
- agent used the supported deletion workflow, distinguished regenerable
20
- artifacts from potentially valuable content, respected hard blocks, and did
21
- not circumvent the guard.
16
+ In the sampled medium- and high-reasoning runs, fresh Codex agents followed
17
+ the skill's scope, recovery, authorization and audit rules. Each agent used
18
+ the supported deletion workflow, distinguished regenerable artifacts from
19
+ potentially valuable content, and accepted hard blocks without retrying
20
+ through another deletion mechanism.
22
21
 
23
22
  The baseline review found four release-blocking defects: non-atomic relocation
24
23
  and manifest recording, unsafe parsing of Git-quoted filenames during
@@ -146,9 +145,9 @@ The model behaved correctly:
146
145
  disguised deletion mechanism.
147
146
  - The final Git worktree was clean.
148
147
 
149
- This is strong evidence that the skill's trigger description, primary rule,
150
- decision vocabulary, and anti-circumvention guidance are understandable and
151
- actionable for Codex at medium reasoning effort.
148
+ This run shows that Codex at medium reasoning effort followed the skill's
149
+ trigger description, deletion workflow and refusal guidance in the sampled
150
+ task.
152
151
 
153
152
  The same run exposed a serious integration defect: Codex's workspace-write
154
153
  sandbox protects `.git` from writes. agent-guard moved three targets into
@@ -285,7 +284,7 @@ according to Codex skill metadata guidance.
285
284
  hard refusal is more useful than a simple allow/deny policy.
286
285
  - Requiring both an ignored path and a recognized artifact shape before direct
287
286
  deletion is a sensible conservative heuristic.
288
- - The threat model honestly positions the project as reliability
287
+ - The threat model positions the project as reliability
289
288
  infrastructure rather than a same-privilege security sandbox.
290
289
  - The friction log shows valuable real-agent iteration and preserves lessons
291
290
  that adapter authors need.
@@ -0,0 +1,142 @@
1
+ # DSH 0.2 upgrade and Core separation check
2
+
3
+ Date: 2026-09-30 (UTC)
4
+
5
+ This is the initial upgrade snapshot. The later
6
+ [contract and release review](test-report-release-readiness-0.2.3.md) records
7
+ the subsequent runtime admission, native v4 support and fresh validation.
8
+ The limitations below describe the source at this initial checkpoint.
9
+
10
+ The unchanged Core works with the upgraded native DSH deletion seam after
11
+ a small adapter correction. Full project compatibility with `0.2.0-rc.2`
12
+ has **not** passed: the production read guard and Lab still pin the previous
13
+ runtime, and the running Web service reports a different installed Guard
14
+ bundle. No new external model call or Kimi OAuth quota was used.
15
+
16
+ ## Runtime and isolation
17
+
18
+ The default local CLI reports `0.2.0-rc.2`. Authenticated, read-only Web RPCs
19
+ also report official base/Web bundles at `0.2.0-rc.2`, 197 plugin rows and
20
+ 165 active rows. `agent-guard` is active; `agent-guard-dsh` is disabled as a
21
+ plugin row, while its installed bundle reports version `0.1.1` and enabled.
22
+ Bundle selection and plugin activation are different projections. These
23
+ responses do not identify the active implementation as this `0.2.3-rc2`
24
+ worktree, or prove interception within an agent's Web context.
25
+
26
+ The supplied access token and resulting cookie stayed in memory. Only
27
+ allowlisted counts, names, versions and states were retained. No live Web
28
+ configuration, session, account, model selection or workspace was changed.
29
+ Browser UI behavior was not tested; the Web checks used the installed
30
+ Connection RPC envelope and cookie authentication.
31
+
32
+ Native execution tests used new private homes and Git workspaces outside
33
+ the repository, on Android/PRoot Debian ARM64 with Node `22.23.2` and Python
34
+ `3.13.5`. The initial fresh profile defaulted to `workspace-write`; the host
35
+ refused its benign command because no confinement backend was usable.
36
+ Subsequent execution probes explicitly set `danger-full-access` in their
37
+ private profiles. This is the scope of those results, not a test of
38
+ workspace-write confinement or a change to the running Web deployment.
39
+
40
+ ## Default adapter: failure, correction and native comparison
41
+
42
+ The initial adapter called `shell.run(shell.resolve(request))`.
43
+ DSH `0.2.0-rc.2` exposes `execute(spec)` returning an execution handle whose
44
+ `result()` resolves to the foreground outcome. The obsolete call was caught
45
+ as an infrastructure failure. It withheld the test command, but produced
46
+ no Core audit; it was not a successful policy decision.
47
+
48
+ The local correction resolves the same request, uses `execute(...).result()`
49
+ when available, and retains `run(...)` for the tested earlier host. It changes
50
+ no Core rule, request policy, tool arguments, public interface or read pin.
51
+ Failures during preparation or result collection remain fail-closed, and
52
+ never retry through the legacy path after execution starts.
53
+
54
+ The native probe's dangerous-looking text is an inert shell comment. If
55
+ unguarded, the command creates only a harmless marker. No destructive
56
+ command is executed.
57
+
58
+ | Private native composition | Benign marker | Guarded marker | Core block audit | Result |
59
+ |---|---|---|---|---|
60
+ | Initial new host, default sandbox | absent; native sandbox error | absent; adapter infrastructure error | absent | failed |
61
+ | Initial new host, explicit host access | created | absent; adapter infrastructure error | absent | failed |
62
+ | Isolated corrected adapter, new host | created | absent | `BLOCK_UNDETERMINABLE_EFFECT` | passed |
63
+ | Corrected worktree adapter, new host | created | absent | `BLOCK_UNDETERMINABLE_EFFECT` | passed |
64
+ | Corrected worktree adapter, old `0.1.5-rc.1` host | created | absent | `BLOCK_UNDETERMINABLE_EFFECT` | passed |
65
+
66
+ The 19 Core and shared skill-script sources match the upgrade baseline
67
+ byte-for-byte, with aggregate SHA-256:
68
+
69
+ `be770e825289a67ce2d7084b0be8e84a29b95048960ecf5ae43ccec0ae98c02a`
70
+
71
+ This supports the separation at these tested seams: host API translation
72
+ belongs in the adapter; decision policy remains in Core. It does not establish
73
+ compatibility for every host provider, sandbox or agent scope. The npm entry
74
+ still selects the DSH adapter and the package engine still pins the old host.
75
+
76
+ ## Read guard startup and research seam
77
+
78
+ The unchanged production read guard rejects the new runtime with
79
+ `READ_GUARD_STARTUP_REFUSED`, as required by its exact version/artifact pins.
80
+ An important distinction was observed: **the Cordis host continued running
81
+ other plugins after this row failed**. With host access enabled, both harmless
82
+ markers were created and no Core block audit existed. Since adapter startup
83
+ awaits read-guard initialization before contributing deletion tools/hooks,
84
+ that failed row supplied neither protection. A refused plugin is not proof
85
+ that the entire host refuses tools.
86
+
87
+ A separate research composition used the new native `read`, LocalFileSystem,
88
+ ToolRuntime and real AgentLoop, with the unchanged Core worker called from a
89
+ private post-execute hook. It did not relax or replace the production runtime
90
+ gate. The native read binding conformance check passed, as did:
91
+
92
+ - Exposure of both supported synthetic secret classes in baseline content/meta.
93
+ - Redaction from guarded value/content/meta, while preserving benign content,
94
+ Chinese text, line numbers and an ordinary random marker.
95
+ - Withholding an incomplete paginated read.
96
+ - Clean next-request messages and full durable JSONL, using two deterministic
97
+ synthetic streams and zero external model/network/shell calls.
98
+ - Restoring the unguarded baseline after research-hook disposal.
99
+
100
+ The new ToolRuntime result-hook probe also retained the previously observed
101
+ contract: content-only replacement leaves original presentation metadata;
102
+ value replacement regenerates it; a later finalizer can reintroduce content.
103
+ These are research results, not production read-guard admission, Web sandbox
104
+ provider coverage, a real-model injection trial or an L1/L2 claim.
105
+
106
+ ## Lab gate and remaining acceptance work
107
+
108
+ The current Lab preflight refuses the actual new CLI with:
109
+ `DSH version preflight requires exactly 0.1.5-rc.1`. No capture, pair or
110
+ historical receipt was upgraded, and no unsupported real-model run was launched.
111
+ The separately generated 17-record synthetic native session has native
112
+ header **version 4**. The current parser requires native header version 3
113
+ and returns `UNSUPPORTED_SESSION_HEADER`, discarding all recognized channels.
114
+ This native format version is distinct from Lab capture receipt version 4.
115
+ The sample is retained for offline research; it does not validate every new
116
+ event or retry form emitted by a full new-host profile. A new format needs
117
+ explicit versioned interpretation while preserving prior receipts/parsers.
118
+
119
+ Remaining acceptance work is to review/admit the new read providers and
120
+ artifact bindings, validate the new Lab composition/session/retry contracts,
121
+ and establish which code and hooks run in the actual Web agent scope. Only
122
+ then should a fresh, matched official `deepseek-official / deepseek-flash`
123
+ (`DeepSeek-V41-Flash`) pair establish any real-model conclusion. Prior
124
+ [retry evidence](test-report-dsh-retry-evidence.md) and
125
+ [real-model follow-up](test-report-dsh-real-followup.md) retain their original
126
+ runtime and interpretation.
127
+
128
+ ## Validation
129
+
130
+ The pre-change full suite passed 590 Python tests in 536.943 seconds and
131
+ both Node smoke suites. After the correction, the full suite again passed
132
+ 590 Python tests in 774.065 seconds and both Node smoke suites. The added
133
+ Node cases exercise the new execution
134
+ handle, status tool completion, preparation/result failures, cancellation
135
+ signal and cwd forwarding, and absence of legacy fallback after a new API
136
+ failure. Native old/new host probes passed after the correction.
137
+ Both repository corpus checks, syntax/LF/whitespace checks, `git diff --check`
138
+ and 224 local links across 54 Markdown files passed. The npm dry-run includes
139
+ 105 files, including this report and no private controllers, captures or
140
+ compiled Python files. The 19 shared sources have no reverse DSH runtime
141
+ imports. Private receipts retain hashes and the before/after snapshots.
142
+ No hosted CI, Windows/PowerShell, publication, commit or push was performed.