@wernerbisschoff/pi-gatekeeper 0.1.1 → 0.1.3

package/dist/gatekeeper.js

@@ -17,10 +17,10 @@
  */
 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 { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 const execAsync = promisify(exec);
 /**
@@ -317,7 +317,7 @@ export function saveRules(filePath, payload, ctx) {
  * extension creates it from a clean slate.
  */
 export function getRulesPath() {
-    const agentDir = join(os.homedir(), ".pi", "agent");
+    const agentDir = getAgentDir();
     mkdirSync(agentDir, { recursive: true, mode: 0o700 });
     return join(agentDir, "perm-rules.json");
 }
@@ -564,21 +564,27 @@ 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)
+ *   - `low`    → `LOW`      (restricted/safe)
+ *   - `medium` → `MEDIUM`   (balanced)
+ *   - `high`   → `HIGH`     (permissive)
  * 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).
  */
+/**
+ * Plain-text level labels used by {@link updateStatus} to build the
+ * TUI footer indicator. The labels are intentionally simple — the
+ * `/perm` hint is appended at render time so the indicator is
+ * self-documenting without coloured circles.
+ */
 export const MODE_LABELS = {
-    low: "🟢 LOW",
-    medium: "🟡 MEDIUM",
-    high: "🟠 HIGH",
+    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
+ * `~/.pi/agent/perm-mode` file directly and overlays the level 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.
  *
@@ -588,7 +594,11 @@ export const MODE_LABELS = {
  * define the primitive so it is independently testable.
  */
 export function updateStatus(ctx) {
-    ctx.ui.setStatus(PERMISSION_STATUS_KEY, MODE_LABELS[currentMode]);
+    const label = MODE_LABELS[currentMode];
+    const text = `${label} · /perm`;
+    // Apply muted theme styling when available (supported in both Pi and OMP).
+    const styled = typeof ctx.ui.theme?.fg === "function" ? ctx.ui.theme.fg("muted", text) : text;
+    ctx.ui.setStatus(PERMISSION_STATUS_KEY, styled);
     // 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
@@ -1270,40 +1280,29 @@ export function matchSegmentAgainstList(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`).
+ * Find the first matching pattern in `patterns`. Single walker primitive for first-match-wins
+ * semantics — {@link matchSegmentAgainstList}, {@link evaluateExplicit}, and the cascade walkers
+ * delegate here so the public API, the explicit-pass evaluator, and the cascade walkers share
+ * one iteration loop. Returns only the matched pattern name on hit (no index) because no
+ * caller surfaces "earlier patterns did not match" diagnostic context — first-match-wins is
+ * expressed by the matched pattern alone (`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 };
+    for (const pattern of patterns) {
+        if (matchGlob(pattern, segment)) {
+            return { matched: true, pattern };
         }
     }
     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.
+ * Build the reason string for an explicit-pass match at the current level. Single-line form:
+ * `${action} at ${level} matched '<pattern>'`. First-match-wins is expressed by the matched
+ * pattern name alone — no earlier-patterns parenthetical is appended, so the FLOW-07 prompt
+ * preview stays decluttered and only the winning pattern reaches the LLM.
  */
-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)`;
+function explicitReason(action, level, matched) {
+    return `${action} at ${level} matched '${matched}'`;
 }
 /**
  * Build the reason string for a cascade-inherited match. Mirrors {@link explicitReason}'s
@@ -1333,7 +1332,7 @@ function evaluateExplicit(segment, mode, levelRules) {
         if (match.matched) {
             return {
                 decision: action,
-                reason: explicitReason(action, mode, match.pattern, match.index, levelRules[action]),
+                reason: explicitReason(action, mode, match.pattern),
             };
         }
     }
@@ -1529,9 +1528,17 @@ export function classifyCommand(command, mode, rules) {
     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,
+    // (c) Strip leading env-var assignments from each segment — shell semantics treat
+    // `VAR=value cmd` as an environment override for `cmd`, so the env-var prefix is not
+    // part of the executable command. This is handled for the full command by
+    // `runPermissionGate`'s `stripLeadingEnvAssignments`, but compound commands split by
+    // `&&`, `||`, `;`, or `|` produce segments where the env var is no longer at position 0
+    // of the original input. Stripping per-segment here ensures classification (allow/deny/ask
+    // rules) and cascade matching work against the bare command in every segment.
+    const strippedSegments = segments.map((seg) => stripLeadingEnvAssignments(seg));
+    // (d) Per-segment classification — delegate to classifySegment for each surviving segment.
+    const perSegment = strippedSegments.map((seg) => classifySegment(seg, mode, rules));
+    // (e) 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("; ");
@@ -2033,14 +2040,13 @@ export function stripLeadingEnvAssignments(command) {
  * 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)
+ *   - `getAllowListEntries("grep -l pattern")` → `["grep"]` (command name extracted)
+ *   - `getAllowListEntries("ls && grep pattern")` → `["ls", "grep"]` (one command per segment)
+ *   - `getAllowListEntries("npm install express && npm test")` → `["npm", "npm test"]`
+ *     (command names; duplicates collapsed; `npm test` is a different command from `npm install`
+ *      but both share `npm` as command name; kept only once)
+ *   - `getAllowListEntries("cat /tmp/output.txt")` → `["cat"]`
+ *   - `getAllowListEntries("echo hello")` → `["echo"]` (single segment command name)
  *
  * Contract anchors:
  *   - `data-model.md:177-228` (FR-008: allowlist entry computation)
@@ -2051,38 +2057,206 @@ export function stripLeadingEnvAssignments(command) {
  * empty-input early-return keeps dedup logic clean and matches PRD's "empty command → empty array"
  * exception strategy.
  */
+/**
+ * Extract the command stem from a command string — the command name plus any
+ * fixed subcommand (e.g. `git diff`, `docker compose`). Everything before the
+ * first flag argument (word starting with `-`) or path argument (word starting
+ * with `/`, `~`, `.`). This produces entries that, when persisted with ` *`,
+ * match the same subcommand pattern without being overly broad (`git diff *`
+ * rather than `git *`).
+ *
+ * For single-word commands without subcommands (e.g. `grep`, `ls`), returns
+ * just the command name.
+ */
+function extractCommandStem(segment) {
+    const cleaned = stripLeadingEnvAssignments(segment);
+    const words = splitShellWords(cleaned);
+    if (words.length === 0)
+        return cleaned;
+    // Take words until we hit something that looks like a flag or path.
+    const stem = [];
+    for (const w of words) {
+        if (w.startsWith("-"))
+            break; // flag argument starts here
+        if (w.startsWith("/") || w.startsWith("~") || w.startsWith(".")) {
+            // Bare path — stop before it UNLESS this is the very first word
+            // (a bare-path command like `/usr/bin/ls`).
+            if (stem.length > 0)
+                break;
+        }
+        stem.push(w);
+    }
+    if (stem.length === 0)
+        return words[0];
+    return stem.join(" ");
+}
+/**
+ * Compute allowlist entries for a command — returns the FULL parsed segments
+ * (not command stems). These entries are used by:
+ *   - `promptForPermission` for the "Will allow" preview (which further filters
+ *     to show only the "ask" segments' command stems)
+ *   - `appendStemsToAllowList` for persistence (each entry is already a command stem
+ *     extracted by the caller — this function does NOT do the stem extraction)
+ *   - "allow-session" and "allow-once" for session/ephemeral caching of the
+ *     full resolved command
+ *
+ * Returns full segments so the caller can decide how to display/persist them.
+ */
 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;
+    // Strip leading env-var assignments from each segment so transient `VAR=val`
+    // prefixes do not leak into entries.
+    const cleanSegments = rawSegments.map((s) => stripLeadingEnvAssignments(s));
+    // Filter bare paths.
+    const segments = cleanSegments.filter((s) => !isBarePath(s));
     if (segments.length === 0) {
-        candidates = [trimmed];
-    }
-    else {
-        candidates = [segments[0], trimmed, ...segments.slice(1)];
+        // Fallback: no non-bare segments.
+        return isBarePath(trimmed) ? [] : [trimmed];
     }
+    // Dedup full segments (preserving order).
     const seen = new Set();
     const out = [];
-    for (const entry of candidates) {
-        if (entry.length === 0)
+    for (const seg of segments) {
+        if (seen.has(seg))
             continue;
-        if (isBarePath(entry))
+        seen.add(seg);
+        out.push(seg);
+    }
+    return out;
+}
+/**
+ * Redirect-operator prefix anchor: a token is a redirect when it begins with `<` / `>`
+ * (including `<<` heredoc, `<<<` herestring, bare `>`), with `&<` / `&>`, or with a digit
+ * fd-prefix followed by a redirect (`2>`, `1<`, `2>>`, …). Single-shot module-scope RegExp
+ * so the three alternative branches don't recompile per call.
+ */
+const REDIRECT_OP_PREFIX_RE = /^(?:[<>]|&[<>]|\d+[<>])/;
+/**
+ * Bare (operator-only) redirect shape: the token is EXACTLY the operator with no embedded
+ * target — `>`, `>>`, `<<`, `<<<`, `&>`, `&>>`, `2>`, `2>>`, … Self-contained forms like
+ * `2>&1`, `2>file`, or `&>out` have non-redirect trailing chars and therefore do NOT match.
+ * Drives {@link stripRedirectsFromTokens}'s target-consumption decision.
+ */
+const BARE_REDIRECT_RE = /^&?[0-9]*[<>]+$/;
+/**
+ * Filter redirect operators and their targets from an already-tokenized word list. Returns the
+ * surviving executable words in their original order.
+ *
+ * Algorithm mirrors `splitShellSegments`'s redirect-tracking state machine
+ * (`src/gatekeeper.ts:1382-1396`) but at the WORD level — a bare redirect operator
+ * (`>`, `>>`, `<`, `<<`, `2>`, `2>>`, …) consumes the next token as its target; self-contained
+ * forms like `2>&1`, `2>file`, `&>out` are recognized by {@link REDIRECT_OP_PREFIX_RE} but do
+ * NOT match {@link BARE_REDIRECT_RE}, so they consume nothing further.
+ */
+function stripRedirectsFromTokens(tokens) {
+    const out = [];
+    let consumeNext = false;
+    for (const token of tokens) {
+        if (consumeNext) {
+            consumeNext = false;
             continue;
-        if (seen.has(entry))
+        }
+        if (token.length > 0 && REDIRECT_OP_PREFIX_RE.test(token)) {
+            if (BARE_REDIRECT_RE.test(token)) {
+                consumeNext = true;
+            }
             continue;
-        seen.add(entry);
-        out.push(entry);
+        }
+        out.push(token);
     }
     return out;
 }
+/**
+ * Compute the list of positional wildcard candidates for a single shell segment. Used by
+ * FLOW-12's segment-by-segment prompt (TSK-009-04) to build `<candidate> * This Session` and
+ * `<candidate> * Always` options from the segment's executable token chain.
+ *
+ * Pipeline:
+ *   1. {@link stripLeadingEnvAssignments} — drop transient `VAR=val` prefixes so they do not
+ *      leak into the candidate list.
+ *   2. {@link splitShellWords} — tokenize on whitespace, respecting single/double quotes so
+ *      `"hello world"` is one token, not two.
+ *   3. {@link stripRedirectsFromTokens} — drop redirect operators (`>`, `>>`, `<`, `<<`,
+ *      `2>`, `2>&1`, …) and their targets so `pnpm exec biome check test/ 2>&1` produces the
+ *      same candidates as `pnpm exec biome check test/`.
+ *   4. Prefix-depth unfolding — emit one candidate per prefix depth `k`:
+ *      `<tokens[0..k).join(" ") + " *">`. The wildcard is always on the LAST emitted token,
+ *      never between tokens.
+ *
+ * Contract (pinned by `test/prompt.test.ts` FLOW-12 sub-describe):
+ *   - `unfoldPositionalCandidates("pnpm exec biome check test/")` →
+ *     `["pnpm *", "pnpm exec *", "pnpm exec biome *", "pnpm exec biome check *", "pnpm exec biome check test/ *"]`
+ *   - `unfoldPositionalCandidates("pnpm exec biome check test/ 2>&1")` → identical to above
+ *     (the `2>&1` redirect contributes nothing).
+ *   - `unfoldPositionalCandidates("> /dev/null")` → `[]` (bare redirect consumes its target).
+ *   - `unfoldPositionalCandidates("NODE_ENV=test pnpm test")` → `["pnpm *", "pnpm test *"]`
+ *     (env-var prefix stripped, then unfolded).
+ *   - `unfoldPositionalCandidates("head")` → `["head *"]` (single-word segment).
+ *   - `unfoldPositionalCandidates("")` → `[]` (empty / whitespace-only inputs never throw).
+ *
+ * Pure function — no I/O, no side effects, no module-level state. O(n) over the segment's
+ * character count.
+ *
+ * Source anchor: AC-ADHOC-012-01 / AC-ADHOC-012-02 (positional wildcard unfolding).
+ */
+export function unfoldPositionalCandidates(segment) {
+    const cleaned = stripLeadingEnvAssignments(segment);
+    if (cleaned.trim().length === 0)
+        return [];
+    const tokens = stripRedirectsFromTokens(splitShellWords(cleaned));
+    if (tokens.length === 0)
+        return [];
+    const candidates = [];
+    for (let k = 1; k <= tokens.length; k += 1) {
+        candidates.push(`${tokens.slice(0, k).join(" ")} *`);
+    }
+    return candidates;
+}
+/**
+ * Validate that every `*` wildcard in `pattern` is preceded by either a whitespace character or
+ * the start of the pattern. Used by FLOW-12 as the write-time guard inside
+ * {@link appendStemsToAllowList} (defense-in-depth) and by the ingest-time check on any
+ * programmatically-built wildcard before it lands in `perm-rules.json`.
+ *
+ * Rule (Issue 009 Hard Inclusion #2, AC-ADHOC-012-04):
+ *   - Every `*` in `pattern` MUST be at position 0 OR immediately preceded by whitespace
+ *     (` `, `\t`, or `\n`).
+ *   - Patterns without a `*` are vacuously valid.
+ *
+ * Why: a pattern like `git*` (no space before the wildcard) compiles to the regex
+ * `^git.*$`, which matches `gitlog`, `git-fetch`, and any other input that merely STARTS
+ * with `git`. The full-token-boundary rule prevents this class of accidental over-match
+ * — `git *` is the correct pattern for "git followed by anything" and matches only inputs
+ * where `git` is its own whitespace-delimited token.
+ *
+ * Pure predicate — single linear scan, O(n) over `pattern.length`. Sub-microsecond per call.
+ *
+ * Contract (pinned by `test/prompt.test.ts` FLOW-12 sub-describe):
+ *   - `validateFullTokenBoundary("git *")` → `true`
+ *   - `validateFullTokenBoundary("git*")` → `false`
+ *   - `validateFullTokenBoundary("*")` → `true` (position 0)
+ *   - `validateFullTokenBoundary("git diff *")` → `true`
+ *   - `validateFullTokenBoundary("npm install express")` → `true` (no `*`, vacuously valid)
+ *   - `validateFullTokenBoundary("")` → `true` (vacuously valid)
+ */
+export function validateFullTokenBoundary(pattern) {
+    for (let i = 0; i < pattern.length; i += 1) {
+        if (pattern[i] !== "*")
+            continue;
+        // Position-0 wildcard is the "start of pattern" boundary — a leading `*` is a suffix
+        // wildcard ("anything ending with X"), which is acceptable.
+        if (i === 0)
+            continue;
+        const prev = pattern[i - 1];
+        if (prev === " " || prev === "\t" || prev === "\n")
+            continue;
+        return false;
+    }
+    return true;
+}
 /**
  * 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
@@ -2147,9 +2321,52 @@ export function sessionAllow(command) {
 export function isSessionAllowed(command) {
     return sessionAllowList.has(command);
 }
+/* ─── Allow All Once — ephemeral flag for compound commands (FLOW-12) ───
+ *
+ * Module-level boolean that when set causes `runPermissionGate` to return
+ * `{ allow: true }` for remaining segments without prompting. Cleared after
+ * execution completes (does NOT persist across bash tool invocations).
+ *
+ * Lifecycle: setAllowAllOnce → consumeAllowAllOnce (read-and-clear,
+ * one-shot, returns true once) → resetAllowAllOnce (unconditional clear).
+ *
+ * Flow references: FLOW-12 Step 3 + Step 8 + FLOW-08 Step 3. */
+let allowAllOnceActive = false;
+/**
+ * Set the Allow All Once flag. After this call, the next
+ * {@link consumeAllowAllOnce} returns `true` and clears the flag.
+ * Exported so the TSK-009-03 lifecycle tests can drive it directly
+ * without going through {@link promptForCompoundCommand}.
+ */
+export function setAllowAllOnce() {
+    allowAllOnceActive = true;
+}
+/**
+ * Consume (read-and-clear) the Allow All Once flag. Returns `true`
+ * exactly once when the flag was set by a prior {@link setAllowAllOnce}
+ * call; subsequent calls return `false` until the flag is re-set.
+ * This one-shot semantics mirrors the existing {@link isEphemeralAllowed}
+ * pattern.
+ */
+export function consumeAllowAllOnce() {
+    if (allowAllOnceActive) {
+        allowAllOnceActive = false;
+        return true;
+    }
+    return false;
+}
+/**
+ * Unconditionally clear the Allow All Once flag. Idempotent — calling
+ * when the flag is already `false` is a no-op. Primed as the test-teardown
+ * seam (per-test `beforeEach` in the FLOW-12 lifecycle describe); intended
+ * for cleanup after compound command execution resolves (FLOW-12 Step 8 —
+ * integration pending).
+ */
+export function resetAllowAllOnce() {
+    allowAllOnceActive = false;
+}
 /**
- * Append `entries` to `list` (in place) using first-occurrence-wins dedup. Pure helper
- * shared by {@link appendToAllowList} and {@link appendToDenyList} — both writers push
+ * shared by {@link appendStemsToAllowList} 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).
  */
@@ -2163,45 +2380,42 @@ function appendUnique(list, entries) {
     }
 }
 /**
- * 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:
+ * Persist command stems from "ask" segments to the current level's allow list.
+ * Each stem is written in two forms — bare (`"git diff"`) and wildcard (`"git diff *"`)
+ * — matching the default-rules convention without being overly broad (`"git *"`
+ * would allow all subcommands). Dedup via {@link appendUnique} so re-clicking
+ * "Allow Always" on the same compound does NOT duplicate entries.
  *
- *   - `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).
+ * Defense-in-depth (Issue 009 §Hard Inclusion #2, AC-ADHOC-012-04): each candidate
+ * is filtered through {@link validateFullTokenBoundary}, silently dropping
+ * glued-wildcard forms (`"git*"`) so future programmatic callers (FLOW-12's
+ * `promptForCompoundCommand`) cannot seed `perm-rules.json` with an over-broad
+ * pattern that would match `gitlog` / `git-fetch`. Empty input is a no-op (no write).
  */
-function appendToAllowList(entries, ctx) {
+export function appendStemsToAllowList(stems, ctx) {
     const rules = loadRules(ctx);
     const mode = getCurrentMode();
-    appendUnique(rules.rules[mode].allow, entries);
+    const expanded = [];
+    for (const stem of stems) {
+        const wild = `${stem} *`;
+        if (validateFullTokenBoundary(stem))
+            expanded.push(stem);
+        if (validateFullTokenBoundary(wild))
+            expanded.push(wild);
+    }
+    if (expanded.length === 0)
+        return;
+    appendUnique(rules.rules[mode].allow, expanded);
     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}.
+ * read-then-write + dedup + safety-floor-preservation contract from {@link appendStemsToAllowList}.
  * 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
+
+ * **API asymmetry note** (see {@link appendStemsToAllowList} 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
@@ -2215,7 +2429,7 @@ function appendToDenyList(command, ctx) {
     saveRules(getRulesPath(), rules, ctx);
 }
 /**
- * Headless-safety short-circuit helper shared by {@link promptForPermission} and
+ * Headless-safety short-circuit helper shared by {@link ensureSelectAvailable} 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)`
@@ -2229,6 +2443,30 @@ function checkHeadlessShortCircuit(ctx) {
         ctx.ui.notify(BLOCKED_HEADLESS_MESSAGE, "warning");
     return true;
 }
+/**
+ * Shared prompt-availability guard used by both {@link promptForPermission} and
+ * {@link promptForCompoundCommand}. Returns `true` when the caller should proceed with
+ * the prompt; `false` when a UI issue (headless mode, missing select function) prevents
+ * showing the prompt and the caller should fall back to a conservative deny.
+ *
+ * Combines two independent checks that are always used together:
+ * 1. {@link checkHeadlessShortCircuit} — headless mode (ctx.hasUI === false)
+ * 2. `ctx.ui.select` availability — runtime-absent UI surface
+ *
+ * Each check emits its own notification on failure so the developer has a clear signal
+ * about why the prompt was skipped. Centralizing them ensures both prompt paths share
+ * the same failure UX without duplicating the guard logic.
+ */
+function ensureSelectAvailable(ctx) {
+    if (checkHeadlessShortCircuit(ctx))
+        return false;
+    if (typeof ctx.ui?.select !== "function") {
+        if (ctx.ui)
+            ctx.ui.notify("Prompt unavailable; defaulting to deny", "warning");
+        return false;
+    }
+    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
@@ -2241,17 +2479,10 @@ function checkHeadlessShortCircuit(ctx) {
  * 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");
+async function promptForPermission(reason, command, askPreview, ctx) {
+    if (!ensureSelectAvailable(ctx))
         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}`;
+    const message = `[${reason}]\n\nCommand: ${command}\n\nWill allow: ${askPreview}`;
     try {
         const items = ["Allow Once", "Allow This Session", "Allow Always", "Deny"];
         const selected = await ctx.ui.select(message, items);
@@ -2271,6 +2502,187 @@ async function promptForPermission(reason, command, ctx) {
         return null;
     }
 }
+/**
+ * Build the option list for the compound command prompt from positional wildcard
+ * candidates. Pure function — no I/O, no side effects.
+ *
+ * Order: Allow All Once, then each candidate with This Session / Always suffixes,
+ * then Deny as the final entry.
+ *
+ * @param candidates — output of {@link unfoldPositionalCandidates}
+ * @returns a string array suitable for `ctx.ui.select({ options })`
+ */
+function buildCompoundOptions(candidates) {
+    const options = ["Allow All Once"];
+    for (const c of candidates) {
+        options.push(`${c} This Session`);
+        options.push(`${c} Always`);
+    }
+    options.push("Deny");
+    return options;
+}
+/**
+ * Parse a selected option string from the compound command prompt back into
+ * a structured {@link CompoundSelection}. Pure function — no I/O, no side effects.
+ *
+ * Returns `null` for unrecognised selections (the caller treats this as a
+ * conservative deny per Constitution §1.6).
+ */
+function parseCompoundSelection(selected) {
+    if (selected === "Allow All Once")
+        return { type: "allow-all-once" };
+    if (selected === "Deny")
+        return { type: "deny" };
+    // Must be a candidate option — determine if This Session or Always.
+    if (selected.endsWith(" This Session")) {
+        const pattern = selected.slice(0, -" This Session".length);
+        return { type: "candidate", pattern, isSession: true };
+    }
+    if (selected.endsWith(" Always")) {
+        const pattern = selected.slice(0, -" Always".length);
+        return { type: "candidate", pattern, isSession: false };
+    }
+    // Unexpected selection.
+    return null;
+}
+/**
+ * Apply a parsed compound selection decision: construct the decision entry,
+ * append it to `resultSegments`, and execute any persistence side effects
+ * (session allow, allow-always persistence). Intended as the inner workhorse
+ * of {@link promptForCompoundCommand}'s segment loop.
+ *
+ * Returns `true` when the caller should short-circuit (Allow All Once selected
+ * — the flag has been set and the function has already returned early by
+ * returning the compound decision with `allowAllOnceUsed: true`); returns
+ * `false` to continue to the next segment.
+ *
+ * Pure-ish: writes to `resultSegments` (mutating push), calls `setAllowAllOnce`,
+ * `sessionAllow`, or `appendStemsToAllowList` as side effects. The caller owns
+ * `resultSegments` and must not reuse it after this returns `true` (the return
+ * already contains the final compound decision).
+ */
+function applyCompoundSegmentDecision(segment, parsed, resultSegments, ctx) {
+    if (parsed.type === "allow-all-once") {
+        setAllowAllOnce();
+        resultSegments.push({ segment, decision: "allow", scope: "ephemeral" });
+        return true;
+    }
+    if (parsed.type === "deny") {
+        resultSegments.push({ segment, decision: "deny", scope: "persist" });
+        return false;
+    }
+    // Candidate — extract the stem (remove trailing ` *` for persistence).
+    const stem = parsed.pattern.endsWith(" *") ? parsed.pattern.slice(0, -2) : parsed.pattern;
+    if (parsed.isSession) {
+        sessionAllow(stem);
+        resultSegments.push({
+            segment,
+            decision: "allow",
+            scope: "session",
+            pattern: parsed.pattern,
+        });
+    }
+    else {
+        appendStemsToAllowList([stem], ctx);
+        resultSegments.push({
+            segment,
+            decision: "allow",
+            scope: "persist",
+            pattern: parsed.pattern,
+        });
+    }
+    return false;
+}
+/**
+ * Segment-by-segment interactive prompt for compound commands (FLOW-12).
+ *
+ * For each "ask" segment, computes positional wildcard candidates via
+ * {@link unfoldPositionalCandidates}, presents them in a `ctx.ui.select()`
+ * dialog with Allow All Once / This Session / Always / Deny options, and
+ * returns a {@link CompoundDecision} mapping each segment to its scoped result.
+ *
+ * The Allow All Once option short-circuits remaining segments without prompting
+ * and sets the Allow All Once flag so {@link runPermissionGate} can skip
+ * re-prompting for subsequent segments of the same compound execution.
+ *
+ * Headless short-circuit (FLOW-11): when `ctx.hasUI === false`, returns an empty
+ * `CompoundDecision` immediately without calling `ctx.ui.select` — the caller
+ * should treat this as a deny per the existing headless auto-deny contract.
+ * Similarly, when `ctx.ui.select` is not a function (UI is absent at runtime),
+ * returns an empty result conservatively.
+ *
+ * Flow references:
+ *   - FLOW-12 Step 3 ("segment-by-segment prompt loop")
+ *   - FLOW-12 Step 8 ("Allow All Once flag lifecycle")
+ *   - FLOW-08 Step 3 ("scope-based persistence routing")
+ */
+export async function promptForCompoundCommand(segments, ctx) {
+    if (!ensureSelectAvailable(ctx)) {
+        return { segments: [], allowAllOnceUsed: false };
+    }
+    if (segments.length === 0) {
+        return { segments: [], allowAllOnceUsed: false };
+    }
+    const resultSegments = [];
+    const promptSelect = ctx.ui.select;
+    for (const segment of segments) {
+        const candidates = unfoldPositionalCandidates(segment);
+        const options = buildCompoundOptions(candidates);
+        let selected;
+        try {
+            selected = await promptSelect({
+                message: `Segment: ${segment}`,
+                options,
+            });
+        }
+        catch {
+            // Fail closed per Constitution §1.6 — a thrown prompt must never silently
+            // allow. The denial is recorded in the CompoundDecision and surfaced by
+            // finalizeCompoundGateResult's notification, avoiding a duplicate warning.
+            resultSegments.push({ segment, decision: "deny", scope: "persist" });
+            return { segments: resultSegments, allowAllOnceUsed: false };
+        }
+        if (selected === undefined) {
+            return { segments: resultSegments, allowAllOnceUsed: false };
+        }
+        const parsed = parseCompoundSelection(selected);
+        if (parsed === null) {
+            resultSegments.push({ segment, decision: "deny", scope: "persist" });
+            continue;
+        }
+        if (applyCompoundSegmentDecision(segment, parsed, resultSegments, ctx)) {
+            return { segments: resultSegments, allowAllOnceUsed: true };
+        }
+    }
+    return { segments: resultSegments, allowAllOnceUsed: false };
+}
+/**
+ * Interpret a {@link CompoundDecision} returned by
+ * {@link promptForCompoundCommand} into a gate result suitable for
+ * {@link runPermissionGate}'s compound branch (5b). Pure logic — no I/O,
+ * no side effects, no persistence.
+ *
+ * Resolution rules:
+ * - Allow All Once → allow all segments (flag already consumed by
+ *   `promptForCompoundCommand`).
+ * - Any segment allowed → allow the compound command (permissive default:
+ *   when the classifier yielded "ask" for every segment, gates that pass
+ *   at least one segment's prompt allow the chain to proceed).
+ * - No segment allowed → notify and deny.
+ */
+function finalizeCompoundGateResult(compoundDecision, ctx) {
+    if (compoundDecision.allowAllOnceUsed) {
+        return { allow: true };
+    }
+    const anyAllowed = compoundDecision.segments.some((s) => s.decision === "allow");
+    if (anyAllowed) {
+        return { allow: true };
+    }
+    if (ctx.hasUI && ctx.ui) {
+        ctx.ui.notify("Blocked: All segments denied", "warning");
+    }
+    return { allow: false };
+}
 /**
  * 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).
@@ -2319,6 +2731,15 @@ export async function runPermissionGate(command, ctx) {
     if (runtimeMode === "off") {
         return { allow: true };
     }
+    // (1.5) Allow All Once check — FLOW-12 Step 7/8. When the flag is set by
+    // promptForCompoundCommand for a preceding segment in the same compound
+    // execution, skip all processing (classifier, prompt) and return allow.
+    // The flag is consumed on first access (single-shot), so a subsequent
+    // runPermissionGate invocation without re-setting the flag goes through the
+    // normal classifier/prompt path.
+    if (consumeAllowAllOnce()) {
+        return { allow: true };
+    }
     // (2) Session allow check — persists across the session without consuming on match.
     if (isSessionAllowed(resolvedCommand)) {
         return { allow: true };
@@ -2327,7 +2748,7 @@ export async function runPermissionGate(command, ctx) {
     if (isEphemeralAllowed(resolvedCommand)) {
         return { allow: true };
     }
-    // (3) Classifier routing.
+    // (4) Classifier routing.
     const mode = getCurrentMode();
     const rules = loadRules(ctx);
     const decision = classifyCommand(resolvedCommand, mode, rules);
@@ -2341,11 +2762,36 @@ export async function runPermissionGate(command, ctx) {
         return { allow: false };
     }
     // (5) Prompt branch — classifier yielded "ask".
-    // (4a) Headless short-circuit (FLOW-11).
+    // (5a) Headless short-circuit (FLOW-11).
     if (checkHeadlessShortCircuit(ctx)) {
         return { allow: false };
     }
-    const choice = await promptForPermission(decision.reason, resolvedCommand, ctx);
+    // (5b) Compound command routing — FLOW-12 Step 2. Split the command into
+    // shell segments; when there is more than one non-empty segment, route
+    // through the segment-by-segment compound prompt instead of the
+    // single-segment prompt.
+    const rawSegments = splitShellSegments(resolvedCommand);
+    const segments = rawSegments.filter((s) => s.trim() !== "");
+    if (segments.length > 1) {
+        // Compound command: delegate to segment-by-segment prompt, then interpret
+        // the CompoundDecision through the shared finalizeCompoundGateResult helper.
+        // Note: promptForCompoundCommand → unfoldPositionalCandidates handles env
+        // stripping internally, so we pass raw segments here.
+        const compoundDecision = await promptForCompoundCommand(segments, ctx);
+        return finalizeCompoundGateResult(compoundDecision, ctx);
+    }
+    // (5c) Single-segment (or collapsed-to-one) ask path. Build the "Will allow"
+    // preview from only the segments that triggered the "ask" decision. Split
+    // the command, re-classify each segment, and extract command stems from the
+    // ask segments. This avoids showing already-allowed entries (e.g. `git diff`
+    // when `git diff *` is already in the low allow list) in the preview.
+    const strippedSegments = segments.map((seg) => stripLeadingEnvAssignments(seg));
+    const perSegment = strippedSegments.map((seg) => classifySegment(seg, mode, rules));
+    const askStems = perSegment
+        .map((d, i) => d.decision === "ask" ? extractCommandStem(strippedSegments[i]) : null)
+        .filter((s) => s !== null);
+    const askPreview = askStems.length > 0 ? askStems.join(", ") : "(no segments)";
+    const choice = await promptForPermission(decision.reason, resolvedCommand, askPreview, 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
@@ -2354,10 +2800,12 @@ export async function runPermissionGate(command, ctx) {
         return { allow: false };
     }
     if (choice === "allow-session") {
-        const entries = getAllowListEntries(resolvedCommand);
-        for (const entry of entries) {
-            sessionAllow(entry);
-        }
+        // Cache the full resolved command directly (not the command-name entries)
+        // so the exact-string `isSessionAllowed(resolvedCommand)` check on the next
+        // invocation finds a match. Entries from `getAllowListEntries` are now just
+        // command names (for display and "Allow Always" persistence), not the full
+        // command string that session matching needs.
+        sessionAllow(resolvedCommand);
         return { allow: true };
     }
     if (choice === "allow-once") {
@@ -2365,8 +2813,12 @@ export async function runPermissionGate(command, ctx) {
         return { allow: true };
     }
     if (choice === "allow-always") {
-        const entries = getAllowListEntries(resolvedCommand);
-        appendToAllowList(entries, ctx);
+        // Persist the command stem + wildcard (e.g. `grep *`, `git diff *`) for
+        // each "ask" segment. This matches the default-rules convention (`grep *`,
+        // `git diff *`) without being overly broad (`git *` would allow ALL git
+        // subcommands). The full-resolved-command pattern is also returned for
+        // the `persistWrite` audit trail.
+        appendStemsToAllowList(askStems, ctx);
         return {
             allow: true,
             persistWrite: { level: mode, action: "allow", pattern: resolvedCommand },
@@ -2459,29 +2911,38 @@ function buildBashResult(text, isError) {
  * 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);
+        // (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);
+            return buildBashResult(stderr && stderr.length > 0 ? `${stdout}${stdout ? "\n" : ""}${stderr}` : stdout, false);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return buildBashResult(`BLOCKED: shell exec failed: ${message}`, true);
+        }
     }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return buildBashResult(`BLOCKED: shell exec failed: ${message}`, true);
+    finally {
+        // FLOW-12 Step 8 clearance: after any compound execution completes,
+        // unconditionally clear the Allow All Once flag so it does not persist
+        // across separate bash tool invocations. The outer try/finally guarantees
+        // this runs even if runPermissionGate throws unexpectedly, making the
+        // safety contract unbreakable (FLOW-12 Step 8, FLOW-08 Step 5).
+        resetAllowAllOnce();
     }
 }
 /**