universal-dev-standards 6.14.0 → 6.14.1-beta.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.
package/bin/uds.js CHANGED
@@ -238,7 +238,7 @@ program
238
238
  .option('--add-standard <id>', 'With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available)', (value, previous) => [...previous, value], [])
239
239
  .option('--claude-target <target>', 'Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall')
240
240
  .option('--locale <locale>', 'Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env')
241
- .option('--with-hooks', 'Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; with --plan, writes nothing; --force also overwrites edited hook scripts)')
241
+ .option('--with-hooks', 'Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; a hook script that is an unmodified copy from an older UDS is replaced, an edited one is kept; with --plan, writes nothing; --force also overwrites edited hook scripts)')
242
242
  .option('--ai-tool <tools>', 'With --with-hooks: comma-separated tools to install hooks for (claude-code, codex, gemini-cli, antigravity) instead of detecting them')
243
243
  .action(updateCommand);
244
244
 
@@ -3,8 +3,8 @@
3
3
 
4
4
  id: mock-boundary
5
5
  meta:
6
- version: "1.2.0"
7
- updated: "2026-07-01"
6
+ version: "1.3.0"
7
+ updated: "2026-10-28"
8
8
  source: core/mock-boundary.md
9
9
  description: >
10
10
  Rules defining what can and cannot be mocked to prevent hollow tests —
@@ -14,6 +14,13 @@ meta:
14
14
  v1.2.0: Added injectable background execution as a seam (parallel to clock
15
15
  injection) — allowed background-runner seam, no-poll/sleep rule, and the
