@gotgenes/pi-permission-system 30.0.0 → 30.1.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [30.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v30.0.0...pi-permission-system-v30.1.0) (2026-09-02)
+
+
+### Features
+
+* **pi-permission-system:** publish isToolFullyDenied for cross-extension tool pre-filtering ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([4345b19](https://github.com/gotgenes/pi-packages/commit/4345b199e5a33427e47bb80f9c16cb78fb1e7fbf)), closes [#815](https://github.com/gotgenes/pi-packages/issues/815)
+
+### Bug Fixes
+
+* **pi-permission-system:** stop hiding a tool whose surface has a reachable non-deny rule ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([ce46b6c](https://github.com/gotgenes/pi-packages/commit/ce46b6c7b9f4c901d6a035f3be6e334f77a76e95)), closes [#815](https://github.com/gotgenes/pi-packages/issues/815)
+
+### Documentation
+
+* **pi-permission-system:** describe tool exposure as surface reachability ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([71d9696](https://github.com/gotgenes/pi-packages/commit/71d96969e5c33ecc0f38b0a43b0bdaf267622000))
+* **pi-permission-system:** stop recommending getToolPermission for tool pre-filtering ([#815](https://github.com/gotgenes/pi-packages/issues/815)) ([fdf0a38](https://github.com/gotgenes/pi-packages/commit/fdf0a383d5419eaded4b6277ead8264e23aa281d))
+
 ## [30.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.3.0...pi-permission-system-v30.0.0) (2026-09-02)
 
 

package/dist/public.d.ts

@@ -531,13 +531,17 @@ interface PermissionQuery {
      */
     checkPermission(surface: string, value?: string, agentName?: string): 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.
      */
@@ -557,6 +561,23 @@ interface PermissionQuery {
  * rules internally.
  */
 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/docs/configuration.md

@@ -295,6 +295,10 @@ A string value is a catch-all for that surface.
 Unknown or absent tools are not required in the config.
 If a tool is not registered at runtime, this extension blocks it before permission checks run.
 
+A tool is withheld from the model entirely only when **every** pattern configured under its surface resolves to `deny`.
+So `"bash": "deny"` hides the tool, while `"bash": { "*": "deny", "git *": "ask" }` keeps it visible — the agent can attempt a `git` command and be prompted, and everything else is denied at the gate.
+Ordering follows the same last-match-wins rule as every other lookup: an exception written *after* the `deny` catch-all is reachable, while one written *before* it is shadowed and the tool is hidden.
+
 #### Path Patterns for File Tools
 
 For path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), an object value maps file-path patterns to actions.
@@ -993,6 +997,9 @@ Avoid arrays, multi-line scalars, and YAML anchors.
 }
 ```
 
+The Bash tool stays visible to the agent here: the three `git` patterns are written after the `deny` catch-all, so they are reachable.
+Every other command is denied at the gate.
+
 ### Read-Only Bash Command Allowlist
 
 The [Read-Only Mode](#read-only-mode) recipe above gates *tools*; this one gates the *bash* surface.
@@ -1142,6 +1149,7 @@ Additional behaviors:
 
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
+- A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
 - The `Available tools:` system prompt section is narrowed to match the filtered active tool set: denied tools' lines are dropped, the rest are kept, and the section is removed entirely only when no tool is allowed
 - The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name

package/docs/cross-extension-api.md

@@ -69,9 +69,12 @@ interface PermissionsService {
     agentName?: string,
   ): PermissionCheckResult;
 
-  /** Query tool-level permission state for pre-filtering before session creation. */
+  /** Query a surface's catch-all permission state — its blanket policy. */
   getToolPermission(toolName: string, agentName?: string): PermissionState;
 
+  /** Whether every value under a tool's surface resolves to deny; use this to pre-filter a tool list. */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
+
   /**
    * Register a custom preview formatter for a specific tool name.
    * Returns a disposer that unregisters the formatter.
@@ -130,14 +133,27 @@ Decomposition needs the tree-sitter parser, which is warmed at `before_agent_sta
 #### `getToolPermission`
 
 Returns `"allow"` | `"deny"` | `"ask"` for a tool name without considering command-level rules.
-Use this to pre-filter a tool list before creating a child session — it avoids calling `checkPermission` per tool and interpreting the full result.
+It reports the surface's own catch-all, so it answers what a surface's blanket policy is.
 
 ```typescript
-const denied = tools.filter(
-  (t) => permissions.getToolPermission(t, agentName) === "deny",
-);
+const blanketPolicy = permissions.getToolPermission("bash", agentName);
 ```
 
+This is not the question to ask when pre-filtering a tool list — use `isToolFullyDenied` for that.
+A surface written as `bash: {"*": "deny", "git *": "ask"}` reports `"deny"` here while `git status` would still be asked about.
+
+#### `isToolFullyDenied`
+
+Returns `true` when every value under the tool's surface resolves to `deny`, and `false` when anything at all could get through.
+Use this to pre-filter a tool list before creating a child session — it avoids calling `checkPermission` per tool and interpreting the full result, and unlike `getToolPermission` it does not withhold a tool that is only partially restricted.
+
+```typescript
+const usable = tools.filter((t) => !permissions.isToolFullyDenied(t, agentName));
+```
+
+Rule ordering is honored (last-match-wins), so an exception written after a `deny` catch-all keeps the tool reachable while one written before it does not.
+It considers config-layer rules only; a runtime session approval does not change the answer.
+
 #### `registerToolInputFormatter`
 
 Register a custom preview formatter for a specific tool name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "30.0.0",
+  "version": "30.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/handlers/before-agent-start.ts

@@ -8,7 +8,6 @@ import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
-import type { PermissionState } from "#src/types";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
@@ -17,16 +16,17 @@ interface BeforeAgentStartPayload {
 
 /**
  * Pure helper: returns true when the tool should be exposed to the agent.
- * Checks the tool-level permission (not command-level) so that a blanket
- * `bash: deny` hides the tool entirely before any invocation is attempted.
+ *
+ * A tool is withheld only when *every* value under its surface resolves to
+ * `deny`, so a blanket `bash: deny` hides the tool entirely while a partially
+ * permissive `bash: {"*": "deny", "git *": "ask"}` keeps it reachable (#815).
  */
 export function shouldExposeTool(
   toolName: string,
   agentName: string | null,
-  getToolPermission: (toolName: string, agentName?: string) => PermissionState,
+  isToolFullyDenied: (toolName: string, agentName?: string) => boolean,
 ): boolean {
-  const toolPermission = getToolPermission(toolName, agentName ?? undefined);
-  return toolPermission !== "deny";
+  return !isToolFullyDenied(toolName, agentName ?? undefined);
 }
 
 /**
@@ -41,7 +41,7 @@ export function shouldExposeTool(
  * - `turnPrep` — brings the node up to date for the turn before anything reads
  *   session state
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
+ * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
  * - `toolRegistry` — Pi tool API subset (getActive + setActive)
  */
 export class AgentPrepHandler {
@@ -70,7 +70,7 @@ export class AgentPrepHandler {
       }
       if (
         shouldExposeTool(toolName, agentName, (t, a) =>
-          this.resolver.getToolPermission(t, a),
+          this.resolver.isToolFullyDenied(t, a),
         )
       ) {
         allowedTools.push(toolName);

package/src/permission-manager.ts

@@ -22,6 +22,7 @@ import {
   evaluateAnyValue,
   evaluateFirst,
   floorAllowsToAsk,
+  isSurfaceFullyDenied,
   rewriteAsksToYolo,
 } from "./rule";
 import { mergeScopesWithOrigins } from "./scope-merge";
@@ -83,6 +84,7 @@ export interface ScopedPermissionManager {
     sessionRules?: Ruleset,
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
   getConfigIssues(agentName?: string): string[];
 }
 
@@ -268,6 +270,24 @@ export class PermissionManager implements ScopedPermissionManager {
     return evaluate(toolName.trim(), "*", composedRules, this.flavor).action;
   }
 
+  /**
+   * Whether every value under a tool's surface resolves to `deny`.
+   *
+   * This is the question tool exposure asks, and it is not
+   * {@link PermissionManager.getToolPermission} — that reports the surface's
+   * catch-all, so `bash: {"*": "deny", "git *": "ask"}` reads as `deny` even
+   * though `git status` would be asked about (#815).
+   *
+   * Reads the same composed rules the catch-all query does, so it inherits the
+   * fail-closed floor and not the yolo rewrite. Neither matters: one touches
+   * only `allow` and the other only `ask`, so neither can create or remove the
+   * `deny` this answer turns on.
+   */
+  isToolFullyDenied(toolName: string, agentName?: string): boolean {
+    const { composedRules } = this.resolvePermissions(agentName);
+    return isSurfaceFullyDenied(toolName.trim(), composedRules, this.flavor);
+  }
+
   /**
    * Unified resolution entry point — dispatches on intent kind.
    *

package/src/permission-resolver.ts

@@ -126,10 +126,19 @@ export class PermissionResolver
     );
   }
 
+  // Reached only through `LocalPermissionsService`'s structural resolver view,
+  // which fallow cannot trace; `tsc` enforces it at that constructor. The
+  // handler's exposure check moved to `isToolFullyDenied` in #815, leaving this
+  // the published cross-extension catch-all query and nothing else.
+  // fallow-ignore-next-line unused-class-member
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     return this.permissionManager.getToolPermission(toolName, agentName);
   }
 
+  isToolFullyDenied(toolName: string, agentName?: string): boolean {
+    return this.permissionManager.isToolFullyDenied(toolName, agentName);
+  }
+
   getConfigIssues(agentName?: string): string[] {
     return this.permissionManager.getConfigIssues(agentName);
   }

package/src/permissions-service.ts

@@ -25,6 +25,7 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 interface ResolverForService {
   resolve(intent: AccessIntent): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
+  isToolFullyDenied(toolName: string, agentName?: string): boolean;
 }
 
 /** Narrow session view: hands out the cwd-bound path normalizer. */
@@ -81,6 +82,13 @@ export class LocalPermissionsService implements PermissionsService {
     return this.resolver.getToolPermission(toolName, agentName);
   }
 
+  isToolFullyDenied(
+    toolName: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["isToolFullyDenied"]> {
+    return this.resolver.isToolFullyDenied(toolName, agentName);
+  }
+
   registerToolInputFormatter(
     toolName: string,
     formatter: ToolInputFormatter,

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