@mokuyoaxis/agent-guard 0.2.2

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 (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
package/README.md ADDED
@@ -0,0 +1,558 @@
1
+ # AGENT-GUARD
2
+
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)
5
+ [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
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.2 source](https://img.shields.io/badge/Source-v0.2.2-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
8
+
9
+ **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
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
+
23
+ The Core is harness-neutral and supports Python 3.9+ and Git. Automatic
24
+ interception still depends on whether the host exposes a compatible hook; a
25
+ Skill by itself does not intercept tool calls. The shared Core, Decision
26
+ Protocol, and Skills define the product; harness adapters are replaceable
27
+ integration bridges rather than the product boundary.
28
+
29
+ > **Agent Guard keeps reversible actions automatic and escalates only when it
30
+ > cannot safely automate them.** It is reliability infrastructure, not a
31
+ > security sandbox: it protects against mistakes, not a malicious agent with
32
+ > equal OS privileges.
33
+
34
+ ## What it looks like
35
+
36
+ ```text
37
+ rm -rf build/ → RELOCATE # an in-scope tree moves to quarantine
38
+ rm -rf . → BLOCK # the workspace root is protected
39
+ git reset --hard → SNAPSHOT # snapshot first when Git state supports it
40
+ git push --force → BLOCK # remote history is not automated
41
+ ```
42
+
43
+ These are illustrative verdicts for supported inputs, not commands to run or
44
+ proof that every harness intercepts them. Ignored, regenerable targets may be
45
+ `ALLOW`; a Git snapshot that cannot be made fails closed. When recovery or safe
46
+ rewriting is possible, the agent can keep working. Otherwise, the guard asks
47
+ the human or blocks the operation.
48
+
49
+ ## Quick start with your coding agent
50
+
51
+ Use the scoped npm package after it is available in the registry, or keep a
52
+ stable Git checkout. Never substitute the unrelated unscoped `agent-guard`
53
+ package.
54
+
55
+ Pinned npm installation into a stable, user-owned prefix:
56
+
57
+ ```sh
58
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
59
+ ```
60
+
61
+ The package root is then
62
+ `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
63
+ Alternatively, clone the source (skip this if you already have a checkout):
64
+
65
+ ```sh
66
+ git clone https://github.com/mokuyoaxis/agent-guard.git
67
+ cd agent-guard
68
+ ```
69
+
70
+ Python 3.9+ and Git are required for the Core; native interception depends on
71
+ the host's hook support. Then give your coding agent the following setup prompt
72
+ (replace the path with your checkout):
73
+
74
+ ```text
75
+ Set up agent-guard for this workspace. Use either an existing Git checkout or
76
+ the exact scoped npm package @mokuyoaxis/agent-guard@0.2.2; never install the
77
+ unscoped package named agent-guard. Before installing, ask me to choose and
78
+ approve a stable user-owned prefix. Treat the checkout or installed package
79
+ root as /absolute/path/to/agent-guard below.
80
+ First identify the current harness and its actual hook/skill capabilities;
81
+ read this README and the matching adapter README. Check Python and Git.
82
+ Install the relevant Skills, then configure a native shell hook only if this
83
+ harness supports one. Preserve existing settings and show me the proposed
84
+ diff before editing user-wide configuration or installing dependencies.
85
+ For Claude Code use adapters/claude/README.md; for Kimi Code use
86
+ adapters/kimi-code/README.md; for DSH use adapters/dsh/README.md.
87
+ For another host, read adapters/INTEGRATION.md and do not invent a native
88
+ hook. If no blocking pre-tool hook is verified, use only Skill/CLI and say
89
+ plainly that automatic interception is not enabled.
90
+ Verify a harmless command and pass a BLOCK-shaped command only as data to
91
+ check.py; never execute a destructive test command. For Claude/Kimi, run the
92
+ local doctor but do not treat its PASS as proof of host interception. Report
93
+ the host version, tool coverage, what was installed, what the host actually
94
+ intercepted, and any unverified paths.
95
+ ```
96
+
97
+ For manual setup and evidence limits, see the
98
+ [adapter matrix](docs/harness-capabilities.md) and the adapter README for your
99
+ host.
100
+
101
+ ## Design principles
102
+
103
+ | Principle | Guarantee |
104
+ |---|---|
105
+ | **Stay in scope** | The guard blocks deletion of the workspace root, `.git`, and outside paths when the operation reaches it |
106
+ | **Make it recoverable** | Supported deletions relocate to `.agent-trash/` with a manifest; destructive Git overwrites snapshot first |
107
+ | **Constrain authorization** | Authorization is session-scoped; a veto downgrades one-way, and only a human restores it |
108
+ | **Leave a durable trail** | Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored |
109
+
110
+ One rule runs through all four: **uncertainty increases restriction.**
111
+
112
+ ## How it decides
113
+
114
+ Each inspected operation is classified by its effect and then mapped to the
115
+ least restrictive decision that preserves the relevant safety or recovery
116
+ guarantee. The stable interface is a Decision Protocol, not a binary
117
+ allow/block check:
118
+
119
+ ```
120
+ Effect → Classifier → Policy → Decision ∈ { ALLOW, SANITIZE, RELOCATE,
121
+ SNAPSHOT, ASK, BLOCK }
122
+ + ReasonCode (stable, machine-readable)
123
+ + Explanation (human-facing)
124
+ + RecoveryPlan (txids, strategy)
125
+ ```
126
+
127
+ | Tier | Decisions | What the agent experiences |
128
+ |---|---|---|
129
+ | **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) |
130
+ | **AMBIGUOUS** | `ASK` | Single-execution authorization (`ASK_ONCE`) — e.g. compound shapes the guard cannot safely automate |
131
+ | **FORBIDDEN** | `BLOCK` | Refused with reason and remediation; never askable |
132
+
133
+ Precedence when several decisions meet in one operation, weakest to strongest:
134
+
135
+ ```
136
+ ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK
137
+ ```
138
+
139
+ `SANITIZE` ranks *below* `ASK` deliberately: it is automatic (SAFE tier),
140
+ while `ASK` forfeits automation. A payload carrying both a sanitizable secret
141
+ and a shape that cannot be rewritten must `ASK` — you cannot silently proceed
142
+ when part of the emission is uninspectable.
143
+
144
+ True effect uncertainty (`$VAR` targets, `bash -c`, `find -delete`, stdin-fed
145
+ lists) stays on the BLOCK path: allowing it would forfeit the core guarantee.
146
+ Adapters map decisions onto their harness natively — DSH `PreToolDecision`,
147
+ Claude Code PreToolUse `ask`, or a deny carrying the explanation where no ask
148
+ exists.
149
+
150
+ ## What Agent Guard includes
151
+
152
+ ### `delete-guard`
153
+
154
+ Answers *"if this destroys something, can we come back?"* It runs before a
155
+ delete or destructive Git action when invoked through a supported adapter or
156
+ CLI, and compensates first when recovery is possible.
157
+
158
+ ### `exfil-guard`
159
+
160
+ Answers *"if this leaves the machine, was it supposed to?"* Its cooperative
161
+ CLI checks text before an emission when the payload owner invokes it, returning
162
+ a redaction or escalation decision for supported patterns.
163
+
164
+ ### `recovery-audit`
165
+
166
+ The incident-response companion for cases where prevention never ran or did not
167
+ cover the path. It establishes source precedence, distinguishes recovered bytes
168
+ from reconstructed behavior and known gaps, audits replay tooling, and keeps
169
+ landing, commit, push, and release as separate authorization gates.
170
+
171
+ `delete-guard` and `exfil-guard` are the two preventive guard branches;
172
+ `recovery-audit` handles evidence-led recovery after the fact.
173
+
174
+ ## recovery-audit
175
+
176
+ Sometimes prevention never ran: a harness had no adapter, a subagent bypassed
177
+ the expected path, or an over-broad command removed the workspace before anyone
178
+ could intervene. The working tree may be gone while the coding agent's session
179
+ cache still preserves successful patches, file snapshots, tool results, diffs,
180
+ and command context.
181
+
182
+ `recovery-audit` turns those remnants, Git remotes/reflogs/stashes, editor or
183
+ tool caches, build artifacts, and project plans into an evidence-led recovery:
184
+
185
+ - every unit is labelled **recovered**, **reconstructed**, or **missing**;
186
+ - recorded tool effects are replayed in chronology and checked for divergence;
187
+ - repeated replay must produce a byte-identical tree;
188
+ - landing, commit, push, and release remain separate authorization gates.
189
+
190
+ It is not filesystem undelete and cannot recreate bytes no surviving source
191
+ captured. Its promise is a fast, auditable path to the strongest project state
192
+ the evidence actually supports, with gaps reported instead of hidden.
193
+
194
+ ## exfil-guard
195
+
196
+ `exfil-guard` checks text before an agent writes, sends, commits, or pushes it
197
+ **when the payload owner calls its CLI**. It also offers an explicit, read-only
198
+ safe view of selected JSON/dotenv configuration files. The text scanner is
199
+ designed to catch two accidental disclosure classes: **known credentials**
200
+ and **host-identifying absolute paths**. Depending on the channel, it can
201
+ allow the payload, return a redaction plan, ask for a human decision, or block
202
+ the emission.
203
+
204
+ It is a prevention and redaction guard, not a compensation engine: after an
205
+ emission there is nothing to recover. It is also **not a security sandbox** and
206
+ does not attempt to stop adversarial exfiltration by an agent with equal OS
207
+ privileges.
208
+
209
+ ### Decisions exfil-guard can return
210
+
211
+ The full Decision Protocol applies, but only four classes are reachable for
212
+ a text payload (`RELOCATE`/`SNAPSHOT` belong to delete-guard — the guard
213
+ cannot rewrite what it did not write):
214
+
215
+ | Decision | Meaning | Example |
216
+ |---|---|---|
217
+ | `ALLOW` | nothing matched, a documented placeholder, or a workspace-relative path | `echo "hello" \| check_span.py` |
218
+ | `SANITIZE` | a redaction plan is returned; the *payload owner* rewrites and emits | a real key on `file-write` / `llm-request` |
219
+ | `ASK` | the channel cannot be rewritten and cannot be taken back | a host path on `shell-stdout` |
220
+ | `BLOCK` | refuse: immutable/remote history, an un-scannable payload, invalid config | a credential in `git-push-payload` |
221
+
222
+ ### What is detected
223
+
224
+ **T1 vendor credential patterns** (`secret/*`, deterministic, near-zero
225
+ false positives). Rule ids: `secret/openai-key`, `secret/github-token`,
226
+ `secret/aws-access-key-id`, `secret/gitlab-token`, `secret/slack-token`,
227
+ `secret/stripe-key` (live keys only — `sk_test_` is exempt), `secret/jwt`
228
+ (structural: the header must base64-decode to JSON containing `alg`), and
229
+ `secret/private-key-block` (whole `-----BEGIN ... PRIVATE KEY-----` block,
230
+ redacted in one piece). See
231
+ [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md)
232
+ for the frozen table.
233
+
234
+ **Value-free secret references** (`secret/source-reference`). The guard
235
+ classifies an environment variable's *name* (`*KEY*`, `*TOKEN*`,
236
+ `*SECRET*`, `*PASSWORD*`, `*CRED*`, `*AUTH*`) and a secret-store *file name*
237
+ (`.env`, `*.pem`, `id_rsa*`, `.netrc`, `kubeconfig`, ...), and detects
238
+ whole-environment expansions (`printenv`, `env | ...`, `cat
239
+ /proc/self/environ`). This scanner **does not resolve the variable value**;
240
+ that does not certify unrelated Guard output or existing audit records as
241
+ secret-free.
242
+
243
+ **Host-identifying paths** (`path/*`). `path/workspace-relative` is `ALLOW`
244
+ (the workspace is exempt); `path/system` (`/usr`, `/etc`, `C:\Windows`) is
245
+ `ALLOW`; `path/host-absolute` (under `HOME`/`TEMP`, a CI root, or a
246
+ workspace ancestor) is `SANITIZE`; `path/generic-absolute` (no host
247
+ correlation) is `ASK`; `path/device` (UNC, `\\?\`, pipes) is `SANITIZE`.
248
+
249
+ ### Channels determine the disposition
250
+
251
+ A channel is defined by two facts: can it be **rewritten**, and does the
252
+ emission **persist**? `rewritable` is what makes `SANITIZE` meaningful;
253
+ `persistence` is what justifies `BLOCK`.
254
+
255
+ | Channel | Rewritable | Persistence | Default |
256
+ |---|---|---|---|
257
+ | `llm-request` | yes | remote | SANITIZE |
258
+ | `file-write` | yes | workspace | SANITIZE |
259
+ | `forge-comment` / `issue-body` / `pr-description` | yes | public | SANITIZE |
260
+ | `git-commit-message` | yes (rewrite argv) | remote history | **BLOCK** |
261
+ | `git-push-payload` | no | **remote** | **BLOCK** |
262
+ | `shell-stdout` | **no** | local transcript | ASK |
263
+ | `shell-file-redirect` | yes | local | ASK |
264
+ | `archive-upload` | yes | remote | ASK |
265
+ | `process-argv` | yes | local | ASK |
266
+
267
+ An unknown channel name is a configuration defect, not "no risk":
268
+ `check_span.py` returns `BLOCK_OUTPUT_UNSCANNABLE`, never an implicit ALLOW.
269
+
270
+ ### Usage
271
+
272
+ `check_span.py` reads the payload on **stdin** and is a pure function — it
273
+ never writes, never rewrites, and never prints the match. `sanitize.py`
274
+ applies the plan the guard returned.
275
+
276
+ ```bash
277
+ # a credential on a rewritable channel -> SANITIZE, exit 0
278
+ echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write
279
+
280
+ # a credential bound for remote history -> BLOCK, exit 2
281
+ echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload
282
+
283
+ # apply the redaction plan (format preserved: sk-<REDACTED>)
284
+ echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write
285
+ ```
286
+
287
+ Exit code contract: `0` = ALLOW/SANITIZED · `2` = BLOCK · `3` = ASK ·
288
+ `1` = ERROR. Use `--json` for the machine-readable verdict (offsets, rule ids
289
+ and placeholders only — **never the matched bytes**), and `--path` to enable
290
+ the repo-local exemption file for the file being written.
291
+
292
+ ### Read a config without printing its values
293
+
294
+ Introduced in the `0.2.0` source; this CLI is **not** in the earlier
295
+ `0.2.0-rc2` preview tag.
296
+
297
+ ```bash
298
+ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
299
+ python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json
300
+ ```
301
+
302
+ The path must be relative to that workspace. The JSON output preserves field
303
+ names and structure, plus scalar types and `set`/`empty` states, but **never
304
+ scalar values**. Known secret-shaped field names are hidden; unknown secrets
305
+ in field names remain a limitation. Only UTF-8 JSON and a strict, single-line
306
+ dotenv subset are supported (256 KiB maximum, 16 levels, 2048 nodes). The
307
+ CLI refuses symlinks, hardlinks, special files, unsafe paths, malformed input,
308
+ and platforms without safe descriptor-relative reads. Exit `0` means a view
309
+ was produced, `2` means refused, and `1` means an internal error. This view
310
+ is for diagnosis only: do not write it back over the original config. It
311
+ does not intercept ordinary file reads made by a harness.
312
+
313
+ ### Relationship to delete-guard
314
+
315
+ They are two halves of the same promise, on opposite sides of the action:
316
+
317
+ | | `delete-guard` | `exfil-guard` |
318
+ |---|---|---|
319
+ | Question | "can we come back?" | "was this supposed to leave?" |
320
+ | Guards | *before a delete* | *before an emission* |
321
+ | Response | compensate, then proceed | redact, then emit |
322
+ | Failure cost | recoverable via txid | **irreversible** |
323
+ | Entry point | `check.py -- <command>` | `check_span.py` (stdin) |
324
+
325
+ They share the vocabulary (`core/policy.py`), the aggregation (`worst()`),
326
+ the exemption discipline, and the audit log. `worst()` is shared by both
327
+ guards, which is why `SANITIZE` had to be ranked once, not twice.
328
+
329
+ ### Coverage and limitations
330
+
331
+ This is stated plainly, because a reliability tool that overstates its reach
332
+ is a false security claim:
333
+
334
+ - **Not a sandbox.** It does not prevent adversarial exfiltration. An agent
335
+ that obfuscates a secret to evade the scanner is out of scope; this
336
+ catches *accidents*.
337
+ - **Channels with no hook are unreachable by construction.** A hosted model
338
+ call with no proxy, the model's own tool calls, content produced *inside* a
339
+ program, and the human clipboard get **no verdict at all** — no coverage is
340
+ claimed there. See `references/channels.md` and
341
+ [docs/secret-guard-analysis.md](docs/secret-guard-analysis.md) §2.4 for
342
+ the reachability table this claim is traceable to.
343
+ - **Not a file scanner.** It is not a gitleaks replacement; it scans what the
344
+ guard can see *on the way out*.
345
+ - **No history rewriting.** Detecting a secret already in Git history is a
346
+ report at most. Rewriting history is a human action with its own risks.
347
+ - **No T3 entropy detector in this release.** It is the single largest
348
+ false-positive source, and the named scenarios do not require it.
349
+
350
+ ## Manual, harness-neutral usage
351
+
352
+ The Core has zero third-party dependencies. Requirements: Python 3.9+, POSIX
353
+ shell, and Git.
354
+
355
+ ```bash
356
+ # delete something - it is quarantined, not destroyed:
357
+ python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"
358
+
359
+ # inspect and undo:
360
+ python3 skills/delete-guard/scripts/status.py
361
+ python3 skills/delete-guard/scripts/restore.py list
362
+ python3 skills/delete-guard/scripts/restore.py <txid>
363
+
364
+ # quarantine maintenance (dry plan by default):
365
+ python3 skills/delete-guard/scripts/gc.py
366
+ ```
367
+
368
+ A harness adapter can invoke the guard before a supported shell command and
369
+ map its exit status to the host's own tool decision:
370
+
371
+ ```text
372
+ python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
373
+ exit 0 → host may run the original command
374
+ exit 2 → deny
375
+ exit 3 → ask the human if supported; otherwise deny
376
+ exit 1 → guard error; fail closed
377
+ ```
378
+
379
+ ## What gets protected
380
+
381
+ These examples assume the command reaches the guard and its targets meet the
382
+ stated conditions; see the [capability matrix](docs/harness-capabilities.md)
383
+ for what each host has actually demonstrated.
384
+
385
+ ```text
386
+ rm -rf build/ → RELOCATE (tree quarantined, command proceeds)
387
+ rm -rf . → BLOCK (workspace root)
388
+ rm -rf $DIR/ → BLOCK (unresolvable target: fail closed)
389
+ rm *.log → BLOCK (opaque glob; safe_delete expands it)
390
+ cd X && rm -rf build → ASK_ONCE (COMPOUND_CWD_DELETE)
391
+ touch f && rm f → ASK_ONCE (COMPOUND_CREATE_DELETE)
392
+ git clean -fd → RELOCATE (enumerate via -n, relocate, proceed)
393
+ git reset --hard → SNAPSHOT (when a Git snapshot can be made)
394
+ git push --force → BLOCK (remote history is never automated)
395
+ node_modules/ (ignored) → ALLOW (provably regenerable)
396
+ quarantine full → BLOCK (never fall back to permanent delete)
397
+ ```
398
+
399
+ ## Integration and validation matrix
400
+
401
+ [![Node.js 20 smoke](https://img.shields.io/badge/Node.js-20%20smoke-339933?logo=nodedotjs&logoColor=white)](.github/workflows/ci.yml)
402
+ [![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)
403
+ [![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)
404
+ [![ZCode win32 CLI evaluated](https://img.shields.io/badge/ZCode-win32%20CLI%20evaluated-7C5CE0)](docs/test-report-zcode-glm-flash.md)
405
+ [![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)
406
+ [![Kimi Code 2.1.1 K3 Bash BLOCK](https://img.shields.io/badge/Kimi%20Code%202.1.1-K3%20Bash%20BLOCK-5B9BD5)](docs/test-report-kimi-code-block.md)
407
+
408
+ "The Core works", "a Skill-guided agent used it", and "the harness
409
+ intercepts every matching tool call" are separate claims. This table keeps
410
+ those evidence levels explicit:
411
+
412
+ | Harness / tested version | Integration path | Evidence and limit |
413
+ |---|---|---|
414
+ | **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. |
415
+ | **DSH 0.1.5-rc.1** | [Native pre-execute adapter](adapters/dsh/README.md) | [Real-host, no-model packaged-plugin probe](docs/test-report-dsh-0.1.5-rc.1.md): benign execution, execution-level `BLOCK`, absent bypass marker and loaded-adapter Core failure; model/Agent and non-`bash` paths unverified. |
416
+ | **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. |
417
+ | **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. |
418
+ | **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 maintainer-confirmed official K3 relay; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open. |
419
+ | **Other / unlisted hosts** | [Self-adaptation guide](adapters/INTEGRATION.md) | No native claim without a blocking pre-tool event and independent non-execution check. |
420
+
421
+ For agent-led setup: identify the actual host version and tool names, follow
422
+ the matching guide above, preserve existing settings, then report separate
423
+ configuration, local-probe, and real-host evidence. For an unlisted host,
424
+ follow the [self-adaptation checklist](adapters/INTEGRATION.md); a prompt or
425
+ adapter exit code alone is not proof of interception. Ask before changing
426
+ user-wide settings, security policy, or dependencies.
427
+
428
+ `tests/test_conformance.py` checks the shared Core and Claude adapter; DSH
429
+ has a smoke test and Kimi has targeted adapter tests. The Kimi observations
430
+ above cover only the tested calls, not every shell construct or a general
431
+ concurrent-agent safety guarantee.
432
+ Run `python3 doctor.py kimi --probe` or `python3 doctor.py claude --probe`
433
+ to check a selected configuration file and the local shell bridge without a
434
+ model call. Add `--json` for machine-readable `configuration`, `local_probe`,
435
+ and `host_interception` statuses. The last status is always `UNVERIFIED`:
436
+ this doctor cannot prove that a live session loaded or enforced the hook.
437
+ Add `--check-drift` to query the local host version and compute privacy-safe
438
+ configuration/runtime fingerprints. It reports `CURRENT`, `STALE`,
439
+ `DRIFTED`, `BROKEN`, or `UNVERIFIED`; even `CURRENT` is static preflight
440
+ evidence, not interception proof. Optional create-new baselines contain only
441
+ the parsed version and SHA-256 fingerprints. See the
442
+ [host drift guide](docs/host-drift.md) for the status and baseline contract.
443
+ An explicit `--live-sentinel` can then spend one configured model call in a
444
+ private blank fixture. It reports `PASS`, `FAIL`, or `INCONCLUSIVE` with
445
+ `NONE`/`NOTICE`, `CRITICAL`, or `WARNING`; marker absence alone never passes.
446
+ It retains a hashed/redacted result but not raw model output. This is a
447
+ reliability probe for a trusted provider, not a sandbox for a malicious model.
448
+ The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and
449
+ hook adapter continue to support Python 3.9+.
450
+ See the [Kimi](adapters/kimi-code/README.md) and
451
+ [Claude](adapters/claude/README.md) adapter guides.
452
+ See [harness capabilities and evidence levels](docs/harness-capabilities.md)
453
+ for the per-host scope and execution-level acceptance criteria.
454
+
455
+ ## Repository layout
456
+
457
+ ```
458
+ agent-guard/
459
+ ├── skills/delete-guard/ # agent-facing skill: SKILL.md + CLI scripts
460
+ ├── skills/exfil-guard/ # egress skill: check_span.py · sanitize.py
461
+ ├── skills/recovery-audit/ # evidence-led repository audit and recovery
462
+ ├── core/ # classifier · policy · recovery · audit · redaction
463
+ ├── doctor.py # local configuration, probes, and drift preflight
464
+ ├── live_sentinel.py # opt-in real-host sentinel and alarm evidence
465
+ ├── adapters/INTEGRATION.md # checklist for an unlisted host
466
+ ├── adapters/claude/ # Claude Code PreToolUse hook adapter
467
+ ├── adapters/kimi-code/ # Kimi Code PreToolUse hook adapter
468
+ ├── adapters/dsh/ # DeepSeek Harness integration bridge
469
+ ├── adapters/codex/harness/# CLI acceptance driver; not a native hook
470
+ ├── tests/ # unittest suites incl. cross-harness conformance
471
+ └── docs/ # architecture · threat-model · friction log
472
+ ```
473
+
474
+ Skills guide agent behavior; constraints live in Core. Future
475
+ `git-guard`, `database-guard`, `cloud-guard` skills plug into the same
476
+ compensation engine without restructuring.
477
+
478
+ ## Documentation
479
+
480
+ | Read | For |
481
+ |---|---|
482
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
483
+ | [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
484
+ | [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
485
+ | [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 |
486
+ | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
487
+ | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
488
+ | [adapters/INTEGRATION.md](adapters/INTEGRATION.md) | self-adaptation checklist for an unlisted host |
489
+ | [docs/threat-model.md](docs/threat-model.md) | honest limits: what this is and is not |
490
+ | [docs/friction.md](docs/friction.md) | what real agents taught us (F1–F11) |
491
+ | [docs/development-note-unguarded-deletion.md](docs/development-note-unguarded-deletion.md) | de-identified incident exploration and the recovery-aware direction |
492
+ | [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) |
493
+ | [docs/test-report-dsh-0.1.5-rc.1.md](docs/test-report-dsh-0.1.5-rc.1.md) | current DSH packaged-plugin and execution-level `bash` acceptance |
494
+ | [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) |
495
+ | [skills/recovery-audit/SKILL.md](skills/recovery-audit/SKILL.md) | evidence hierarchy, deterministic replay, recovery and landing gates |
496
+ | [skills/delete-guard/references/policy.md](skills/delete-guard/references/policy.md) | full rule table and decision codes |
497
+ | [skills/exfil-guard/references/rules.md](skills/exfil-guard/references/rules.md) | exfil rule table, reason codes, exemption format, audit shape |
498
+ | [skills/exfil-guard/references/channels.md](skills/exfil-guard/references/channels.md) | egress-channel taxonomy and the unreachable channels |
499
+
500
+ ## Status & roadmap
501
+
502
+ The source version is **v0.2.2**. The published `v0.2.0` baseline includes
503
+ recoverable destructive actions, cmd/PowerShell dialect parsing, the
504
+ `exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
505
+ Later source releases add Claude/Kimi POSIX hook bridges, bounded host
506
+ evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
507
+ current DSH package acceptance. See the
508
+ [0.2.2 notes](docs/release-notes-0.2.2.md) for exact scope and
509
+ [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
510
+ publication status; a source version is not itself a published Release.
511
+
512
+ The release identity is harness-neutral. Existing DSH and Claude adapters,
513
+ Codex/ZCode acceptance evidence, and the bounded Kimi exercise are entries
514
+ in a growing compatibility matrix, not separate definitions of the product.
515
+ The Kimi result includes sampled hook-compensation and execution-level BLOCK
516
+ paths, not proof that its host enforces every BLOCK or that arbitrary agent
517
+ actions are protected. A tested direct-Python hook startup failure was
518
+ fail-open. The optional shell bridge blocked a sampled Python startup failure
519
+ in a real Kimi host session, but only when the bridge itself ran; config
520
+ validation alone cannot prove that the hook is live.
521
+ Real Windows end-to-end coverage and general concurrent-subagent safety
522
+ also remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
523
+ `cloud-guard`) reuse the same protocol and compensation engine.
524
+
525
+ ## 0.2.x preview: guard-lab
526
+
527
+ Planned, **not included in 0.2.2**: an opt-in, offline honeytoken lab
528
+ using disposable projects and synthetic, non-secret markers. It will compare
529
+ normal tasks with prompt-injection attempts, and separately observe whether a
530
+ harness indexes or exports files without an agent-requested read. Positive and
531
+ negative controls, an independent observer, and evidence labels will keep a
532
+ mere read request distinct from a confirmed external transfer. No real
533
+ credentials or automatic background monitoring are part of the plan. This is
534
+ a bounded diagnostic experiment, not a guarantee against a malicious model
535
+ or harness.
536
+
537
+ ## Contributing
538
+
539
+ Bug reports, design proposals, compatibility evidence, documentation fixes,
540
+ and focused code changes are welcome. Please start with an
541
+ [Issue](https://github.com/mokuyoaxis/agent-guard/issues) for non-trivial or
542
+ security-boundary changes, and submit implementations as a focused
543
+ [Pull Request](https://github.com/mokuyoaxis/agent-guard/pulls). Read the
544
+ [contribution guide](CONTRIBUTING.md) before sharing logs or test evidence;
545
+ credentials, private configuration, and unredacted incident data must not be
546
+ posted publicly.
547
+
548
+ ## Community
549
+
550
+ [![LINUX DO community link](assets/linux-do-community.svg)](https://linux.do/t/topic/2942799)
551
+
552
+ This project-made banner links to our
553
+ [LINUX DO project post](https://linux.do/t/topic/2942799). It does not imply
554
+ official endorsement by the community.
555
+
556
+ ## License
557
+
558
+ MIT — see [LICENSE](LICENSE).