@zeldrisho/pi-gate 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-09-17
+
+### Security
+
+- prompt for all commands when an existing configuration cannot be read or parsed instead of allowing every command through unblocked
+
+## [0.4.0] - 2026-09-12
+
+### Changed
+
+- report interactive approval prompts to Herdr when running inside a Herdr-managed TUI pane, while remaining a no-op for other users
+
 ## [0.3.0] - 2026-09-07
 
 ### Added
@@ -44,7 +56,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.3.0...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.1...HEAD
+[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
 [0.2.0]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.1.1...pi-gate-v0.2.0
 [0.1.1]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.1.0...pi-gate-v0.1.1

package/README.md

@@ -1,30 +1,18 @@
 # @zeldrisho/pi-gate
 
-Pi extension that blocks or confirms bash tool calls based on a user-provided JSON configuration.
+Pi extension that blocks or confirms `bash` tool calls using a user-provided JSON configuration.
 
 ## Install
 
 ```bash
 pi install npm:@zeldrisho/pi-gate
-```
-
-Install only for the current project:
-
-```bash
+# project-local:
 pi install -l npm:@zeldrisho/pi-gate
 ```
 
 ## Configure
 
-On first load, the extension creates `~/.pi/agent/pi-gate.json` with a default 30-second prompt timeout, starter rules, and a `$schema` reference for editor validation. Existing configuration files are never overwritten.
-
-The published package includes [`config.schema.json`](config.schema.json). New configurations reference its canonical URL automatically; existing configurations can add the same `$schema` property shown below to enable completion and validation in compatible editors.
-
-Edit `~/.pi/agent/pi-gate.json` to customize the rules. `promptTimeoutMs` controls how long a confirmation remains open (30 seconds by default if omitted, with a maximum of one day). Each rule is a substring pattern and one of three actions:
-
-- `prompt` — ask the user to allow or deny the command
-- `block` — deny the command without asking
-- `allow` — explicitly allow an exception to a broader matching rule
+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:
 
 ```json
 {
@@ -34,50 +22,30 @@ Edit `~/.pi/agent/pi-gate.json` to customize the rules. `promptTimeoutMs` contro
     "rm -rf": "prompt",
     "sudo": "prompt",
     "sudo apt update": "allow",
-    "chmod 777": "block",
-    "corepack enable": "block"
+    "chmod 777": "block"
   }
 }
 ```
 
-Patterns use simple substring matching. Empty patterns and patterns longer than 1,024 characters are ignored, and at most 1,000 valid rules are loaded. Commands with no matching rule are allowed automatically. The explicit `allow` action is only needed to carve out an exception: in the starter configuration, `sudo apt update` is allowed even though the broader `sudo` rule prompts. When several patterns match, the longest pattern wins.
+Rules use substring matching and have one of three actions:
 
-After editing, run `/reload` to apply the new rules in the current session.
-
-## Behavior
+- `prompt`: ask the user to allow or deny;
+- `block`: deny without asking;
+- `allow`: explicitly permit an exception to a broader match.
 
-- Only the built-in `bash` tool is gated. Other tools pass through unchanged.
-- `prompt` rules ask the user with a two-button confirmation (`Allow` / `Deny`). The dialog identifies the matched rule, wraps its visible occurrences in `»…«`, and auto-denies after `promptTimeoutMs` instead of waiting indefinitely. Commands are normalized and terminal control characters are escaped for display; prompts show at most 2,000 command characters and 20 lines, but an allowed command always executes in full and unchanged.
-- `block` rules never ask and always deny. The warning identifies the matched rule.
-- `allow` rules are explicit pass-throughs, useful for carving out exceptions.
-- Blocked, denied, dismissed, and timed-out calls request early termination. Pi ends the turn only when every finalized result in the tool-call batch requests termination; a mixed parallel batch containing allowed calls may continue.
-- RPC hosts use their native selection dialog. In non-interactive modes (`-p`, JSON), `prompt` and `block` rules both block and request termination instead of auto-approving.
+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.
 
-### What the agent sees
-
-The confirmation dialog and your choice are not sent directly to the agent.
-
-- If you allow a `prompt` rule, the command runs and the agent receives its normal bash result.
-- If you deny or dismiss a `prompt`, the agent receives an error result naming the matched rule and saying the user denied it.
-- If a `block` rule matches, the agent receives an error result naming that rule.
-- If a `prompt` rule matches without an available UI, the agent receives an error explaining that the matched rule required a prompt.
+## Behavior
 
-For example, a blocked `sudo apt update` call reports:
+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.
 
-```text
-pi-gate: command blocked by rule "sudo": "block"
-```
+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.
 
 ## Uninstall
 
 ```bash
 pi remove npm:@zeldrisho/pi-gate
-```
-
-For a project-local installation:
-
-```bash
-pi remove -l npm:@zeldrisho/pi-gate
+pi remove -l npm:@zeldrisho/pi-gate  # project-local
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
   "keywords": [
     "command-blocking",
@@ -25,9 +25,7 @@
   "files": [
     "src",
     "config.schema.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "CHANGELOG.md"
   ],
   "type": "module",
   "publishConfig": {
@@ -36,8 +34,8 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "typescript": "^7.0.2",
-    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
-    "vite-plus": "0.3.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.2",
+    "vite-plus": "0.3.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/src/config.ts

@@ -0,0 +1,206 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type Action = "prompt" | "block" | "allow";
+
+export interface GateConfig {
+  operations: Record<string, Action>;
+  promptTimeoutMs: number;
+}
+
+export type ConfigLoadStatus = "missing" | "loaded" | "failed";
+
+export interface ConfigLoadResult {
+  config: GateConfig;
+  status: ConfigLoadStatus;
+}
+
+const 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";
+
+const ACTIONS: readonly Action[] = ["prompt", "block", "allow"] as const;
+
+export const DEFAULT_PROMPT_TIMEOUT_MS = 30_000;
+
+export const MAX_RULE_COUNT = 1_000;
+
+export const MAX_RULE_PATTERN_LENGTH = 1_024;
+
+export const MAX_PROMPT_TIMEOUT_MS = 86_400_000;
+
+const DEFAULT_CONFIG: GateConfig = {
+  promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS,
+  operations: {
+    "rm -rf": "prompt",
+    sudo: "prompt",
+    "sudo apt update": "allow",
+    "chmod 777": "block",
+    "corepack enable": "block",
+  },
+};
+
+/**
+ * Returns the directory where pi-gate configuration files are stored.
+ *
+ * @returns The absolute path to the agent configuration directory
+ */
+function agentDir(): string {
+  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+/**
+ * Returns the full path to the pi-gate configuration file.
+ *
+ * @returns The absolute path to pi-gate.json
+ */
+export function configPath(): string {
+  return join(agentDir(), CONFIG_FILE_NAME);
+}
+
+/**
+ * Type guard that checks if an unknown value is a valid Action.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is one of "prompt", "block", or "allow"
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
+function isAction(value: unknown): value is Action {
+  return (
+    typeof value === "string" &&
+    // SAFETY: ACTIONS is the source-of-truth tuple of supported action strings; widening
+    // it to readonly string[] lets Array.prototype.includes perform a runtime check
+    // before the type predicate narrows the value to Action.
+    (ACTIONS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Type guard that checks if an unknown value is a plain JSON object.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a non-null object and not an array
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters, anti-slop/no-unsafe-dictionary-type -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parses the user configuration file. Returns an empty configuration (no
+ * rules) when the file is missing, unreadable, malformed, or fails
+ * validation; an explicit empty `operations` object is also valid.
+ *
+ * Invalid entries are skipped so a single bad rule does not disable the
+ * entire gate; parsing continues for the remaining rules.
+ */
+export function parseConfig(content: string): GateConfig {
+  const rules: Record<string, Action> = {};
+  let acceptedRuleCount = 0;
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
+  }
+
+  if (!isJsonObject(parsed)) {
+    return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
+  }
+
+  const configuredTimeout = parsed["promptTimeoutMs"];
+
+  const promptTimeoutMs =
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validate the optional numeric field at the untrusted JSON boundary before applying range checks
+    typeof configuredTimeout === "number" &&
+    Number.isInteger(configuredTimeout) &&
+    configuredTimeout > 0 &&
+    configuredTimeout <= MAX_PROMPT_TIMEOUT_MS
+      ? configuredTimeout
+      : DEFAULT_PROMPT_TIMEOUT_MS;
+
+  const operations = parsed["operations"];
+
+  if (!isJsonObject(operations)) {
+    return { operations: rules, promptTimeoutMs };
+  }
+
+  for (const [pattern, action] of Object.entries(operations)) {
+    if (acceptedRuleCount >= MAX_RULE_COUNT) break;
+
+    if (pattern.length === 0 || pattern.length > MAX_RULE_PATTERN_LENGTH) continue;
+
+    if (isAction(action)) {
+      rules[pattern] = action;
+      acceptedRuleCount += 1;
+    }
+  }
+
+  return { operations: rules, promptTimeoutMs };
+}
+
+/**
+ * Loads the configuration from disk. Returns an empty configuration when the
+ * file is missing; returns the parsed configuration otherwise.
+ */
+export function loadConfigResult(): ConfigLoadResult {
+  const emptyConfig = { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
+  const path = configPath();
+
+  if (!existsSync(path)) {
+    return { config: emptyConfig, status: "missing" };
+  }
+
+  let content: string;
+
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    return { config: emptyConfig, status: "failed" };
+  }
+
+  try {
+    const parsed: unknown = JSON.parse(content);
+
+    if (!isJsonObject(parsed) || !isJsonObject(parsed["operations"])) {
+      return { config: parseConfig(content), status: "failed" };
+    }
+  } catch {
+    return { config: emptyConfig, status: "failed" };
+  }
+
+  return { config: parseConfig(content), status: "loaded" };
+}
+
+/** Loads the configuration, preserving the historical empty-config fallback. */
+export function loadConfig(): GateConfig {
+  return loadConfigResult().config;
+}
+
+/**
+ * Writes the default configuration on first run. Existing configuration files
+ * are never overwritten.
+ */
+export function ensureConfig(): void {
+  const path = configPath();
+
+  if (existsSync(path)) return;
+
+  try {
+    mkdirSync(agentDir(), { recursive: true });
+  } catch {
+    return;
+  }
+
+  const content = JSON.stringify({ $schema: CONFIG_SCHEMA_URL, ...DEFAULT_CONFIG }, null, 2) + "\n";
+
+  try {
+    writeFileSync(path, content, { encoding: "utf-8", flag: "wx", mode: 0o600 });
+  } catch {
+    // Best-effort: another process may have created it, or the warning banner
+    // will surface that no configuration is active.
+  }
+}

package/src/display.ts

@@ -0,0 +1,144 @@
+import type { RuleMatch } from "./rules";
+
+export const MAX_DISPLAY_COMMAND_CHARACTERS = 2_000;
+
+export const MAX_DISPLAY_COMMAND_LINES = 20;
+
+const DISPLAY_TRUNCATION_MARKER = "\n  … [command display truncated]";
+
+const BIDI_CONTROL_CODE_POINTS = new Set([
+  0x061c, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069,
+]);
+
+/** Converts terminal controls and bidirectional formatting characters to visible escapes. */
+function escapeUnsafeDisplayCharacter(character: string): string {
+  const codePoint = character.codePointAt(0);
+
+  if (codePoint === undefined) return "";
+
+  if (
+    codePoint < 0x20 ||
+    (codePoint >= 0x7f && codePoint <= 0x9f) ||
+    BIDI_CONTROL_CODE_POINTS.has(codePoint)
+  ) {
+    return `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
+  }
+
+  return character;
+}
+
+interface MatchRange {
+  start: number;
+  end: number;
+}
+
+/** Finds non-overlapping raw match ranges before any display escaping occurs. */
+function findMatchRanges(command: string, pattern?: string): MatchRange[] {
+  if (!pattern) return [];
+  const ranges: MatchRange[] = [];
+  let offset = 0;
+
+  while (offset <= command.length - pattern.length) {
+    const start = command.indexOf(pattern, offset);
+
+    if (start === -1) break;
+    ranges.push({ start, end: start + pattern.length });
+    offset = start + pattern.length;
+  }
+
+  return ranges;
+}
+
+/** Produces bounded terminal-safe text, optionally marking raw matched spans. */
+function renderCommandForDisplay(command: string, pattern?: string): string {
+  const ranges = findMatchRanges(command, pattern);
+  let rangeIndex = 0;
+  let activeRange: MatchRange | undefined;
+  let output = "";
+  let lineCount = 1;
+  let offset = 0;
+
+  const truncate = (closeActiveRange = activeRange !== undefined): string =>
+    output + (closeActiveRange ? "«" : "") + DISPLAY_TRUNCATION_MARKER;
+
+  while (offset < command.length) {
+    const rawStart = offset;
+    let rawEnd: number;
+    let rendered: string;
+    const codePoint = command.codePointAt(offset);
+
+    if (codePoint === 0x0d) {
+      rawEnd = offset + (command.codePointAt(offset + 1) === 0x0a ? 2 : 1);
+      rendered = "\n";
+    } else {
+      const character = String.fromCodePoint(codePoint!);
+      rawEnd = offset + character.length;
+      rendered = character === "\n" ? character : escapeUnsafeDisplayCharacter(character);
+    }
+
+    const nextRange = ranges[rangeIndex];
+    const wasInsideRange = activeRange !== undefined;
+
+    const opensRange =
+      activeRange === undefined &&
+      nextRange !== undefined &&
+      nextRange.start < rawEnd &&
+      nextRange.end > rawStart;
+
+    if (opensRange) activeRange = nextRange;
+    const closesRange = activeRange !== undefined && activeRange.end <= rawEnd;
+    const decorated = `${opensRange ? "»" : ""}${rendered}${closesRange ? "«" : ""}`;
+
+    if (rendered === "\n") {
+      if (lineCount >= MAX_DISPLAY_COMMAND_LINES) return truncate(wasInsideRange);
+      lineCount += 1;
+    }
+
+    if (output.length + decorated.length > MAX_DISPLAY_COMMAND_CHARACTERS) {
+      return truncate(wasInsideRange);
+    }
+
+    output += decorated;
+
+    if (closesRange) {
+      activeRange = undefined;
+      rangeIndex += 1;
+    }
+
+    offset = rawEnd;
+  }
+
+  return output;
+}
+
+/**
+ * Produces bounded terminal-safe text for a command without changing the command that is executed.
+ */
+export function formatCommandForDisplay(command: string): string {
+  return renderCommandForDisplay(command);
+}
+
+/** Marks raw matched-rule occurrences while producing terminal-safe command text. */
+export function highlightRuleForDisplay(command: string, pattern: string): string {
+  return renderCommandForDisplay(command, pattern);
+}
+
+/** Indents every line of terminal-safe command text for the confirmation dialog. */
+export function formatPromptCommand(command: string, pattern: string): string {
+  return highlightRuleForDisplay(command, pattern)
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n");
+}
+
+/**
+ * Formats a rule match as a terminal-safe, human-readable string.
+ *
+ * @param match - The rule match to format
+ * @returns A string representation showing the pattern and action
+ */
+export function formatRule(match: RuleMatch): string {
+  return formatCommandForDisplay(
+    `${JSON.stringify(match.pattern)}: ${JSON.stringify(match.action)}`,
+  );
+}

