@gotgenes/pi-permission-system 20.4.2 → 20.5.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [20.5.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.4.2...pi-permission-system-v20.5.0) (2026-07-13)
+
+
+### Features
+
+* **pi-permission-system:** add shellTools config schema ([cd4f851](https://github.com/gotgenes/pi-packages/commit/cd4f851ab4ddccbc2409f664432e3cf256997817))
+* **pi-permission-system:** carry shellTools through config merge ([635d66b](https://github.com/gotgenes/pi-packages/commit/635d66b56d753f00192269f04cd7dceba1264f8d))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** treat bare / as a filesystem-root path candidate ([#583](https://github.com/gotgenes/pi-packages/issues/583)) ([dfa4080](https://github.com/gotgenes/pi-packages/commit/dfa408026a6f74f63c4537f9e6904acabc4f260a))
+
+
+### Documentation
+
+* **pi-permission-system:** document shellTools config ([1b8e3c3](https://github.com/gotgenes/pi-packages/commit/1b8e3c3a5779ac6cae9686c10da1b8b3a0f36309))
+
 ## [20.4.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.4.1...pi-permission-system-v20.4.2) (2026-07-13)
 
 

package/README.md

@@ -109,6 +109,8 @@ Project overrides global; per-agent YAML frontmatter overrides both.
 
 Within a surface map like `bash` or `mcp`, **last matching rule wins** — put broad catch-alls first and specific overrides after.
 
+The optional `shellTools` field records which non-`bash` tools carry shell semantics (e.g. an `exec_command` tool that replaces native `bash`), so they can be gated through the same enforcement — see [docs/configuration.md](docs/configuration.md#shelltools--gating-aliased-shell-tools).
+
 For the full reference — all surfaces, runtime knobs, per-agent overrides, merge semantics, and common recipes — see [docs/configuration.md](docs/configuration.md).
 
 ## Upgrading

package/config/config.example.json

@@ -10,6 +10,10 @@
 
   "piInfrastructureReadPaths": [],
 
+  "shellTools": {
+    "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }
+  },
+
   "permission": {
     "*": "ask",
     "path": {

package/docs/configuration.md

@@ -46,6 +46,11 @@ Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`) use simple replace
   "toolTextSummaryMaxLength": 120,
   "piInfrastructureReadPaths": [],
 
+  // Non-bash tools that carry shell semantics
+  "shellTools": {
+    "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }
+  },
+
   // Flat permission policy
   "permission": {
     "*": "ask",                              // universal fallback
@@ -104,6 +109,37 @@ Example — allow reads from a Homebrew-managed Pi install at any version:
 }
 ```
 
+### `shellTools` — gating aliased shell tools
+
+The native `bash` tool goes through the full bash enforcement stack: command decomposition, wrapper flooring, path and external-directory token gates, and `bash:` rules.
+Some extensions replace `bash` with a differently-named tool — for example [`@howaboua/pi-codex-conversion`](https://github.com/IgorWarzocha/howaboua-pi-stuff) registers `exec_command`, which carries the shell command in a `cmd` argument and an optional working directory in `workdir`.
+Without a hint, the permission system cannot tell that such a tool is really a shell, so it gates it as a generic extension tool and the bash rules never apply.
+
+`shellTools` records that hint.
+Each key is a tool name; its value maps the tool's input arguments (the keys of the tool call's `arguments` object):
+
+```jsonc
+{
+  "shellTools": {
+    "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }
+  }
+}
+```
+
+| Field             | Required | Description                                                               |
+| ----------------- | -------- | ------------------------------------------------------------------------- |
+| `commandArgument` | yes      | The tool's input argument holding the shell command string (e.g. `cmd`).  |
+| `workdirArgument` | no       | The tool's input argument holding the working directory (e.g. `workdir`). |
+
+Merge semantics: `shellTools` **shallow-merges by tool name** across global → project.
+A project entry overrides a specific tool's mapping on a key collision but never drops a global entry — so adding a project-scoped alias cannot silently remove enforcement for a tool the global config already covers.
+To change a specific tool's mapping, set that tool's key at the project scope (the alias object is replaced wholesale, not deep-merged).
+
+`shellTools` only ever *tightens* enforcement and is inert when the named tool is not registered in the current session.
+Opting a project out of a shell-aliasing extension is a package-disable concern, not a `shellTools` edit.
+
+> **Note:** `shellTools` records the alias; the enforcement wiring that consumes it is tracked in [#574](https://github.com/gotgenes/pi-packages/issues/574).
+
 ---
 
 ## Policy Reference

package/package.json

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

package/schemas/permissions.schema.json

@@ -101,6 +101,42 @@
           }
         }
       ]
+    },
+    "shellTools": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "description": "A non-bash tool name that carries shell semantics."
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "commandArgument": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The name of the tool's input argument holding the shell command string (e.g. 'cmd')."
+          },
+          "workdirArgument": {
+            "description": "Optional name of the tool's input argument holding the working directory (e.g. 'workdir').",
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": ["commandArgument"],
+        "additionalProperties": false,
+        "description": "Maps one shell-aliased tool to the input arguments holding its command and (optionally) its working directory."
+      },
+      "description": "Maps non-bash tool names that carry shell semantics to the input arguments holding their command and working directory.",
+      "markdownDescription": "Records which non-`bash` tools carry shell semantics, mapping each tool name to the input argument holding its command (and optionally its working directory).\n\nUse this when an extension replaces the native `bash` tool under a different name — e.g. `@howaboua/pi-codex-conversion` registers `exec_command` with a `cmd` argument and an optional `workdir`. Recording the alias lets the permission system gate that tool through the same bash enforcement stack as native `bash` (command decomposition, wrapper flooring, path/external-directory token gates, and `bash:` rules).\n\nExample:\n\n```json\n\"shellTools\": {\n  \"exec_command\": { \"commandArgument\": \"cmd\", \"workdirArgument\": \"workdir\" }\n}\n```\n\n**Merge order:** shallow-merge by tool name across global → project. A project entry overrides a specific tool's mapping on key collision but never drops a global entry.",
+      "examples": [
+        {
+          "exec_command": {
+            "commandArgument": "cmd",
+            "workdirArgument": "workdir"
+          }
+        }
+      ]
     }
   },
   "additionalProperties": false,

package/src/access-intent/bash/token-classification.ts

@@ -9,7 +9,7 @@
  *     which matches an active, specific (non-`*`) `path` deny/ask rule (#509).
  *
  * All three classifiers share the private `rejectNonPathToken` predicate that
- * captures the seven rejection cases common to them (the production clone this
+ * captures the six rejection cases common to them (the production clone this
  * module was extracted to eliminate).
  *
  * Both `classifyTokenAsPathCandidate` and `classifyTokenAsRuleCandidate` recognize
@@ -143,8 +143,11 @@ const REGEX_METACHAR_PATTERN = /\.\*|\.\+|\\\||\\\(|\\\)|\[.*?\]|\^\//;
  * filesystem path, regardless of which classifier is asking.
  *
  * Rejects: empty tokens, flags (leading `-`), env assignments (`FOO=/bar`),
- * URLs, `@scope/package` patterns, bare-slash tokens, and regex metacharacter
- * sequences.
+ * URLs, `@scope/package` patterns, and regex metacharacter sequences.
+ *
+ * A bare `/` (or `//`, `///`) is NOT rejected: it denotes the filesystem root,
+ * a deliberate external-directory access (`find /`, `ls /`), so it must reach
+ * the path surfaces like any other absolute token (#583).
  */
 function rejectNonPathToken(token: string): boolean {
   if (!token) return true;
@@ -163,10 +166,6 @@ function rejectNonPathToken(token: string): boolean {
   // since it looks like an absolute-rooted path, not an npm scope.
   if (token.startsWith("@") && !token.startsWith("@/")) return true;
 
-  // Bare-slash tokens (/, //, ///) resolve to filesystem root and are never
-  // meaningful path arguments in practice.
-  if (/^\/+$/.test(token)) return true;
-
   if (REGEX_METACHAR_PATTERN.test(token)) return true;
 
   return false;

package/src/{input-normalizer.ts → access-intent/input-normalizer.ts}

@@ -1,10 +1,10 @@
-import type { AccessIntent } from "./access-intent/access-intent";
-import { classifyToolKind } from "./access-intent/tool-kind";
-import { stripBashCommentLines } from "./bash-arity";
+import { stripBashCommentLines } from "#src/bash-arity";
+import type { PathNormalizer } from "#src/path-normalizer";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
+import type { AccessIntent } from "./access-intent";
 import { createMcpPermissionTargets } from "./mcp-targets";
-import type { PathNormalizer } from "./path-normalizer";
 import { PATH_SURFACES } from "./path-surfaces";
-import { getNonEmptyString, toRecord } from "./value-guards";
+import { classifyToolKind } from "./tool-kind";
 
 /**
  * Build the {@link AccessIntent} an external policy query (the `Symbol.for()`

package/src/{mcp-targets.ts → access-intent/mcp-targets.ts}

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./value-guards";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 
 /**
  * An ordered accumulator that owns the uniqueness invariant.

package/src/{tool-input-path.ts → access-intent/tool-input-path.ts}

@@ -1,6 +1,6 @@
-import { classifyToolKind } from "./access-intent/tool-kind";
-import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
-import { getNonEmptyString, toRecord } from "./value-guards";
+import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
+import { classifyToolKind } from "./tool-kind";
 
 export function getPathBearingToolPath(
   toolName: string,

package/src/access-intent/tool-kind.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
+import { PATH_BEARING_TOOLS } from "./path-surfaces";
 
 /**
  * What a tool invocation accesses — decided once from the tool name at the

package/src/config-loader.ts

@@ -9,6 +9,7 @@ import {
   getProjectConfigPath,
 } from "./config-paths";
 import {
+  type ShellToolsConfig,
   type UnifiedPermissionConfig,
   unifiedConfigSchema,
 } from "./config-schema";
@@ -20,7 +21,7 @@ import { isDenyWithReason, isPermissionState } from "./types";
 // the single source of truth) and re-exported so existing importers keep their
 // import path. All fields are optional so partial configs merge before
 // defaults are applied downstream.
-export type { UnifiedPermissionConfig };
+export type { ShellToolsConfig, UnifiedPermissionConfig };
 
 export interface UnifiedConfigLoadResult {
   config: UnifiedPermissionConfig;
@@ -228,6 +229,19 @@ export function mergeUnifiedConfigs(
     merged.piInfrastructureReadPaths = piInfrastructureReadPaths;
   }
 
+  // shellTools: shallow-merge by tool name so a project entry overrides a
+  // colliding tool's alias but never drops a global entry (a dropped alias is
+  // a silent enforcement regression).
+  const baseShell = base.shellTools;
+  const overrideShell = override.shellTools;
+  if (baseShell && overrideShell) {
+    merged.shellTools = { ...baseShell, ...overrideShell };
+  } else if (baseShell) {
+    merged.shellTools = baseShell;
+  } else if (overrideShell) {
+    merged.shellTools = overrideShell;
+  }
+
   // Permission: deep-shallow merge
   const basePerm = base.permission;
   const overridePerm = override.permission;

package/src/config-schema.ts

@@ -110,6 +110,41 @@ const permissionSchema = z
     ],
   });
 
+const shellToolAliasSchema = z
+  .strictObject({
+    commandArgument: z.string().min(1).meta({
+      description:
+        "The name of the tool's input argument holding the shell command string (e.g. 'cmd').",
+    }),
+    workdirArgument: z.string().min(1).optional().meta({
+      description:
+        "Optional name of the tool's input argument holding the working directory (e.g. 'workdir').",
+    }),
+  })
+  .meta({
+    description:
+      "Maps one shell-aliased tool to the input arguments holding its command and (optionally) its working directory.",
+  });
+
+const shellToolsSchema = z
+  .record(
+    z.string().min(1).meta({
+      description: "A non-bash tool name that carries shell semantics.",
+    }),
+    shellToolAliasSchema,
+  )
+  .meta({
+    description:
+      "Maps non-bash tool names that carry shell semantics to the input arguments holding their command and working directory.",
+    markdownDescription:
+      'Records which non-`bash` tools carry shell semantics, mapping each tool name to the input argument holding its command (and optionally its working directory).\n\nUse this when an extension replaces the native `bash` tool under a different name — e.g. `@howaboua/pi-codex-conversion` registers `exec_command` with a `cmd` argument and an optional `workdir`. Recording the alias lets the permission system gate that tool through the same bash enforcement stack as native `bash` (command decomposition, wrapper flooring, path/external-directory token gates, and `bash:` rules).\n\nExample:\n\n```json\n"shellTools": {\n  "exec_command": { "commandArgument": "cmd", "workdirArgument": "workdir" }\n}\n```\n\n**Merge order:** shallow-merge by tool name across global → project. A project entry overrides a specific tool\'s mapping on key collision but never drops a global entry.',
+    examples: [
+      {
+        exec_command: { commandArgument: "cmd", workdirArgument: "workdir" },
+      },
+    ],
+  });
+
 /**
  * The on-disk config file shape.
  *
@@ -165,6 +200,7 @@ export const unifiedConfigSchema = z
       default: [],
     }),
     permission: permissionSchema.optional(),
+    shellTools: shellToolsSchema.optional(),
   })
   .meta({
     title: "PI Permission System Configuration",
@@ -186,6 +222,9 @@ export type PatternValue = z.infer<typeof patternValueSchema>;
 /** The on-disk permission shape inside the `"permission"` key. */
 export type FlatPermissionConfig = z.infer<typeof permissionSchema>;
 
+/** The `shellTools` map: tool name → shell-alias argument mapping. */
+export type ShellToolsConfig = z.infer<typeof shellToolsSchema>;
+
 /** The raw config file shape after validation (all fields optional). */
 export type UnifiedPermissionConfig = z.infer<typeof unifiedConfigSchema>;
 

package/src/extension-config.ts

@@ -2,7 +2,10 @@ import { mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { UnifiedPermissionConfig } from "./config-loader";
+import type {
+  ShellToolsConfig,
+  UnifiedPermissionConfig,
+} from "./config-loader";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -16,6 +19,8 @@ export interface PermissionSystemExtensionConfig {
   toolInputPreviewMaxLength?: number;
   /** Max length of inline pattern/path summaries (grep/find/ls) in permission prompts. Defaults to 80. */
   toolTextSummaryMaxLength?: number;
+  /** Non-bash tools that carry shell semantics, keyed by tool name. */
+  shellTools?: ShellToolsConfig;
 }
 
 export const DEFAULT_EXTENSION_CONFIG: PermissionSystemExtensionConfig = {
@@ -63,6 +68,9 @@ export function normalizePermissionSystemConfig(
   if (raw.toolTextSummaryMaxLength !== undefined) {
     result.toolTextSummaryMaxLength = raw.toolTextSummaryMaxLength;
   }
+  if (raw.shellTools !== undefined) {
+    result.shellTools = raw.shellTools;
+  }
   return result;
 }
 

package/src/handlers/gates/external-directory.ts

@@ -1,9 +1,9 @@
+import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
-import { getToolInputPath } from "#src/tool-input-path";
 import type { GateResult } from "./descriptor";
 import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";

package/src/handlers/gates/path.ts

@@ -1,9 +1,9 @@
+import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
-import { getToolInputPath } from "#src/tool-input-path";
 import type { GateDescriptor, GateResult } from "./descriptor";
 import type { ToolCallContext } from "./types";
 

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,12 +1,12 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
+import { getPathBearingToolPath } from "#src/access-intent/tool-input-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { ToolInputFormatterLookup } from "#src/tool-input-formatter-registry";
-import { getPathBearingToolPath } from "#src/tool-input-path";
 import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,

package/src/handlers/gates/tool.ts

@@ -1,10 +1,10 @@
 import type { AccessPath } from "#src/access-intent/access-path";
+import { PATH_BEARING_TOOLS } from "#src/access-intent/path-surfaces";
+import { getPathBearingToolPath } from "#src/access-intent/tool-input-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
-import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
 import { suggestSessionPattern } from "#src/pattern-suggest";
 import { formatAskPrompt } from "#src/permission-prompts";
 import { SessionApproval } from "#src/session-approval";
-import { getPathBearingToolPath } from "#src/tool-input-path";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";

package/src/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
 import { warmBashParser } from "./access-intent/bash/parser";
+import { buildAccessIntentForSurface } from "./access-intent/input-normalizer";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
 import {
   ForwardedRequestServer,
@@ -29,7 +30,6 @@ import { GateRunner } from "./handlers/gates/runner";
 import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
 import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
-import { buildAccessIntentForSurface } from "./input-normalizer";
 import { pathFlavorForPlatform } from "./path/path-flavor";
 import { PermissionManager } from "./permission-manager";
 import { PermissionResolver } from "./permission-resolver";

package/src/path/pi-infrastructure-read.ts

@@ -1,8 +1,7 @@
 import { join } from "node:path";
-
+import { READ_ONLY_PATH_BEARING_TOOLS } from "#src/access-intent/path-surfaces";
 import { expandHomePath } from "#src/expand-home";
 import type { PathFlavor } from "#src/path/path-flavor";
-import { READ_ONLY_PATH_BEARING_TOOLS } from "#src/path-surfaces";
 import { wildcardMatch } from "#src/wildcard-matcher";
 
 function containsGlobChars(value: string): boolean {

package/src/pattern-suggest.ts

@@ -1,5 +1,5 @@
+import { PATH_BEARING_TOOLS } from "./access-intent/path-surfaces";
 import { prefix, stripBashCommentLines } from "./bash-arity";
-import { PATH_BEARING_TOOLS } from "./path-surfaces";
 import { deriveApprovalPattern } from "./session-rules";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */

package/src/permission-manager.ts

@@ -1,15 +1,15 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "./access-intent/access-intent";
+import { normalizeInput } from "./access-intent/input-normalizer";
+import { PATH_SURFACES } from "./access-intent/path-surfaces";
 import { classifyToolKind } from "./access-intent/tool-kind";
 import {
   getGlobalConfigPath,
   getProjectAgentsDir,
   getProjectConfigPath,
 } from "./config-paths";
-import { normalizeInput } from "./input-normalizer";
 import { normalizeFlatConfig } from "./normalize";
 import { type PathFlavor, posixPathFlavor } from "./path/path-flavor";
-import { PATH_SURFACES } from "./path-surfaces";
 import {
   FilePolicyLoader,
   type PolicyLoader,

package/src/permissions-service.ts

@@ -1,6 +1,6 @@
 import type { AccessIntent } from "./access-intent/access-intent";
+import { buildAccessIntentForSurface } from "./access-intent/input-normalizer";
 import { resolveBashAdvisoryCheck } from "./bash-advisory-check";
-import { buildAccessIntentForSurface } from "./input-normalizer";
 import type { PathNormalizer } from "./path-normalizer";
 import type { PermissionsService } from "./service";
 import type {

package/src/rule.ts

@@ -1,6 +1,6 @@
 import type { PathFlavor } from "#src/path/path-flavor";
 
-import { PATH_SURFACES } from "./path-surfaces";
+import { PATH_SURFACES } from "./access-intent/path-surfaces";
 import type { PermissionState } from "./types";
 import { type WildcardMatchOptions, wildcardMatch } from "./wildcard-matcher";