@gotgenes/pi-permission-system 20.5.0 → 20.6.0

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).
 
+## [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)
 
 

package/README.md

@@ -109,7 +109,7 @@ 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).
+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).
 

package/docs/configuration.md

@@ -115,7 +115,7 @@ The native `bash` tool goes through the full bash enforcement stack: command dec
 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.
+`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
@@ -131,6 +131,8 @@ Each key is a tool name; its value maps the tool's input arguments (the keys of
 | `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).
@@ -138,8 +140,6 @@ To change a specific tool's mapping, set that tool's key at the project scope (t
 `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.5.0",
+  "version": "20.6.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

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/tool-kind.ts

@@ -1,3 +1,5 @@
+import type { ShellToolsConfig } from "#src/config-schema";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { PATH_BEARING_TOOLS } from "./path-surfaces";
 
 /**
@@ -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/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/tool-call-gate-pipeline.ts

@@ -1,7 +1,11 @@
 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 {
+  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";
@@ -12,7 +16,6 @@ import {
   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,7 +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 {
+  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";
@@ -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/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 ────────────────────────────────────────────────
 
   /**