@gotgenes/pi-permission-system 3.10.0 → 3.11.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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).
 
+## [3.11.0](https://github.com/gotgenes/pi-permission-system/compare/v3.10.0...v3.11.0) (2026-05-04)
+
+
+### Features
+
+* add "session" source to PermissionCheckResult ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([039ae26](https://github.com/gotgenes/pi-permission-system/commit/039ae26c5756ae51d97da27aee53a7ca8b55fa91))
+* add synthesize module (synthesizeDefaults, synthesizeOverrides, synthesizeBaseline, composeRuleset) ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([e0469b2](https://github.com/gotgenes/pi-permission-system/commit/e0469b26a49cdb2858b1d441615f5511d5c271d5))
+* compose ruleset with synthesized defaults and overrides ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([dac47c1](https://github.com/gotgenes/pi-permission-system/commit/dac47c1ce4fe6b98ee657e2cb7dca46c1dbf5c89))
+* remove separate session pre-check from tool_call ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([d156e9b](https://github.com/gotgenes/pi-permission-system/commit/d156e9be08c053ebe62bb5f198d3f0ee411c6728))
+* tag session rules with layer metadata ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([2346f95](https://github.com/gotgenes/pi-permission-system/commit/2346f957e0e552846870576c129f1fc8a620ef0d))
+
+
+### Documentation
+
+* drop backward-compat language for config format ([#66](https://github.com/gotgenes/pi-permission-system/issues/66)) ([fabde91](https://github.com/gotgenes/pi-permission-system/commit/fabde91e86afc08ac8ccf11c211a701d01a4d91a))
+* plan generalized session approvals and update target architecture ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([23a019a](https://github.com/gotgenes/pi-permission-system/commit/23a019af3ef381f89a145ab8d435c2447b538894))
+* plan synthesize defaults into ruleset and unify evaluate path ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([295fd10](https://github.com/gotgenes/pi-permission-system/commit/295fd10d77827b547ad14c50d73709c3f45cbebf))
+* **retro:** add retro notes for issue [#57](https://github.com/gotgenes/pi-permission-system/issues/57) ([cffb3a5](https://github.com/gotgenes/pi-permission-system/commit/cffb3a56ee8059015f89bbe7ba2922eee45d3dda))
+* update architecture for synthesized defaults and deprecate getSurfaceDefault() ([#65](https://github.com/gotgenes/pi-permission-system/issues/65)) ([e703809](https://github.com/gotgenes/pi-permission-system/commit/e7038090ce9e8b42e6f4c4423bcf8c03fb1aa3ea))
+
 ## [3.10.0](https://github.com/gotgenes/pi-permission-system/compare/v3.9.0...v3.10.0) (2026-05-04)
 
 

package/package.json

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

package/src/defaults.ts

@@ -26,6 +26,12 @@ const SURFACE_TO_DEFAULT_KEY: Record<string, keyof PermissionDefaultPolicy> = {
  * - "bash", "mcp", "skill" → dedicated defaultPolicy key
  * - special-key surfaces (e.g. "external_directory") → defaults.special
  * - everything else (tool-name surfaces) → defaults.tools
+ *
+ * @deprecated Default policy is now synthesized into the composed ruleset via
+ * `synthesizeDefaults()` in `src/synthesize.ts`. Call-sites that previously
+ * consulted this function can evaluate against the composed ruleset instead.
+ * This function is kept for backward compatibility and will be removed in a
+ * future cleanup.
  */
 export function getSurfaceDefault(
   surface: string,

package/src/handlers/tool-call.ts

@@ -29,7 +29,6 @@ import {
   formatUnknownToolReason,
   formatUserDeniedReason,
 } from "../permission-prompts";
-import { evaluate } from "../rule";
 import { deriveApprovalPattern } from "../session-rules";
 import { findSkillPathMatch } from "../skill-prompt-sanitizer";
 import { getPermissionLogContext } from "../tool-input-preview";
@@ -170,15 +169,14 @@ export async function handleToolCall(
       externalDirectoryPath,
       ctx.cwd,
     );
-    const sessionRuleset = deps.runtime.sessionRules.getRuleset();
-    const sessionMatch = evaluate(
+    const extCheck = deps.runtime.permissionManager.checkPermission(
       "external_directory",
-      normalizedExtPath,
-      sessionRuleset,
+      { path: normalizedExtPath },
+      agentName ?? undefined,
+      deps.runtime.sessionRules.getRuleset(),
     );
-    const isSessionApproved = sessionRuleset.includes(sessionMatch);
 
-    if (isSessionApproved) {
+    if (extCheck.source === "session") {
       deps.runtime.writeReviewLog("permission_request.session_approved", {
         source: "tool_call",
         toolCallId: (event as { toolCallId: string }).toolCallId,
@@ -186,16 +184,10 @@ export async function handleToolCall(
         agentName,
         path: externalDirectoryPath,
         resolution: "session_approved",
-        sessionApprovalPattern: sessionMatch.pattern,
+        sessionApprovalPattern: extCheck.matchedPattern,
       });
       // Fall through to normal permission check
     } else {
-      const extCheck = deps.runtime.permissionManager.checkPermission(
-        "external_directory",
-        {},
-        agentName ?? undefined,
-      );
-
       let extDirDecision: PermissionPromptDecision | null = null;
       const extDirMessage = formatExternalDirectoryAskPrompt(
         toolName,
@@ -265,12 +257,15 @@ export async function handleToolCall(
         ctx.cwd,
       );
       if (externalPaths.length > 0) {
-        const bashSessionRuleset = deps.runtime.sessionRules.getRuleset();
+        const bashSessionRules = deps.runtime.sessionRules.getRuleset();
         const uncoveredPaths = externalPaths.filter(
           (p) =>
-            !bashSessionRuleset.includes(
-              evaluate("external_directory", p, bashSessionRuleset),
-            ),
+            deps.runtime.permissionManager.checkPermission(
+              "external_directory",
+              { path: p },
+              agentName ?? undefined,
+              bashSessionRules,
+            ).source !== "session",
         );
 
         if (uncoveredPaths.length === 0) {
@@ -285,6 +280,7 @@ export async function handleToolCall(
           });
           // Fall through to normal bash permission check
         } else {
+          // Get the config-level policy (no path → no session check).
           const extCheck = deps.runtime.permissionManager.checkPermission(
             "external_directory",
             {},
@@ -361,6 +357,7 @@ export async function handleToolCall(
     toolName,
     input,
     agentName ?? undefined,
+    deps.runtime.sessionRules.getRuleset(),
   );
   const permissionLogContext = getPermissionLogContext(
     check,

package/src/permission-manager.ts

@@ -15,6 +15,12 @@ import { mergeDefaults } from "./defaults";
 import { normalizeConfig } from "./normalize";
 import type { Ruleset } from "./rule";
 import { evaluate } from "./rule";
+import {
+  composeRuleset,
+  synthesizeBaseline,
+  synthesizeDefaults,
+  synthesizeOverrides,
+} from "./synthesize";
 import type {
   PermissionCheckResult,
   PermissionDefaultPolicy,
@@ -42,14 +48,6 @@ const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "ls",
 ]);
 const SPECIAL_PERMISSION_KEYS = new Set(["external_directory"]);
-const MCP_BASELINE_TARGETS = new Set([
-  "mcp_status",
-  "mcp_list",
-  "mcp_search",
-  "mcp_describe",
-  "mcp_connect",
-]);
-
 const DEFAULT_POLICY: PermissionDefaultPolicy = {
   tools: "ask",
   bash: "ask",
@@ -364,13 +362,11 @@ export interface ResolvedPolicyPaths {
 }
 
 type ResolvedPermissions = {
-  rules: Ruleset;
-  defaults: PermissionDefaultPolicy;
-  /** tools.bash fallback: tools.bash || defaults.bash */
-  bashDefault: PermissionState;
-  /** tools.mcp fallback (undefined = no explicit tools.mcp) */
-  mcpToolLevel: PermissionState | undefined;
-  hasAnyMcpAllowRule: boolean;
+  /**
+   * Fully composed ruleset: synthesized defaults → baseline → overrides → config.
+   * Session rules are appended at call-time inside checkPermission().
+   */
+  composedRules: Ruleset;
 };
 
 type FileCacheEntry<TValue> = {
@@ -599,16 +595,20 @@ export class PermissionManager {
     const agentConfig = this.loadScopeConfig(agentName);
     const projectAgentConfig = this.loadProjectScopeConfig(agentName);
 
-    // Normalize each scope into a flat Ruleset and concatenate.
-    // Later scopes appear last → higher priority via last-match-wins.
-    const rules: Ruleset = [
-      ...normalizeConfig(globalConfig),
-      ...normalizeConfig(projectConfig),
-      ...normalizeConfig(agentConfig),
-      ...normalizeConfig(projectAgentConfig),
+    // Tag config rules with layer "config" so checkPermission() can derive
+    // the result source and matchedPattern without positional arithmetic.
+    const tagConfig = (r: import("./rule").Rule) => ({
+      ...r,
+      layer: "config" as const,
+    });
+    const configRules: Ruleset = [
+      ...normalizeConfig(globalConfig).map(tagConfig),
+      ...normalizeConfig(projectConfig).map(tagConfig),
+      ...normalizeConfig(agentConfig).map(tagConfig),
+      ...normalizeConfig(projectAgentConfig).map(tagConfig),
     ];
 
-    // Merge defaults separately (shallow spread, same precedence order).
+    // Merge defaultPolicy across scopes (shallow spread, same precedence).
     const defaults = mergeDefaults(
       globalConfig.defaultPolicy,
       projectConfig.defaultPolicy,
@@ -616,32 +616,26 @@ export class PermissionManager {
       projectAgentConfig.defaultPolicy,
     );
 
-    // tools.bash / tools.mcp are fallback overrides, not catch-all rules.
-    // Extract with last-scope-wins precedence.
-    const toolBash =
-      projectAgentConfig.tools?.bash ??
-      agentConfig.tools?.bash ??
-      projectConfig.tools?.bash ??
-      globalConfig.tools?.bash;
-    const bashDefault = toolBash ?? defaults.bash;
-
-    const mcpToolLevel =
-      projectAgentConfig.tools?.mcp ??
-      agentConfig.tools?.mcp ??
-      projectConfig.tools?.mcp ??
-      globalConfig.tools?.mcp;
-
-    const hasAnyMcpAllowRule = rules.some(
-      (r) => r.surface === "mcp" && r.action === "allow",
+    // tools.bash / tools.mcp overrides: per-scope, lowest-priority first so
+    // that later scopes win via last-match-wins in synthesizeOverrides.
+    const overrideScopes = [
+      { bash: globalConfig.tools?.bash, mcp: globalConfig.tools?.mcp },
+      { bash: projectConfig.tools?.bash, mcp: projectConfig.tools?.mcp },
+      { bash: agentConfig.tools?.bash, mcp: agentConfig.tools?.mcp },
+      {
+        bash: projectAgentConfig.tools?.bash,
+        mcp: projectAgentConfig.tools?.mcp,
+      },
+    ];
+
+    const composedRules = composeRuleset(
+      synthesizeDefaults(defaults),
+      synthesizeBaseline(configRules),
+      synthesizeOverrides(overrideScopes),
+      configRules,
     );
 
-    const value: ResolvedPermissions = {
-      rules,
-      defaults,
-      bashDefault,
-      mcpToolLevel,
-      hasAnyMcpAllowRule,
-    };
+    const value: ResolvedPermissions = { composedRules };
 
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
     return value;
@@ -679,47 +673,69 @@ export class PermissionManager {
    * @returns The permission state for the tool at the tool level
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
-    const { rules, defaults, bashDefault, mcpToolLevel } =
-      this.resolvePermissions(agentName);
+    const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
-    // Special keys use the special default.
+    // Special surfaces: evaluate via the "special" surface used by config rules
+    // and the synthesized special default.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const rule = evaluate("special", normalizedToolName, rules);
-      if (rules.includes(rule)) return rule.action;
-      return defaults.special;
+      return evaluate("special", normalizedToolName, composedRules).action;
     }
 
-    // Bash and MCP have dedicated fallback overrides from tools.bash / tools.mcp.
-    if (normalizedToolName === "bash") return bashDefault;
-    if (normalizedToolName === "mcp") return mcpToolLevel ?? defaults.mcp;
-
-    // Skills use the skills default.
-    if (normalizedToolName === "skill") return defaults.skills;
+    // For bash, mcp, skill: evaluate with "*" value against composedRules.
+    // The synthesized override/default rules are catch-alls (pattern "*") that
+    // respond correctly to a "*" lookup without matching specific patterns.
+    if (normalizedToolName === "bash") {
+      return evaluate("bash", "*", composedRules).action;
+    }
+    if (normalizedToolName === "mcp") {
+      return evaluate("mcp", "*", composedRules).action;
+    }
+    if (normalizedToolName === "skill") {
+      return evaluate("skill", "*", composedRules).action;
+    }
 
-    // Tool-name surfaces: check rules, fall back to tools default.
-    const rule = evaluate(normalizedToolName, "*", rules);
-    if (rules.includes(rule)) return rule.action;
-    return defaults.tools;
+    // Tool-name surfaces (read, write, etc. and extension tools).
+    return evaluate(normalizedToolName, "*", composedRules).action;
   }
 
   checkPermission(
     toolName: string,
     input: unknown,
     agentName?: string,
+    sessionRules?: Ruleset,
   ): PermissionCheckResult {
-    const { rules, defaults, bashDefault, mcpToolLevel, hasAnyMcpAllowRule } =
-      this.resolvePermissions(agentName);
+    const { composedRules } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
     // --- Special surfaces (external_directory) ---
+    // Config/default rules use surface "special"; session rules use surface
+    // "external_directory" with path patterns. Check each independently.
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
-      const rule = evaluate("special", normalizedToolName, rules);
-      const explicit = rules.includes(rule);
+      // Session check: match by specific normalized path.
+      const record = toRecord(input);
+      const pathValue = typeof record.path === "string" ? record.path : null;
+      if (pathValue && sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate(
+          "external_directory",
+          pathValue,
+          sessionRules,
+        );
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+      // Config/default check.
+      const rule = evaluate("special", normalizedToolName, composedRules);
       return {
         toolName,
-        state: explicit ? rule.action : defaults.special,
-        matchedPattern: explicit ? rule.pattern : undefined,
+        state: rule.action,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "special",
       };
     }
@@ -727,19 +743,12 @@ export class PermissionManager {
     // --- Skills ---
     if (normalizedToolName === "skill") {
       const skillName = toRecord(input).name;
-      if (typeof skillName === "string") {
-        const rule = evaluate("skill", skillName, rules);
-        const explicit = rules.includes(rule);
-        return {
-          toolName,
-          state: explicit ? rule.action : defaults.skills,
-          matchedPattern: explicit ? rule.pattern : undefined,
-          source: explicit ? "skill" : "skill",
-        };
-      }
+      const lookupValue = typeof skillName === "string" ? skillName : "*";
+      const rule = evaluate("skill", lookupValue, composedRules);
       return {
         toolName,
-        state: defaults.skills,
+        state: rule.action,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "skill",
       };
     }
@@ -748,13 +757,12 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
-      const rule = evaluate("bash", command, rules);
-      const explicit = rules.includes(rule);
+      const rule = evaluate("bash", command, composedRules);
       return {
         toolName,
-        state: explicit ? rule.action : bashDefault,
+        state: rule.action,
         command,
-        matchedPattern: explicit ? rule.pattern : undefined,
+        matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
         source: "bash",
       };
     }
@@ -770,67 +778,39 @@ export class PermissionManager {
       ];
       const fallbackTarget = mcpTargets[0] || "mcp";
 
-      // Try each candidate target against the merged rules.
+      // Try each candidate target. Stop on the first non-default match
+      // (config, override, or baseline rule). Default rules are catch-alls
+      // that would fire on every target — skip them so more-specific targets
+      // can be checked first.
       for (const target of mcpTargets) {
-        const rule = evaluate("mcp", target, rules);
-        if (rules.includes(rule)) {
+        const rule = evaluate("mcp", target, composedRules);
+        if (rule.layer !== "default") {
           return {
             toolName,
             state: rule.action,
-            matchedPattern: rule.pattern,
+            matchedPattern: rule.layer === "config" ? rule.pattern : undefined,
             target,
-            source: "mcp",
-          };
-        }
-      }
-
-      // tools.mcp fallback (e.g. tools: { mcp: "allow" }).
-      if (mcpToolLevel) {
-        return {
-          toolName,
-          state: mcpToolLevel,
-          target: fallbackTarget,
-          source: "tool",
-        };
-      }
-
-      // Baseline auto-allow: if this is a metadata operation and at least one
-      // MCP rule allows something (or the default is allow), auto-allow.
-      const baselineTarget = mcpTargets.find((target) =>
-        MCP_BASELINE_TARGETS.has(target),
-      );
-      if (baselineTarget) {
-        if (hasAnyMcpAllowRule || defaults.mcp === "allow") {
-          return {
-            toolName,
-            state: "allow",
-            target: baselineTarget,
-            source: "mcp",
+            source: rule.layer === "override" ? "tool" : "mcp",
           };
         }
       }
 
+      // All targets matched only the synthesized default.
+      const defaultRule = evaluate("mcp", fallbackTarget, composedRules);
       return {
         toolName,
-        state: defaults.mcp,
+        state: defaultRule.action,
         target: fallbackTarget,
         source: "default",
       };
     }
 
     // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
-    const rule = evaluate(normalizedToolName, "*", rules);
-    const explicit = rules.includes(rule);
+    const rule = evaluate(normalizedToolName, "*", composedRules);
 
+    // Built-in tools always report source "tool" regardless of which layer
+    // supplied the decision (matches current behaviour).
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
-      return {
-        toolName,
-        state: explicit ? rule.action : defaults.tools,
-        source: "tool",
-      };
-    }
-
-    if (explicit) {
       return {
         toolName,
         state: rule.action,
@@ -838,10 +818,12 @@ export class PermissionManager {
       };
     }
 
+    // Extension tools: "default" layer → source "default"; any explicit rule
+    // (config or override) → source "tool".
     return {
       toolName,
-      state: defaults.tools,
-      source: "default",
+      state: rule.action,
+      source: rule.layer === "default" ? "default" : "tool",
     };
   }
 }

package/src/rule.ts

@@ -9,6 +9,11 @@ export interface Rule {
   pattern: string;
   /** The permission decision. */
   action: PermissionState;
+  /**
+   * Origin layer — used to derive PermissionCheckResult.source after evaluation.
+   * Not used by evaluate(); purely informational metadata.
+   */
+  layer?: "default" | "override" | "baseline" | "config" | "session";
 }
 
 /** An ordered list of rules. Later rules take priority (last-match-wins). */

package/src/session-rules.ts

@@ -15,7 +15,7 @@ export class SessionRules {
 
   /** Record a wildcard pattern as approved for the given surface. */
   approve(surface: string, pattern: string): void {
-    this.rules.push({ surface, pattern, action: "allow" });
+    this.rules.push({ surface, pattern, action: "allow", layer: "session" });
   }
 
   /** Return a defensive copy of the current session ruleset. */

package/src/synthesize.ts

@@ -0,0 +1,152 @@
+import type { Rule, Ruleset } from "./rule";
+import type { PermissionDefaultPolicy, PermissionState } from "./types";
+
+/**
+ * Convert the merged `defaultPolicy` into catch-all rules at the lowest
+ * priority position in the composed ruleset.
+ *
+ * Produces 5 rules:
+ * 1. `{ surface: "*", pattern: "*" }` — universal fallback (tools default)
+ * 2. `{ surface: "bash", pattern: "*" }` — bash default
+ * 3. `{ surface: "mcp", pattern: "*" }` — mcp default
+ * 4. `{ surface: "skill", pattern: "*" }` — skill default
+ * 5. `{ surface: "special", pattern: "*" }` — special / external_directory default
+ *
+ * All rules carry `layer: "default"`. `evaluate()` ignores this field.
+ * The specific per-surface rules come after the universal rule so they win
+ * via last-match-wins when a surface-specific default differs from the
+ * tools default.
+ */
+export function synthesizeDefaults(defaults: PermissionDefaultPolicy): Ruleset {
+  return [
+    { surface: "*", pattern: "*", action: defaults.tools, layer: "default" },
+    { surface: "bash", pattern: "*", action: defaults.bash, layer: "default" },
+    { surface: "mcp", pattern: "*", action: defaults.mcp, layer: "default" },
+    {
+      surface: "skill",
+      pattern: "*",
+      action: defaults.skills,
+      layer: "default",
+    },
+    {
+      surface: "special",
+      pattern: "*",
+      action: defaults.special,
+      layer: "default",
+    },
+  ];
+}
+
+/**
+ * Per-scope override shape — the relevant keys extracted from `tools`.
+ * `undefined` means the scope did not configure that override.
+ */
+export interface OverrideScope {
+  bash?: PermissionState;
+  mcp?: PermissionState;
+}
+
+/**
+ * Convert per-scope `tools.bash` / `tools.mcp` entries into catch-all rules
+ * placed between defaults and config rules.
+ *
+ * Scopes must be passed in precedence order (lowest first, e.g. global →
+ * project → agent → project-agent). Later scopes produce later rules and
+ * therefore win via last-match-wins — identical to the current last-scope-wins
+ * logic for `bashDefault` / `mcpToolLevel`.
+ *
+ * Only scopes that explicitly define a value contribute a rule; `undefined`
+ * entries are skipped.
+ *
+ * All rules carry `layer: "override"`.
+ */
+export function synthesizeOverrides(
+  scopes: ReadonlyArray<OverrideScope>,
+): Ruleset {
+  const rules: Rule[] = [];
+  for (const scope of scopes) {
+    if (scope.bash !== undefined) {
+      rules.push({
+        surface: "bash",
+        pattern: "*",
+        action: scope.bash,
+        layer: "override",
+      });
+    }
+    if (scope.mcp !== undefined) {
+      rules.push({
+        surface: "mcp",
+        pattern: "*",
+        action: scope.mcp,
+        layer: "override",
+      });
+    }
+  }
+  return rules;
+}
+
+/**
+ * MCP metadata operation targets that are auto-allowed when any explicit MCP
+ * allow rule exists in the config layer.
+ */
+const MCP_BASELINE_TARGETS: readonly string[] = [
+  "mcp_status",
+  "mcp_list",
+  "mcp_search",
+  "mcp_describe",
+  "mcp_connect",
+];
+
+/**
+ * Conditionally synthesize MCP baseline auto-allow rules.
+ *
+ * Emits allow rules for the 5 MCP metadata targets only when `configRules`
+ * contains at least one `surface: "mcp", action: "allow"` rule. This replicates
+ * the `hasAnyMcpAllowRule` heuristic as actual rules.
+ *
+ * When `defaults.mcp === "allow"`, the synthesized default catch-all already
+ * covers all MCP targets — no separate baseline rules are needed (and this
+ * function is not called in that case).
+ *
+ * Baseline rules are placed BEFORE override rules in the composed array so
+ * that `tools.mcp` overrides beat baseline (preserving current behaviour where
+ * an explicit `tools.mcp` value always terminates the MCP decision).
+ *
+ * All rules carry `layer: "baseline"`.
+ */
+export function synthesizeBaseline(configRules: Ruleset): Ruleset {
+  const hasAnyMcpAllow = configRules.some(
+    (r) => r.surface === "mcp" && r.action === "allow",
+  );
+  if (!hasAnyMcpAllow) {
+    return [];
+  }
+  return MCP_BASELINE_TARGETS.map(
+    (target): Rule => ({
+      surface: "mcp",
+      pattern: target,
+      action: "allow",
+      layer: "baseline",
+    }),
+  );
+}
+
+/**
+ * Concatenate all rule layers into a single flat ruleset.
+ *
+ * Priority order (lowest → highest, i.e. earlier index → later index):
+ *   defaults → baseline → overrides → config
+ *
+ * Session rules are NOT included here — they are appended at call-time inside
+ * `checkPermission()` so that the cached composed ruleset remains session-agnostic.
+ *
+ * `evaluate()` scans from the end, so later layers override earlier ones.
+ */
+export function composeRuleset(
+  defaults: Ruleset,
+  baseline: Ruleset,
+  overrides: Ruleset,
+  config: Ruleset,
+): Ruleset {
+  return [...defaults, ...baseline, ...overrides, ...config];
+}

package/src/types.ts

@@ -41,5 +41,5 @@ export interface PermissionCheckResult {
   matchedPattern?: string;
   command?: string;
   target?: string;
-  source: "tool" | "bash" | "mcp" | "skill" | "special" | "default";
+  source: "tool" | "bash" | "mcp" | "skill" | "special" | "default" | "session";
 }

package/tests/permission-system.test.ts

@@ -46,7 +46,11 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../src/tool-registry";
-import type { PermissionState, ScopeConfig } from "../src/types";
+import type {
+  PermissionCheckResult,
+  PermissionState,
+  ScopeConfig,
+} from "../src/types";
 import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
@@ -2969,3 +2973,193 @@ test("session approval: regular 'Yes' does not create session approval", async (
     rmSync(rootDir, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// Session-aware checkPermission() integration
+// ---------------------------------------------------------------------------
+
+test("checkPermission returns source 'session' when session rules cover the external_directory path", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/src/foo.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+    assert.equal(result.matchedPattern, "/other/project/*");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission falls back to config policy when session rules do not cover the path", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "deny",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Path NOT under /other/project/ — session rules don't match.
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/completely/different/path.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "deny");
+    assert.equal(result.source, "special");
+  } finally {
+    cleanup();
+  }
+});
+
+test("checkPermission with empty session rules is identical to call without sessionRules arg", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+    special: { external_directory: "deny" },
+  });
+
+  try {
+    const withEmpty = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/foo.ts" },
+      undefined,
+      [],
+    );
+    const withoutArg = manager.checkPermission("external_directory", {
+      path: "/other/project/foo.ts",
+    });
+    const expected: PermissionCheckResult = {
+      toolName: "external_directory",
+      state: "deny",
+      matchedPattern: "external_directory",
+      source: "special",
+    };
+    assert.deepEqual(withEmpty, expected);
+    assert.deepEqual(withoutArg, expected);
+  } finally {
+    cleanup();
+  }
+});
+
+test("session rules for one surface do not affect checks on other surfaces", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "ask",
+      bash: "ask",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Bash check — session rules should not affect bash decisions.
+    const bashResult = manager.checkPermission(
+      "bash",
+      { command: "git status" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(bashResult.state, "ask");
+    assert.equal(bashResult.source, "bash");
+
+    // MCP check — session rules should not affect MCP decisions.
+    const mcpResult = manager.checkPermission(
+      "mcp",
+      { tool: "exa:search" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(mcpResult.state, "ask");
+    assert.equal(mcpResult.source, "default");
+  } finally {
+    cleanup();
+  }
+});
+
+test("session rules override config deny for external_directory", () => {
+  const { manager, cleanup } = createManager({
+    defaultPolicy: {
+      tools: "allow",
+      bash: "allow",
+      mcp: "allow",
+      skills: "allow",
+      special: "ask",
+    },
+    special: { external_directory: "deny" },
+  });
+
+  try {
+    const sessionRules = [
+      {
+        surface: "external_directory",
+        pattern: "/other/project/*",
+        action: "allow" as const,
+        layer: "session" as const,
+      },
+    ];
+
+    // Session approval overrides config deny for the covered path.
+    const result = manager.checkPermission(
+      "external_directory",
+      { path: "/other/project/src/foo.ts" },
+      undefined,
+      sessionRules,
+    );
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "session");
+  } finally {
+    cleanup();
+  }
+});

package/tests/rule.test.ts

@@ -137,4 +137,35 @@ describe("evaluate", () => {
     expect(result.pattern).toBe("git status");
     expect(result.action).toBe("ask");
   });
+
+  test("rule.layer is ignored by evaluate() — matching is identical with or without it", () => {
+    const withLayer: Rule = {
+      surface: "bash",
+      pattern: "git *",
+      action: "allow",
+      layer: "config",
+    };
+    const withoutLayer: Rule = {
+      surface: "bash",
+      pattern: "git *",
+      action: "allow",
+    };
+    const withDefault: Rule = {
+      surface: "bash",
+      pattern: "*",
+      action: "ask",
+      layer: "default",
+    };
+    // Both rules with and without layer field produce the same match.
+    expect(evaluate("bash", "git status", [withLayer]).action).toBe("allow");
+    expect(evaluate("bash", "git status", [withoutLayer]).action).toBe("allow");
+    // Layer metadata does not affect last-match-wins ordering.
+    const ruleset: Rule[] = [withDefault, withLayer];
+    expect(evaluate("bash", "git status", ruleset)).toEqual(withLayer);
+    // A rule with layer: "default" still wins if it is last in the array.
+    const reversedRuleset: Rule[] = [withLayer, withDefault];
+    expect(evaluate("bash", "git status", reversedRuleset)).toEqual(
+      withDefault,
+    );
+  });
 });

package/tests/session-rules.test.ts

@@ -20,6 +20,7 @@ describe("SessionRules", () => {
           surface: "external_directory",
           pattern: "/other/project/*",
           action: "allow",
+          layer: "session",
         },
       ]);
     });

package/tests/synthesize.test.ts

@@ -0,0 +1,413 @@
+import { describe, expect, test } from "vitest";
+import { evaluate } from "../src/rule";
+import {
+  composeRuleset,
+  synthesizeBaseline,
+  synthesizeDefaults,
+  synthesizeOverrides,
+} from "../src/synthesize";
+import type { PermissionDefaultPolicy } from "../src/types";
+
+const ALL_ASK: PermissionDefaultPolicy = {
+  tools: "ask",
+  bash: "ask",
+  mcp: "ask",
+  skills: "ask",
+  special: "ask",
+};
+
+const ALL_ALLOW: PermissionDefaultPolicy = {
+  tools: "allow",
+  bash: "allow",
+  mcp: "allow",
+  skills: "allow",
+  special: "allow",
+};
+
+// ── synthesizeDefaults ─────────────────────────────────────────────────────
+
+describe("synthesizeDefaults", () => {
+  test("emits 5 catch-all rules with layer 'default'", () => {
+    const rules = synthesizeDefaults(ALL_ASK);
+    expect(rules).toHaveLength(5);
+    for (const rule of rules) {
+      expect(rule.layer).toBe("default");
+      expect(rule.pattern).toBe("*");
+    }
+  });
+
+  test("emits universal catch-all for tools default", () => {
+    const rules = synthesizeDefaults(ALL_ASK);
+    const universal = rules.find((r) => r.surface === "*");
+    expect(universal).toEqual({
+      surface: "*",
+      pattern: "*",
+      action: "ask",
+      layer: "default",
+    });
+  });
+
+  test("emits per-surface catch-alls for bash, mcp, skill, special", () => {
+    const rules = synthesizeDefaults(ALL_ASK);
+    const surfaces = rules.map((r) => r.surface);
+    expect(surfaces).toContain("bash");
+    expect(surfaces).toContain("mcp");
+    expect(surfaces).toContain("skill");
+    expect(surfaces).toContain("special");
+  });
+
+  test("reflects non-ask actions correctly", () => {
+    const rules = synthesizeDefaults(ALL_ALLOW);
+    for (const rule of rules) {
+      expect(rule.action).toBe("allow");
+    }
+  });
+
+  test("mixed defaults produce correct per-surface actions", () => {
+    const mixed: PermissionDefaultPolicy = {
+      tools: "allow",
+      bash: "deny",
+      mcp: "ask",
+      skills: "allow",
+      special: "deny",
+    };
+    const rules = synthesizeDefaults(mixed);
+    const get = (surface: string) => rules.find((r) => r.surface === surface);
+    expect(get("*")?.action).toBe("allow"); // tools default
+    expect(get("bash")?.action).toBe("deny");
+    expect(get("mcp")?.action).toBe("ask");
+    expect(get("skill")?.action).toBe("allow");
+    expect(get("special")?.action).toBe("deny");
+  });
+
+  test("default rules catch any surface via the universal '*' entry", () => {
+    const rules = synthesizeDefaults(ALL_ASK);
+    // A brand-new surface "future_tool" should be caught by the universal rule.
+    const result = evaluate("future_tool", "*", rules);
+    expect(result.action).toBe("ask");
+    expect(result.layer).toBe("default");
+  });
+
+  test("specific surface default beats universal default (last-match-wins)", () => {
+    const mixed: PermissionDefaultPolicy = {
+      tools: "allow",
+      bash: "deny",
+      mcp: "ask",
+      skills: "ask",
+      special: "ask",
+    };
+    const rules = synthesizeDefaults(mixed);
+    // For bash, the specific bash rule (later in array) beats the universal rule.
+    const result = evaluate("bash", "git status", rules);
+    expect(result.action).toBe("deny");
+    expect(result.layer).toBe("default");
+  });
+});
+
+// ── synthesizeOverrides ────────────────────────────────────────────────────
+
+describe("synthesizeOverrides", () => {
+  test("returns empty ruleset for empty input", () => {
+    expect(synthesizeOverrides([])).toEqual([]);
+  });
+
+  test("returns empty ruleset when no scope has overrides", () => {
+    expect(synthesizeOverrides([{}, {}, {}])).toEqual([]);
+  });
+
+  test("emits a bash override rule for each scope that defines tools.bash", () => {
+    const rules = synthesizeOverrides([{ bash: "allow" }]);
+    expect(rules).toEqual([
+      { surface: "bash", pattern: "*", action: "allow", layer: "override" },
+    ]);
+  });
+
+  test("emits an mcp override rule for each scope that defines tools.mcp", () => {
+    const rules = synthesizeOverrides([{ mcp: "deny" }]);
+    expect(rules).toEqual([
+      { surface: "mcp", pattern: "*", action: "deny", layer: "override" },
+    ]);
+  });
+
+  test("emits both bash and mcp override rules when both are defined in a scope", () => {
+    const rules = synthesizeOverrides([{ bash: "allow", mcp: "deny" }]);
+    expect(rules).toHaveLength(2);
+    const bash = rules.find((r) => r.surface === "bash");
+    const mcp = rules.find((r) => r.surface === "mcp");
+    expect(bash?.action).toBe("allow");
+    expect(mcp?.action).toBe("deny");
+  });
+
+  test("later scopes produce later rules (higher priority via last-match-wins)", () => {
+    const rules = synthesizeOverrides([{ bash: "deny" }, { bash: "allow" }]);
+    const result = evaluate("bash", "git status", rules);
+    expect(result.action).toBe("allow"); // later scope wins
+  });
+
+  test("skips undefined fields and emits nothing for them", () => {
+    const rules = synthesizeOverrides([
+      { bash: undefined, mcp: "allow" },
+      { bash: "deny", mcp: undefined },
+    ]);
+    const bashRules = rules.filter((r) => r.surface === "bash");
+    const mcpRules = rules.filter((r) => r.surface === "mcp");
+    expect(bashRules).toHaveLength(1);
+    expect(mcpRules).toHaveLength(1);
+    expect(bashRules[0].action).toBe("deny");
+    expect(mcpRules[0].action).toBe("allow");
+  });
+
+  test("override rules all have layer 'override'", () => {
+    const rules = synthesizeOverrides([
+      { bash: "allow", mcp: "deny" },
+      { bash: "deny" },
+    ]);
+    for (const rule of rules) {
+      expect(rule.layer).toBe("override");
+    }
+  });
+});
+
+// ── synthesizeBaseline ─────────────────────────────────────────────────────
+
+describe("synthesizeBaseline", () => {
+  test("returns empty ruleset when config has no mcp allow rules", () => {
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "*",
+        action: "deny" as const,
+        layer: "config" as const,
+      },
+    ];
+    expect(synthesizeBaseline(configRules)).toEqual([]);
+  });
+
+  test("returns empty ruleset for empty config rules", () => {
+    expect(synthesizeBaseline([])).toEqual([]);
+  });
+
+  test("synthesizes 5 baseline rules when at least one mcp allow config rule exists", () => {
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "exa:*",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    const rules = synthesizeBaseline(configRules);
+    expect(rules).toHaveLength(5);
+  });
+
+  test("baseline rules all have layer 'baseline' and action 'allow'", () => {
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "exa:*",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    const rules = synthesizeBaseline(configRules);
+    for (const rule of rules) {
+      expect(rule.layer).toBe("baseline");
+      expect(rule.action).toBe("allow");
+      expect(rule.surface).toBe("mcp");
+    }
+  });
+
+  test("baseline rules cover the 5 MCP metadata targets", () => {
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "exa:*",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    const rules = synthesizeBaseline(configRules);
+    const patterns = rules.map((r) => r.pattern);
+    expect(patterns).toContain("mcp_status");
+    expect(patterns).toContain("mcp_list");
+    expect(patterns).toContain("mcp_search");
+    expect(patterns).toContain("mcp_describe");
+    expect(patterns).toContain("mcp_connect");
+  });
+
+  test("baseline is NOT synthesized when allow rule is on a non-mcp surface", () => {
+    const configRules = [
+      {
+        surface: "bash",
+        pattern: "git *",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    expect(synthesizeBaseline(configRules)).toEqual([]);
+  });
+
+  test("baseline is NOT synthesized when defaults.mcp === 'allow' but no config allow rules", () => {
+    // defaults.mcp === 'allow' is handled by the synthesized default catch-all, not baseline.
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "*",
+        action: "deny" as const,
+        layer: "config" as const,
+      },
+    ];
+    expect(synthesizeBaseline(configRules)).toEqual([]);
+  });
+
+  test("baseline auto-allows mcp_status when an mcp allow rule exists", () => {
+    const configRules = [
+      {
+        surface: "mcp",
+        pattern: "exa:*",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    const rules = synthesizeBaseline(configRules);
+    const result = evaluate("mcp", "mcp_status", rules);
+    expect(result.action).toBe("allow");
+    expect(result.layer).toBe("baseline");
+  });
+});
+
+// ── composeRuleset ─────────────────────────────────────────────────────────
+
+describe("composeRuleset", () => {
+  test("returns concatenation of all layers in order", () => {
+    const defaults = synthesizeDefaults(ALL_ASK);
+    const baseline = synthesizeBaseline([
+      { surface: "mcp", pattern: "exa:*", action: "allow", layer: "config" },
+    ]);
+    const overrides = synthesizeOverrides([{ bash: "allow" }]);
+    const config = [
+      { surface: "bash", pattern: "rm -rf *", action: "deny" as const },
+    ];
+    const composed = composeRuleset(defaults, baseline, overrides, config);
+    expect(composed.length).toBe(
+      defaults.length + baseline.length + overrides.length + config.length,
+    );
+  });
+
+  test("defaults come first (lowest priority), config comes last (highest priority)", () => {
+    const defaults = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "ask" as const,
+        layer: "default" as const,
+      },
+    ];
+    const baseline: never[] = [];
+    const overrides = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "allow" as const,
+        layer: "override" as const,
+      },
+    ];
+    const config = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "deny" as const,
+        layer: "config" as const,
+      },
+    ];
+    const composed = composeRuleset(defaults, baseline, overrides, config);
+    // Last-match-wins: config is last → deny wins for any bash command.
+    const result = evaluate("bash", "echo hello", composed);
+    expect(result.action).toBe("deny");
+    expect(result.layer).toBe("config");
+  });
+
+  test("override beats default when no config rule exists", () => {
+    const defaults = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "ask" as const,
+        layer: "default" as const,
+      },
+    ];
+    const overrides = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "allow" as const,
+        layer: "override" as const,
+      },
+    ];
+    const composed = composeRuleset(defaults, [], overrides, []);
+    const result = evaluate("bash", "echo hello", composed);
+    expect(result.action).toBe("allow");
+    expect(result.layer).toBe("override");
+  });
+
+  test("baseline beats default but override beats baseline", () => {
+    const defaults = [
+      {
+        surface: "mcp",
+        pattern: "*",
+        action: "ask" as const,
+        layer: "default" as const,
+      },
+    ];
+    const baseline = [
+      {
+        surface: "mcp",
+        pattern: "mcp_status",
+        action: "allow" as const,
+        layer: "baseline" as const,
+      },
+    ];
+    const overrides = [
+      {
+        surface: "mcp",
+        pattern: "*",
+        action: "deny" as const,
+        layer: "override" as const,
+      },
+    ];
+    const composed = composeRuleset(defaults, baseline, overrides, []);
+    // override beats baseline for mcp_status
+    const result = evaluate("mcp", "mcp_status", composed);
+    expect(result.action).toBe("deny");
+    expect(result.layer).toBe("override");
+  });
+
+  test("config beats override for specific patterns", () => {
+    const overrides = [
+      {
+        surface: "mcp",
+        pattern: "*",
+        action: "deny" as const,
+        layer: "override" as const,
+      },
+    ];
+    const config = [
+      {
+        surface: "mcp",
+        pattern: "exa_web_search",
+        action: "allow" as const,
+        layer: "config" as const,
+      },
+    ];
+    const composed = composeRuleset([], [], overrides, config);
+    const result = evaluate("mcp", "exa_web_search", composed);
+    expect(result.action).toBe("allow");
+    expect(result.layer).toBe("config");
+  });
+
+  test("handles empty layers gracefully", () => {
+    const defaults = synthesizeDefaults(ALL_ASK);
+    const composed = composeRuleset(defaults, [], [], []);
+    expect(composed).toEqual(defaults);
+  });
+});