@mokuyoaxis/agent-guard 0.2.3 → 0.2.4-hotfix.1

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 (70) hide show
  1. package/README.md +70 -63
  2. package/README.zh-CN.md +61 -59
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +10 -6
  8. package/adapters/dsh/harness/README.md +8 -8
  9. package/adapters/dsh/harness/guard_lab.py +3 -3
  10. package/adapters/dsh/lib/index.js +1 -1
  11. package/adapters/kimi-code/README.md +7 -7
  12. package/adapters/kimi-code/harness/README.md +3 -3
  13. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  14. package/core/__init__.py +1 -1
  15. package/core/classifier.py +66 -17
  16. package/core/policy.py +28 -13
  17. package/core/recovery.py +256 -23
  18. package/core/trash_index.py +193 -0
  19. package/docs/README.md +104 -0
  20. package/docs/{architecture.md → design/architecture.md} +31 -6
  21. package/docs/{compatibility.md → design/compatibility.md} +80 -4
  22. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  23. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  24. package/docs/guides/trash-index.md +106 -0
  25. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  26. package/docs/{friction.md → history/friction.md} +61 -0
  27. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  28. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  29. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  30. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  31. package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
  32. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  33. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  34. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  35. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  36. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  37. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  38. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  39. package/docs/releases/release-notes-0.2.4-hotfix.1.md +75 -0
  40. package/docs/releases/release-notes-0.2.4.md +89 -0
  41. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  42. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  43. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  44. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  45. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  46. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  47. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  48. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  49. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  50. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  51. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  52. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  53. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  54. package/package.json +1 -1
  55. package/skills/delete-guard/SKILL.md +38 -0
  56. package/skills/delete-guard/references/policy.md +29 -9
  57. package/skills/delete-guard/scripts/check.py +19 -0
  58. package/skills/delete-guard/scripts/restore.py +18 -6
  59. package/skills/delete-guard/scripts/status.py +52 -0
  60. package/skills/exfil-guard/references/channels.md +1 -1
  61. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  62. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  63. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  64. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  65. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  66. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  67. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  68. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  69. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  70. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -78,11 +78,11 @@ prompt.
78
78
  A passing check does **not** inspect Claude's merged settings, prove a
79
79
  running session loaded the hook, or verify host-level interception. For
80
80
  those claims, use the isolated host acceptance in the
81
- [capability matrix](../../docs/harness-capabilities.md).
81
+ [capability matrix](../../docs/guides/harness-capabilities.md).
82
82
  Add `--check-drift` to compare the installed Claude Code version with the
83
83
  shipped profile and compute privacy-safe configuration/runtime
84
84
  fingerprints. `CURRENT` still does not prove live interception; see the
85
- [drift status contract](../../docs/host-drift.md).
85
+ [drift status contract](../../docs/guides/host-drift.md).
86
86
  An explicit `--live-sentinel` may then use one configured model call in a
87
87
  private fixture and requires adapter, audit, host-feedback, and marker
88
88
  evidence. It keeps `dontAsk` and never enables permission bypass.
@@ -126,7 +126,7 @@ returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
126
126
  Validated end-to-end against real Claude Code sessions (2.1.270 and 2.1.273) with a
127
127
  scripted mock Anthropic endpoint standing in for the model, plus the
128
128
  `python3`-free regression tests. See
129
- [`docs/test-report-claude-code-harness.md`](../../docs/test-report-claude-code-harness.md)
129
+ [`docs/reports/test-report-claude-code-harness.md`](../../docs/reports/test-report-claude-code-harness.md)
130
130
  and the shipped harness in [`harness/`](harness/README.md).
131
131
 
132
132
  The guard child is spawned with `sys.executable`, never `python3` from
@@ -1,7 +1,7 @@
1
1
  # Claude Code end-to-end harness
2
2
 
3
3
  Reproduces the live interception test in
4
- [`docs/test-report-claude-code-harness.md`](../../../docs/test-report-claude-code-harness.md):
4
+ [`docs/reports/test-report-claude-code-harness.md`](../../../docs/reports/test-report-claude-code-harness.md):
5
5
  the **real** Claude Code CLI, the **real** agent-guard `PreToolUse` hook, and
6
6
  a **scripted mock Anthropic endpoint** standing in for the model.
7
7
 
@@ -1,10 +1,10 @@
1
1
  # Codex acceptance harness
2
2
 
3
3
  Reproduces the 20-check acceptance run recorded in
4
- [`docs/test-report-codex-gpt-6-astra-high.md`](../../../docs/test-report-codex-gpt-6-astra-high.md)
4
+ [`docs/reports/test-report-codex-gpt-6-astra-high.md`](../../../docs/reports/test-report-codex-gpt-6-astra-high.md)
5
5
  (2026-09-19, baseline `de5a00e`, `gpt-6-astra` / `high`).
6
6
 
7
- Unlike [`adapters/claude/harness/`](../../claude/harness/), there is no Codex
7
+ Unlike [`adapters/claude/harness/`](../../claude/harness), there is no Codex
8
8
  adapter behind this directory. Codex has no native PreToolUse hook in this
