pi-open-agents 0.1.23 → 0.1.25

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.25",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/discovery/loader.ts

@@ -92,6 +92,9 @@ export async function loadAgents(options: LoadAgentsOptions = {}): Promise<Agent
   const projectAgents = new Map<string, AgentDefinition>();
   const warnings: AgentLoadResult["warnings"] = [];
 
+  const GLOBAL_FAMILY_RANK: Record<string, number> = { pi: 2, opencode: 1, shared: 1 };
+  const globalRanks = new Map<string, number>();
+
   for (const discPath of paths) {
     // For each subdir pattern, scan the directory
     for (const subdir of discPath.subdirs) {
@@ -113,8 +116,16 @@ export async function loadAgents(options: LoadAgentsOptions = {}): Promise<Agent
           if (agent.disable) continue;
 
           // Add to the appropriate map
-          const target = discPath.source === "project" ? projectAgents : globalAgents;
-          target.set(agent.name, agent);
+          if (discPath.source === "project") {
+            projectAgents.set(agent.name, agent);
+          } else {
+            const rank = GLOBAL_FAMILY_RANK[discPath.family] ?? 0;
+            const prevRank = globalRanks.get(agent.name);
+            if (prevRank === undefined || rank >= prevRank) {
+              globalAgents.set(agent.name, agent);
+              globalRanks.set(agent.name, rank);
+            }
+          }
         } catch (error) {
           warnings.push({
             filePath,

package/src/index.ts

@@ -22,17 +22,19 @@ import type { AgentDefinition, ThinkingLevel } from "./types.ts";
 import { loadAgents, selectableAgents, spawnableAgents } from "./discovery/loader.ts";
 import { AgentManager } from "./primary/manager.ts";
 import { refreshAgentTools, buildSystemPrompt, buildSubagentGuidance } from "./primary/executor.ts";
-import { updateBanner } from "./tui/banner.ts";
+import { setShowAgentDescription, updateBanner } from "./tui/banner.ts";
 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 ────────────────────────────────────────────────────────────────
 
 interface Settings {
   defaultAgent?: string;
   defaultThinkingLevel?: ThinkingLevel;
+  showAgentDescription?: boolean;
 }
 
 function loadSettings(cwd: string): Settings {
@@ -74,6 +76,7 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
   pi.on("session_start", async (event, ctx) => {
     // Load settings for thinking fallback
     const settings = loadSettings(ctx.cwd);
+    setShowAgentDescription(settings.showAgentDescription);
 
     // Load all agent definitions from discovery paths
     const result = await loadAgents({
@@ -98,10 +101,32 @@ 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.
     if (isSubagentProcess(process.env)) {
+      // A forked child inherits the parent's session entries (pi core copies
+      // them into the branched session) and never re-announces (this early
+      // return). Without this, the permission system would resolve the
+      // parent's active_agent entry and attribute the parent's policy to the
+      // child. Append an explicit terminator so the child falls back to the
+      // global policy — the pre-patch baseline. Falls back to the global policy
+      // because nothing has resolved an agent name yet in this process — the
+      // permission system caches the last name it resolved (knownAgentName) and
+      // does not clear it between sessions.
+      pi.appendEntry("active_agent", { name: null });
       updateBanner(ctx.ui, undefined, 0);
       return;
     }
@@ -127,10 +152,26 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
 
       if (agentEntry?.data?.name) {
         manager.restoreFromSession(agentEntry.data.name);
-        // Re-apply tools on resume (model preserved from session)
+        // Only announce the agent when the restore actually produced an active
+        // agent. restoreFromSession() silently no-ops on an unknown name
+        // (deleted, renamed, or disable:true — the loader skips those), and
+        // announcing one would make the permission system apply a disabled
+        // agent's policy to this session.
         const active = manager.getActive();
         if (active) {
+          pi.appendEntry("active_agent", { name: active.name });
+          // Re-apply tools on resume (model preserved from session)
           refreshAgentTools(active, pi);
+        } else {
+          // The restore no-op'd (see above), so no new entry was written. An
+          // older active_agent entry written by a previous apply() is still the
+          // newest one, and the consumer's backward scan would resolve it —
+          // silently applying that (now disabled/unknown) agent's policy.
+          // Append an explicit terminator so it stops here and falls back to
+          // the global policy — nothing has resolved an agent name yet in this
+          // process, since the consumer caches the last name it resolved
+          // (knownAgentName) and does not clear it between sessions.
+          pi.appendEntry("active_agent", { name: null });
         }
         updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
         return;

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).
  */

package/src/primary/manager.ts

@@ -69,6 +69,7 @@ export class AgentManager {
     this.active = agent;
 
     await applyAgentConfig(agent, pi, ctx);
+    pi.appendEntry("active_agent", { name });
 
     return true;
   }
@@ -93,6 +94,10 @@ export class AgentManager {
 
     this.activeName = undefined;
     this.active = undefined;
+    // The consumer treats a null-name entry as "stop scanning" and then falls
+    // back to its last known name, so clearing does not restore the global
+    // policy for a session that already resolved a non-null agent.
+    pi.appendEntry("active_agent", { name: null });
   }
 
   /**

package/src/tui/banner.ts

@@ -1,12 +1,22 @@
 /**
  * Status banner widget for the TUI.
  *
- * Shows the active agent name, model, and description above the editor.
+ * Shows the active agent name, description (when enabled), and model above the editor.
  */
 
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { AgentDefinition } from "../types.ts";
 
+let showDescription = true;
+
+/**
+ * Configure whether the active agent's description is shown in the status banner.
+ * Absent/undefined falls back to true, preserving the default behavior.
+ */
+export function setShowAgentDescription(value: boolean | undefined): void {
+  showDescription = value ?? true;
+}
+
 /**
  * Update the status widget to reflect the active agent.
  * Pass undefined to show "no agent selected" hint.
@@ -20,7 +30,7 @@ export function updateBanner(
     const parts: string[] = [];
     parts.push(ui.theme.bold(ui.theme.fg("accent", activeAgent.name)));
 
-    if (activeAgent.description) {
+    if (showDescription && activeAgent.description) {
       parts.push(ui.theme.fg("muted", `— ${activeAgent.description}`));
     }