16
16
  poll/sleep-for-background-result anti-pattern (issue #143).
17
+ v1.3.0: Added blocking-hook entry testing (H1 MUST: spawn the hook, send the
18
+ host's stdin payload, assert the signal the host reads), the per-host block
19
+ signal table, and the replay-validates-wiring-not-rules note. Counter-example:
20
+ UDS's own dangerous-command hook blocked 0 of 26 (exit 1; Claude Code blocks on exit 2).
21
+ related:
22
+ - turn-completion-integrity
23
+ - verification-oracle
17
24
 
18
25
  # ─────────────────────────────────────────────────────────
19
26
  # Mock Levels (v1.1.0)
@@ -178,6 +185,116 @@ allowed:
178
185
  async settle(): Promise<void> { await Promise.all(this.tasks) }
179
186
  }
180
187
 
188
+ # ─────────────────────────────────────────────────────────
189
+ # Blocking Hooks: test the host's entry, not the matcher (v1.3.0)
190
+ # ─────────────────────────────────────────────────────────
191
+ blocking_hooks:
192
+ definition: >
193
+ A hook is a script an AI host (Claude Code, Codex, Gemini CLI, Antigravity CLI)
194
+ runs at a lifecycle event. It has a judgement layer (is this command dangerous?)
195
+ and a wiring layer (read the host's stdin payload, answer in the signal the host
196
+ reads). A unit test of the judgement function exercises only the first layer.
197
+ counter_example:
198
+ hook: scripts/hooks/check-dangerous-cmd.mjs (PreToolUse)
199
+ fault: "exited 1 on detection; Claude Code blocks a tool call only on exit 2, any other non-zero code is a non-blocking hook error"
200
+ why_tests_were_green: "tests imported isDangerousCommand() and called it; no test ran the hook as a process"
201
+ measurement: "replay of 11,617 real shell calls (2026-10-27): rule `rm -rf /` fired 26 times, the host blocked 0; 25 were harmless temp cleanups, none a real root wipe; `rm -fr /` and `rm -r -f /` were missed"
202
+ fixed_in: "PR #281"
203
+ rules:
204
+ h1_host_entry_test:
205
+ level: MUST
206
+ applies_to: "a hook that can stop a tool call, a prompt, or a turn"
207
+ rule: >
208
+ At least one test (1) runs the hook as a separate process with the command
209
+ the host config runs, (2) sends the host's own stdin payload with that host's
210
+ field names, (3) asserts the signal the host reads: the exact exit code or
211
+ the JSON the host parses on stdout.
212
+ does_not_count:
213
+ - "a test that imports and calls an internal function"
214
+ - "asserting only 'non-zero' or 'exited with error' (exit 1 is non-zero and blocks nothing on Claude Code)"
215
+ - "asserting only that stderr contains a word"
216
+ - "a payload shaped like the author's idea of the host"
217
+ also_applies_to: "a hook whose only effect is that the host reads its signal, e.g. PostToolUse exit 2 to put stderr in front of the model"
218
+ h2_pair_with_allow_case:
219
+ level: SHOULD
220
+ rule: Run an allowing case the same way and assert the host's allow signal; a hook that blocks everything passes a blocking-only test
221
+ h3_cut_check:
222
+ level: SHOULD
223
+ rule: Change the hook's block signal (e.g. exit 2 to exit 1) and confirm the entry test goes red
224
+ # Single place for non-Stop block signals. Stop-type events are in
225
+ # turn-completion-integrity (supported_harnesses) and are not repeated here.
226
+ # Retrieved 2026-10-28 from each host's own documentation; re-check before relying on a cell.
227
+ # "not found" = page read and silent, which is not "no".
228
+ host_block_signals:
229
+ - host: claude-code
230
+ event: PreToolUse
231
+ blocks: 'exit 2 (stderr is the reason); or exit 0 + stdout {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}'
232
+ does_not_block: "any other exit code including 1 (non-blocking hook error, action proceeds); invalid JSON. Exception stated by the docs: a hook configured with onFailure: \"block\" blocks when it fails"
233
+ source: "code.claude.com/docs/en/hooks (Exit code output, Exit code 2, Other exit codes, Decision control)"
234
+ - host: claude-code
235
+ event: UserPromptSubmit
236
+ blocks: 'exit 2; or exit 0 + stdout {"decision":"block","reason":"..."}'
237
+ does_not_block: "any other exit code (same onFailure: \"block\" exception)"
238
+ source: "code.claude.com/docs/en/hooks (Exit code 2 behavior per event)"
239
+ - host: claude-code
240
+ event: PostToolUse
241
+ blocks: "cannot block: the tool already ran; exit 2 only shows stderr to the model"
242
+ does_not_block: "any exit code, for blocking purposes"
243
+ source: "code.claude.com/docs/en/hooks (Exit code 2 behavior per event)"
244
+ - host: codex
245
+ event: PreToolUse
246
+ blocks: 'exit 2 with reason on stderr; or stdout {"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}; legacy {"decision":"block","reason":"..."} also accepted'
247
+ does_not_block: "plain stdout is ignored; permissionDecision ask, continue:false, stopReason, suppressOutput unsupported (hook run marked failed, tool call continues); other non-zero exit codes: not found"
248
+ source: "developers.openai.com/codex/hooks (PreToolUse)"
249
+ - host: codex
250
+ event: UserPromptSubmit
251
+ blocks: 'exit 2 with reason on stderr; or stdout {"decision":"block","reason":"..."}'
252
+ does_not_block: "plain stdout is added as context; other non-zero exit codes: not found"
253
+ source: "developers.openai.com/codex/hooks (UserPromptSubmit)"
254
+ - host: codex
255
+ event: PermissionRequest
256
+ blocks: 'stdout {"hookSpecificOutput":{"decision":{"behavior":"deny","message":"..."}}}; any deny wins'
257
+ does_not_block: "exit 2 for this event: not found; plain stdout is ignored"
258
+ source: "developers.openai.com/codex/hooks (PermissionRequest)"
259
+ - host: gemini-cli
260
+ status: legacy
261
+ event: BeforeTool
262
+ blocks: 'exit 2 (stderr is the reason sent to the agent); or exit 0 + stdout {"decision":"deny","reason":"..."} ("block" is an alias; docs name the JSON form preferred)'
263
+ does_not_block: "any other exit code is a warning and the CLI continues"
264
+ source: "geminicli.com/docs/hooks/reference (Global hook mechanics, BeforeTool)"
265
+ - host: gemini-cli
266
+ status: legacy
267
+ event: BeforeAgent, BeforeModel
268
+ blocks: "exit 2 aborts the turn (BeforeAgent also erases the prompt; BeforeModel skips the LLM call); or decision deny"
269
+ does_not_block: "as BeforeTool"
270
+ source: "geminicli.com/docs/hooks/reference"
271
+ - host: antigravity-cli
272
+ event: PreToolUse
273
+ blocks: 'exit 0 + stdout {"decision":"deny","reason":"..."} (hard block). decision is required; other values: allow, auto_approve, ask, force_ask, deny_unless_prior_grant. stdin has toolCall.name and toolCall.args, not tool_name/tool_input'
274
+ does_not_block: "exit-code semantics: not found (official page silent); do not assume Claude Code's exit 2; a third-party claim that any non-zero denies is not official and not used"
275
+ source: "antigravity.google/docs/hooks (Input and output contract, PreToolUse)"
276
+ - host: cursor-and-others
277
+ event: any
278
+ blocks: "not found (not surveyed in this revision)"
279
+ does_not_block: "not found"
280
+ source: none
281
+ replay_validates_wiring_not_rules:
282
+ rule: >
283
+ A replay of recorded calls through a hook, where the same rule list decides both
284
+ "should block" and "should not", proves the hook behaves as its rules say. It
285
+ does not prove the rules are right. Report it as "wiring correct", never as "rules correct".
286
+ evidence: >
287
+ The 0-of-26 result was measurable because the host's contract (exit 2 blocks)
288
+ is a fact outside the hook. For which commands deserve blocking there was only the
289
+ hook's own pattern: 26 hits consistent with it, 0 real dangers, and `rm -fr /`
290
+ could never appear as a miss because the oracle shares the blind spot.
291
+ instead: "read the commands that actually matched, or keep a separate answer key written without looking at the hook's patterns (see verification-oracle)"
292
+ enforcement_in_uds: >
293
+ CI runs `node scripts/check-hook-entry-tests.mjs` (npm run check:hook-entry-tests):
294
+ fails when a shipped hook that can block has no test that spawns it, feeds stdin and
295
+ asserts the host's signal. Static analysis: proves a test of the right shape exists,
296
+ not that it would go red if the hook regressed (that is H3).
297
+
181
298
  # ─────────────────────────────────────────────────────────
182
299
  # Forbidden Mocks
183
300
  # ─────────────────────────────────────────────────────────
@@ -343,6 +460,24 @@ rules:
343
460
  the tracked task, then assert on success, exception, or retry.
344
461
  priority: required
345
462
 
463
+ - id: blocking-hook-host-entry-test
464
+ trigger: writing or reviewing tests for a hook that can stop a tool call, a prompt, or a turn
465
+ instruction: >
466
+ Require at least one test that spawns the hook as a process, sends the host's own
467
+ stdin payload, and asserts the exit code or stdout JSON the host reads
468
+ (see blocking_hooks.host_block_signals). A test that imports and calls an internal
469
+ function does not count. Pair with an allowing case; confirm the test goes red when
470
+ the block signal is changed.
471
+ priority: required
472
+
473
+ - id: replay-proves-wiring-only
474
+ trigger: reporting the result of replaying real calls through a hook
475
+ instruction: >
476
+ If the same rule list decided both "should block" and "should not", report
477
+ "wiring correct", not "rules correct". Check rules against matched commands or an
478
+ independent answer key.
479
+ priority: required
480
+
346
481
  - id: level-2-stub-server-rules
347
482
  trigger: UAT environment lacks a real external service (SMS, payment, IdP)
348
483
  instruction: >
@@ -385,3 +520,4 @@ quick_reference:
385
520
  □ Mock count < import count (or justified with comment)
386
521
  □ At least one assertion on actual output value (not mock call)
387
522
  □ Integration counterpart exists for each cross-module mock
523
+ □ Each blocking hook has a test that spawns it, sends the host's payload, and asserts the host's signal
@@ -3,11 +3,12 @@
3
3
 
4
4
  id: turn-completion-integrity
5
5
  meta:
6
- version: "1.5.0"
7
- updated: "2026-09-29"
6
+ version: "1.5.1"
7
+ updated: "2026-10-28"
8
8
  source: core/turn-completion-integrity.md
9
9
  description: An agent must not end a turn having stated a next action it did not take; enforced at turn end, not by instruction
10
10
  related:
11
+ - mock-boundary
11
12
  - agent-behavior-discipline
12
13
  - ai-response-navigation
13
14
  - anti-hallucination
@@ -117,6 +118,9 @@ enforcement:
117
118
  severity: warning
118
119
  timeout_ms: 2000
119
120
 
121
+ # Stop-type events only. Block signals for events that stop a tool call or a prompt
122
+ # (PreToolUse, UserPromptSubmit, BeforeTool) live in mock-boundary (host_block_signals)
123
+ # and are not repeated here.
120
124
  # The check is enforced only where an adapter exists AND a hook is wired into
121
125
  # that harness's own config. This is separate from `enforcement:` above, which
122
126
  # only describes the Claude Code entry the generic installer walks — Codex,
@@ -1,7 +1,7 @@
1
1
  # Mock Boundary Standards
2
2
 
3
- **Version**: 1.1.0
4
- **Last Updated**: 2026-07-01
3
+ **Version**: 1.3.0
4
+ **Last Updated**: 2026-10-28
5
5
  **Applicability**: All software projects with unit and integration tests
6
6
  **Scope**: universal
7
7
  **Industry Standards**: ISTQB Foundation (Test Doubles), xUnit Patterns (Gerard Meszaros)
@@ -101,6 +101,67 @@ The test injects `DeterministicDispatcher`, exercises the code under test, then
101
101
 
102
102
  ---
103
103
 
104
+ ## Blocking Hooks: Test the Host's Entry, Not the Matcher
105
+
106
+ A **hook** is a script an AI host (Claude Code, Codex, Gemini CLI, Antigravity CLI, and others) runs at a lifecycle event. Some hooks can **stop** what the host was about to do: refuse a tool call, reject a prompt, keep a turn from ending. For these the hollow-test problem needs no mock at all. The test simply never touches the entry the host calls.
107
+
108
+ A hook has two layers. The **judgement** decides whether this command is dangerous. The **wiring** reads the host's stdin payload and answers in the signal the host reads (an exit code, or JSON on stdout). A unit test that imports the judgement function exercises the first layer only, and the host reads the second. A wrong exit code, a payload field read under the wrong name, or output in a shape the host ignores all leave that test green.
109
+
110
+ ### Counter-example: UDS's own dangerous-command hook blocked 0 of 26
111
+
112
+ `scripts/hooks/check-dangerous-cmd.mjs` is a PreToolUse hook. When it detected a dangerous command it exited **1**. Claude Code blocks a tool call only on exit **2**; any other non-zero code is a non-blocking hook error and the command runs anyway. Its tests imported the matcher function (`isDangerousCommand()`) and called it directly, so they were green for months.
113
+
114
+ Replaying 11,617 real shell calls (2026-10-27) the rule `rm -rf /` fired 26 times. The host blocked **0** of them. 25 of the 26 were harmless temp cleanups such as `rm -rf /tmp/x`; none was a real attempt to wipe the root. The same pattern missed `rm -fr /` and `rm -r -f /`. The fix and its entry tests shipped in PR #281.
115
+
116
+ ### Rules
117
+
118
+ **H1 (MUST).** A hook that can stop a tool call, a prompt or a turn MUST have at least one test that does all three:
119
+
120
+ 1. **Runs the hook as a separate process**, with the same command the host's config runs. Spawning the script counts; importing it does not.
121
+ 2. **Sends the host's own payload on stdin**, with the field names that host uses (see the table below: Claude Code sends `tool_name` / `tool_input`, Antigravity sends `toolCall`). A payload shaped like the author's idea of the host proves nothing.
122
+ 3. **Asserts the signal the host reads**: the exact exit code, or the JSON the host parses on stdout. "Non-zero", "exited with an error" and "stderr contained the word" do not count: exit 1 is non-zero and blocks nothing on Claude Code.
123
+
124
+ A test that imports and calls an internal function MAY exist and is useful for the judgement, but it does not count toward H1.
125
+
126
+ **H2 (SHOULD).** Pair the blocking case with an allowing case run the same way, and assert the host's allow signal (for example exit 0 with nothing on stdout). A hook that blocks everything passes a blocking-only test.
127
+
128
+ **H3 (SHOULD).** Cut check: change the hook's block signal (for example `exit 2` to `exit 1`) and confirm the entry test goes red. A test that stays green has not been guarding the wiring.
129
+
130
+ H1 also applies to a hook whose only effect is that the host reads its signal, such as a PostToolUse hook that uses exit 2 to put its stderr in front of the model. The tool has already run, so it cannot be undone, but a wrong code silences the hook just the same.
131
+
132
+ ### What each host reads as "blocked"
133
+
134
+ Retrieved 2026-10-28 from each host's own documentation. Hosts change these contracts; re-check the source before relying on a cell, and when a cell says "not found" the page was read and says nothing, which is not the same as "no".
135
+
136
+ | Host | Event | Blocks | Does not block | Source |
137
+ |---|---|---|---|---|
138
+ | Claude Code | PreToolUse | exit **2** (stderr is the reason); or exit 0 with stdout `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}` | any other exit code, **including 1**, is a non-blocking hook error and the action proceeds; invalid JSON likewise. Exception stated by the docs: a hook configured with `onFailure: "block"` blocks when it fails | code.claude.com/docs/en/hooks: Exit code output, Exit code 2, Other exit codes, Decision control |
139
+ | Claude Code | UserPromptSubmit | exit **2** (the prompt never reaches the model); or exit 0 with stdout `{"decision":"block","reason":"..."}` | any other exit code (same `onFailure: "block"` exception) | same page, Exit code 2 behavior per event |
140
+ | Claude Code | PostToolUse | cannot block: the tool already ran. Exit 2 only shows stderr to the model | any exit code, for blocking purposes | same page, Exit code 2 behavior per event |
141
+ | Codex | PreToolUse | exit **2** with the reason on stderr; or stdout `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"..."}}`; the older `{"decision":"block","reason":"..."}` is also accepted | plain text on stdout is ignored; `permissionDecision:"ask"`, `continue:false`, `stopReason`, `suppressOutput` are not supported and the hook run is marked failed while the tool call continues; other non-zero exit codes: not found | developers.openai.com/codex/hooks, PreToolUse |
142
+ | Codex | UserPromptSubmit | exit **2** with the reason on stderr; or stdout `{"decision":"block","reason":"..."}` | plain text on stdout is added as context; other non-zero exit codes: not found | same page, UserPromptSubmit |
143
+ | Codex | PermissionRequest | stdout `{"hookSpecificOutput":{"decision":{"behavior":"deny","message":"..."}}}`; any `deny` wins | exit 2 for this event: not found; plain text on stdout is ignored | same page, PermissionRequest |
144
+ | Gemini CLI (legacy) | BeforeTool | exit **2** (stderr is the reason sent to the agent); or exit 0 with stdout `{"decision":"deny","reason":"..."}` (`"block"` is an alias). The docs name the JSON form the preferred path | any other exit code is a warning and the CLI continues | geminicli.com/docs/hooks/reference, Global hook mechanics and BeforeTool |
145
+ | Gemini CLI (legacy) | BeforeAgent, BeforeModel | exit **2** aborts the turn (BeforeAgent also erases the prompt from context; BeforeModel skips the LLM call); or `decision:"deny"` | as above | same page |
146
+ | Antigravity CLI (`agy`) | PreToolUse | exit 0 with stdout `{"decision":"deny","reason":"..."}` ("Hard blocks execution immediately"). The `decision` field is required; its other values are `allow`, `auto_approve`, `ask`, `force_ask`, `deny_unless_prior_grant`. stdin carries `toolCall.name` and `toolCall.args`, not Claude Code's names | exit-code semantics: not found (the official page is silent). Do not assume Claude Code's exit 2 applies. A third-party guide claims any non-zero code denies; it is not official and is not used here | antigravity.google/docs/hooks, Input and output contract, PreToolUse |
147
+ | Cursor and other hosts | any | not found (not surveyed in this revision) | not found | none |
148
+
149
+ Stop-type events (Claude Code and Codex Stop, Gemini CLI AfterAgent, Antigravity Stop) are **not repeated here**. Their block contracts are in the "Supported harnesses" table of [turn-completion-integrity](turn-completion-integrity.md), the single place they are written down. That table also records one case where a failed Antigravity hook was let through silently, which is the same wiring failure this section is about.
150
+
151
+ ### A replay validates the wiring, not the rules
152
+
153
+ Replaying recorded real calls through a hook (for example with rules-to-guards) is a strong way to check the wiring. It has a limit that must be stated whenever its result is reported. If the same rule list decides both "this should be blocked" and "this should not", the replay proves the hook behaves as its rules say. It does not prove the rules are right.
154
+
155
+ The 0-of-26 measurement could be made because the host's contract (exit 2 blocks) is a fact outside the hook. For "which commands deserve blocking" there was only the hook's own pattern: all 26 hits were consistent with it, 0 were real dangers, and `rm -fr /`, which the pattern did not cover, could never show up as a miss because the oracle shares the blind spot.
156
+
157
+ So report a replay as "wiring is correct" or "wiring is wrong". Do not report "the rules are correct" from it. To say anything about the rules, read the commands that actually matched, or keep a separate answer key (see [verification-oracle](verification-oracle.md)) written without looking at the hook's patterns.
158
+
159
+ ### Enforcement in UDS
160
+
161
+ UDS checks this rule against its own shipped hooks in CI: `node scripts/check-hook-entry-tests.mjs` (npm run `check:hook-entry-tests`) fails when a hook UDS ships that can block has no test that spawns it, feeds stdin and asserts the host's signal. It is static text analysis: it shows that a test of the right shape exists, not that the test would go red if the hook regressed. That is what H3 is for.
162
+
163
+ ---
164
+
104
165
  ## Hollow Test Detection
105
166
 
106
167
  Before submitting a test file, check:
@@ -109,6 +170,7 @@ Before submitting a test file, check:
109
170
  2. **All assertions are `.toHaveBeenCalled()` variants** → Add output-value assertions
110
171
  3. **Mock path matches test subject directory** → Self-referential mock; remove it
111
172
  4. **More mock setup lines than assertion lines** → Likely hollow
173
+ 5. **A blocking hook whose tests only import and call its functions** → Add an entry test that spawns it and asserts the host's signal (see Blocking Hooks)
112
174
 
113
175
  ---
114
176
 
@@ -119,6 +181,7 @@ Before submitting a test file, check:
119
181
  - **Orphan Mock**: Cross-module mock with no integration test counterpart
120
182
  - **Security Bypass Mock**: Auth/permission logic replaced with pass-through stub
121
183
  - **Database Mock Cascade**: DB returns hardcoded data, hiding real query errors
184
+ - **Matcher-Only Hook Test**: A blocking hook whose tests import and call its judgement function and never run the hook as the host does. Green while the hook blocks nothing (UDS's own 0-of-26)
122
185
  - **Poll/Sleep for Background Result**: Sleeping or polling to wait for fire-and-forget work to finish. The race is still there — the timeout merely hides it most of the time while slowing the whole suite and, on a shared runner, leaking flakiness into other MRs' CI. Inject a deterministic runner and await the tracked task instead.
123
186
 
124
187
  ---
@@ -133,6 +196,8 @@ Before submitting a test file, check:
133
196
  | No security mock | Test involves auth/permissions | Use real test user + real token |
134
197
  | Hollow review | Mock count ≥ import count | Add output-value assertion |
135
198
  | No poll/sleep for background work | Test asserts a fire-and-forget side effect | Inject deterministic runner; await the tracked task |
199
+ | Host entry test for blocking hooks | Hook can stop a tool call, prompt or turn | Spawn it, send the host's payload on stdin, assert the exit code or stdout JSON the host reads |
200
+ | Replay proves wiring only | Reporting a replay of real calls through a hook | Report "wiring correct"; do not report "rules correct" unless the rules were checked against an independent answer |
136
201
 
137
202
  ---
138
203
 
@@ -141,6 +206,8 @@ Before submitting a test file, check:
141
206
  - **testing**: Mock boundary rules apply to all test levels in the testing pyramid
142
207
  - **test-completeness-dimensions**: Dimension 8 (AI Test Quality) references these rules
143
208
  - **flow-based-testing**: Flow tests must follow mock boundary rules
209
+ - **turn-completion-integrity**: Holds the block contracts for Stop-type events; this standard holds them for tool and prompt events, and neither repeats the other
210
+ - **verification-oracle**: An answer key for judging whether a hook's rules are right must not be derived from the hook's own patterns
144
211
 
145
212
  ---
146
213
 
@@ -150,3 +217,4 @@ Before submitting a test file, check:
150
217
  |---------|------|--------|
151
218
  | 1.0.0 | 2026-05-04 | Initial standard: hollow test problem, CAN/CANNOT mock tables, detection, anti-patterns, rules summary |
152
219
  | 1.1.0 | 2026-07-01 | Added injectable background execution as a seam (parallel to clock injection): CAN-mock row, `Injectable Background Execution` section, `Poll/Sleep for Background Result` anti-pattern, and no-poll/sleep rule (issue #143) |
220
+ | 1.3.0 | 2026-10-28 | Added `Blocking Hooks: Test the Host's Entry, Not the Matcher`: H1 MUST (spawn the hook, send the host's stdin payload, assert the signal the host reads), H2/H3 SHOULD, the per-host block-signal table, and the replay-validates-wiring-not-rules note, with UDS's own 0-of-26 as the counter-example. Number re-aligned with `mock-boundary.ai.yaml`, which had used 1.2.0 for the background-execution addition recorded here as 1.1.0 |
@@ -2,8 +2,8 @@
2
2
 
3
3
  > **Language**: English | [繁體中文](../locales/zh-TW/core/turn-completion-integrity.md)
4
4
 
5
- **Version**: 1.5.0
6
- **Last Updated**: 2026-09-29
5
+ **Version**: 1.5.1
6
+ **Last Updated**: 2026-10-28
7
7
  **Applicability**: Any harness where an agent ends a turn and hands control back to a human
8
8
  **Scope**: universal
9
9
  **Industry Standards**: none claimed — derived from observed failures, see Evidence
@@ -158,6 +158,12 @@ actually wired into that harness's own config. As of v1.5.0:
158
158
  | Gemini CLI (legacy) | AfterAgent | `.gemini/settings.json` | stdout `{"decision":"deny","reason":...}`, exit 0 — the documented preferred path over exit code 2 |
159
159
  | Antigravity CLI (`agy`) | Stop | `.agents/hooks.json` | stdout `{"decision":"continue","reason":...}`, exit 0; `{}` allows |
160
160
 
161
+ This table covers Stop-type events only. The signals a host reads for events that
162
+ stop a tool call or a prompt (PreToolUse, UserPromptSubmit, BeforeTool) are in the
163
+ "What each host reads as 'blocked'" table of [mock-boundary](mock-boundary.md), the
164
+ one place they are written down, together with the rule that a blocking hook must be
165
+ tested by running it as the host does. They are not repeated here.
166
+
161
167
  Wired is not running on Codex. Codex skips a project hook until the project
162
168
  is trusted **and** that exact hook definition has been trusted through `/hooks`
163
169
  in an interactive Codex session; trust is recorded against the definition's
@@ -2,10 +2,20 @@
2
2
  /**
3
3
  * UDS Hook: Dangerous Command Detection
4
4
  *
5
- * Detects potentially destructive shell commands and blocks execution.
6
- * Exit code: 0 = safe, 1 = dangerous
5
+ * Detects destructive shell commands and blocks the tool call.
7
6
  *
8
- * Usage: echo "rm -rf /" | node check-dangerous-cmd.mjs
7
+ * Exit code: 0 = allow, 2 = dangerous (blocks the tool call).
8
+ * Claude Code blocks a PreToolUse call ONLY on exit 2; any other non-zero code
9
+ * is a non-blocking hook error and the command still runs.
10
+ *
11
+ * Input, in order of preference:
12
+ * 1. Claude Code PreToolUse payload on stdin:
13
+ * {"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"..."}}
14
+ * Only `tool_input.command` is inspected, never the other fields.
15
+ * 2. A raw command line on stdin when stdin is not a JSON object.
16
+ * 3. A command line as argv[2].
17
+ *
18
+ * Usage: echo '{"tool_input":{"command":"rm -rf /"}}' | node check-dangerous-cmd.mjs
9
19
  * or: node check-dangerous-cmd.mjs "rm -rf /"
10
20
  *
11
21
  * Performance target: < 500ms
@@ -13,48 +23,173 @@
13
23
  * @see docs/specs/SPEC-HOOKS-001-core-standard-hooks.md (REQ-2)
14
24
  */
15
25
 
16
- const DANGEROUS_PATTERNS = [
17
- /rm\s+-rf\s+\//,
18
- /mkfs\./,
19
- /dd\s+if=.*of=\/dev\//,
20
- /format\s+[a-zA-Z]:/,
21
- />\s*\/dev\/sda/,
22
- /chmod\s+-R\s+777\s+\//,
23
- /:()\{\s*:\|:&\s*\};:/, // fork bomb
26
+ const BLOCK_EXIT_CODE = 2;
27
+
28
+ // Where `rm -r` is never what the user meant: the filesystem root or the home directory.
29
+ // `/`, `//`, `/*`, `~`, `~/`, `~/*`, `$HOME`, `${HOME}`, `$HOME/`, `$HOME/*`. Not `/tmp/x`, not `~/proj`.
30
+ const ROOT_OR_HOME = /^(?:\/+\*?|(?:~|\$HOME|\$\{HOME\})(?:\/+\*?)?)$/;
31
+
32
+ // Words after which the real command follows (`sudo -u root rm ...`, `bash -c "rm ..."`, `then rm ...`).
33
+ const WRAPPERS = new Set([
34
+ 'sudo', 'doas', 'env', 'command', 'builtin', 'exec', 'nohup', 'time', 'nice', 'ionice', 'timeout',
35
+ 'bash', 'sh', 'zsh', 'dash', 'ksh', 'eval',
36
+ 'then', 'do', 'else', 'elif', 'if', 'while', 'until', '!', '{',
37
+ ]);
38
+
39
+ const baseName = (word) => word.slice(word.lastIndexOf('/') + 1);
40
+ const unquote = (word) => word.replace(/^["'`]+|["'`]+$/g, '');
41
+
42
+ /** Split a command line into simple commands, each a list of unquoted words. */
43
+ function simpleCommands(cmd) {
44
+ return cmd
45
+ .split(/[;&|\n()`]+/)
46
+ .map((segment) => segment.split(/\s+/).map(unquote).filter(Boolean))
47
+ .filter((words) => words.length > 0);
48
+ }
49
+
50
+ /**
51
+ * Index of the real command word in a simple command, or -1.
52
+ * The command is the first word, or the first word after a run of wrappers.
53
+ * `echo rm -rf /` and `git commit -m "rm -rf /"` have no `rm` command, so they never reach here.
54
+ */
55
+ function commandIndex(words, name) {
56
+ let i = 0;
57
+ while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++; // VAR=value prefix
58
+ if (i >= words.length) return -1;
59
+ if (matches(words[i], name)) return i;
60
+ if (!WRAPPERS.has(words[i])) return -1;
61
+ for (let j = i + 1; j < words.length; j++) {
62
+ if (matches(words[j], name)) return j;
63
+ }
64
+ return -1;
65
+ }
66
+
67
+ const matches = (word, name) => (typeof name === 'string' ? baseName(word) === name : name.test(baseName(word)));
68
+
69
+ function partition(args) {
70
+ const flags = [];
71
+ const operands = [];
72
+ let optionsEnded = false;
73
+ for (const arg of args) {
74
+ if (!optionsEnded && arg === '--') optionsEnded = true;
75
+ else if (!optionsEnded && arg.startsWith('-') && arg.length > 1) flags.push(arg);
76
+ else operands.push(arg);
77
+ }
78
+ return { flags, operands };
79
+ }
80
+
81
+ const isRecursive = (flags) =>
82
+ flags.some((f) => f === '--recursive' || (!f.startsWith('--') && /[rR]/.test(f)));
83
+
84
+ const RULES = [
85
+ {
86
+ name: 'rm-recursive-root-or-home',
87
+ test: (words) => {
88
+ const at = commandIndex(words, 'rm');
89
+ if (at < 0) return false;
90
+ const { flags, operands } = partition(words.slice(at + 1));
91
+ return isRecursive(flags) && operands.some((t) => ROOT_OR_HOME.test(t));
92
+ },
93
+ },
94
+ {
95
+ name: 'mkfs',
96
+ test: (words) => commandIndex(words, /^mkfs(?:\..+)?$/) >= 0,
97
+ },
98
+ {
99
+ name: 'dd-to-device',
100
+ test: (words) => {
101
+ const at = commandIndex(words, 'dd');
102
+ if (at < 0) return false;
103
+ return words.slice(at + 1).some((w) => /^of=\/dev\//.test(w) && !/^of=\/dev\/(?:null|zero|stdout|stderr|tty|fd\/)/.test(w));
104
+ },
105
+ },
106
+ {
107
+ name: 'format-drive',
108
+ test: (words) => {
109
+ const at = commandIndex(words, /^format(?:\.com|\.exe)?$/i);
110
+ return at >= 0 && words.slice(at + 1).some((w) => /^[a-zA-Z]:/.test(w));
111
+ },
112
+ },
113
+ {
114
+ name: 'chmod-recursive-777-root',
115
+ test: (words) => {
116
+ const at = commandIndex(words, 'chmod');
117
+ if (at < 0) return false;
118
+ const { flags, operands } = partition(words.slice(at + 1));
119
+ const recursive = flags.some((f) => f === '--recursive' || (!f.startsWith('--') && /R/.test(f)));
120
+ const wideOpen = operands.some((o) => /^(?:0?777|[ugoa]*\+rwx)$/.test(o));
121
+ return recursive && wideOpen && operands.some((t) => ROOT_OR_HOME.test(t));
122
+ },
123
+ },
124
+ ];
125
+
126
+ // Matched on the whole command line, not per word: they are syntax, not a command word.
127
+ const WHOLE_LINE_RULES = [
128
+ { name: 'redirect-to-disk', pattern: />\s*\/dev\/(?:sd[a-z]|hd[a-z]|vd[a-z]|xvd[a-z]|nvme\d+n\d+|r?disk\d+)/ },
129
+ { name: 'fork-bomb', pattern: /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/ },
24
130
  ];
25
131
 
132
+ /**
133
+ * Name of the first dangerous rule the command trips, or null.
134
+ * @param {string} cmd - The shell command to check
135
+ * @returns {string|null}
136
+ */
137
+ export function findDangerousRule(cmd) {
138
+ if (!cmd || typeof cmd !== 'string') return null;
139
+ for (const rule of WHOLE_LINE_RULES) {
140
+ if (rule.pattern.test(cmd)) return rule.name;
141
+ }
142
+ for (const words of simpleCommands(cmd)) {
143
+ for (const rule of RULES) {
144
+ if (rule.test(words)) return rule.name;
145
+ }
146
+ }
147
+ return null;
148
+ }
149
+
26
150
  /**
27
151
  * Check if a command matches dangerous patterns.
28
152
  * @param {string} cmd - The shell command to check
29
153
  * @returns {boolean} true if dangerous
30
154
  */
31
155
  export function isDangerousCommand(cmd) {
32
- if (!cmd || typeof cmd !== 'string') return false;
33
- return DANGEROUS_PATTERNS.some((p) => p.test(cmd));
156
+ return findDangerousRule(cmd) !== null;
157
+ }
158
+
159
+ /**
160
+ * The command to check, from stdin text. A Claude Code payload yields only
161
+ * `tool_input.command` (null when it has none); anything else is a raw command line.
162
+ * @param {string} raw
163
+ * @returns {string|null}
164
+ */
165
+ export function commandFromInput(raw) {
166
+ let payload;
167
+ try { payload = JSON.parse(raw); } catch { return raw; }
168
+ if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return raw;
169
+ const command = payload.tool_input?.command;
170
+ return typeof command === 'string' ? command : null;
171
+ }
172
+
173
+ function verdict(cmd) {
174
+ const rule = findDangerousRule(cmd);
175
+ if (rule === null) process.exit(0);
176
+ console.error(`Blocked by UDS security standard (rule: ${rule}): ${cmd}`);
177
+ process.exit(BLOCK_EXIT_CODE);
34
178
  }
35
179
 
36
180
  // CLI mode
37
181
  if (process.argv[1] && process.argv[1].endsWith('check-dangerous-cmd.mjs')) {
38
182
  const input = process.argv[2];
39
183
  if (input) {
40
- if (isDangerousCommand(input)) {
41
- console.error(`⚠️ Dangerous command detected: "${input}"`);
42
- process.exit(1);
43
- } else {
44
- process.exit(0);
45
- }
184
+ verdict(input);
46
185
  } else {
47
186
  let data = '';
48
187
  process.stdin.setEncoding('utf-8');
49
188
  process.stdin.on('data', (chunk) => { data += chunk; });
50
189
  process.stdin.on('end', () => {
51
- const cmd = data.trim();
52
- if (isDangerousCommand(cmd)) {
53
- console.error(`⚠️ Dangerous command detected: "${cmd}"`);
54
- process.exit(1);
55
- } else {
56
- process.exit(0);
57
- }
190
+ const raw = data.trim();
191
+ if (!raw) process.exit(0);
192
+ verdict(commandFromInput(raw));
58
193
  });
59
194
  }
60
195
  }
@@ -4,7 +4,19 @@
4
4
  *
5
5
  * Checks code for unstructured logging calls (console.log, console.warn, etc.)
6
6
  * and suggests using structured logging instead.
7
- * Exit code: 0 = pass, 1 = unstructured logging found
7
+ * Exit code: 0 = pass, 2 = unstructured logging found
8
+ *
9
+ * Why 2 and not 1: Claude Code shows a PostToolUse hook's stderr to the model only on
10
+ * exit 2. Any other non-zero code is a non-blocking hook error that the model never
11
+ * sees, so the suggestion would reach nobody. (The Write has already happened, so
12
+ * exit 2 here feeds the message back; it cannot undo anything.)
13
+ *
14
+ * Input, in order of preference:
15
+ * 1. Claude Code PostToolUse payload on stdin: only the written text
16
+ * (`tool_input.content`, or `tool_input.new_string` for an Edit) is checked,
17
+ * never the other fields such as file_path.
18
+ * 2. Raw code on stdin when stdin is not a JSON object.
19
+ * 3. Code as argv[2].
8
20
  *
9
21
  * Usage: echo 'console.log("debug")' | node check-logging-standard.mjs
10
22
  * or: node check-logging-standard.mjs 'console.log("debug")'
@@ -32,13 +44,29 @@ export function hasUnstructuredLogging(code) {
32
44
  return UNSTRUCTURED_PATTERNS.some((p) => p.test(code));
33
45
  }
34
46
 
47
+ /**
48
+ * The code to check, from stdin text. A Claude Code payload yields only the written
49
+ * text (null when it carries none); anything else is raw code.
50
+ * @param {string} raw
51
+ * @returns {string|null}
52
+ */
53
+ export function codeFromInput(raw) {
54
+ let payload;
55
+ try { payload = JSON.parse(raw); } catch { return raw; }
56
+ if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return raw;
57
+ const text = payload.tool_input?.content ?? payload.tool_input?.new_string;
58
+ return typeof text === 'string' ? text : null;
59
+ }
60
+
61
+ const FEEDBACK_EXIT_CODE = 2;
62
+
35
63
  // CLI mode
36
64
  if (process.argv[1] && process.argv[1].endsWith('check-logging-standard.mjs')) {
37
65
  const input = process.argv[2];
38
66
  if (input) {
39
67
  if (hasUnstructuredLogging(input)) {
40
- console.error('⚠️ Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
41
- process.exit(1);
68
+ console.error('Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
69
+ process.exit(FEEDBACK_EXIT_CODE);
42
70
  } else {
43
71
  process.exit(0);
44
72
  }
@@ -47,10 +75,11 @@ if (process.argv[1] && process.argv[1].endsWith('check-logging-standard.mjs')) {
47
75
  process.stdin.setEncoding('utf-8');
48
76
  process.stdin.on('data', (chunk) => { data += chunk; });
49
77
  process.stdin.on('end', () => {
50
- const code = data.trim();
78
+ const raw = data.trim();
79
+ const code = raw ? codeFromInput(raw) : null;
51
80
  if (hasUnstructuredLogging(code)) {
52
- console.error('⚠️ Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
53
- process.exit(1);
81
+ console.error('Unstructured logging detected. Use structured logging (e.g., JSON logger) instead.');
82
+ process.exit(FEEDBACK_EXIT_CODE);
54
83
  } else {
55
84
  process.exit(0);
56
85
  }