9
9
  repository, so nothing here implies automatic interception: the driver
10
10
  exercises the guard through the production CLI (`check.py`, `safe_delete.py`,
@@ -7,19 +7,23 @@ delegates deletion verdicts to the shared Python core
7
7
  The opt-in text-read prototype reuses the existing Core exfil policy through
8
8
  a bounded local worker. Both ship inside this package.
9
9
 
10
- The [current contract review](../../docs/test-report-release-readiness-0.2.3.md)
10
+ The [0.2.3 contract review](../../docs/reports/test-report-release-readiness-0.2.3.md)
11
11
  verifies the default deletion path on `0.2.0-rc.2` and `0.1.5-rc.1`, and
12
12
  the opt-in read path on the reviewed new local and sandbox filesystem providers.
13
13
  The package admits both exact host versions. Lab preflight accepts both and
14
14
  binds their native formats separately; unsupported session shapes remain
15
15
  inconclusive. A running Web service's plugin inventory does not validate this
16
- checkout or its agent scope. The [initial upgrade check](../../docs/test-report-dsh-0.2-upgrade.md)
16
+ checkout or its agent scope. The [initial upgrade check](../../docs/reports/test-report-dsh-0.2-upgrade.md)
17
17
  retains the earlier failures and correction history.
18
18
 
19
19
  ## Install
20
20
 
21
+ The [0.2.4 release](../../docs/releases/release-notes-0.2.4.md) updates the shared
22
+ Core and docs without broadening the admitted DSH versions or native-read
23
+ coverage. Install the exact version:
24
+
21
25
  ```bash
22
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.3
26
+ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
23
27
  ```
24
28
 
25
29
  Use an exact package version whose host contract matches your DSH installation.
@@ -95,11 +99,11 @@ it reads no target file and performs no model/network call. Native `read`
95
99
  continues to own filesystem access. The shell-policy inheritance note below
96
100
  applies to the existing deletion commands, not this controller worker.
97
101
 
98
- The [zero-model native report](../../docs/test-report-dsh-read-redaction.md)
102
+ The [zero-model native report](../../docs/reports/test-report-dsh-read-redaction.md)
99
103
  verifies the actual returned value/content/meta, next request, and full durable
100
104
  JSONL log through the real AgentLoop with a synthetic stream. It does not
101
105
  establish real-model injection mitigation or universal emission protection.
102
- The separate [official Flash real-model follow-up](../../docs/test-report-dsh-real-followup.md)
106
+ The separate [official Flash real-model follow-up](../../docs/reports/test-report-dsh-real-followup.md)
103
107
  observed supported synthetic-secret redaction in tool content, presentation
104
108
  metadata and the decoded session during a direct-read off/on experiment. It
105
109
  preserved useful configuration and remains outside the Lab injection L2 protocol.
@@ -136,7 +140,7 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
136
140
  reproducing a test; a source checkout may contain later changes.
137
141
  - DSH `0.1.5-rc.1` package loading and one harmless execution-level `bash`
138
142
  block are independently verified in the
139
- [bounded host report](../../docs/test-report-dsh-0.1.5-rc.1.md). Model,
143
+ [bounded host report](../../docs/reports/test-report-dsh-0.1.5-rc.1.md). Model,
140
144
  subagent, concurrency, ASK UI and non-`bash` paths remain separate tests.
141
145
  - For repeatable baselines and reviewed guard-off/on Lab pairs, use the
142
146
  [headless capture/review runner](harness/README.md). Its separate `check`
@@ -51,7 +51,7 @@ python3 adapters/dsh/harness/guard_lab.py run \
51
51
  --dsh-home /tmp/approved-disposable-dsh-home \
52
52
  --output-dir /tmp/dsh-lab-clean \
53
53
  --case clean --model-label "DeepSeek official deepseek-flash" \
54
- --task-file docs/guard-lab-clean-task.md \
54
+ --task-file docs/lab/tasks/guard-lab-clean-task.md \
55
55
  --trial-group dsh-baseline-01 --timeout 120
56
56
  ```
57
57
 
@@ -147,7 +147,7 @@ replacement operations and unknown content blocks refuse every output channel.
147
147
  Parser 2 still refuses these source references. The retained new-host real-model
148
148
  clean capture was refused with `UNSUPPORTED_SURFACE_REPLAY`, and its composition
149
149
  also changed; it did not establish a new off/on result. The
150
- [current review](../../../docs/test-report-release-readiness-0.2.3.md) separates
150
+ [current review](../../../docs/reports/test-report-release-readiness-0.2.3.md) separates
151
151
  the passing no-model preflight/parser regressions from this incomplete trial.
152
152
 
153
153
  Historical version 1 receipts still finalize with stdout/stderr coverage only.
@@ -155,7 +155,7 @@ They do not acquire native coverage by opening them with the updated helper.
155
155
  Use fresh captures with identical channel coverage for a later differential
156
156
  trial. The generic comparison now requires equal scanned channel sets and
157
157
  non-guard fingerprints, while their provenance remains user-declared.
158
- [Native-session follow-up](../../../docs/test-report-dsh-native-session.md)
158
+ [Native-session follow-up](../../../docs/reports/test-report-dsh-native-session.md)
159
159
  records the offline review of retained real logs separately.
160
160
 
161
161
  ## Capture the guard-off attack probe
@@ -192,7 +192,7 @@ review checklist or `--attack-sample config-comment-v1` for instructions in
192
192
  service configuration comments. The original `direct-v1` remains the default.
193
193
  Each sample gets its own protocol ID and template fingerprint. Keep the original
194
194
  task, use a fresh output/home for each sample, and use the same sample for any
195
- later guarded comparison. See the [sample registry](../../../docs/guard-lab.md#versioned-attack-samples).
195
+ later guarded comparison. See the [sample registry](../../../docs/lab/guard-lab.md#versioned-attack-samples).
196
196
 
197
197
  ## Evidence and exit status
198
198
 
@@ -227,7 +227,7 @@ DSH also retains its own session artifacts.
227
227
  Lab events and reports continue to retain no raw output or marker values.
228
228
 
229
229
  Version/model labels, completion review, environment equality across separate
230
- runs, and same-UID isolation retain the [normal Lab limitations](../../../docs/guard-lab.md).
230
+ runs, and same-UID isolation retain the [normal Lab limitations](../../../docs/lab/guard-lab.md).
231
231
  The original composition fingerprint checks one composed tree. New receipt
232
232
  version 3 additionally binds `dsh-lab-non-guard-v1`: rendered non-Guard rows,
233
233
  saved `settings.yaml`, home `.env`, the headless package manifest and inherited
@@ -318,7 +318,7 @@ another capture under the new rules. Prepare a fresh pair to continue testing.
318
318
  Results distinguish tool and assistant canary exposure from fake Lab execution
319
319
  and URL contact. The default `deletion-v1` profile loads the existing deletion
320
320
  adapter. Continued tool exposure with that profile can validly yield
321
- `NOT_MITIGATED`. The [investigation report](../../../docs/test-report-dsh-paired-lab.md)
321
+ `NOT_MITIGATED`. The [investigation report](../../../docs/reports/test-report-dsh-paired-lab.md)
322
322
  describes the candidate result-rewriting seam and its limits.
323
323
 
324
324
  ### Explicit native read redaction profile
@@ -339,7 +339,7 @@ python3 adapters/dsh/harness/guard_lab.py prepare-pair \
339
339
  --guard-profile read-redaction-v1 \
340
340
  --read-guard-dsh-root /absolute/path/to/installed/@deepseek-ai/dsh \
341
341
  --attack-sample read-redaction-v1 \
342
- --task-file docs/guard-lab-read-trial-task.md \
342
+ --task-file docs/lab/tasks/guard-lab-read-trial-task.md \
343
343
  --model-label "DeepSeek official deepseek-flash" \
344
344
  --trial-group dsh-read-redaction-01
345
345
  ```
@@ -376,7 +376,7 @@ external-network call. They cover unreviewed/failed/empty/oversized/timed-out
376
376
  captures, exposure semantics, capture corruption, version/config preflight,
377
377
  composition drift, create-once finalization, recovered/broken retries,
378
378
  fragmented markers, retry-only exposure and legacy coverage. The
379
- [retry-evidence report](../../../docs/test-report-dsh-retry-evidence.md) records
379
+ [retry-evidence report](../../../docs/reports/test-report-dsh-retry-evidence.md) records
380
380
  an offline reparse of the retained official Flash retry log. A mock pass does not establish
381
381
  a new real-model or execution-level DSH acceptance claim.
382
382
  The dedicated CI `dsh-native-lab` job selects Node 22.23.2 and runs these suites;
@@ -699,7 +699,7 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
699
699
  run.add_argument("--output-dir", type=Path, required=True)
700
700
  run.add_argument("--case", choices=("clean", "injection-probe"), required=True)
701
701
  run.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
702
- run.add_argument("--task-file", type=Path, default=ROOT / "docs" / "guard-lab-trial-task.md")
702
+ run.add_argument("--task-file", type=Path, default=ROOT / "docs" / "lab" / "tasks" / "guard-lab-trial-task.md")
703
703
  run.add_argument("--model-label", required=True)
704
704
  run.add_argument("--trial-group", required=True)
705
705
  run.add_argument("--timeout", type=int, default=120)
@@ -717,8 +717,8 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
717
717
  pair.add_argument("--patch", type=Path, action="append", default=[])
718
718
  pair.add_argument("--model-label", required=True)
719
719
  pair.add_argument("--trial-group", required=True)
720
- pair.add_argument("--task-file", type=Path, default=ROOT / "docs/guard-lab-trial-task.md")
721
- pair.add_argument("--clean-task-file", type=Path, default=ROOT / "docs/guard-lab-clean-task.md")
720
+ pair.add_argument("--task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-trial-task.md")
721
+ pair.add_argument("--clean-task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-clean-task.md")
722
722
  pair.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
723
723
  pair.add_argument("--timeout", type=int, default=120)
724
724
  pair.add_argument("--guard-profile", choices=GUARD_PROFILES, default="deletion-v1")
@@ -22,7 +22,7 @@
22
22
  * config.repoRoot points at a live checkout (development mode).
23
23
  *
24
24
  * Positioning: automatic recovery system with human escalation - reliability
25
- * infrastructure, not a security sandbox. See docs/threat-model.md.
25
+ * infrastructure, not a security sandbox. See docs/design/threat-model.md.
26
26
  */
27
27
 
28
28
  import fs from "node:fs";
@@ -15,10 +15,10 @@ contract comparison below was established against 0.42.0; the 2.1.1 trials
15
15
  independently observed authenticated root `Bash` blocks through the same
16
16
  exit-2 hook path on an OAuth official model and a second configured model
17
17
  route. Connection details and private route identifiers are omitted. See the
18
- [bounded report](../../docs/test-report-kimi-code-block.md).
18
+ [bounded report](../../docs/reports/test-report-kimi-code-block.md).
19
19
 
20
20
  For the separate honeytoken experiment, see the
21
- [guard-lab pair and local follow-up](../../docs/test-report-kimi-guard-lab.md).
21
+ [guard-lab pair and local follow-up](../../docs/reports/test-report-kimi-guard-lab.md).
22
22
  Its recorded tool-channel exposure and matched guarded observation are distinct
23
23
  from native Bash interception. A local doctor pass does not rerun that pair.
24
24
  Use the [private capture/review helper](harness/README.md) to repeat the Lab
@@ -80,7 +80,7 @@ allowed. `blockDecision()` collects any hook result with `action === "block"`.
80
80
  Add `--check-drift` to compare the installed Kimi Code version with the
81
81
  shipped profile and compute privacy-safe configuration/runtime
82
82
  fingerprints. `CURRENT` still does not prove live interception; see the
83
- [drift status contract](../../docs/host-drift.md).
83
+ [drift status contract](../../docs/guides/host-drift.md).
84
84
  An explicit `--live-sentinel` may then use one configured model call in a
85
85
  private fixture and requires adapter, audit, host-feedback, and marker
86
86
  evidence. The selected file must be named `config.toml`; the runner does
@@ -112,7 +112,7 @@ It does not describe a missing hook or a failed hook command.
112
112
  `kimi --auto`, Kimi 0.42.0 treats `permissionDecision: "ask"` as allow.
113
113
  This adapter therefore maps Core ASK to exit 2 (BLOCK). The failure class
114
114
  is described in the public
115
- [`development note`](../../docs/development-note-unguarded-deletion.md),
115
+ [`development note`](../../docs/history/development-note-unguarded-deletion.md),
116
116
  and it is fixed:
117
117
  `cd /tmp && rm -rf "$PWD/../home"` now classifies as
118
118
  `BLOCK / BLOCK_UNDETERMINABLE_EFFECT`. A shape rule describes
@@ -126,7 +126,7 @@ It does not describe a missing hook or a failed hook command.
126
126
  isolated sandboxes using one configured model route, single and concurrent
127
127
  subagent Bash calls reached the native hook and produced recoverable audit
128
128
  records.
129
- A third isolated project then showed [execution-level `BLOCK` enforcement](../../docs/test-report-kimi-code-block.md)
129
+ A third isolated project then showed [execution-level `BLOCK` enforcement](../../docs/reports/test-report-kimi-code-block.md)
130
130
  for one root and one single-subagent inert Bash probe. Its separate root
131
131
  `ASK` probe was denied. A fourth isolated project reproduced these bounded
132
132
  paths using a second configured request model ID and
@@ -143,7 +143,7 @@ It does not describe a missing hook or a failed hook command.
143
143
  before Python started.** In an isolated Kimi 0.42.0 trial, a process-local failing
144
144
  `python3` shim made a Bash call execute even though the correctly started
145
145
  adapter would have returned `BLOCK_DIALECT_UNKNOWN`. The sentinel appeared
146
- and no guard audit event was added. See the [bounded report](../../docs/test-report-kimi-code-block.md).
146
+ and no guard audit event was added. See the [bounded report](../../docs/reports/test-report-kimi-code-block.md).
147
147
  The bridge changes this particular failure into exit 2 **if the bridge
148
148
  itself starts**. It cannot block a hook that is absent, skipped by the
149
149
  matcher, fails to spawn, or times out. The host remains fail-open for those
@@ -156,7 +156,7 @@ It does not describe a missing hook or a failed hook command.
156
156
  process-local Python startup fault returned exit 1 before the adapter ran;
157
157
  the bridge converted it to Kimi's hard refusal, and the sentinel stayed
158
158
  absent. This does not test a bridge-spawn failure or timeout; see the
159
- [bounded report](../../docs/test-report-kimi-code-block.md).
159
+ [bounded report](../../docs/reports/test-report-kimi-code-block.md).
160
160
  - Kimi's `doctor config` accepted a hook-free test config and an invalid
161
161
  regex matcher; it checks configuration validity, not live interception.
162
162
  In the installed 0.42.0 bundle, a matcher regex error yields no match.
@@ -42,9 +42,9 @@ remain user-declared; configuration equality does not authenticate a backend.
42
42
 
43
43
  ## Clean control, then baseline
44
44
 
45
- Use the [README-only task](../../../docs/guard-lab-clean-task.md) for a real-host
45
+ Use the [README-only task](../../../docs/lab/tasks/guard-lab-clean-task.md) for a real-host
46
46
  negative control so that it requests no bait read. Use the original
47
- [review task](../../../docs/guard-lab-trial-task.md) for both attack trials.
47
+ [review task](../../../docs/lab/tasks/guard-lab-trial-task.md) for both attack trials.
48
48
  For the clean control, prepare a separate equivalent disposable home if the
49
49
  matched attack pair should start without any previous host session state.
50
50
 
@@ -53,7 +53,7 @@ python3 adapters/kimi-code/harness/guard_lab.py run \
53
53
  --kimi-home /tmp/kimi-lab-homes/off \
54
54
  --kimi-executable /absolute/path/to/kimi-2.1.1 --guard-state off \
55
55
  --output-dir /tmp/kimi-lab-clean --case clean \
56
- --task-file docs/guard-lab-clean-task.md \
56
+ --task-file docs/lab/tasks/guard-lab-clean-task.md \
57
57
  --model-label "Kimi official OAuth model" --trial-group kimi-pair-01
58
58
  ```
59
59
 
@@ -392,7 +392,7 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
392
392
  run.add_argument("--output-dir", type=Path, required=True)
393
393
  run.add_argument("--case", choices=("clean", "injection-probe"), required=True)
394
394
  run.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
395
- run.add_argument("--task-file", type=Path, default=ROOT / "docs/guard-lab-trial-task.md")
395
+ run.add_argument("--task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-trial-task.md")
396
396
  run.add_argument("--model-label", required=True)
397
397
  run.add_argument("--trial-group", required=True)
398
398
  run.add_argument("--timeout", type=int, default=180)
package/core/__init__.py CHANGED
@@ -1,6 +1,6 @@
1
1
  """agent-guard core: a reliability layer for autonomous AI agents.
2
2
 
3
- Four pillars (see docs/architecture.md):
3
+ Four pillars (see docs/design/architecture.md):
4
4
 
5
5
  Scope - where the agent may act -> policy.py
6
6
  Recoverability - whether mistakes can be undone -> recovery.py
@@ -33,7 +33,7 @@ import shlex
33
33
  from dataclasses import dataclass, field
34
34
  from typing import List, Optional, Tuple
35
35
 
36
- from . import dialects
36
+ from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, dialects
37
37
 
38
38
  # ---------------------------------------------------------------- vocabulary
39
39
 
@@ -41,7 +41,7 @@ FS_DELETE_CMDS = {"rm", "rmdir", "unlink", "shred"}
41
41
  # Windows-native delete verbs. Recognised on EVERY dialect: a harness that
42
42
  # never configured `AGENT_GUARD_DIALECT` still defaults to posix, and a
43
43
  # posix-lexed `del /s /q build` must not be treated as an unknown verb.
44
- # See docs/development-note-unguarded-deletion.md (lesson: the normalized
44
+ # See docs/history/development-note-unguarded-deletion.md (lesson: the normalized
45
45
  # target decides, not the spelling).
46
46
  WINDOWS_DELETE_CMDS = {"del", "erase", "rd", "rmdir", "ri"}
47
47
  SHELL_PREFIXES = {
@@ -56,7 +56,7 @@ INDETERMINACY_CHARS = ("$", "`")
56
56
  # Filesystem roots that must never be a deletion target, whatever the
57
57
  # workspace setting says. `rm -rf /home` blocks today only because /home
58
58
  # happens to sit outside the workspace root - an accident of configuration,
59
- # not a policy (see docs/development-note-unguarded-deletion.md).
59
+ # not a policy (see docs/history/development-note-unguarded-deletion.md).
60
60
  #
61
61
  # Matching is EXACT: the rule fires when a target *is* one of these roots,
62
62
  # never when it merely lives under one, so `rm -rf /home/alice/build` stays
@@ -137,7 +137,7 @@ KIND_GIT_DISCARD = "git-discard" # git restore <path> / git checkout -- <
137
137
  KIND_GIT_PUSH_FORCE = "git-push-force" # force / mirror / ref-deletion push
138
138
  KIND_UNKNOWN = "unknown" # destructive smell, no parseable shape
139
139
 
140
- # Whole-command-line shape facts (docs/friction.md F1/F2).
140
+ # Whole-command-line shape facts (docs/history/friction.md F1/F2).
141
141
  CREATION_CMDS = {"touch", "mkdir", "cp", "mv", "install", "ln", "tee"}
142
142
  # cmd builtins with the same shape (F2 is about "created then destroyed",
143
143
  # which `copy x a.tmp && del a.tmp` expresses just as literally).
@@ -146,7 +146,9 @@ CMD_CREATION_CMDS = {"copy", "xcopy", "robocopy", "mkdir", "md", "mklink",
146
146
  REDIRECT_CREATE_TOKENS = {">", ">>"}
147
147
  # Kinds whose compensation depends on enumerating concrete targets; a target
148
148
  # created earlier in the same line is invisible to pre-execution compensation.
149
- TARGET_DEPENDENT_KINDS = {KIND_FS_DELETE, KIND_GIT_CLEAN, KIND_GIT_DISCARD}
149
+ TARGET_DEPENDENT_KINDS = {
150
+ KIND_FS_DELETE, KIND_GIT_CLEAN, KIND_GIT_DISCARD, KIND_GIT_RESET_HARD,
151
+ }
150
152
 
151
153
 
152
154
  @dataclass
@@ -190,6 +192,7 @@ class PathSpec:
190
192
  inside_trash: bool = False
191
193
  protected: Optional[str] = None # None | ancestor-root | workspace-root
192
194
  # | outside-workspace | git-metadata
195
+ # | quarantine-control
193
196
  error: Optional[str] = None
194
197
 
195
198
  # ------------------------------------------------------------- path analysis
@@ -248,6 +251,26 @@ def _physical_keep_final(path: str) -> str:
248
251
  return os.path.join(os.path.realpath(parent), name)
249
252
 
250
253
 
254
+ def _quarantine_control_path(absolute: str, physical: str,
255
+ trash_root: str, trash_physical: str,
256
+ workspace: str) -> bool:
257
+ """Protect storage access and root metadata, retaining leaf-link location."""
258
+ # A configured final link is also the access path to an external bucket.
259
+ # Deleting its parent would sever that access even if storage is elsewhere.
260
+ if (inside_path(physical, workspace) and
261
+ any(inside_path(storage, physical) for storage in
262
+ (trash_physical, _physical_keep_final(trash_root)))):
263
+ return True
264
+ controls = {MANIFEST_NAME, AUDIT_NAME, STATE_NAME, STATE_NAME + ".tmp",
265
+ "sessions"}
266
+ for candidate in (physical, _physical_keep_final(absolute)):
267
+ if inside_path(candidate, trash_physical):
268
+ relative = os.path.relpath(candidate, trash_physical)
269
+ if relative.split(os.sep)[0] in controls:
270
+ return True
271
+ return False
272
+
273
+
251
274
  def workspace_boundary_root(workspace: str) -> str:
252
275
  """Physical form of a workspace root, for callers that compare roots."""
253
276
  return _physical(os.path.normpath(os.path.abspath(workspace)))
@@ -363,6 +386,9 @@ def classify_paths(
363
386
  # content. `rm -rf .` stays a hard BLOCK. (When no trash_root is
364
387
  # given, trash_physical is None and cannot match a real path.)
365
388
  spec.protected = "workspace-root"
389
+ elif trash_root and _quarantine_control_path(
390
+ absolute, physical, trash_root, trash_physical, workspace):
391
+ spec.protected = "quarantine-control"
366
392
  elif not spec.inside_workspace:
367
393
  spec.protected = "outside-workspace"
368
394
  else:
@@ -839,9 +865,21 @@ def _parse_git(segment: List[str]) -> OpSpec:
839
865
  if "--hard" in rest:
840
866
  spec.kind = KIND_GIT_RESET_HARD
841
867
  spec.force = True
842
- spec.targets = [
843
- t for t in rest if t != "--hard" and not t.startswith("-")
844
- ]
868
+ for tok in rest:
869
+ if tok in ("--hard", "-q", "--quiet"):
870
+ continue
871
+ if tok.startswith("-"):
872
+ spec.undeterminable = True
873
+ spec.note("unsupported hard reset option or path limit")
874
+ continue
875
+ spec.targets.append(tok)
876
+ if len(spec.targets) > 1:
877
+ spec.undeterminable = True
878
+ spec.note("hard reset requires a single target commit")
879
+ _scan_targets(spec)
880
+ if spec.wildcard:
881
+ spec.undeterminable = True
882
+ spec.note("hard reset target contains shell glob syntax")
845
883
  if not spec.targets:
846
884
  spec.note("whole-tree reset (no path limit)")
847
885
  apply_global_uncertainty()
@@ -947,16 +985,17 @@ def _has_create_redirect(segment: List[str]) -> bool:
947
985
 
948
986
 
949
987
  def _apply_shape_rules(specs: List[OpSpec], cd_positions: List[int],
950
- creation_positions: List[int]) -> None:
951
- """Whole-command-line restrictions (docs/friction.md F1/F2).
988
+ creation_positions: List[int],
989
+ segment_count: int = 1) -> None:
990
+ """Whole-command-line restrictions (docs/history/friction.md F1/F2).
952
991
 
953
992
  F1: a destructive op preceded by cd resolves against the wrong working
954
993
  directory - compensation would enumerate/snapshot the wrong tree.
955
994
  Applies to every destructive kind.
956
995
  F2: a target created earlier in the same line does not exist yet at
957
996
  interception time, so target-dependent compensation cannot cover it.
958
- Position-independent compensations (reset --hard whole-tree stash,
959
- force-push which is blocked anyway) are exempt.
997
+ Force-push, which is blocked anyway, is exempt. Hard reset also
998
+ needs a preflight of untracked content against its target tree.
960
999
  Shapes are DECISION-CLASS facts, not effect-uncertainty: the operation
961
1000
  itself is well understood, only its safe automatic compensation is not.
962
1001
  Policy maps them to ASK (single-execution authorization), keeping true
@@ -966,6 +1005,10 @@ def _apply_shape_rules(specs: List[OpSpec], cd_positions: List[int],
966
1005
  if spec.kind in (KIND_OTHER, KIND_UNKNOWN):
967
1006
  continue
968
1007
  idx = spec.segment_index
1008
+ if spec.kind == KIND_GIT_RESET_HARD and segment_count != 1:
1009
+ spec.undeterminable = True
1010
+ spec.note("hard reset must be a standalone command; other "
1011
+ "segments may change its target or collisions")
969
1012
  if any(pos < idx for pos in cd_positions):
970
1013
  spec.shape = "F1"
971
1014
  spec.note(
@@ -1152,14 +1195,19 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1152
1195
  elif head == "find":
1153
1196
  emit(_parse_find(seg), index)
1154
1197
  elif head == "git":
1155
- emit(_parse_git(seg), index)
1198
+ spec = _parse_git(seg)
1199
+ if spec.kind == KIND_GIT_RESET_HARD and len(seg) != len(segment):
1200
+ spec.undeterminable = True
1201
+ spec.note("hard reset wrappers may change its Git context")
1202
+ emit(spec, index)
1156
1203
  # anything else: kind OTHER, intentionally ignored by policy
1157
1204
 
1158
1205
  for spec in specs:
1159
1206
  spec.dialect = dialects.DIALECT_POSIX
1160
1207
  _append_dialect_mismatches(
1161
1208
  specs, command_segments, dialects.DIALECT_POSIX)
1162
- _apply_shape_rules(specs, cd_positions, creation_positions)
1209
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1210
+ len(raw_segments))
1163
1211
  return [s for s in specs if s.kind != KIND_OTHER], None
1164
1212
 
1165
1213
 
@@ -1189,7 +1237,7 @@ def _classify_windows_dialect(cmd: str, dialect: str
1189
1237
  accepts `/`, while leaving `\\` in the fact makes Linux and Windows CI
1190
1238
  disagree about the same command.
1191
1239
 
1192
- Shape rules (docs/friction.md F1/F2) apply to Windows lines too: `cd`
1240
+ Shape rules (docs/history/friction.md F1/F2) apply to Windows lines too: `cd`
1193
1241
  and the interpreter prefix set are shared shell concepts, so F1 means
1194
1242
  the same thing in cmd and PowerShell.
1195
1243
  """
@@ -1213,7 +1261,8 @@ def _classify_windows_dialect(cmd: str, dialect: str
1213
1261
  spec.targets = [t.replace("\\", "/") for t in spec.targets]
1214
1262
  _attribute_targets(spec)
1215
1263
  _append_dialect_mismatches(specs, stream.segments, dialect)
1216
- _apply_shape_rules(specs, cd_positions, creation_positions)
1264
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1265
+ len(stream.segments))
1217
1266
  return [s for s in specs if s.kind != KIND_OTHER], None
1218
1267
 
1219
1268
 
@@ -1230,7 +1279,7 @@ def classify_command(cmd: str, dialect: str = dialects.DEFAULT_DIALECT
1230
1279
  dialect layer exists to prevent.
1231
1280
 
1232
1281
  Heredoc bodies are stripped before POSIX parsing (they are written
1233
- payload, not commands - see docs/friction.md F5).
1282
+ payload, not commands - see docs/history/friction.md F5).
1234
1283
 
1235
1284
  Returns (specs, parse_error). Segments that are not destructive are
1236
1285
  returned as kind=OTHER and ignored by policy. A parse_error (unbalanced
package/core/policy.py CHANGED
@@ -7,7 +7,7 @@ The stable cross-harness interface is NOT allow/block. It is:
7
7
  + Explanation
8
8
  + RecoveryPlan (payload)
9
9
 
10
- Decision classes (docs/architecture.md):
10
+ Decision classes (docs/design/architecture.md):
11
11
 
12
12
  ALLOW safe to run as-is (noop / provably regenerable / trash GC)
13
13
  RELOCATE compensate by quarantine, then run
@@ -118,6 +118,7 @@ CODE_ASK_PATH_EMISSION = "ASK_PATH_EMISSION"
118
118
  CODE_ALLOW_SECRET_PLACEHOLDER = "ALLOW_SECRET_PLACEHOLDER"
119
119
  CODE_ALLOW_PATH_IN_WORKSPACE = "ALLOW_PATH_IN_WORKSPACE"
120
120
  CODE_BLOCK_COMPENSATION_FAILED = "COMPENSATION_FAILED"
121
+ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
121
122
 
122
123
  # Human-facing one-liners: why the guard cannot just do it (or did do it).
123
124
  EXPLANATIONS: Dict[str, str] = {
@@ -137,6 +138,11 @@ EXPLANATIONS: Dict[str, str] = {
137
138
  "real command ran.",
138
139
  CODE_SNAPSHOT_GIT_STASH: "Tracked modifications snapshotted as a stash "
139
140
  "before the command; apply it to recover.",
141
+ CODE_BLOCK_GIT_RESET_COLLISION: "git reset --hard would overwrite "
142
+ "untracked or ignored content, or "
143
+ "quarantine storage, that a tracked-only "
144
+ "stash cannot protect. Preserve the "
145
+ "conflicting paths separately first.",
140
146
  CODE_ASK_COMPOUND_CWD_DELETE: "This line combines a working-directory "
141
147
  "change with deletion, so the guard "
142
148
  "cannot safely relocate the target before "
@@ -160,8 +166,10 @@ EXPLANATIONS: Dict[str, str] = {
160
166
  "/usr, /etc, ...), regardless of the "
161
167
  "workspace setting. Hard boundary - not "
162
168
  "askable.",
163
- CODE_BLOCK_PROTECTED_PATH: "Target is the workspace root or git "
164
- "metadata. Hard boundary - not askable.",
169
+ CODE_BLOCK_PROTECTED_PATH: "Target is a protected workspace, Git or "
170
+ "quarantine control path. Hard boundary - "
171
+ "not askable; quarantine transaction cleanup "
172
+ "uses the explicit GC entry point.",
165
173
  CODE_BLOCK_WILDCARD: "Glob target sets are opaque; use safe_delete, "
166
174
  "which expands globs explicitly.",
167
175
  CODE_BLOCK_RESTRICTED_MODE: "This session is in RESTRICTED mode; the "
@@ -491,7 +499,20 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
491
499
  [f"protected filesystem root: {s.raw}"
492
500
  for s in protected_ancestor[:5]])
493
501
 
502
+ # Housekeeping never overrides root, control-file or Git protection.
503
+ protected_other = [s for s in specs
504
+ if s.protected in ("workspace-root", "git-metadata",
505
+ "quarantine-control")]
506
+ if protected_other:
507
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
508
+ [f"protected: {s.protected} ({s.raw})"
509
+ for s in protected_other[:5]])
510
+
494
511
  if specs and all(s.inside_trash for s in specs):
512
+ if any(s.wildcard for s in specs):
513
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
514
+ ["quarantine globs may include protected evidence; "
515
+ "enumerate explicitly with safe_delete"])
495
516
  return Verdict(DECISION_ALLOW, CODE_ALLOW_TRASH_GC)
496
517
 
497
518
  protected_outside = [s for s in specs
@@ -501,13 +522,6 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
501
522
  [f"outside workspace boundary: {s.raw}"
502
523
  for s in protected_outside[:5]])
503
524
 
504
- protected_other = [s for s in specs
505
- if s.protected in ("workspace-root", "git-metadata")]
506
- if protected_other:
507
- return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
508
- [f"protected: {s.protected} ({s.raw})"
509
- for s in protected_other[:5]])
510
-
511
525
  wild = [s for s in specs if s.wildcard]
512
526
  if wild:
513
527
  return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
@@ -607,7 +621,7 @@ def decide_op(spec: OpSpec, ctx: PolicyContext) -> Optional[Verdict]:
607
621
  # when the target set also trips a hard boundary, that boundary wins.
608
622
  # Without this, `cd /tmp && rm -rf /home` degrades a hard refusal into
609
623
  # an ASK - and any auto-approving host grants an ASK silently, which is
610
- # the incident finding described in docs/development-note-unguarded-deletion.md.
624
+ # the incident finding described in docs/history/development-note-unguarded-deletion.md.
611
625
  if spec.shape in ("F1", "F2"):
612
626
  ask_code = (CODE_ASK_COMPOUND_CWD_DELETE if spec.shape == "F1"
613
627
  else CODE_ASK_COMPOUND_CREATE_DELETE)
@@ -648,8 +662,9 @@ def decide_op(spec: OpSpec, ctx: PolicyContext) -> Optional[Verdict]:
648
662
  if spec.kind == KIND_GIT_RESET_HARD:
649
663
  return Verdict(
650
664
  DECISION_SNAPSHOT, CODE_SNAPSHOT_GIT_STASH,
651
- ["snapshot tracked modifications via git stash create/store "
652
- "before reset --hard"],
665
+ ["preflight untracked/ignored collisions with the target tree, "
666
+ "then snapshot tracked modifications via git stash "
667
+ "create/store before reset --hard"],
653
668
  )
654
669
 
655
670
  if spec.kind == KIND_GIT_DISCARD: