Skip to content

Commit 226de08

Browse files
committed
W2182: refuse a Stride API call whose response reaches neither tier
This plugin resolves a response FILE-FIRST, so the question is not whether the body stays on stdout but whether it reaches either channel the resolver reads. A preToolUse guard now refuses the shapes that reach neither, while permitting --output to the canonical response file -- one of the two delivery shapes this repository's own skills document. Refusing that would have contradicted our own instructions and stopped real work. Also adds a held-claim condition to the Stop gate, reading the env cache this plugin already writes, mutually exclusive with the unfollowed- completion condition and still costing at most one API call; and makes an absent completion body announce instead of returning in silence. The PowerShell twin carries all three with byte-identical messages, since stride-hook.sh execs it before stdin is read on native Windows. Efficacy is UNVERIFIED on this runtime: github/copilot-cli#3874 reports preToolUse denial not working at all. Both documented channels are emitted and no prose claims the guard is known to block. Review found four under-refusals and two over-refusals across two rounds -- shell wrappers, curl after if/while, a closed transformer denylist, tee -a onto the canonical file, and two refusals that contradicted the guard's own thesis. Each is recorded in the CHANGELOG with why it slipped through. 806 assertions pass; the fleet canon check stays clean. Claude-Session: https://claude.ai/code/session_01SqtvH3vrbrqRovwP6P1kaA
1 parent ee6f5be commit 226de08

10 files changed

Lines changed: 1884 additions & 27 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,191 @@
22

33
All notable changes to this project will be documented in this file.
44

