@zeldrisho/pi-gate 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +23,6 @@ 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.1.1...HEAD
+[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

@@ -48,11 +48,26 @@ 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.
+- `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.
 
+### 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
 
 ```bash

package/package.json

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

package/src/index.ts

@@ -36,6 +36,11 @@ export interface GateConfig {
   operations: Record<string, Action>;
 }
 
+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;
@@ -48,18 +53,39 @@ const EXAMPLE_CONFIG: GateConfig = {
   },
 };
 
+/**
+ * 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);
 }
 
+/**
+ * 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.
+ *
+ * @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 (
@@ -71,6 +97,12 @@ function isAction(value: unknown): value is Action {
   );
 }
 
+/**
+ * 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);
@@ -147,13 +179,17 @@ export function ensureExampleConfig(): void {
 }
 
 /**
- * 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
  * 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 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;
@@ -162,7 +198,22 @@ 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. */
@@ -197,26 +248,31 @@ 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 };
     }
 
     // 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`,
+      };
     }
     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"],
     );
     if (choice !== "Allow") {
-      return { block: true, reason: "pi-gate: denied by user" };
+      return { block: true, reason: `pi-gate: command denied by user after matching rule ${rule}` };
     }
     return undefined;
   });