@zeldrisho/pi-gate 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- ship a JSON Schema for `pi-gate.json` and reference it from newly seeded configurations for editor completion and validation
+
+### Changed
+
+- wrap visible matched-rule occurrences in confirmation-dialog command text so guarded operations are easier to identify
+- escape terminal and bidirectional control characters and bound long or multiline command text in confirmation dialogs without changing the command executed
+- ignore empty or oversized rule patterns and load at most 1,000 valid rules
+- document and test RPC-host confirmation behavior
+
 ## [0.2.0] - 2026-09-02
 
 ### Changed
@@ -31,7 +50,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.2.0...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.4.0...HEAD
+[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
 [0.1.0]: https://github.com/zeldrisho/pi-packages/releases/tag/pi-gate-v0.1.0

package/README.md

@@ -1,80 +1,51 @@
 # @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 and starter rules. Existing configuration files are never overwritten.
-
-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. The published package includes [`config.schema.json`](config.schema.json); use this schema URL for editor completion:
 
 ```json
 {
+  "$schema": "https://raw.githubusercontent.com/zeldrisho/pi-packages/main/packages/pi-gate/config.schema.json",
   "promptTimeoutMs": 30000,
   "operations": {
     "rm -rf": "prompt",
     "sudo": "prompt",
     "sudo apt update": "allow",
-    "chmod 777": "block",
-    "corepack enable": "block"
+    "chmod 777": "block"
   }
 }
 ```
 
-Patterns use simple substring matching. 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.
-
-After editing, run `/reload` to apply the new rules in the current session.
-
-## Behavior
-
-- 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 and auto-denies after `promptTimeoutMs` instead of waiting indefinitely.
-- `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.
-- In non-interactive modes (`-p`, JSON), `prompt` and `block` rules both block and request termination instead of auto-approving.
+Rules use substring matching and have one of three actions:
 
-### What the agent sees
+- `prompt`: ask the user to allow or deny;
+- `block`: deny without asking;
+- `allow`: explicitly permit an exception to a broader match.
 
-The confirmation dialog and your choice are not sent directly to the agent.
+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.
 
-- 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/config.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/zeldrisho/pi-packages/main/packages/pi-gate/config.schema.json",
+  "title": "pi-gate configuration",
+  "description": "Rules used by @zeldrisho/pi-gate to allow, block, or confirm bash commands.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["operations"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri-reference",
+      "description": "Optional JSON Schema reference for editor validation."
+    },
+    "promptTimeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 86400000,
+      "default": 30000,
+      "description": "Maximum time to wait for an interactive confirmation, in milliseconds."
+    },
+    "operations": {
+      "type": "object",
+      "description": "Command substring patterns mapped to actions. When multiple patterns match, the longest wins.",
+      "maxProperties": 1000,
+      "propertyNames": {
+        "minLength": 1,
+        "maxLength": 1024
+      },
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["prompt", "block", "allow"]
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
   "keywords": [
     "command-blocking",
@@ -24,6 +24,7 @@
   },
   "files": [
     "src",
+    "config.schema.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/config.ts

@@ -0,0 +1,159 @@
+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;
+}
+
+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 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.
+  }
+}

package/src/display.ts

@@ -0,0 +1,128 @@
+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,201 +26,56 @@
  * indefinitely.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
 import { isToolCallEventType, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-export type Action = "prompt" | "block" | "allow";
-
-export interface GateConfig {
-  operations: Record<string, Action>;
-  promptTimeoutMs: number;
-}
-
-export interface RuleMatch {
-  pattern: string;
-  action: Action;
-}
-
-const CONFIG_FILE_NAME = "pi-gate.json";
-const ACTIONS: readonly Action[] = ["prompt", "block", "allow"] as const;
-export const DEFAULT_PROMPT_TIMEOUT_MS = 30_000;
-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
- */
-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 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 (isAction(action)) {
-      rules[pattern] = action;
-    }
-  }
-  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 {
+import { configPath, ensureConfig, loadConfig } from "./config";
+import { resolveRule } from "./rules";
+import { formatPromptCommand, formatRule } from "./display";
+
+const HERDR_BLOCKED_LABEL = "pi-gate: approval required";
+
+function reportHerdrBlocked(pi: ExtensionAPI, ctx: { mode?: string }, active: boolean): void {
+  if (
+    ctx.mode !== "tui" ||
+    process.env.HERDR_ENV !== "1" ||
+    !process.env.HERDR_SOCKET_PATH ||
+    !process.env.HERDR_PANE_ID
+  ) {
     return;
   }
-  const content = JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n";
+
+  // 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 {
-    writeFileSync(path, content, { encoding: "utf-8", flag: "wx", mode: 0o600 });
+    pi.events.emit("herdr:blocked", {
+      active,
+      label: HERDR_BLOCKED_LABEL,
+    });
   } catch {
-    // Best-effort: another process may have created it, or the warning banner
-    // will surface that no configuration is active.
+    // Herdr is an optional host integration.
   }
 }
 
-/**
- * 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;
-}
-
-/**
- * Formats a rule match as a human-readable string for display in prompts and notifications.
- *
- * @param match - The rule match to format
- * @returns A string representation showing the pattern and action
- */
-function formatRule(match: RuleMatch): string {
-  return `${JSON.stringify(match.pattern)}: ${JSON.stringify(match.action)}`;
-}
+export type { Action, GateConfig } from "./config";
+export {
+  CONFIG_SCHEMA_URL,
+  DEFAULT_PROMPT_TIMEOUT_MS,
+  MAX_PROMPT_TIMEOUT_MS,
+  MAX_RULE_COUNT,
+  MAX_RULE_PATTERN_LENGTH,
+  ensureConfig,
+  loadConfig,
+  parseConfig,
+} from "./config";
+export type { RuleMatch } from "./rules";
+export { resolveAction, resolveRule } from "./rules";
+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 {
@@ -274,11 +129,17 @@ export default function piGate(pi: ExtensionAPI): void {
         terminate: true,
       };
     }
-    const choice = await ctx.ui.select(
-      `pi-gate: allow this command?\n\n  ${command}\n\nMatched rule: ${rule}`,
-      ["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: config.promptTimeoutMs },
+      );
+    } finally {
+      reportHerdrBlocked(pi, ctx, false);
+    }
     if (choice !== "Allow") {
       return {
         block: true,

package/src/rules.ts

@@ -0,0 +1,34 @@
+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;
+}