pi-open-agents 0.1.23 → 0.1.24

package/README.md

@@ -147,6 +147,26 @@ Tool names are normalized automatically: `task` → `subagent`, `vscode` → `re
 **separate** tools — `write` creates/overwrites files, `edit` does search-and-
 replace — so they have separate permission categories.
 
+**Runtime enforcement (v0.1.24).** Every tool call is evaluated against the
+active agent's rules *before it runs* — not just used to filter the toolset:
+
+- `deny` blocks the call; the model receives a clear denial reason
+- `ask` opens a dialog: *Allow once / Allow always (this session) / Deny*
+- Patterns are **argument-aware**: file paths for `read`/`edit`/`write`,
+  command strings for `bash` (`"rm -rf *": deny`, `"**/*.env": deny` — `*`
+  doesn't cross `/`, use `**` for nested paths)
+- Rules are evaluated top-to-bottom, **last match wins** — put specific rules
+  *after* catch-alls (`"*": ask` first, then `"git *": allow`)
+- A call matching no pattern within a configured category proceeds (rule lists
+  are deny/ask lists, not exhaustive allowlists)
+
+> **⚠️ Migration note (v0.1.24):** `ask` is now enforced — previously it was
+> parsed but silently ignored. In non-interactive processes (subagent
+> children, print/JSON mode) an `ask` rule **blocks** the call (fail-closed):
+> add an explicit `allow` rule if a subagent needs that tool. `deny` now also
+> blocks matching *individual calls* (patterns included), not just statically
+> hiding whole tools. (#20)
+
 ### Auto-injected delegation guidance
 
 If an agent has the `subagent` tool, the plugin automatically appends a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -27,6 +27,7 @@ import { registerTuiControls } from "./tui/selector.ts";
 import { registerAgentTools } from "./tui/tools.ts";
 import { registerSubagentTool } from "./subagent/tool.ts";
 import { allowedAgentNames, isSubagentProcess } from "./subagent/env.ts";
+import { registerPermissionGate } from "./permission/gate.ts";
 
 // ─── Settings ────────────────────────────────────────────────────────────────
 
@@ -98,6 +99,18 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
       getActiveAgent: () => manager.getActive(),
     });
 
+    // Runtime permission gate: enforces allow/deny/ask on every tool call
+    // (argument-aware patterns + interactive ask; fail-closed in subagents).
+    registerPermissionGate(pi, {
+      resolveAgent: () => {
+        // In subagent children the active agent is not applied (the executor
+        // configures them via CLI flags) — resolve by the env var it passes.
+        const childName = process.env.PI_OPEN_AGENTS_NAME;
+        if (childName) return manager.getAgent(childName);
+        return manager.getActive();
+      },
+    });
+
     // Subagent child processes are fully configured by the executor via CLI flags
     // (--model, --system-prompt, --tools). Do NOT apply defaultAgent — it would
     // override the executor's model/tools/prompt settings.

package/src/permission/evaluator.ts

@@ -112,7 +112,7 @@ export function evaluate(
  * "*" matches anything
  * "edit" matches "e*" (not typical, but supported)
  */
-function matchPermissionKey(rulePermission: string, toolPermission: string): boolean {
+export function matchPermissionKey(rulePermission: string, toolPermission: string): boolean {
   if (rulePermission === "*") return true;
   return matchPattern(rulePermission, toolPermission);
 }

package/src/permission/gate.ts

@@ -0,0 +1,194 @@
+/**
+ * Runtime permission gate.
+ *
+ * Enforces allow/deny/ask on every tool call via pi's `tool_call` hook:
+ *
+ * - deny  → the call is blocked with a model-visible reason
+ * - ask   → interactive select dialog (allow once / always this session / deny)
+ * - ask in a non-interactive process (headless subagent) → fail-closed block
+ * - allow / no matching rule → the call proceeds
+ *
+ * This complements the static toolset filtering in `evaluator.ts`:
+ * pre-filtering hides tools that are denied with pattern "*"; the gate
+ * enforces argument-aware rules (file paths, bash commands) that cannot be
+ * derived statically, and implements `ask` — which has no other executor.
+ *
+ * Semantics (documented):
+ * - Rules are scoped by permission category: if the agent has no rule whose
+ *   permission key matches the call's category, the call is not gated.
+ * - Within a gated category, last-match-wins; a call that matches no pattern
+ *   proceeds (unmatched ≠ ask — write an explicit `"*": "ask"` rule to ask
+ *   for the remainder).
+ * - A dialog returning "always" memoizes the category for the process
+ *   (i.e. for the session — subagent children are separate processes).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { AgentDefinition, PermissionAction, PermissionRule } from "../types.ts";
+import { evaluate, matchPermissionKey, toolToPermission } from "./evaluator.ts";
+import { parsePermissionRules } from "./parser.ts";
+
+// ─── Argument Extraction ─────────────────────────────────────────────────────
+
+/**
+ * Extract the string argument a permission pattern is matched against.
+ *
+ * - bash/powershell → the command
+ * - file tools → the path (pi uses `file_path`; some tools use `path`)
+ * - grep/find → path when present, else the pattern
+ * - unknown tools → first conventional string field, else undefined
+ *   (only `"*"` patterns match undefined)
+ */
+export function extractToolArg(toolName: string, input: Record<string, unknown>): string | undefined {
+  const str = (key: string): string | undefined =>
+    typeof input[key] === "string" ? (input[key] as string) : undefined;
+
+  switch (toolName) {
+    case "bash":
+    case "powershell":
+    case "shell":
+      return str("command");
+    case "read":
+    case "edit":
+    case "write":
+    case "apply_patch":
+    case "ls":
+      return str("file_path") ?? str("path");
+    case "grep":
+    case "find":
+      return str("path") ?? str("pattern");
+    default:
+      return str("path") ?? str("file_path") ?? str("command") ?? str("pattern") ?? str("url");
+  }
+}
+
+// ─── Decision ────────────────────────────────────────────────────────────────
+
+export interface GateDecision {
+  /** Effective action for this call */
+  action: PermissionAction;
+  /** Permission category (write → edit, etc.) */
+  category: string;
+  /** Matched rule, if any */
+  matched?: { permission: string; pattern: string; action: PermissionAction };
+  /** Whether the call is gated at all (false = no rules for the category) */
+  gated: boolean;
+}
+
+/**
+ * Decide the effective action for a tool call.
+ *
+ * Ungated categories (no rules) return `allow` — this keeps the gate opt-in
+ * per category and preserves behavior for agents without permission config.
+ */
+export function decideToolCall(
+  toolName: string,
+  input: Record<string, unknown>,
+  rules: PermissionRule[],
+): GateDecision {
+  const category = toolToPermission(toolName);
+
+  const categoryHasRules = rules.some((rule) => matchPermissionKey(rule.permission, category));
+  if (!categoryHasRules) {
+    return { action: "allow", category, gated: false };
+  }
+
+  const arg = extractToolArg(toolName, input);
+  const result = evaluate(toolName, arg, rules);
+
+  if (!result.matched) {
+    // Explicit rules exist for the category but none matched this call:
+    // unmatched proceeds (deny/ask lists are not exhaustive allowlists).
+    return { action: "allow", category, gated: true };
+  }
+
+  return {
+    action: result.action,
+    category,
+    gated: true,
+    matched: { permission: result.permission, pattern: result.pattern, action: result.action },
+  };
+}
+
+// ─── Reason Formatting ───────────────────────────────────────────────────────
+
+function preview(value: string, max = 80): string {
+  const flat = value.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+function formatDenyReason(toolName: string, decision: GateDecision, arg: string | undefined): string {
+  const rule = decision.matched;
+  const target = arg ? ` (${preview(arg)})` : "";
+  return `Permission denied: agent rules deny "${toolName}"${target} [rule: ${rule?.permission} "${rule?.pattern}" → deny]`;
+}
+
+function formatHeadlessAskReason(toolName: string, decision: GateDecision): string {
+  const rule = decision.matched;
+  return (
+    `Permission required: the active agent asks for confirmation on "${toolName}" ` +
+    `[rule: ${rule?.permission} "${rule?.pattern}" → ask], but this process is non-interactive ` +
+    `(subagent) — the call was blocked (fail-closed). Add an explicit allow rule to permit it.`
+  );
+}
+
+// ─── Gate Registration ───────────────────────────────────────────────────────
+
+export interface PermissionGateOptions {
+  /** Resolve the agent whose rules apply (active agent, or the subagent's own definition). */
+  resolveAgent: () => AgentDefinition | undefined;
+  /** Session-scoped "always allow" memo (per process). Injectable for tests. */
+  alwaysAllow?: Map<string, boolean>;
+}
+
+/**
+ * Register the permission gate on the `tool_call` event.
+ *
+ * Does nothing for agents without permission rules.
+ */
+export function registerPermissionGate(pi: ExtensionAPI, options: PermissionGateOptions): void {
+  const alwaysAllow = options.alwaysAllow ?? new Map<string, boolean>();
+
+  pi.on("tool_call", async (event, ctx: ExtensionContext) => {
+    const agent = options.resolveAgent();
+    if (!agent?.permission) return undefined;
+
+    const input = (event as { input?: Record<string, unknown> }).input ?? {};
+    const rules = parsePermissionRules(agent.permission);
+    const decision = decideToolCall(event.toolName, input, rules);
+
+    if (!decision.gated || decision.action === "allow") return undefined;
+
+    const arg = extractToolArg(event.toolName, input);
+
+    if (decision.action === "deny") {
+      return { block: true, reason: formatDenyReason(event.toolName, decision, arg) };
+    }
+
+    // ── ask ──
+    if (alwaysAllow.get(decision.category)) return undefined;
+
+    if (!ctx.hasUI) {
+      return { block: true, reason: formatHeadlessAskReason(event.toolName, decision) };
+    }
+
+    const target = arg ? `: ${preview(arg)}` : "";
+    const choice = await ctx.ui.select(
+      `Permission: allow ${event.toolName}${target}?`,
+      ["Allow once", "Allow always (this session)", "Deny"],
+    );
+
+    if (choice === "Allow always (this session)") {
+      alwaysAllow.set(decision.category, true);
+      return undefined;
+    }
+    if (choice === "Allow once") return undefined;
+
+    const how = choice === undefined ? "no answer was given" : "the user denied it";
+    return {
+      block: true,
+      reason: `Permission denied: ${how} for "${event.toolName}".`,
+    };
+  });
+}

package/src/permission/parser.ts

@@ -29,8 +29,9 @@ import { toolToPermission } from "./evaluator.ts";
  * Rules from nested objects are expanded with their pattern.
  * Simple string values get pattern "*".
  *
- * Permission keys are normalized via toolToPermission (write → edit, etc.)
- * so that both "write: deny" and "edit: deny" affect the edit tool.
+ * Permission keys are normalized via toolToPermission (apply_patch → edit,
+ * mcp read tools → read). In pi, `write` and `edit` are separate tools and
+ * stay separate permission categories (see evaluator.ts).
  *
  * Order is preserved as written (object key order).
  */