@herbertgao/pi-extensions 2026.9.7 → 2026.9.9

package/node_modules/grok-mermaid/src/width.ts

@@ -0,0 +1,74 @@
+import { WIDTHS } from './width-data.ts'
+
+/**
+ * Display width, measured in grapheme clusters.
+ *
+ * A cluster is the unit both of measuring and of painting, so a box is always
+ * sized for exactly what gets drawn into it. Splitting those two — sizing by
+ * cluster but painting by code point — is what makes `👨‍👩‍👧` overflow its
+ * border in the Rust original.
+ *
+ * Clustering comes from `Intl.Segmenter` (UAX #29), which already handles ZWJ
+ * sequences, skin-tone modifiers, variation selectors, keycaps, flags and
+ * Hangul. Per-code-point widths are generated from the `unicode-width` crate.
+ */
+
+const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' })
+
+const VS16 = 0xfe0f
+const isRegionalIndicator = (cp: number): boolean => cp >= 0x1f1e6 && cp <= 0x1f1ff
+
+/** Width of one code point; the table covers the whole code point space. */
+function codePointWidth(cp: number): number {
+  let lo = 0
+  let hi = WIDTHS.length - 1
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1
+    const run = WIDTHS[mid]
+    if (cp < run[0]) hi = mid - 1
+    else if (cp > run[1]) lo = mid + 1
+    else return run[2]
+  }
+  return 1
+}
+
+/**
+ * Columns occupied by one grapheme cluster.
+ *
+ * The widest code point wins, so a base plus its combining marks measures as
+ * the base. Two adjustments: a variation selector requesting emoji
+ * presentation forces two columns, as does a regional indicator pair (a flag).
+ *
+ * Zero is a real answer — a soft hyphen or zero-width space occupies nothing,
+ * and callers skip painting such a cluster rather than reserving a cell.
+ */
+export function clusterWidth(cluster: string): number {
+  let w = 0
+  let vs16 = false
+  let regional = 0
+  for (const ch of cluster) {
+    const cp = ch.codePointAt(0) as number
+    if (cp === VS16) vs16 = true
+    if (isRegionalIndicator(cp)) regional++
+    const cw = codePointWidth(cp)
+    if (cw > w) w = cw
+  }
+  return vs16 || regional >= 2 ? 2 : w
+}
+
+/** Iterate grapheme clusters, so no loop can split one. */
+export function* clusters(s: string): Generator<string> {
+  for (const { segment } of segmenter.segment(s)) yield segment
+}
+
+/** Iterate clusters paired with their display width. */
+export function* measured(s: string): Generator<[string, number]> {
+  for (const { segment } of segmenter.segment(s)) yield [segment, clusterWidth(segment)]
+}
+
+/** Display columns of a string. */
+export function stringWidth(s: string): number {
+  let w = 0
+  for (const { segment } of segmenter.segment(s)) w += clusterWidth(segment)
+  return w
+}

