@sjawhar/pi-envoy 11.4.0 → 11.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -220,3 +220,245 @@ EOF
220
220
  Lifecycle and scope decisions between Legion roles go through `envoy_publish` to the owning
221
221
  architect's role topic; Dispatch is for durable questions to the human and the shared
222
222
  document, not for coordination between roles.
223
+
224
+ ## AskGate
225
+
226
+ AskGate reviews each Dispatch write of a session's main agent before the write posts. One model
227
+ call judges the write against the rules in `extensions/askgate/rules.md` and answers `allow` or
228
+ `revise`. A `revise` answer carries the reason and the fix. The gate reviews these calls:
229
+
230
+ - `dispatch ask`, `dispatch message`, `dispatch edit-ask`, `dispatch comment`, `dispatch doc-edit`
231
+ and `dispatch request-approval`
232
+ - `dispatch issue` with `--spec` or `--spec-file`
233
+ - `dispatch artifact` when it uploads a markdown document: inline text (`--content`,
234
+ `--content-file`), a `--path` file whose name ends in `.md` or `.markdown`, or a `--name` that
235
+ ends in `.md`
236
+
237
+ Every other Dispatch command is outside the gate, and its text posts unreviewed: among them
238
+ `dispatch issue-update --reason`, `dispatch resolve-ask --reason` and `dispatch suggest`.
239
+
240
+ The gate reads the arguments from the command's own `--dry-run`. An upload that reads its name
241
+ from a file (`--name-file`) is decided from the name the dry run prints. `--path-file` is refused:
242
+ its content names a file the gate does not read before Dispatch opens it. An upload whose name or
243
+ path holds an expansion (`"$NAME"`) is outside the form the gate reads. The gate reads each file
244
+ whose text the write posts, a `--<field>-file` operand and an upload's `--path`, in place, shows
245
+ those bytes to the model, and runs the call as written. The marker it mints binds the sha256 of
246
+ each file. Before the write posts, the CLI reads each file again and refuses one whose bytes
247
+ changed after the review, and an upload sends the bytes the CLI read for that check. An `--image`
248
+ file is not one of them: the model reads the path, not the picture. The file must be a regular
249
+ file. The gate refuses a missing file, a directory, a device and a FIFO before it reads them, and
250
+ a path that reaches a file descriptor of whichever process opens it (`/dev/stdin`, `/dev/fd/N`,
251
+ `/proc/self/fd/N`, `/proc/thread-self/fd/N`, `/proc/<n>/fd/N`, and any link to one): AskGate
252
+ would open it in Oh My Pi's process and the command in its shell. For text from standard input,
253
+ use `--<field>-file -` with a quoted here-document. For an upload, that is `--content-file -`:
254
+ the CLI reads `--path -` as a file named `-`. The gate cuts all arguments at 64 KiB as one JSON
255
+ block, so it reviews only part of a long document. It judges an upload against content failure
256
+ 10 alone: a plan or a report is long by nature. An upload of any other file is not reviewed. A
257
+ `task` subagent is not reviewed.
258
+
259
+ **A file a call of the same message writes.** Oh My Pi runs the gate for every call of a message
260
+ before any call of that message runs. So the gate reads a file before an earlier call of the same
261
+ message writes or edits it. A file that is not there yet is refused in `block` mode with the
262
+ advice to send the call again in a later message; in `warn` mode the call runs unreviewed, with
263
+ that advice as its note. A file that an earlier call changed is refused by the CLI in `block` mode
264
+ (`… AskGate reviews the calls of a message before any of them runs, so it did not review that
265
+ change. Send the call again in a later message.`); in `warn` mode it posts with a
266
+ `dispatch: warning:` line. Write or edit a file in one message, and send the write that posts it
267
+ in the next.
268
+
269
+ **The form the gate reads.** One `dispatch` call, alone in the bash call:
270
+
271
+ ```
272
+ [cd <literal path> && ] dispatch <subcommand> <literal words…> [2>&1] [<<'DELIM' … DELIM] [| head|tail [-n N]]
273
+ ```
274
+
275
+ - The program is `dispatch` by name, or a literal path that ends in it.
276
+ - Every word is literal. Outside quotes a word holds only letters, digits and `._/+@%:,=-`, so no
277
+ `$`, backtick, `~`, `*`, `?`, `[`, `{`, `}` or backslash. Single quotes make every character
278
+ literal. Inside double quotes there is no `$`, backtick or backslash. A quoted word may run over
279
+ several lines.
280
+ - A backslash at the end of a line continues the command, as bash reads it.
281
+ - One `cd <literal path> &&` may stand before it, and one `2>&1` after it.
282
+ - One here-document may feed it, with its delimiter in quotes (`<<'EOF'` or `<<"EOF"`), before or
283
+ after the `2>&1`. Its body is on the lines after the line that opens it.
284
+ - One trailing pipe stage may read its output: `head` or `tail`, alone or with `-n N`, `-nN` or
285
+ `-N`. The dry run leaves it out.
286
+ - Nothing else is in the call: no second command, no other pipe, no `;`, `&&`, `||` or `&`, no
287
+ assignment, no other redirect and no comment.
288
+
289
+ **Everything else runs, and the `dispatch` command enforces the review.** The gate reads no other
290
+ form and refuses none: a call outside the literal grammar runs as written. What holds it back is
291
+ the CLI. For each literal call it lets run, the gate mints a single-use marker; the CLI posts a
292
+ gated write only when it consumes one, so a write sent any other way is refused in `block` mode:
293
+
294
+ - **The record.** While the gate is bound, pi-envoy keeps one owner-only file for its process in
295
+ the `askgate/` directory of the CLI's state directory of each session id it binds
296
+ (`<state>/sessions/<id>/askgate/<pid>-<start>.json`, where `<state>` is `DISPATCH_STATE_DIR`,
297
+ else `$XDG_STATE_HOME/dispatch`, else `~/.local/state/dispatch`). It names the Oh My Pi process,
298
+ its Linux start time, and the process's owner-only marker store. Each process writes and removes
299
+ only its own file, so two processes that bind one session never drop each other. pi-envoy sets
300
+ `DISPATCH_STATE_DIR` in the session's environment when it is not set, so a command that changes
301
+ `HOME` or `XDG_STATE_HOME` still finds the record. A record of a session the process switched
302
+ away from stays until the process exits, since a shell or an eval kernel started before the
303
+ switch still acts as that session. A record whose process is gone, or whose pid another process
304
+ now holds, is inert, and the CLI's session pruning keeps a directory whose record is live. A
305
+ record pi-envoy cannot write is a notice in the session, at start or at a switch.
306
+ - **The marker.** The gate mints one file in the store for each literal call it lets run, created
307
+ owner-only and exclusively. It binds the exact argument vector the CLI receives and, behind a
308
+ review or a deliberate pass (a rebuttal, a breaker trip, a halt, another provider), the digest
309
+ of the arguments the dry run printed and the sha256 of each file the argv names, as the gate
310
+ read it. A call no verdict stands behind, and a `task` subagent's literal call, get a marker of
311
+ the argument vector alone. Nothing of it is in the command the agent sees. A marker goes when
312
+ its call ends, is refused or the session shuts down; a backgrounded call keeps its marker until
313
+ shutdown, and a marker older than two hours, longer than any tool's time limit, is refused and
314
+ removed. The process removes its store when it exits; the CLI's daily session pruning removes
315
+ the store of a process that is gone and that nothing changed for two hours.
316
+ - **The check.** After `--help`, `--dry-run` and the session and Dispatch settings, and before a
317
+ gated write posts, the CLI reads the session's record. With a live one it reads each file the
318
+ argv names once and consumes one matching marker by unlinking it: exactly one process wins, so a
319
+ marker posts one write and a replay finds none. In `block` mode a write with no matching marker
320
+ is refused (`dispatch <command> was not called: AskGate is on for this session, …`, which names
321
+ the form to send, or, for a file that changed after the review, says to send the call again in a
322
+ later message). In `warn` mode the CLI first records the write in the session's ledger, refuses
323
+ it when the ledger cannot take that line, and then posts it with a `dispatch: warning:` line.
324
+ Either way pi-envoy records an `advisor-gate` entry with outcome `unmarked`. A record that cannot
325
+ be read, or that names a store that is gone, is a refusal. A session no live record names needs
326
+ no marker: a terminal, CI, Claude Code, OpenCode, a pod without pi-envoy, a session with no
327
+ Dispatch and one with `askgate.enabled: false`.
328
+ - **The cause note.** When a `bash` call outside the literal form holds a `dispatch` word and a
329
+ gated subcommand, and its result holds the CLI's refusal (or warn-mode warning) of a write with
330
+ no marker, the gate appends an `AskGate note:` to that result. It names the first cause it found
331
+ in the call, with the call's own text (an expansion in a value, a double-quoted value over lines
332
+ with an expansion in it, a program that runs the write such as `xargs` or `timeout`, a pipe, a
333
+ second command, an assignment, a redirect), and the change that puts the write in the literal
334
+ form. The note is help only: the gate refuses nothing for it.
335
+
336
+ The gated writes are the same list for the gate and the CLI (`gatedWrite` in
337
+ `@legion/envoy-client/askgate-marker`): the six commands above, an `issue` with a spec and an
338
+ `artifact` that uploads a markdown document. `--help`, `--dry-run` and every other command need no
339
+ marker. So a pipe to a program other than one trailing `head` or `tail`, a loop, a variable,
340
+ `xargs`, an alias, a script, `python3 -c`, `node -e`, or a process an eval cell starts runs, and
341
+ its gated write is refused by the CLI in `block` mode with the form to send; a call that holds no
342
+ Dispatch write, such as a commit message or a search pattern that names one, runs and posts
343
+ nothing. A literal call whose last command gives no argument vector is refused in `block` mode. A
344
+ gate that did not load refuses each literal call at the hook, so those never reach the CLI; it
345
+ writes the record and mints nothing, so every gated write that does reach the CLI — one outside the
346
+ literal form, and a subagent's literal one — is refused where the session set `OMP_ASKGATE=block`,
347
+ and at the warn default posts with a warning and an `unmarked` entry.
348
+
349
+ **Where the gate binds.** AskGate binds only in a session that has Dispatch, judged at load from
350
+ the session's own envoy.json and the variables over it (`DISPATCH_URL` and the other Dispatch
351
+ variables), with a checkout's `.envoy/envoy.json` able to turn it on and never off: a checkout that
352
+ names its own server and token gives the session a Dispatch, and one that turns off the Dispatch of
353
+ its own directory leaves the gate bound, since a later command can still pass that with
354
+ `DISPATCH_URL`. A session or a pod with no Dispatch has no write to review, so it gets no gate, no
355
+ record and no refusal. The test runs once, at load: a session that turns Dispatch on afterwards has
356
+ no gate until it is started again.
357
+
358
+ **The switch.** In a session with Dispatch, AskGate runs unless the session's own envoy.json turns
359
+ it off. Write this top-level section beside `dispatch`:
360
+
361
+ ```json
362
+ { "askgate": { "enabled": false } }
363
+ ```
364
+
365
+ No section, or `enabled: true`, keeps it on. A checkout's `.envoy/envoy.json` cannot set it, and a
366
+ checkout's `dispatch.enabled: false` does not turn it off. A section that does not parse keeps
367
+ AskGate on, and the start notice names the file.
368
+
369
+ **The modes.** A model's revise verdict and the CLI's marker checks have separate defaults. A revise
370
+ verdict blocks by default: the write does not post. `OMP_ASKGATE=warn`, or a session whose latest
371
+ `experiments` entry turns its `askgate_block` arm off, lets the write post with the reason. The
372
+ CLI's checks warn by default: a gated write with no matching marker, a file changed after the
373
+ review, and a file missing when the gate ran each post with a warning and an `unmarked` or
374
+ `unreadable` entry that the report counts. They refuse only when the session chose block
375
+ explicitly: `OMP_ASKGATE=block`, or, with no such variable, an `experiments` entry whose arm is on.
376
+ AskGate ignores any other value of `OMP_ASKGATE`, `off` included, and the first review shows one
377
+ notice that names `askgate.enabled` as the switch. The gate writes the checks' mode into the
378
+ session's own record (not a process-wide file, so a process that binds two sessions keeps each
379
+ one's mode, and a switch never changes another session's) at each main-agent `bash` or `eval`
380
+ call, where the CLI reads it, and a record with no mode is warn. pi-envoy also writes
381
+ `OMP_ASKGATE=block` into the record at the bind, so a session that chose block that way stays at
382
+ block even when its gate does not load. A later bind of a session id that recorded block (a switch
383
+ back to it, or a branch or host move that keeps the id) keeps block, so its mode never goes back to
384
+ warn before the gate's next call. An `experiments` arm alone does not reach the record at the
385
+ bind: only the loaded gate reads the arm, so a session that chose block through the arm alone has
386
+ no mode on disk until the gate's first main-agent `bash` or `eval` call, and none at all when the
387
+ gate does not load — a write outside the literal form there posts with a warning. **An operator
388
+ who selects block through the arm should also set `OMP_ASKGATE=block` for a hard guarantee**,
389
+ which holds from the session's start and through a failed load. Two other refusals follow neither
390
+ mode: no model role, and a gate that did not load, which refuses each literal call it would review
391
+ in both modes, since neither can review anything.
392
+
393
+ **The model.** The gate asks the session's `askgate` model role (`modelRoles.askgate`). When that
394
+ role is not set, it asks the `default` role. A model that answers with an error passes the request
395
+ to the next model of that role's `retry.fallbackChains` chain, on the same provider. When neither
396
+ role resolves, the gate refuses the write in both modes and names the two roles. A session whose
397
+ main model is on another provider than the gate's model is not reviewed: its transcript stays on
398
+ that provider.
399
+
400
+ **When a write posts unreviewed.** Each of these lets the write out, records an `advisor-gate`
401
+ entry with its outcome, and hands the agent a note that says the write went out unreviewed and
402
+ why. The note reaches a headless session too:
403
+
404
+ | Outcome | What happened |
405
+ | --- | --- |
406
+ | `timeout` | the review did not answer within its deadline |
407
+ | `error` | the review failed: a model error, a handler exception, or a dry run that failed |
408
+ | `no-verdict` | the model answered with no verdict the gate could read |
409
+ | `halted` | three calls in a row reached no verdict, and the gate is paused for the session |
410
+ | `skipped` | the session's main model is on another provider than the gate's |
411
+ | `rebuttal` | the agent sent `--advisor-rebuttal <line>`, which is recorded and removed |
412
+ | `breaker` | a third attempt on one target after two revise verdicts |
413
+ | `unreadable` (warn mode) | a file the literal call names was missing or not a regular file when the gate ran |
414
+ | `abandoned` (warn mode) | the call or the run ended before the review answered |
415
+ | `shutdown` (warn mode) | the session shut down before the review answered |
416
+ | `unmarked` (warn mode) | the CLI found no marker for a gated write sent in another form |
417
+
418
+ Where the mode that applies is `block` (the verdict's for `abandoned` and `shutdown`, the checks'
419
+ for `unreadable` and `unmarked`), those outcomes refuse the call instead. Only
420
+ `askgate.enabled: false`, and a session with no Dispatch, are silent. Each outcome after a failure
421
+ runs the agent's own command as written: a gate that fails breaks no valid write.
422
+
423
+ **The time limit.** `OMP_ASKGATE_TIMEOUT_MS` sets the review's time limit. The default is 90 s. The
424
+ gate holds the limit 5 s under `extensionHandlers.toolCallTimeoutMs`, the host's limit for one
425
+ `tool_call` handler. That key is 30 s by default, so the limit is then 25 s. A review of a long
426
+ session often takes longer than 25 s, and a review that times out lets the write post. Three
427
+ timeouts in a row stop the gate for the rest of the session. Set the key to 120000 or more in the
428
+ session's settings, for example in `~/.omp/agent/config.yml` or an overlay in `PI_CONFIG_FILES`:
429
+
430
+ ```yaml
431
+ extensionHandlers:
432
+ toolCallTimeoutMs: 120000
433
+ ```
434
+
435
+ When the limit is under 30 s, the gate logs one warning at start that names the key, the host's
436
+ limit and the review's limit. It still reviews each write.
437
+
438
+ `OMP_ASKGATE_DUMP` names a file that gets each review's two prompts. Every gated call writes one
439
+ `advisor-gate` entry into the session's transcript, and `scripts/askgate-report.ts` reports over
440
+ those entries: what the gate sent back and what the reviews cost, a count for each outcome, and
441
+ every session that had a write the gate did not review, with its counts. The report counts a
442
+ write as **sent back** when the gate did not pass it as sent: every entry whose decision is
443
+ `revise` — a revise verdict, `no-model-role`, and in block mode `abandoned`, `shutdown` and
444
+ `unmarked` — and every `unreadable`, `unmarked` or `load-failed` entry, whatever its mode, counted
445
+ over every gated call, since some of them never reach a review; as a **refusal** when the write did
446
+ not post (one sent back in block mode, and `no-model-role` and `load-failed`, which refuse in warn
447
+ mode too); and as **unreviewed** when it posted with no review behind it, which is every `allow`
448
+ whose outcome is no verdict (the table above, a rebuttal, a breaker trip and warn mode's
449
+ `abandoned` and `shutdown` included).
450
+
451
+ **What AskGate is not.** AskGate reviews the writes of a cooperating agent, so that a write that
452
+ breaks its rules comes back with the reason before it posts. It is no sandbox. A process that
453
+ runs as the same user as the session defeats it: it can set `askgate.enabled` to false in its own
454
+ envoy.json, or point the session at another envoy.json with `OMP_PROFILE`, `PI_CODING_AGENT_DIR`,
455
+ `ENVOY_CONFIG_FILE`, `XDG_CONFIG_HOME` or `HOME` in the launching shell.
456
+
457
+ The CLI's check holds only for the CLI. It does not cover a direct HTTP request to Dispatch with
458
+ the session's token, an older or a different `dispatch` binary, or a same-user process that
459
+ removes the record or a marker file, sets `DISPATCH_STATE_DIR` or `DISPATCH_SESSION_ID` itself to
460
+ act as another state directory or session id, or otherwise goes around the CLI. claude-envoy has
461
+ no Dispatch write tool over MCP: Claude Code writes through the same CLI
462
+ under host `claude`, where AskGate keeps no record, so nothing there asks for a marker. Use the
463
+ gate for the writes of an agent that wants the review, and not as a boundary against a program
464
+ that wants around it.