5+
## [2.41.0] - 2026-09-10
6+
7+
### Added — the response has to reach a channel this plugin actually reads (W2182)
8+
9+
A `preToolUse` guard now refuses a Stride API call that sends its response
10+
somewhere neither tier of this plugin's resolver can see. The failure it closes
11+
is silent by construction: nothing records the loop state, the Stop gate cannot
12+
tell the task was completed, `changed_files` lands empty, and `after_goal`
13+
detection falls back to a fresh API call — with no error anywhere, so the first
14+
sign of trouble is work that quietly never left the board.
15+
16+
**The rule set here is deliberately NOT the sibling ports'.** This plugin is
17+
FILE-FIRST: `read_canonical_response` is Tier 1 and the tool stdout is Tier 2.
18+
So `--output "$CLAUDE_PROJECT_DIR/.stride/.last-api-response.json"` does not hide
19+
anything from us — it is the second of the two delivery shapes this repository
20+
documents, named as such in `loop_state_payload_ok`'s own comment and
21+
recommended by both the claiming and completing skills. Refusing it outright
22+
would have satisfied the letter of the task and contradicted three of our own
23+
comments plus two skill files, refusing the very fallback they instruct the
24+
agent to use. The criterion is read on its operative words — *hides the
25+
response* — and the exemption is narrow: the target must be the canonical file,
26+
spelled the way this repository actually documents it.
27+
28+
Refused: `-o`/`-oX`/`-sSo`/`--output`/`--output=` to any other target including
29+
`/dev/null`; `-O`/`--remote-name`, which names its file after the URL and so can
30+
never be the canonical one; **any** pipe whose next stage is not `tee`;
31+
`>`/`1>`/`>|`/`&>`/`>&2` to any other target; and
32+
`>>`/`&>`/`&>>` **onto** the canonical file, because appending a second document
33+
or merging a progress line makes the one JSON value we parse unparsable — the
34+
response is lost just as surely. An unresolvable target (`-o "$OUT"`) is refused
35+
too: a refusal is recoverable, a false permit is silent.
36+
37+
Permitted, with cases pinning each: `tee` to any target, every stderr-only
38+
redirect (`2>`, `2>>`, `2>&1`), `-o`/`--output`/`>` to the canonical file in any
39+
documented spelling, a bare call with no capture, and a `>` or `-o` sitting
40+
inside a quoted JSON payload.
41+
42+
The pipe rule is an **allowlist**, which it was not in the first draft. A
43+
nine-name denylist carried over from the sibling port silently permitted
44+
`| python3 -m json.tool` and `| xargs echo` — consumers nobody had thought to
45+
name, taking the body away exactly as `jq` does. The guard's own question is
46+
whether the response reaches a channel the resolver reads, and only `tee`
47+
answers yes.
48+
49+
Two corollaries earn their own permits, both of them refusals the first draft got
50+
wrong against its own thesis. A `tee` whose target **is** the canonical file
51+
fills Tier 1, so a transformer after *that* is safe — `curl … | tee <canonical> |
52+
jq .` combines two shapes the skills endorse. So is a redirect after such a tee:
53+
`curl … | tee <canonical> >/dev/null` keeps the capture while keeping a multi-KB
54+
body out of the transcript, and the body has already arrived.
55+
56+
**But append mode is not a capture,** and granting that permit without checking
57+
for it opened a false permit in the same breath: `tee -a <canonical>` adds a
58+
second JSON document after the first, and Tier 1 is parsed as one value, so the
59+
file becomes unparsable and the resolver falls through — the response is lost on
60+
exactly the reasoning the `append` redirect rule already carried. `tee -a` and
61+
`tee --append` onto the canonical file are refused as `append`.
62+
63+
### Fixed in review — ordinary shell shapes defeated the guard entirely
64+
65+
Worth recording in full, because every fixture written beforehand was an
66+
unwrapped `curl`, and that is exactly how these reached review green. All were
67+
**permitted** on both halves:
68+
69+
* `RESP=$(curl … -o /tmp/x)` and `` RESP=`curl … -o x` `` — a command
70+
substitution fuses the assignment and the command into one word;
71+
* `( curl … > out.json )` and `{ curl … -o out.json; }` — `(` and `{` stand in
72+
command position;
73+
* `if true; then curl … -o out.json; fi`, and then in a second round
74+
`if curl -sf … -o /tmp/x; then …; fi` with its `while` and `until` forms — the
75+
keyword itself was returned as the stage's command word.
76+
77+
In each case the command-word scan never found `curl`, so the **entire segment
78+
was skipped** — including the `-o` and redirect rules acceptance criterion 1
79+
names by hand. Fixed at the root rather than per-shape: the operator view now
80+
neutralises the shell's grouping characters `()` `` ` `` `{}` — replaced with
81+
spaces, so the substitution is length-preserving and the raw/blanked pairing
82+
offsets still hold — and the compound keywords `if then elif else fi while until
83+
do done !` are skipped alongside the existing leading-assignment and wrapper
84+
skips.
85+
86+
Two rounds were needed because the first fix closed the grouping-character subset
87+
and left the keyword-in-command-position subset live. The lesson is in the
88+
fixtures rather than the code: a guard tested only on the shape its author had in
89+
mind is tested on one shape.
90+
91+
### The Copilot deny contract, and one thing it is not
92+
93+
Deny keys are **top-level** — `{"permissionDecision":"deny","permissionDecisionReason":…}`
94+
— re-verified against the live hooks-configuration documentation on 2026-09-10.
95+
They are not nested under `hookSpecificOutput` (a sibling runtime's shape) and
96+
not the `decision`/`reason` pair this plugin's Stop gate emits (that pair is
97+
`agentStop`'s). Three shapes for three events.
98+
99+
`docs/HOOK_RESEARCH.md` said exit-code semantics were undocumented as a blocking
100+
signal. That is now out of date: the live docs state exit `2` **is** treated as
101+
a deny for `preToolUse`, which means the port's existing `exit 2` on the pre
102+
phase was right all along. The guard emits both channels for that reason.
103+
104+
**Efficacy is UNVERIFIED on this runtime, and the code says so.**
105+
`github/copilot-cli#3874` (opened 2026-06-20, still open, no maintainer
106+
response) reports `preToolUse` denial not working at all — exit 2,
107+
`permissionDecision: deny` and `behavior: deny` each ran the tool anyway. That
108+
report is against Copilot Chat Extension v1.0.65, possibly a different surface
109+
from the CLI. Emitting both channels is the hedge; no prose here or in the
110+
handler claims the guard is known to block.
111+
112+
### Added — the gate refuses a turn end while a claim is open
113+
114+
The gate previously blocked on one condition: a recorded completion never
115+
followed up. A turn ending **mid-task** produced no completion, so no loop
116+
state, so a silent permit — invisible to the only condition it had.
117+
118+
It now blocks on two, and they are the two sides of one file test, so they are
119+
mutually exclusive by construction and the gate still costs at most one API
120+
call. The new condition reads the **existing** `.stride-env-cache` — this plugin
121+
already writes `TASK_IDENTIFIER` and `TASK_STATUS` there, so nothing new was
122+
invented — and confirms with a single projected request that the task is still
123+
`in_progress`, uncompleted, and inside its claim window. The budget is keyed
124+
`held:<IDENT>` so neither condition can spend the other's.
125+
126+
Measured while building this: the server does **not** flip a task's status when
127+
its claim expires. One was observed still answering `in_progress` with
128+
`completed_by_id` null twelve minutes past `claim_expires_at`; reaping is lazy.
129+
That is why expiry is checked as its own condition rather than inferred from
130+
status — status alone would refuse a turn end over a task another agent is now
131+
free to take.
132+
133+
### Fixed — unrecordable states announce instead of returning in silence
134+
135+
An **absent** completion body was silent, and that was the wrong silence: unlike
136+
a 422, which arrives with a well-formed body that parses and correctly records
137+
nothing, an absent body means the response never reached the hook at all, so the
138+
completion may have landed while no loop state exists. Three further
139+
unrecordable states now announce as well (a rejected identifier, a non-boolean
140+
`needs_review`, a failed record assembly); the first two are defensive, since the
141+
payload check has already proven both. The one silence kept is the parseable
142+
non-success body — there, nothing failed.
143+
144+
### Both halves, and the vendored copy
145+
146+
The PowerShell twin carries the guard, the announcements and the held-claim
147+
condition, with refusal and block messages **byte-identical** to the bash half —
148+
`stride-hook.sh` execs it on native Windows before stdin is read, so a bash-only
149+
guard would have left every Windows session unguarded while looking complete.
150+
Two bugs worth recording. PowerShell's `-eq` is case-insensitive, so `-eq '-O'`
151+
also matched `-o` and refused the very `-o <canonical>` the bash half permits;
152+
every option comparison in that loop is now `-ceq`. And the gate's twin rendered
153+
`DateTime.UtcNow` without `InvariantCulture` — in a .NET custom format string `:`
154+
is the culture-sensitive time-separator placeholder, so on a host whose culture
155+
separates with `.` the timestamp became `2026-09-10T12.34.56Z`, and the ordinal
156+
comparison then sorted `.` below `:`, so an **expired** claim read as unexpired
157+
and the gate blocked a turn end it should have permitted. The sibling hook
158+
already passed `InvariantCulture` for the same format string. Three further
159+
announcements that existed only in bash were added to the twin as well.
160+
161+
### Tests
162+
163+
153 new assertions across two groups, plus a pwsh-gated cross-half parity block: the guard's refusals, its permits and their
164+
near-misses, the refusal document and its top-level keys, the token never
165+
reaching either stream, the multi-line and multi-byte payload cases, and the
166+
scan ceiling from both sides; plus the held-claim block, every condition that
167+
releases it, mutual exclusion, the one-API-call bound and the announcements.
168+
**806 assertions pass.** The suite is slower than before — each new case spawns
169+
the hook, which sources ~1,900 lines. One avoidable cost was removed after
170+
review measured it: a *permitted* `/complete` call falls through the guard into
171+
routing, which runs the section and the changed-files capture at roughly 44
172+
seconds a case. Permits whose assertion does not depend on the endpoint now use
173+
`/api/tasks/claim`, which routing maps to nothing on the pre phase and so exits
174+
straight after the guard; the `/complete` permits that do matter stay, so the real
175+
fall-through path is still exercised. The same conversion was needed a second time
176+
for the parity block, whose permits run **both** halves. Even so the suite takes
177+
about **25 minutes** on the development machine against roughly 47 seconds before
178+
this change — a real cost for a suite this port runs as a gate, recorded here
179+
rather than glossed. What remains is inherent to the approach: every case spawns a
180+
fresh hook process.
181+
182+
The scan ceiling is **65,536 bytes**, not the 4,000 a sibling port started with.
183+
A completion call carries `completion_summary` and `completion_notes`, so an
184+
ordinary one is several KB — and above the ceiling the payload's own prose is
185+
read as live shell syntax, which measured as refusing the operator's correct
186+
command. Above the ceiling the command is judged **whole** rather than
187+
segmented, because segmenting unblanked text shatters it on the `;` inside its
188+
own payload and drops a hiding flag into a fragment with no endpoint beside it.
189+
5190
## [2.40.0] - 2026-09-07
6191

7192
### Added — a back-reference beside every anchored rule (W2137)

‎docs/HOOK_RESEARCH.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,34 @@ Currently, only `"deny"` is processed (the docs note `"allow"` and `"ask"`
7878
are reserved but not yet honored). Exit-code semantics are not documented as
7979
an alternative blocking signal — the canonical path is the stdout JSON.
8080

81+
> **CORRECTION (2026-09-10, W2182).** The sentence immediately above is out of
82+
> date, and the record is corrected here rather than rewritten so the earlier
83+
> reasoning stays readable. Re-checked against the live hooks-configuration
84+
> documentation on that date:
85+
>
86+
> * **Exit `2` IS a deny** for `preToolUse` and `permissionRequest` —
87+
> "For `permissionRequest` and `preToolUse`, exit `2` is treated as a deny".
88+
> Any other non-zero also denies, with an error surfaced. So this port's own
89+
> `exit 2` on the pre phase was correct, not a Claude Code leftover.
90+
> * **Timeouts fail OPEN** on every event, `preToolUse` included.
91+
> * The deny keys are **top-level**, not nested under `hookSpecificOutput`.
92+
> * The event is accepted as `preToolUse` **or** `PreToolUse`.
93+
> * stdin carries `toolName`/`toolArgs`, or the VS Code-compatible
94+
> `tool_name`/`tool_input`.
95+
>
96+
> The W2182 guard therefore emits **both** channels — the stdout document and
97+
> `exit 2` — so a runtime honouring either one refuses.
98+
>
99+
> **Still unsettled, and it matters:** `github/copilot-cli#3874` (opened
100+
> 2026-06-20, still open, no maintainer response) reports `preToolUse` denial
101+
> not working *at all* — exit 2, `permissionDecision: deny` and
102+
> `behavior: deny` each ran the tool anyway, reported against Copilot Chat
103+
> Extension v1.0.65 (possibly a different surface from the CLI). Until a live
104+
> session settles it, treat the guard's efficacy as UNVERIFIED on this runtime,
105+
> exactly as the Stop gate's registration is treated above. The paragraph below
106+
> about the two contracts not being interchangeable remains correct in
107+
> substance: the *documents* differ per event even though exit 2 works on both.
108+
81109
This contrasts with Claude Code's PreToolUse contract, which the gate uses:
82110
**exit 2 + structured JSON on stdout** to block. The two contracts are not
83111
interchangeable; a port would have to switch from `exit 2` to writing the

0 commit comments

Comments
 (0)