@zeldrisho/pi-gate 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ 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
@@ -23,6 +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.1...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,39 @@ 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`). The dialog identifies the matched rule.
+- `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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeldrisho/pi-gate",
-  "version": "0.1.1",
+  "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,6 +35,7 @@ export type Action = "prompt" | "block" | "allow";
 
 export interface GateConfig {
   operations: Record<string, Action>;
+  promptTimeoutMs: number;
 }
 
 export interface RuleMatch {
@@ -42,14 +44,18 @@ export interface RuleMatch {
 }
 
 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",
   },
 };
 
@@ -71,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.
  *
@@ -122,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 };
 }
 
 /**
@@ -146,35 +152,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(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.
   }
 }
 
@@ -218,7 +224,7 @@ function formatRule(match: RuleMatch): string {
 
 /** 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 +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",
       );
     }
@@ -257,7 +263,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 +271,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}`,
       ["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;
   });