@zeldrisho/pi-gate 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-10-25
+
+### Changed
+
+- Create starter configuration when a session starts rather than when the extension is loaded.
+
+### Fixed
+
+- Cancel active approval dialogs and reject queued calls during shutdown, reload, and session replacement.
+
+## [0.7.0] - 2026-10-24
+
+### Changed
+
+- Apply `gate.json` edits to the next gated call without reloading Pi.
+- Show one approval dialog at a time. Approvals apply only to the current call; persistent exceptions remain in `gate.json`.
+
+### Fixed
+
+- Avoid unnecessary approvals for literal `echo`/`printf` output, comments, and partial command names such as `git checkout-index`, while retaining conservative checks for complex shell syntax.
+- Reject pending approvals if the call is canceled, the session changes, or the rules change.
+- Correct rule-precedence guidance shown by editors for `gate.json`.
+
 ## [0.6.1] - 2026-10-21
 
 ### Changed
@@ -82,7 +105,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - support `prompt`, `block`, and `allow` actions, with longest-pattern-wins resolution
 - block rather than auto-approve in non-UI modes
 
-[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.6.1...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.7.1...HEAD
+[0.7.1]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.7.0...pi-gate-v0.7.1
+[0.7.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.6.1...pi-gate-v0.7.0
 [0.6.1]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.6.0...pi-gate-v0.6.1
 [0.6.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.5.0...pi-gate-v0.6.0
 [0.5.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.1...pi-gate-v0.5.0

package/README.md

@@ -15,9 +15,7 @@ Use `pi config` to enable or disable this extension interactively. Run `pi list`
 
 ## Configure
 
-The extension reads `~/.pi/agent/gate.json`, falling back to legacy `~/.pi/agent/pi-gate.json` only when `gate.json` is absent. Set `PI_CODING_AGENT_DIR` to use a different configuration directory. If both files exist, only `gate.json` is used—even if it is invalid. To migrate, rename `pi-gate.json` to `gate.json` and run `/reload`; existing files are never automatically renamed, merged, or overwritten.
-
-On first load, if neither file exists, the extension creates `gate.json` with starter rules and a 30-second prompt timeout. If no configuration can be created yet, pi-gate warns at session start and allows commands until the file is created. If an existing configuration cannot be read or parsed, pi-gate warns and prompts for every command until it is fixed. The published package includes [`config.schema.json`](config.schema.json); use this schema URL for editor completion:
+Edit `~/.pi/agent/gate.json` to choose which commands need approval. The extension creates this file with starter rules when the first session starts. Changes apply before the next gated call, without restarting Pi. Add the optional `$schema` below for editor completion and validation:
 
 ```json
 {
@@ -32,23 +30,34 @@ On first load, if neither file exists, the extension creates `gate.json` with st
 }
 ```
 
-Rules use substring matching and have one of three actions:
+Rules match command text and have one of three actions:
 
 - `prompt`: ask the user to allow or deny;
 - `block`: deny without asking;
 - `allow`: explicitly permit matches fully contained within its matching text.
 
-Empty or over-1,024-character patterns are ignored, at most 1,000 valid rules are loaded, and commands with no match are allowed. Matching is case-insensitive and collapses whitespace runs. An `allow` suppresses only prompt/block matches fully inside its matching span; otherwise any surviving `block` wins over `prompt`. `promptTimeoutMs` defaults to 30 s (maximum one day); a timeout counts as a denial and ends the turn, so raise it for attended sessions. Run `/reload` after editing.
+For simple commands, matching is case-insensitive, treats runs of whitespace as a single space, and matches complete words: `git checkout` does not match `git checkout-index`. Restrictive flag and numeric patterns retain prefix coverage, so `rm -rf` still gates `rm -rfv` and `chmod 777` still gates `chmod 7777`.
+
+Literal arguments to `echo` and `printf`, and shell comments, do not trigger unrelated rules: `echo sudo` does not match `sudo`. Explicit output rules such as `echo sudo` still work. An `allow` suppresses only prompt/block matches fully inside its matching text in the same simple command; otherwise any remaining `block` wins over `prompt`. Commands with no match are allowed. Patterns must contain 1–1,024 characters; at most 1,000 valid rules are loaded.
+
+pi-gate is a guard rail, not a sandbox. Complex shell syntax, pipelines, redirects, substitutions, script arguments, or rules containing shell syntax use conservative substring matching and can still prompt on literal text. Generated commands, flag-order variants, and commands run through other tools are not fully understood; keep `allow` patterns specific. Bash path checks remain textual, so a separate earlier `cd ~/.pi/agent` followed by `echo x > gate.json` may not be recognized.
+
+## Usage
+
+The built-in `bash` tool is gated, and `write`/`edit` calls targeting the gate config require approval. Prompt dialogs offer `Allow` and `Deny`; approvals are never remembered. To stop repeated prompts, add a specific `allow` rule to `gate.json`.
 
-pi-gate is a guard rail, not a sandbox. Substring matching cannot see flag-order variants, `$(…)`, or commands run through other tools; keep `allow` patterns specific. Bash path checks are textual, so a separate earlier `cd ~/.pi/agent` followed by `echo x > gate.json` may not be recognized.
+Approval dialogs are serialized for concurrent tool calls; cancellation, shutdown, reload, session replacement, or a policy change while a dialog is open denies the pending call. Calls queued before shutdown or session replacement are also denied.
 
-## Behavior
+Long commands are truncated in approval dialogs, but an approved command executes in full. Denied, dismissed, blocked, and timed-out calls stop the turn; other allowed calls in a parallel batch may still run. In non-interactive modes (`-p`, JSON), commands requiring approval are denied.
 
-The built-in `bash` tool is gated, and `write`/`edit` calls targeting the gate config require approval. Prompt dialogs offer `Allow` and `Deny`, escape terminal controls, and show at most 2,000 command characters and 20 lines; an allowed command executes in full and unchanged. Blocked, denied, dismissed, and timed-out calls request early termination. A parallel batch continues when it contains allowed calls. In non-interactive modes (`-p`, JSON), prompts and blocks deny and request termination.
+In Herdr-managed panes, install Herdr's Pi integration with `herdr integration install pi` to report pending approvals as `blocked`. Herdr is optional.
 
-The agent receives normal bash output after approval, or a bounded error naming the matched rule after denial or blocking. Dialogs and choices are not sent directly to the agent. RPC hosts use their native selection dialog.
+## Configuration notes
 
-When running in a Herdr-managed TUI pane, pi-gate can report an active approval prompt as `blocked` in Herdr. This is optional: pi-gate works normally without Herdr, and reporting requires Herdr's Pi integration (`herdr integration install pi`). If Herdr or that integration is unavailable, the report is simply ignored.
+- `promptTimeoutMs` defaults to 30 seconds and accepts up to one day. Increase it if you need more time to approve calls.
+- Set `PI_CODING_AGENT_DIR` if your Pi configuration lives outside `~/.pi/agent`.
+- Legacy `pi-gate.json` is used only when `gate.json` is absent. To migrate, rename it to `gate.json`; existing files are never overwritten automatically.
+- An unreadable or invalid configuration causes every command to require approval until fixed. If no file exists and one cannot be created, pi-gate warns and allows commands until you create it.
 
 ## Uninstall
 

package/config.schema.json

@@ -21,7 +21,7 @@
     },
     "operations": {
       "type": "object",
-      "description": "Command substring patterns mapped to actions. When multiple patterns match, the longest wins.",
+      "description": "Case-insensitive command patterns. Simple commands use word matching and ignore literal echo/printf arguments; complex syntax uses substring matching. Contained allow matches suppress restrictions; remaining blocks win.",
       "maxProperties": 1000,
       "propertyNames": {
         "minLength": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "Pi extension that gates bash commands and protects its configuration from tool edits",
   "keywords": [
     "command-blocking",
@@ -32,7 +32,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "typebox": "^1.4.2",
     "typescript": "^7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
     "vite-plus": "1.3.0"

package/src/index.ts

@@ -7,18 +7,19 @@
  *
  * Configuration file: `~/.pi/agent/gate.json` (legacy fallback: `pi-gate.json`)
  *
- * The configuration has an `operations` section, which maps a substring
+ * The configuration has an `operations` section, which maps a command-text
  * pattern to one of three actions, and an optional `promptTimeoutMs` setting:
  *
  * - `prompt` - ask the user to allow or deny the command
  * - `block`  - deny the command without asking
  * - `allow`  - explicitly allow (use to carve out an exception)
  *
- * Matching is case-insensitive and whitespace-normalized. An allow occurrence
- * suppresses only restrictive occurrences fully contained within its span;
- * surviving blocks take priority over prompts.
+ * Simple commands match whole words without treating literal echo/printf data
+ * as commands; uncertain syntax retains conservative substring matching.
+ * Matching is case-insensitive and whitespace-normalized. Allow occurrences
+ * suppress contained restrictions in the same command; surviving blocks win.
  *
- * On first run, a configuration with the default prompt timeout and starter
+ * On first session start, a configuration with the default prompt timeout and starter
  * operation rules is written to `~/.pi/agent/gate.json` when neither file exists.
  *
  * Non-UI modes (print, JSON) never auto-approve. A `prompt` or `block` rule
@@ -27,7 +28,11 @@
  * indefinitely.
  */
 
-import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+  type ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
 import { configPath, ensureConfig, loadConfigResult } from "./config";
 import {
   bashTouchesConfig,
@@ -105,15 +110,46 @@ export {
   highlightRuleForDisplay,
 } from "./display";
 
-/** Gate the built-in `bash` tool against the user-provided rules. */
+/**
+ * Gates `bash` calls against user rules and requires approval for protected
+ * configuration writes and edits. Attempts to create a starter configuration
+ * at session start if absent.
+ * Reloads rules before gating and after each prompt; approvals apply per call.
+ * Dialogs are serialized. Cancellation, shutdown, and session replacement deny
+ * active and queued gated calls; policy changes invalidate an active approval.
+ * UI failures reject the affected tool call.
+ */
 export default function piGate(pi: ExtensionAPI): void {
-  ensureConfig();
   let loadResult = loadConfigResult();
-  const { config } = loadResult;
+  let session = new AbortController();
+  let policy = JSON.stringify(loadResult);
+  let revision = 0;
+  let pending = Promise.resolve();
+
+  /** Reloads policy and invalidates active approvals when its parsed value or load status changes. */
+  const refreshConfig = () => {
+    loadResult = loadConfigResult();
+    const current = JSON.stringify(loadResult);
+
+    if (current !== policy) {
+      revision += 1;
+      policy = current;
+    }
+  };
+
+  pi.on("session_shutdown", () => {
+    session.abort();
+    revision += 1;
+  });
 
   pi.on("session_start", (_event, ctx) => {
+    session.abort();
+    session = new AbortController();
+    revision += 1;
+    ensureConfig();
+    refreshConfig();
     const path = configPath();
-    const ruleCount = Object.keys(config.operations).length;
+    const ruleCount = Object.keys(loadResult.config.operations).length;
 
     if (loadResult.status === "loaded" && ruleCount === 0) {
       ctx.ui.notify(
@@ -133,89 +169,128 @@ export default function piGate(pi: ExtensionAPI): void {
     }
   });
 
-  pi.on("tool_call", async (event, ctx) => {
-    let command: string;
-    let configChange = false;
-
-    if (event.toolName === "bash") {
-      if (!isToolCallEventType("bash", event)) return undefined;
-      command = event.input.command;
-      configChange = bashTouchesConfig(command);
-    } else if (isToolCallEventType("write", event)) {
-      if (!isProtectedConfigPath(event.input.path)) return undefined;
-      command = event.input.path;
-      configChange = true;
-    } else if (isToolCallEventType("edit", event)) {
-      if (!isProtectedConfigPath(event.input.path)) return undefined;
-      command = event.input.path;
-      configChange = true;
-    } else {
-      return undefined;
-    }
+  pi.on("tool_call", (event, ctx) => {
+    // Capture ownership before queueing so old calls cannot enter a replacement session.
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, session.signal]) : session.signal;
 
-    if (loadResult.status === "failed") loadResult = loadConfigResult();
+    // Pi can dispatch sibling tools concurrently; never overlap approval dialogs.
+    /**
+     * Returns a terminating block result for denied calls, or undefined to allow;
+     * UI errors propagate.
+     */
+    const run = async (): Promise<ToolCallEventResult | undefined> => {
+      let command: string;
+      let configChange = false;
 
-    const match = configChange
-      ? { pattern: "gate config change requires approval", action: "prompt" as const }
-      : loadResult.status === "failed"
-        ? { pattern: "configuration unavailable", action: "prompt" as const }
-        : resolveRule(command, loadResult.config.operations);
+      if (event.toolName === "bash") {
+        if (!isToolCallEventType("bash", event)) return undefined;
+        command = event.input.command;
+        configChange = bashTouchesConfig(command);
+      } else if (isToolCallEventType("write", event)) {
+        if (!isProtectedConfigPath(event.input.path)) return undefined;
+        command = event.input.path;
+        configChange = true;
+      } else if (isToolCallEventType("edit", event)) {
+        if (!isProtectedConfigPath(event.input.path)) return undefined;
+        command = event.input.path;
+        configChange = true;
+      } else {
+        return undefined;
+      }
 
-    if (match === null || match.action === "allow") return undefined;
-    const rule = configChange ? CONFIG_CHANGE_REASON : formatRule(match);
+      if (signal.aborted) {
+        return {
+          block: true,
+          reason: "pi-gate: approval cancelled; command not run.",
+          terminate: true,
+        };
+      }
 
-    if (match.action === "block") {
-      const reason = `pi-gate: blocked by rule "${reasonRuleName(match.pattern)}". Do not retry or use equivalent commands; ask the user.`;
+      refreshConfig();
 
-      if (ctx.hasUI) ctx.ui.notify(reason, "warning");
+      const match = configChange
+        ? { pattern: "gate config change requires approval", action: "prompt" as const }
+        : loadResult.status === "failed"
+          ? { pattern: "configuration unavailable", action: "prompt" as const }
+          : resolveRule(command, loadResult.config.operations);
 
-      return { block: true, reason, terminate: true };
-    }
+      if (match === null || match.action === "allow") return undefined;
+      const rule = configChange ? CONFIG_CHANGE_REASON : formatRule(match);
 
-    if (!ctx.hasUI) {
-      return {
-        block: true,
-        reason: configChange
-          ? CONFIG_CHANGE_REASON
-          : `pi-gate: rule "${reasonRuleName(match.pattern)}" needs approval but no UI is available. Do not retry; ask the user.`,
-        terminate: true,
-      };
-    }
+      if (match.action === "block") {
+        const reason = `pi-gate: blocked by rule "${reasonRuleName(match.pattern)}". Do not retry or use equivalent commands; ask the user.`;
 
-    reportHerdrBlocked(pi, ctx, true);
-    let choice: string | undefined;
-    let timedOut = false;
-    const timeoutMs = loadResult.config.promptTimeoutMs;
-
-    const promptCommand = configChange
-      ? `  ${formatCommandForDisplay(command)}`
-      : formatPromptCommand(command, match.pattern);
-
-    try {
-      const promptStartedAt = Date.now();
-      choice = await ctx.ui.select(
-        `pi-gate: allow this command?\n\n${promptCommand}\n\nMatched rule: ${rule}${configChange ? "" : "\nMatched command text is wrapped in »…«"}`,
-        ["Allow", "Deny"],
-        { timeout: timeoutMs },
-      );
-      // Pi returns undefined for both dismissal and timeout; elapsed time separates the timeout case.
-      timedOut = choice === undefined && Date.now() - promptStartedAt >= timeoutMs;
-    } finally {
-      reportHerdrBlocked(pi, ctx, false);
-    }
+        if (ctx.hasUI) ctx.ui.notify(reason, "warning");
+
+        return { block: true, reason, terminate: true };
+      }
 
-    if (choice !== "Allow") {
-      return {
-        block: true,
-        reason: timedOut
-          ? timeoutReason(match.pattern, timeoutMs)
-          : configChange
+      if (!ctx.hasUI) {
+        return {
+          block: true,
+          reason: configChange
             ? CONFIG_CHANGE_REASON
-            : `pi-gate: denied by rule "${reasonRuleName(match.pattern)}". Do not retry or use equivalent commands; ask the user.`,
-        terminate: true,
-      };
-    }
+            : `pi-gate: rule "${reasonRuleName(match.pattern)}" needs approval but no UI is available. Do not retry; ask the user.`,
+          terminate: true,
+        };
+      }
+
+      const promptRevision = revision;
+
+      reportHerdrBlocked(pi, ctx, true);
+      let choice: string | undefined;
+      let timedOut = false;
+      const timeoutMs = loadResult.config.promptTimeoutMs;
+
+      const promptCommand = configChange
+        ? `  ${formatCommandForDisplay(command)}`
+        : formatPromptCommand(command, match.pattern);
+
+      try {
+        const promptStartedAt = Date.now();
+        choice = await ctx.ui.select(
+          `pi-gate: allow this command?\n\n${promptCommand}\n\nMatched rule: ${rule}${configChange ? "" : "\nMatched command text is wrapped in »…«"}`,
+          ["Allow", "Deny"],
+          { timeout: timeoutMs, signal },
+        );
+        // Pi returns undefined for both dismissal and timeout; elapsed time separates the timeout case.
+        timedOut = choice === undefined && Date.now() - promptStartedAt >= timeoutMs;
+      } finally {
+        reportHerdrBlocked(pi, ctx, false);
+      }
+
+      refreshConfig();
+
+      if (signal.aborted || revision !== promptRevision) {
+        return {
+          block: true,
+          reason:
+            "pi-gate: approval cancelled or policy changed; command not run. Ask the user whether to retry.",
+          terminate: true,
+        };
+      }
+
+      if (choice !== "Allow") {
+        return {
+          block: true,
+          reason: timedOut
+            ? timeoutReason(match.pattern, timeoutMs)
+            : configChange
+              ? CONFIG_CHANGE_REASON
+              : `pi-gate: denied by rule "${reasonRuleName(match.pattern)}". Do not retry or use equivalent commands; ask the user.`,
+          terminate: true,
+        };
+      }
+
+      return undefined;
+    };
+
+    const result = pending.then(run);
+    pending = result.then(
+      () => undefined,
+      () => undefined,
+    );
 
-    return undefined;
+    return result;
   });
 }

package/src/literal-commands.ts

@@ -0,0 +1,108 @@
+/** A simple command whose words contain no shell expansion or evaluation syntax. */
+export interface LiteralCommand {
+  text: string;
+  literalOutput: boolean;
+}
+
+const MAX_LITERAL_COMMAND_CHARACTERS = 65_536;
+
+/**
+ * Recognizes only literal words, quotes, comments, and command separators.
+ * Unsupported syntax returns undefined for the entire input: callers must use
+ * conservative text matching, not treat an unrecognized command as safe.
+ * This does not expand variables, execute commands, or attempt full Bash parsing.
+ * Returned text joins recognized words with spaces after quote and escape
+ * handling; comments and separators are omitted. Empty or comment-only input returns an empty list.
+ * Inputs longer than 65,536 UTF-16 code units also return undefined.
+ */
+export function literalCommands(command: string): LiteralCommand[] | undefined {
+  if (command.length > MAX_LITERAL_COMMAND_CHARACTERS) return undefined;
+
+  const commands: LiteralCommand[] = [];
+  let words: string[] = [];
+  let word = "";
+  let active = false;
+  let quote: "'" | '"' | undefined;
+  let opaque = false;
+
+  const finishWord = () => {
+    if (!active) return;
+    words.push(word);
+    word = "";
+    active = false;
+  };
+
+  const finishCommand = () => {
+    finishWord();
+
+    if (words.length === 0) return;
+    const literalOutput = words[0] === "echo" || words[0] === "printf";
+
+    // Other programs may interpret quoted arguments as scripts. Do not discard
+    // shell-looking text passed to bash -c, eval, Python, or other interpreters.
+    if (!literalOutput && words.some((value) => /[\s$`(){}<>;&|*?[\]~!]/u.test(value))) {
+      opaque = true;
+    }
+
+    commands.push({ text: words.join(" "), literalOutput });
+    words = [];
+  };
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+
+    if (quote === "'") {
+      if (char === "'") quote = undefined;
+      else word += char;
+      continue;
+    }
+
+    if (char === "\\") {
+      const next = command[index + 1];
+
+      // Continued lines and trailing escapes need the conservative matcher.
+      if (next === undefined || next === "\n" || next === "\r") return undefined;
+
+      // Inside double quotes, only these characters lose their backslash.
+      if (quote === '"' && !'"\\$`'.includes(next)) word += "\\";
+      word += next;
+      active = true;
+      index += 1;
+      continue;
+    }
+
+    if (quote === '"') {
+      if (char === '"') quote = undefined;
+      else if (char === "$" || char === "`") return undefined;
+      else word += char;
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      active = true;
+    } else if (char === "#" && !active) {
+      while (index < command.length && command[index] !== "\n") index += 1;
+      finishCommand();
+    } else if (char === "\n" || char === ";" || char === "&" || char === "|") {
+      // Printed text can become executable input down a pipeline.
+      if (char === "|" && command[index + 1] !== "|") return undefined;
+      finishCommand();
+
+      if ((char === "&" || char === "|") && command[index + 1] === char) index += 1;
+    } else if (/\s/u.test(char ?? "")) {
+      finishWord();
+    } else if ("$`(){}<>*?[]~!".includes(char ?? "")) {
+      // Expansions, grouping, redirects, and globs are not parsed.
+      return undefined;
+    } else {
+      word += char;
+      active = true;
+    }
+  }
+
+  if (quote !== undefined) return undefined;
+  finishCommand();
+
+  return opaque ? undefined : commands;
+}

package/src/rules.ts

@@ -1,4 +1,5 @@
 import type { Action } from "./config";
+import { literalCommands } from "./literal-commands";
 
 export interface RuleMatch {
   pattern: string;
@@ -9,6 +10,14 @@ interface RuleOccurrence extends RuleMatch {
   start: number;
   end: number;
   normalizedLength: number;
+  scope: number;
+}
+
+interface RuleText {
+  text: string;
+  scope: number;
+  wholeWords: boolean;
+  literalOutput: boolean;
 }
 
 /** Normalize matching text while leaving the original command untouched for display/execution. */
@@ -16,20 +25,42 @@ export function normalizeMatchText(text: string): string {
   return text.toLowerCase().replace(/\s+/gu, " ");
 }
 
-function findOccurrences(text: string, pattern: string, rule: RuleMatch): RuleOccurrence[] {
+/**
+ * Finds overlapping spans of a nonempty, normalized pattern in normalized text,
+ * applying the context's boundaries for words and literal output and retaining its scope.
+ */
+function findOccurrences(context: RuleText, pattern: string, rule: RuleMatch): RuleOccurrence[] {
   const occurrences: RuleOccurrence[] = [];
+  const { text } = context;
   let offset = 0;
 
   while (offset <= text.length - pattern.length) {
     const start = text.indexOf(pattern, offset);
 
     if (start === -1) break;
-    occurrences.push({
-      ...rule,
-      start,
-      end: start + pattern.length,
-      normalizedLength: pattern.length,
-    });
+    const end = start + pattern.length;
+    const lastWord = pattern.slice(pattern.lastIndexOf(" ") + 1);
+
+    // Do not silently stop gating combined flags (-rfv) or extended modes
+    // (7777). Allow exceptions still require the complete final word.
+    const restrictivePrefix =
+      rule.action !== "allow" && (lastWord.startsWith("-") || /^\d+$/u.test(lastWord));
+
+    const bounded =
+      !context.wholeWords ||
+      ((start === 0 || text[start - 1] === " " || text[start - 1] === "/") &&
+        (end === text.length || text[end] === " " || restrictivePrefix));
+
+    if (bounded && (!context.literalOutput || start === 0)) {
+      occurrences.push({
+        ...rule,
+        start,
+        end,
+        scope: context.scope,
+        normalizedLength: pattern.length,
+      });
+    }
+
     // Advance one code unit so overlapping occurrences are retained.
     offset = start + 1;
   }
@@ -38,25 +69,46 @@ function findOccurrences(text: string, pattern: string, rule: RuleMatch): RuleOc
 }
 
 /**
- * Resolves all matching spans. An allow only suppresses a prompt/block occurrence
- * when that allow occurrence fully contains it. A surviving block takes priority
- * over prompt; the longest pattern for the winning action is reported.
+ * Matches whole words in recognized literal commands, excluding data arguments
+ * to echo/printf. Restrictive final flag or numeric words also match prefixes.
+ * Complex syntax or patterns retain conservative text matching.
+ * Allows suppress only contained restrictions in the same command; surviving
+ * blocks take priority, with the longest pattern reported for the winning action.
+ * Returns null when no rule matches. Considers at most 1,000 rules, skipping
+ * empty patterns and patterns longer than 1,024 UTF-16 code units.
  */
 export function resolveRule(command: string, rules: Record<string, Action>): RuleMatch | null {
-  const normalizedCommand = normalizeMatchText(command);
-  const occurrences: RuleOccurrence[] = [];
-
-  let acceptedRuleCount = 0;
+  const acceptedRules: RuleMatch[] = [];
 
   for (const [pattern, action] of Object.entries(rules)) {
-    if (acceptedRuleCount >= 1_000) break;
+    if (acceptedRules.length >= 1_000) break;
 
     if (pattern.length === 0 || pattern.length > 1_024) continue;
-    const normalizedPattern = normalizeMatchText(pattern);
+    acceptedRules.push({ pattern, action });
+  }
+
+  // Shell syntax in a rule keeps its existing textual meaning.
+  const simplePatterns = acceptedRules.every(({ pattern }) =>
+    /^[\p{L}\p{N}_./:@%+=,-]+(?: [\p{L}\p{N}_./:@%+=,-]+)*$/u.test(normalizeMatchText(pattern)),
+  );
+
+  const literal = simplePatterns ? literalCommands(command) : undefined;
+
+  const contexts: RuleText[] = literal
+    ? literal.map((entry, scope) => ({
+        ...entry,
+        text: normalizeMatchText(entry.text),
+        scope,
+        wholeWords: true,
+      }))
+    : [{ text: normalizeMatchText(command), scope: 0, wholeWords: false, literalOutput: false }];
+
+  const occurrences: RuleOccurrence[] = [];
+
+  for (const rule of acceptedRules) {
+    const pattern = normalizeMatchText(rule.pattern);
 
-    if (!normalizedPattern) continue;
-    occurrences.push(...findOccurrences(normalizedCommand, normalizedPattern, { pattern, action }));
-    acceptedRuleCount += 1;
+    for (const context of contexts) occurrences.push(...findOccurrences(context, pattern, rule));
   }
 
   const allows = occurrences.filter((occurrence) => occurrence.action === "allow");
@@ -64,7 +116,12 @@ export function resolveRule(command: string, rules: Record<string, Action>): Rul
   const surviving = occurrences.filter(
     (occurrence) =>
       occurrence.action === "allow" ||
-      !allows.some((allow) => allow.start <= occurrence.start && allow.end >= occurrence.end),
+      !allows.some(
+        (allow) =>
+          allow.scope === occurrence.scope &&
+          allow.start <= occurrence.start &&
+          allow.end >= occurrence.end,
+      ),
   );
 
   const action: Action | null = surviving.some((occurrence) => occurrence.action === "block")