@gotgenes/pi-permission-system 30.0.0 → 30.2.0

package/src/authority/permission-prompt-component.ts

@@ -22,6 +22,7 @@ import {
   type PromptModelConfig,
   type PromptViewState,
   reducePrompt,
+  visibleOptionKeys,
 } from "#src/authority/permission-prompt-decision";
 import {
   completeViewBudget,
@@ -127,12 +128,11 @@ const DEFAULT_SESSION_LABEL = "Yes, for this session";
 const OPTION_LABELS: Record<PromptKey, string> = {
   y: "Yes",
   s: DEFAULT_SESSION_LABEL,
+  b: "Yes, for this session in both directions",
   n: "No",
   r: "No, provide reason",
 };
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
-
 export function presentInlinePermissionPrompt(
   view: PermissionPromptView,
   title: string,
@@ -142,6 +142,7 @@ export function presentInlinePermissionPrompt(
   const config: PromptModelConfig = {
     doublePressToConfirm: view.doublePressToConfirm,
     sessionLabel: options?.sessionLabel ?? DEFAULT_SESSION_LABEL,
+    widthLabel: options?.sessionWidth?.label,
     sessionScope: options?.sessionScope,
   };
   return view.ui.custom<UnattributedDecision>(
@@ -330,7 +331,9 @@ class PermissionPromptComponent implements Component {
       return { type: "cancel" };
     }
     if (this.state.step === "decision") {
-      const key = OPTION_ORDER.find((option) => matchesKey(data, option));
+      const key = visibleOptionKeys(this.config).find((option) =>
+        matchesKey(data, option),
+      );
       if (key) {
         return { type: "hotkey", key };
       }
@@ -354,8 +357,8 @@ class PermissionPromptComponent implements Component {
   private renderDecision(width: number): string[] {
     const ask = this.renderAsk(width);
     const lines = [this.theme.fg("accent", this.title), ...ask.lines, ""];
-    for (const key of OPTION_ORDER) {
-      const label = key === "s" ? this.config.sessionLabel : OPTION_LABELS[key];
+    for (const key of visibleOptionKeys(this.config)) {
+      const label = this.labelFor(key);
       const selected = this.state.highlightedKey === key;
       const marker = selected ? "▶" : " ";
       const row = `${marker} (${key}) ${label}`;
@@ -366,6 +369,16 @@ class PermissionPromptComponent implements Component {
     return lines;
   }
 
+  /**
+   * The row label for a key: the two session options carry ask-supplied text
+   * naming what they grant, and the rest are fixed.
+   */
+  private labelFor(key: PromptKey): string {
+    if (key === "s") return this.config.sessionLabel;
+    if (key === "b") return this.config.widthLabel ?? OPTION_LABELS.b;
+    return OPTION_LABELS[key];
+  }
+
   private renderReason(width: number): string[] {
     const lines = [
       this.theme.fg("accent", this.title),

package/src/authority/permission-prompt-decision.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import {
   createDeniedPermissionDecision,
   normalizePermissionDenialReason,
@@ -15,17 +16,45 @@ import {
  * forwards keystrokes to {@link reducePrompt} and renders the returned state.
  */
 
-/** The four decision hotkeys, in display order. */
-export type PromptKey = "y" | "s" | "n" | "r";
+/**
+ * The decision hotkeys, in display order.
+ *
+ * `b` is conditional: it appears only for an ask whose session grant can be
+ * widened to both directions (#813), so the roster an ask actually offers
+ * comes from {@link visibleOptionKeys} rather than from this type.
+ */
+export type PromptKey = "y" | "s" | "b" | "n" | "r";
 
 /** Which sub-view the dialog is showing. */
 export type PromptStep = "decision" | "reason" | "scope";
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
+const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "b", "n", "r"];
+
+const NARROW_OPTION_ORDER: readonly PromptKey[] = OPTION_ORDER.filter(
+  (key) => key !== "b",
+);
+
+/**
+ * The decision step's option keys, in display order.
+ *
+ * A function of the config rather than an exported constant, so which options
+ * an ask offers is decided in the model and the component renders whatever it
+ * is handed — two copies of the roster would be two places to teach about a
+ * conditional option.
+ *
+ * The width option is offered iff the ask supplied a label for it, so an ask
+ * that proves no single direction is rendered and navigated exactly as before.
+ */
+export function visibleOptionKeys(
+  config: PromptModelConfig,
+): readonly PromptKey[] {
+  return config.widthLabel ? OPTION_ORDER : NARROW_OPTION_ORDER;
+}
 
 const OPTION_VERBS: Record<PromptKey, string> = {
   y: "approve",
   s: "approve for this session",
+  b: "approve both directions for this session",
   n: "deny",
   r: "deny with a reason",
 };
@@ -36,6 +65,13 @@ export interface PromptModelConfig {
   doublePressToConfirm: boolean;
   /** Label shown beside the approve-for-session option. */
   sessionLabel: string;
+  /**
+   * Label for the both-directions session option (#813).
+   *
+   * Its presence is what offers the option: an ask whose grants prove no
+   * single direction supplies none, and the roster stays four keys.
+   */
+  widthLabel?: string;
   /**
    * Forwarded asks only: when set, confirming `s` opens a second step choosing
    * whether the grant applies to the requesting subagent only (least-privilege
@@ -56,6 +92,15 @@ export interface PromptViewState {
   reasonError?: string;
   /** Scope step: false = subagent-only (default), true = whole serving session. */
   scopeServing: boolean;
+  /**
+   * The width the session option chosen so far would grant.
+   *
+   * Held on the state rather than passed to the scope step, because a
+   * forwarded ask commits the two choices in different steps. Reset to
+   * `"proven"` on every return to the decision step, so a width the user
+   * backed out of cannot ride along with a later narrow choice.
+   */
+  grantWidth: SessionGrantWidth;
 }
 
 /** An input event the reducer understands. */
@@ -81,6 +126,7 @@ export function initialPromptState(
     hint: "",
     reasonError: undefined,
     scopeServing: false,
+    grantWidth: "proven",
   };
 }
 
@@ -116,12 +162,14 @@ function reduceDecisionStep(
     case "nav":
       return render({
         ...state,
-        highlightedKey: shiftKey(state.highlightedKey, event.direction),
+        highlightedKey: shiftKey(config, state.highlightedKey, event.direction),
         armedKey: undefined,
         hint: "",
       });
     case "hotkey":
-      return pressHotkey(config, state, event.key);
+      return visibleOptionKeys(config).includes(event.key)
+        ? pressHotkey(config, state, event.key)
+        : render(state);
     case "confirm":
       return commit(config, state, state.highlightedKey);
     case "cancel":
@@ -170,23 +218,48 @@ function commit(
         reasonError: undefined,
       });
     case "s":
+    case "b": {
+      // The two session options differ only in the width they grant; which
+      // scope they land on is the forwarded scope step's separate question.
+      const grantWidth: SessionGrantWidth = key === "b" ? "family" : "proven";
       if (config.sessionScope) {
         return render({
           ...state,
           step: "scope",
-          highlightedKey: "s",
+          highlightedKey: key,
           armedKey: undefined,
           hint: "",
           scopeServing: false,
+          grantWidth,
         });
       }
       return {
         kind: "decision",
-        decision: { approved: true, state: "approved_for_session" },
+        decision: sessionDecision("approved_for_session", grantWidth),
       };
+    }
   }
 }
 
+/**
+ * A session-granting decision, naming its width only when it is not the
+ * default.
+ *
+ * Absent means `"proven"` everywhere this value travels — the decision, the
+ * gate result, and the forwarded wire — so the narrow grant serializes
+ * exactly as it did before the option existed.
+ */
+function sessionDecision(
+  state: "approved_for_session" | "approved_for_serving_session",
+  width: SessionGrantWidth,
+): UnattributedDecision {
+  return {
+    approved: true,
+    state,
+    ...(width === "family" ? { sessionGrantWidth: width } : {}),
+  };
+}
+
 function reduceReasonStep(
   state: PromptViewState,
   event: PromptEvent,
@@ -198,6 +271,7 @@ function reduceReasonStep(
       armedKey: undefined,
       hint: "",
       reasonError: undefined,
+      grantWidth: "proven",
     });
   }
   if (event.type === "submitReason") {
@@ -226,12 +300,12 @@ function reduceScopeStep(
     case "confirm":
       return {
         kind: "decision",
-        decision: {
-          approved: true,
-          state: state.scopeServing
+        decision: sessionDecision(
+          state.scopeServing
             ? "approved_for_serving_session"
             : "approved_for_session",
-        },
+          state.grantWidth,
+        ),
       };
     case "cancel":
       return render({
@@ -239,17 +313,23 @@ function reduceScopeStep(
         step: "decision",
         armedKey: undefined,
         hint: "",
+        grantWidth: "proven",
       });
     default:
       return render(state);
   }
 }
 
-function shiftKey(current: PromptKey, direction: "up" | "down"): PromptKey {
-  const index = OPTION_ORDER.indexOf(current);
+function shiftKey(
+  config: PromptModelConfig,
+  current: PromptKey,
+  direction: "up" | "down",
+): PromptKey {
+  const keys = visibleOptionKeys(config);
+  const index = keys.indexOf(current);
   const delta = direction === "down" ? 1 : -1;
-  const next = (index + delta + OPTION_ORDER.length) % OPTION_ORDER.length;
-  return OPTION_ORDER[next] ?? current;
+  const next = (index + delta + keys.length) % keys.length;
+  return keys[next] ?? current;
 }
 
 function render(state: PromptViewState): PromptOutcome {

package/src/authority/permission-prompter.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
@@ -11,6 +12,25 @@ import type { TerminalAuthorizer } from "./authorizer";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
+/**
+ * The width a decision's session grant was recorded at, or `undefined` when it
+ * granted nothing for the session.
+ *
+ * Absent means "proven" everywhere else this value travels, but the review log
+ * is read rather than consumed, so a session-granting entry states its width
+ * explicitly instead of leaving the reader to know the default (#813).
+ */
+function recordedGrantWidth(
+  decision: PermissionPromptDecision,
+): SessionGrantWidth | undefined {
+  const grantsForSession =
+    decision.state === "approved_for_session" ||
+    decision.state === "approved_for_serving_session";
+  return grantsForSession
+    ? (decision.sessionGrantWidth ?? "proven")
+    : undefined;
+}
+
 /**
  * Provenance of a forwarded ask: who is really asking, one hop below.
  *
@@ -133,6 +153,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
           : decision.state,
         denialReason: decision.denialReason,
         decidedBy: decision.decidedBy,
+        sessionGrantWidth: recordedGrantWidth(decision),
       },
     );
 
@@ -151,10 +172,14 @@ export class PermissionPrompter implements PermissionPrompterApi {
       resolution?: string;
       denialReason?: string;
       decidedBy?: DecisionSource;
+      sessionGrantWidth?: SessionGrantWidth;
     },
   ): void {
     this.deps.logger.review(event, {
       ...(details.decidedBy ? { decidedBy: details.decidedBy } : {}),
+      ...(details.sessionGrantWidth
+        ? { sessionGrantWidth: details.sessionGrantWidth }
+        : {}),
       requestId: details.requestId,
       source: details.source,
       agentName: details.agentName,

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/handlers/gates/runner.ts

@@ -228,9 +228,9 @@ export class GateRunner {
       messages,
     });
 
-    // 4. Determine whether session approval was granted
-    const hasSessionApproval =
-      gateResult.action === "allow" && gateResult.forSession === true;
+    // 4. Determine whether session approval was granted, and at what width
+    const sessionGrant =
+      gateResult.action === "allow" ? gateResult.sessionGrant : undefined;
 
     // 5. Emit decision event
     this.emitDecision(
@@ -242,15 +242,17 @@ export class GateRunner {
         gateResult.action === "allow" ? "allow" : "deny",
         resolutionFor(gateResult.decidedBy, {
           approved: gateResult.action === "allow",
-          forSession: hasSessionApproval,
+          forSession: sessionGrant !== undefined,
         }),
       ),
     );
 
     // 6. Record session approval — tell the store; it owns the per-pattern loop
-    // hasSessionApproval already implies gateResult.action === "allow"
-    if (hasSessionApproval && descriptor.sessionApproval) {
-      this.recorder.recordSessionApproval(descriptor.sessionApproval);
+    // A present grant already implies gateResult.action === "allow".
+    if (sessionGrant && descriptor.sessionApproval) {
+      this.recorder.recordSessionApproval(
+        descriptor.sessionApproval.atWidth(sessionGrant.width),
+      );
     }
 
     if (gateResult.action === "block") {

package/src/pattern-suggest.ts

@@ -1,4 +1,9 @@
-import { PATH_BEARING_TOOLS } from "./access-intent/path-surfaces";
+import {
+  type CapabilityDirection,
+  PATH_BEARING_TOOLS,
+  surfaceFamilyOf,
+} from "./access-intent/path-surfaces";
+import type { ApprovalGrant } from "./approval-grant";
 import { prefix, stripBashCommentLines } from "./bash-arity";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
@@ -69,27 +74,90 @@ export interface ForwardedScopeLabels {
   servingSessionLabel: string;
 }
 
+/**
+ * What an approval's grants cover, as one phrase.
+ *
+ * A single grant names its pattern; several name their count, because only the
+ * external-directory gate aggregates an ask over many paths and there is no
+ * pattern that describes them all. Requires at least one grant — an approval
+ * with none is never offered as a session option.
+ */
+export function describeGrantTarget(grants: readonly ApprovalGrant[]): string {
+  return grants.length === 1
+    ? `"${grants[0].pattern}"`
+    : `${grants.length} paths`;
+}
+
+/** The two session-option labels for an ask whose grants prove one direction. */
+export interface DirectionalSessionLabels {
+  /** The proven-direction grant — the least-privilege default. */
+  sessionLabel: string;
+  /** The both-directions grant, offered beside it (#813). */
+  widenedLabel: string;
+}
+
+const DIRECTION_NOUNS: Record<CapabilityDirection, string> = {
+  read: "reads",
+  write: "writes",
+};
+
+/**
+ * Label the two widths a directional ask's session grant can take.
+ *
+ * Both rows name the direction and the target, so the choice between them
+ * contrasts on a stated axis rather than on "wider" (#813).
+ */
+export function buildDirectionalSessionLabels(
+  direction: CapabilityDirection,
+  target: string,
+): DirectionalSessionLabels {
+  return {
+    sessionLabel: `Yes, allow ${DIRECTION_NOUNS[direction]} to ${target} for this session`,
+    widenedLabel: `Yes, allow ${DIRECTION_NOUNS.read} and ${DIRECTION_NOUNS.write} to ${target} for this session`,
+  };
+}
+
 /**
  * Build the two scope labels shown when a human grants a forwarded request
  * "for this session."
  *
  * The subagent option names the requester (least privilege); the whole-session
- * option restates the surface + pattern being granted session-wide.
+ * option restates what is being granted session-wide — every grant, not the
+ * first of them (the residual #810 deferred here).
+ *
+ * The surface is named as the grants' shared **family**, never a directional
+ * member: these labels are built before the dialog runs, so a direction here
+ * could contradict a width the human chooses inside it. Grants that share no
+ * family name no surface at all.
  */
 export function buildForwardedScopeLabels(
   agentName: string | null,
-  surface: string,
-  pattern: string,
+  grants: readonly ApprovalGrant[],
 ): ForwardedScopeLabels {
   const subagentLabel = agentName
     ? `This subagent ('${agentName}') only`
     : "This subagent only";
+  const family = sharedSurfaceFamilyOf(grants);
+  const granted = family
+    ? `${family} ${describeGrantTarget(grants)}`
+    : describeGrantTarget(grants);
   return {
     subagentLabel,
-    servingSessionLabel: `The whole session — allow ${surface} "${pattern}" for parent and all subagents`,
+    servingSessionLabel: `The whole session — allow ${granted} for parent and all subagents`,
   };
 }
 
+/** The family every grant belongs to, or `null` when they disagree. */
+function sharedSurfaceFamilyOf(
+  grants: readonly ApprovalGrant[],
+): string | null {
+  if (grants.length === 0) return null;
+  const family = surfaceFamilyOf(grants[0].surface);
+  return grants.every((grant) => surfaceFamilyOf(grant.surface) === family)
+    ? family
+    : null;
+}
+
 /** Surface-aware human-readable labels for the session-approval option. */
 function buildLabel(pattern: string, surface: string): string {
   switch (surface) {

package/src/permission-gate.ts

@@ -1,3 +1,4 @@
+import type { SessionGrantWidth } from "#src/approval-grant";
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
@@ -13,8 +14,15 @@ export type PermissionGateResult =
   | {
       action: "allow";
       decidedBy: DecisionSource;
-      /** Set when the human granted the ask for the whole session. */
-      forSession?: true;
+      /**
+       * Set when the human granted the ask for the whole session, carrying the
+       * width to record it at.
+       *
+       * One field rather than a `forSession` flag beside a width: the width is
+       * meaningless without the grant, and two optional fields could represent
+       * a width for a grant that never happened.
+       */
+      sessionGrant?: { width: SessionGrantWidth };
     }
   | { action: "block"; decidedBy: DecisionSource; reason: string };
 
@@ -112,7 +120,12 @@ export async function applyPermissionGate(
       decision.state === "approved_for_session" &&
       params.canGrantForSession
     ) {
-      return { action: "allow", decidedBy, forSession: true };
+      return {
+        action: "allow",
+        decidedBy,
+        // Absent means the width every producer chose before #813.
+        sessionGrant: { width: decision.sessionGrantWidth ?? "proven" },
+      };
     }
     return { action: "allow", decidedBy };
   }

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,