@gotgenes/pi-permission-system 3.10.0 → 4.0.0

package/tests/permission-system.test.ts

@@ -31,10 +31,7 @@ import {
   SUBAGENT_ENV_HINT_KEYS,
   SUBAGENT_PARENT_SESSION_ENV_KEY,
 } from "../src/permission-forwarding";
-import {
-  normalizeRawPermission,
-  PermissionManager,
-} from "../src/permission-manager";
+import { PermissionManager } from "../src/permission-manager";
 import {
   findSkillPathMatch,
   parseAllSkillPromptSections,
@@ -46,7 +43,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,
@@ -514,20 +515,7 @@ test("Before-agent-start cache dedupes unchanged active-tool exposure and prompt
 
 test("Before-agent-start prompt cache invalidates on permission changes while runtime enforcement stays authoritative", () => {
   const { manager, globalConfigPath, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "allow",
-      mcp: "allow",
-      skills: "allow",
-      special: "allow",
-    },
-    tools: {
-      write: "deny",
-    },
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: {},
+    permission: { "*": "allow", write: "deny" },
   });
 
   try {
@@ -547,22 +535,7 @@ test("Before-agent-start prompt cache invalidates on permission changes while ru
     assert.equal(manager.checkPermission("write", {}, undefined).state, "deny");
 
     const updatedConfig = `${JSON.stringify(
-      {
-        defaultPolicy: {
-          tools: "allow",
-          bash: "allow",
-          mcp: "allow",
-          skills: "allow",
-          special: "allow",
-        },
-        tools: {
-          write: "allow",
-        },
-        bash: {},
-        mcp: {},
-        skills: {},
-        special: {},
-      },
+      { permission: { "*": "allow", write: "allow" } },
       null,
       2,
     )}\n`;
@@ -633,10 +606,6 @@ test("Permission-system logger respects debug toggle and keeps review log enable
     assert.equal(reviewWarning, undefined);
     assert.equal(existsSync(debugLogPath), false);
     assert.equal(existsSync(reviewLogPath), true);
-    assert.match(
-      readFileSync(reviewLogPath, "utf8"),
-      /permission_request\.waiting/,
-    );
 
     config.debugLog = true;
     const enabledDebugWarning = logger.debug("debug.enabled", { sample: true });
@@ -650,16 +619,7 @@ test("Permission-system logger respects debug toggle and keeps review log enable
 
 test("PermissionManager canonical built-in permission checking", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "deny",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {
-      read: "allow",
-    },
+    permission: { "*": "deny", read: "allow" },
   });
 
   try {
@@ -675,49 +635,26 @@ test("PermissionManager canonical built-in permission checking", () => {
   }
 });
 
-test("Bash patterns stay higher priority than tool-level bash fallback", () => {
-  const { manager, cleanup } = createManager(
-    {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
-      bash: {
-        "rm -rf *": "deny",
-      },
-    },
-    {
-      reviewer: `---
-name: reviewer
-permission:
-  tools:
-    bash: allow
----
-`,
+test("Bash specific deny patterns override catch-all within the same config", () => {
+  // In the flat format, patterns within a surface map are ordered by insertion.
+  // Last-match-wins means specific patterns placed AFTER the catch-all override it.
+  const { manager, cleanup } = createManager({
+    permission: {
+      "*": "ask",
+      bash: { "*": "allow", "rm -rf *": "deny" },
     },
-  );
+  });
 
   try {
-    const denied = manager.checkPermission(
-      "bash",
-      { command: "rm -rf build" },
-      "reviewer",
-    );
+    const denied = manager.checkPermission("bash", { command: "rm -rf build" });
     assert.equal(denied.state, "deny");
     assert.equal(denied.source, "bash");
     assert.equal(denied.matchedPattern, "rm -rf *");
 
-    const fallback = manager.checkPermission(
-      "bash",
-      { command: "echo hello" },
-      "reviewer",
-    );
-    assert.equal(fallback.state, "allow");
-    assert.equal(fallback.source, "bash");
-    assert.equal(fallback.matchedPattern, undefined);
+    const allowed = manager.checkPermission("bash", { command: "echo hello" });
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.source, "bash");
+    assert.equal(allowed.matchedPattern, "*");
   } finally {
     cleanup();
   }
@@ -725,17 +662,9 @@ permission:
 
 test("MCP wildcard matching uses the registered mcp tool", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    mcp: {
-      "*": "deny",
-      "research_*": "ask",
-      "research_query-*": "allow",
+    permission: {
+      "*": "ask",
+      mcp: { "*": "deny", "research_*": "ask", "research_query-*": "allow" },
     },
   });
 
@@ -748,12 +677,12 @@ test("MCP wildcard matching uses the registered mcp tool", () => {
     assert.equal(queryDocs.matchedPattern, "research_query-*");
     assert.equal(queryDocs.target, "research_query-docs");
 
-    const resolve = manager.checkPermission("mcp", {
+    const resolve2 = manager.checkPermission("mcp", {
       tool: "research:resolve-context",
     });
-    assert.equal(resolve.state, "ask");
-    assert.equal(resolve.matchedPattern, "research_*");
-    assert.equal(resolve.target, "research_resolve-context");
+    assert.equal(resolve2.state, "ask");
+    assert.equal(resolve2.matchedPattern, "research_*");
+    assert.equal(resolve2.target, "research_resolve-context");
 
     const unknown = manager.checkPermission("mcp", { tool: "search:provider" });
     assert.equal(unknown.state, "deny");
@@ -766,18 +695,10 @@ test("MCP wildcard matching uses the registered mcp tool", () => {
 
 test("Arbitrary extension tools use exact-name tool permissions instead of MCP fallback", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "deny",
-      bash: "ask",
-      mcp: "allow",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {
-      third_party_tool: "allow",
-    },
-    mcp: {
+    permission: {
       "*": "deny",
+      third_party_tool: "allow",
+      mcp: { "*": "deny" },
     },
   });
 
@@ -786,6 +707,8 @@ test("Arbitrary extension tools use exact-name tool permissions instead of MCP f
     assert.equal(allowed.state, "allow");
     assert.equal(allowed.source, "tool");
 
+    // another_extension_tool has no explicit rule — falls through to the
+    // universal default (permission["*"] = "deny") with source "default".
     const fallback = manager.checkPermission("another_extension_tool", {});
     assert.equal(fallback.state, "deny");
     assert.equal(fallback.source, "default");
@@ -796,17 +719,13 @@ test("Arbitrary extension tools use exact-name tool permissions instead of MCP f
 
 test("Skill permission matching", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    skills: {
+    permission: {
       "*": "ask",
-      "web-*": "deny",
-      "requesting-code-review": "allow",
+      skill: {
+        "*": "ask",
+        "web-*": "deny",
+        "requesting-code-review": "allow",
+      },
     },
   });
 
@@ -837,16 +756,9 @@ test("Skill permission matching", () => {
 test("MCP proxy tool infers server-prefixed aliases from configured server names", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
-      mcp: {
-        "exa_*": "deny",
-        exa_get_code_context_exa: "allow",
+      permission: {
+        "*": "ask",
+        mcp: { "exa_*": "deny", exa_get_code_context_exa: "allow" },
       },
     },
     {},
@@ -876,25 +788,8 @@ test("MCP server names in settings.json are not used — only mcp.json is consul
   const agentsDir = join(baseDir, "agents");
   mkdirSync(agentsDir, { recursive: true });
 
-  // Policy: allow any target prefixed with legacy-server, default mcp is ask.
-  // If legacy-server were known as a configured server name, a tool named
-  // "some_tool_legacy-server" would derive "legacy-server_some_tool_legacy-server"
-  // which matches this rule and returns "allow".
-  // After the fix, settings.json is ignored, so no server name is derived and the
-  // result falls through to the default mcp policy ("ask").
   const config: ScopeConfig = {
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {},
-    bash: {},
-    mcp: { "legacy-server_*": "allow" },
-    skills: {},
-    special: {},
+    permission: { "*": "ask", mcp: { "legacy-server_*": "allow" } },
   };
 
   writeFileSync(
@@ -902,9 +797,7 @@ test("MCP server names in settings.json are not used — only mcp.json is consul
     `${JSON.stringify(config, null, 2)}\n`,
     "utf8",
   );
-  // mcp.json does not know about legacy-server.
   writeFileSync(mcpConfigPath, JSON.stringify({ mcpServers: {} }), "utf8");
-  // settings.json has legacy-server — the legacy source that must now be ignored.
   writeFileSync(
     settingsJsonPath,
     JSON.stringify({ mcpServers: { "legacy-server": {} } }),
@@ -918,8 +811,6 @@ test("MCP server names in settings.json are not used — only mcp.json is consul
   });
 
   try {
-    // "legacy-server" must not be derived from settings.json.
-    // The bare tool name falls through to the default mcp policy → "ask".
     const result = manager.checkPermission("mcp", {
       tool: "some_tool_legacy-server",
     });
@@ -932,16 +823,9 @@ test("MCP server names in settings.json are not used — only mcp.json is consul
 test("MCP describe mode normalizes qualified tool names without duplicating server prefixes", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
-      mcp: {
-        "exa_*": "deny",
-        exa_web_search_exa: "allow",
+      permission: {
+        "*": "ask",
+        mcp: { "exa_*": "deny", exa_web_search_exa: "allow" },
       },
     },
     {},
@@ -966,17 +850,7 @@ test("MCP describe mode normalizes qualified tool names without duplicating serv
 
 test("Canonical tools map directly without legacy aliases", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {
-      find: "allow",
-      ls: "deny",
-    },
+    permission: { "*": "ask", find: "allow", ls: "deny" },
   });
 
   try {
@@ -992,23 +866,16 @@ test("Canonical tools map directly without legacy aliases", () => {
   }
 });
 
-test("tools.mcp acts as fallback allow for unmatched MCP targets", () => {
+test("mcp catch-all acts as fallback for unmatched MCP targets", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  tools:
-    mcp: allow
+  mcp: allow
 ---
 `,
     },
@@ -1021,31 +888,24 @@ permission:
       "reviewer",
     );
     assert.equal(result.state, "allow");
-    assert.equal(result.source, "tool");
+    assert.equal(result.source, "mcp");
     assert.equal(result.target, "exa_web_search_exa");
   } finally {
     cleanup();
   }
 });
 
-test("specific MCP rules override tools.mcp fallback", () => {
+test("specific MCP rules override mcp catch-all", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  tools:
-    mcp: allow
   mcp:
+    "*": allow
     exa_web_search_exa: deny
 ---
 `,
@@ -1070,24 +930,17 @@ permission:
   }
 });
 
-test("specific MCP rules still win when tools.mcp is deny", () => {
+test("specific MCP rules still win when mcp catch-all is deny", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  tools:
-    mcp: deny
   mcp:
+    "*": deny
     exa_web_search_exa: allow
 ---
 `,
@@ -1114,30 +967,23 @@ permission:
       "reviewer",
     );
     assert.equal(fallback.state, "deny");
-    assert.equal(fallback.source, "tool");
+    assert.equal(fallback.source, "mcp");
     assert.equal(fallback.target, "exa_other_exa");
   } finally {
     cleanup();
   }
 });
 
-test("partial agent defaultPolicy overrides preserve global defaults", () => {
+test("mcp catch-all in agent frontmatter overrides global default", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "deny",
-        bash: "deny",
-        mcp: "deny",
-        skills: "deny",
-        special: "deny",
-      },
+      permission: { "*": "deny" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  defaultPolicy:
-    mcp: allow
+  mcp: allow
 ---
 `,
     },
@@ -1154,7 +1000,7 @@ permission:
       "reviewer",
     );
     assert.equal(mcpResult.state, "allow");
-    assert.equal(mcpResult.source, "default");
+    assert.equal(mcpResult.source, "mcp");
   } finally {
     cleanup();
   }
@@ -1163,13 +1009,7 @@ permission:
 test("Agent frontmatter canonical tools resolve correctly", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "deny",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "deny" },
     },
     {
       reviewer: `---
@@ -1195,16 +1035,10 @@ permission:
   }
 });
 
-test("Only canonical built-ins support top-level shorthand in agent frontmatter", () => {
+test("All surface names work in agent frontmatter flat permission format", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "deny",
-        bash: "ask",
-        mcp: "deny",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "deny" },
     },
     {
       reviewer: `---
@@ -1223,17 +1057,18 @@ permission:
     assert.equal(findResult.state, "allow");
     assert.equal(findResult.source, "tool");
 
+    // In flat format any surface key works, including extension tools
     const taskResult = manager.checkPermission("task", {}, "reviewer");
-    assert.equal(taskResult.state, "deny");
-    assert.equal(taskResult.source, "default");
+    assert.equal(taskResult.state, "allow");
+    assert.equal(taskResult.source, "tool");
 
+    // mcp: allow catches all MCP targets
     const mcpResult = manager.checkPermission(
       "mcp",
       { tool: "exa:web_search_exa" },
       "reviewer",
     );
-    assert.equal(mcpResult.state, "deny");
-    assert.equal(mcpResult.source, "default");
+    assert.equal(mcpResult.state, "allow");
   } finally {
     cleanup();
   }
@@ -1241,16 +1076,7 @@ permission:
 
 test("task uses exact-name tool permissions like any registered extension tool", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "deny",
-      bash: "ask",
-      mcp: "allow",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {
-      task: "allow",
-    },
+    permission: { "*": "deny", task: "allow" },
   });
 
   try {
@@ -1303,22 +1129,15 @@ test("Tool registry blocks unregistered tools and handles aliases", () => {
 test("getToolPermission returns tool-level policy for canonical and extension tools", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  tools:
-    bash: deny
-    read: deny
-    task: allow
+  bash: deny
+  read: deny
+  task: allow
 ---
 `,
     },
@@ -1338,16 +1157,7 @@ permission:
     assert.equal(defaultBashPermission, "ask");
 
     const { manager: manager2, cleanup: cleanup2 } = createManager({
-      defaultPolicy: {
-        tools: "deny",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
-      tools: {
-        bash: "allow",
-      },
+      permission: { "*": "deny", bash: "allow" },
     });
 
     try {
@@ -1363,16 +1173,7 @@ permission:
 
 test("getToolPermission supports arbitrary extension tool names", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "deny",
-      bash: "ask",
-      mcp: "allow",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {
-      third_party_tool: "allow",
-    },
+    permission: { "*": "deny", third_party_tool: "allow" },
   });
 
   try {
@@ -1481,6 +1282,10 @@ test("Permission forwarding rejects unresolved sentinel session ids", () => {
   assert.equal(targetSessionId, null);
 });
 
+// ---------------------------------------------------------------------------
+// Project-level and per-agent config scope tests
+// ---------------------------------------------------------------------------
+
 type CreateManagerWithProjectOptions = CreateManagerOptions & {
   projectConfig?: ScopeConfig;
   projectAgentFiles?: Record<string, string>;
@@ -1545,23 +1350,15 @@ function createManagerWithProject(
 test("Project-level config overrides base bash patterns", () => {
   const { manager, cleanup } = createManagerWithProject(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
-      bash: {
-        "rm -rf *": "deny",
+      permission: {
+        "*": "allow",
+        bash: { "*": "ask", "rm -rf *": "deny" },
       },
     },
     {},
     {
       projectConfig: {
-        bash: {
-          "rm -rf build": "allow",
-        },
+        permission: { bash: { "rm -rf build": "allow" } },
       },
     },
   );
@@ -1586,13 +1383,7 @@ test("Project-level config overrides base bash patterns", () => {
 test("System-agent config overrides project-level bash patterns", () => {
   const { manager, cleanup } = createManagerWithProject(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "allow", bash: "ask" },
     },
     {
       reviewer: `---
@@ -1605,9 +1396,7 @@ permission:
     },
     {
       projectConfig: {
-        bash: {
-          "git *": "deny",
-        },
+        permission: { bash: { "git *": "deny" } },
       },
     },
   );
@@ -1636,20 +1425,13 @@ permission:
 test("Project-agent config overrides system-agent tool rules", () => {
   const { manager, cleanup } = createManagerWithProject(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  tools:
-    read: deny
+  read: deny
 ---
 `,
     },
@@ -1658,8 +1440,7 @@ permission:
         reviewer: `---
 name: reviewer
 permission:
-  tools:
-    read: allow
+  read: allow
 ---
 `,
       },
@@ -1675,38 +1456,28 @@ permission:
   }
 });
 
-test("Full precedence chain base < project < system-agent < project-agent for defaultPolicy", () => {
+test("Full precedence chain base < project < system-agent < project-agent for universal default", () => {
   const { manager, cleanup } = createManagerWithProject(
     {
-      defaultPolicy: {
-        tools: "deny",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "deny" },
     },
     {
       reviewer: `---
 name: reviewer
 permission:
-  defaultPolicy:
-    tools: ask
+  "*": ask
 ---
 `,
     },
     {
       projectConfig: {
-        defaultPolicy: {
-          tools: "allow",
-        },
+        permission: { "*": "allow" },
       },
       projectAgentFiles: {
         reviewer: `---
 name: reviewer
 permission:
-  defaultPolicy:
-    tools: deny
+  "*": deny
 ---
 `,
       },
@@ -1733,13 +1504,7 @@ permission:
 test("Project-agent applies even without a matching system-agent file", () => {
   const { manager, cleanup } = createManagerWithProject(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "allow" },
     },
     {},
     {
@@ -1747,8 +1512,7 @@ test("Project-agent applies even without a matching system-agent file", () => {
         reviewer: `---
 name: reviewer
 permission:
-  tools:
-    read: deny
+  read: deny
 ---
 `,
       },
@@ -1780,18 +1544,7 @@ test("PermissionManager reads config from PI_CODING_AGENT_DIR when set", () => {
   mkdirSync(dirname(newConfigPath), { recursive: true });
 
   const config: ScopeConfig = {
-    defaultPolicy: {
-      tools: "deny",
-      bash: "deny",
-      mcp: "deny",
-      skills: "deny",
-      special: "deny",
-    },
-    tools: { read: "allow" },
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: {},
+    permission: { "*": "deny", read: "allow" },
   };
   writeFileSync(newConfigPath, JSON.stringify(config), "utf8");
 
@@ -1848,15 +1601,9 @@ test("parseAllSkillPromptSections finds every available_skills block", () => {
 
 test("REGRESSION: resolveSkillPromptEntries sanitizes every available_skills block", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    skills: {
-      "denied-skill": "deny",
+    permission: {
+      "*": "ask",
+      skill: { "denied-skill": "deny" },
     },
   });
 
@@ -1915,15 +1662,9 @@ test("REGRESSION: resolveSkillPromptEntries sanitizes every available_skills blo
 
 test("REGRESSION: resolveSkillPromptEntries keeps only visible skills available for path matching", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    skills: {
-      "blocked-skill": "deny",
+    permission: {
+      "*": "ask",
+      skill: { "blocked-skill": "deny" },
     },
   });
 
@@ -1975,16 +1716,9 @@ test("REGRESSION: resolveSkillPromptEntries keeps only visible skills available
 // external_directory special permission
 // ---------------------------------------------------------------------------
 
-test("external_directory permission falls back to special default policy when not explicitly configured", () => {
-  const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "allow",
-      mcp: "allow",
-      skills: "allow",
-      special: "ask",
-    },
-  });
+test("external_directory permission falls back to universal default when not explicitly configured", () => {
+  // Empty permission: everything defaults to "ask" (least privilege).
+  const { manager, cleanup } = createManager({ permission: {} });
 
   try {
     const result = manager.checkPermission("external_directory", {});
@@ -1996,25 +1730,16 @@ test("external_directory permission falls back to special default policy when no
   }
 });
 
-test("external_directory permission respects explicit deny in special config", () => {
+test("external_directory permission respects explicit deny", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "allow",
-      mcp: "allow",
-      skills: "allow",
-      special: "ask",
-    },
-    special: {
-      external_directory: "deny",
-    },
+    permission: { "*": "allow", external_directory: "deny" },
   });
 
   try {
     const result = manager.checkPermission("external_directory", {});
     assert.equal(result.state, "deny");
     assert.equal(result.source, "special");
-    assert.equal(result.matchedPattern, "external_directory");
+    assert.equal(result.matchedPattern, "*");
   } finally {
     cleanup();
   }
@@ -2022,23 +1747,14 @@ test("external_directory permission respects explicit deny in special config", (
 
 test("external_directory permission can be explicitly allowed", () => {
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "allow",
-      mcp: "allow",
-      skills: "allow",
-      special: "deny",
-    },
-    special: {
-      external_directory: "allow",
-    },
+    permission: { "*": "allow", external_directory: "allow" },
   });
 
   try {
     const result = manager.checkPermission("external_directory", {});
     assert.equal(result.state, "allow");
     assert.equal(result.source, "special");
-    assert.equal(result.matchedPattern, "external_directory");
+    assert.equal(result.matchedPattern, "*");
   } finally {
     cleanup();
   }
@@ -2047,23 +1763,13 @@ test("external_directory permission can be explicitly allowed", () => {
 test("external_directory permission respects per-agent override", () => {
   const { manager, cleanup } = createManager(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: {
-        external_directory: "deny",
-      },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     {
       trusted: `---
 name: trusted
 permission:
-  special:
-    external_directory: allow
+  external_directory: allow
 ---
 `,
     },
@@ -2087,31 +1793,18 @@ permission:
   }
 });
 
-test("external_directory permission is unaffected when doom_loop key is present in config (deprecated and ignored)", () => {
+test("external_directory permission is not affected by unrelated surface keys", () => {
+  // Flat format: unknown surface keys are just rules for that surface.
+  // external_directory resolves from its own rule, not from unrelated keys.
   const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "allow",
-      mcp: "allow",
-      skills: "allow",
-      special: "ask",
-    },
-    special: {
-      doom_loop: "deny",
-      external_directory: "allow",
-    },
+    permission: { "*": "allow", external_directory: "allow" },
   });
 
   try {
-    // doom_loop is deprecated and stripped — falls through to defaultPolicy.tools
-    const doomResult = manager.checkPermission("doom_loop", {});
-    assert.equal(doomResult.state, "allow"); // defaultPolicy.tools, not the stripped doom_loop: "deny"
-    assert.equal(doomResult.matchedPattern, undefined);
-
     // external_directory still resolves from its own entry
     const extResult = manager.checkPermission("external_directory", {});
     assert.equal(extResult.state, "allow");
-    assert.equal(extResult.matchedPattern, "external_directory");
+    assert.equal(extResult.matchedPattern, "*");
   } finally {
     cleanup();
   }
@@ -2125,14 +1818,7 @@ test("tool_call blocks path-bearing tools outside cwd when external_directory is
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "deny" },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     ["read"],
     { cwd },
@@ -2160,14 +1846,7 @@ test("tool_call blocks path-bearing tools outside cwd when external_directory is
 test("tool_call allows path-bearing tools inside cwd without external_directory prompt", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "deny" },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     ["read"],
   );
@@ -2189,14 +1868,7 @@ test("tool_call allows path-bearing tools inside cwd without external_directory
 test("tool_call blocks external_directory ask when no confirmation channel is available", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["write"],
   );
@@ -2224,14 +1896,7 @@ test("tool_call blocks external_directory ask when no confirmation channel is av
 test("tool_call prompts for external_directory and then falls through to normal tool policy", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["grep"],
   );
@@ -2261,14 +1926,7 @@ test("tool_call prompts for external_directory and then falls through to normal
 test("tool_call skips external_directory checks for optional path tools without a path", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "deny" },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     ["find"],
   );
@@ -2292,14 +1950,7 @@ test("tool_call skips external_directory checks for optional path tools without
 test("tool_call blocks bash command with external path when external_directory is denied", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "deny" },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     ["bash"],
   );
@@ -2325,14 +1976,7 @@ test("tool_call blocks bash command with external path when external_directory i
 test("tool_call allows bash command with only internal paths when external_directory is denied", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "deny" },
+      permission: { "*": "allow", external_directory: "deny" },
     },
     ["bash"],
   );
@@ -2353,14 +1997,7 @@ test("tool_call allows bash command with only internal paths when external_direc
 test("tool_call prompts for bash command with external path when external_directory is ask", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["bash"],
   );
@@ -2386,14 +2023,7 @@ test("tool_call prompts for bash command with external path when external_direct
 test("tool_call allows bash command with external path when external_directory is allow", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "allow" },
+      permission: { "*": "allow", external_directory: "allow" },
     },
     ["bash"],
   );
@@ -2415,15 +2045,11 @@ test("tool_call allows bash command with external path when external_directory i
 test("tool_call applies bash pattern permissions after external_directory allow", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
+      permission: {
+        "*": "allow",
+        external_directory: "allow",
+        bash: { "*": "allow", "cat *": "deny" },
       },
-      special: { external_directory: "allow" },
-      bash: { "cat *": "deny" },
     },
     ["bash"],
   );
@@ -2446,13 +2072,7 @@ test("tool_call applies bash pattern permissions after external_directory allow"
 test("generic ask prompts include serialized tool input for informed approval", async () => {
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "ask",
-        bash: "ask",
-        mcp: "ask",
-        skills: "ask",
-        special: "ask",
-      },
+      permission: { "*": "ask" },
     },
     ["weather_lookup"],
   );
@@ -2539,86 +2159,11 @@ test("getResolvedPolicyPaths returns false for missing files and null for absent
   }
 });
 
-// --- tool_call_limit deprecation tests (#18) ---
-
-test("normalizeRawPermission emits deprecation issue for special.tool_call_limit (integer)", () => {
-  const result = normalizeRawPermission({ special: { tool_call_limit: 5 } });
-  assert.equal(result.configIssues.length, 1);
-  assert.ok(result.configIssues[0].includes("tool_call_limit"));
-  assert.equal(result.permissions.special?.tool_call_limit, undefined);
-});
-
-test("normalizeRawPermission emits deprecation issue for special.tool_call_limit (string)", () => {
-  const result = normalizeRawPermission({
-    special: { tool_call_limit: "allow" },
-  });
-  assert.equal(result.configIssues.length, 1);
-  assert.ok(result.configIssues[0].includes("tool_call_limit"));
-  assert.equal(result.permissions.special?.tool_call_limit, undefined);
-});
-
-test("normalizeRawPermission emits deprecation issue for special.doom_loop (string)", () => {
-  const result = normalizeRawPermission({
-    special: { doom_loop: "ask" },
-  });
-  assert.equal(result.configIssues.length, 1);
-  assert.ok(result.configIssues[0].includes("doom_loop"));
-  assert.equal(result.permissions.special?.doom_loop, undefined);
-});
-
-test("normalizeRawPermission emits deprecation issue for special.doom_loop (deny)", () => {
-  const result = normalizeRawPermission({
-    special: { doom_loop: "deny" },
-  });
-  assert.equal(result.configIssues.length, 1);
-  assert.ok(result.configIssues[0].includes("doom_loop"));
-  assert.equal(result.permissions.special?.doom_loop, undefined);
-});
-
-test("normalizeRawPermission emits no issues when special is absent", () => {
-  const result = normalizeRawPermission({ tools: { read: "allow" } });
-  assert.equal(result.configIssues.length, 0);
-});
-
-test("PermissionManager.getConfigIssues returns deprecation for tool_call_limit in global config", () => {
-  const config: ScopeConfig = {
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {},
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: { tool_call_limit: "allow" as PermissionState },
-  };
-  const { manager, cleanup } = createManager(config);
-  try {
-    const issues = manager.getConfigIssues();
-    assert.equal(issues.length, 1);
-    assert.ok(issues[0].includes("tool_call_limit"));
-  } finally {
-    cleanup();
-  }
-});
+// --- config issues tests ---
 
 test("PermissionManager.getConfigIssues returns empty array for clean config", () => {
   const config: ScopeConfig = {
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {},
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: { external_directory: "ask" },
+    permission: { "*": "ask", external_directory: "ask" },
   };
   const { manager, cleanup } = createManager(config);
   try {
@@ -2629,59 +2174,19 @@ test("PermissionManager.getConfigIssues returns empty array for clean config", (
   }
 });
 
-// --- doom_loop config-loader deprecation tests (#54) ---
-
-test("PermissionManager.getConfigIssues returns deprecation for doom_loop in global config", () => {
-  const config: ScopeConfig = {
-    defaultPolicy: {
-      tools: "ask",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "ask",
-    },
-    tools: {},
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: { doom_loop: "deny" },
-  };
-  const { manager, cleanup } = createManager(config);
+test("PermissionManager.getConfigIssues returns empty array for empty config", () => {
+  const { manager, cleanup } = createManager({});
   try {
     const issues = manager.getConfigIssues();
-    assert.equal(issues.length, 1);
-    assert.ok(issues[0].includes("doom_loop"));
-  } finally {
-    cleanup();
-  }
-});
-
-test("checkPermission doom_loop falls through to defaultPolicy.tools when stripped by config-loader", () => {
-  const { manager, cleanup } = createManager({
-    defaultPolicy: {
-      tools: "allow",
-      bash: "ask",
-      mcp: "ask",
-      skills: "ask",
-      special: "deny",
-    },
-    tools: {},
-    bash: {},
-    mcp: {},
-    skills: {},
-    special: { doom_loop: "ask" },
-  });
-  try {
-    const result = manager.checkPermission("doom_loop", {});
-    // doom_loop stripped by config-loader — falls through to defaultPolicy.tools
-    assert.equal(result.state, "allow");
-    assert.equal(result.matchedPattern, undefined);
+    assert.equal(issues.length, 0);
   } finally {
     cleanup();
   }
 });
 
-// --- session-scoped approval tests (#45) ---
+// ---------------------------------------------------------------------------
+// Session-scoped approval tests (#45)
+// ---------------------------------------------------------------------------
 
 test("session approval: first prompt with 'Yes, for this session' skips subsequent prompts under same prefix", async () => {
   const rootDir = mkdtempSync(join(tmpdir(), "pi-session-approval-"));
@@ -2692,14 +2197,7 @@ test("session approval: first prompt with 'Yes, for this session' skips subseque
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["read", "grep"],
     { cwd },
@@ -2762,14 +2260,7 @@ test("session approval: different directory prefix still prompts", async () => {
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["read"],
     { cwd },
@@ -2814,14 +2305,7 @@ test("session approval: session_shutdown clears session approvals", async () =>
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["read"],
     { cwd },
@@ -2872,14 +2356,7 @@ test("session approval: bash external directory with 'Yes, for this session' ski
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["bash"],
     { cwd },
@@ -2927,14 +2404,7 @@ test("session approval: regular 'Yes' does not create session approval", async (
 
   const harness = createToolCallHarness(
     {
-      defaultPolicy: {
-        tools: "allow",
-        bash: "allow",
-        mcp: "allow",
-        skills: "allow",
-        special: "ask",
-      },
-      special: { external_directory: "ask" },
+      permission: { "*": "allow", external_directory: "ask" },
     },
     ["read"],
     { cwd },
@@ -2969,3 +2439,166 @@ 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({
+    permission: { "*": "allow" },
+  });
+
+  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({
+    permission: { "*": "allow", external_directory: "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({
+    permission: { "*": "allow", 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: "*",
+      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({
+    // Empty permission: universal default is "ask" from DEFAULT_UNIVERSAL_FALLBACK.
+    permission: {},
+  });
+
+  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({
+    permission: { "*": "allow", 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();
+  }
+});
+
+// Suppress unused import warning — PermissionState used in type annotations
+const _unused: PermissionState = "ask";
+void _unused;