@gotgenes/pi-permission-system 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
+## [4.3.0](https://github.com/gotgenes/pi-permission-system/compare/v4.2.0...v4.3.0) (2026-05-04)
+
+
+### Features
+
+* add pattern-suggest module for session approval patterns ([0752604](https://github.com/gotgenes/pi-permission-system/commit/0752604ea63a3bcbf4a8d15f6a9760dde4de9b9d))
+* dynamic session approval label in permission dialog ([4737f0d](https://github.com/gotgenes/pi-permission-system/commit/4737f0dbe69b579dca057a149788408cb63e52ec))
+* extend checkPermission session evaluation to all surfaces ([ffc6731](https://github.com/gotgenes/pi-permission-system/commit/ffc67312e09fb0df0c4dbcb572a625b92c3cd018))
+* extend permission gate with sessionApproval pass-through ([a77bad7](https://github.com/gotgenes/pi-permission-system/commit/a77bad7d9193a5500678bf18ac7854da0be2e79f))
+* generalize session approvals to all permission surfaces ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([2fcc2e3](https://github.com/gotgenes/pi-permission-system/commit/2fcc2e37db4f704702fd3d4c64a1388ab417c407))
+
+
+### Documentation
+
+* document generalized session approvals ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([233666e](https://github.com/gotgenes/pi-permission-system/commit/233666e496dd81165dec44ef4242bca090750edd))
+* plan generalized session approvals for all surfaces ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([3b40cf9](https://github.com/gotgenes/pi-permission-system/commit/3b40cf954c9f598c7c3c199a4137e897c4fce4b2))
+* **retro:** add retro notes for issue [#74](https://github.com/gotgenes/pi-permission-system/issues/74) ([0eb2ea0](https://github.com/gotgenes/pi-permission-system/commit/0eb2ea001669cba1436d564af9e28ca0ff26c77e))
+
 ## [4.2.0](https://github.com/gotgenes/pi-permission-system/compare/v4.1.1...v4.2.0) (2026-05-04)
 
 

package/README.md

@@ -437,20 +437,28 @@ Current agent requested tool 'edit' for '.gitignore' (1 replacement: edit #1 rep
 
 ### Session-Scoped Approvals
 
-When `external_directory` resolves to `ask`, the permission dialog offers four options:
+When any permission resolves to `ask`, the permission dialog offers four options:
 
 ```text
-Yes | Yes, for this session | No | No, provide reason
+Yes | Yes, allow "<pattern>" for this session | No | No, provide reason
 ```
 
-Selecting **Yes, for this session** approves the current request and caches the directory prefix so that subsequent accesses under the same directory skip the prompt for the remainder of the session.
-For example, approving access to `~/other-project/src/foo.ts` covers all paths under `~/other-project/src/` until the session ends.
+Selecting **Yes, allow "\<pattern\>" for this session** approves the current request and records the suggested wildcard pattern as a session rule.
+Subsequent requests that match the pattern skip the prompt for the remainder of the session.
 
-Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
-The review log records these decisions with `resolution: "session_approved"` so they remain auditable.
+The suggested pattern is surface-specific:
+
+|Surface|Example request|Suggested session pattern|
+|---|---|---|
+|bash|`git status --short`|`git *`|
+|mcp (qualified)|`exa:search`|`exa:*`|
+|mcp (munged)|`exa_search`|`exa_*`|
+|skill|`librarian`|`librarian`|
+|tool (read, write, …)|`read`|`*`|
+|external_directory|`/other/project/src/foo.ts`|`/other/project/src/*`|
 
-This is currently scoped to the `external_directory` surface only.
-Other permission surfaces (tools, bash patterns, MCP, skills) always use the standard one-time approval flow.
+Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
+The review log records these decisions: `resolution: "approved_for_session"` when the user approves, and `resolution: "session_approved"` when a later request is matched by an existing session rule.
 
 ### Subagent Permission Forwarding
 
@@ -496,7 +504,8 @@ This makes it easy to verify which files the extension actually loaded:
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
-├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, external-directory access)
+├── pattern-suggest.ts        → Per-surface session approval pattern suggestions
+├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, wildcard patterns across all surfaces)
 ├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
 ├── config-paths.ts         → Path derivation for global, project, and legacy config locations
 ├── config-reporter.ts      → Resolved config path reporting for diagnostic logs

package/package.json

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

package/src/forwarded-permissions/polling.ts

@@ -7,7 +7,10 @@ import {
   getActiveAgentNameFromSystemPrompt,
 } from "../active-agent";
 import { toRecord } from "../common";
-import type { PermissionPromptDecision } from "../permission-dialog";
+import type {
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "../permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
@@ -42,6 +45,7 @@ export interface PermissionForwardingDeps {
     ui: ExtensionContext["ui"],
     title: string,
     message: string,
+    options?: RequestPermissionOptions,
   ) => Promise<PermissionPromptDecision>;
   shouldAutoApprove: () => boolean;
 }
@@ -339,12 +343,14 @@ export async function confirmPermission(
   ctx: ExtensionContext,
   message: string,
   deps: PermissionForwardingDeps,
+  options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
   if (ctx.hasUI) {
     return deps.requestPermissionDecisionFromUi(
       ctx.ui,
       "Permission Required",
       message,
+      options,
     );
   }
 

package/src/handlers/tool-call.ts

@@ -18,6 +18,7 @@ import {
   normalizePathForComparison,
   PATH_BEARING_TOOLS,
 } from "../external-directory";
+import { suggestSessionPattern } from "../pattern-suggest";
 import type { PermissionPromptDecision } from "../permission-dialog";
 import { applyPermissionGate } from "../permission-gate";
 import {
@@ -359,12 +360,35 @@ export async function handleToolCall(
     agentName ?? undefined,
     deps.runtime.sessionRules.getRuleset(),
   );
+
+  // Session-hit: already approved by a session rule — skip the gate entirely.
+  if (check.source === "session") {
+    deps.runtime.writeReviewLog("permission_request.session_approved", {
+      source: "tool_call",
+      toolCallId: (event as { toolCallId: string }).toolCallId,
+      toolName,
+      agentName,
+      resolution: "session_approved",
+      sessionApprovalPattern: check.matchedPattern,
+    });
+    return {};
+  }
+
   const permissionLogContext = getPermissionLogContext(
     check,
     input,
     PATH_BEARING_TOOLS,
   );
 
+  // Compute session approval suggestion for the "for this session" option.
+  const suggestionValue =
+    toolName === "bash"
+      ? (check.command ?? "")
+      : toolName === "mcp"
+        ? (check.target ?? "mcp")
+        : "*";
+  const suggestion = suggestSessionPattern(toolName, suggestionValue);
+
   const toolUnavailableReason =
     toolName === "bash" && isToolCallEventType("bash", event as ToolCallEvent)
       ? `Running bash command '${(event as ToolCallEvent & { input: { command: string } }).input.command}' requires approval, but no interactive UI is available.`
@@ -376,6 +400,10 @@ export async function handleToolCall(
   const toolGate = await applyPermissionGate({
     state: check.state,
     canConfirm: deps.canRequestPermissionConfirmation(ctx),
+    sessionApproval: {
+      surface: suggestion.surface,
+      pattern: suggestion.pattern,
+    },
     promptForApproval: () =>
       deps.promptPermission(ctx, {
         requestId: (event as { toolCallId: string }).toolCallId,
@@ -384,6 +412,7 @@ export async function handleToolCall(
         message: toolAskMessage,
         toolCallId: (event as { toolCallId: string }).toolCallId,
         toolName,
+        sessionLabel: suggestion.label,
         ...permissionLogContext,
       }),
     writeLog: deps.runtime.writeReviewLog,
@@ -407,5 +436,12 @@ export async function handleToolCall(
     return { block: true, reason: toolGate.reason };
   }
 
+  if (toolGate.sessionApproval) {
+    deps.runtime.sessionRules.approve(
+      toolGate.sessionApproval.surface,
+      toolGate.sessionApproval.pattern,
+    );
+  }
+
   return {};
 }

package/src/handlers/types.ts

@@ -19,6 +19,8 @@ export interface PromptPermissionDetails {
   command?: string;
   target?: string;
   toolInputPreview?: string;
+  /** Override label for the "for this session" dialog option. */
+  sessionLabel?: string;
 }
 
 /**

package/src/pattern-suggest.ts

@@ -0,0 +1,91 @@
+import { deriveApprovalPattern } from "./session-rules";
+
+/** The suggestion returned for a "Yes, for this session" dialog option. */
+export interface SessionApprovalSuggestion {
+  /** The permission surface this approval applies to. */
+  surface: string;
+  /** The wildcard pattern to store as a session rule. */
+  pattern: string;
+  /** Human-readable label for the "for session" dialog option. */
+  label: string;
+}
+
+/**
+ * Suggest a bash session-approval pattern from a command string.
+ *
+ * Heuristic: split on the first space to get the base command.
+ * Multi-word commands → `<command> *`.
+ * Single-word commands → exact command (no wildcard).
+ *
+ * This is intentionally conservative. The arity table (#52) will refine
+ * suggestions later (e.g. `git checkout *` instead of `git *`).
+ */
+export function suggestBashPattern(command: string): string {
+  const trimmed = command.trim();
+  const spaceIndex = trimmed.indexOf(" ");
+  if (spaceIndex === -1) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, spaceIndex)} *`;
+}
+
+/**
+ * Suggest an MCP session-approval pattern from a resolved target string.
+ *
+ * - Qualified target (`server:tool`) → `server:*`
+ * - Munged target (`server_tool`) → `server_*`
+ * - Bare target (no separator) → `*`
+ */
+export function suggestMcpPattern(target: string): string {
+  const trimmed = target.trim();
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex > 0) {
+    return `${trimmed.slice(0, colonIndex)}:*`;
+  }
+
+  const underscoreIndex = trimmed.indexOf("_");
+  if (underscoreIndex > 0) {
+    return `${trimmed.slice(0, underscoreIndex)}_*`;
+  }
+
+  return "*";
+}
+
+function buildLabel(pattern: string): string {
+  return `Yes, allow "${pattern}" for this session`;
+}
+
+/**
+ * Suggest a session-approval pattern for the given permission surface and value.
+ *
+ * Returns a `SessionApprovalSuggestion` with the surface, the wildcard pattern
+ * to store in `SessionRules`, and a human-readable dialog label.
+ */
+export function suggestSessionPattern(
+  surface: string,
+  value: string,
+): SessionApprovalSuggestion {
+  let pattern: string;
+
+  switch (surface) {
+    case "bash":
+      pattern = suggestBashPattern(value);
+      break;
+    case "mcp":
+      pattern = suggestMcpPattern(value);
+      break;
+    case "skill":
+      pattern = value;
+      break;
+    case "external_directory":
+      pattern = deriveApprovalPattern(value);
+      break;
+    default:
+      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      pattern = "*";
+      break;
+  }
+
+  return { surface, pattern, label: buildLabel(pattern) };
+}

package/src/permission-dialog.ts

@@ -64,13 +64,27 @@ export function isPermissionDecisionState(
   );
 }
 
+export interface RequestPermissionOptions {
+  /** Override the "for this session" option label (e.g. to show the suggested pattern). */
+  sessionLabel?: string;
+}
+
 export async function requestPermissionDecisionFromUi(
   ui: PermissionDecisionUi,
   title: string,
   message: string,
+  options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
+  const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
+  const decisionOptions = [
+    APPROVE_OPTION,
+    sessionOption,
+    DENY_OPTION,
+    DENY_WITH_REASON_OPTION,
+  ] as const;
+
   const selected = await ui.select(`${title}\n${message}`, [
-    ...PERMISSION_DECISION_OPTIONS,
+    ...decisionOptions,
   ]);
 
   if (selected === APPROVE_OPTION) {
@@ -80,7 +94,7 @@ export async function requestPermissionDecisionFromUi(
     };
   }
 
-  if (selected === APPROVE_FOR_SESSION_OPTION) {
+  if (selected === sessionOption) {
     return {
       approved: true,
       state: "approved_for_session",

package/src/permission-gate.ts

@@ -2,7 +2,7 @@ import type { PermissionPromptDecision } from "./permission-dialog";
 
 /** Result of applying the permission gate. */
 export type PermissionGateResult =
-  | { action: "allow" }
+  | { action: "allow"; sessionApproval?: { surface: string; pattern: string } }
   | { action: "block"; reason: string };
 
 /** Everything the gate needs — no direct dependency on ExtensionContext. */
@@ -16,6 +16,13 @@ export interface PermissionGateParams {
   /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
   promptForApproval: () => Promise<PermissionPromptDecision>;
 
+  /**
+   * Session approval suggestion to record when the user selects
+   * "for this session". When present and the decision is `approved_for_session`,
+   * the result carries the suggestion back to the caller for recording.
+   */
+  sessionApproval?: { surface: string; pattern: string };
+
   /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
   writeLog: (event: string, extra: Record<string, unknown>) => void;
 
@@ -68,6 +75,9 @@ export async function applyPermissionGate(
     if (!decision.approved) {
       return { action: "block", reason: messages.userDeniedReason(decision) };
     }
+    if (decision.state === "approved_for_session" && params.sessionApproval) {
+      return { action: "allow", sessionApproval: params.sessionApproval };
+    }
   }
 
   return { action: "allow" };

package/src/permission-manager.ts

@@ -493,6 +493,20 @@ export class PermissionManager {
     if (normalizedToolName === "skill") {
       const skillName = toRecord(input).name;
       const lookupValue = typeof skillName === "string" ? skillName : "*";
+
+      // Session check.
+      if (sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate("skill", lookupValue, sessionRules);
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+
       const rule = evaluate("skill", lookupValue, composedRules);
       return {
         toolName,
@@ -506,6 +520,21 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
+
+      // Session check.
+      if (sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate("bash", command, sessionRules);
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            command,
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+
       const rule = evaluate("bash", command, composedRules);
       return {
         toolName,
@@ -527,6 +556,22 @@ export class PermissionManager {
       ];
       const fallbackTarget = mcpTargets[0] || "mcp";
 
+      // Session check: try each candidate target against session rules.
+      if (sessionRules && sessionRules.length > 0) {
+        for (const target of mcpTargets) {
+          const sessionRule = evaluate("mcp", target, sessionRules);
+          if (sessionRules.includes(sessionRule)) {
+            return {
+              toolName,
+              state: "allow",
+              matchedPattern: sessionRule.pattern,
+              target,
+              source: "session",
+            };
+          }
+        }
+      }
+
       // Try each candidate target. Stop on the first non-default match.
       for (const target of mcpTargets) {
         const rule = evaluate("mcp", target, composedRules);
@@ -552,6 +597,20 @@ export class PermissionManager {
     }
 
     // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
+
+    // Session check.
+    if (sessionRules && sessionRules.length > 0) {
+      const sessionRule = evaluate(normalizedToolName, "*", sessionRules);
+      if (sessionRules.includes(sessionRule)) {
+        return {
+          toolName,
+          state: "allow",
+          matchedPattern: sessionRule.pattern,
+          source: "session",
+        };
+      }
+    }
+
     const rule = evaluate(normalizedToolName, "*", composedRules);
 
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {

package/src/runtime.ts

@@ -332,6 +332,7 @@ export async function promptPermission(
     ctx,
     details.message,
     forwardingDeps,
+    details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
   );
   reviewPermissionDecision(
     runtime.writeReviewLog,

package/tests/handlers/tool-call.test.ts

@@ -447,3 +447,215 @@ describe("handleToolCall — bash external-directory gate", () => {
     expect(result).toEqual({});
   });
 });
+
+// ── session approval ───────────────────────────────────────────────
+
+describe("handleToolCall — session-hit detection (normal gate)", () => {
+  it("skips gate and logs session_approved when bash check returns source=session", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "allow",
+            toolName: "bash",
+            source: "session",
+            command: "git status",
+            matchedPattern: "git *",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "git status" },
+    });
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toEqual({});
+    expect(deps.runtime.writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.session_approved",
+      expect.objectContaining({
+        resolution: "session_approved",
+        toolName: "bash",
+      }),
+    );
+  });
+
+  it("skips gate and logs session_approved when mcp check returns source=session", async () => {
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "allow",
+            toolName: "mcp",
+            source: "session",
+            target: "exa:search",
+            matchedPattern: "exa:*",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "mcp" }]),
+    });
+    const event = makeToolCallEvent("mcp", { input: { tool: "exa:search" } });
+    const result = await handleToolCall(deps, event, makeCtx());
+    expect(result).toEqual({});
+    expect(deps.runtime.writeReviewLog).toHaveBeenCalledWith(
+      "permission_request.session_approved",
+      expect.objectContaining({
+        resolution: "session_approved",
+        toolName: "mcp",
+      }),
+    );
+  });
+
+  it("does NOT call sessionRules.approve when source is session (already recorded)", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "allow",
+            toolName: "bash",
+            source: "session",
+            command: "git status",
+            matchedPattern: "git *",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "git status" },
+    });
+    await handleToolCall(deps, event, makeCtx());
+    expect(sessionRules.approve).not.toHaveBeenCalled();
+  });
+});
+
+describe("handleToolCall — session recording on approved_for_session", () => {
+  it("records bash session approval with suggestBashPattern result", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "ask",
+            toolName: "bash",
+            source: "bash",
+            command: "git status",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+      canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "git status" },
+    });
+    await handleToolCall(deps, event, makeCtx());
+    expect(sessionRules.approve).toHaveBeenCalledWith("bash", "git *");
+  });
+
+  it("records mcp session approval with suggestMcpPattern result", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "ask",
+            toolName: "mcp",
+            source: "mcp",
+            target: "exa:search",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+      getAllTools: vi.fn().mockReturnValue([{ name: "mcp" }]),
+      canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    const event = makeToolCallEvent("mcp", { input: { tool: "exa:search" } });
+    await handleToolCall(deps, event, makeCtx());
+    expect(sessionRules.approve).toHaveBeenCalledWith("mcp", "exa:*");
+  });
+
+  it("records tool session approval with * pattern for read surface", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "ask",
+            toolName: "read",
+            source: "tool",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+      canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved_for_session" }),
+    });
+    const event = makeToolCallEvent("read", {
+      input: { path: "/test/project/foo.ts" },
+    });
+    await handleToolCall(deps, event, makeCtx());
+    expect(sessionRules.approve).toHaveBeenCalledWith("read", "*");
+  });
+
+  it("does NOT call sessionRules.approve when user approves once (not for session)", async () => {
+    const sessionRules = {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"];
+    const deps = makeDeps({
+      runtime: makeRuntime({
+        permissionManager: {
+          checkPermission: vi.fn().mockReturnValue({
+            state: "ask",
+            toolName: "bash",
+            source: "bash",
+            command: "git status",
+          }),
+        } as unknown as ExtensionRuntime["permissionManager"],
+        sessionRules,
+      }),
+      canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" }),
+    });
+    const event = makeToolCallEvent("bash", {
+      input: { command: "git status" },
+    });
+    await handleToolCall(deps, event, makeCtx());
+    expect(sessionRules.approve).not.toHaveBeenCalled();
+  });
+});

package/tests/pattern-suggest.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+  suggestBashPattern,
+  suggestMcpPattern,
+  suggestSessionPattern,
+} from "../src/pattern-suggest";
+
+describe("suggestBashPattern", () => {
+  it("returns <command> * for a multi-word command", () => {
+    expect(suggestBashPattern("git status --short")).toBe("git *");
+  });
+
+  it("uses only the first word as the base", () => {
+    expect(suggestBashPattern("npm run build")).toBe("npm *");
+  });
+
+  it("returns the exact command when there are no arguments", () => {
+    expect(suggestBashPattern("ls")).toBe("ls");
+  });
+
+  it("trims leading and trailing whitespace", () => {
+    expect(suggestBashPattern("  git log  ")).toBe("git *");
+  });
+
+  it("handles empty string gracefully", () => {
+    expect(suggestBashPattern("")).toBe("");
+  });
+});
+
+describe("suggestMcpPattern", () => {
+  it("suggests server:* for a qualified target (colon-separated)", () => {
+    expect(suggestMcpPattern("exa:search")).toBe("exa:*");
+  });
+
+  it("suggests server_* for a munged target (underscore-separated)", () => {
+    expect(suggestMcpPattern("exa_search")).toBe("exa_*");
+  });
+
+  it("suggests * for a bare 'mcp' target", () => {
+    expect(suggestMcpPattern("mcp")).toBe("*");
+  });
+
+  it("suggests * for a plain tool name with no server prefix", () => {
+    expect(suggestMcpPattern("search")).toBe("*");
+  });
+
+  it("prefers colon over underscore when both are present", () => {
+    // Qualified names contain ':'; the colon check runs first.
+    expect(suggestMcpPattern("my-server:some_tool")).toBe("my-server:*");
+  });
+});
+
+describe("suggestSessionPattern", () => {
+  describe("bash surface", () => {
+    it("returns bash surface with <command> * pattern for multi-word command", () => {
+      const result = suggestSessionPattern("bash", "git status --short");
+      expect(result).toMatchObject({
+        surface: "bash",
+        pattern: "git *",
+      });
+    });
+
+    it("returns exact command for single-word bash command", () => {
+      const result = suggestSessionPattern("bash", "ls");
+      expect(result).toMatchObject({ surface: "bash", pattern: "ls" });
+    });
+  });
+
+  describe("mcp surface", () => {
+    it("returns mcp surface with server:* for qualified target", () => {
+      const result = suggestSessionPattern("mcp", "exa:search");
+      expect(result).toMatchObject({ surface: "mcp", pattern: "exa:*" });
+    });
+
+    it("returns mcp surface with server_* for munged target", () => {
+      const result = suggestSessionPattern("mcp", "exa_search");
+      expect(result).toMatchObject({ surface: "mcp", pattern: "exa_*" });
+    });
+
+    it("returns * for bare mcp target", () => {
+      const result = suggestSessionPattern("mcp", "mcp");
+      expect(result).toMatchObject({ surface: "mcp", pattern: "*" });
+    });
+  });
+
+  describe("skill surface", () => {
+    it("returns exact skill name as pattern", () => {
+      const result = suggestSessionPattern("skill", "librarian");
+      expect(result).toMatchObject({ surface: "skill", pattern: "librarian" });
+    });
+  });
+
+  describe("external_directory surface", () => {
+    it("returns parent-directory glob from deriveApprovalPattern", () => {
+      const result = suggestSessionPattern(
+        "external_directory",
+        "/tmp/foo.txt",
+      );
+      expect(result).toMatchObject({
+        surface: "external_directory",
+        pattern: "/tmp/*",
+      });
+    });
+  });
+
+  describe("tool surfaces", () => {
+    it("returns * for read surface", () => {
+      const result = suggestSessionPattern("read", "*");
+      expect(result).toMatchObject({ surface: "read", pattern: "*" });
+    });
+
+    it("returns * for write surface", () => {
+      const result = suggestSessionPattern("write", "*");
+      expect(result).toMatchObject({ surface: "write", pattern: "*" });
+    });
+
+    it("returns * for edit surface", () => {
+      const result = suggestSessionPattern("edit", "*");
+      expect(result).toMatchObject({ surface: "edit", pattern: "*" });
+    });
+  });
+
+  describe("label field", () => {
+    it("includes the suggested pattern in the label", () => {
+      const result = suggestSessionPattern("bash", "git status");
+      expect(result.label).toContain("git *");
+    });
+
+    it("wraps the pattern in quotes in the label", () => {
+      const result = suggestSessionPattern("mcp", "exa:search");
+      expect(result.label).toContain('"exa:*"');
+    });
+
+    it("label reads as a natural session-approval option", () => {
+      const result = suggestSessionPattern("skill", "librarian");
+      expect(result.label).toBe('Yes, allow "librarian" for this session');
+    });
+  });
+});

package/tests/permission-dialog.test.ts

@@ -132,6 +132,45 @@ describe("requestPermissionDecisionFromUi", () => {
       "No, provide reason",
     ]);
   });
+
+  it("uses custom sessionLabel when provided", async () => {
+    const selectFn = vi.fn().mockResolvedValue("Yes");
+    const ui: PermissionDecisionUi = {
+      select: selectFn,
+      input: vi.fn(),
+    };
+    await requestPermissionDecisionFromUi(ui, "Title", "Message", {
+      sessionLabel: 'Yes, allow "git *" for this session',
+    });
+    const options = selectFn.mock.calls[0][1] as string[];
+    expect(options[1]).toBe('Yes, allow "git *" for this session');
+  });
+
+  it("still returns approved_for_session when user selects the custom session label", async () => {
+    const customLabel = 'Yes, allow "git *" for this session';
+    const ui: PermissionDecisionUi = {
+      select: vi.fn().mockResolvedValue(customLabel),
+      input: vi.fn(),
+    };
+    const result = await requestPermissionDecisionFromUi(
+      ui,
+      "Title",
+      "Message",
+      { sessionLabel: customLabel },
+    );
+    expect(result).toEqual({ approved: true, state: "approved_for_session" });
+  });
+
+  it("falls back to default session label when no options provided", async () => {
+    const selectFn = vi.fn().mockResolvedValue("Yes");
+    const ui: PermissionDecisionUi = {
+      select: selectFn,
+      input: vi.fn(),
+    };
+    await requestPermissionDecisionFromUi(ui, "Title", "Message");
+    const options = selectFn.mock.calls[0][1] as string[];
+    expect(options[1]).toBe("Yes, for this session");
+  });
 });
 
 describe("normalizePermissionDenialReason", () => {

package/tests/permission-gate.test.ts

@@ -179,6 +179,74 @@ describe("applyPermissionGate", () => {
     });
   });
 
+  describe("ask branch — approved_for_session with sessionApproval", () => {
+    it("attaches sessionApproval to result when decision is approved_for_session and param provided", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved_for_session",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+        sessionApproval: { surface: "bash", pattern: "git *" },
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({
+        action: "allow",
+        sessionApproval: { surface: "bash", pattern: "git *" },
+      });
+    });
+
+    it("does not attach sessionApproval when decision is approved (once)", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+        sessionApproval: { surface: "bash", pattern: "git *" },
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not attach sessionApproval when no sessionApproval param", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: true,
+        state: "approved_for_session",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "allow" });
+    });
+
+    it("does not attach sessionApproval when user denies", async () => {
+      const decision: PermissionPromptDecision = {
+        approved: false,
+        state: "denied",
+      };
+      const promptForApproval = vi.fn().mockResolvedValue(decision);
+      const params = makeParams({
+        state: "ask",
+        canConfirm: true,
+        promptForApproval,
+        sessionApproval: { surface: "bash", pattern: "git *" },
+      });
+      const result = await applyPermissionGate(params);
+      expect(result).toEqual({ action: "block", reason: "User denied." });
+    });
+  });
+
   describe("allow branch", () => {
     it("returns allow immediately when state is allow", async () => {
       const params = makeParams({ state: "allow" });

package/tests/permission-system.test.ts

@@ -2620,6 +2620,187 @@ test("session rules override config deny for external_directory", () => {
   }
 });
 
+// ── Session rule evaluation for all surfaces ─────────────────────────────
+
+test("checkPermission returns source 'session' for bash when session rules match", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "git *",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "bash",
+      { command: "git status --short" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+    assert.equal(result.matchedPattern, "git *");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission returns source 'session' for bash when session rule is exact match", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "ls",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "bash",
+      { command: "ls" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission falls back to config for bash when session rules do not match the command", () => {
+  const { manager, cleanup } = createManager({ permission: { bash: "deny" } });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "git *",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "bash",
+      { command: "npm run build" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "deny");
+    assert.equal(result.source, "bash");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission returns source 'session' for mcp when session rules match the target", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "mcp",
+        pattern: "exa:*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "mcp",
+      { tool: "exa:search" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission returns source 'session' for skill when session rules match", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "skill",
+        pattern: "librarian",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "skill",
+      { name: "librarian" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+    assert.equal(result.matchedPattern, "librarian");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission returns source 'session' for tool surface when session rules match", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "read",
+        pattern: "*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission("read", {}, undefined, sessionRules);
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});
+
+test("bash session rules do not bleed into mcp checks", () => {
+  const { manager, cleanup } = createManager({ permission: {} });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "git *",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "mcp",
+      { tool: "exa:search" },
+      undefined,
+      sessionRules,
+    );
+    // bash session rule must not affect mcp surface
+    assert.notEqual(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});
+
 // Suppress unused import warning — PermissionState used in type annotations
 const _unused: PermissionState = "ask";
 void _unused;