|
2 | 2 |
|
3 | 3 | All notable changes to this project will be documented in this file. |
4 | 4 |
|
| 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 | + |
5 | 190 | ## [2.40.0] - 2026-09-07 |
6 | 191 |
|
7 | 192 | ### Added — a back-reference beside every anchored rule (W2137) |
|
0 commit comments