package/node_modules/pi-jev-auto-mode/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+## 0.4.1 - 2026-09-18
+
+- **An unclear answer passes by default.** `uncertain` defaulted to `deny`, which meant a
+  judgment the model was unsure about stopped the call. That is the interruption an auto mode
+  exists to remove; clear rejections still block. `uncertain deny` and `uncertain ask` remain
+  available for anyone who wants the stricter behaviour.
+- **Without a key the gate says so and stops**, instead of inventing a verdict and blocking with
+  an unexplained reason. The message names the fix: `/jev-auto-mode login`, or
+  `/jev-auto-mode off`. The footer reads `🛡 jev no key` in that state, and the session start
+  warns once.
+- **A chain of read-only commands is read-only.** `cd src && ls -la && git log -3` was judged as
+  a whole because the allowlist rejected any command containing shell control syntax, so agents
+  paid a judgment round trip for their most common line. Each segment is now checked on its own,
+  and `cd` is allowed. A chain containing anything else (`curl … | sh`) is still judged.
+- **The docs match the no-key behaviour.** The README and a comment still described a fallback
+  that confirms in a UI, which the gate no longer does: without a key it stops the calls it cannot
+  judge and says it is not connected to Jev.
+
+
+## 0.4.0
+
+**The semantic layer now sees everything the deterministic layer cannot vouch for, and it does
+not stop ordinary work.**
+
+- `gateScope` (default `all`) replaces the denylist as the way calls are selected. A dangerous
+  pattern can only recognise a shape someone wrote down first: a request that uploads a file
+  (`curl -d @...`) once ran with no judgment at all because no pattern described it, and adding
+  patterns to a denylist is a race that never ends. Under `all`, the deterministic layer names
+  what it can vouch for and everything else is judged. `matched` keeps the old behaviour.
+  `/jev-auto-mode scope all|matched` switches between them.
+- **The intent question is asked only about commands the deterministic layer recognised as a
+  dangerous shape, and only a clear "this was not requested" blocks.** Asked about every command,
+  it blocked ordinary work the request never mentioned — an unrequested `mv`, `cp`, `tar`,
+  `chmod +x`, or `node -e`. An auto mode that stops for those has no reason to exist. Measured
+  after the change: those run, while an unrequested `git reset --hard`, `npm publish`, `rm -rf`,
+  or `sudo` still blocks (p = 0.04–0.11).
+- Read-only inspection is now a real fast path, because under `all` it carries the load the
+  denylist used to carry: `cat`, `head`, `tail`, `wc`, `find`, `jq`, `diff`, `sort`, `stat`,
+  version probes, and read-only git subcommands. Destructive variants (`find -delete`,
+  `git tag -d`, `push --force`) still match dangerous patterns and are judged.
+- The user's `safeCommands` outranks a dangerous-pattern match; the built-in read-only list does
+  not, so `grep secret ~/.ssh/id_ed25519` is judged even though `grep` is read-only.
+- `Escalated:` replaces `Matched:` in the confirmation dialog, because under `all` the reasons
+  are not all pattern matches.
+
+## 0.3.0
+
+The 0.2.0 default resolved the middle band as a block, but two conditions were still
+`required`, which made the gate strict for structurally wrong reasons rather than measured
+ones. Corrected:
+
+- `intent_coverage` 0.80 → **0.60**. Measured answers are 0.77–0.98 when the user asked and
+  0.06–0.15 when they did not, so 0.80 sat on top of the "asked" cluster instead of inside the
+  empty band between the two. The middle band is now (0.40, 0.60).
+- `policy_compliance` required → **hazard**. It measured 0.66–0.85 on calls where nothing was
+  wrong, so as a requirement it blocked every gated call the moment a policy was configured.
+  Now only a clear violation stops a call.
+- `path_not_protected` required → **hazard**. An unclear answer no longer blocks on its own; the
+  user's request decides. A target the model clearly identifies as a credential store still
+  blocks (`.env` measured p = 0.02, `~/.ssh` p = 0.03).
+- New `no_fetched_code_execution`, required, asked only for commands the deterministic layer
+  already recognised as downloaded-script execution. `curl | bash` stays blocked (p = 0.02)
+  without making every other call strict.
+- `.env.example`, `.env.sample`, `.env.template`, and `.env.dist` are no longer treated as
+  credential stores: templates belong in the repository.
+- The intent window widened from 8 messages / 4000 characters to 12 / 6000, so an ongoing task
+  does not lose the request that justifies it and look unrequested as a result.
+
+## 0.2.0
+
+- The confirmation dialog is bounded: it showed the whole command, and since Pi's dialogs do not
+  clip their content a long command produced a dialog taller than the terminal. It now shows a
+  short preview and says what was hidden.
+- **The middle band no longer asks the user by default.** An auto mode that stops to ask has
+  handed the decision back to a human, and the agent can always ask in conversation if it needs
+  guidance. A judgment that is neither satisfied nor rejected now blocks, so the gate never
+  takes over the screen.
+- `uncertain` setting and `/jev-auto-mode uncertain deny|ask|allow` control it. `deny` is the
+  default; `ask` restores the confirmation dialog; `allow` trusts the band.
+- `/jev-auto-mode threshold edit` picks a rule and prompts for a value, showing each rule's
+  current threshold next to the last probability the model returned for it.
+
+
+## 0.1.1
+
+- Correct the product name. It is **Jev** — TypeSafe's System One model, spelled with a
+  capital J and lowercase `ev`, as in their announcement, FAQ, and the model id
+  `typesafe-ai/jev` — not "JEV". Fixed in the README, docs, source comments, and the package
+  description. The `0.1.0` metadata cannot be edited, so this release exists to carry the
+  corrected name. No behavioral change.
+
+## 0.1.0
+
+Initial release.
+
+- Two-layer gate: a deterministic policy envelope (hard-deny, allow/deny patterns,
+  dangerous-command detection, protected paths) and a Jev semantic layer that only sees
+  what the first layer escalated.
+- Conditions carry a `mode` (`required` / `hazard`) and a `severity` (`hazard` / `soft`),
+  calibrated against measured probabilities from the real API (`docs/calibration.md`).
+- Fail-closed everywhere: no key, timeout, malformed response, cancellation, missing
+  answer, or oversized request all resolve to a block rather than an approval.
+- `/jev-auto-mode` command surface: `on|off`, `login|logout`, `policy`, `threshold`.
+- Decision records via `pi.appendEntry`, kept out of the LLM context, expandable to a
+  per-condition tuning sheet.
+- Network uploads of local data and reads of credential material are gated: a `curl -d @file`
+  that matched nothing ran with no judgment before this.
+- `pi install` from npm or git; tagged `pi-package` for the package gallery.

