@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc2

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 (38) hide show
  1. package/README.md +166 -573
  2. package/README.zh-CN.md +138 -489
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +4 -2
  5. package/adapters/dsh/README.md +7 -0
  6. package/assets/linux-do-community.svg +19 -0
  7. package/core/audit.py +170 -25
  8. package/core/classifier.py +25 -1
  9. package/core/lab.py +77 -7
  10. package/core/policy.py +17 -9
  11. package/core/recovery.py +5 -1
  12. package/core/redaction.py +122 -21
  13. package/docs/README.md +18 -5
  14. package/docs/design/architecture.md +25 -6
  15. package/docs/design/compatibility.md +106 -1
  16. package/docs/design/threat-model.md +6 -4
  17. package/docs/guides/audit-metadata.md +77 -0
  18. package/docs/guides/getting-started.md +106 -0
  19. package/docs/guides/harness-capabilities.md +5 -0
  20. package/docs/history/friction.md +85 -0
  21. package/docs/lab/guard-lab.md +15 -1
  22. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  23. package/docs/releases/release-notes-0.2.5-rc2.md +101 -0
  24. package/guard_lab.py +11 -0
  25. package/package.json +4 -2
  26. package/skills/delete-guard/SKILL.md +45 -7
  27. package/skills/delete-guard/references/policy.md +90 -4
  28. package/skills/delete-guard/scripts/check.py +3 -0
  29. package/skills/delete-guard/scripts/gc.py +18 -3
  30. package/skills/delete-guard/scripts/restore.py +22 -7
  31. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  32. package/skills/delete-guard/scripts/status.py +9 -7
  33. package/skills/exfil-guard/SKILL.md +23 -11
  34. package/skills/exfil-guard/references/channels.md +8 -1
  35. package/skills/exfil-guard/references/rules.md +86 -6
  36. package/skills/exfil-guard/scripts/_payload.py +20 -0
  37. package/skills/exfil-guard/scripts/check_span.py +5 -1
  38. package/skills/exfil-guard/scripts/sanitize.py +6 -3
package/README.md CHANGED
@@ -1,632 +1,225 @@
1
1
  # AGENT-GUARD
2
2
 
