@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
@@ -0,0 +1,462 @@
1
+ # agent-guard Claude Code Harness Live-Test Report
2
+
3
+ **Date:** 2026-09-14
4
+ **Repository:** `apigogo/agent-guard`
5
+ **Baseline commit:** `90878d6` (`main`)
6
+ **Interception mode:** Claude Code `PreToolUse` hook → `adapters/claude/pre_tool_use.py` → `check.py --enforce`
7
+ **Harness:** Claude Code CLI **2.1.270** (npm `@anthropic-ai/claude-code`, native Linux x64 build)
8
+ **Model:** mocked — a scripted Anthropic Messages endpoint (`adapters/claude/harness/mock_anthropic_api.mjs`)
9
+ **Sandbox:** inherit-session (no additional backend)
10
+ **Platform:** Linux 5.4.241 (x86_64, container), Python 3.11.2, Node.js v24.21.0, git 2.39.5
11
+
12
+ ## Executive summary
13
+
14
+ Two previously unverified claims are now closed.
15
+
16
+ 1. **The `python3` hardcode is fixed and the failure is reproducible.**
17
+ `adapters/claude/pre_tool_use.py` spawned the guard as `["python3", ...]`.
18
+ On a host that provides only `python`, every interception failed closed —
19
+ the guard was installed but *unusable*, and the failure was silent apart
20
+ from a stderr line the model may ignore. The child is now spawned with
21
+ `sys.executable`. The A/B below was run **inside the real harness** on an
22
+ identical environment: pre-fix the hook exits 2 with
23
+ `guard infrastructure error (fail-closed): [Errno 2] No such file or
24
+ directory: 'python3'`; post-fix the same `rm -rf build` returns a clean
25
+ `RELOCATE_TREE` allow and quarantines the tree. Two regression tests pin
26
+ both the allow and the block path on a `PATH` without `python3`.
27
+
28
+ 2. **The Claude Code adapter works end-to-end against a real harness
29
+ session.** A real Claude Code CLI, driving a real Bash tool through a real
30
+ project `.claude/settings.json` hook, hit RELOCATE, BLOCK, and ASK exactly
31
+ as `adapters/claude/README.md` documents. RELOCATE emitted
32
+ `permissionDecision: "allow"` and moved `build/` into
33
+ `.agent-trash/`; BLOCK exited 2 and the guard's stderr reached the model
34
+ as a hook error; ASK emitted `permissionDecision: "ask"` and, with no
35
+ interactive approver, Claude Code declined the call and the command never
36
+ ran. Each case left a matching `.agent-trash/audit.jsonl` record.
37
+
38
+ A control run (benign `git status`) confirms the fast path costs nothing:
39
+ no `.agent-trash/` is created and the hook stays silent.
40
+
41
+ **This is still not a security boundary.** The mock endpoint means the
42
+ *tool-selection* behaviour of a real model is out of scope here — what was
43
+ measured is the interception mechanism, which is model-independent. The two
44
+ upstream reports' "Claude Code live session at `v0.1.1`" item is advanced to
45
+ a real harness; a real-model forward test on Claude Code remains open.
46
+
47
+ ## Scope and methodology
48
+
49
+ 1. Full deterministic suite — `GIT_CONFIG_GLOBAL=/dev/null python3 -m
50
+ unittest discover tests` — run as a non-root user, as CI does.
51
+ 2. `node tests/test_dsh_adapter.mjs` — DSH adapter smoke, for regression.
52
+ 3. `python3 -m unittest tests.test_conformance` — the adapter conformance
53
+ suite, including the two new `python3`-free regression tests.
54
+ 4. Real-harness scenarios, each in a fresh disposable git project containing
55
+ tracked source (`src/main.py`), a regenerable `build/` tree, an ignored
56
+ `app.log`, and an untracked, potentially valuable `NOTES.md`:
57
+
58
+ - **RELOCATE** — `rm -rf build`
59
+ - **BLOCK** — `rm -rf .`
60
+ - **ASK** — `touch f && rm f`
61
+ - **control** — `git status --short` (benign fast path)
62
+
63
+ 5. The no-`python3` A/B: the same scenario re-run with the hook invoked as
64
+ `python` and the CLI's `PATH` containing `python` but no `python3`,
65
+ once with the pre-fix adapter and once with the fix.
66
+
67
+ Every scenario ran with the **unmodified real hook** and the real
68
+ `check.py --enforce`; nothing was stubbed on the agent-guard side. Only the
69
+ model was replaced. No repository source was modified during behavioural
70
+ testing, and no destructive probe touched anything outside a temp fixture.
71
+
72
+ ### Why a mock model is the right instrument
73
+
74
+ Claude Code accepts any Anthropic-protocol endpoint via `ANTHROPIC_BASE_URL`
75
+ + `ANTHROPIC_AUTH_TOKEN`. The subject under test is the interception path —
76
+ hook discovery, payload shape, guard invocation, exit-code semantics, and the
77
+ permission decision the harness acts on — none of which depend on which model
78
+ produced the `tool_use`. Scripting the turns makes each decision reachable
79
+ deterministically and removes network variance, at the cost of not measuring
80
+ model behaviour (see Limitations).
81
+
82
+ The mock advances its script **only when the client returns a `tool_result`**,
83
+ so one scripted turn equals one harness turn and the destructive command is
84
+ guaranteed to actually execute and be observed.
85
+
86
+ ## Finding: the `python3` hardcode disabled the guard (fixed)
87
+
88
+ **Symptom.** `pre_tool_use.py` line 88 spawned the guard as
89
+ `["python3", CHECK, "--enforce", ...]`. `python3` is a POSIX convention;
90
+ Windows (and stripped container images) ship `python` only. Where `python3`
91
+ is absent, the `subprocess.run` raised, and the adapter's fail-closed handler
92
+ returned exit 2 with:
93
+
94
+ ```
95
+ [agent-guard] guard infrastructure error (fail-closed): [Errno 2] No such file or directory: 'python3'
96
+ ```
97
+
98
+ Every Bash command that matched the destructive prefilter was therefore
99
+ blocked — including commands the guard would have allowed. The guard's
100
+ recoverability promise was replaced by a blanket denial, and on Windows this
101
+ made the adapter non-functional (the same class of defect as the
102
+ `os.uname()` finding in the ZCode report).
103
+
104
+ **Reproduced inside the real harness.** With the pre-fix adapter, a
105
+ `PATH` exposing `python` but not `python3`, and `rm -rf build`:
106
+
107
+ ```json
108
+ {
109
+ "stdout": "",
110
+ "stderr": "[agent-guard] guard infrastructure error (fail-closed): [Errno 2] No such file or directory: 'python3'\n",
111
+ "exit_code": 2,
112
+ "outcome": "error"
113
+ }
114
+ ```
115
+
116
+ **Fix.** One line — spawn the guard with the interpreter already running the
117
+ adapter:
118
+
119
+ ```diff
120
+ - ["python3", CHECK, "--enforce", "--json", "--", command],
121
+ + [sys.executable, CHECK, "--enforce", "--json", "--", command],
122
+ ```
123
+
124
+ This is strictly more correct than resolving `python3` from `PATH`: the
125
+ guard runs under the *same* interpreter as the adapter, so an interpreter
126
+ mismatch cannot silently change core behaviour.
127
+
128
+ **Verified — same environment, post-fix:**
129
+
130
+ ```json
131
+ {
132
+ "stdout": "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"[agent-guard] RELOCATE_TREE: compensated automatically (1 relocation(s)); restorable via txid\"}}\n",
133
+ "stderr": "",
134
+ "exit_code": 0,
135
+ "outcome": "success"
136
+ }
137
+ ```
138
+
139
+ and the matching audit record:
140
+
141
+ ```json
142
+ {"command": "rm -rf build", "compensations": [{"moved": 1, "strategy": "relocate", "txid": "20260914-051016-2d3c9915"}], "event": "enforce-proceed", "guard_latency_ms": 1.8, "session": "49b2d3e4-6852-4b9f-99f7-19348071252c", "ts": "2026-09-14T05:10:16Z"}
143
+ ```
144
+
145
+ **Regression coverage** (`tests/test_conformance.py`) drives the adapter with
146
+ a `PATH` that has `python` but no `python3` —
147
+ `test_adapter_spawns_guard_with_sys_executable` (allow + quarantine must
148
+ still happen) and `test_adapter_blocking_still_works_without_python3_on_path`
149
+ (hard boundary must still block, and must not report an infrastructure
150
+ error). Both fail on the pre-fix adapter with exactly the reported symptom and
151
+ pass after it — the red/green pair is what makes the fix load-bearing rather
152
+ than merely different.
153
+
154
+ ## Results
155
+
156
+ ### Deterministic release checks
157
+
158
+ | Check | Result |
159
+ |---|---|
160
+ | Python unit, CLI, policy, recovery, GC, conformance suite (non-root, as CI) | PASS, 86/86 |
161
+ | `tests/test_conformance` incl. new `python3`-free regression tests | PASS, 9/9 |
162
+ | Same suite on the pre-fix adapter | FAIL (2) — reproduces the issue |
163
+ | DSH adapter Node smoke test | PASS |
164
+ | Repository worktree after evaluation | Clean |
165
+
166
+ The `python3`-free tests inject a `PATH` containing both `python` **and**
167
+ `git`: the core shells out to `git` for workspace discovery and snapshot
168
+ work independently of the spawn fix, so removing it would test the wrong
169
+ thing.
170
+
171
+ ### Real-harness interception matrix
172
+
173
+ | Scenario | Command | Hook exit | Hook output | Guard verdict observed | Executed? |
174
+ |---|---|---|---|---|---|
175
+ | RELOCATE | `rm -rf build` | 0 | `permissionDecision: "allow"` + `RELOCATE_TREE` | `RELOCATE_TREE` | yes, after quarantine |
176
+ | BLOCK | `rm -rf .` | 2 | stderr teaching message | `BLOCK_PROTECTED_PATH` | **no** |
177
+ | ASK | `touch f && rm f` | 0 | `permissionDecision: "ask"` + `COMPOUND_CREATE_DELETE` | `COMPOUND_CREATE_DELETE` | **no** (not approved) |
178
+ | control | `git status --short` | 0 | silent | none (prefilter fast path) | yes |
179
+
180
+ All four matched the documented mapping in `adapters/claude/README.md`.
181
+
182
+ ### Evidence per decision
183
+
184
+ **RELOCATE — quarantined before the original command ran.**
185
+
186
+ ```json
187
+ {"hook_name": "PreToolUse:Bash", "hook_event": "PreToolUse",
188
+ "stdout": "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\", \"permissionDecisionReason\": \"[agent-guard] RELOCATE_TREE: compensated automatically (1 relocation(s)); restorable via txid\"}}\n",
189
+ "stderr": "", "exit_code": 0, "outcome": "success"}
190
+ ```
191
+
192
+ `.agent-trash/audit.jsonl`:
193
+
194
+ ```json
195
+ {"command": "rm -rf build", "compensations": [{"moved": 1, "strategy": "relocate", "txid": "20260914-050923-48f8e9a0"}], "event": "enforce-proceed", "guard_latency_ms": 2.3, "session": "a8c61691-4ec0-4151-b128-fd4c6b221a3d", "ts": "2026-09-14T05:09:23Z"}
196
+ ```
197
+
198
+ `.agent-trash/manifest.jsonl` — durable intent precedes the move:
199
+
200
+ ```json
201
+ {"meta": {"command": "rm -rf build", "tool": "check --enforce"}, "strategy": "relocate", "ts": "2026-09-14T05:09:23Z", "txid": "20260914-050923-48f8e9a0", "type": "tx-start"}
202
+ {"origin_path": "<run>/project/build", "raw": "build", "trash_path": "<run>/project/.agent-trash/20260914-050923-48f8e9a0/build", "ts": "2026-09-14T05:09:23Z", "txid": "20260914-050923-48f8e9a0", "type": "relocate-intent"}
203
+ {"origin_path": "<run>/project/build", "trash_path": "<run>/project/.agent-trash/20260914-050923-48f8e9a0/build", "ts": "2026-09-14T05:09:23Z", "txid": "20260914-050923-48f8e9a0", "type": "relocate"}
204
+ ```
205
+
206
+ Post-state: `build/` absent from the workspace, `build/o.js` present under
207
+ `.agent-trash/20260914-050923-48f8e9a0/build/`. The full roundtrip closes:
208
+
209
+ ```
210
+ $ python3 skills/delete-guard/scripts/restore.py 20260914-050923-48f8e9a0
211
+ restored: /tmp/<run>/project/build
212
+ $ cat build/o.js
213
+ artifact
214
+ ```
215
+
216
+ **BLOCK — the model, not just the user, is told why.**
217
+
218
+ ```json
219
+ {"hook_name": "PreToolUse:Bash", "hook_event": "PreToolUse", "stdout": "",
220
+ "stderr": "[agent-guard] BLOCKED [BLOCK_PROTECTED_PATH] Target is the workspace root or git metadata. Hard boundary - not askable. (protected: workspace-root (.)) | Restate with explicit workspace-relative paths, or use the safe-delete flow. Do NOT circumvent the guard.\n",
221
+ "exit_code": 2, "outcome": "error"}
222
+ ```
223
+
224
+ Claude Code converted the exit-2 stderr into a tool error handed back to the
225
+ model, which is the teaching channel the adapter intends:
226
+
227
+ ```
228
+ PreToolUse:Bash hook error: [python3 .../pre_tool_use.py]: [agent-guard] BLOCKED
229
+ [BLOCK_PROTECTED_PATH] ... Do NOT circumvent the guard.
230
+ ```
231
+
232
+ `.agent-trash/audit.jsonl`:
233
+
234
+ ```json
235
+ {"code": "BLOCK_PROTECTED_PATH", "command": "rm -rf .", "event": "enforce-block", "guard_latency_ms": 0.1, "reasons": ["protected: workspace-root (.)"], "session": "4ca9b011-3faa-4e41-b960-f1d4d17d6d16", "ts": "2026-09-14T05:09:33Z"}
236
+ ```
237
+
238
+ The workspace afterwards is byte-for-byte intact — `src/`, `build/`,
239
+ `NOTES.md`, `app.log`, and `.git/` all still present. Nothing was deleted.
240
+
241
+ **ASK — escalated once, and nothing ran without approval.**
242
+
243
+ ```json
244
+ {"hook_name": "PreToolUse:Bash", "hook_event": "PreToolUse",
245
+ "stdout": "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"[agent-guard] COMPOUND_CREATE_DELETE: This line creates files and then destroys them, so pre-execution compensation cannot see the targets. Allow once to run it as-is, or split the deletion into its own command.\"}}\n",
246
+ "stderr": "", "exit_code": 0, "outcome": "success"}
247
+ ```
248
+
249
+ Under `--permission-mode default` with no interactive approver available in
250
+ `-p` mode, Claude Code declined the call. The harness records the denial:
251
+
252
+ ```json
253
+ {"permission_denials": [{"tool_name": "Bash", "tool_use_id": "toolu_d", "tool_input": {"command": "touch f && rm f"}}]}
254
+ ```
255
+
256
+ and the tool result fed back to the model is the guard's explanation,
257
+ `is_error: true`. The strongest evidence is the filesystem: `f` was never
258
+ created — the compound command did **not** run. `.agent-trash/audit.jsonl`
259
+ records the escalation:
260
+
261
+ ```json
262
+ {"code": "COMPOUND_CREATE_DELETE", "command": "touch f && rm f", "event": "ask", "reasons": ["this command line creates files before destroying them; pre-execution compensation cannot see targets that do not exist yet"], "session": "51b54dab-06f7-4758-9bed-027dbb495f74", "ts": "2026-09-14T05:09:39Z"}
263
+ ```
264
+
265
+ Note the asymmetry the adapter documents held in practice: RELOCATE's reason
266
+ reached the user through `permissionDecisionReason`, while BLOCK's reached the
267
+ *model* through stderr.
268
+
269
+ **Control — the benign fast path stays free.**
270
+
271
+ `git status --short` produced a silent exit-0 hook and **no
272
+ `.agent-trash/` at all**: the regex prefilter short-circuits before any
273
+ Python process is spawned, so benign Bash traffic pays neither guard latency
274
+ nor audit writes. `ls -A` in the same session behaved identically.
275
+
276
+ ### The no-`python3` A/B, inside the harness
277
+
278
+ | | pre-fix (`["python3", ...]`) | post-fix (`[sys.executable, ...]`) |
279
+ |---|---|---|
280
+ | Hook exit | 2 | 0 |
281
+ | Hook stderr | `guard infrastructure error (fail-closed): [Errno 2] No such file or directory: 'python3'` | *(empty)* |
282
+ | `permissionDecision` | — (never reached the guard) | `allow` / `RELOCATE_TREE` |
283
+ | `build/` after run | untouched, command refused | quarantined, `.agent-trash/` audited |
284
+ | Guard usable? | **no** | yes |
285
+
286
+ Both runs used the same harness, the same settings file (hook invoked as
287
+ `python`), the same `PATH` directory, and the same scripted command. Only
288
+ the adapter line differs.
289
+
290
+ ## Reproduction
291
+
292
+ The harness ships with the repository so the run is repeatable rather than
293
+ merely described.
294
+
295
+ ```bash
296
+ npm install -g @anthropic-ai/claude-code # or export CLAUDE_BIN=...
297
+
298
+ # RELOCATE / BLOCK / ASK / control
299
+ bash adapters/claude/harness/run_scenario.sh relocate "rm -rf build" 8901
300
+ bash adapters/claude/harness/run_scenario.sh block "rm -rf ." 8903
301
+ bash adapters/claude/harness/run_scenario.sh ask "touch f && rm f" 8904 default
302
+ bash adapters/claude/harness/run_scenario.sh control "git status --short" 8905
303
+
304
+ # the Windows / no-python3 shape
305
+ bash adapters/claude/harness/run_scenario_no_python3.sh nopy3_fixed "rm -rf build" 8908
306
+ ```
307
+
308
+ Each run writes `script.json`, `transcript.jsonl` (with
309
+ `--include-hook-events`, so hook stdout/stderr/exit codes are recorded),
310
+ `requests.jsonl`, and the resulting `project/` including `.agent-trash/`.
311
+ See `adapters/claude/harness/README.md`.
312
+
313
+ ## Findings about the harness (not agent-guard)
314
+
315
+ - **`PreToolUse` hooks fire in `-p` (non-interactive) mode without a
316
+ workspace-trust step.** Unlike the ZCode finding in
317
+ `docs/test-report-zcode-glm-flash.md`, no trust prompt gated the hook here:
318
+ with `.claude/settings.json` in place, project hooks loaded at session
319
+ start and intercepted on the first matching Bash call. Non-interactive runs
320
+ skip the trust dialog by design.
321
+ - **`--dangerously-skip-permissions` cannot be combined with running as
322
+ root**, so the non-interactive runs used
323
+ `--permission-mode dontAsk` (RELOCATE/BLOCK) or `default` (ASK). The
324
+ guard's decision is emitted before the harness's own permission layer
325
+ resolves, and was unaffected by the mode.
326
+ - **An ASK that nobody approves is a deny — and that is fail-safe.** With no
327
+ interactive approver the command did not run. That is the correct outcome
328
+ for a headless harness, but it means ASK in `-p` mode is not an
329
+ "interactive prompt"; operators get a denial unless they wire up an
330
+ approver. Worth stating in the adapter README.
331
+ - Claude Code validates the adapter's `hookSpecificOutput` schema strictly,
332
+ exactly as ZCode did; no schema-strictness issue was found.
333
+
334
+ ## Limitations
335
+
336
+ - **The model is mocked.** Tool-selection behaviour (does a real model reach
337
+ for `rm -rf .` at all, does it retry after a BLOCK, does it argue with an
338
+ ASK) is out of scope. This report is evidence about the *interception
339
+ mechanism* on a real Claude Code build; it is not a Claude Code forward
340
+ test. The upstream "Claude Code live session" item is advanced, not closed.
341
+ - **Single harness build.** Claude Code 2.1.270 on Linux x64 only. Hook
342
+ semantics are the harness's contract and could change between builds.
343
+ - **No hostile-agent testing.** Consistent with `docs/threat-model.md`, this
344
+ is mistake protection, not a privilege boundary.
345
+ - The no-`python3` A/B uses a synthetic `PATH` (symlinks) rather than a
346
+ genuine Windows host. It reproduces the failure mode exactly — the missing
347
+ executable — because that is what the defect keys on, but it is not a
348
+ Windows run. Windows remains out of V1 scope.
349
+ - RELOCATE's three-decision sample is one command per decision class;
350
+ `tests/test_conformance.py` remains the broad matrix.
351
+
352
+ ## Relationship to prior history
353
+
354
+ - **ZCode/GLM Flash report** (`docs/test-report-zcode-glm-flash.md`): its
355
+ `os.uname()` finding is the same *shape* of defect as this report's
356
+ `python3` hardcode — a POSIX-only assumption that fail-closed into total
357
+ guard unavailability on Windows. Both are one-line platform fixes; both
358
+ were invisible to the decision matrix because the fixtures always had the
359
+ expected environment. Its "Claude Code integration" open item is advanced
360
+ here to a real Claude Code build.
361
+ - **DSH v0.1.1 report** (`docs/test-report-dsh-v0.1.1.md`): same decision
362
+ matrix methodology and the same "remaining matrix expansion → Claude Code
363
+ live sessions" item, now partially closed.
364
+ - **Codex report** (`docs/test-report-codex-gpt-5.6-sol.md`): its fail-closed
365
+ compensation contract is unrelated to this defect but shares the principle —
366
+ a guard that cannot do its job must refuse rather than pretend. Here the
367
+ refusal was correct in isolation and catastrophic in aggregate, which is why
368
+ the regression tests assert *success*, not merely *an exit code*.
369
+
370
+ ## Remaining matrix expansion
371
+
372
+ - Claude Code with a **real** model family (forward test through the same
373
+ harness).
374
+ - A real Windows host running the adapter under Git Bash / `python`.
375
+ - Interactive Claude Code session, to observe ASK actually prompting a human
376
+ and to check whether Claude Code's own "always allow" rule can short-circuit
377
+ the hook the way ZCode's does.
378
+ - Additional Claude Code builds as the hook schema evolves.
379
+
380
+ ## Conclusion
381
+
382
+ The `python3` hardcode was a real, reproducible, release-blocking defect on
383
+ any host without a `python3` alias: it turned the guard from a recovery
384
+ system into a blanket denial while reporting only a stderr line. Spawning the
385
+ guard with `sys.executable` fixes it at the source, and two regression tests
386
+ keep it fixed on both the allow and block paths.
387
+
388
+ With that fix in place the Claude Code adapter is validated end-to-end against
389
+ a real Claude Code 2.1.270 session: RELOCATE quarantined and allowed, BLOCK
390
+ refused and taught the model why, ASK escalated and executed nothing without
391
+ approval — each with matching audit records and a control run showing the
392
+ benign path stays free. The harness ships in
393
+ `adapters/claude/harness/` so the result can be re-derived.
394
+
395
+ ## Post-test note (2026-09-14)
396
+
397
+ *Added after the report above was finalised; the dated evidence in the body
398
+ is unchanged.*
399
+
400
+ **Windows-native shell support has since landed.** The Limitations section
401
+ recorded "Windows remains out of V1 scope" because that was the repository
402
+ state when these scenarios ran. The dialect layer was merged afterwards, in
403
+ two phases:
404
+
405
+ - **MR !3 / !6 (`core/dialects.py`)** - cmd and PowerShell lexical front ends
406
+ that map Windows-native vocabulary (`ri`/`rd`/`del`/`Remove-Item`,
407
+ `-Recurse`/`-Force`, PowerShell short-parameter prefixes) onto the same
408
+ effect facts the POSIX lexer produces. `check.py` gained `--dialect`, the
409
+ hook forwards a dialect, and the prefilter follows it.
410
+ - The differential and phase-2 suites (`tests/test_dialects.py`,
411
+ `tests/test_dialect_phase2.py`) now cover what the earlier limitation
412
+ described, so that sentence is superseded as a statement of repository
413
+ capability.
414
+
415
+ **Still open.** A real Windows HOST running the adapter end to end - Git Bash
416
+ or `cmd`, a stock `python` (no `python3` alias), the hook wired into
417
+ `.claude/settings.json` - remains an open item, and this report does not
418
+ claim otherwise. What changed is the reason: the gap is no longer "Windows is
419
+ out of scope" but "the dialect layer is covered by unit and conformance
420
+ tests, not yet by a live run on Windows". The `python3`-free A/B earlier in
421
+ this report still stands as the closest available approximation of that host.
422
+
423
+ Note also that the symlink-ancestor path fixes delivered later (F9/F9b in
424
+ macOS CI) are outside this report's scope; see
425
+ `tests/test_workspace_symlink.py`.
426
+
427
+ ## 2026-09-24 addendum: Claude Code 2.1.273 POSIX bridge
428
+
429
+ This addendum is a **new local checkout test**, not a revision of the
430
+ 2.1.270 evidence above. It used the installed Claude Code CLI 2.1.273 on
431
+ Linux ARM64/PRoot, the same scripted model endpoint, and separate synthetic
432
+ Git projects. The project `.claude/settings.json` selected `PreToolUse:Bash`
433
+ and invoked `/bin/sh adapters/claude/hook_bridge.sh` with an absolute Python
434
+ path. The runner requested the project setting source and did not change the
435
+ user's global Claude configuration. No Claude AI model was called.
436
+
437
+ | Scenario | Hook evidence | Independent project state |
438
+ |---|---|---|
439
+ | `rm -rf build`, healthy Python | `RELOCATE_TREE`, `permissionDecision: "allow"`, exit 0; Bash completed | `build/` absent; quarantine transaction listed `RESTORABLE` |
440
+ | `rm -rf .`, healthy Python | `BLOCK_PROTECTED_PATH`, exit 2; Bash tool result is a hook error | tracked `NOTES.md` still exists |
441
+ | `touch f && rm f`, healthy Python | `COMPOUND_CREATE_DELETE`, `permissionDecision: "ask"`; headless `dontAsk` denied it | `f` absent; no approval was given |
442
+ | `rm -rf build`, bridge with process-local `/bin/false` in place of Python | bridge mapped exit 1 to exit 2 for both the recon and target Bash calls | `build/` and its artifact still exist |
443
+
444
+ The failing-interpreter trial is a **host-level injected process failure**,
445
+ not merely a direct bridge unit test. A separate healthy run proves this
446
+ same `build/` operation otherwise proceeds after quarantine. An ordinary
447
+ `touch` sentinel was *not* used as the comparison: under this headless
448
+ permission mode Claude Code independently refused `touch`, making its absence
449
+ ambiguous. The fixture runner now refuses to overwrite prior output.
450
+
451
+ The Claude adapter also now rejects malformed `PreToolUse` envelopes with
452
+ exit 2, aligning the shared adapter's default with Kimi's already-strict
453
+ entrypoint. New local tests cover malformed input, non-Bash pass-through,
454
+ the bridge's interpreter-failure mapping and the example settings command.
455
+ After updating an older dialect fixture to include its required event name,
456
+ the complete local `npm test` run passed 398 Python tests and the DSH adapter
457
+ smoke test. The shell scripts passed syntax checks.
458
+
459
+ **Boundary:** the bridge helps only when Claude actually starts it. It cannot
460
+ make a missing hook, unmatched tool, bridge-spawn failure, or host timeout
461
+ fail closed. This was a scripted-model test of host interception, not a
462
+ real-Claude-model, Windows, interactive ASK, or subagent acceptance test.