@gotgenes/pi-permission-system 31.0.2 → 31.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).
 
+## [31.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.2...pi-permission-system-v31.1.0) (2026-09-04)
+
+
+### Features
+
+* **pi-permission-system:** record every change to the effective tool surface in the debug log ([bf0331a](https://github.com/gotgenes/pi-packages/commit/bf0331a26ace5dcee7f6a26064af1251fecaaa41))
+
+### Bug Fixes
+
+* **pi-permission-system:** restore a tool when its deny rule is relaxed mid-session ([190a25e](https://github.com/gotgenes/pi-packages/commit/190a25eccdcd5101badf6266f10142c809296983))
+* **pi-permission-system:** forget a withheld tool that pi has unregistered ([404d819](https://github.com/gotgenes/pi-packages/commit/404d8194f9763ee8a228bd36176c5adbb944464c)), closes [#873](https://github.com/gotgenes/pi-packages/issues/873)
+
+### Documentation
+
+* **pi-permission-system:** document the tool-surface baseline ([0997065](https://github.com/gotgenes/pi-packages/commit/09970655c60bfe14c5a38b986301c480ed19f316))
+
 ## [31.0.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.0.1...pi-permission-system-v31.0.2) (2026-09-04)
 
 

package/docs/configuration.md

@@ -1165,9 +1165,13 @@ 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`)
+- Policy is applied to the tool surface pi has activated over the session, not to the previous turn's filtered result, so removing a `deny` rule restores the tool it had hidden without restarting pi.
+  A tool that stops being active for any other reason (another extension deactivating it, pi unregistering it) is not restored.
+- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt an extension receives before the extension runs, so the line is only regenerated once the restored tool is already active
 - 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
+- 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.
+  A policy change is an intentional cache transition, as a mid-session agent switch already is.
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
 - Permission review logs include `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))

package/package.json

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

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

@@ -5,9 +5,11 @@ import type {
 import type { TurnPreparation } from "#src/handlers/session-turn-prep";
 import type { PermissionResolver } from "#src/permission-resolver";
 import type { PermissionSession } from "#src/permission-session";
+import type { DebugLogger } from "#src/session-logger";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
 import { sanitizeAvailableToolsSection } from "#src/system-prompt-sanitizer";
 import { getToolNameFromValue, type ToolRegistry } from "#src/tool-registry";
+import type { ToolSurfaceObservation } from "#src/tool-surface-baseline";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
@@ -42,7 +44,11 @@ export function shouldExposeTool(
  *   session state
  * - `session` — encapsulates all mutable session state and lifecycle operations
  * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
- * - `toolRegistry` — Pi tool API subset (getActive + setActive)
+ * - `toolRegistry` — Pi tool API subset (getAll + getActive + setActive)
+ * - `logger` — records each change to the effective tool surface
+ *
+ * The active set is recomputed from the session's pre-filter tool surface
+ * every turn, so relaxing a rule restores the tool it had withheld (#873).
  */
 export class AgentPrepHandler {
   constructor(
@@ -50,6 +56,7 @@ export class AgentPrepHandler {
     private readonly session: PermissionSession,
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
+    private readonly logger: DebugLogger,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -60,24 +67,23 @@ export class AgentPrepHandler {
     this.turnPrep.prepare(ctx);
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
-    const activeTools = this.toolRegistry.getActive();
-    const allowedTools: string[] = [];
-
-    for (const tool of activeTools) {
-      const toolName = getToolNameFromValue(tool);
-      if (!toolName) {
-        continue;
-      }
-      if (
+    const surface = this.session.resolveExposedTools(
+      this.observeToolSurface(),
+      (toolName) =>
         shouldExposeTool(toolName, agentName, (t, a) =>
           this.resolver.isToolFullyDenied(t, a),
-        )
-      ) {
-        allowedTools.push(toolName);
-      }
-    }
+        ),
+    );
+    const allowedTools = [...surface.exposed];
 
     this.toolRegistry.setActive(allowedTools);
+    if (surface.changed) {
+      this.logger.debug("tool_surface.changed", {
+        exposed: surface.exposed,
+        withheld: surface.withheld,
+        restored: surface.restored,
+      });
+    }
 
     const toolPromptResult = sanitizeAvailableToolsSection(
       event.systemPrompt,
@@ -94,4 +100,22 @@ export class AgentPrepHandler {
       ? { systemPrompt: skillPromptResult.prompt }
       : {};
   }
+
+  private observeToolSurface(): ToolSurfaceObservation {
+    return {
+      active: toolNamesOf(this.toolRegistry.getActive()),
+      registered: new Set(toolNamesOf(this.toolRegistry.getAll())),
+    };
+  }
+}
+
+function toolNamesOf(tools: readonly unknown[]): string[] {
+  const names: string[] = [];
+  for (const tool of tools) {
+    const toolName = getToolNameFromValue(tool);
+    if (toolName) {
+      names.push(toolName);
+    }
+  }
+  return names;
 }

package/src/index.ts

@@ -318,6 +318,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     session,
     resolver,
     toolRegistry,
+    logger,
   );
 
   const gateRunner = new GateRunner(

package/src/permission-session.ts

@@ -20,6 +20,11 @@ import {
   resolveToolPreviewLimits,
   type ToolPreviewFormatterOptions,
 } from "./tool-preview-formatter";
+import {
+  ToolSurfaceBaseline,
+  type ToolSurfaceObservation,
+  type ToolSurfaceResolution,
+} from "./tool-surface-baseline";
 
 /**
  * Encapsulates all mutable session state and exposes operations instead of
@@ -40,6 +45,7 @@ export class PermissionSession implements ToolCallGateInputs {
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
   private pathNormalizer: PathNormalizer;
+  private readonly toolSurfaceBaseline = new ToolSurfaceBaseline();
 
   constructor(
     private readonly paths: ExtensionPaths,
@@ -108,6 +114,7 @@ export class PermissionSession implements ToolCallGateInputs {
       projectTrusted ? ctx.cwd : undefined,
     );
     this.skillEntries = [];
+    this.toolSurfaceBaseline.reset();
     this.activate(ctx);
   }
 
@@ -118,6 +125,7 @@ export class PermissionSession implements ToolCallGateInputs {
   shutdown(): void {
     this.sessionRules.clear();
     this.skillEntries = [];
+    this.toolSurfaceBaseline.reset();
     this.deactivate();
   }
 
@@ -134,6 +142,23 @@ export class PermissionSession implements ToolCallGateInputs {
       projectTrusted ? this.context?.cwd : undefined,
     );
     this.skillEntries = [];
+    // The tool-surface baseline deliberately survives a reload: a reload is
+    // when a relaxed policy arrives, and reseeding from the already-filtered
+    // active set would strand the tool it just un-denied (#873).
+  }
+
+  // ── Tool surface ───────────────────────────────────────────────────────
+
+  /**
+   * Answer which tools the agent may see this turn, applying `isExposed` to
+   * the session's pre-filter tool surface rather than to the previous turn's
+   * filtered result.
+   */
+  resolveExposedTools(
+    observation: ToolSurfaceObservation,
+    isExposed: (toolName: string) => boolean,
+  ): ToolSurfaceResolution {
+    return this.toolSurfaceBaseline.resolveExposed(observation, isExposed);
   }
 
   // ── Skill entries ──────────────────────────────────────────────────────

package/src/session-logger.ts

@@ -18,13 +18,19 @@ export interface ReviewLogger {
 }
 
 /**
- * Logging seam for consumers that write both debug and review entries.
- * Injected into `ConfigStore`, `ParentAuthorizer`, and `ForwardedRequestServer`.
+ * Narrowest logging seam — consumers that only write debug-log entries.
+ * Injected into `AgentPrepHandler`.
  */
-export interface DebugReviewLogger extends ReviewLogger {
+export interface DebugLogger {
   debug(event: string, details?: Record<string, unknown>): void;
 }
 
+/**
+ * Logging seam for consumers that write both debug and review entries.
+ * Injected into `ConfigStore`, `ParentAuthorizer`, and `ForwardedRequestServer`.
+ */
+export interface DebugReviewLogger extends ReviewLogger, DebugLogger {}
+
 /**
  * Unified logging + notification surface for handler deps.
  *

package/src/tool-surface-baseline.ts

@@ -0,0 +1,101 @@
+/** What a turn observed about pi's tool surface. */
+export interface ToolSurfaceObservation {
+  /** Names pi reports active right now (`pi.getActiveTools()`). */
+  readonly active: readonly string[];
+  /** Names pi currently has registered (`pi.getAllTools()`). */
+  readonly registered: ReadonlySet<string>;
+}
+
+/** The effective tool surface for one turn, and what changed to produce it. */
+export interface ToolSurfaceResolution {
+  /** Names to hand to `setActive`, in baseline order. */
+  readonly exposed: readonly string[];
+  /** Baseline members the current policy withholds. */
+  readonly withheld: readonly string[];
+  /** Names withheld on an earlier turn that the current policy exposes again. */
+  readonly restored: readonly string[];
+  /** Whether the withheld set differs from the previous turn's. */
+  readonly changed: boolean;
+}
+
+/** Decides whether the current policy lets the agent see a tool. */
+type ToolExposurePolicy = (toolName: string) => boolean;
+
+/**
+ * The runtime tool surface a session has, independent of what policy withholds.
+ *
+ * Filtering writes its result back through `setActive`, so reading the active
+ * set again next turn returns the *filtered* set. Applying policy to that makes
+ * the surface monotonically shrink and leaves a tool stranded once its rule is
+ * relaxed (#873). This baseline is the stable input policy is applied to
+ * instead: `exposed = baseline ∩ policy`, recomputed every turn.
+ *
+ * The baseline only ever grows from tools observed **active**, never from the
+ * whole registry, so a tool pi deliberately left inactive is never activated
+ * (#385). A tool that stops being active without this extension withholding it
+ * — another extension deactivating it — leaves the baseline with it.
+ */
+export class ToolSurfaceBaseline {
+  private baseline: readonly string[] = [];
+  private withheld: ReadonlySet<string> = new Set();
+
+  resolveExposed(
+    observation: ToolSurfaceObservation,
+    isExposed: ToolExposurePolicy,
+  ): ToolSurfaceResolution {
+    const baseline = this.rebuild(observation);
+    const exposed: string[] = [];
+    const withheld: string[] = [];
+    for (const toolName of baseline) {
+      (isExposed(toolName) ? exposed : withheld).push(toolName);
+    }
+    const restored = exposed.filter((toolName) => this.withheld.has(toolName));
+    const changed = !holdsExactly(this.withheld, withheld);
+
+    this.baseline = baseline;
+    this.withheld = new Set(withheld);
+    return { exposed, withheld, restored, changed };
+  }
+
+  /** Forget the surface, so the next turn reseeds from what pi reports. */
+  reset(): void {
+    this.baseline = [];
+    this.withheld = new Set();
+  }
+
+  /**
+   * Reconstruct the pre-filter surface: the tools still active, plus the ones
+   * only this extension's own filtering removed, plus anything newly active.
+   *
+   * A withheld tool that has left the registry is forgotten rather than kept as
+   * a restoration candidate, so re-registering it inactive cannot activate it.
+   * The registry is consulted for withheld tools only — an active tool is real
+   * by definition — and an active tool is adopted whatever the registry says,
+   * so a registry that reports nothing can cost restoration candidates but
+   * never removes a tool pi has active.
+   */
+  private rebuild(observation: ToolSurfaceObservation): readonly string[] {
+    const active = new Set(observation.active);
+    const baseline = this.baseline.filter(
+      (toolName) =>
+        active.has(toolName) ||
+        (this.withheld.has(toolName) && observation.registered.has(toolName)),
+    );
+
+    const known = new Set(baseline);
+    for (const toolName of observation.active) {
+      if (!known.has(toolName)) {
+        known.add(toolName);
+        baseline.push(toolName);
+      }
+    }
+    return baseline;
+  }
+}
+
+function holdsExactly(
+  set: ReadonlySet<string>,
+  members: readonly string[],
+): boolean {
+  return set.size === members.length && members.every((m) => set.has(m));
+}