@zeldrisho/pi-gate 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- identify the matched rule in confirmation prompts, block notifications, and agent-visible error results
+
 ## [0.1.0] - 2026-08-25
 
 ### Added
@@ -17,5 +31,7 @@ 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.0...HEAD
+[Unreleased]: https://github.com/zeldrisho/pi-packages/compare/pi-gate-v0.2.0...HEAD
+[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,54 @@ 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 and starter rules. Existing configuration files are never overwritten.
 
-Copy the example and edit it:
-
-```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
 {
+  "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. 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`).
-- `block` rules never ask and always deny.
+- `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.
-- 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.
+- In non-interactive modes (`-p`, JSON), `prompt` and `block` rules both block and request termination instead of auto-approving.
+
+### 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.
+
+For example, a blocked `sudo apt update` call reports:
+
+```text
+pi-gate: command blocked by rule "sudo": "block"
+```
 
 ## Uninstall
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pi extension that blocks or confirms bash commands based on a user-provided JSON configuration",
   "keywords": [
     "command-blocking",

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,17 +35,27 @@ 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 EXAMPLE_FILE_NAME = "pi-gate.json.example";
 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 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",
   },
 };
 
@@ -66,15 +77,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.
  *
@@ -117,21 +119,30 @@ export function parseConfig(content: string): GateConfig {
   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 (isAction(action)) {
       rules[pattern] = action;
     }
   }
-  return { operations: rules };
+  return { operations: rules, promptTimeoutMs };
 }
 
 /**
@@ -141,40 +152,40 @@ 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(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.
   }
 }
 
 /**
- * Resolves the action that applies to a command against the configured rules.
+ * 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
@@ -182,9 +193,9 @@ export function ensureExampleConfig(): void {
  *
  * @param command - The bash command to evaluate against the rules
  * @param rules - A map of pattern strings to actions
- * @returns The action to take, or `null` if no rule matches
+ * @returns The matched pattern and action, or `null` if no rule matches
  */
-export function resolveAction(command: string, rules: Record<string, Action>): Action | null {
+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;
@@ -193,12 +204,27 @@ export function resolveAction(command: string, rules: Record<string, Action>): A
     }
   }
   if (bestPattern === null) return null;
-  return rules[bestPattern];
+  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)}`;
 }
 
 /** 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) => {
@@ -218,7 +244,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",
       );
     }
@@ -228,26 +254,37 @@ export default function piGate(pi: ExtensionAPI): void {
     if (event.toolName !== "bash") return undefined;
     if (!isToolCallEventType("bash", event)) return undefined;
     const command = event.input.command;
-    const action = resolveAction(command, config.operations);
-    if (action === null || action === "allow") return undefined;
+    const match = resolveRule(command, config.operations);
+    if (match === null || match.action === "allow") return undefined;
+    const rule = formatRule(match);
 
-    if (action === "block") {
+    if (match.action === "block") {
+      const reason = `pi-gate: command blocked by rule ${rule}`;
       if (ctx.hasUI) {
-        ctx.ui.notify(`pi-gate: blocked command matching a rule`, "warning");
+        ctx.ui.notify(reason, "warning");
       }
-      return { block: true, reason: `pi-gate: command matches a "block" rule` };
+      return { block: true, reason, terminate: true };
     }
 
     // action === "prompt"
     if (!ctx.hasUI) {
-      return { block: true, reason: "pi-gate: prompt required but no UI is available" };
+      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\nA rule in pi-gate.json requests confirmation.`,
+      `pi-gate: allow this command?\n\n  ${command}\n\nMatched rule: ${rule}`,
       ["Allow", "Deny"],
+      { timeout: config.promptTimeoutMs },
     );
     if (choice !== "Allow") {
-      return { block: true, reason: "pi-gate: denied by user" };
+      return {
+        block: true,
+        reason: `pi-gate: command denied, dismissed, or timed out after matching rule ${rule}`,
+        terminate: true,
+      };
     }
     return undefined;
   });