@mokuyoaxis/agent-guard 0.2.3 → 0.2.5-rc1

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