@gotgenes/pi-permission-system 30.0.0 → 30.2.0

package/src/rule.ts

@@ -1,6 +1,7 @@
 import type { PathFlavor } from "#src/path/path-flavor";
 
 import { PATH_SURFACES } from "./access-intent/path-surfaces";
+import { expandHomePath } from "./expand-home";
 import type { PermissionState } from "./types";
 import { type WildcardMatchOptions, wildcardMatch } from "./wildcard-matcher";
 
@@ -139,6 +140,54 @@ function ruleMatches(
   );
 }
 
+/**
+ * Whether every value on `surface` resolves to `deny`.
+ *
+ * This is a different question from "what does the surface's catch-all say?",
+ * and it carries a different burden of proof: the catch-all answers *what this
+ * surface is*, while this answers *whether anything at all could get through* —
+ * the question tool exposure has to ask before withholding a tool from the
+ * agent entirely.
+ *
+ * Reachability is decided by probing each pattern configured on the surface as
+ * a representative value through {@link evaluate}, so last-match-wins shadowing
+ * is honored: an exception written *after* a `deny` catch-all is reachable,
+ * while one written *before* it is not.
+ *
+ * The probe is an approximation of "does any string resolve non-deny", not a
+ * decision procedure for it. Being wrong in either direction only changes
+ * whether the agent sees the tool — the invocation gate re-evaluates the real
+ * value against the same ruleset either way.
+ */
+export function isSurfaceFullyDenied(
+  surface: string,
+  rules: Ruleset,
+  flavor: PathFlavor,
+): boolean {
+  for (const value of probeValuesForSurface(surface, rules)) {
+    if (evaluate(surface, value, rules, flavor).action !== "deny") return false;
+  }
+  return true;
+}
+
+/**
+ * The representative values {@link isSurfaceFullyDenied} probes: the catch-all,
+ * plus every pattern configured on a rule whose surface reaches `surface`.
+ *
+ * Each pattern is home-expanded because {@link compileWildcardPattern} expands
+ * the *pattern* side only; an unexpanded `~/notes/*` probe would fail to match
+ * its own rule and report the surface denied.
+ */
+function probeValuesForSurface(surface: string, rules: Ruleset): Set<string> {
+  const values = new Set<string>(["*"]);
+  for (const rule of rules) {
+    if (wildcardMatch(rule.surface, surface)) {
+      values.add(expandHomePath(rule.pattern));
+    }
+  }
+  return values;
+}
+
 /**
  * Evaluate a surface against multiple values, returning the most restrictive
  * non-allow result (deny > ask > allow).

package/src/service.ts

@@ -99,13 +99,17 @@ export interface PermissionQuery {
   ): PermissionCheckResult;
 
   /**
-   * Query the tool-level permission state for pre-filtering tools before
-   * creating a child session.
+   * Query a surface's catch-all permission state — its blanket policy.
    *
    * Returns `"deny"` | `"allow"` | `"ask"` based on the composed policy.
    * Does not consider command-level rules (e.g. per-bash-command patterns) —
    * use `checkPermission` for runtime invocation gates.
    *
+   * This is **not** the question to ask when pre-filtering a tool list: a
+   * partially permissive surface such as `bash: {"*": "deny", "git *": "ask"}`
+   * answers `"deny"` here while `git status` would still be asked about. Use
+   * {@link PermissionsService.isToolFullyDenied} for that.
+   *
    * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
    * @param agentName - Optional agent name for per-agent policy resolution.
    */
@@ -126,6 +130,24 @@ export interface PermissionQuery {
  * rules internally.
  */
 export interface PermissionsService extends PermissionQuery {
+  /**
+   * Whether every value under a tool's surface resolves to `deny`.
+   *
+   * This is the question to ask before withholding a tool from a child
+   * session's tool list, and it is not `getToolPermission`: that reports the
+   * surface's own catch-all, so a partially permissive surface such as
+   * `bash: {"*": "deny", "git *": "ask"}` reads as `"deny"` while `git status`
+   * would still be asked about.
+   *
+   * Rule ordering is honored (last-match-wins), so an exception written *after*
+   * a `deny` catch-all keeps the tool reachable and one written *before* it
+   * does not.
+   *
+   * @param toolName  - Tool name (e.g. `"bash"`, `"read"`, `"my-extension:tool"`).
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
+
   /**
    * Register a custom preview formatter for a specific tool name.
    *

package/src/session-approval.ts

@@ -1,4 +1,8 @@
-import type { ApprovalGrant } from "#src/approval-grant";
+import {
+  type ApprovalGrant,
+  type SessionGrantWidth,
+  widenGrant,
+} from "#src/approval-grant";
 import type { ForwardedSessionApproval } from "#src/authority/permission-forwarding";
 
 /**
@@ -33,6 +37,20 @@ export class SessionApproval {
     return this.grants.length > 0;
   }
 
+  /**
+   * This approval as recorded at `width`.
+   *
+   * The runner holds a width and an approval and tells the approval to produce
+   * itself — it never inspects a grant's surface. Each grant is folded
+   * individually, so an approval whose patterns proved different directions
+   * keeps one grant per pattern (#810) at either width.
+   */
+  atWidth(width: SessionGrantWidth): SessionApproval {
+    return width === "proven"
+      ? this
+      : new SessionApproval(this.grants.map(widenGrant));
+  }
+
   /**
    * Plain data shape for relaying this approval on a forwarded request, so the
    * serving node can record the same grants as a whole-session grant.