@mokuyoaxis/agent-guard 0.2.2 → 0.2.3-rc1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm version](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![v0.2.2 source](https://img.shields.io/badge/Source-v0.2.2-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
7
+ [![v0.2.3-rc1 source](https://img.shields.io/badge/Source-v0.2.3--rc1-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
8
8
 
9
9
  **Make destructive agent actions reversible by default.** · [简体中文](README.zh-CN.md)
10
10
 
@@ -58,6 +58,10 @@ Pinned npm installation into a stable, user-owned prefix:
58
58
  npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
59
59
  ```
60
60
 
61
+ `0.2.2` remains the stable recommendation. After the candidate is published,
62
+ explicit testers may select `@mokuyoaxis/agent-guard@0.2.3-rc1` or the npm
63
+ `@rc` channel; prereleases do not replace npm `latest`.
64
+
61
65
  The package root is then
62
66
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`.
63
67
  Alternatively, clone the source (skip this if you already have a checkout):
@@ -482,6 +486,7 @@ compensation engine without restructuring.
482
486
  | [CONTRIBUTING.md](CONTRIBUTING.md) | how to propose an Issue and submit a focused Pull Request |
483
487
  | [docs/architecture.md](docs/architecture.md) | pillars ↔ components, data flow, design decisions |
484
488
  | [docs/host-drift.md](docs/host-drift.md) | zero-token host/version drift states and privacy-minimal baselines |
489
+ | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed candidate and prerelease channel |
485
490
  | [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
491
  | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor changes and bounded evidence |
487
492
  | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 changes, evidence levels, and known limits |
@@ -499,13 +504,15 @@ compensation engine without restructuring.
499
504
 
500
505
  ## Status & roadmap
501
506
 
502
- The source version is **v0.2.2**. The published `v0.2.0` baseline includes
507
+ The source version is **v0.2.3-rc1**; the latest stable release remains
508
+ **v0.2.2**. The published `v0.2.0` baseline includes
503
509
  recoverable destructive actions, cmd/PowerShell dialect parsing, the
504
510
  `exfil-guard` text CLI, a read-only config view, and `recovery-audit`.
505
511
  Later source releases add Claude/Kimi POSIX hook bridges, bounded host
506
512
  evidence, a local `doctor`, host-drift checks, an opt-in live sentinel and
507
513
  current DSH package acceptance. See the
508
- [0.2.2 notes](docs/release-notes-0.2.2.md) for exact scope and
514
+ [0.2.3-rc1 notes](docs/release-notes-0.2.3-rc1.md) for the candidate scope,
515
+ [0.2.2 notes](docs/release-notes-0.2.2.md) for the stable scope, and
509
516
  [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) for
510
517
  publication status; a source version is not itself a published Release.
511
518
 
@@ -518,13 +525,14 @@ actions are protected. A tested direct-Python hook startup failure was
518
525
  fail-open. The optional shell bridge blocked a sampled Python startup failure
519
526
  in a real Kimi host session, but only when the bridge itself ran; config
520
527
  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`,
528
+ The candidate adds a focused real-Windows Core gate for Issue #7, but native
529
+ cmd/PowerShell execution through every harness and general concurrent-subagent
530
+ safety remain explicit gaps. Later Guard branches (`git-guard`, `database-guard`,
523
531
  `cloud-guard`) reuse the same protocol and compensation engine.
524
532
 
525
533
  ## 0.2.x preview: guard-lab
526
534
 
527
- Planned, **not included in 0.2.2**: an opt-in, offline honeytoken lab
535
+ Planned, **not included in 0.2.3-rc1**: an opt-in, offline honeytoken lab
528
536
  using disposable projects and synthetic, non-secret markers. It will compare
529
537
  normal tasks with prompt-injection attempts, and separately observe whether a
530
538
  harness indexes or exports files without an agent-requested read. Positive and
package/README.zh-CN.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![npm 版本](https://img.shields.io/npm/v/%40mokuyoaxis%2Fagent-guard.svg)](https://www.npmjs.com/package/@mokuyoaxis/agent-guard)
5
5
  [![License](https://img.shields.io/github/license/mokuyoaxis/agent-guard)](LICENSE)
6
6
  [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
7
- [![v0.2.2 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.2-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
7
+ [![v0.2.3-rc1 源码](https://img.shields.io/badge/%E6%BA%90%E7%A0%81-v0.2.3--rc1-5B6B7A)](https://github.com/mokuyoaxis/agent-guard/releases)
8
8
 
9
9
  **让 AI Agent 的破坏性操作默认可逆。** · [English](README.md)
10
10
 
@@ -48,6 +48,10 @@ checkout。不要误装无作用域的同名 `agent-guard` 包。
48
48
  npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.2
49
49
  ```
50
50
 
51
+ `0.2.2` 仍是稳定版推荐。候选版发布后,测试者可显式选择
52
+ `@mokuyoaxis/agent-guard@0.2.3-rc1` 或 npm 的 `@rc` 通道;预发布不会替换
53
+ npm `latest`。
54
+
51
55
  安装后的包根目录是
52
56
  `/absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard`。
53
57
  也可以克隆源码;如果已有 checkout,跳过克隆:
@@ -425,6 +429,7 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
425
429
  | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提出 Issue 与提交范围清晰的 Pull Request |
426
430
  | [docs/architecture.md](docs/architecture.md) | 四柱↔组件映射、数据流、关键设计决定 |
427
431
  | [docs/host-drift.md](docs/host-drift.md) | 零 Token 宿主/版本漂移状态与最小化基线 |
432
+ | [docs/release-notes-0.2.3-rc1.md](docs/release-notes-0.2.3-rc1.md) | Windows Core fail-closed 候选版与预发布通道 |
428
433
  | [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md) | 0.2.2 宿主漂移、实时哨兵与 DSH 打包验收 |
429
434
  | [docs/release-notes-0.2.1.md](docs/release-notes-0.2.1.md) | 0.2.1 adapter/doctor 变更与证据边界 |
430
435
  | [docs/release-notes-0.2.0.md](docs/release-notes-0.2.0.md) | 0.2.0 变更、证据等级与已知限制 |
@@ -442,11 +447,13 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
442
447
 
443
448
  ## 状态与路线图
444
449
 
445
- 当前源码版本为 **v0.2.2**。已发布的 `v0.2.0` 基线包含可恢复的破坏性
450
+ 当前源码版本为 **v0.2.3-rc1**,最新稳定版仍为 **v0.2.2**。已发布的
451
+ `v0.2.0` 基线包含可恢复的破坏性
446
452
  操作、cmd/PowerShell 方言解析、`exfil-guard` 文本 CLI、只读配置安全视图
447
453
  和 `recovery-audit`。后续源码版新增 Claude/Kimi POSIX hook 桥、有界宿主
448
454
  证据、`doctor`、宿主漂移检查、可选实时哨兵与当前 DSH 打包验收。准确范围见
449
- [0.2.2 说明](docs/release-notes-0.2.2.md);是否已正式发布以
455
+ [0.2.3-rc1 说明](docs/release-notes-0.2.3-rc1.md)记录候选范围,
456
+ [0.2.2 说明](docs/release-notes-0.2.2.md)记录稳定版范围;是否已正式发布以
450
457
  [GitHub Releases](https://github.com/mokuyoaxis/agent-guard/releases) 为准,
451
458
  源码版本号本身不代表已有 Release。
452
459
 
@@ -455,13 +462,14 @@ Skill 负责 Agent 行为引导,约束全部下沉 Core。未来的 `git-guard`
455
462
  Kimi 结果包含所测调用的 hook 补偿与执行级 BLOCK 证据,不证明宿主强制执行
456
463
  所有 `BLOCK`,也不意味着任意 Agent 操作都受保护。实测旧的直连 Python hook
457
464
  启动故障会放行;可选 shell 桥在一次 Kimi 宿主故障注入中将其转为拒绝,
458
- 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。真实 Windows 端到端覆盖
459
- 与一般并发子代理安全仍是明确缺口。
465
+ 但前提是桥自身成功运行;单凭配置校验无法证明 hook 在线。候选版为 Issue #7
466
+ 新增了聚焦的真实 Windows Core 门,但各 harness 下的原生 cmd/PowerShell
467
+ 执行与一般并发子代理安全仍是明确缺口。
460
468
  后续 `git-guard`、`database-guard`、`cloud-guard` 继续复用同一协议与补偿引擎。
461
469
 
462
470
  ## 0.2.x 预告:guard-lab 合成蜜罐
463
471
 
464
- 这是规划中的可选实验,**不属于 0.2.2**。它会在离线、一次性的测试项目
472
+ 这是规划中的可选实验,**不属于 0.2.3-rc1**。它会在离线、一次性的测试项目
465
473
  里放入无认证能力的合成标记,对照正常任务与提示词注入诱导;另设试次观察
466
474
  harness 是否在 Agent 未请求读取时自行索引或外发文件。正负对照、独立观察器
467
475
  和证据分级将区分“提出读取”“本地接触”与“证实越过外部边界”。不使用真实
@@ -115,11 +115,11 @@ lines are lexed with the right rules. Precedence:
115
115
  | environment | `AGENT_GUARD_DIALECT=powershell` |
116
116
  | default | `posix` |
117
117
 
118
- The prefilter follows the dialect: the POSIX regex cannot see
119
- `ri build -r -fo`, so a Windows-native payload would otherwise skip the
120
- guard entirely. The POSIX prefilter is unchanged, so the default path keeps
121
- its exact behaviour. An unrecognised dialect selector is **not** swapped
122
- for POSIX - `check.py` returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
118
+ The prefilter screens both POSIX and Windows destructive vocabularies. The
119
+ dialect chooses the lexer, not whether a suspicious command reaches Core;
120
+ this lets Core turn a known vocabulary mismatch into a fail-closed verdict.
121
+ An unrecognised dialect selector is **not** swapped for POSIX - `check.py`
122
+ returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
123
123
 
124
124
  ## Live-tested
125
125
 
@@ -14,9 +14,9 @@ Design rules:
14
14
  push) covers the overwhelming majority of real agent accidents on
15
15
  Linux/macOS. Native Windows shells express the same effects with other
16
16
  programs and other lexical rules; those live in `dialects.py` and are
17
- dispatched by `classify_command(dialect=...)`. The default dialect is
18
- POSIX, so the pre-dialect behaviour is unchanged for every existing
19
- caller.
17
+ dispatched by `classify_command(dialect=...)`. The default lexer is POSIX;
18
+ a separate vocabulary-mismatch floor prevents known destructive commands
19
+ from disappearing merely because a host selected the wrong lexer.
20
20
  * Fail closed. Unbalanced quotes, shell variables, command substitution,
21
21
  unknown flags, stdin-fed target lists, indirect shells (bash -c) - all
22
22
  become `undeterminable` facts. The policy layer restricts those.
@@ -693,13 +693,11 @@ def _normalize_windows_separators(cmd: str) -> str:
693
693
  r"""Turn a backslash into a slash so `del build\o.js` survives POSIX.
694
694
 
695
695
  `shlex.split(..., posix=True)` treats `\` as an escape and silently
696
- yields `buildo.js` - one wrong filename instead of a path. Only the
697
- segment following a Windows delete verb is rewritten, and only on a
698
- non-Windows host, matching `_classify_windows_dialect`: separation is a
699
- host concern, not a dialect concern.
696
+ yields `buildo.js` - one wrong filename instead of a path. The caller
697
+ invokes this only for a standalone Windows delete verb, so normal POSIX
698
+ escapes are untouched. Lexical facts must not depend on the OS running
699
+ the classifier: Windows accepts `/` as a path separator too.
700
700
  """
701
- if os.name == "nt":
702
- return cmd
703
701
  return cmd.replace("\\", "/")
704
702
 
705
703
 
@@ -992,6 +990,73 @@ def _parse_error_spec(exc: str,
992
990
  return spec
993
991
 
994
992
 
993
+ _KNOWN_DELETE_HEADS = frozenset(
994
+ FS_DELETE_CMDS | WINDOWS_DELETE_CMDS | {"remove-item"})
995
+
996
+
997
+ def _portable_command_name(token: str, casefold: bool = True) -> str:
998
+ """Command basename for safety probes, independent of the host OS."""
999
+ cleaned = token.strip().strip("&").strip("'\"")
1000
+ base = os.path.basename(cleaned.replace("\\", "/"))
1001
+ if casefold:
1002
+ base = base.lower()
1003
+ return base[:-4] if casefold and base.endswith(".exe") else base
1004
+
1005
+
1006
+ def _known_destructive_segment(segment: List[str], dialect: str) -> bool:
1007
+ """Whether one selected-dialect command segment has a known hazard.
1008
+
1009
+ This deliberately examines the command head/shape produced by the
1010
+ *selected* tokenizer. Re-parsing the raw line as another shell would
1011
+ manufacture semantics (for example cmd treats ``$(rm ...)`` as text).
1012
+ The result is only a mismatch signal; callers must not derive targets or
1013
+ a compensation plan from it.
1014
+ """
1015
+ if not segment:
1016
+ return False
1017
+ windows_syntax = dialect != dialects.DIALECT_POSIX
1018
+ head = _portable_command_name(segment[0], casefold=windows_syntax)
1019
+ if head in _KNOWN_DELETE_HEADS:
1020
+ return True
1021
+ if not windows_syntax and head.lower() in (
1022
+ WINDOWS_DELETE_CMDS | {"remove-item"}):
1023
+ # A foreign Windows verb may arrive in any case even though the
1024
+ # selected POSIX shell is case-sensitive. Do not case-fold POSIX's
1025
+ # own command vocabulary (`RM` may be an unrelated executable).
1026
+ return True
1027
+ if head == "find":
1028
+ probe = _parse_find(["find", *segment[1:]])
1029
+ return probe.kind != KIND_OTHER
1030
+ if head == "git":
1031
+ probe = _parse_git(["git", *segment[1:]])
1032
+ return probe.kind != KIND_OTHER
1033
+ return False
1034
+
1035
+
1036
+ def _append_dialect_mismatches(specs: List[OpSpec],
1037
+ segments: List[List[str]],
1038
+ dialect: str) -> None:
1039
+ """Fail closed when known destructive vocabulary vanished in parsing.
1040
+
1041
+ One operation in an earlier segment must not mask a missed later one.
1042
+ ``segment_index`` is therefore the coverage key. The appended UNKNOWN
1043
+ fact carries no raw command or target bytes and can only BLOCK; it can
1044
+ never authorize compensation under a grammar the caller did not select.
1045
+ """
1046
+ covered = {spec.segment_index for spec in specs}
1047
+ for index, segment in enumerate(segments):
1048
+ if index in covered or not _known_destructive_segment(
1049
+ segment, dialect):
1050
+ continue
1051
+ spec = _unknown_op(
1052
+ "known destructive vocabulary is incompatible with the "
1053
+ "selected dialect")
1054
+ spec.segment_index = index
1055
+ spec.dialect = dialect
1056
+ specs.append(spec)
1057
+ specs.sort(key=lambda spec: spec.segment_index)
1058
+
1059
+
995
1060
  _WINDOWS_PREFIX_RE = "|".join(sorted(SHELL_PREFIXES - {"xargs"}))
996
1061
  _WINDOWS_COMMAND_RE = re.compile(
997
1062
  r"(^|[;&|\n])\s*(?:(?:" + _WINDOWS_PREFIX_RE + r")\s+)*"
@@ -1050,7 +1115,9 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1050
1115
  spec.segment_index = index
1051
1116
  specs.append(spec)
1052
1117
 
1053
- for index, segment in enumerate(_split_segments(tokens)):
1118
+ raw_segments = _split_segments(tokens)
1119
+ command_segments: List[List[str]] = [[] for _ in raw_segments]
1120
+ for index, segment in enumerate(raw_segments):
1054
1121
  seg, from_xargs, prefix_uncertain = _unwrap_shell_prefixes(segment)
1055
1122
  if prefix_uncertain:
1056
1123
  opaque = " ".join(segment)
@@ -1061,6 +1128,7 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1061
1128
  continue
1062
1129
  if not seg:
1063
1130
  continue
1131
+ command_segments[index] = seg
1064
1132
  head = _basename(seg[0])
1065
1133
 
1066
1134
  if head == "cd":
@@ -1089,6 +1157,8 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1089
1157
 
1090
1158
  for spec in specs:
1091
1159
  spec.dialect = dialects.DIALECT_POSIX
1160
+ _append_dialect_mismatches(
1161
+ specs, command_segments, dialects.DIALECT_POSIX)
1092
1162
  _apply_shape_rules(specs, cd_positions, creation_positions)
1093
1163
  return [s for s in specs if s.kind != KIND_OTHER], None
1094
1164
 
@@ -1114,12 +1184,10 @@ def _classify_windows_dialect(cmd: str, dialect: str
1114
1184
  ) -> Tuple[List[OpSpec], Optional[str]]:
1115
1185
  """Native Windows dialects: lex, map effects, then shared annotations.
1116
1186
 
1117
- Rewriting the path separators before classification is what makes the
1118
- existing POSIX boundary/glob machinery work unchanged: on Linux a naive
1119
- `deploy\build` is one filename, so the boundary check would silently
1120
- treat a Windows tree as a file inside the workspace. Host-native
1121
- commands keep their separators - the running host already resolves
1122
- them.
1187
+ Rewriting target separators after tokenization gives the shared
1188
+ boundary/glob machinery one host-independent representation. Windows
1189
+ accepts `/`, while leaving `\\` in the fact makes Linux and Windows CI
1190
+ disagree about the same command.
1123
1191
 
1124
1192
  Shape rules (docs/friction.md F1/F2) apply to Windows lines too: `cd`
1125
1193
  and the interpreter prefix set are shared shell concepts, so F1 means
@@ -1142,12 +1210,9 @@ def _classify_windows_dialect(cmd: str, dialect: str
1142
1210
  creation_positions.append(index)
1143
1211
  for spec in specs:
1144
1212
  spec.dialect = dialect
1145
- if os.name != "nt":
1146
- # Path separation is a host concern, not a dialect concern:
1147
- # only rewrite on a non-Windows host, where `\` is an ordinary
1148
- # filename character and would defeat boundary analysis.
1149
- spec.targets = [t.replace("\\", "/") for t in spec.targets]
1213
+ spec.targets = [t.replace("\\", "/") for t in spec.targets]
1150
1214
  _attribute_targets(spec)
1215
+ _append_dialect_mismatches(specs, stream.segments, dialect)
1151
1216
  _apply_shape_rules(specs, cd_positions, creation_positions)
1152
1217
  return [s for s in specs if s.kind != KIND_OTHER], None
1153
1218
 
@@ -1156,8 +1221,10 @@ def classify_command(cmd: str, dialect: str = dialects.DEFAULT_DIALECT
1156
1221
  ) -> Tuple[List[OpSpec], Optional[str]]:
1157
1222
  """Parse one shell command line into destructive OpSpecs.
1158
1223
 
1159
- `dialect` selects the lexical front end: `posix` (default, identical to
1160
- pre-dialect behaviour), `cmd`, or `powershell`. Unknown dialect names
1224
+ `dialect` selects the lexical front end: `posix` (default), `cmd`, or
1225
+ `powershell`. Native POSIX command semantics remain stable, while the
1226
+ shared vocabulary floor may newly refuse a known destructive command
1227
+ that the selected grammar could not classify. Unknown dialect names
1161
1228
  raise ValueError rather than silently falling back to POSIX - parsing a
1162
1229
  Windows command line with the POSIX lexer is the exact failure the
1163
1230
  dialect layer exists to prevent.
package/core/dialects.py CHANGED
@@ -31,11 +31,12 @@ Design rules (mirroring the core's):
31
31
  another process, a wildcard handed to a tool that expands it itself -
32
32
  becomes an `undeterminable` fact. The policy layer turns those into
33
33
  BLOCK. We never guess what a target set will be.
34
- * **Additive.** The POSIX dialect preserves the exact behaviour of the
35
- historical `shlex`-based path, including the ALIAS vocabulary
36
- (`rm`/`ri`/`del` in PowerShell). The default dialect stays POSIX, so
37
- every existing adapter (Claude hook, DSH plugin, check.py CLI) is
38
- unaffected until a caller opts in.
34
+ * **Selected lexer, shared safety floor.** POSIX remains the default lexical
35
+ grammar, while cmd and PowerShell keep their own quoting and separators.
36
+ After structural classification, Core may add a target-free UNKNOWN when
37
+ the selected tokenizer exposed known destructive vocabulary that its
38
+ classifier could not safely interpret. That is an intentional fail-closed
39
+ change, never a guessed cross-shell compensation.
39
40
  * **Facts, not decisions.** Like the rest of the classifier, a dialect
40
41
  returns OpSpecs only; it never decides ALLOW/BLOCK.
41
42
 
@@ -92,7 +92,7 @@ neither do the lexical rules. `core/dialects.py` isolates both concerns:
92
92
 
93
93
  ```
94
94
  classify_command(cmd, dialect="posix")
95
- posix -> shlex + heredoc stripping (default; unchanged)
95
+ posix -> shlex + heredoc stripping (default lexer)
96
96
  cmd -> caret escapes, & separators, no
97
97
  backslash escapes in quotes, del/erase/rd/rmdir, /s /q
98
98
  powershell -> '' literal quoting, ` escapes, $() kept verbatim,
@@ -110,15 +110,16 @@ The dialect is selected by, in precedence order:
110
110
 
111
111
  Both adapters forward the *requested* selector verbatim rather than a
112
112
  resolved value, so `check.py` owns the single verdict for an unusable
113
- selector. Adapters also pick their cheap prefilter from the dialect: the
114
- POSIX regex cannot see `ri build -r -fo`, so a Windows session would
115
- otherwise skip the guard entirely. The POSIX prefilter is untouched, so
116
- the default path keeps its exact behaviour and cost.
113
+ selector. Their cheap prefilter screens both POSIX and Windows vocabularies:
114
+ the selector chooses the lexer, not whether a destructive-looking command
115
+ reaches Core at all.
117
116
 
118
117
  Four rules keep the layer honest:
119
118
 
120
- * **The default dialect is POSIX.** Every existing caller keeps its
121
- exact behaviour; opting in is explicit.
119
+ * **The default lexer is POSIX.** Existing POSIX syntax keeps POSIX quoting
120
+ and separator rules. The cross-vocabulary safety floor is deliberately
121
+ additive: a known destructive command that previously vanished on a
122
+ mismatch now blocks instead of becoming `ALLOW_NOOP`.
122
123
  * **An unknown dialect name is never a silent POSIX fallback.** The
123
124
  library raises/returns unusable; the CLI and adapters turn that into
124
125
  `BLOCK_DIALECT_UNKNOWN` (name not recognised) or
@@ -131,6 +132,12 @@ Four rules keep the layer honest:
131
132
  (`powershell -Command "..."`) all become undeterminable facts -> BLOCK.
132
133
  `-WhatIf:$true` is a dry run (ALLOW); `-WhatIf:$false` is a real delete;
133
134
  a *variable* switch value blocks.
135
+ * **Known destructive vocabulary cannot disappear on a dialect mismatch.**
136
+ The selected tokenizer defines command boundaries. If one of those
137
+ segments contains a supported destructive command shape but its dialect
138
+ classifier produced no operation, Core emits a target-free `UNKNOWN` fact
139
+ and blocks. It never reuses targets or flags guessed under another shell
140
+ grammar, and it does not scan ordinary argument text for dangerous words.
134
141
  * **Abbreviations expand only when unambiguous.** PowerShell resolves
135
142
  `-r`/`-rec` to `-Recurse` and `-fo` to `-Force`, and the guard follows so
136
143
  a recursive forced delete is not read as a mild one. A prefix matching
@@ -205,16 +212,24 @@ order of value:
205
212
  alias subset, `-WhatIf`/`-Recurse`/`-Force`/`-Confirm` semantics, and
206
213
  fail-closed handling of variables, subexpressions, piped target sets
207
214
  and nested hosts. Unit-tested on Linux CI; POSIX stays the default
208
- dialect so no existing adapter changes behaviour.
215
+ lexical grammar. Since `0.2.3-rc1`, the shared safety floor can turn a
216
+ previously invisible cross-vocabulary mismatch into a target-free
217
+ refusal without guessing another shell's targets.
209
218
  - **Phase 2 (done at the pure-logic/adapter-test level).** Differential
210
219
  and regression suites (`tests/test_dialects.py`,
211
220
  `tests/test_dialect_phase2.py`) cover further cmd/PowerShell spellings,
212
221
  option aliases and fail-closed edge cases. Hook payload dialect forwarding
213
222
  has adapter tests; this is not a Windows host execution claim.
214
- - **Phase 3 (not done; needs a real Windows host).** End-to-end
215
- validation: real cmd/PowerShell execution, relocation across Windows
216
- path semantics, host-selected dialect wiring, UNC/device paths and the
217
- portability gaps reported in `test-report-zcode-glm-flash.md`.
223
+ - **Phase 3a (`0.2.3-rc1` candidate).** A blocking `windows-latest` Core
224
+ job covers the Issue #7 dialect-mismatch and separator regressions,
225
+ deterministic cmd/PowerShell facts, and recovery inside disposable
226
+ fixtures. The job uses Python argv/bytes so a surrounding shell cannot
227
+ rewrite the evidence.
228
+ - **Phase 3 remains incomplete.** Real cmd/PowerShell execution through
229
+ each harness, host-selected dialect wiring, privileged symlink cases,
230
+ broader UNC/device paths and full-suite portability still require
231
+ separate evidence. A focused Core runner is not a universal Windows E2E
232
+ claim.
218
233
  - V2: `git-guard` skill (remote ref protection with lease semantics);
219
234
  adapter hardening (host-side mode storage, tamper-evident audit).
220
235
  - V3+: `database-guard` (compensations = transaction / backup /
@@ -37,11 +37,11 @@ While the major version is `0`:
37
37
 
38
38
  | Surface | Class | Notes |
39
39
  |---|---|---|
40
- | Command dialects (`cmd`, `powershell`) | minor | `classify_command(cmd, dialect=...)`; the default stays `posix`, so pre-existing callers are unaffected |
40
+ | Command dialects (`cmd`, `powershell`) | minor | `classify_command(cmd, dialect=...)`; the default lexical grammar stays `posix` |
41
41
  | `core/dialects.py` module + `TokenStream` | minor | Internal-but-documented; used by the dialect unit tests |
42
42
  | `OpSpec.dialect` field | minor | New field; unknown fields stay opaque to consumers |
43
43
  | `Ask` on PowerShell `-WhatIf` | minor | A dry run is an `ALLOW_NOOP`; a real delete keeps existing rules |
44
- | `check.py --dialect` flag | minor | Defaults to `posix`; omitting it is byte-for-byte the old behaviour |
44
+ | `check.py --dialect` flag | minor | Defaults to the POSIX lexical grammar; later safety releases may newly block a previously invisible known destructive vocabulary mismatch |
45
45
  | `AGENT_GUARD_DIALECT` env var | minor | Read by `check.py` and the native shell adapters; unset means `posix` |
46
46
  | `BLOCK_DIALECT_UNKNOWN` / `BLOCK_DIALECT_INVALID` | minor | New reason codes (additive) |
47
47
  | `BLOCK_PROTECTED_ANCESTOR` | minor | New reason code (additive). Filesystem roots (`/`, `/home`, `/usr`, `$HOME`, ...) are refused by identity rather than by falling outside the workspace |
@@ -54,6 +54,7 @@ While the major version is `0`:
54
54
  | `.agent-guard/exfil-allow.toml` exemption file | minor | Read from the workspace root only; values exempted by `sha256:...`, never by value |
55
55
  | `doctor.py --check-drift` report and adapter `compatibility.json` profiles | minor | Additive local preflight. Without drift flags the doctor keeps its previous process-execution and exit behavior; `CURRENT` never promotes live interception above `UNVERIFIED` |
56
56
  | `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
57
+ | Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
57
58
 
58
59
  ### 0.2.0 check output minimization
59
60
 
@@ -84,9 +85,13 @@ unknown selector must produce a Decision Protocol verdict with a reason
84
85
  code; a usage error carries none, and a harness could read "no decision" as
85
86
  "nothing to worry about".
86
87
 
87
- Phase 3 (real Windows end-to-end validation, UNC/device paths, module
88
- auto-loading) has not happened. The dialect layer stays additive and
89
- opt-in so Windows support lands without changing any POSIX verdict.
88
+ `0.2.3-rc1` adds a focused real-Windows Core gate for dialect mismatch,
89
+ separator normalization, disposable-fixture recovery and exact-byte path
90
+ redaction. It also makes known destructive vocabulary fail closed when it
91
+ does not match the configured dialect. This is only Phase 3a: native
92
+ cmd/PowerShell execution through each harness, hook-selected dialect wiring,
93
+ broader UNC/device paths, module auto-loading and full-suite Windows
94
+ portability remain unverified.
90
95
 
91
96
  ### PowerShell parameter prefixes
92
97
 
package/docs/friction.md CHANGED
@@ -264,3 +264,26 @@ without data is still a legitimately empty payload (ALLOW, since nothing
264
264
  can leak); and on platforms where stdin is not selectable the code falls
265
265
  back to the blocking read rather than refusing a caller whose payload may
266
266
  be perfectly good.
267
+
268
+ ## F16 · A selected shell dialect could erase a known hazard
269
+
270
+ The dialect selector chose both a tokenizer and its recognized command
271
+ vocabulary. That made a configuration mismatch asymmetric: `rm -rf .`
272
+ was a protected-root refusal under POSIX, but the cmd classifier returned no
273
+ operation and policy reported `ALLOW_NOOP`. A mixed line was worse: one
274
+ recognized Windows delete could make the result look guarded while a later
275
+ POSIX delete segment remained invisible. Separately, Windows-native targets
276
+ kept backslashes only when Core itself ran on Windows, so identical command
277
+ text produced host-dependent path facts.
278
+
279
+ **Fixed in `0.2.3-rc1`:** the selected tokenizer still owns command
280
+ boundaries and quoting semantics, but every resulting segment also passes a
281
+ small, shared destructive-vocabulary floor. A known delete, destructive Git
282
+ shape, or `find -delete` shape that its selected classifier did not resolve
283
+ becomes target-free `UNKNOWN` and therefore
284
+ `BLOCK_UNDETERMINABLE_EFFECT`. Core never re-parses the segment under a
285
+ different grammar and never invents a compensation target. Recognized
286
+ Windows delete targets are normalized after their own tokenizer on every
287
+ host, removing the OS-dependent fact split. Negative tests pin quoted output
288
+ and shell-specific literal syntax so the safety floor does not become a
289
+ substring blacklist.
@@ -0,0 +1,92 @@
1
+ # Agent Guard 0.2.3-rc1 — Windows Core fail-closed candidate
2
+
3
+ These notes describe the `0.2.3-rc1` source candidate. A version in the
4
+ repository is not proof that its tag, GitHub prerelease, or npm package has
5
+ been published. The latest stable npm installation remains `0.2.2` unless the
6
+ registry says otherwise.
7
+
8
+ ## Issue #7: two confirmed Core fixes
9
+
10
+ [Issue #7](https://github.com/mokuyoaxis/agent-guard/issues/7) reported two
11
+ fail-open paths from a Windows 11 CLI run. The runner was WorkBuddy, but every
12
+ reproduction called Core directly; these were not adapter findings.
13
+
14
+ 1. A known destructive command could disappear when its vocabulary did not
15
+ match the configured dialect. In particular, `rm -rf .` changed from
16
+ `BLOCK_PROTECTED_PATH` under POSIX to `ALLOW_NOOP` under `cmd`.
17
+ 2. Windows-native delete targets kept or lost backslashes according to the OS
18
+ running the classifier. On Windows, `del build\o.js` could become either
19
+ `buildo.js` or a host-specific target fact and fall through as a no-op.
20
+
21
+ The classifier now treats the selected dialect's command segmentation as the
22
+ authoritative boundary, then checks every segment for known destructive
23
+ vocabulary that produced no operation. A mismatch becomes a target-free,
24
+ non-compensable `UNKNOWN` fact and therefore
25
+ `BLOCK_UNDETERMINABLE_EFFECT`. It does not borrow targets or flags from a
26
+ different shell grammar. Mixed lines are checked segment by segment, so an
27
+ earlier recognized delete cannot hide a later mismatch.
28
+
29
+ This safety floor covers the existing filesystem-delete vocabulary and the
30
+ already supported destructive Git/`find -delete` shapes. It does not block
31
+ all unknown commands. Negative regressions keep ordinary `echo`,
32
+ `Write-Host`, `git status`, quoted command text and cmd-literal `$()` forms
33
+ quiet.
34
+
35
+ Windows-native delete targets are now normalized to `/` after their own
36
+ tokenizer has identified them, on every host OS. The default POSIX bridge
37
+ performs the same rewrite only for its existing standalone Windows-verb
38
+ compatibility path. Normal POSIX escape semantics such as `rm a\ b` are not
39
+ globally rewritten.
40
+
41
+ ## Withdrawn exfil report
42
+
43
+ The issue's third finding was withdrawn by its reporter after an exact-byte
44
+ rerun. Git Bash `printf` had changed the backslashes and newline before the
45
+ payload reached `check_span.py`. Python `subprocess` input confirmed that
46
+ native, forward-slash, mixed-separator and UNC Windows absolute paths were
47
+ already classified and sanitized correctly.
48
+
49
+ This candidate does not change `core/redaction.py` or expand exfil policy. It
50
+ adds a regression that constructs the native Windows path in Python, supplies
51
+ matching `USERPROFILE`/`USERNAME` markers, and requires
52
+ `SANITIZE_PATH_REWRITE` without reproducing the matched bytes in output.
53
+
54
+ ## Focused Windows CI
55
+
56
+ CI now includes a blocking `windows-latest` / Python 3.13 Core job. It runs
57
+ the cmd/PowerShell dialect suite, the two Issue #7 CLI regressions, a safe
58
+ temporary-directory relocate/restore round trip, and the exact-byte exfil
59
+ regression. Test inputs are passed by Python rather than shell `printf` or
60
+ `echo`, so Git Bash cannot silently rewrite them. The existing Linux/macOS
61
+ matrix continues to run the full suite.
62
+
63
+ A passing run is bounded real-Windows evidence for the listed Core paths,
64
+ not completion of the entire Windows roadmap. It does not prove native
65
+ cmd/PowerShell execution by every harness, hook-selected dialect wiring,
66
+ privileged symlink behavior, all UNC/device paths, or full-suite portability.
67
+
68
+ ## Prerelease publishing
69
+
70
+ The release workflow now accepts the project's exact `X.Y.Z-rcN` tag shape in
71
+ addition to stable `X.Y.Z` tags. A tested channel classifier routes RCs to a
72
+ GitHub prerelease and npm's `rc` dist-tag; stable versions use `latest`. The
73
+ tag and `package.json` version must still match exactly, and GitHub Release
74
+ plus npm still receive the same packed tarball with provenance.
75
+
76
+ If published, install this candidate explicitly as
77
+ `@mokuyoaxis/agent-guard@0.2.3-rc1` or through
78
+ `@mokuyoaxis/agent-guard@rc`. An RC publication must not move npm `latest`
79
+ away from `0.2.2`.
80
+
81
+ ## Verification and limits
82
+
83
+ The local candidate gate passes 450 Python tests plus the DSH adapter smoke
84
+ test. [GitHub Actions run 36366616252](https://github.com/mokuyoaxis/agent-guard/actions/runs/36366616252)
85
+ passed all 12 jobs for implementation commit `7b83649`, including the focused
86
+ Windows Core gate on `windows-latest` / Python 3.13. This is the bounded
87
+ evidence described above, not a universal Windows-harness claim. No tag,
88
+ GitHub prerelease, npm publication, or Issue closure is implied by these
89
+ notes.
90
+
91
+ `guard-lab` is not included in `0.2.3-rc1`. It remains planned for the next
92
+ available 0.2.3 candidate after the Windows fix is stable.
@@ -104,7 +104,7 @@ relocations and restores succeed end-to-end.
104
104
  fixture now spells the path with forward slashes, matching what the shell
105
105
  would actually see on this platform.
106
106
 
107
- ### Verified non-issue: backslash targets do not bypass the guard
107
+ ### Verified non-issue within the tested Git Bash `rm` path
108
108
 
109
109
  `rm -rf C:\...\build` (unquoted, unquoted-backslash) classifies as
110
110
  `ALLOW_NOOP` because `shlex` posix-tokenization strips the backslashes — the
@@ -114,6 +114,13 @@ and shell therefore agree on the effective target, and no fail-open gap exists
114
114
  on this harness. Quoted and forward-slash spellings — the forms that do delete
115
115
  — classify correctly (`RELOCATE_TREE`).
116
116
 
117
+ This conclusion is deliberately limited to POSIX `rm` under the tested Git
118
+ Bash execution path. It does not cover Windows-native `del`/`rd`/
119
+ `Remove-Item`, where a backslash is a separator rather than an escape.
120
+ Issue #7 later demonstrated that those target facts varied by host OS;
121
+ `0.2.3-rc1` normalizes recognized Windows-native targets independently of the
122
+ machine running Core and pins them in a focused Windows CI job.
123
+
117
124
  ### ZCode integration properties (harness, not agent-guard)
118
125
 
119
126
  - **Project hooks load at session start and require workspace trust.** The
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.2",
3
+ "version": "0.2.3-rc1",
4
4
  "description": "Harness-neutral reliability infrastructure for AI coding agents: reversible destructive actions, pre-emission redaction, recovery evidence, and a shared Decision Protocol with optional native adapters.",
5
5
  "type": "module",
6
6
  "main": "./adapters/dsh/lib/index.js",