pi-permission-system 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [0.2.2] - 2026-03-13
+
+### Changed
+- Removed delegation task restriction logic — the `task` tool is no longer restricted to orchestrator agent only
+- Simplified tool permission lookup to use explicit `tools` entries for arbitrary registered tools instead of MCP fallback
+- Renamed `TOOL_PERMISSION_NAMES` to `BUILT_IN_TOOL_PERMISSION_NAMES` to clarify it covers only canonical Pi tools
+- Updated schema descriptions for `tools` and `mcp` fields to guide configuration usage
+
+### Removed
+- Removed delegation-specific permission checks (`isDelegationAllowedAgent`, `getDelegationBlockReason`) from permission evaluation
+
+### Tests
+- Added comprehensive test coverage for tool permission lookup behavior
+
 ## [0.2.1] - 2026-03-13
 
 ### Added

package/README.md

@@ -79,7 +79,7 @@ The extension integrates via Pi's lifecycle hooks:
 **Additional behaviors:**
 - Unknown/unregistered tools are blocked before permission checks (prevents bypass attempts)
 - The `Available tools:` system prompt section is rewritten to match the filtered active tool set
-- The `task` delegation tool is restricted to the `orchestrator` agent only
+- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name instead of private built-in hardcodes
 - When a subagent hits an `ask` permission without direct UI access, the request can be forwarded to the main interactive session for confirmation
 - When a subagent triggers an `ask` permission without UI access, the request can be forwarded to the main session and answered there
 
@@ -111,14 +111,14 @@ Both logs write to files only under the extension directory. No debug output is
 
 The policy file is a JSON object with these sections:
 
-| Section         | Description                              |
-|-----------------|------------------------------------------|
-| `defaultPolicy` | Fallback permissions per category        |
-| `tools`         | Built-in tool permissions                |
-| `bash`          | Command pattern permissions              |
-| `mcp`           | MCP server/tool permissions              |
-| `skills`        | Skill name pattern permissions           |
-| `special`       | Reserved permission checks               |
+| Section         | Description                                         |
+|-----------------|-----------------------------------------------------|
+| `defaultPolicy` | Fallback permissions per category                   |
+| `tools`         | Exact-name tool permissions for registered tools    |
+| `bash`          | Command pattern permissions                         |
+| `mcp`           | MCP server/tool permissions for calls routed through a registered `mcp` tool |
+| `skills`        | Skill name pattern permissions                      |
+| `special`       | Reserved permission checks                          |
 
 > **Note:** Trailing commas are **not** supported. If parsing fails, the extension falls back to `ask` for all categories.
 
@@ -147,7 +147,7 @@ permission:
 
 **Precedence:** Agent frontmatter overrides global config (shallow-merged per section).
 
-**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for the built-in `mcp` tool. More specific `permission.mcp` target rules override that fallback when they match.
+**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for a registered `mcp` tool when one is available. More specific `permission.mcp` target rules override that fallback when they match.
 
 **Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors.
 
@@ -173,33 +173,34 @@ Sets fallback permissions when no specific rule matches:
 
 ### `tools`
 
-Controls built-in tools by exact name (no wildcards):
+Controls tools by exact registered name (no wildcards). This is the recommended standalone format for **all** tool entries, including Pi built-ins and arbitrary third-party extension tools.
 
-| Tool    | Description                    |
-|---------|--------------------------------|
-| `bash`  | Shell command execution        |
-| `read`  | File reading                   |
-| `write` | File creation/overwriting      |
-| `edit`  | Surgical file edits            |
-| `grep`  | Pattern searching              |
-| `find`  | File discovery                 |
-| `ls`    | Directory listing              |
-| `mcp`   | MCP proxy tool entry/fallback  |
+| Tool name example     | Description |
+|-----------------------|-------------|
+| `bash`                | Shell command execution (tool-level fallback before `bash` pattern rules) |
+| `read` / `write`      | Canonical Pi built-in file tools |
+| `mcp`                 | Registered MCP proxy tool entry/fallback when available |
+| `task`                | Delegation tool handled like any other registered extension tool |
+| `third_party_tool`    | Arbitrary registered extension tool |
 
 ```jsonc
 {
   "tools": {
     "read": "allow",
     "write": "deny",
-    "edit": "deny",
-    "mcp": "allow"
+    "mcp": "allow",
+    "third_party_tool": "ask"
   }
 }
 ```
 
