@gotgenes/pi-permission-system 20.4.2 → 20.6.0

package/CHANGELOG.md

@@ -5,6 +5,38 @@ 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.6.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.5.0...pi-permission-system-v20.6.0) (2026-07-13)
+
+
+### Features
+
+* **pi-permission-system:** add resolveShellInvocation dispatch point ([5c5edc8](https://github.com/gotgenes/pi-packages/commit/5c5edc84cd46dafb5dade9fd51b2946632b72776))
+* **pi-permission-system:** gate aliased shell tools through the bash stack ([2c17f2c](https://github.com/gotgenes/pi-packages/commit/2c17f2ce4b6207684f999d0bc30fe630c79934bb)), closes [#574](https://github.com/gotgenes/pi-packages/issues/574)
+* **pi-permission-system:** resolve and gate aliased shell workdir ([d9b2af8](https://github.com/gotgenes/pi-packages/commit/d9b2af86107671366935242e704d1f17821db73f)), closes [#574](https://github.com/gotgenes/pi-packages/issues/574)
+
+
+### Documentation
+
+* **pi-permission-system:** document live shellTools enforcement ([b8048ed](https://github.com/gotgenes/pi-packages/commit/b8048eddba5f8c0e9b82cf0c3e31055e7813b745))
+
+## [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 are gated at full parity with native `bash` — 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, and an aliased tool is then gated at full parity with native `bash` — command decomposition, wrapper flooring, path and external-directory token gates, and `bash:` rules — with the invoked tool name preserved in the review log.
+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`). |
+
+When `workdirArgument` is set, the tool's working directory is the base the command's relative paths resolve against, and the working directory itself is gated by `external_directory` when it falls outside the session's working directory.
+
+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.
+
 ---
 
 ## Policy Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "20.4.2",
+  "version": "20.6.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/bash-path-resolver.ts

@@ -101,20 +101,57 @@ export class BashPathResolver {
   constructor(
     private readonly normalizer: PathNormalizer,
     private readonly isPromotablePathToken: PathRuleTokenMatcher = NO_PROMOTION,
+    private readonly workdir?: string,
   ) {}
 
   /**
    * Resolve a parsed bash program's path references into its external-path and
    * rule-candidate slices, walking the AST exactly once.
+   *
+   * When a `workdir` is set (an aliased shell tool's working directory, #574),
+   * it seeds the initial effective base — as if the program were prefixed with
+   * `cd <workdir>` — so relative tokens resolve against it, and the `workdir`
+   * itself is added to the external paths when it resolves outside the cwd.
+   * Containment is always measured against the session cwd baked into the
+   * normalizer, so a `workdir` outside the cwd does not widen the sandbox.
    */
   resolve(rootNode: TSNode): ResolvedBashPaths {
-    const candidates = this.collectPathCandidates(rootNode);
+    const initialBase =
+      this.workdir === undefined
+        ? CWD_BASE
+        : this.deriveBaseFromCdTarget(CWD_BASE, this.workdir);
+    const candidates = this.collectPathCandidates(rootNode, initialBase);
     return {
-      externalPaths: this.projectExternalPaths(candidates),
+      externalPaths: this.withWorkdirExternal(
+        this.projectExternalPaths(candidates),
+      ),
       ruleCandidates: this.projectRuleCandidates(candidates),
     };
   }
 
+  /**
+   * Prepend the `workdir`'s own {@link AccessPath} to the external paths when it
+   * resolves outside the cwd. A real `cd /etc` flags `/etc` via its argument
+   * token; the seeded base carries no such token, so it is added explicitly and
+   * deduplicated against the command's own external tokens (#574).
+   */
+  private withWorkdirExternal(
+    tokenExternals: readonly AccessPath[],
+  ): AccessPath[] {
+    if (this.workdir === undefined) return [...tokenExternals];
+    const wdPath = this.normalizer.forBashToken(this.workdir);
+    const canonical = wdPath.boundaryValue();
+    const isExternal = canonical
+      ? this.normalizer.isBoundaryOutsideWorkingDirectory(canonical)
+      : true;
+    if (!isExternal) return [...tokenExternals];
+    const key = canonical || wdPath.value();
+    const alreadyPresent = tokenExternals.some(
+      (p) => (p.boundaryValue() || p.value()) === key,
+    );
+    return alreadyPresent ? [...tokenExternals] : [wdPath, ...tokenExternals];
+  }
+
   // ── AST walk — collect PathCandidates ──────────────────────────────────
 
   /**
@@ -129,9 +166,12 @@ export class BashPathResolver {
    * inherit the enclosing base without folding their own `cd`s (a conservative
    * first tier).
    */
-  private collectPathCandidates(rootNode: TSNode): PathCandidate[] {
+  private collectPathCandidates(
+    rootNode: TSNode,
+    initialBase: EffectiveBase,
+  ): PathCandidate[] {
     const out: PathCandidate[] = [];
-    this.walkForCandidates(rootNode, CWD_BASE, out);
+    this.walkForCandidates(rootNode, initialBase, out);
     return out;
   }
 
@@ -330,6 +370,25 @@ export class BashPathResolver {
     if (extractCommandName(commandNode) !== "cd") return base;
     const target = cdLiteralTarget(commandNode);
     if (target === null) return UNKNOWN_BASE;
+    return this.deriveBaseFromCdTarget(base, target);
+  }
+
+  /**
+   * Fold a literal `cd`/working-directory target string into the effective
+   * base, delegating the platform/MSYS interpretation to the
+   * {@link PathNormalizer}. Owns only the base-folding state:
+   *
+   * - `absolute` → a fresh known base (recovers from an earlier unknown base).
+   * - `unknown` → the base becomes conservatively unknown.
+   * - `relative` → join into a known base, or stay unknown if already unknown.
+   *
+   * Shared by {@link foldCd} (inline `cd` commands) and the initial-base seed
+   * (an aliased shell tool's `workdir`, an implicit leading `cd <workdir>`).
+   */
+  private deriveBaseFromCdTarget(
+    base: EffectiveBase,
+    target: string,
+  ): EffectiveBase {
     const interpreted = this.normalizer.interpretBashCdTarget(target);
     switch (interpreted.kind) {
       case "absolute":

package/src/access-intent/bash/program.ts

@@ -25,6 +25,7 @@ export type { BashCommand, BashPathRuleCandidate };
  */
 export class BashProgram {
   private constructor(
+    private readonly sourceCommand: string,
     private readonly commandUnits: readonly BashCommand[],
     private readonly resolvedExternalPaths: readonly AccessPath[],
     private readonly resolvedRuleCandidates: readonly BashPathRuleCandidate[],
@@ -44,22 +45,30 @@ export class BashProgram {
    * specific `path` deny/ask rule (#509). Defaults to promoting nothing, so
    * callers that only read `externalPaths()` (e.g. `bash-path-extractor.ts`)
    * are unaffected.
+   *
+   * `options.workdir`, when supplied (an aliased shell tool's working directory,
+   * #574), seeds the initial effective base — as if the command were prefixed
+   * with `cd <workdir>` — so relative tokens resolve against it, and the workdir
+   * itself is flagged as external when it resolves outside the cwd.
    */
   static async parse(
     command: string,
     normalizer: PathNormalizer,
     isPromotablePathToken?: PathRuleTokenMatcher,
+    options?: { workdir?: string },
   ): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
-    if (!tree) return new BashProgram([], [], []);
+    if (!tree) return new BashProgram(command, [], [], []);
 
     try {
       const { externalPaths, ruleCandidates } = new BashPathResolver(
         normalizer,
         isPromotablePathToken,
+        options?.workdir,
       ).resolve(tree.rootNode);
       return new BashProgram(
+        command,
         collectCommands(tree.rootNode),
         externalPaths,
         ruleCandidates,
@@ -69,6 +78,18 @@ export class BashProgram {
     }
   }
 
+  /**
+   * The source command string this program was parsed from.
+   *
+   * The bash gates read this for prompts, logs, and decision display instead of
+   * receiving the command as a separate parameter — the program is the parsed
+   * command, so it owns its source text (#574). Native `bash` and an aliased
+   * shell tool alike reach the gates through this single collaborator.
+   */
+  commandText(): string {
+    return this.sourceCommand;
+  }
+
   /**
    * The top-level command-pattern units of the chain, in source order.
    *

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,6 @@
-import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
+import type { ShellToolsConfig } from "#src/config-schema";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
+import { PATH_BEARING_TOOLS } from "./path-surfaces";
 
 /**
  * What a tool invocation accesses — decided once from the tool name at the
@@ -39,6 +41,59 @@ export function classifyToolKind(toolName: string): ToolKind {
   return "extension";
 }
 
+/** A shell invocation's effective command and optional working directory. */
+export interface ShellInvocation {
+  /** The shell command string to decompose and gate. */
+  command: string;
+  /** The working directory the command runs in, if the tool projects one. */
+  workdir: string | undefined;
+}
+
+/**
+ * Decide whether a tool invocation carries shell semantics, and if so extract
+ * its command and working directory.
+ *
+ * Native `bash` and any tool recorded in `shellTools` both yield a
+ * {@link ShellInvocation}; every other tool yields `null`. This is the single
+ * dispatch point the bash gate pipeline consults instead of re-deriving
+ * `toolName === "bash"` and reading `input.command`, so an aliased shell tool
+ * (e.g. `@howaboua/pi-codex-conversion`'s `exec_command`) is routed through the
+ * same bash enforcement stack as native `bash` (#574).
+ *
+ * The command and workdir are read through {@link getNonEmptyString} (trimmed,
+ * empty → `""`/`undefined`), matching the pipeline's existing native-bash
+ * extraction. Kept separate from {@link classifyToolKind} because it needs
+ * config (the alias map) and returns a richer product than a {@link ToolKind}
+ * string — `classifyToolKind` stays AccessPath-free and config-free.
+ */
+export function resolveShellInvocation(
+  toolName: string,
+  input: unknown,
+  aliases: ShellToolsConfig | undefined,
+): ShellInvocation | null {
+  const name = toolName.trim();
+  const record = toRecord(input);
+
+  if (name === "bash") {
+    return {
+      command: getNonEmptyString(record.command) ?? "",
+      workdir: undefined,
+    };
+  }
+
+  const alias = aliases?.[name];
+  if (alias) {
+    return {
+      command: getNonEmptyString(record[alias.commandArgument]) ?? "",
+      workdir: alias.workdirArgument
+        ? (getNonEmptyString(record[alias.workdirArgument]) ?? undefined)
+        : undefined,
+    };
+  }
+
+  return null;
+}
+
 /** The resolved-check fields that decide MCP-ness. */
 interface McpKindFields {
   toolName: string;

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/bash-external-directory.ts

@@ -2,7 +2,6 @@ import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
-import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";
@@ -13,21 +12,21 @@ import type { ToolCallContext } from "./types";
  *
  * Reads the external paths from the injected `BashProgram` and checks whether
  * any reference directories outside the working directory. Returns `null` when the gate
- * does not apply (tool is not bash, no CWD, or no external paths found).
+ * does not apply (not a shell invocation, no command, or no external paths found).
  * Returns a `GateBypass` when all paths are allowed (by config or session rule).
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
+ *
+ * The shell command (native `bash` or an aliased shell tool) is read from the
+ * injected `BashProgram`, which owns the source text it was parsed from, so
+ * this gate does not re-derive the input field name (#574).
  */
 export function describeBashExternalDirectoryGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
   resolver: ScopedPermissionResolver,
 ): GateResult {
-  if (tcc.toolName !== "bash") return null;
-
-  const command = getNonEmptyString(toRecord(tcc.input).command);
-  if (!command) return null;
-
   if (!bashProgram) return null;
+  const command = bashProgram.commandText();
 
   const externalPaths = bashProgram.externalPaths();
   if (externalPaths.length === 0) return null;

package/src/handlers/gates/bash-path.ts

@@ -4,7 +4,6 @@ import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
-import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";
@@ -20,22 +19,22 @@ import type { ToolCallContext } from "./types";
  * restrictive result, while prompts, logs, and session approvals use the raw
  * token.
  *
- * Returns `null` when the gate does not apply (tool is not bash, no command,
- * no tokens extracted, or all tokens evaluate to `allow`).
+ * Returns `null` when the gate does not apply (not a shell invocation, no
+ * command, no tokens extracted, or all tokens evaluate to `allow`).
  * Returns a `GateBypass` when all tokens are session-covered.
  * Returns a `GateDescriptor` for the most restrictive token needing a check.
+ *
+ * The shell command (native `bash` or an aliased shell tool) is read from the
+ * injected `BashProgram`, which owns the source text it was parsed from, so
+ * this gate does not re-derive the input field name (#574).
  */
 export function describeBashPathGate(
   tcc: ToolCallContext,
   bashProgram: BashProgram | null,
   resolver: ScopedPermissionResolver,
 ): GateResult {
-  if (tcc.toolName !== "bash") return null;
-
-  const command = getNonEmptyString(toRecord(tcc.input).command);
-  if (!command) return null;
-
   if (!bashProgram) return null;
+  const command = bashProgram.commandText();
 
   const candidates = bashProgram.pathRuleCandidates();
   if (candidates.length === 0) return null;

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,18 +1,21 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { BashProgram } from "#src/access-intent/bash/program";
-import { classifyToolKind } from "#src/access-intent/tool-kind";
+import { getPathBearingToolPath } from "#src/access-intent/tool-input-path";
+import {
+  resolveShellInvocation,
+  type ShellInvocation,
+} from "#src/access-intent/tool-kind";
+import type { ShellToolsConfig } from "#src/config-schema";
 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,
 } from "#src/tool-preview-formatter";
 import type { PathRuleTokenMatcher, PermissionCheckResult } from "#src/types";
-import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";
@@ -43,6 +46,12 @@ export interface ToolCallGateInputs {
   getToolPreviewLimits(): ToolPreviewFormatterOptions;
   /** The session's path normalizer (platform + cwd baked in). */
   getPathNormalizer(): PathNormalizer;
+  /**
+   * The configured shell-tool aliases (`shellTools`), or `undefined` when none
+   * are set. Consulted by {@link resolveShellInvocation} so an aliased shell
+   * tool is gated through the bash stack at parity with native `bash` (#574).
+   */
+  getShellToolAliases(): ShellToolsConfig | undefined;
   /**
    * Predicate deciding whether a bare bash token should be promoted into the
    * `path` rule-candidate surface (#509), scoped to the given agent.
@@ -73,20 +82,24 @@ export class ToolCallGatePipeline {
     tcc: ToolCallContext,
     runner: GateRunner,
   ): Promise<GateOutcome> {
-    // Parse the bash command exactly once per evaluate; the three bash gates
-    // share this single BashProgram instead of each re-parsing (#308).
-    const command = getNonEmptyString(toRecord(tcc.input).command);
+    // Resolve the shell invocation once: native `bash` and any tool recorded in
+    // `shellTools` both yield a command (+ optional workdir); every other tool
+    // yields null (#574). The three bash gates then share the single BashProgram
+    // parsed from that command instead of each re-parsing (#308).
+    const shell = resolveShellInvocation(
+      tcc.toolName,
+      tcc.input,
+      this.inputs.getShellToolAliases(),
+    );
     const normalizer = this.inputs.getPathNormalizer();
-    const bashProgram =
-      classifyToolKind(tcc.toolName) === "bash" && command
-        ? await BashProgram.parse(
-            command,
-            normalizer,
-            this.inputs.getPromotablePathTokenMatcher(
-              tcc.agentName ?? undefined,
-            ),
-          )
-        : null;
+    const bashProgram = shell?.command
+      ? await BashProgram.parse(
+          shell.command,
+          normalizer,
+          this.inputs.getPromotablePathTokenMatcher(tcc.agentName ?? undefined),
+          { workdir: shell.workdir },
+        )
+      : null;
 
     const formatter = new ToolPreviewFormatter(
       this.inputs.getToolPreviewLimits(),
@@ -115,8 +128,8 @@ export class ToolCallGatePipeline {
       () => {
         const { toolCheck, accessPath } = this.resolvePerToolCheck(
           tcc,
+          shell,
           bashProgram,
-          command,
           normalizer,
         );
         const toolDescriptor = describeToolGate(
@@ -124,6 +137,7 @@ export class ToolCallGatePipeline {
           toolCheck,
           formatter,
           accessPath,
+          shell,
         );
         toolDescriptor.preCheck = toolCheck;
         return toolDescriptor;
@@ -156,18 +170,31 @@ export class ToolCallGatePipeline {
    */
   private resolvePerToolCheck(
     tcc: ToolCallContext,
+    shell: ShellInvocation | null,
     bashProgram: BashProgram | null,
-    command: string | null,
     normalizer: PathNormalizer,
   ): { toolCheck: PermissionCheckResult; accessPath?: AccessPath } {
-    if (classifyToolKind(tcc.toolName) === "bash" && bashProgram) {
+    if (shell) {
+      if (bashProgram) {
+        return {
+          toolCheck: resolveBashCommandCheck(
+            bashProgram.commandText(),
+            bashProgram.commands(),
+            tcc.agentName ?? undefined,
+            this.resolver,
+          ),
+        };
+      }
+      // A shell invocation whose command did not parse (e.g. empty) still
+      // resolves on the `bash` surface, so an aliased tool never falls through
+      // to its own extension-tool surface.
       return {
-        toolCheck: resolveBashCommandCheck(
-          command ?? "",
-          bashProgram.commands(),
-          tcc.agentName ?? undefined,
-          this.resolver,
-        ),
+        toolCheck: this.resolver.resolve({
+          kind: "tool",
+          surface: "bash",
+          input: { command: shell.command },
+          agentName: tcc.agentName ?? undefined,
+        }),
       };
     }
 

package/src/handlers/gates/tool.ts

@@ -1,10 +1,13 @@
 import type { AccessPath } from "#src/access-intent/access-path";
-import { classifyToolKind } from "#src/access-intent/tool-kind";
-import { PATH_BEARING_TOOLS } from "#src/path-surfaces";
+import { PATH_BEARING_TOOLS } from "#src/access-intent/path-surfaces";
+import { getPathBearingToolPath } from "#src/access-intent/tool-input-path";
+import {
+  classifyToolKind,
+  type ShellInvocation,
+} from "#src/access-intent/tool-kind";
 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";
@@ -20,11 +23,11 @@ import type { ToolCallContext } from "./types";
  * others (or a path-bearing tool with no path) → catch-all wildcard.
  */
 function deriveSuggestionValue(
-  tcc: ToolCallContext,
+  toolName: string,
   check: PermissionCheckResult,
   accessPath?: AccessPath,
 ): string {
-  switch (classifyToolKind(tcc.toolName)) {
+  switch (classifyToolKind(toolName)) {
     case "bash":
       return check.command ?? "";
     case "mcp":
@@ -45,7 +48,14 @@ export function describeToolGate(
   check: PermissionCheckResult,
   formatter: ToolPreviewFormatter,
   accessPath?: AccessPath,
+  shell?: ShellInvocation | null,
 ): GateDescriptor {
+  // A shell invocation (native `bash` or an aliased shell tool) is gated on the
+  // `bash` surface — its session rule, decision value, and suggestion are
+  // bash-shaped — while the invoked tool name is preserved in the prompt and
+  // review log so a user sees which tool actually ran (#574).
+  const gateSurface = shell ? "bash" : tcc.toolName;
+
   const permissionLogContext = formatter.getPermissionLogContext(
     check,
     tcc.input,
@@ -54,8 +64,8 @@ export function describeToolGate(
 
   // Compute session approval suggestion for the "for this session" option.
   const suggestion = suggestSessionPattern(
-    tcc.toolName,
-    deriveSuggestionValue(tcc, check, accessPath),
+    gateSurface,
+    deriveSuggestionValue(gateSurface, check, accessPath),
   );
 
   const askMessage = formatAskPrompt(
@@ -66,7 +76,7 @@ export function describeToolGate(
   );
 
   return {
-    surface: tcc.toolName,
+    surface: gateSurface,
     input: tcc.input,
     denialContext: {
       kind: "tool",
@@ -95,9 +105,9 @@ export function describeToolGate(
       ...permissionLogContext,
     },
     decision: {
-      surface: tcc.toolName,
+      surface: gateSurface,
       value: deriveDecisionValue(
-        tcc.toolName,
+        gateSurface,
         check,
         getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
       ),

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/permission-session.ts

@@ -5,6 +5,7 @@ import {
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
 import type { AuthorizerSelectionLifecycle } from "./authority/authorizer-selection";
+import type { ShellToolsConfig } from "./config-schema";
 import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
@@ -205,6 +206,16 @@ export class PermissionSession implements ToolCallGateInputs {
     return resolveToolPreviewLimits(this.config);
   }
 
+  /**
+   * The configured shell-tool aliases (`shellTools`), mapping a non-`bash` tool
+   * name to the input arguments holding its command and optional working
+   * directory. `undefined` when no aliases are configured. Consumed by the
+   * gate pipeline's {@link resolveShellInvocation} consult (#574).
+   */
+  getShellToolAliases(): ShellToolsConfig | undefined {
+    return this.config.shellTools;
+  }
+
   // ── Path normalization ────────────────────────────────────────────────
 
   /**

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";