@zeldrisho/pi-gate 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-01
+
+### Changed
+
+- Match bash config protection against resolved config paths instead of bare filenames, and shorten denial reasons while retaining the matched rule.
+- Give prompt timeouts a distinct denial reason that includes the configured timeout and asks whether to retry.
+- Normalize rule matching and require allow spans to contain the matches they suppress; compound commands previously allowed by a longer allow rule can now prompt or block.
+- Prompt before bash commands and write/edit calls that target gate configuration files.
+- Show the number of hidden characters when command text is truncated in a prompt.
+
+### Security
+
+- Escape terminal controls and bound config paths shown in approval prompts.
+
+## [0.5.0] - 2026-09-24
+
+### Changed
+
+- Use `gate.json` as the default configuration filename, retaining `pi-gate.json` as a legacy fallback only when `gate.json` is absent; existing files are never automatically renamed or overwritten.
+
 ## [0.4.1] - 2026-09-17
 
 ### Security
@@ -56,7 +76,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.4.1...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.6.0...HEAD
+[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
 [0.4.1]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.0...pi-gate-v0.4.1
 [0.4.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.3.0...pi-gate-v0.4.0
 [0.3.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.2.0...pi-gate-v0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @zeldrisho/pi-gate
 
-Pi extension that blocks or confirms `bash` tool calls using a user-provided JSON configuration.
+Pi extension that blocks or confirms `bash` tool calls and protects its configuration from `write` and `edit` calls.
 
 ## Install
 
@@ -12,7 +12,9 @@ pi install -l npm:@zeldrisho/pi-gate
 
 ## Configure
 
-On first load, the extension creates `~/.pi/agent/pi-gate.json` with starter rules and a 30-second prompt timeout. Existing files are never overwritten. 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:
+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:
 
 ```json
 {
@@ -31,16 +33,20 @@ Rules use substring matching and have one of three actions:
 
 - `prompt`: ask the user to allow or deny;
 - `block`: deny without asking;
-- `allow`: explicitly permit an exception to a broader match.
+- `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.
 
-Empty or over-1,024-character patterns are ignored, at most 1,000 valid rules are loaded, and commands with no match are allowed. The longest matching pattern wins. `promptTimeoutMs` defaults to 30 seconds and is capped at one day. Run `/reload` after editing.
+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.
 
 ## Behavior
 
-Only the built-in `bash` tool is gated. 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.
+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.
 
 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.
 
+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.
+
 ## Uninstall
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
   "keywords": [
     "command-blocking",
@@ -32,10 +32,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.99.1",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
-    "vite-plus": "0.3.2"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
+    "vite-plus": "1.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/src/config-protection.ts

@@ -0,0 +1,133 @@
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+
+export const CONFIG_CHANGE_REASON = "pi-gate: gate config change requires approval";
+
+const CONFIG_NAMES = ["gate.json", "pi-gate.json"] as const;
+
+/** Returns the configured agent directory, defaulting to ~/.pi/agent. */
+function configDirectory(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+/** Resolves symlinks in the nearest existing ancestor and preserves any missing path suffix. */
+function canonicalizeWithExistingParent(path: string): string {
+  const absolute = resolve(path);
+
+  if (existsSync(absolute)) return realpathSync(absolute);
+
+  const tail: string[] = [];
+  let parent = absolute;
+
+  while (!existsSync(parent)) {
+    const next = dirname(parent);
+
+    if (next === parent) return absolute;
+    tail.unshift(basename(parent));
+    parent = next;
+  }
+
+  return resolve(realpathSync(parent), ...tail);
+}
+
+/** Returns canonical paths for both the current and legacy gate configuration files. */
+export function protectedConfigPaths(): string[] {
+  const directory = configDirectory();
+
+  return CONFIG_NAMES.map((name) => canonicalizeWithExistingParent(join(directory, name)));
+}
+
+/** Expands a leading ~ or ~/ using the current user's home directory. */
+function expandHome(path: string): string {
+  if (path === "~") return homedir();
+
+  if (path.startsWith("~/")) return join(homedir(), path.slice(2));
+
+  return path;
+}
+
+/**
+ * Checks whether a path targets either gate configuration file after home expansion
+ * and symlink resolution. Relative paths use the process working directory.
+ */
+export function isProtectedConfigPath(inputPath: string): boolean {
+  if (inputPath.length === 0) return false;
+  const expanded = expandHome(inputPath);
+
+  const candidate = canonicalizeWithExistingParent(
+    isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded),
+  );
+
+  return protectedConfigPaths().includes(candidate);
+}
+
+/** Returns a tilde-relative path, or undefined when the path is outside the home directory. */
+function homeForm(path: string): string | undefined {
+  const home = resolve(homedir());
+  const absolute = resolve(path);
+
+  if (absolute === home) return "~";
+
+  if (absolute.startsWith(`${home}/`)) return `~/${absolute.slice(home.length + 1)}`;
+
+  return undefined;
+}
+
+/** Lists unique canonical, configured, tilde, and applicable environment-variable file paths. */
+function configPathForms(name: (typeof CONFIG_NAMES)[number], canonicalPath: string): string[] {
+  const configuredDirectory = configDirectory();
+  const logicalPath = resolve(configuredDirectory, name);
+  const envDirectory = process.env.PI_CODING_AGENT_DIR;
+  const forms = [canonicalPath, logicalPath];
+  const homeForms = [homeForm(canonicalPath), homeForm(logicalPath)];
+  forms.push(...homeForms.filter((form): form is string => form !== undefined));
+
+  if (envDirectory !== undefined) {
+    forms.push(`$PI_CODING_AGENT_DIR/${name}`, `\${PI_CODING_AGENT_DIR}/${name}`);
+  }
+
+  return [...new Set(forms)];
+}
+
+/** Lists unique directory spellings used to recognize relative config filenames in commands. */
+function configDirectoryForms(canonicalPath: string): string[] {
+  const configuredDirectory = configDirectory();
+  const logicalDirectory = resolve(configuredDirectory);
+  const canonicalDirectory = dirname(canonicalPath);
+  const forms = [logicalDirectory, canonicalDirectory];
+  const homeForms = [homeForm(logicalDirectory), homeForm(canonicalDirectory)];
+  forms.push(...homeForms.filter((form): form is string => form !== undefined));
+
+  if (process.env.PI_CODING_AGENT_DIR !== undefined) {
+    forms.push("$PI_CODING_AGENT_DIR", "${PI_CODING_AGENT_DIR}");
+  }
+
+  return [...new Set(forms)];
+}
+
+/** Checks for a literal path substring without parsing shell syntax or expanding variables. */
+function commandContainsPath(command: string, path: string): boolean {
+  return command.includes(path);
+}
+
+/**
+ * Detects textual references to gate configuration paths in a shell command.
+ * Bare filenames match only when the same command also names the config directory;
+ * this does not resolve shell expressions or track directory changes across calls.
+ */
+export function bashTouchesConfig(command: string): boolean {
+  const paths = protectedConfigPaths();
+  const pathForms = CONFIG_NAMES.flatMap((name, index) => configPathForms(name, paths[index]!));
+
+  if (pathForms.some((path) => commandContainsPath(command, path))) return true;
+
+  // Relative filenames are guarded only when the command also names the config directory.
+  return CONFIG_NAMES.some((name, index) => {
+    const refersToDirectory = configDirectoryForms(paths[index]!).some((directory) =>
+      commandContainsPath(command, directory),
+    );
+
+    return refersToDirectory && commandContainsPath(command, name);
+  });
+}

package/src/config.ts

@@ -16,7 +16,9 @@ export interface ConfigLoadResult {
   status: ConfigLoadStatus;
 }
 
-const CONFIG_FILE_NAME = "pi-gate.json";
+const CONFIG_FILE_NAME = "gate.json";
+
+const LEGACY_CONFIG_FILE_NAME = "pi-gate.json";
 
 export const CONFIG_SCHEMA_URL =
   "https://raw.githubusercontent.com/zeldrisho/pi-packages/main/packages/pi-gate/config.schema.json";
@@ -54,10 +56,18 @@ function agentDir(): string {
 /**
  * Returns the full path to the pi-gate configuration file.
  *
- * @returns The absolute path to pi-gate.json
+ * Prefers gate.json, falling back to pi-gate.json only when gate.json is absent.
+ *
+ * @returns The selected configuration path, or gate.json for first-run creation
  */
 export function configPath(): string {
-  return join(agentDir(), CONFIG_FILE_NAME);
+  const path = join(agentDir(), CONFIG_FILE_NAME);
+
+  if (existsSync(path)) return path;
+
+  const legacyPath = join(agentDir(), LEGACY_CONFIG_FILE_NAME);
+
+  return existsSync(legacyPath) ? legacyPath : path;
 }
 
 /**

package/src/display.ts

@@ -4,7 +4,8 @@ export const MAX_DISPLAY_COMMAND_CHARACTERS = 2_000;
 
 export const MAX_DISPLAY_COMMAND_LINES = 20;
 
-const DISPLAY_TRUNCATION_MARKER = "\n  … [command display truncated]";
+const DISPLAY_TRUNCATION_MARKER = (hiddenCharacters: number): string =>
+  `\n  … [${hiddenCharacters} more characters hidden]`;
 
 const BIDI_CONTROL_CODE_POINTS = new Set([
   0x061c, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069,
@@ -58,8 +59,10 @@ function renderCommandForDisplay(command: string, pattern?: string): string {
   let lineCount = 1;
   let offset = 0;
 
-  const truncate = (closeActiveRange = activeRange !== undefined): string =>
-    output + (closeActiveRange ? "«" : "") + DISPLAY_TRUNCATION_MARKER;
+  const truncate = (
+    hiddenCharacters: number,
+    closeActiveRange = activeRange !== undefined,
+  ): string => output + (closeActiveRange ? "«" : "") + DISPLAY_TRUNCATION_MARKER(hiddenCharacters);
 
   while (offset < command.length) {
     const rawStart = offset;
@@ -90,12 +93,13 @@ function renderCommandForDisplay(command: string, pattern?: string): string {
     const decorated = `${opensRange ? "»" : ""}${rendered}${closesRange ? "«" : ""}`;
 
     if (rendered === "\n") {
-      if (lineCount >= MAX_DISPLAY_COMMAND_LINES) return truncate(wasInsideRange);
+      if (lineCount >= MAX_DISPLAY_COMMAND_LINES)
+        return truncate(command.length - rawStart, wasInsideRange);
       lineCount += 1;
     }
 
     if (output.length + decorated.length > MAX_DISPLAY_COMMAND_CHARACTERS) {
-      return truncate(wasInsideRange);
+      return truncate(command.length - rawStart, wasInsideRange);
     }
 
     output += decorated;

package/src/index.ts

@@ -1,11 +1,11 @@
 /**
  * pi-gate Extension
  *
- * Intercepts the built-in `bash` tool and gates each command against a
- * user-provided JSON configuration. Without a configuration file, the
+ * Intercepts the built-in `bash` tool and protects the gate configuration
+ * from `write` and `edit` calls. Without a configuration file, the
  * extension creates one with starter rules and a default prompt timeout.
  *
- * Configuration file: `~/.pi/agent/pi-gate.json`
+ * Configuration file: `~/.pi/agent/gate.json` (legacy fallback: `pi-gate.json`)
  *
  * The configuration has an `operations` section, which maps a substring
  * pattern to one of three actions, and an optional `promptTimeoutMs` setting:
@@ -14,11 +14,12 @@
  * - `block`  - deny the command without asking
  * - `allow`  - explicitly allow (use to carve out an exception)
  *
- * When multiple patterns match a command, the longest pattern wins, so a
- * narrow `allow` rule can override a broader `prompt` or `block` rule.
+ * 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.
  *
  * On first run, a configuration with the default prompt timeout and starter
- * operation rules is written to `~/.pi/agent/pi-gate.json`.
+ * 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
  * in non-UI mode always blocks and requests termination of the agent turn.
@@ -28,11 +29,32 @@
 
 import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { configPath, ensureConfig, loadConfigResult } from "./config";
+import {
+  bashTouchesConfig,
+  CONFIG_CHANGE_REASON,
+  isProtectedConfigPath,
+} from "./config-protection";
 import { resolveRule } from "./rules";
-import { formatPromptCommand, formatRule } from "./display";
+import { formatCommandForDisplay, formatPromptCommand, formatRule } from "./display";
 
 const HERDR_BLOCKED_LABEL = "pi-gate: approval required";
 
+const MAX_REASON_RULE_NAME_LENGTH = 27;
+
+/** Escapes a rule pattern for terminal display and bounds its length in denial messages. */
+function reasonRuleName(pattern: string): string {
+  const safePattern = formatCommandForDisplay(pattern);
+
+  return safePattern.length <= MAX_REASON_RULE_NAME_LENGTH
+    ? safePattern
+    : `${safePattern.slice(0, MAX_REASON_RULE_NAME_LENGTH - 1)}…`;
+}
+
+/** Formats an approval timeout with the matched rule, elapsed limit in seconds, and retry guidance. */
+function timeoutReason(pattern: string, timeoutMs: number): string {
+  return `pi-gate: no response to rule "${reasonRuleName(pattern)}" within ${timeoutMs / 1_000}s; command not run. Ask the user whether to retry.`;
+}
+
 function reportHerdrBlocked(pi: ExtensionAPI, ctx: { mode?: string }, active: boolean): void {
   if (
     ctx.mode !== "tui" ||
@@ -119,51 +141,72 @@ export default function piGate(pi: ExtensionAPI): void {
   });
 
   pi.on("tool_call", async (event, ctx) => {
-    if (event.toolName !== "bash") return undefined;
-
-    if (!isToolCallEventType("bash", event)) return undefined;
-    const command = event.input.command;
-
-    if (loadResult.status === "failed") {
-      loadResult = loadConfigResult();
+    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;
     }
 
-    const match =
-      loadResult.status === "failed"
+    if (loadResult.status === "failed") loadResult = loadConfigResult();
+
+    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 (match === null || match.action === "allow") return undefined;
-    const rule = formatRule(match);
+    const rule = configChange ? CONFIG_CHANGE_REASON : formatRule(match);
 
     if (match.action === "block") {
-      const reason = `pi-gate: command blocked by rule ${rule}`;
+      const reason = `pi-gate: blocked by rule "${reasonRuleName(match.pattern)}". Do not retry or use equivalent commands; ask the user.`;
 
-      if (ctx.hasUI) {
-        ctx.ui.notify(reason, "warning");
-      }
+      if (ctx.hasUI) ctx.ui.notify(reason, "warning");
 
       return { block: true, reason, terminate: true };
     }
 
-    // action === "prompt"
     if (!ctx.hasUI) {
       return {
         block: true,
-        reason: `pi-gate: command blocked because rule ${rule} requires a prompt, but no UI is available`,
+        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,
       };
     }
 
     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${formatPromptCommand(command, match.pattern)}\n\nMatched rule: ${rule}\nMatched command text is wrapped in »…«`,
+        `pi-gate: allow this command?\n\n${promptCommand}\n\nMatched rule: ${rule}${configChange ? "" : "\nMatched command text is wrapped in »…«"}`,
         ["Allow", "Deny"],
-        { timeout: loadResult.config.promptTimeoutMs },
+        { 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);
     }
@@ -171,7 +214,11 @@ export default function piGate(pi: ExtensionAPI): void {
     if (choice !== "Allow") {
       return {
         block: true,
-        reason: `pi-gate: command denied, dismissed, or timed out after matching rule ${rule}`,
+        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,
       };
     }

package/src/rules.ts

@@ -5,34 +5,86 @@ export interface RuleMatch {
   action: Action;
 }
 
+interface RuleOccurrence extends RuleMatch {
+  start: number;
+  end: number;
+  normalizedLength: number;
+}
+
+/** Normalize matching text while leaving the original command untouched for display/execution. */
+export function normalizeMatchText(text: string): string {
+  return text.toLowerCase().replace(/\s+/gu, " ");
+}
+
+function findOccurrences(text: string, pattern: string, rule: RuleMatch): RuleOccurrence[] {
+  const occurrences: RuleOccurrence[] = [];
+  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,
+    });
+    // Advance one code unit so overlapping occurrences are retained.
+    offset = start + 1;
+  }
+
+  return occurrences;
+}
+
 /**
- * Resolves the rule that applies to a command against the configured rules.
- *
- * Returns `null` when no rule matches, in which case the caller should let the
- * command through. When multiple rules match, the longest pattern wins so
- * that narrow rules can override broader ones.
- *
- * @param command - The bash command to evaluate against the rules
- * @param rules - A map of pattern strings to actions
- * @returns The matched pattern and action, or `null` if no rule matches
+ * 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.
  */
 export function resolveRule(command: string, rules: Record<string, Action>): RuleMatch | null {
-  let bestPattern: string | null = null;
+  const normalizedCommand = normalizeMatchText(command);
+  const occurrences: RuleOccurrence[] = [];
+
+  let acceptedRuleCount = 0;
+
+  for (const [pattern, action] of Object.entries(rules)) {
+    if (acceptedRuleCount >= 1_000) break;
 
-  for (const pattern of Object.keys(rules)) {
-    if (!command.includes(pattern)) continue;
+    if (pattern.length === 0 || pattern.length > 1_024) continue;
+    const normalizedPattern = normalizeMatchText(pattern);
 
-    if (bestPattern === null || pattern.length > bestPattern.length) {
-      bestPattern = pattern;
-    }
+    if (!normalizedPattern) continue;
+    occurrences.push(...findOccurrences(normalizedCommand, normalizedPattern, { pattern, action }));
+    acceptedRuleCount += 1;
   }
 
-  if (bestPattern === null) return null;
+  const allows = occurrences.filter((occurrence) => occurrence.action === "allow");
+
+  const surviving = occurrences.filter(
+    (occurrence) =>
+      occurrence.action === "allow" ||
+      !allows.some((allow) => allow.start <= occurrence.start && allow.end >= occurrence.end),
+  );
+
+  const action: Action | null = surviving.some((occurrence) => occurrence.action === "block")
+    ? "block"
+    : surviving.some((occurrence) => occurrence.action === "prompt")
+      ? "prompt"
+      : surviving.some((occurrence) => occurrence.action === "allow")
+        ? "allow"
+        : null;
+
+  if (action === null) return null;
+
+  const winner = surviving
+    .filter((occurrence) => occurrence.action === action)
+    .sort((a, b) => b.normalizedLength - a.normalizedLength)[0];
 
-  return { pattern: bestPattern, action: rules[bestPattern] };
+  return winner ? { pattern: winner.pattern, action: winner.action } : null;
 }
 
-/** Returns only the action selected by {@link resolveRule}. */
+/** Returns the selected action, or null when no rule matches. */
 export function resolveAction(command: string, rules: Record<string, Action>): Action | null {
   return resolveRule(command, rules)?.action ?? null;
 }