package/node_modules/pi-jev-auto-mode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jomatsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/pi-jev-auto-mode/README.md

@@ -0,0 +1,285 @@
+# pi-jev-auto-mode
+
+Auto mode for the [Pi coding agent](https://github.com/earendil-works/pi-mono) backed by
+**Jev** (TypeSafe System One, a decision-only model). Pi has no built-in permission system,
+so a gate either exists as an extension or it does not exist at all. This one judges
+`bash`, `write`, and `edit` tool calls semantically and **fails closed** whenever a decision
+cannot be made.
+
+> **Status: milestones 1–3 are complete.** The deterministic envelope, the Jev engine,
+> real-API calibration, settings, policy notes, per-rule threshold tuning, and decision
+> records are implemented and tested (171 tests, no network). See [`docs/design.md`](./docs/design.md) for
+> the roadmap and [`docs/calibration.md`](./docs/calibration.md) for the measured
+> probabilities behind every threshold.
+
+## What it does
+
+The gate has two layers, in this order:
+
+1. **Deterministic policy** — hard-deny commands, your allow/deny patterns, dangerous-command
+   detection, protected paths. Hard-deny is never handed to the semantic layer.
+2. **Semantic judgment (Jev)** — only the calls the first layer escalated.
+
+```
+hard-deny               → block (never reaches Jev)
+your deny pattern       → block
+your allow pattern      → allow (recorded)
+your safeCommands       → run, no record
+dangerous pattern match → Jev (even when the command looks read-only)
+read-only builtin       → run, no record
+in-project write/edit   → run, no record
+everything else         → Jev: allow · block · block-if-undecidable
+```
+
+**`gateScope` decides how far the semantic layer reaches, and the default is `all`.** A denylist
+can only recognise the shapes someone wrote a pattern for first: a command that uploaded a file
+(`curl -d @~/.ssh/id_ed25519 ...`) matched nothing and ran with no judgment at all. Under `all`
+the deterministic layer names what it can vouch for — read-only inspection, your declared safe
+commands, a write inside the project to an unprotected path — and everything else is judged.
+`matched` restores the old pattern-only behaviour. `/jev-auto-mode scope all|matched` changes it.
+
+The trade is latency: a judged call costs roughly half a second (measured 193–642 ms across
+eleven ordinary commands), while a fast-path call costs nothing. Read-only inspection is
+therefore a real allowlist rather than a convenience.
+
+An auto mode that stops for ordinary work has no reason to exist, so **the intent question is
+asked only about commands the deterministic layer recognised as a dangerous shape, and only a
+clear "this was not requested" blocks**. Measured: an unrequested `mv`, `cp`, `tar`, `chmod +x`,
+or `node -e` is judged and allowed, while an unrequested `git reset --hard`, `npm publish`,
+`rm -rf`, or `sudo` is blocked.
+
+`rm -rf build` inside the repository is recognized as a scoped local deletion. A write to
+`.env`, `.git/`, `~/.ssh`, `.pi/`, `.github/workflows/`, or `AGENTS.md` is escalated even when
+the path is inside the working directory.
+
+### How Jev decides
+
+Conditions are phrased so the safe state is "yes", and each one is classified by
+`mode` and `severity`:
+
+| | meaning |
+|---|---|
+| `mode: required` | must be satisfied; the middle band escalates to a confirmation |
+| `mode: hazard` | only a clear negative matters; the middle band is ignored |
+| `severity: hazard` | a clear rejection always blocks |
+| `severity: soft` | a clear rejection is cleared when the user's own request covers the call |
+
+So `intent_coverage` ("is this what the user asked for?") is the permission question, and
+questions like "is a secret being sent to a network endpoint" are hazard detectors that only
+block when they are sure. Posting a private key is never cleared by intent; force-pushing a
+feature branch the user asked for is.
+
+**Nothing is delegated to the user by default.** The middle band — where Jev is neither
+satisfied nor rejecting — resolves to a block, so Jev's probability is the whole answer and the
+gate never takes over the screen. `/jev-auto-mode uncertain ask` restores the confirmation
+dialog if you want it; `allow` trusts the band. Everything else that cannot be decided — no
+engine, timeout, malformed response, cancellation — also blocks.
+
+## Install
+
+```sh
+pi install npm:pi-jev-auto-mode
+```
+
+Or straight from the repository, which needs no npm account:
+
+```sh
+pi install git:github.com/jomatsu/pi-jev-auto-mode
+```
+
+Try it without installing:
+
+```sh
+pi -e npm:pi-jev-auto-mode
+```
+
+Packages are discovered in the [package gallery](https://pi.dev/packages) through the
+`pi-package` keyword.
+
+## Usage
+
+```
+/jev-auto-mode            show status (settings + where the API key comes from)
+/jev-auto-mode on|off     toggle auto mode
+/jev-auto-mode login      store a TypeSafe API key (verified, then saved 0600)
+/jev-auto-mode logout     remove the stored key
+/jev-auto-mode policy     list the policy notes
+/jev-auto-mode policy edit
+/jev-auto-mode policy clear
+/jev-auto-mode threshold                show thresholds and the last observed probability per rule
+/jev-auto-mode threshold <rule> <0.5-1> set one threshold
+/jev-auto-mode threshold edit            pick a rule and type a value
+/jev-auto-mode threshold reset [rule]   restore the calibrated default
+/jev-auto-mode uncertain                show what the middle band resolves to
+/jev-auto-mode uncertain deny|ask|allow
+/jev-auto-mode scope all|matched        how far the semantic layer reaches
+```
+
+```
+pi --jev-auto-mode        start with auto mode enabled
+```
+
+The semantic layer needs a [TypeSafe](https://typesafe.ai/) API key. Jev is early access, so an
+account may be waitlisted; **the gate still works without one**. Its own rules keep running —
+read-only and user-declared safe commands pass, hard-deny shapes are blocked — but a call
+nothing vouches for is blocked with "Not connected to Jev" instead of being judged.
+
+`/jev-auto-mode login` asks for the key, verifies it against the API (`GET /v1/models`), and
+stores it as an owner-only file at
+`$PI_CODING_AGENT_DIR/secrets/jev-auto-mode-typesafe-api-key` (mode `0600`) — the same place Pi
+keeps its own credentials, so it is never committed with a project. `TYPESAFE_API_KEY` takes
+precedence when set, so a one-off or CI override needs no login. `TYPESAFE_DEFAULT_MODEL`
+selects the model (default `jev-latest`).
+
+A key is only stored after the API accepts it: a typo that got saved would turn into a gate
+that silently blocks every escalated call. If the API cannot be reached the key is not stored
+either, and the command says so rather than claiming success.
+
+Without a key the gate does not disable itself and does not allow everything: it stops the calls
+it cannot judge and says it is not connected to Jev. The footer shows `🛡 jev (<scope>)` while the
+semantic layer is active and `🛡 jev no key (<scope>)` when it is not.
+
+## Tuning
+
+The thresholds are a starting point measured on twelve fixtures, not a truth
+([`docs/calibration.md`](./docs/calibration.md)). To retune them from your own work:
+
+1. Run the thing you care about. The gate records every judgment; expand the record in the
+transcript and read the per-condition table:
+
+```
+intent_coverage     p=0.97  pass (t=0.80, >= 0.80)
+no_outward_effect   p=0.06  reject (t=0.90, <= 0.10) <- decided (cleared by the user's request)
+local_scope         p=0.81  pass (t=0.90, >= 0.90)
+```
+
+2. If a condition that should have passed lands in the middle band, lower its threshold. If
+something got through that should not have, raise it. `/jev-auto-mode threshold` shows the
+current value next to the last probability the model returned for that rule.
+
+3. `/jev-auto-mode threshold <rule> <value>` writes the override. It takes effect immediately
+and persists in the global settings file.
+
+A threshold must leave a middle band on both sides (`0.5 < t <= 1`): `t` is the probability
+required to count as satisfied, and `1 - t` is the probability at or below which the condition
+counts as violated. Values that close one side are rejected.
+
+```json
+{
+  "thresholds": {
+    "intent_coverage": 0.6,
+    "no_secret_egress": 0.995
+  }
+}
+```
+
+The right fix is usually to phrase the condition better, not to move the threshold. If "should
+pass" and "should reject" answers overlap, the question is ambiguous.
+
+## Configuration
+
+Global settings: `$PI_CODING_AGENT_DIR/jev-auto-mode.json` (default `~/.pi/agent/`).
+Project override: `<cwd>/.pi/jev-auto-mode.json`, honored **only for a trusted project** —
+an untrusted checkout must not be able to loosen the gate that is judging it.
+Policy notes: `$PI_CODING_AGENT_DIR/jev-auto-mode-policy.md`.
+
+```json
+{
+  "enabled": true,
+  "timeoutMs": 4000,
+  "maxRetries": 1,
+  "safeCommands": ["uv run pytest*", "pnpm run typecheck*"],
+  "allowedCommands": ["rm -rf build*"],
+  "disallowedCommands": ["npm publish*"],
+  "extraProtectedPaths": [],
+  "maxStateCharacters": 120000,
+  "uncertain": "deny",
+  "gateScope": "all",
+  "thresholds": {}
+}
+```
+
+- Allow patterns never match a command containing shell control syntax (`;`, `&&`, `|`,
+  redirection, substitution), so `ls*` cannot approve `ls && rm -rf /`.
+- Malformed values are dropped rather than defaulted, so a broken project file cannot pin a
+  value that overrides the global layer.
+- There are two ways to widen the fast path, with different meanings:
+
+  | Setting | Effect |
+  |---|---|
+  | `safeCommands` | Run without a decision record. For commands that are safe *on your machine*: `uv run pytest*`, `npm run test*`, `cargo test*`, `go test ./...*` |
+  | `allowedCommands` | Override a dangerous-pattern match. The override is recorded, so approving `rm -rf build` by rule is visible |
+
+  The built-in safe list is not configurable and holds read-only inspection only (`git
+  status`/`diff`/`log`/`show`/`branch`, `ls`, `pwd`, `rg`, `grep`). It deliberately contains no
+  command that executes project code: a test runner runs repository code, so declaring it safe
+  is a decision for the machine that owns it, not a default shipped to everyone. Allow patterns
+  never match a command containing shell control syntax, so `ls*` cannot approve `ls && rm -rf /`.
+
+## What leaves the machine
+
+An escalated call sends the following to TypeSafe's API (`api.typesafe.ai`):
+
+- the tool name and the bash command text (truncated),
+- for `write` / `edit`: the target **path** — never the file contents or the diff,
+- the working directory, the matched policy reason names,
+- recent **user** messages (bounded), and your policy notes.
+
+Obvious credentials (`*_KEY=…`, `Bearer …`, JWTs, `sk-…`, `ghp_…`, PEM private keys) are
+redacted on the way out. Assistant output, tool output, and file contents are never sent.
+Details and the failure-mode table: [`docs/security.md`](./docs/security.md).
+
+## Releasing
+
+A version, a tag, and a release are cut **once, when the version is published**, so the tag list
+matches what people can install. Unfinished work accumulates under `## Unreleased` in
+`CHANGELOG.md` and is renamed to the version at release time:
+
+1. `npm run check`
+2. rename `## Unreleased` to `## <version>` in `CHANGELOG.md`, bump `version` in `package.json`
+3. commit, `git tag -a v<version>`, `git push --follow-tags`
+4. `gh release create v<version> --notes-file <(the changelog section)`
+5. `npm publish`
+
+## Development
+
+```sh
+npm install
+npm test          # node:test, no network
+npm run typecheck
+node --experimental-strip-types scripts/calibrate.ts   # real API, needs TYPESAFE_API_KEY
+```
+
+Layout:
+
+| Path | Responsibility |
+|---|---|
+| `src/policy.ts` | hard-deny, user rules, dangerous patterns, protected paths, safe commands |
+| `src/call.ts` | `tool_call` → judgment state (redaction, truncation, path classification) |
+| `src/intent.ts` | recent user-authored intent only |
+| `src/decide.ts` | the decision-engine seam (`DecisionEngine`) |
+| `src/jev/questions.ts` | the condition set, modes, severities, thresholds |
+| `src/jev/availability.ts` | where the API key comes from (env or stored secret) |
+| `src/jev/decide.ts` | probability → condition verdict → decision |
+| `src/jev/engine.ts` | one request per call, budget guard, calibration hook |
+| `src/jev/transport.ts` | the SDK, wrapped so failures become decisions |
+| `src/jev/response.ts` | response re-validation (a 200 is not an answer) |
+| `src/settings.ts` | global/project settings, policy notes, and the stored API key |
+| `src/records.ts` | `appendEntry` records and their renderer |
+| `src/ui.ts` | footer status and user-facing text |
+| `src/extension.ts` | `tool_call` orchestration and command wiring |
+
+## Acknowledgements
+
+The deterministic pattern catalogue is adapted from
+[`@nilskluewer/pi-auto-permission-gate`](https://github.com/nilskluewer/pi-auto-permission-gate)
+(MIT), and the three-layer structure (fast paths → hard rules → classifier) follows the same
+extension and Qwen Code's Auto Mode. The Jev design constraints (fail closed, two-sided
+thresholds that keep the middle band meaningful, one request per judgment) come from measuring
+the API directly — [`docs/calibration.md`](./docs/calibration.md) records the measurements and
+the reasoning. Nothing here depends on a wrapper library: the Jev layer is written against the
+official SDK.
+
+## License
+
+MIT

package/node_modules/pi-jev-auto-mode/SECURITY.md

@@ -0,0 +1,32 @@
+# Security
+
+This extension stands between a coding agent and your shell, so its own failure modes matter.
+
+## Reporting
+
+Open a private security advisory on the repository, or an issue if the report does not need to
+stay private. Please include the tool call, the recorded decision (`/jev-auto-mode` records
+are expandable in the transcript), and the Jev probabilities if you have them.
+
+## What is in scope
+
+- A call that should have been blocked and was not.
+- A call that was approved without the semantic layer being consulted.
+- Credential or file content leaving the machine inside a judgment request.
+- A stored API key readable by another user, or written somewhere other than
+  `<agentDir>/secrets/` with mode `0600`.
+
+## Design summary
+
+The gate is two layers and the order is the enforcement:
+
+1. A deterministic envelope (hard-deny, user rules, dangerous-command patterns, protected
+   paths). Hard-deny returns before the semantic layer is constructed, so a probabilistic
+   verdict can never resurrect it.
+2. Jev, which only sees calls the first layer escalated.
+
+Anything that cannot be decided — no key, timeout, malformed response, a response missing an
+answer, cancellation, an oversized request — blocks. See
+[docs/security.md](./docs/security.md) for the failure-mode table, what is sent to the API, and
+the known limits (including the `soft`-severity clearing, which is the mechanism to remove first
+if a wrong approval ever appears).