@zeldrisho/pi-gate 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- request termination of the current agent turn when a command is blocked, denied, dismissed, or times out; mixed parallel batches containing allowed calls may continue
+- auto-deny interactive prompts after a configurable `promptTimeoutMs` (30 seconds by default)
+- create `pi-gate.json` directly on first load with the default timeout and starter prompt/block/allow rules instead of writing an example file
+
 ## [0.1.1] - 2026-09-01
 
 ### Changed
@@ -23,6 +44,8 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.3.0...HEAD
+[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

@@ -16,42 +16,42 @@ pi install -l npm:@zeldrisho/pi-gate
 
 ## Configure
 
-The extension ships with **no default rules**. On first load, an example configuration is written to `~/.pi/agent/pi-gate.json.example` and a warning notifies you that no configuration is active. Every bash command is allowed until you create a configuration.
+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.
 
-Copy the example and edit it:
+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.
 
-```bash
-cp ~/.pi/agent/pi-gate.json.example ~/.pi/agent/pi-gate.json
-```
-
-Then edit `~/.pi/agent/pi-gate.json` to add your rules. Each rule is a substring pattern and one of three actions:
+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 (use to carve out an exception to a broader rule)
+- `allow` — explicitly allow an exception to a broader matching rule
 
 ```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"
   }
 }
 ```
 
-Patterns use simple substring matching. When several patterns match the same command, the longest pattern wins, so a narrow `allow` rule can override a broader `block` or `prompt` rule.
+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.
 
 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.
+- `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.
-- In non-interactive modes (`-p`, JSON), `prompt` and `block` rules both block the command instead of auto-approving.
+- 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.
 
 ### What the agent sees
 

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.1.1",
+  "version": "0.3.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/index.ts

@@ -2,14 +2,13 @@
  * pi-gate Extension
  *
  * Intercepts the built-in `bash` tool and gates each command against a
- * user-provided JSON configuration. Without a configuration file, every
- * command is allowed and the extension posts a warning on `session_start`
- * reminding the user to create one.
+ * user-provided JSON configuration. Without a configuration file, the
+ * extension creates one with starter rules and a default prompt timeout.
  *
  * Configuration file: `~/.pi/agent/pi-gate.json`
  *
- * The configuration has a single section, `operations`, which maps a
- * substring pattern to one of three actions:
+ * The configuration has an `operations` section, which maps a substring
+ * pattern to one of three actions, and an optional `promptTimeoutMs` setting:
  *
  * - `prompt` - ask the user to allow or deny the command
  * - `block`  - deny the command without asking
@@ -18,11 +17,13 @@
  * When multiple patterns match a command, the longest pattern wins, so a
  * narrow `allow` rule can override a broader `prompt` or `block` rule.
  *
- * On first run, an example configuration is written next to the real one
- * at `~/.pi/agent/pi-gate.json.example` to document the format.
+ * On first run, a configuration with the default prompt timeout and starter
+ * operation rules is written to `~/.pi/agent/pi-gate.json`.
  *
  * Non-UI modes (print, JSON) never auto-approve. A `prompt` or `block` rule
- * in non-UI mode always blocks the command.
+ * in non-UI mode always blocks and requests termination of the agent turn.
+ * Interactive prompts auto-deny after `promptTimeoutMs` rather than waiting
+ * indefinitely.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -34,6 +35,7 @@ export type Action = "prompt" | "block" | "allow";
 
 export interface GateConfig {
   operations: Record<string, Action>;
+  promptTimeoutMs: number;
 }
 
 export interface RuleMatch {
@@ -42,14 +44,28 @@ export interface RuleMatch {
 }
 
 const CONFIG_FILE_NAME = "pi-gate.json";
-const EXAMPLE_FILE_NAME = "pi-gate.json.example";
+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 EXAMPLE_CONFIG: GateConfig = {
+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",
   },
 };
 
@@ -71,15 +87,6 @@ function configPath(): string {
   return join(agentDir(), CONFIG_FILE_NAME);
 }
 
-/**
- * Returns the full path to the example pi-gate configuration file.
- *
- * @returns The absolute path to pi-gate.json.example
- */
-function examplePath(): string {
-  return join(agentDir(), EXAMPLE_FILE_NAME);
-}
-
 /**
  * Type guard that checks if an unknown value is a valid Action.
  *
@@ -118,25 +125,38 @@ function isJsonObject(value: unknown): value is Record<string, unknown> {
  */
 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 };
+    return { operations: rules, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   }
   if (!isJsonObject(parsed)) {
-    return { operations: rules };
+    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 };
+    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 };
+  return { operations: rules, promptTimeoutMs };
 }
 
 /**
@@ -146,35 +166,35 @@ export function parseConfig(content: string): GateConfig {
 export function loadConfig(): GateConfig {
   const path = configPath();
   if (!existsSync(path)) {
-    return { operations: {} };
+    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   }
   let content: string;
   try {
     content = readFileSync(path, "utf-8");
   } catch {
-    return { operations: {} };
+    return { operations: {}, promptTimeoutMs: DEFAULT_PROMPT_TIMEOUT_MS };
   }
   return parseConfig(content);
 }
 
 /**
- * Writes the example configuration next to the real one. Existing example
- * files are left alone so the user can rely on them to track the latest
- * supported shape.
+ * Writes the default configuration on first run. Existing configuration files
+ * are never overwritten.
  */
-export function ensureExampleConfig(): void {
-  const path = examplePath();
+export function ensureConfig(): void {
+  const path = configPath();
   if (existsSync(path)) return;
   try {
     mkdirSync(agentDir(), { recursive: true });
   } catch {
     return;
   }
-  const example = JSON.stringify(EXAMPLE_CONFIG, null, 2) + "\n";
+  const content = JSON.stringify({ $schema: CONFIG_SCHEMA_URL, ...DEFAULT_CONFIG }, null, 2) + "\n";
   try {
-    writeFileSync(path, example, "utf-8");
+    writeFileSync(path, content, { encoding: "utf-8", flag: "wx", mode: 0o600 });
   } catch {
-    // Best-effort: the warning banner still surfaces the missing config.
+    // Best-effort: another process may have created it, or the warning banner
+    // will surface that no configuration is active.
   }
 }
 
@@ -206,19 +226,129 @@ export function resolveAction(command: string, rules: Record<string, Action>): A
   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 "";
+  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;
+}
+
 /**
- * Formats a rule match as a human-readable string for display in prompts and notifications.
+ * 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 `${JSON.stringify(match.pattern)}: ${JSON.stringify(match.action)}`;
+  return formatCommandForDisplay(
+    `${JSON.stringify(match.pattern)}: ${JSON.stringify(match.action)}`,
+  );
 }
 
 /** Gate the built-in `bash` tool against the user-provided rules. */
 export default function piGate(pi: ExtensionAPI): void {
-  ensureExampleConfig();
+  ensureConfig();
   const config = loadConfig();
 
   pi.on("session_start", (_event, ctx) => {
@@ -238,7 +368,7 @@ export default function piGate(pi: ExtensionAPI): void {
       }
     } else {
       ctx.ui.notify(
-        `pi-gate: no configuration found at ${path}; all commands are allowed. Copy ${examplePath()} to ${path} to start gating.`,
+        `pi-gate: could not create configuration at ${path}; all commands are allowed until that file is created.`,
         "warning",
       );
     }
@@ -257,7 +387,7 @@ export default function piGate(pi: ExtensionAPI): void {
       if (ctx.hasUI) {
         ctx.ui.notify(reason, "warning");
       }
-      return { block: true, reason };
+      return { block: true, reason, terminate: true };
     }
 
     // action === "prompt"
@@ -265,14 +395,20 @@ export default function piGate(pi: ExtensionAPI): void {
       return {
         block: true,
         reason: `pi-gate: command blocked because rule ${rule} requires a prompt, but no UI is available`,
+        terminate: true,
       };
     }
     const choice = await ctx.ui.select(
-      `pi-gate: allow this command?\n\n  ${command}\n\nMatched rule: ${rule}`,
+      `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 },
     );
     if (choice !== "Allow") {
-      return { block: true, reason: `pi-gate: command denied by user after matching rule ${rule}` };
+      return {
+        block: true,
+        reason: `pi-gate: command denied, dismissed, or timed out after matching rule ${rule}`,
+        terminate: true,
+      };
     }
     return undefined;
   });