@gotgenes/pi-permission-system 4.1.1 → 4.3.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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)
+
+
+### Features
+
+* replace shell-quote with tree-sitter-bash for AST-based path extraction ([7dce2a4](https://github.com/gotgenes/pi-permission-system/commit/7dce2a4d264d26171a1d54db265f12f3f1d342c6))
+
+
+### Documentation
+
+* note tree-sitter follow-up addressed by [#74](https://github.com/gotgenes/pi-permission-system/issues/74) ([bd835bd](https://github.com/gotgenes/pi-permission-system/commit/bd835bda62af9aa9149149c24ddb14927d52abf4))
+* note tree-sitter-bash AST parser in architecture docs ([ecec2a6](https://github.com/gotgenes/pi-permission-system/commit/ecec2a6db375434a4bc2f920a21741fe29786896))
+* plan tree-sitter-bash AST-based path extraction ([#74](https://github.com/gotgenes/pi-permission-system/issues/74)) ([1693794](https://github.com/gotgenes/pi-permission-system/commit/1693794fd423eaf872400a2a6dc3b0d0faeba13a))
+* rename current-architecture.md to v3-architecture.md ([38d91c5](https://github.com/gotgenes/pi-permission-system/commit/38d91c587a842caa71b32f379ed5723e73f490f4))
+* **retro:** add retro notes for issue [#73](https://github.com/gotgenes/pi-permission-system/issues/73) ([d73097d](https://github.com/gotgenes/pi-permission-system/commit/d73097d7dcda097fb79b6213b482bac8642f4a90))
+* update bash external-directory description for tree-sitter AST parser ([d022d3d](https://github.com/gotgenes/pi-permission-system/commit/d022d3d87ab0cc0192ba9adbaf3b9bf379dfa414))
+
 ## [4.1.1](https://github.com/gotgenes/pi-permission-system/compare/v4.1.0...v4.1.1) (2026-05-04)
 
 

package/README.md

@@ -91,7 +91,7 @@ The extension integrates via Pi's lifecycle hooks:
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries instead of raw multiline JSON
 - Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls so approvals can be audited without writing raw full payloads
 - Path-bearing file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) evaluate `permission.external_directory` before their normal tool permission when an explicit path points outside `ctx.cwd`
-- Bash commands are scanned for path tokens (absolute, `~/`, or `..`-relative) that resolve outside `ctx.cwd`; matching commands trigger the same `permission.external_directory` gate before the normal bash pattern check
+- Bash commands are parsed with a full bash AST (`web-tree-sitter` + `tree-sitter-bash`) to extract path-bearing arguments; only genuine command arguments and redirect destinations are checked — heredoc bodies, comments, and quoted string contents are correctly excluded — and paths that resolve outside `ctx.cwd` trigger the same `permission.external_directory` gate before the normal bash pattern check
 
 ## Configuration
 
@@ -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.1.1",
+  "version": "4.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [
@@ -56,13 +56,13 @@
     "@mariozechner/pi-coding-agent": "^0.72.1",
     "@mariozechner/pi-tui": "^0.72.1",
     "@types/node": "^25.6.0",
-    "@types/shell-quote": "^1.7.5",
     "markdownlint-cli2": "^0.22.1",
     "typescript": "6.0.3",
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "shell-quote": "^1.8.3"
+    "tree-sitter-bash": "^0.25.1",
+    "web-tree-sitter": "^0.26.8"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/external-directory.ts

@@ -1,8 +1,7 @@
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, normalize, resolve, sep } from "node:path";
 
-import { parse } from "shell-quote";
-
 import { getNonEmptyString, toRecord } from "./common";
 
 /**
@@ -157,6 +156,197 @@ export function formatBashExternalDirectoryDenyReason(
   return `${subject} is not permitted to run bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. ${formatExternalDirectoryHardStopHint()}`;
 }
 
+// ── tree-sitter-bash lazy parser ───────────────────────────────────────────
+
+/**
+ * Minimal subset of web-tree-sitter's SyntaxNode used by the AST walker.
+ * Defined locally so callers do not need to import web-tree-sitter types.
+ */
+interface TSNode {
+  readonly type: string;
+  readonly text: string;
+  readonly childCount: number;
+  child(index: number): TSNode | null;
+}
+
+/**
+ * Minimal subset of web-tree-sitter's Parser used by this module.
+ */
+interface TSParser {
+  parse(input: string): { rootNode: TSNode; delete(): void } | null;
+  delete(): void;
+}
+
+let parserPromise: Promise<TSParser> | null = null;
+
+async function initParser(): Promise<TSParser> {
+  // Use named imports — web-tree-sitter exports Parser as a named class.
+  const { Parser, Language } = await import("web-tree-sitter");
+  const req = createRequire(import.meta.url);
+  const treeSitterWasm = req.resolve("web-tree-sitter/web-tree-sitter.wasm");
+  await Parser.init({ locateFile: () => treeSitterWasm });
+
+  const parser = new Parser();
+  const bashWasm = req.resolve("tree-sitter-bash/tree-sitter-bash.wasm");
+  const bash = await Language.load(bashWasm);
+  parser.setLanguage(bash);
+  return parser as TSParser;
+}
+
+function getParser(): Promise<TSParser> {
+  if (!parserPromise) {
+    parserPromise = initParser();
+  }
+  return parserPromise;
+}
+
+/**
+ * Reset the cached parser promise.  Only used by tests to avoid
+ * cross-test pollution or to inject a mock parser.
+ */
+export function resetParserForTesting(): void {
+  parserPromise = null;
+}
+
+// ── AST walker ─────────────────────────────────────────────────────────────
+
+/**
+ * Node types whose subtrees must never be descended into for
+ * path extraction — their text content is not a command argument.
+ */
+const SKIP_SUBTREE_TYPES = new Set(["heredoc_body", "heredoc_end", "comment"]);
+
+/**
+ * Resolve the "shell value" of an argument node — the string the shell
+ * would pass to the command after quote removal.
+ *
+ * - `word`          → `.text` (already unquoted)
+ * - `raw_string`    → strip surrounding single quotes
+ * - `string`        → strip surrounding double quotes, concatenate children text
+ * - `concatenation` → concatenate resolved children
+ * - other           → `.text` as fallback
+ */
+function resolveNodeText(node: TSNode): string {
+  switch (node.type) {
+    case "word":
+      return node.text;
+    case "raw_string": {
+      // Strip surrounding single quotes: 'content' → content
+      const t = node.text;
+      if (t.length >= 2 && t[0] === "'" && t[t.length - 1] === "'") {
+        return t.slice(1, -1);
+      }
+      return t;
+    }
+    case "string": {
+      // Double-quoted string: concatenate the resolved text of inner children,
+      // skipping the quote-delimiter nodes (literal `"`).
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        // Skip the literal `"` delimiters
+        if (child.type === '"') continue;
+        result += resolveNodeText(child);
+      }
+      return result;
+    }
+    case "string_content":
+    case "simple_expansion":
+    case "expansion":
+      return node.text;
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        result += resolveNodeText(child);
+      }
+      return result;
+    }
+    default:
+      return node.text;
+  }
+}
+
+/**
+ * Recursively visit the AST and collect resolved text of nodes that
+ * represent command arguments or redirect destinations.
+ *
+ * Skips `heredoc_body`, `heredoc_end`, and `comment` subtrees entirely.
+ */
+function collectPathCandidateTokens(node: TSNode, tokens: string[]): void {
+  if (SKIP_SUBTREE_TYPES.has(node.type)) return;
+
+  // Extract arguments from `command` nodes (skip the command name).
+  if (node.type === "command") {
+    let seenCommandName = false;
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+
+      if (child.type === "command_name") {
+        seenCommandName = true;
+        continue;
+      }
+      // Skip variable_assignment nodes (FOO=/bar)
+      if (child.type === "variable_assignment") continue;
+
+      // If there was no explicit command_name node, the first word-like
+      // child is the command name itself — skip it.
+      if (
+        !seenCommandName &&
+        (child.type === "word" ||
+          child.type === "concatenation" ||
+          child.type === "string" ||
+          child.type === "raw_string")
+      ) {
+        seenCommandName = true;
+        continue;
+      }
+
+      // Argument nodes: resolve their text and collect.
+      if (
+        child.type === "word" ||
+        child.type === "concatenation" ||
+        child.type === "string" ||
+        child.type === "raw_string"
+      ) {
+        tokens.push(resolveNodeText(child));
+        continue;
+      }
+
+      // Recurse into other children (e.g. command_substitution nested in args)
+      collectPathCandidateTokens(child, tokens);
+    }
+    return;
+  }
+
+  // Extract redirect destinations from `file_redirect` nodes.
+  if (node.type === "file_redirect") {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+      if (
+        child.type === "word" ||
+        child.type === "concatenation" ||
+        child.type === "string" ||
+        child.type === "raw_string"
+      ) {
+        tokens.push(resolveNodeText(child));
+      }
+    }
+    return;
+  }
+
+  // For all other node types, recurse into children.
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    collectPathCandidateTokens(child, tokens);
+  }
+}
+
 /**
  * URL pattern to skip tokens that look like URLs rather than paths.
  */
@@ -200,18 +390,25 @@ function classifyTokenAsPathCandidate(token: string): string | null {
 
 /**
  * Extracts paths from a bash command string that resolve outside CWD.
- * Uses shell-quote to tokenize so that quoted strings, operators, and comments
- * are handled correctly, eliminating false positives from the old regex approach.
+ * Uses tree-sitter-bash to parse the command into a full AST, then walks
+ * command argument and redirect-destination nodes.  Heredoc bodies, comments,
+ * and other non-argument content are skipped, eliminating false positives.
  */
-export function extractExternalPathsFromBashCommand(
+export async function extractExternalPathsFromBashCommand(
   command: string,
   cwd: string,
-): string[] {
-  // shell-quote parse() returns strings (resolved arguments), operator objects,
-  // glob objects, and comment objects. Only string entries are path candidates.
-  const tokens = parse(command).filter(
-    (entry): entry is string => typeof entry === "string",
-  );
+): Promise<string[]> {
+  const parser = await getParser();
+  const tree = parser.parse(command);
+  if (!tree) return [];
+
+  const tokens: string[] = [];
+  try {
+    collectPathCandidateTokens(tree.rootNode, tokens);
+  } finally {
+    tree.delete();
+  }
+
   const seen = new Set<string>();
   const externalPaths: string[] = [];
 

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 {
@@ -252,7 +253,7 @@ export async function handleToolCall(
   if (ctx.cwd && toolName === "bash") {
     const command = getNonEmptyString(toRecord(input).command);
     if (command) {
-      const externalPaths = extractExternalPathsFromBashCommand(
+      const externalPaths = await extractExternalPathsFromBashCommand(
         command,
         ctx.cwd,
       );
@@ -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" };