3
3
  [![CI](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/mokuyoaxis/agent-guard/actions/workflows/ci.yml)
4
- [![npm version](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
4
+ [![npm stable](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![v0.2.4 source](https://img.shields.io/badge/Source-v0.2.4-5B6B7A)](docs/releases/release-notes-0.2.4.md)
7
+ [![0.2.5-rc2 candidate](https://img.shields.io/badge/RC-0.2.5--rc2-5B6B7A)](docs/releases/release-notes-0.2.5-rc2.md)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
11
- Agent Guard is a reliability layer for coding agents. It makes supported
12
- high-impact actions recoverable instead of permanently destructive, while
13
- keeping routine work automatic.
14
-
15
- - **Destructive file operations** can be relocated to `.agent-trash/` with a
16
- recovery manifest instead of being permanently deleted.
17
- - **Destructive Git operations** can snapshot recoverable state before they
18
- overwrite the working tree.
19
- - **Accidental outbound disclosure** of known credentials or host-identifying
20
- absolute paths can be checked through a cooperative text CLI. A caller that
21
- owns the emission can apply its redaction plan, escalate, or block.
22
- - **Synthetic honeytoken experiments** can exercise declared local channels
23
- with zero-token controls and fail-inconclusive evidence health checks.
24
-
25
- The Core is harness-neutral and supports Python 3.9+ and Git. Automatic
26
- interception still depends on whether the host exposes a compatible hook; a
27
- Skill by itself does not intercept tool calls. The shared Core, Decision
28
- Protocol, and Skills define the product; harness adapters are replaceable
29
- integration bridges rather than the product boundary.
30
-
31
- > **Agent Guard keeps reversible actions automatic and escalates only when it
32
- > cannot safely automate them.** It is reliability infrastructure, not a
33
- > security sandbox: it protects against mistakes, not a malicious agent with
34
- > equal OS privileges.
35
-
36
- ## What it looks like
37
-
38
- ```text
39
- rm -rf build/ → RELOCATE # an in-scope tree moves to quarantine
40
- rm -rf . → BLOCK # the workspace root is protected
41
- git reset --hard → SNAPSHOT # after collision preflight, snapshot tracked changes
42
- git push --force → BLOCK # remote history is not automated
43
- ```
11
+ Agent Guard is reliability infrastructure for coding agents. It provides
12
+ recovery before supported destructive actions, checks text before disclosure,
13
+ and gives users a Lab for testing observed agent and harness behaviour.
14
+ The shared Python Core works through explicit CLIs and optional host adapters.
44
15
 
45
- These are illustrative verdicts for supported inputs, not commands to run or
46
- proof that every harness intercepts them. Ignored, regenerable targets may be
47
- `ALLOW`; hard reset is blocked if its target tree would overwrite untracked
48
- or ignored content, or if its preflight/snapshot cannot be completed. When
49
- recovery or safe rewriting is possible, the agent can keep working. Otherwise,
50
- the guard asks the human or blocks the operation.
16
+ | Capability | What it helps you do | Entry |
17
+ |---|---|---|
18
+ | **Recovery protection** | Relocate valuable files before deletion; snapshot tracked state before supported Git overwrites; inspect and restore transactions | [delete-guard](skills/delete-guard/SKILL.md) |
19
+ | **Disclosure checks** | Detect supported credentials and host-identifying paths; apply a redaction plan or withhold a payload | [exfil-guard](skills/exfil-guard/SKILL.md) |
20
+ | **Behaviour experiments** | Calibrate an observer, test a declared exposure channel, then compare matched guard-off/on trials | [guard-lab](docs/lab/guard-lab.md) |
51
21
 
52
- ## Quick start with your coding agent
22
+ A Skill supplies instructions; it does not intercept tool calls. Automatic
23
+ protection depends on an active, compatible host hook and its covered tools.
24
+ Agent Guard is not an OS sandbox against a malicious process with equal
25
+ privileges. The [capability matrix](docs/guides/harness-capabilities.md)
26
+ states the observed coverage and gaps.
53
27
 
54
- Use the scoped npm package or a stable Git checkout. The unscoped
55
- `agent-guard` package is unrelated to this project.
28
+ <a id="guard-lab"></a>
56
29
 
57
- Pinned npm installation into a stable, user-owned prefix:
30
+ ## guard-lab: test with evidence
58
31
 
59
- ```sh
60
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
61
- ```
32
+ guard-lab is a **user-controlled experiment tool**. It puts non-secret,
33
+ synthetic markers and harmless bait into a disposable project and observes
34
+ only declared channels. The real controller and evidence stay outside the
35
+ fixture given to the tested agent.
62
36
 
63
- **0.2.4** adds hard-reset collision checks,
64
- restore path validation, current-version preservation on forced restore, and
65
- a read-only trash location query. See the [release notes](docs/releases/release-notes-0.2.4.md)
66
- for behavior changes and evidence limits. The npm badge and
67
- [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) show
68
- which artifacts are available.
37
+ Its workflow separates three questions:
69
38
 
70
- The package root is then
71
- `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
72
- Alternatively, clone the source (skip this if you already have a checkout):
39
+ 1. **Calibrate:** do the observer, markers, scans and evidence chain work?
40
+ Built-in controls call no model and make no external-network request.
41
+ 2. **Observe exposure:** does an unguarded real-harness trial trigger the
42
+ selected channel?
43
+ 3. **Compare protection:** after an effective baseline, does a matched
44
+ guarded trial reduce or block that exposure?
45
+
46
+ Start with one zero-model control from the package or checkout root:
73
47
 
74
48
  ```sh
75
- git clone https://github.com/mokuyoaxis/agent-guard.git
76
- cd agent-guard
49
+ lab_run="$(mktemp -d)"
50
+ python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json
77
51
  ```
78
52
 
79
- Python 3.9+ and Git are required for the Core; native interception depends on
80
- the host's hook support. Then give your coding agent the following setup prompt
81
- (replace the path with your checkout):
82
-
83
- ```text
84
- Set up agent-guard for this workspace. Use either an existing Git checkout or
85
- the exact scoped npm package @mokuyoaxis/agent-guard@0.2.4;
86
- never install the unscoped package named agent-guard. If 0.2.4 is unavailable,
87
- report that and use the existing checkout or ask me to choose a published
88
- version. Before installing, ask me to choose and
89
- approve a stable user-owned prefix. Treat the checkout or installed package
90
- root as /absolute/path/to/agent-guard below.
91
- First identify the current harness and its actual hook/skill capabilities;
92
- read this README and the matching adapter README. Check Python and Git.
93
- Install the relevant Skills, then configure a native shell hook only if this
94
- harness supports one. Preserve existing settings and show me the proposed
95
- diff before editing user-wide configuration or installing dependencies.
96
- For Claude Code use adapters/claude/README.md; for Kimi Code use
97
- adapters/kimi-code/README.md; for DSH use adapters/dsh/README.md.
98
- For another host, read adapters/INTEGRATION.md and do not invent a native
99
- hook. If no blocking pre-tool hook is verified, use only Skill/CLI and say
100
- plainly that automatic interception is not enabled.
101
- Verify a harmless command and pass a BLOCK-shaped command only as data to
102
- check.py; never execute a destructive test command. For Claude/Kimi, run the
103
- local doctor but do not treat its PASS as proof of host interception. Report
104
- the host version, tool coverage, what was installed, what the host actually
105
- intercepted, and any unverified paths.
106
- ```
53
+ The other controls are `mock-positive`, `mock-injection` and
54
+ `snapshot-positive`. Run all four before a real-harness experiment, following
55
+ the [Lab guide](docs/lab/guard-lab.md). Installed packages also expose
56
+ `agent-guard-lab`.
107
57
 
108
- For manual setup and evidence limits, see the
109
- [adapter matrix](docs/guides/harness-capabilities.md) and the adapter README for your
110
- host.
58
+ A control PASS means **instrument calibration**, not model safety.
59
+ An unhealthy observer or missing evidence is `INCONCLUSIVE`; a quiet
60
+ guard-off baseline cannot establish mitigation. Matched comparisons require
61
+ the same relevant harness/version/model, task, protocol and non-guard
62
+ configuration. Lab results cover the declared channels, not every file read,
63
+ external transfer or model request. Existing
64
+ [Kimi](docs/reports/test-report-kimi-guard-lab.md) and
65
+ [DSH](docs/reports/test-report-dsh-guard-lab.md) reports retain their bounded
66
+ results, failures and review states.
111
67
 
112
- ## Design principles
68
+ <a id="quick-start-with-your-coding-agent"></a>
113
69
 
114
- | Principle | Guarantee |
115
- |---|---|
116
- | **Stay in scope** | The guard blocks deletion of the workspace root, `.git`, and outside paths when the operation reaches it |
117
- | **Make it recoverable** | Supported deletions relocate to `.agent-trash/` with a manifest; destructive Git overwrites snapshot first |
118
- | **Constrain authorization** | Authorization is session-scoped; a veto downgrades one-way, and only a human restores it |
119
- | **Leave a durable trail** | Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored |
70
+ ## Install and choose a version
120
71
 
121
- One rule runs through all four: **uncertainty increases restriction.**
72
+ Python 3.9+ and Git are required for the Core. The examples use a POSIX shell;
73
+ native bridges and optional capture helpers have their own requirements.
122
74
 
123
- ## How it decides
75
+ | Version | Status |
76
+ |---|---|
77
+ | [0.2.4](docs/releases/release-notes-0.2.4.md) | Published stable baseline |
78
+ | [0.2.5-rc1](docs/releases/release-notes-0.2.5-rc1.md) | Previous published prerelease baseline |
79
+ | [0.2.5-rc2](docs/releases/release-notes-0.2.5-rc2.md) | Maintenance prerelease; check the exact publication receipts |
124
80
 
125
- Each inspected operation is classified by its effect and then mapped to the
126
- least restrictive decision that preserves the relevant safety or recovery
127
- guarantee. The stable interface is a Decision Protocol, not a binary
128
- allow/block check:
81
+ For the published stable package, use a chosen, stable user-owned prefix:
129
82
 
83
+ ```sh
84
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4
130
85
  ```
131
- Effect → Classifier → Policy → Decision ∈ { ALLOW, SANITIZE, RELOCATE,
132
- SNAPSHOT, ASK, BLOCK }
133
- + ReasonCode (stable, machine-readable)
134
- + Explanation (human-facing)
135
- + RecoveryPlan (txids, strategy)
136
- ```
137
-
138
- | Tier | Decisions | What the agent experiences |
139
- |---|---|---|
140
- | **SAFE** | `ALLOW` · `SANITIZE` · `RELOCATE` · `SNAPSHOT` | Runs silently; compensation is applied first where needed; recoverable mutations are restorable via txid. `SANITIZE` returns a plan for the *payload owner* to rewrite (not a command rewrite) |
141
- | **AMBIGUOUS** | `ASK` | Single-execution authorization (`ASK_ONCE`) — e.g. compound shapes the guard cannot safely automate |
142
- | **FORBIDDEN** | `BLOCK` | Refused with reason and remediation; never askable |
143
86
 
144
- Precedence when several decisions meet in one operation, weakest to strongest:
87
+ The package root is
88
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
89
+ The exact scoped package name matters. A source checkout is also usable:
145
90
 
91
+ ```sh
92
+ git clone https://github.com/mokuyoaxis/agent-guard.git
93
+ cd agent-guard
146
94
  ```
147
- ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
148
- ```
149
-
150
- `SANITIZE` ranks *below* `ASK` deliberately: it is automatic (SAFE tier),
151
- while `ASK` forfeits automation. A payload carrying both a sanitizable secret
152
- and a shape that cannot be rewritten must `ASK` — you cannot silently proceed
153
- when part of the emission is uninspectable.
154
-
155
- True effect uncertainty (`$VAR` targets, `bash -c`, `find -delete`, stdin-fed
156
- lists) stays on the BLOCK path: allowing it would forfeit the core guarantee.
157
- Adapters map decisions onto their harness natively — DSH `PreToolDecision`,
158
- Claude Code PreToolUse `ask`, or a deny carrying the explanation where no ask
159
- exists.
160
-
161
- ## What Agent Guard includes
162
-
163
- ### `delete-guard`
164
-
165
- Answers *"if this destroys something, can we come back?"* It runs before a
166
- delete or destructive Git action when invoked through a supported adapter or
167
- CLI, and compensates first when recovery is possible.
168
-
169
- ### `exfil-guard`
170
95
 
171
- Answers *"if this leaves the machine, was it supposed to?"* Its cooperative
172
- CLI checks text before an emission when the payload owner invokes it, returning
173
- a redaction or escalation decision for supported patterns.
96
+ For RC2, select `@mokuyoaxis/agent-guard@0.2.5-rc2` explicitly; the RC
97
+ channel does not replace stable `latest`. Check the
98
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.5-rc2)
99
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.5-rc2)
100
+ for publication. A reviewed checkout or supplied tarball is also usable;
101
+ the manifest alone does not establish registry availability. See
102
+ [setup and the agent setup prompt](docs/guides/getting-started.md).
174
103
 
175
- ### `recovery-audit`
104
+ ## Recover a supported deletion
176
105
 
177
- The incident-response companion for cases where prevention never ran or did not
178
- cover the path. It establishes source precedence, distinguishes recovered bytes
179
- from reconstructed behavior and known gaps, audits replay tooling, and keeps
180
- landing, commit, push, and release as separate authorization gates.
106
+ From the workspace being protected, point at your package/checkout root:
181
107
 
182
- `delete-guard` and `exfil-guard` are the two preventive guard branches;
183
- `recovery-audit` handles evidence-led recovery after the fact.
184
-
185
- ## recovery-audit
186
-
187
- Sometimes prevention never ran: a harness had no adapter, a subagent bypassed
188
- the expected path, or an over-broad command removed the workspace before anyone
189
- could intervene. The working tree may be gone while the coding agent's session
190
- cache still preserves successful patches, file snapshots, tool results, diffs,
191
- and command context.
192
-
193
- `recovery-audit` turns those remnants, Git remotes/reflogs/stashes, editor or
194
- tool caches, build artifacts, and project plans into an evidence-led recovery:
195
-
196
- - every unit is labelled **recovered**, **reconstructed**, or **missing**;
197
- - recorded tool effects are replayed in chronology and checked for divergence;
198
- - repeated replay must produce a byte-identical tree;
199
- - landing, commit, push, and release remain separate authorization gates.
200
-
201
- It is not filesystem undelete and cannot recreate bytes no surviving source
202
- captured. Its promise is a fast, auditable path to the strongest project state
203
- the evidence actually supports, with gaps reported instead of hidden.
204
-
205
- ## exfil-guard
206
-
207
- `exfil-guard` checks text before an agent writes, sends, commits, or pushes it
208
- **when the payload owner calls its CLI**. It also offers an explicit, read-only
209
- safe view of selected JSON/dotenv configuration files. The text scanner is
210
- designed to catch two accidental disclosure classes: **known credentials**
211
- and **host-identifying absolute paths**. Depending on the channel, it can
212
- allow the payload, return a redaction plan, ask for a human decision, or block
213
- the emission.
214
-
215
- DSH also offers a [default-off text-read redaction prototype](adapters/dsh/README.md#experimental-text-read-redaction)
216
- for complete native reads in a pinned composition. It reuses Core and
217
- regenerates both rendered text and presentation metadata; a zero-model native
218
- probe covers the next request and durable JSONL log. A separate
219
- [official Flash direct-read trial](docs/reports/test-report-dsh-real-followup.md)
220
- observed supported synthetic-secret redaction while useful config stayed readable.
221
-
222
- It is a prevention and redaction guard, not a compensation engine: after an
223
- emission there is nothing to recover. It is also **not a security sandbox** and
224
- does not attempt to stop adversarial exfiltration by an agent with equal OS
225
- privileges.
226
-
227
- ### Decisions exfil-guard can return
228
-
229
- The full Decision Protocol applies, but only four classes are reachable for
230
- a text payload (`RELOCATE`/`SNAPSHOT` belong to delete-guard — the guard
231
- cannot rewrite what it did not write):
232
-
233
- | Decision | Meaning | Example |
234
- |---|---|---|
235
- | `ALLOW` | nothing matched, a documented placeholder, or a workspace-relative path | `echo "hello" \| check_span.py` |
236
- | `SANITIZE` | a redaction plan is returned; the *payload owner* rewrites and emits | a real key on `file-write` / `llm-request` |
237
- | `ASK` | the channel cannot be rewritten and cannot be taken back | a host path on `shell-stdout` |
238
- | `BLOCK` | refuse: immutable/remote history, an un-scannable payload, invalid config | a credential in `git-push-payload` |
239
-
240
- ### What is detected
241
-
242
- **T1 vendor credential patterns** (`secret/*`). These rules use known formats;
243
- documented placeholders and negative examples constrain false positives.
244
- Rule ids: `secret/openai-key`, `secret/github-token`,
245
- `secret/aws-access-key-id`, `secret/gitlab-token`, `secret/slack-token`,
246
- `secret/stripe-key` (live keys only — `sk_test_` is exempt),
247
- `secret/pypi-token`, `secret/jwt` (structural: the header must decode to JSON
248
- with a nonempty ASCII string `alg`), and
249
- `secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
250
- redacted in one piece). See
251
- [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
252
- for the rule table and remaining ambiguities.
253
-
254
- `secret/connection-password` also detects nonempty passwords in URI userinfo.
255
- It redacts only the password, preserving the scheme, account and host for
256
- diagnostics. Percent-encoded passwords and JSON-escaped scheme slashes are
257
- supported; this does not hide network topology or scan every DSN format.
258
-
259
- **Value-free secret references** (`secret/source-reference`). The guard
260
- classifies complete components in an environment variable's *name* (such as
261
- `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD`, `CRED`, or `AUTH`) and a
262
- secret-store *file name*
263
- (`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
264
- whole-environment expansions (`printenv`, `env | ...`, `cat
265
- /proc/self/environ`). This scanner **does not resolve the variable value**;
266
- that does not certify unrelated Guard output or existing audit records as
267
- secret-free.
268
-
269
- **Host-identifying paths** (`path/*`). `path/workspace-relative` is `ALLOW`
270
- (the workspace is exempt); `path/system` (`/usr`, `/etc`, `C:\Windows`) is
271
- `ALLOW`; `path/host-absolute` (under `HOME`/`TEMP`, a CI root, or a
272
- workspace ancestor) is `SANITIZE`; `path/generic-absolute` (no host
273
- correlation) is `ASK`; `path/device` (UNC, `\\?\`, pipes) is `SANITIZE`.
274
-
275
- ### Channels determine the disposition
276
-
277
- A channel is defined by two facts: can it be **rewritten**, and does the
278
- emission **persist**? `rewritable` is what makes `SANITIZE` meaningful;
279
- `persistence` is what justifies `BLOCK`.
280
-
281
- | Channel | Rewritable | Persistence | Default |
282
- |---|---|---|---|
283
- | `llm-request` | yes | remote | SANITIZE |
284
- | `file-write` | yes | workspace | SANITIZE |
285
- | `forge-comment` / `issue-body` / `pr-description` | yes | public | SANITIZE |
286
- | `git-commit-message` | yes (rewrite argv) | remote history | **BLOCK** |
287
- | `git-push-payload` | no | **remote** | **BLOCK** |
288
- | `shell-stdout` | **no** | local transcript | ASK |
289
- | `shell-file-redirect` | yes | local | ASK |
290
- | `archive-upload` | yes | remote | ASK |
291
- | `process-argv` | yes | local | ASK |
292
-
293
- An unknown channel name is a configuration defect, not "no risk":
294
- `check_span.py` returns `BLOCK_OUTPUT_UNSCANNABLE`, never an implicit ALLOW.
295
-
296
- ### Usage
297
-
298
- `check_span.py` reads the payload on **stdin** and is a pure function — it
299
- never writes, never rewrites, and never prints the match. `sanitize.py`
300
- applies the plan the guard returned.
301
-
302
- ```bash
303
- # a credential on a rewritable channel -> SANITIZE, exit 0
304
- echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
305
-
306
- # a credential bound for remote history -> BLOCK, exit 2
307
- echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
308
-
309
- # apply the redaction plan (format preserved: sk-<REDACTED>)
310
- echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
311
- ```
312
-
313
- Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
314
- `1` = ERROR. Use `--json` for the machine-readable verdict (offsets, rule ids
315
- and placeholders only — **never the matched bytes**), and `--path` to enable
316
- the repo-local exemption file for the file being written.
317
-
318
- `sanitize.py` enforces the same exit codes: ASK/BLOCK and errors emit no
319
- payload on stdout. It validates an external `--plan` against the current scan
320
- and rescans the rewritten text before emitting. Both CLIs use the same default
321
- workspace and host-side mode; stdin is bounded to the scan cap (4 MiB by default)
322
- during reading, as is an external plan file. A checker plan produced with an
323
- explicit mode or path exemption must still satisfy the sanitizer's current
324
- policy; the plan itself does not authorize emission.
325
-
326
- Credential detection covers classic and stateless `ghs_APPID_JWT` GitHub
327
- installation tokens, including long signatures and credentials next to CJK
328
- prose. Placeholder exemptions require whole shapes; incidental example words
329
- inside a token do not exempt it. Secret variable references are classified by
330
- complete name components, preserving ordinary identifiers such as `MONKEY`
331
- and metadata such as `TOKEN_COUNT`. See the [rule reference](skills/exfil-guard/references/rules.md)
332
- for supported forms and limitations.
333
-
334
- PyPI publishing tokens are also detected with their documented prefix and
335
- minimum body shape, with complete redaction of long tokens. AWS group/user/
336
- role/policy IDs are kept distinct from access-key IDs; JWT headers require
337
- the declared nonempty ASCII string `alg`. Public-key variable names and the
338
- broad legacy `sk-` shape retain their documented conservative boundaries.
339
-
340
- ### Read a config without printing its values
341
-
342
- Introduced in the `0.2.0` source; this CLI is **not** in the earlier
343
- `0.2.0-rc2` preview tag.
344
-
345
- ```bash
346
- python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
347
- python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
108
+ ```sh
109
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
110
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
111
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
112
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>
348
113
  ```
349
114
 
350
- The path must be relative to that workspace. The JSON output preserves field
351
- names and structure, plus scalar types and `set`/`empty` states, but **never
352
- scalar values**. Known secret-shaped field names are hidden; unknown secrets
353
- in field names remain a limitation. Only UTF-8 JSON and a strict, single-line
354
- dotenv subset are supported (256 KiB maximum, 16 levels, 2048 nodes). The
355
- CLI refuses symlinks, hardlinks, special files, unsafe paths, malformed input,
356
- and platforms without safe descriptor-relative reads. Exit `0` means a view
357
- was produced, `2` means refused, and `1` means an internal error. This view
358
- is for diagnosis only: do not write it back over the original config. It
359
- does not intercept ordinary file reads made by a harness.
115
+ Valuable targets are relocated with exact recovery paths in a manifest.
116
+ Provably regenerable, Git-ignored artifacts may be deleted directly.
117
+ Supported Git overwrites snapshot tracked state; hard-reset collisions with
118
+ untracked/ignored content are refused. Force restore preserves the current
119
+ occupant before replacement. Errors can leave partial work: inspect the
120
+ reported transaction IDs, filesystem and state before retrying.
360
121
 
361
- ### Relationship to delete-guard
122
+ Advisory `check.py` and `safe_delete.py --dry-run` preserve command targets but
123
+ may write quarantine/audit metadata and a Git local exclude entry. Advisory
124
+ exit 0 is not permission to execute a BLOCK or ASK.
125
+ See the [policy and assessment contract](skills/delete-guard/references/policy.md).
362
126
 
363
- They are two halves of the same promise, on opposite sides of the action:
127
+ RC1 added quarantine control-path protection, excluded PURGED transactions
128
+ from active GC planning, and minimized restore/safe_delete audit fields.
129
+ Exact CLI/manifest recovery paths remain available. These changes are not in
130
+ the published 0.2.4 package; see the [RC notes](docs/releases/release-notes-0.2.5-rc1.md).
364
131
 
365
- | | `delete-guard` | `exfil-guard` |
366
- |---|---|---|
367
- | Question | "can we come back?" | "was this supposed to leave?" |
368
- | Guards | *before a delete* | *before an emission* |
369
- | Response | compensate, then proceed | redact, then emit |
370
- | Failure cost | recoverable via txid | **irreversible** |
371
- | Entry point | `check.py -- <command>` | `check_span.py` (stdin) |
372
-
373
- They share the vocabulary (`core/policy.py`), the aggregation (`worst()`),
374
- the exemption discipline, and the audit log. `worst()` is shared by both
375
- guards, which is why `SANITIZE` had to be ranked once, not twice.
376
-
377
- ### Coverage and limitations
378
-
379
- This is stated plainly, because a reliability tool that overstates its reach
380
- is a false security claim:
381
-
382
- - **Not a sandbox.** It does not prevent adversarial exfiltration. An agent
383
- that obfuscates a secret to evade the scanner is out of scope; this
384
- catches *accidents*.
385
- - **Channels with no hook are unreachable by construction.** A hosted model
386
- call with no proxy, the model's own tool calls, content produced *inside* a
387
- program, and the human clipboard get **no verdict at all** — no coverage is
388
- claimed there. See `references/channels.md` and
389
- [docs/history/secret-guard-analysis.md](docs/history/secret-guard-analysis.md) §2.4 for
390
- the reachability table this claim is traceable to.
391
- - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
392
- guard can see *on the way out*.
393
- - **No history rewriting.** Detecting a secret already in Git history is a
394
- report at most. Rewriting history is a human action with its own risks.
395
- - **No T3 entropy detector in this release.** Random-looking text alone is
396
- insufficient evidence of a credential; ordinary identifiers stay readable.
397
-
398
- ## Manual, harness-neutral usage
399
-
400
- The Core has zero third-party dependencies. Requirements: Python 3.9+, POSIX
401
- shell, and Git.
402
-
403
- ```bash
404
- # delete something - it is quarantined, not destroyed:
405
- python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
406
-
407
- # inspect and undo:
408
- python3 skills/delete-guard/scripts/status.py
409
- python3 skills/delete-guard/scripts/status.py --trash-index --root <projects> --json
410
- python3 skills/delete-guard/scripts/restore.py list
411
- python3 skills/delete-guard/scripts/restore.py <txid>
412
-
413
- # quarantine maintenance (dry plan by default):
414
- python3 skills/delete-guard/scripts/gc.py
415
- ```
132
+ The RC2 source candidate also projects shared audit metadata,
133
+ uses opaque session correlation, and limits legacy status/GC metadata.
134
+ See the [audit contract and remaining boundaries](docs/guides/audit-metadata.md).
135
+ It adds observer startup diagnostics and correct cancellation accounting;
136
+ the original intermittent timeout's cause remains unknown. See the
137
+ [RC2 scope and evidence](docs/releases/release-notes-0.2.5-rc2.md).
416
138
 
417
- The local [trash location query](docs/guides/trash-index.md) provides a shared
418
- read-only JSON interface for agents and future UI callers. It reports scoped
419
- location candidates and layout hints; it neither scans recovery contents nor
420
- grants cleanup permission. It is included in 0.2.4.
139
+ ## Check text before emission
421
140
 
422
- A harness adapter can invoke the guard before a supported shell command and
423
- map its exit status to the host's own tool decision:
141
+ The payload owner invokes the scanner and applies its decision.
142
+ For a text file:
424
143
 
425
- ```text
426
- python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
427
- exit 0 → host may run the original command
428
- exit 2 → deny
429
- exit 3 → ask the human if supported; otherwise deny
430
- exit 1 → guard error; fail closed
431
- ```
432
-
433
- ## What gets protected
434
-
435
- These examples assume the command reaches the guard and its targets meet the
436
- stated conditions; see the [capability matrix](docs/guides/harness-capabilities.md)
437
- for what each host has actually demonstrated.
438
-
439
- ```text
440
- rm -rf build/ → RELOCATE (tree quarantined, command proceeds)
441
- rm -rf . → BLOCK (workspace root)
442
- rm -rf $DIR/ → BLOCK (unresolvable target: fail closed)
443
- rm *.log → BLOCK (opaque glob; safe_delete expands it)
444
- cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
445
- touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
446
- git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
447
- git reset --hard → SNAPSHOT (collision preflight + tracked snapshot)
448
- reset with collisions → BLOCK (preserve untracked/ignored paths first)
449
- git push --force → BLOCK (remote history is never automated)
450
- node_modules/ (ignored) → ALLOW (provably regenerable)
451
- quarantine full → BLOCK (never fall back to permanent delete)
144
+ ```sh
145
+ python3 skills/exfil-guard/scripts/check_span.py --channel file-write --json < draft.md
146
+ python3 skills/exfil-guard/scripts/sanitize.py --channel file-write < draft.md
452
147
  ```
453
148
 
454
- ## Integration and validation matrix
149
+ A complete synthetic credential example is generated at runtime:
455
150
 
456
- [![Node.js 22 smoke](https://img.shields.io/badge/Node.js-22%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
457
- [![Codex Skill/CLI tested](https://img.shields.io/badge/Codex-Skill%2FCLI%20tested-000000?logo=openai&logoColor=white)](docs/reports/test-report-codex-gpt-6-astra-high.md)
458
- [![DSH 0.1.5-rc.1 host BLOCK tested](https://img.shields.io/badge/DSH%200.1.5--rc.1-host%20BLOCK%20tested-4D6BFE)](docs/reports/test-report-dsh-0.1.5-rc.1.md)
459
- [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/reports/test-report-zcode-glm-flash.md)
460
- [![Claude Code hook tested with scripted model](https://img.shields.io/badge/Claude%20Code-hook%20tested%20%28scripted%20model%29-D97757?logo=anthropic&logoColor=white)](docs/reports/test-report-claude-code-harness.md)
461
- [![Kimi Code 2.1.1 root Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-root%20Bash%20BLOCK-5B9BD5)](docs/reports/test-report-kimi-code-block.md)
462
- [![WorkBuddy Windows Core/CLI evaluated](https://img.shields.io/badge/WorkBuddy-Windows%20Core%2FCLI%20evaluated-5B6B7A)](docs/reports/test-report-workbuddy-windows-core.md)
463
- [![Windows Core CI](https://img.shields.io/badge/Windows-Core%20CI-0078D4)](docs/releases/release-notes-0.2.3-rc1.md#focused-windows-ci)
464
- [![DSH native text-read checked](https://img.shields.io/badge/DSH-native%20text--read%20checked-4D6BFE)](docs/reports/test-report-release-readiness-0.2.3.md)
151
+ ```sh
152
+ python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
153
+ python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
154
+ ```
465
155
 
466
- These badges link to scoped evidence; they do not certify every tool or model.
467
- The DSH text-read feature is optional and off by default.
156
+ The expected output is `config: sk-<REDACTED>`. The checker returns a
157
+ decision and plan; it never rewrites the payload. Its exit 0 means
158
+ ALLOW/SANITIZE assessment, while the sanitizer's successful stdout is the
159
+ allowed or rewritten text. ASK/BLOCK/error withholds sanitizer payload output.
468
160
 
469
- "The Core works", "a Skill-guided agent used it", and "the harness
470
- intercepts every matching tool call" are separate claims. This table keeps
471
- those evidence levels explicit:
161
+ Detection covers documented credential shapes, value-free secret references
162
+ and selected host paths. It is not a general repository scanner or protection
163
+ against deliberate obfuscation. The text CLIs do not automatically append
164
+ egress audit events; a trusted integration owns emission and any audit storage.
165
+ For configuration inspection, an explicit safe view reports supported
166
+ JSON/dotenv structure without scalar values; it is not an editable copy or
167
+ automatic read interception.
472
168
 
473
- | Harness / tested version | Integration path | Evidence and limit |
474
- |---|---|---|
475
- | **Claude Code 2.1.270 / 2.1.273** | [Native `PreToolUse` for Bash](adapters/claude/README.md) | [Real CLI + scripted model](docs/reports/test-report-claude-code-harness.md): sampled allow/ask/deny and Python-startup failure; other tools unverified. |
476
- | **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host packaged-plugin probe](docs/reports/test-report-dsh-0.1.5-rc.1.md): execution-level `BLOCK` and loaded-adapter Core failure. A [real-model Lab baseline](docs/reports/test-report-dsh-guard-lab.md) stayed quiet with guard off, so no L2 mitigation claim exists; model-proposed destructive `bash` enforcement remains unverified. The separate opt-in read path is listed below. |
477
- | **DSH CLI rc.1 / tools and FS rc.2 / Node 22** | [Experimental text-read redaction](adapters/dsh/README.md#experimental-text-read-redaction), default off | [Zero-model native probe](docs/reports/test-report-dsh-read-redaction.md): next request and durable JSONL. [Official Flash direct-read off/on](docs/reports/test-report-dsh-real-followup.md): supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim. |
478
- | **DSH 0.2.0-rc.2 / Node 22** | [Default deletion and optional text-read adapter](adapters/dsh/README.md) | [Fresh contract review](docs/reports/test-report-release-readiness-0.2.3.md): native deletion blocking, read redaction on reviewed local/sandbox FS, next synthetic request and durable JSONL. Native v4 Lab support remains bounded; no new real-model L2 result. |
479
- | **Codex CLI 0.154.0 (tested session)** | [Skill + production CLI](docs/reports/test-report-codex-gpt-6-astra-high.md) | Older-source cooperative acceptance; no native hook claim. |
480
- | **WorkBuddy (version not recorded; Windows 11)** | [Core / CLI](docs/reports/test-report-workbuddy-windows-core.md) | Community feedback on 0.2.2 found two Core defects now covered by regressions and focused Windows CI; no WorkBuddy adapter or native-hook validation. |
481
- | **ZCode (version unrecorded; win32)** | [Historical Skill/CLI + hook trial](docs/reports/test-report-zcode-glm-flash.md) | Older hook observation includes a persistent-permission bypass; current version unverified. |
482
- | **Kimi Code 0.42.0 / 2.1.1** | [Native `PreToolUse` for Bash](adapters/kimi-code/README.md) | [Bounded tests](docs/reports/test-report-kimi-code-block.md): authenticated 2.1.1 root-Bash PASS on an OAuth official model and a second configured model route; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
483
- | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
484
-
485
- For agent-led setup: identify the actual host version and tool names, follow
486
- the matching guide above, preserve existing settings, then report separate
487
- configuration, local-probe, and real-host evidence. For an unlisted host,
488
- follow the [self-adaptation checklist](adapters/INTEGRATION.md); a prompt or
489
- adapter exit code alone is not proof of interception. Ask before changing
490
- user-wide settings, security policy, or dependencies.
491
-
492
- `tests/test_conformance.py` checks the shared Core and Claude adapter; DSH
493
- has a smoke test and Kimi has targeted adapter tests. The Kimi observations
494
- above cover only the tested calls, not every shell construct or a general
495
- concurrent-agent safety guarantee.
496
- Run `python3 doctor.py kimi --probe` or `python3 doctor.py claude --probe`
497
- to check a selected configuration file and the local shell bridge without a
498
- model call. Add `--json` for machine-readable `configuration`, `local_probe`,
499
- and `host_interception` statuses. The last status is always `UNVERIFIED`:
500
- this doctor cannot prove that a live session loaded or enforced the hook.
501
- Add `--check-drift` to query the local host version and compute privacy-safe
502
- configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
503
- `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
504
- evidence, not interception proof. Optional create-new baselines contain only
505
- the parsed version and SHA-256 fingerprints. See the
506
- [host drift guide](docs/guides/host-drift.md) for the status and baseline contract.
507
- An explicit `--live-sentinel` can then spend one configured model call in a
508
- private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
509
- `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
510
- It retains a hashed/redacted result but not raw model output. This is a
511
- reliability probe for a trusted provider, not a sandbox for a malicious model.
512
- The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
513
- hook adapter continue to support Python 3.9+.
514
- See the [Kimi](adapters/kimi-code/README.md) and
515
- [Claude](adapters/claude/README.md) adapter guides.
516
- See [harness capabilities and evidence levels](docs/guides/harness-capabilities.md)
517
- for the per-host scope and execution-level acceptance criteria.
518
-
519
- ## Repository layout
169
+ Read the [Skill](skills/exfil-guard/SKILL.md),
170
+ [rules and exemption diagnostics](skills/exfil-guard/references/rules.md), and
171
+ [channel contract](skills/exfil-guard/references/channels.md).
520
172
 
521
- ```
522
- agent-guard/
523
- ├── skills/delete-guard/ # agent-facing skill: SKILL.md + CLI scripts
524
- ├── skills/exfil-guard/ # egress skill: check_span.py · sanitize.py
525
- ├── skills/recovery-audit/ # evidence-led repository audit and recovery
526
- ├── core/ # classifier · policy · recovery · audit · redaction
527
- ├── doctor.py # local configuration, probes, and drift preflight
528
- ├── live_sentinel.py # opt-in real-host sentinel and alarm evidence
529
- ├── guard_lab.py # user-controlled offline synthetic honeytoken lab
530
- ├── adapters/INTEGRATION.md # checklist for an unlisted host
531
- ├── adapters/claude/ # Claude Code PreToolUse hook adapter
532
- ├── adapters/kimi-code/ # Kimi Code PreToolUse hook adapter
533
- ├── adapters/dsh/ # DeepSeek Harness integration bridge
534
- ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
535
- ├── tests/ # unittest suites incl. cross-harness conformance
536
- └── docs/ # guides · design · Lab · reports · releases · history
537
- ```
538
-
539
- Skills guide agent behavior; constraints live in Core. Future
540
- `git-guard`, `database-guard`, `cloud-guard` skills plug into the same
541
- compensation engine without restructuring.
173
+ <a id="integration-and-validation-matrix"></a>
542
174
 
543
- ## Documentation
175
+ ## Connect your coding agent
544
176
 
545
- The [documentation index](docs/README.md) lists every document by purpose.
546
- Historical reports retain their tested versions and evidence limits.
177
+ These are version-specific historical observations. They do not certify a
178
+ new source candidate, every tool or every subagent path.
547
179
 
548
- | Read | For |
180
+ | Host | Integration and evidence |
181
+ |---|---|
182
+ | Claude Code | Native Bash `PreToolUse`; sampled 2.1.270/2.1.273 scripted-host enforcement. [Setup](adapters/claude/README.md) |
183
+ | Kimi Code | Native Bash `PreToolUse`; bounded 0.42.0 root/child and 2.1.1 root-Bash observations. ASK is denied; missing/timed-out hooks remain uncovered. [Setup](adapters/kimi-code/README.md) |
184
+ | DSH | Reviewed 0.1.5-rc.1/0.2.0-rc.2 deletion paths; optional complete text-read protection is default off. Sampled PTC Bash refusal does not imply universal PTC mediation. [Setup](adapters/dsh/README.md) |
185
+ | Codex / other hosts | Explicit Skill/CLI is usable. Native interception needs a verified blocking hook. [Adaptation guide](adapters/INTEGRATION.md) |
186
+
187
+ Use the [full capability and evidence matrix](docs/guides/harness-capabilities.md)
188
+ for precise versions, tests and gaps. `doctor.py kimi|claude --probe` checks a
189
+ selected configuration and local adapter path; PASS does not prove a live
190
+ host loaded the hook. Drift checks are local preflight. A live sentinel is
191
+ explicit, may consume provider quota, and covers only its sampled root Bash
192
+ call. See the [host drift guide](docs/guides/host-drift.md).
193
+
194
+ ## Decisions, recovery and documentation
195
+
196
+ The shared protocol is `ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK`,
197
+ with stable reason codes and explanations.
198
+ Aggregation is `BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW`.
199
+ Opaque targets and protected boundaries are refused; supported recoverable
200
+ mutations compensate before proceeding. Authorization state remains a local
201
+ discipline, not an isolated identity boundary.
202
+
203
+ After an incident, [recovery-audit](skills/recovery-audit/SKILL.md) helps recover
204
+ from surviving Git/session/cache evidence, distinguishing original bytes,
205
+ reconstruction and known gaps. It cannot recreate bytes that no source kept.
206
+
207
+ | Document | Purpose |
549
208
  |---|---|
550
- | [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
551
- | [Guides](docs/README.md#guides) | current harness capabilities, host drift and maintainer guidance |
552
- | [Design and contracts](docs/README.md#design) | architecture, threat model and compatibility |
553
- | [Lab](docs/README.md#lab) | experiment guide, task templates and candidate attack references |
554
- | [Test reports](docs/README.md#reports) | versioned Core, CLI, hook and Lab evidence |
555
- | [Release notes](docs/README.md#releases) | stable and prerelease scopes |
556
- | [Historical design and findings](docs/README.md#history) | early proposals, friction log and incident exploration |
557
- | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
558
- | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
559
- | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
560
- | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
561
- | [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | egress-channel taxonomy and the unreachable channels |
562
-
563
- ## Status & roadmap
564
-
565
- **v0.2.4** adds focused recovery maintenance and the trash query
566
- to 0.2.3. It refuses hard-reset collisions with untracked/ignored content,
567
- checks restore sources and destinations, and preserves an occupied destination
568
- before a forced restore. The query supplies a shared CLI/agent/future UI
569
- contract. Existing text redaction, safe config inspection, offline Lab,
570
- Claude/Kimi bridges, doctor, host-drift checks and live sentinel remain available.
571
- The DSH bridge supports the reviewed `0.1.5-rc.1` and `0.2.0-rc.2` contracts;
572
- its optional text-read protection remains off by default.
573
-
574
- The [0.2.4 notes](docs/releases/release-notes-0.2.4.md) describe this release's scope.
575
- The [0.2.3](docs/releases/release-notes-0.2.3.md),
576
- [rc2](docs/releases/release-notes-0.2.3-rc2.md),
577
- [rc1](docs/releases/release-notes-0.2.3-rc1.md), and
578
- [0.2.2](docs/releases/release-notes-0.2.2.md) notes retain their historical scope.
579
- Check [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases)
580
- and npm for published artifacts.
581
-
582
- The Core and Decision Protocol are shared across harnesses. DSH, Claude and
583
- Kimi adapters, together with Codex/WorkBuddy/ZCode acceptance records, are documented in
584
- one compatibility matrix.
585
- The Kimi result includes sampled hook-compensation and execution-level BLOCK
586
- paths, not proof that its host enforces every BLOCK or that arbitrary agent
587
- actions are protected. A tested direct-Python hook startup failure was
588
- fail-open. The optional shell bridge blocked a sampled Python startup failure
589
- in a real Kimi host session, but only when the bridge itself ran; config
590
- validation alone cannot prove that the hook is live.
591
- The release adds a focused real-Windows Core gate for Issue #7, but native
592
- cmd/PowerShell execution through every harness and general concurrent-subagent
593
- safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
594
- `cloud-guard`) reuse the same protocol and compensation engine.
595
-
596
- ## guard-lab
597
-
598
- The opt-in, offline honeytoken Lab uses disposable
599
- projects and synthetic, non-secret markers. Its `clean`, `mock-positive`,
600
- `mock-injection`, and `snapshot-positive` controls call no model and make no
601
- external request. A bounded loopback observer records the fake Lab stub, bait
602
- URL, or a validated synthetic snapshot; an explicit post-run scan can detect a
603
- canary in selected output without retaining the raw value.
604
-
605
- The user keeps the true controller and evidence outside the fixture shown to
606
- the tested agent. Broken controls or changed evidence produce `INCONCLUSIVE`,
607
- never an optimistic pass. The Lab cannot observe ordinary file
608
- reads, prove remote transfer, universally block LLM calls, or resist a same-UID
609
- adversary. Start with the zero-token controls and read the
610
- [guard-lab guide](docs/lab/guard-lab.md) before involving a real harness.
611
- The built-in cases report `CALIBRATION_ONLY`. A separate manual
612
- `injection-probe` treats bait contact as `EXPOSURE_OBSERVED`, and `compare`
613
- accepts a mitigation result only after an effective unguarded baseline and a
614
- matched guarded trial with the same protocol, harness/version/model, group,
615
- and task hash. Manual real-model runs also require a user-verified completed
616
- host result, so an exit-0 startup/model failure cannot count as a quiet win.
617
- A quiet baseline stays `INCONCLUSIVE`; no result is a general model or vendor
618
- safety rating.
209
+ | [Getting started](docs/guides/getting-started.md) | Package paths, agent setup prompt and safe verification |
210
+ | [Documentation index](docs/README.md) | Guides, design, Lab, reports, releases and history |
211
+ | [Architecture](docs/design/architecture.md) | Shared Core, compensation and adapter flow |
212
+ | [Threat model](docs/design/threat-model.md) | Trust assumptions and unresolved boundaries |
213
+ | [Compatibility](docs/design/compatibility.md) | Interface and release contracts |
214
+ | [0.2.5-rc2 notes](docs/releases/release-notes-0.2.5-rc2.md) | Current source candidate's changes and validation status |
619
215
 
620
216
  ## Contributing
621
217
 
622
- Bug reports, design proposals, compatibility evidence, documentation fixes,
623
- and focused code changes are welcome. Please start with an
624
- [Issue](https://github.com/mokuyoaxis/agent-guard/issues) for non-trivial or
625
- security-boundary changes, and submit implementations as a focused
626
- [Pull Request](https://github.com/mokuyoaxis/agent-guard/pulls). Read the
627
- [contribution guide](CONTRIBUTING.md) before sharing logs or test evidence;
628
- credentials, private configuration, and unredacted incident data must not be
629
- posted publicly.
218
+ Bug reports, compatibility evidence, documentation fixes and focused code
219
+ changes are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before sharing
220
+ logs. Use [Issues](https://github.com/mokuyoaxis/agent-guard/issues) and
221
+ [Pull Requests](https://github.com/mokuyoaxis/agent-guard/pulls); keep credentials,
222
+ private configuration and unredacted incident records out of public reports.
630
223
 
631
224
  ## Community
632
225