package/src/index.ts

@@ -26,335 +26,74 @@
  * indefinitely.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { configPath, ensureConfig, loadConfigResult } from "./config";
+import { resolveRule } from "./rules";
+import { formatPromptCommand, formatRule } from "./display";
 
-export type Action = "prompt" | "block" | "allow";
+const HERDR_BLOCKED_LABEL = "pi-gate: approval required";
 
-export interface GateConfig {
-  operations: Record<string, Action>;
-  promptTimeoutMs: number;
-}
-
-export interface RuleMatch {
-  pattern: string;
-  action: Action;
-}
-
-const 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";
-const ACTIONS: readonly Action[] = ["prompt", "block", "allow"] as const;
-export const DEFAULT_PROMPT_TIMEOUT_MS = 30_000;
-export const MAX_RULE_COUNT = 1_000;
-export const MAX_RULE_PATTERN_LENGTH = 1_024;
-export const MAX_DISPLAY_COMMAND_CHARACTERS = 2_000;
-export const MAX_DISPLAY_COMMAND_LINES = 20;
-export const MAX_PROMPT_TIMEOUT_MS = 86_400_000;
-const DISPLAY_TRUNCATION_MARKER = "\n  … [command display truncated]";
-const BIDI_CONTROL_CODE_POINTS = new Set([
-  0x061c, 0x200e, 0x200f, 0x202a, 0x202b, 0x202c, 0x202d, 0x202e, 0x2066, 0x2067, 0x2068, 0x2069,
-]);
-
-const DEFAULT_CONFIG: GateConfig = {
-  promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS,
-  operations: {
-    "rm -rf": "prompt",
-    sudo: "prompt",
-    "sudo apt update": "allow",
-    "chmod 777": "block",
-    "corepack enable": "block",
-  },
-};
-
-/**
- * Returns the directory where pi-gate configuration files are stored.
- *
- * @returns The absolute path to the agent configuration directory
- */
-function agentDir(): string {
-  return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
-}
-
-/**
- * Returns the full path to the pi-gate configuration file.
- *
- * @returns The absolute path to pi-gate.json
- */
-function configPath(): string {
-  return join(agentDir(), CONFIG_FILE_NAME);
-}
-
-/**
- * Type guard that checks if an unknown value is a valid Action.
- *
- * @param value - The value to check
- * @returns `true` if the value is one of "prompt", "block", or "allow"
- */
-// oxlint-disable-next-line anti-slop/no-unknown-parameters -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
-function isAction(value: unknown): value is Action {
-  return (
-    typeof value === "string" &&
-    // SAFETY: ACTIONS is the source-of-truth tuple of supported action strings; widening
-    // it to readonly string[] lets Array.prototype.includes perform a runtime check
-    // before the type predicate narrows the value to Action.
-    (ACTIONS as readonly string[]).includes(value)
-  );
-}
-
-/**
- * Type guard that checks if an unknown value is a plain JSON object.
- *
- * @param value - The value to check
- * @returns `true` if the value is a non-null object and not an array
- */
-// oxlint-disable-next-line anti-slop/no-unknown-parameters, anti-slop/no-unsafe-dictionary-type -- type-guard helper intentionally narrows untrusted JSON values at the parse boundary
-function isJsonObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Parses the user configuration file. Returns an empty configuration (no
- * rules) when the file is missing, unreadable, malformed, or fails
- * validation; an explicit empty `operations` object is also valid.
- *
- * Invalid entries are skipped so a single bad rule does not disable the
- * entire gate; parsing continues for the remaining rules.
- */
-export function parseConfig(content: string): GateConfig {
-  const rules: Record<string, Action> = {};
-  let acceptedRuleCount = 0;
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(content);
-  } catch {
-    return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
-  }
-  if (!isJsonObject(parsed)) {
-    return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
-  }
-  const configuredTimeout = parsed["promptTimeoutMs"];
-  const promptTimeoutMs =
-    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validate the optional numeric field at the untrusted JSON boundary before applying range checks
-    typeof configuredTimeout === "number" &&
-    Number.isInteger(configuredTimeout) &&
-    configuredTimeout > 0 &&
-    configuredTimeout <= MAX_PROMPT_TIMEOUT_MS
-      ? configuredTimeout
-      : DEFAULT_PROMPT_TIMEOUT_MS;
-  const operations = parsed["operations"];
-  if (!isJsonObject(operations)) {
-    return { operations: rules, promptTimeoutMs };
-  }
-  for (const [pattern, action] of Object.entries(operations)) {
-    if (acceptedRuleCount >= MAX_RULE_COUNT) break;
-    if (pattern.length === 0 || pattern.length > MAX_RULE_PATTERN_LENGTH) continue;
-    if (isAction(action)) {
-      rules[pattern] = action;
-      acceptedRuleCount += 1;
-    }
-  }
-  return { operations: rules, promptTimeoutMs };
-}
-
-/**
- * Loads the configuration from disk. Returns an empty configuration when the
- * file is missing; returns the parsed configuration otherwise.
- */
-export function loadConfig(): GateConfig {
-  const path = configPath();
-  if (!existsSync(path)) {
-    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
-  }
-  let content: string;
-  try {
-    content = readFileSync(path, "utf-8");
-  } catch {
-    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
-  }
-  return parseConfig(content);
-}
-
-/**
- * Writes the default configuration on first run. Existing configuration files
- * are never overwritten.
- */
-export function ensureConfig(): void {
-  const path = configPath();
-  if (existsSync(path)) return;
-  try {
-    mkdirSync(agentDir(), { recursive: true });
-  } catch {
-    return;
-  }
-  const content = JSON.stringify({ $schema: CONFIG_SCHEMA_URL, ...DEFAULT_CONFIG }, null, 2) + "\n";
-  try {
-    writeFileSync(path, content, { encoding: "utf-8", flag: "wx", mode: 0o600 });
-  } catch {
-    // Best-effort: another process may have created it, or the warning banner
-    // will surface that no configuration is active.
-  }
-}
-
-/**
- * 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
- */
-export function resolveRule(command: string, rules: Record<string, Action>): RuleMatch | null {
-  let bestPattern: string | null = null;
-  for (const pattern of Object.keys(rules)) {
-    if (!command.includes(pattern)) continue;
-    if (bestPattern === null || pattern.length > bestPattern.length) {
-      bestPattern = pattern;
-    }
-  }
-  if (bestPattern === null) return null;
-  return { pattern: bestPattern, action: rules[bestPattern] };
-}
-
-/** Returns only the action selected by {@link resolveRule}. */
-export function resolveAction(command: string, rules: Record<string, Action>): Action | null {
-  return resolveRule(command, rules)?.action ?? null;
-}
-
-/** Converts terminal controls and bidirectional formatting characters to visible escapes. */
-function escapeUnsafeDisplayCharacter(character: string): string {
-  const codePoint = character.codePointAt(0);
-  if (codePoint === undefined) return "";
+function reportHerdrBlocked(pi: ExtensionAPI, ctx: { mode?: string }, active: boolean): void {
   if (
-    codePoint < 0x20 ||
-    (codePoint >= 0x7f && codePoint <= 0x9f) ||
-    BIDI_CONTROL_CODE_POINTS.has(codePoint)
+    ctx.mode !== "tui" ||
+    process.env.HERDR_ENV !== "1" ||
+    !process.env.HERDR_SOCKET_PATH ||
+    !process.env.HERDR_PANE_ID
   ) {
-    return `\\u{${codePoint.toString(16).padStart(4, "0")}}`;
+    return;
   }
-  return character;
-}
 
-interface MatchRange {
-  start: number;
-  end: number;
-}
-
-/** Finds non-overlapping raw match ranges before any display escaping occurs. */
-function findMatchRanges(command: string, pattern?: string): MatchRange[] {
-  if (!pattern) return [];
-  const ranges: MatchRange[] = [];
-  let offset = 0;
-  while (offset <= command.length - pattern.length) {
-    const start = command.indexOf(pattern, offset);
-    if (start === -1) break;
-    ranges.push({ start, end: start + pattern.length });
-    offset = start + pattern.length;
+  // The Herdr integration consumes this event and reports it through its
+  // existing socket connection. Keep this optional integration best-effort so
+  // a missing or incompatible Herdr extension cannot affect command gating.
+  try {
+    pi.events.emit("herdr:blocked", {
+      active,
+      label: HERDR_BLOCKED_LABEL,
+    });
+  } catch {
+    // Herdr is an optional host integration.
   }
-  return ranges;
 }
 
-/** Produces bounded terminal-safe text, optionally marking raw matched spans. */
-function renderCommandForDisplay(command: string, pattern?: string): string {
-  const ranges = findMatchRanges(command, pattern);
-  let rangeIndex = 0;
-  let activeRange: MatchRange | undefined;
-  let output = "";
-  let lineCount = 1;
-  let offset = 0;
+export type { Action, GateConfig } from "./config";
 
-  const truncate = (closeActiveRange = activeRange !== undefined): string =>
-    output + (closeActiveRange ? "«" : "") + DISPLAY_TRUNCATION_MARKER;
+export {
+  CONFIG_SCHEMA_URL,
+  DEFAULT_PROMPT_TIMEOUT_MS,
+  MAX_PROMPT_TIMEOUT_MS,
+  MAX_RULE_COUNT,
+  MAX_RULE_PATTERN_LENGTH,
+  ensureConfig,
+  loadConfig,
+  loadConfigResult,
+  parseConfig,
+} from "./config";
 
-  while (offset < command.length) {
-    const rawStart = offset;
-    let rawEnd: number;
-    let rendered: string;
-    const codePoint = command.codePointAt(offset);
-    if (codePoint === 0x0d) {
-      rawEnd = offset + (command.codePointAt(offset + 1) === 0x0a ? 2 : 1);
-      rendered = "\n";
-    } else {
-      const character = String.fromCodePoint(codePoint!);
-      rawEnd = offset + character.length;
-      rendered = character === "\n" ? character : escapeUnsafeDisplayCharacter(character);
-    }
+export type { ConfigLoadResult, ConfigLoadStatus } from "./config";
 
-    const nextRange = ranges[rangeIndex];
-    const wasInsideRange = activeRange !== undefined;
-    const opensRange =
-      activeRange === undefined &&
-      nextRange !== undefined &&
-      nextRange.start < rawEnd &&
-      nextRange.end > rawStart;
-    if (opensRange) activeRange = nextRange;
-    const closesRange = activeRange !== undefined && activeRange.end <= rawEnd;
-    const decorated = `${opensRange ? "»" : ""}${rendered}${closesRange ? "«" : ""}`;
+export type { RuleMatch } from "./rules";
 
-    if (rendered === "\n") {
-      if (lineCount >= MAX_DISPLAY_COMMAND_LINES) return truncate(wasInsideRange);
-      lineCount += 1;
-    }
-    if (output.length + decorated.length > MAX_DISPLAY_COMMAND_CHARACTERS) {
-      return truncate(wasInsideRange);
-    }
+export { resolveAction, resolveRule } from "./rules";
 
-    output += decorated;
-    if (closesRange) {
-      activeRange = undefined;
-      rangeIndex += 1;
-    }
-    offset = rawEnd;
-  }
-  return output;
-}
-
-/**
- * Produces bounded terminal-safe text for a command without changing the command that is executed.
- */
-export function formatCommandForDisplay(command: string): string {
-  return renderCommandForDisplay(command);
-}
-
-/** Marks raw matched-rule occurrences while producing terminal-safe command text. */
-export function highlightRuleForDisplay(command: string, pattern: string): string {
-  return renderCommandForDisplay(command, pattern);
-}
-
-/** Indents every line of terminal-safe command text for the confirmation dialog. */
-function formatPromptCommand(command: string, pattern: string): string {
-  return highlightRuleForDisplay(command, pattern)
-    .split("\n")
-    .map((line) => `  ${line}`)
-    .join("\n");
-}
-
-/**
- * Formats a rule match as a terminal-safe, human-readable string.
- *
- * @param match - The rule match to format
- * @returns A string representation showing the pattern and action
- */
-function formatRule(match: RuleMatch): string {
-  return formatCommandForDisplay(
-    `${JSON.stringify(match.pattern)}: ${JSON.stringify(match.action)}`,
-  );
-}
+export {
+  MAX_DISPLAY_COMMAND_CHARACTERS,
+  MAX_DISPLAY_COMMAND_LINES,
+  formatCommandForDisplay,
+  highlightRuleForDisplay,
+} from "./display";
 
 /** Gate the built-in `bash` tool against the user-provided rules. */
 export default function piGate(pi: ExtensionAPI): void {
   ensureConfig();
-  const config = loadConfig();
+  let loadResult = loadConfigResult();
+  const { config } = loadResult;
 
   pi.on("session_start", (_event, ctx) => {
     const path = configPath();
     const ruleCount = Object.keys(config.operations).length;
-    if (existsSync(path)) {
+
+    if (loadResult.status === "loaded") {
       if (ruleCount === 0) {
         ctx.ui.notify(
           `pi-gate: ${path} is empty; no commands are gated. Add rules to the "operations" object to start gating.`,
@@ -366,9 +105,14 @@ export default function piGate(pi: ExtensionAPI): void {
           "info",
         );
       }
+    } else if (loadResult.status === "failed") {
+      ctx.ui.notify(
+        "pi-gate: configuration exists but could not be loaded; prompting for all commands until it is fixed.",
+        "warning",
+      );
     } else {
       ctx.ui.notify(
-        `pi-gate: could not create configuration at ${path}; all commands are allowed until that file is created.`,
+        `pi-gate: no configuration found at ${configPath()}; all commands are allowed until it is created.`,
         "warning",
       );
     }
@@ -376,17 +120,29 @@ 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;
-    const match = resolveRule(command, config.operations);
+
+    if (loadResult.status === "failed") {
+      loadResult = loadConfigResult();
+    }
+
+    const match =
+      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);
 
     if (match.action === "block") {
       const reason = `pi-gate: command blocked by rule ${rule}`;
+
       if (ctx.hasUI) {
         ctx.ui.notify(reason, "warning");
       }
+
       return { block: true, reason, terminate: true };
     }
 
@@ -398,11 +154,20 @@ export default function piGate(pi: ExtensionAPI): void {
         terminate: true,
       };
     }
-    const 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 »…«`,
-      ["Allow", "Deny"],
-      { timeout: config.promptTimeoutMs },
-    );
+
+    reportHerdrBlocked(pi, ctx, true);
+    let choice: string | undefined;
+
+    try {
+      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 »…«`,
+        ["Allow", "Deny"],
+        { timeout: loadResult.config.promptTimeoutMs },
+      );
+    } finally {
+      reportHerdrBlocked(pi, ctx, false);
+    }
+
     if (choice !== "Allow") {
       return {
         block: true,
@@ -410,6 +175,7 @@ export default function piGate(pi: ExtensionAPI): void {
         terminate: true,
       };
     }
+
     return undefined;
   });
 }

package/src/rules.ts

@@ -0,0 +1,38 @@
+import type { Action } from "./config";
+
+export interface RuleMatch {
+  pattern: string;
+  action: Action;
+}
+
+/**
+ * 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
+ */
+export function resolveRule(command: string, rules: Record<string, Action>): RuleMatch | null {
+  let bestPattern: string | null = null;
+
+  for (const pattern of Object.keys(rules)) {
+    if (!command.includes(pattern)) continue;
+
+    if (bestPattern === null || pattern.length > bestPattern.length) {
+      bestPattern = pattern;
+    }
+  }
+
+  if (bestPattern === null) return null;
+
+  return { pattern: bestPattern, action: rules[bestPattern] };
+}
+
+/** Returns only the action selected by {@link resolveRule}. */
+export function resolveAction(command: string, rules: Record<string, Action>): Action | null {
+  return resolveRule(command, rules)?.action ?? null;
+}