+Unknown or absent tools are not required in the config. If another extension is not installed, its tool simply will not be registered at runtime, and this extension will block attempts to call that missing tool before permission checks run.
+
 > **Note:** Setting `tools.bash` affects the *default* for bash commands, but `bash` patterns can provide command-level overrides.
 >
-> **Note:** Setting `tools.mcp` controls coarse access to the built-in `mcp` tool. Specific `mcp` rules still override it when a target pattern matches.
+> **Note:** Setting `tools.mcp` controls coarse access to a registered `mcp` tool when one is available. Specific `mcp` rules still override it when a target pattern matches.
+>
+> **Note:** Top-level shorthand is only supported for the canonical Pi built-ins (`bash`, `read`, `write`, `edit`, `grep`, `find`, `ls`) in agent frontmatter. Use `permission.tools.<name>` for `mcp`, `task`, and any third-party tool.
 
 ### `bash`
 
@@ -241,7 +242,7 @@ MCP permissions match against derived targets from tool input. These rules are m
 
 #### MCP Tool Fallback via `tools.mcp`
 
-The `mcp` built-in tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
+A registered `mcp` tool can use `tools.mcp` as an entry permission point. This provides a fallback when no specific MCP pattern matches:
 
 ```jsonc
 {
@@ -456,7 +457,7 @@ npx --yes ajv-cli@5 validate \
 |---------|-------|----------|
 | Config not applied (everything asks) | File not found or parse error | Verify file at `~/.pi/agent/pi-permissions.jsonc`; check for trailing commas |
 | Per-agent override not applied | Frontmatter parsing issue | Ensure `---` delimiters at file top; keep YAML simple; restart session |
-| Tool blocked as unregistered | Unknown tool name | Use built-in `mcp` tool for server tools: `{ "tool": "server:tool" }` |
+| Tool blocked as unregistered | Unknown tool name | Use a registered `mcp` tool for server tools: `{ "tool": "server:tool" }` |
 | `/skill:<name>` blocked | Missing context or deny policy | Requires active agent context; `ask` behaves as block in headless mode |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permission-system",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "main": "./index.ts",

package/schemas/permissions.schema.json

@@ -31,12 +31,14 @@
       }
     },
     "tools": {
+      "description": "Exact-name permissions for registered tools. Use this map for the canonical Pi built-ins and any extension-provided or third-party tools.",
       "$ref": "#/$defs/permissionMap"
     },
     "bash": {
       "$ref": "#/$defs/permissionMap"
     },
     "mcp": {
+      "description": "Pattern-based permissions for targets invoked through a registered `mcp` tool when available.",
       "$ref": "#/$defs/permissionMap"
     },
     "skills": {

package/src/index.ts

@@ -27,8 +27,6 @@ const LEGACY_PERMISSION_FORWARDING_RESPONSES_DIR = join(LEGACY_PERMISSION_FORWAR
 const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
 const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
 const SUBAGENT_ENV_HINT_KEYS = ["PI_IS_SUBAGENT", "PI_SUBAGENT_SESSION_ID", "PI_AGENT_ROUTER_SUBAGENT"] as const;
-const ORCHESTRATOR_AGENT_NAME = "orchestrator";
-const DELEGATION_TOOL_NAME = "task";
 
 const AVAILABLE_SKILLS_OPEN_TAG = "<available_skills>";
 const AVAILABLE_SKILLS_CLOSE_TAG = "</available_skills>";
@@ -377,15 +375,6 @@ function getActiveAgentNameFromSystemPrompt(systemPrompt: string | undefined): s
   return normalizeAgentName(match[1]);
 }
 
-function isDelegationAllowedAgent(agentName: string | null): boolean {
-  return Boolean(agentName && agentName.toLowerCase() === ORCHESTRATOR_AGENT_NAME);
-}
-
-function getDelegationBlockReason(agentName: string | null): string {
-  const resolvedAgent = agentName ?? "none";
-  return `Tool '${DELEGATION_TOOL_NAME}' is restricted to '${ORCHESTRATOR_AGENT_NAME}'. Active agent '${resolvedAgent}' cannot delegate.`;
-}
-
 function formatMissingToolNameReason(): string {
   return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";
 }
@@ -397,7 +386,7 @@ function formatUnknownToolReason(toolName: string, availableToolNames: readonly
 
   const mcpHint = toolName === "mcp"
     ? ""
-    : " If this was intended as an MCP server tool, call the built-in 'mcp' tool (for example: {\"tool\":\"server:tool\"}).";
+    : " If this was intended as an MCP server tool, call the registered 'mcp' tool when available (for example: {\"tool\":\"server:tool\"}).";
 
   return `Tool '${toolName}' is not registered in this runtime and was blocked before permission checks.${mcpHint} Registered tools: ${availableList}.`;
 }
@@ -1080,10 +1069,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
 
   const shouldExposeTool = (toolName: string, agentName: string | null): boolean => {
-    if (toolName === DELEGATION_TOOL_NAME && !isDelegationAllowedAgent(agentName)) {
-      return false;
-    }
-
     // Use tool-level permission check for tool injection decisions
     // This ensures that agent-specific tool deny rules (e.g., bash: deny) are respected
     // before any command-level permissions are considered
@@ -1234,10 +1219,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       };
     }
 
-    if (toolName === DELEGATION_TOOL_NAME && !isDelegationAllowedAgent(agentName)) {
-      return { block: true, reason: getDelegationBlockReason(agentName) };
-    }
-
     if (isToolCallEventType("read", event) && activeSkillEntries.length > 0) {
       const normalizedReadPath = normalizePathForComparison(event.input.path, ctx.cwd);
       const matchedSkill = findSkillPathMatch(normalizedReadPath, activeSkillEntries);

package/src/permission-manager.ts

@@ -24,7 +24,7 @@ const AGENTS_DIR = join(homedir(), ".pi", "agent", "agents");
 const LEGACY_GLOBAL_SETTINGS_PATH = join(homedir(), ".pi", "agent", "settings.json");
 const GLOBAL_MCP_CONFIG_PATH = join(homedir(), ".pi", "agent", "mcp.json");
 
-const TOOL_PERMISSION_NAMES = new Set(["bash", "read", "write", "edit", "grep", "find", "ls", "mcp", "task"]);
+const BUILT_IN_TOOL_PERMISSION_NAMES = new Set(["bash", "read", "write", "edit", "grep", "find", "ls"]);
 const SPECIAL_PERMISSION_KEYS = new Set(["doom_loop", "external_directory"]);
 const MCP_BASELINE_TARGETS = new Set(["mcp_status", "mcp_list", "mcp_search", "mcp_describe", "mcp_connect"]);
 
@@ -211,7 +211,7 @@ function normalizeRawPermission(raw: unknown): AgentPermissions {
       continue;
     }
 
-    if (TOOL_PERMISSION_NAMES.has(key)) {
+    if (BUILT_IN_TOOL_PERMISSION_NAMES.has(key)) {
       normalized.tools = { ...(normalized.tools || {}), [key]: value };
       continue;
     }
@@ -590,7 +590,10 @@ export class PermissionManager {
    * This is used for tool injection decisions where we need to know if a tool is allowed/denied
    * at the tool level before checking specific command permissions.
    *
-   * @param toolName - The name of the tool (e.g., "bash", "read", "write")
+   * Exact-name entries in `tools` work for arbitrary registered extension tools.
+   * Canonical Pi tools with dedicated categories still use their specialized fallbacks.
+   *
+   * @param toolName - The name of the tool (for example "bash", "read", or a third-party tool name)
    * @param agentName - Optional agent name to check agent-specific permissions
    * @returns The permission state for the tool at the tool level
    */
@@ -598,44 +601,23 @@ export class PermissionManager {
     const { merged } = this.resolvePermissions(agentName);
     const normalizedToolName = toolName.trim();
 
-    // Handle special permission keys (doom_loop, external_directory)
     if (SPECIAL_PERMISSION_KEYS.has(normalizedToolName)) {
       return merged.defaultPolicy.special;
     }
 
-    // Handle skill tool
     if (normalizedToolName === "skill") {
       return merged.defaultPolicy.skills;
     }
 
-    // For bash tool, return the tool-level permission (not command-level)
     if (normalizedToolName === "bash") {
       return merged.tools?.bash || merged.defaultPolicy.bash;
     }
 
-    // Handle mcp tool
     if (normalizedToolName === "mcp") {
       return merged.tools?.mcp || merged.defaultPolicy.mcp;
     }
 
-    // Handle other tool permission names
-    if (TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
-      return merged.tools?.[normalizedToolName] || merged.defaultPolicy.tools;
-    }
-
-    // For MCP tools (qualified names like "server_tool"), check mcp permissions
-    if (normalizedToolName.includes("_")) {
-      const mcpMatch = findCompiledPermissionMatch(
-        compilePermissionPatternsFromSources(this.loadGlobalConfig().mcp, this.loadAgentPermissions(agentName).mcp),
-        normalizedToolName
-      );
-      if (mcpMatch) {
-        return mcpMatch.state;
-      }
-    }
-
-    // Default to the tools default policy
-    return merged.defaultPolicy.tools;
+    return merged.tools?.[normalizedToolName] || merged.defaultPolicy.tools;
   }
 
   checkPermission(toolName: string, input: unknown, agentName?: string): PermissionCheckResult {
@@ -731,7 +713,7 @@ export class PermissionManager {
       };
     }
 
-    if (TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
+    if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {
       return {
         toolName,
         state: merged.tools?.[normalizedToolName] || merged.defaultPolicy.tools,
@@ -739,21 +721,18 @@ export class PermissionManager {
       };
     }
 
-    const mcpMatch = findCompiledPermissionMatch(compiledMcp, toolName);
-    if (mcpMatch) {
+    const explicitToolPermission = merged.tools?.[normalizedToolName];
+    if (explicitToolPermission) {
       return {
         toolName,
-        state: mcpMatch.state,
-        matchedPattern: mcpMatch.matchedPattern,
-        target: mcpMatch.matchedName,
-        source: "mcp",
+        state: explicitToolPermission,
+        source: "tool",
       };
     }
 
     return {
       toolName,
-      state: merged.defaultPolicy.mcp || "deny",
-      target: toolName,
+      state: merged.defaultPolicy.tools,
       source: "default",
     };
   }

package/src/test.ts

@@ -128,7 +128,7 @@ runTest("BashFilter uses opencode-style last-match hierarchy", () => {
   assert.equal(generic.matchedPattern, "git *");
 });
 
-runTest("PermissionManager built-in permission checking", () => {
+runTest("PermissionManager canonical built-in permission checking", () => {
   const { manager, cleanup } = createManager({
     defaultPolicy: {
       tools: "deny",
@@ -195,7 +195,7 @@ permission:
   }
 });
 
-runTest("MCP wildcard matching", () => {
+runTest("MCP wildcard matching uses the registered mcp tool", () => {
   const { manager, cleanup } = createManager({
     defaultPolicy: {
       tools: "ask",
@@ -206,24 +206,57 @@ runTest("MCP wildcard matching", () => {
     },
     mcp: {
       "*": "deny",
-      "subagent_*": "ask",
-      "subagent_query-*": "allow",
+      "research_*": "ask",
+      "research_query-*": "allow",
     },
   });
 
   try {
-    const queryDocs = manager.checkPermission("subagent_query-docs", {});
+    const queryDocs = manager.checkPermission("mcp", { tool: "research:query-docs" });
     assert.equal(queryDocs.state, "allow");
     assert.equal(queryDocs.source, "mcp");
-    assert.equal(queryDocs.matchedPattern, "subagent_query-*");
+    assert.equal(queryDocs.matchedPattern, "research_query-*");
+    assert.equal(queryDocs.target, "research_query-docs");
 
-    const resolve = manager.checkPermission("subagent_resolve-context", {});
+    const resolve = manager.checkPermission("mcp", { tool: "research:resolve-context" });
     assert.equal(resolve.state, "ask");
-    assert.equal(resolve.matchedPattern, "subagent_*");
+    assert.equal(resolve.matchedPattern, "research_*");
+    assert.equal(resolve.target, "research_resolve-context");
 
-    const unknown = manager.checkPermission("web_search_provider", {});
+    const unknown = manager.checkPermission("mcp", { tool: "search:provider" });
     assert.equal(unknown.state, "deny");
     assert.equal(unknown.matchedPattern, "*");
+    assert.equal(unknown.target, "search_provider");
+  } finally {
+    cleanup();
+  }
+});
+
+runTest("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: {
+      "*": "deny",
+    },
+  });
+
+  try {
+    const allowed = manager.checkPermission("third_party_tool", {});
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.source, "tool");
+
+    const fallback = manager.checkPermission("another_extension_tool", {});
+    assert.equal(fallback.state, "deny");
+    assert.equal(fallback.source, "default");
   } finally {
     cleanup();
   }
@@ -538,7 +571,47 @@ permission:
   }
 });
 
-runTest("task uses tool permissions instead of MCP fallback", () => {
+runTest("Only canonical built-ins support top-level shorthand in agent frontmatter", () => {
+  const { manager, cleanup } = createManager(
+    {
+      defaultPolicy: {
+        tools: "deny",
+        bash: "ask",
+        mcp: "deny",
+        skills: "ask",
+        special: "ask",
+      },
+    },
+    {
+      reviewer: `---
+name: reviewer
+permission:
+  find: allow
+  task: allow
+  mcp: allow
+---
+`,
+    },
+  );
+
+  try {
+    const findResult = manager.checkPermission("find", {}, "reviewer");
+    assert.equal(findResult.state, "allow");
+    assert.equal(findResult.source, "tool");
+
+    const taskResult = manager.checkPermission("task", {}, "reviewer");
+    assert.equal(taskResult.state, "deny");
+    assert.equal(taskResult.source, "default");
+
+    const mcpResult = manager.checkPermission("mcp", { tool: "exa:web_search_exa" }, "reviewer");
+    assert.equal(mcpResult.state, "deny");
+    assert.equal(mcpResult.source, "default");
+  } finally {
+    cleanup();
+  }
+});
+
+runTest("task uses exact-name tool permissions like any registered extension tool", () => {
   const { manager, cleanup } = createManager(
     {
       defaultPolicy: {
@@ -574,7 +647,7 @@ runTest("Tool registry resolves event tool names from string and object payloads
 runTest("Tool registry blocks unregistered tools and handles aliases", () => {
   const registeredTools = [{ toolName: "mcp" }, { toolName: "read" }, { toolName: "bash" }];
 
-  const unknownCheck = checkRequestedToolRegistration("subagent_query-docs", registeredTools);
+  const unknownCheck = checkRequestedToolRegistration("third_party_tool", registeredTools);
   assert.equal(unknownCheck.status, "unregistered");
   if (unknownCheck.status === "unregistered") {
     assert.deepEqual(unknownCheck.availableToolNames, ["bash", "mcp", "read"]);
@@ -587,7 +660,7 @@ runTest("Tool registry blocks unregistered tools and handles aliases", () => {
   assert.equal(missingNameCheck.status, "missing-tool-name");
 });
 
-runTest("getToolPermission returns tool-level deny for agent with bash: deny", () => {
+runTest("getToolPermission returns tool-level policy for canonical and extension tools", () => {
   const { manager, cleanup } = createManager(
     {
       defaultPolicy: {
@@ -599,8 +672,8 @@ runTest("getToolPermission returns tool-level deny for agent with bash: deny", (
       },
     },
     {
-      orchestrator: `---
-name: orchestrator
+      reviewer: `---
+name: reviewer
 permission:
   tools:
     bash: deny
@@ -612,23 +685,18 @@ permission:
   );
 
   try {
-    // Tool-level check for bash should return deny for orchestrator
-    const bashPermission = manager.getToolPermission("bash", "orchestrator");
+    const bashPermission = manager.getToolPermission("bash", "reviewer");
     assert.equal(bashPermission, "deny");
 
-    // Tool-level check for task should return allow
-    const taskPermission = manager.getToolPermission("task", "orchestrator");
+    const taskPermission = manager.getToolPermission("task", "reviewer");
     assert.equal(taskPermission, "allow");
 
-    // Tool-level check for read should return deny
-    const readPermission = manager.getToolPermission("read", "orchestrator");
+    const readPermission = manager.getToolPermission("read", "reviewer");
     assert.equal(readPermission, "deny");
 
-    // When no agent specified, should fall back to default policy
     const defaultBashPermission = manager.getToolPermission("bash");
     assert.equal(defaultBashPermission, "ask");
 
-    // Global config tools setting should work
     const { manager: manager2, cleanup: cleanup2 } = createManager({
       defaultPolicy: {
         tools: "deny",
@@ -653,4 +721,29 @@ permission:
   }
 });
 
+runTest("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",
+    },
+  });
+
+  try {
+    const explicitPermission = manager.getToolPermission("third_party_tool");
+    assert.equal(explicitPermission, "allow");
+
+    const fallbackPermission = manager.getToolPermission("missing_extension_tool");
+    assert.equal(fallbackPermission, "deny");
+  } finally {
+    cleanup();
+  }
+});
+
 console.log("All permission system tests passed.");