@gotgenes/pi-permission-system 32.0.6 → 33.0.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [33.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.1.0...pi-permission-system-v33.0.0) (2026-09-18)
+
+
+### Features
+
+* **breaking:** apply MCP server rules to prefix-named tools such as github_search_code ([1994b32](https://github.com/gotgenes/pi-packages/commit/1994b3227e16898c8ca4ff0d7a17b258dc306bcb)), closes [#929](https://github.com/gotgenes/pi-packages/issues/929)
+
+### Bug Fixes
+
+* **breaking:** honor last-match-wins for MCP rules instead of stopping at the first candidate ([c573696](https://github.com/gotgenes/pi-packages/commit/c57369648a4ffd64de9b07999e2687ceaa96e867))
+* stop deriving unmatchable re-prefixed MCP candidates for already-qualified tool names ([72b3b0b](https://github.com/gotgenes/pi-packages/commit/72b3b0b6859511f9ce41d55aa803e57e5886077c)), closes [#929](https://github.com/gotgenes/pi-packages/issues/929)
+
+### Documentation
+
+* describe how MCP tool names derive server and tool permission targets ([49484a6](https://github.com/gotgenes/pi-packages/commit/49484a635d69292e8e0ad17dbe792019acd97269))
+
+## [32.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.6...pi-permission-system-v32.1.0) (2026-09-16)
+
+
+### Features
+
+* **pi-permission-system:** let the permission dialog's hotkeys be remapped ([e8fa79b](https://github.com/gotgenes/pi-packages/commit/e8fa79b6a30b925441aa2afb21c13fb10ff0b133)), closes [#927](https://github.com/gotgenes/pi-packages/issues/927)
+* **pi-permission-system:** report a refused permission-dialog key binding ([6798c63](https://github.com/gotgenes/pi-packages/commit/6798c6359cee2abed5f3e1cf28f10002d22d765d)), closes [#927](https://github.com/gotgenes/pi-packages/issues/927)
+
+### Documentation
+
+* **pi-permission-system:** document permissionDialogKeys ([63d3221](https://github.com/gotgenes/pi-packages/commit/63d3221c5b3eac76843c63b4d1e81e8afde60c8f)), closes [#927](https://github.com/gotgenes/pi-packages/issues/927)
+
 ## [32.0.6](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v32.0.5...pi-permission-system-v32.0.6) (2026-09-16)
 
 

package/README.md

@@ -66,6 +66,7 @@ All permissions use one of three states:
 
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 In an interactive TUI session the prompt is an inline keybind dialog — `y` approve, `s` approve for this session, `n` deny, `r` deny with a reason — where each hotkey arms and a second press confirms (configurable via `doublePressToConfirm`).
+The hotkeys themselves are remappable through `permissionDialogKeys`, which matters if you type with an input method editor: composition mode swallows letter keys before they reach the terminal, and digits do not.
 A file-access ask that proves a single direction offers `b` as well, granting the session both directions instead of only the one the gate proved.
 The prompt shows one fact per line — who is asking, the tool, the matched rule, the value being decided — within a row budget, so a large tool input cannot take over the transcript; `Ctrl+O` (`app.tools.expand`) expands it to the complete request.
 See [docs/configuration.md](docs/configuration.md#inline-permission-dialog-tui) for the hotkeys and [docs/session-approvals.md](docs/session-approvals.md) for session-scoped rules and pattern suggestions.

package/config/config.example.json

@@ -5,6 +5,13 @@
   "permissionReviewLog": true,
   "yoloMode": false,
   "doublePressToConfirm": true,
+  "permissionDialogKeys": {
+    "approve": "y",
+    "approveSession": "s",
+    "approveSessionBoth": "b",
+    "deny": "n",
+    "denyWithReason": "r"
+  },
 
   "forwardingTimeoutMs": 600000,
 

package/docs/configuration.md

@@ -37,6 +37,7 @@ See [migration/0644-project-trust-gating.md](migration/0644-project-trust-gating
 
 The `permission` object uses deep-shallow merge: string-vs-string replaces; both-object shallow-merges pattern maps; string-vs-object the override wins entirely.
 Scalar fields (`debugLog`, `permissionReviewLog`, `yoloMode`, `doublePressToConfirm`, `forwardingTimeoutMs`, `promptMaxRows`, `promptFieldMaxWidth`) use simple replacement.
+`permissionDialogKeys` replaces the whole map rather than merging entry by entry, so the map that was validated is the map that applies.
 
 **Invalid higher-precedence scope fails closed.**
 If a non-global scope (project config, global agent frontmatter, or project agent frontmatter) is present but fails to load or validate, it no longer contributes an empty scope that silently inherits the lower scope's rules.
@@ -103,6 +104,7 @@ This clamp is deny-preserving and, like `yoloMode`, applied at composition; when
 | `permissionReviewLog`       | `true`   | Enables the permission request/denial review log at `logs/pi-permission-system-permission-review.jsonl`. Records bash command strings, masked only where a name binds the secret — see [Log file sensitivity](#log-file-sensitivity)         |
 | `yoloMode`                  | `false`  | Auto-approves `ask` results instead of prompting when yolo mode is enabled                                                                                                                                                                   |
 | `doublePressToConfirm`      | `true`   | Requires a confirming second press of a decision hotkey in the inline TUI dialog (see below). TUI sessions only; set to `false` for single-press.                                                                                            |
+| `permissionDialogKeys`      | —        | Remaps the inline TUI dialog's decision hotkeys (see below). One printable character per decision; omitted decisions keep `y` / `s` / `b` / `n` / `r`.                                                                                       |
 | `forwardingTimeoutMs`       | `600000` | How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. A child whose parent is not draining its inbox gives up in ~2 s regardless, whether that parent runs in this process or its own. |
 | `promptMaxRows`             | `24`     | Max rows a permission prompt renders before eliding its evidence. The request's own facts are never elided by this budget; `Ctrl+O` expands the prompt to the complete request.                                                              |
 | `promptFieldMaxWidth`       | `400`    | Max characters of any one field shown in a permission prompt. This is what bounds a single long field (a here-string command, say) that would otherwise fill the prompt through wrapping.                                                    |
@@ -132,12 +134,50 @@ Every other ask shows the four options above without it.
 See [session-approvals.md](session-approvals.md#grant-direction) for what the two widths grant.
 
 Arrow keys / `j`/`k` move the highlight, `enter` confirms the highlighted option, and `esc` denies.
-With `doublePressToConfirm` enabled (the default), a letter hotkey **arms** its action and shows a `Press y again to approve.` hint; press the same key again to commit.
+With `doublePressToConfirm` enabled (the default), a hotkey **arms** its action and shows a `Press y again to approve.` hint; press the same key again to commit.
 Set `doublePressToConfirm` to `false` to commit on the first press.
 
+#### Remapping the hotkeys
+
+Set `permissionDialogKeys` to bind any decision to a different key:
+
+```jsonc
+{
+  "permissionDialogKeys": {
+    "approve": "1",
+    "approveSession": "2",
+    "approveSessionBoth": "3",
+    "deny": "4",
+    "denyWithReason": "5"
+  }
+}
+```
+
+The five decision names above are the only keys the map accepts, and each is optional — a decision you do not name keeps its default letter.
+
+This exists for input method editors.
+While an IME is composing — Chinese Pinyin or Wubi, Japanese, Korean — a letter keypress is consumed by the candidate buffer and never reaches the terminal, so `y` and `n` do nothing and the dialog looks frozen.
+The usual way out of a candidate popup is `esc`, which *does* reach the terminal and which this dialog reads as a denial, so a call you meant to approve gets refused.
+Digits are unaffected on essentially every layout, which is why `1`–`5` is the mapping to reach for.
+
+Each value is a **single printable character**: a lowercase letter, a digit, or a symbol.
+Three things are refused:
+
+- `j` and `k`, which move the dialog's highlight — a decision bound to one would never fire.
+- An uppercase letter.
+  Pi lowercases a key identifier, so `"Y"` would answer to a lowercase `y` rather than to the keystroke you asked for.
+- A character two decisions would share, including one a decision you did **not** remap already holds.
+  Trading two decisions' keys is fine (`{"approve": "n", "deny": "y"}`), because neither keeps the other's.
+
+A refused entry is a warning, never a policy event: that decision keeps its default letter, the rest of the map still applies, and your permission rules are untouched.
+Named keys (`f1`, `pageUp`) and modifier combinations (`ctrl+g`) are not accepted.
+
+One collision no check can see: if you rebind Pi's own `app.tools.expand` to a printable character that is also a dialog binding, expansion wins — the dialog offers that action first, before it maps a decision key.
+
 Pi's tool-expansion binding (`app.tools.expand`, `Ctrl+O` by default) stays live while the dialog is open.
 It expands both the prompt itself — to the complete request, unbounded by `promptMaxRows` and `promptFieldMaxWidth` — and the host's pending tool call, so one keystroke shows you everything before you decide.
 It only toggles the display — it never resolves, commits, or arms the pending decision.
+Because it is offered ahead of the decision keys, a printable rebinding of it shadows a `permissionDialogKeys` entry that names the same character.
 While you are typing a denial reason it is not intercepted, so a rebound printable key still reaches the reason editor.
 
 The reason editor is Pi's own line editor, so it behaves like the chat input: pasting works, as do cursor movement, word and line deletion, the kill ring, and undo.
@@ -483,6 +523,46 @@ MCP permissions match against derived targets from tool input:
 
 > **Note:** Baseline discovery targets auto-allow when any explicit `mcp: allow` rule exists.
 
+In that example `mcp_status` and `mcp_list` allow discovery, `myServer:*` prompts for each of that server's tools, and `dangerousServer` denies every call to it — including `dangerousServer_wipe` and a `{"tool": "wipe", "server": "dangerousServer"}` call — because each rule is written **after** the `"*"` catch-all.
+
+#### How a call becomes targets
+
+One MCP call is looked up under several names, and a rule may name any of them.
+When the call carries no explicit `server`, the server is derived from the tool name against the servers in your MCP config, in this order — the first convention that matches settles the name:
+
+1. **Qualified** — `server:tool` splits directly.
+2. **Prefix** — the **longest** configured server that is the leading segment of `<server>_<tool>`.
+   This is the common case: the `mcp()` proxy carries names like `chrome_devtools_take_screenshot`, and aggregators expose `<server>_<tool>`.
+   `foo_bar_baz` belongs to `foo_bar`, never also to `foo`, and a prefix match settles the name — so `foo_bar_baz_github` derives `foo_bar` and not `github`.
+3. **Suffix** — a legacy name like `search_code_github`, which also derives the qualified forms.
+
+An explicit `server` argument skips derivation entirely.
+
+| Call                                                  | Targets                                                                                              |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `{"tool": "github_search_code"}`, `github` configured | `github_search_code`, `github`, `mcp_call`                                                           |
+| `{"tool": "search_code_github"}`, `github` configured | `github_search_code_github`, `github:search_code_github`, `github`, `search_code_github`, `mcp_call` |
+| `{"tool": "github:search_code"}`                      | `github_search_code`, `github:search_code`, `github`, `search_code`, `mcp_call`                      |
+| `{"tool": "search_code", "server": "github"}`         | `github_search_code`, `github:search_code`, `github`, `search_code`, `mcp_call`                      |
+
+Deriving a server from a name is a heuristic, and it can attach the wrong rule: with `git` configured, a `git_lab_issues` tool from a different server derives `git`.
+Longest-match only helps when both servers are configured.
+Where the distinction matters, pass an explicit `server` argument or use a qualified `server:tool` name.
+
+#### Which rule shape to write
+
+| Rule shape     | Matches                | Use it for                                                                                                                            |
+| -------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `"myServer"`   | the bare-server target | **Server-level policy — the recommended form.** Fires for any call belonging to that server, whichever naming convention produced it. |
+| `"myServer_*"` | the tool-name target   | Tool-level policy for prefix-named tools.                                                                                             |
+| `"myServer:*"` | the qualified target   | Tool-level policy for qualified names and explicit-`server` calls.                                                                    |
+| `"*_myServer"` | the suffix targets     | Only when you have suffix-named tools.                                                                                                |
+
+**Rule position decides, not target order.**
+The last rule matching *any* of a call's targets wins, exactly as on every other surface — so put broad catch-alls first and specific overrides after.
+A `{"*": "allow", "github": "deny"}` config denies github calls; reversing the two lines makes the catch-all win instead.
+The target order above decides only which name the decision is reported under in the prompt and the review log, where the most specific matching name is shown.
+
 String shorthand grants broad MCP access — useful for per-agent overrides:
 
 ```yaml

package/package.json

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

package/schemas/permissions.schema.json

@@ -31,6 +31,43 @@
       "default": true,
       "type": "boolean"
     },
+    "permissionDialogKeys": {
+      "type": "object",
+      "properties": {
+        "approve": {
+          "description": "Key that approves the pending call once. Default: y.",
+          "type": "string"
+        },
+        "approveSession": {
+          "description": "Key that approves for the rest of the session. Default: s.",
+          "type": "string"
+        },
+        "approveSessionBoth": {
+          "description": "Key that approves for the session in both directions. Default: b.",
+          "type": "string"
+        },
+        "deny": {
+          "description": "Key that denies the pending call. Default: n.",
+          "type": "string"
+        },
+        "denyWithReason": {
+          "description": "Key that denies and opens the reason editor. Default: r.",
+          "type": "string"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Remaps the inline TUI permission dialog's decision hotkeys. Each value is one printable character.",
+      "markdownDescription": "Remaps the inline **TUI** permission dialog's decision hotkeys, which default to `y` / `s` / `b` / `n` / `r`.\n\nEach value is a single printable character — a lowercase letter, a digit, or a symbol. Digits are the usual choice for input-method-editor (IME) users, whose composition mode swallows letter keys before they reach the terminal.\n\n`j` and `k` are reserved for moving the dialog's highlight, uppercase is rejected (pi lowercases a key identifier, so `\"Y\"` would answer to `y`), and two decisions may not share a character. An entry that breaks one of those rules is ignored with a warning and its decision keeps its default letter.\n\nA project config replaces a global one's map entirely rather than merging entry by entry.",
+      "examples": [
+        {
+          "approve": "1",
+          "approveSession": "2",
+          "approveSessionBoth": "3",
+          "deny": "4",
+          "denyWithReason": "5"
+        }
+      ]
+    },
     "forwardingTimeoutMs": {
       "description": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",
       "markdownDescription": "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds.\n\nOmit to use the default (`600000`, ten minutes). A child whose in-process parent is not draining its inbox at all gives up in a couple of seconds regardless of this value, so lower it only to bound how long you are willing to leave an *unanswered* prompt pending.",

package/src/access-intent/input-normalizer.ts

@@ -102,15 +102,17 @@ function buildInputForSurface(
 
 /**
  * Surface-normalized representation of a tool invocation used by
- * `checkPermission()` to feed a single `evaluateFirst()` call.
+ * `checkPermission()` to feed a single `evaluateAnyValue()` call.
  */
 export interface NormalizedInput {
   /** The permission surface for `evaluate()` (e.g. "bash", "mcp", "skill"). */
   surface: string;
   /**
-   * Candidate lookup values in priority order (most-specific first).
-   * Most surfaces produce a single-element array; MCP produces a
-   * multi-candidate list derived from the invocation input.
+   * Alternative lookup names for this one access, most-specific first.
+   * MCP is the only surface producing more than one; every other surface
+   * produces a single-element array. Order does not decide which rule wins
+   * (rule position does) — it decides which name the decision is reported
+   * under when the winning rule matches several.
    */
   values: string[];
   /**

package/src/access-intent/mcp-targets.ts

@@ -51,6 +51,35 @@ export function parseQualifiedMcpToolName(
   return { server, tool };
 }
 
+/**
+ * Find the configured server that owns `toolName` by the prefix convention.
+ *
+ * Returns the **longest** configured name that is the tool's leading
+ * `<server>_` segment, so `foo_bar_baz` belongs to `foo_bar` and never also to
+ * `foo`. Selecting here rather than trusting the caller's ordering keeps the
+ * rule true for any caller: the production loader sorts longest-first, but the
+ * `mcpServerNames` option does not.
+ */
+function findLongestPrefixServer(
+  toolName: string,
+  configuredServerNames: readonly string[],
+): string | null {
+  let longest: string | null = null;
+
+  for (const serverName of configuredServerNames) {
+    const trimmedServerName = serverName.trim();
+    if (!trimmedServerName || !toolName.startsWith(`${trimmedServerName}_`)) {
+      continue;
+    }
+
+    if (longest === null || trimmedServerName.length > longest.length) {
+      longest = trimmedServerName;
+    }
+  }
+
+  return longest;
+}
+
 function addDerivedMcpServerTargets(
   toolName: string,
   configuredServerNames: readonly string[],
@@ -61,6 +90,23 @@ function addDerivedMcpServerTargets(
     return;
   }
 
+  // Prefix convention (`github_search_code`): the name already carries its
+  // server, so the bare server is the only candidate worth deriving. A prefix
+  // hit also settles the name's convention, which is why the suffix pass below
+  // does not run — a tool ending in another configured server's name is a
+  // coincidence, not a second owner.
+  const prefixServer = findLongestPrefixServer(
+    trimmedToolName,
+    configuredServerNames,
+  );
+  if (prefixServer) {
+    targets.add(trimmedToolName);
+    targets.add(prefixServer);
+    return;
+  }
+
+  // Suffix convention (`search_code_github`): the server is not part of any
+  // candidate the caller will add, so the qualified forms are derived too.
   for (const serverName of configuredServerNames) {
     const trimmedServerName = serverName.trim();
     if (!trimmedServerName) {
@@ -71,10 +117,6 @@ function addDerivedMcpServerTargets(
       continue;
     }
 
-    if (trimmedToolName.startsWith(`${trimmedServerName}_`)) {
-      continue;
-    }
-
     targets.add(`${trimmedServerName}_${trimmedToolName}`);
     targets.add(`${trimmedServerName}:${trimmedToolName}`);
     targets.add(trimmedServerName);
@@ -92,8 +134,17 @@ function pushMcpToolPermissionTargets(
   const resolvedTool = qualified?.tool ?? rawReference;
 
   if (resolvedServer) {
-    targets.add(`${resolvedServer}_${resolvedTool}`);
-    targets.add(`${resolvedServer}:${resolvedTool}`);
+    // A name already carrying its server needs no re-prefixing: the qualified
+    // forms would be `github_github_search_code`, which no rule can usefully
+    // name, and which led the list as the reported target. The tool name is
+    // itself the qualified form, so it leads instead — matching what prefix
+    // derivation produces when no explicit server accompanies the call.
+    if (resolvedTool.startsWith(`${resolvedServer}_`)) {
+      targets.add(resolvedTool);
+    } else {
+      targets.add(`${resolvedServer}_${resolvedTool}`);
+      targets.add(`${resolvedServer}:${resolvedTool}`);
+    }
     targets.add(resolvedServer);
   } else {
     addDerivedMcpServerTargets(resolvedTool, configuredServerNames, targets);
@@ -107,8 +158,11 @@ function pushMcpToolPermissionTargets(
  * Derive the ordered list of MCP permission-lookup candidates from a raw MCP
  * tool invocation input.
  *
- * Candidates are ordered from most-specific to least-specific so that
- * `evaluateFirst()` stops at the first non-default match.
+ * Candidates are ordered from most-specific to least-specific. The order does
+ * not decide which rule wins — `evaluateAnyValue()` gives that to the last
+ * matching rule — but it decides which candidate a winning rule is reported
+ * against, so the most specific name the rule matches is the one the prompt
+ * and the review log show.
  */
 export function createMcpPermissionTargets(
   input: unknown,

package/src/authority/permission-prompt-component.ts

@@ -3,7 +3,13 @@ import type {
   ExtensionUIContext,
   KeybindingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { type Component, Input, matchesKey } from "@earendil-works/pi-tui";
+import {
+  type Component,
+  Input,
+  type KeyId,
+  matchesKey,
+} from "@earendil-works/pi-tui";
+import type { DialogKeyBindings, PromptAction } from "#src/config/dialog-keys";
 import {
   completeViewBudget,
   type DialogView,
@@ -23,11 +29,10 @@ import {
 import {
   initialPromptState,
   type PromptEvent,
-  type PromptKey,
   type PromptModelConfig,
   type PromptViewState,
   reducePrompt,
-  visibleOptionKeys,
+  visibleActions,
 } from "./permission-prompt-decision";
 
 /**
@@ -60,6 +65,8 @@ export interface PromptPreferences {
   doublePressToConfirm: boolean;
   /** How much room a render has; the terminal width is added per frame. */
   budget: RenderBudget;
+  /** The character bound to each decision. */
+  dialogKeys: DialogKeyBindings;
 }
 
 /**
@@ -122,12 +129,12 @@ interface PromptTheme {
 
 const DEFAULT_SESSION_LABEL = "Yes, for this session";
 
-const OPTION_LABELS: Record<PromptKey, string> = {
-  y: "Yes",
-  s: DEFAULT_SESSION_LABEL,
-  b: "Yes, for this session in both directions",
-  n: "No",
-  r: "No, provide reason",
+const OPTION_LABELS: Record<PromptAction, string> = {
+  approve: "Yes",
+  approveSession: DEFAULT_SESSION_LABEL,
+  approveSessionBoth: "Yes, for this session in both directions",
+  deny: "No",
+  denyWithReason: "No, provide reason",
 };
 
 export function presentInlinePermissionPrompt(
@@ -141,6 +148,7 @@ export function presentInlinePermissionPrompt(
     sessionLabel: options?.sessionLabel ?? DEFAULT_SESSION_LABEL,
     widthLabel: options?.sessionWidth?.label,
     sessionScope: options?.sessionScope,
+    keys: view.dialogKeys,
   };
   return view.ui.custom<UnattributedDecision>(
     (tui, theme, keybindings, done) =>
@@ -328,11 +336,11 @@ class PermissionPromptComponent implements Component {
       return { type: "cancel" };
     }
     if (this.state.step === "decision") {
-      const key = visibleOptionKeys(this.config).find((option) =>
-        matchesKey(data, option),
+      const action = visibleActions(this.config).find((option) =>
+        matchesKey(data, this.boundKey(option)),
       );
-      if (key) {
-        return { type: "hotkey", key };
+      if (action) {
+        return { type: "hotkey", action };
       }
     }
     return undefined;
@@ -354,11 +362,11 @@ class PermissionPromptComponent implements Component {
   private renderDecision(width: number): string[] {
     const ask = this.renderAsk(width);
     const lines = [this.theme.fg("accent", this.title), ...ask.lines, ""];
-    for (const key of visibleOptionKeys(this.config)) {
-      const label = this.labelFor(key);
-      const selected = this.state.highlightedKey === key;
+    for (const action of visibleActions(this.config)) {
+      const label = this.labelFor(action);
+      const selected = this.state.highlightedAction === action;
       const marker = selected ? "▶" : " ";
-      const row = `${marker} (${key}) ${label}`;
+      const row = `${marker} (${this.boundKey(action)}) ${label}`;
       lines.push(selected ? this.theme.fg("accent", row) : row);
     }
     lines.push("");
@@ -366,14 +374,26 @@ class PermissionPromptComponent implements Component {
     return lines;
   }
 
+  /**
+   * The character that selects an option, as a key identifier.
+   *
+   * The cast is total by construction: a binding is one printable character,
+   * which is exactly what pi-tui's matcher accepts as a `KeyId`.
+   */
+  private boundKey(action: PromptAction): KeyId {
+    return this.config.keys[action] as KeyId;
+  }
+
   /**
    * The row label for a key: the two session options carry ask-supplied text
    * naming what they grant, and the rest are fixed.
    */
-  private labelFor(key: PromptKey): string {
-    if (key === "s") return this.config.sessionLabel;
-    if (key === "b") return this.config.widthLabel ?? OPTION_LABELS.b;
-    return OPTION_LABELS[key];
+  private labelFor(action: PromptAction): string {
+    if (action === "approveSession") return this.config.sessionLabel;
+    if (action === "approveSessionBoth") {
+      return this.config.widthLabel ?? OPTION_LABELS.approveSessionBoth;
+    }
+    return OPTION_LABELS[action];
   }
 
   private renderReason(width: number): string[] {

package/src/authority/permission-prompt-decision.ts

@@ -1,3 +1,4 @@
+import type { DialogKeyBindings, PromptAction } from "#src/config/dialog-keys";
 import type { SessionGrantWidth } from "#src/session/approval-grant";
 import {
   createDeniedPermissionDecision,
@@ -16,26 +17,30 @@ import {
  * forwards keystrokes to {@link reducePrompt} and renders the returned state.
  */
 
-/**
- * The decision hotkeys, in display order.
- *
- * `b` is conditional: it appears only for an ask whose session grant can be
- * widened to both directions (#813), so the roster an ask actually offers
- * comes from {@link visibleOptionKeys} rather than from this type.
- */
-export type PromptKey = "y" | "s" | "b" | "n" | "r";
-
 /** Which sub-view the dialog is showing. */
 export type PromptStep = "decision" | "reason" | "scope";
 
-const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "b", "n", "r"];
+/**
+ * The decisions in display order.
+ *
+ * `approveSessionBoth` is conditional: it appears only for an ask whose session
+ * grant can be widened to both directions (#813), so the roster an ask actually
+ * offers comes from {@link visibleActions} rather than from this list.
+ */
+const OPTION_ORDER: readonly PromptAction[] = [
+  "approve",
+  "approveSession",
+  "approveSessionBoth",
+  "deny",
+  "denyWithReason",
+];
 
-const NARROW_OPTION_ORDER: readonly PromptKey[] = OPTION_ORDER.filter(
-  (key) => key !== "b",
+const NARROW_OPTION_ORDER: readonly PromptAction[] = OPTION_ORDER.filter(
+  (action) => action !== "approveSessionBoth",
 );
 
 /**
- * The decision step's option keys, in display order.
+ * The decision step's options, in display order.
  *
  * A function of the config rather than an exported constant, so which options
  * an ask offers is decided in the model and the component renders whatever it
@@ -45,24 +50,31 @@ const NARROW_OPTION_ORDER: readonly PromptKey[] = OPTION_ORDER.filter(
  * The width option is offered iff the ask supplied a label for it, so an ask
  * that proves no single direction is rendered and navigated exactly as before.
  */
-export function visibleOptionKeys(
+export function visibleActions(
   config: PromptModelConfig,
-): readonly PromptKey[] {
+): readonly PromptAction[] {
   return config.widthLabel ? OPTION_ORDER : NARROW_OPTION_ORDER;
 }
 
-const OPTION_VERBS: Record<PromptKey, string> = {
-  y: "approve",
-  s: "approve for this session",
-  b: "approve both directions for this session",
-  n: "deny",
-  r: "deny with a reason",
+const OPTION_VERBS: Record<PromptAction, string> = {
+  approve: "approve",
+  approveSession: "approve for this session",
+  approveSessionBoth: "approve both directions for this session",
+  deny: "deny",
+  denyWithReason: "deny with a reason",
 };
 
 /** Static configuration for a single prompt presentation. */
 export interface PromptModelConfig {
-  /** When true, a letter hotkey arms first and commits only on a second press. */
+  /** When true, a hotkey arms first and commits only on a second press. */
   doublePressToConfirm: boolean;
+  /**
+   * The character bound to each decision.
+   *
+   * What the dialog matches keystrokes against and what it renders, so an
+   * option's identity and the key that selects it are separate values.
+   */
+  keys: DialogKeyBindings;
   /** Label shown beside the approve-for-session option. */
   sessionLabel: string;
   /**
@@ -83,9 +95,9 @@ export interface PromptModelConfig {
 /** The re-render view state the component draws from. */
 export interface PromptViewState {
   step: PromptStep;
-  highlightedKey: PromptKey;
+  highlightedAction: PromptAction;
   /** Set only while awaiting the confirming second press of a hotkey. */
-  armedKey?: PromptKey;
+  armedAction?: PromptAction;
   /** "Press y again to approve." while armed; empty otherwise. */
   hint: string;
   /** Set when an empty reason submit is rejected. */
@@ -106,7 +118,7 @@ export interface PromptViewState {
 /** An input event the reducer understands. */
 export type PromptEvent =
   | { type: "nav"; direction: "up" | "down" }
-  | { type: "hotkey"; key: PromptKey }
+  | { type: "hotkey"; action: PromptAction }
   | { type: "confirm" }
   | { type: "cancel" }
   | { type: "submitReason"; draft: string };
@@ -121,8 +133,8 @@ export function initialPromptState(
 ): PromptViewState {
   return {
     step: "decision",
-    highlightedKey: "y",
-    armedKey: undefined,
+    highlightedAction: "approve",
+    armedAction: undefined,
     hint: "",
     reasonError: undefined,
     scopeServing: false,
@@ -162,16 +174,20 @@ function reduceDecisionStep(
     case "nav":
       return render({
         ...state,
-        highlightedKey: shiftKey(config, state.highlightedKey, event.direction),
-        armedKey: undefined,
+        highlightedAction: shiftAction(
+          config,
+          state.highlightedAction,
+          event.direction,
+        ),
+        armedAction: undefined,
         hint: "",
       });
     case "hotkey":
-      return visibleOptionKeys(config).includes(event.key)
-        ? pressHotkey(config, state, event.key)
+      return visibleActions(config).includes(event.action)
+        ? pressHotkey(config, state, event.action)
         : render(state);
     case "confirm":
-      return commit(config, state, state.highlightedKey);
+      return commit(config, state, state.highlightedAction);
     case "cancel":
       return { kind: "decision", decision: createDeniedPermissionDecision() };
     case "submitReason":
@@ -182,52 +198,53 @@ function reduceDecisionStep(
 function pressHotkey(
   config: PromptModelConfig,
   state: PromptViewState,
-  key: PromptKey,
+  action: PromptAction,
 ): PromptOutcome {
-  if (!config.doublePressToConfirm || state.armedKey === key) {
-    return commit(config, state, key);
+  if (!config.doublePressToConfirm || state.armedAction === action) {
+    return commit(config, state, action);
   }
   return render({
     ...state,
-    highlightedKey: key,
-    armedKey: key,
-    hint: `Press ${key} again to ${OPTION_VERBS[key]}.`,
+    highlightedAction: action,
+    armedAction: action,
+    hint: `Press ${config.keys[action]} again to ${OPTION_VERBS[action]}.`,
   });
 }
 
 function commit(
   config: PromptModelConfig,
   state: PromptViewState,
-  key: PromptKey,
+  action: PromptAction,
 ): PromptOutcome {
-  switch (key) {
-    case "y":
+  switch (action) {
+    case "approve":
       return {
         kind: "decision",
         decision: { approved: true, state: "approved" },
       };
-    case "n":
+    case "deny":
       return { kind: "decision", decision: createDeniedPermissionDecision() };
-    case "r":
+    case "denyWithReason":
       return render({
         ...state,
         step: "reason",
-        highlightedKey: "r",
-        armedKey: undefined,
+        highlightedAction: "denyWithReason",
+        armedAction: undefined,
         hint: "",
         reasonError: undefined,
       });
-    case "s":
-    case "b": {
+    case "approveSession":
+    case "approveSessionBoth": {
       // The two session options differ only in the width they grant; which
       // scope they land on is the forwarded scope step's separate question.
-      const grantWidth: SessionGrantWidth = key === "b" ? "family" : "proven";
+      const grantWidth: SessionGrantWidth =
+        action === "approveSessionBoth" ? "family" : "proven";
       if (config.sessionScope) {
         return render({
           ...state,
           step: "scope",
-          highlightedKey: key,
-          armedKey: undefined,
+          highlightedAction: action,
+          armedAction: undefined,
           hint: "",
           scopeServing: false,
           grantWidth,
@@ -268,7 +285,7 @@ function reduceReasonStep(
     return render({
       ...state,
       step: "decision",
-      armedKey: undefined,
+      armedAction: undefined,
       hint: "",
       reasonError: undefined,
       grantWidth: "proven",
@@ -311,7 +328,7 @@ function reduceScopeStep(
       return render({
         ...state,
         step: "decision",
-        armedKey: undefined,
+        armedAction: undefined,
         hint: "",
         grantWidth: "proven",
       });
@@ -320,16 +337,16 @@ function reduceScopeStep(
   }
 }
 
-function shiftKey(
+function shiftAction(
   config: PromptModelConfig,
-  current: PromptKey,
+  current: PromptAction,
   direction: "up" | "down",
-): PromptKey {
-  const keys = visibleOptionKeys(config);
-  const index = keys.indexOf(current);
+): PromptAction {
+  const actions = visibleActions(config);
+  const index = actions.indexOf(current);
   const delta = direction === "down" ? 1 : -1;
-  const next = (index + delta + keys.length) % keys.length;
-  return keys[next] ?? current;
+  const next = (index + delta + actions.length) % actions.length;
+  return actions[next] ?? current;
 }
 
 function render(state: PromptViewState): PromptOutcome {

package/src/config/config-loader.ts

@@ -16,6 +16,7 @@ import {
   type UnifiedPermissionConfig,
   unifiedConfigSchema,
 } from "./config-schema";
+import { type DialogKeysConfig, resolveDialogKeys } from "./dialog-keys";
 
 // The unified config shape is derived from the zod schema (config-schema.ts,
 // the single source of truth) and re-exported so existing importers keep their
@@ -196,6 +197,7 @@ function formatConfigIssues(error: ZodError): string[] {
  *   present in the override.
  * - Array fields (piInfrastructureReadPaths) replace the base when present in
  *   the override (override-wins, same as scalars).
+ * - `permissionDialogKeys` replaces the base map whole, unlike `shellTools`.
  */
 // Scalar knobs merged by override-replaces-base; keep in sync with
 // PermissionSystemExtensionConfig booleans (debugLog, permissionReviewLog,
@@ -242,6 +244,16 @@ export function mergeUnifiedConfigs(
     }
   }
 
+  // permissionDialogKeys: whole-object replacement. A key map is validated as
+  // a unit, so merging two individually valid maps could bind one character to
+  // two decisions with neither file's own validation able to see it. Dropping a
+  // base entry only restores a default letter, which is why this does not need
+  // the shellTools rule below.
+  const dialogKeys = override.permissionDialogKeys ?? base.permissionDialogKeys;
+  if (dialogKeys !== undefined) {
+    merged.permissionDialogKeys = dialogKeys;
+  }
+
   // 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).
@@ -378,6 +390,9 @@ export function loadAndMergeConfigs(
   const deprecatedCapsIssue = detectDeprecatedPreviewCaps(merged);
   if (deprecatedCapsIssue) allIssues.push(deprecatedCapsIssue);
 
+  const dialogKeysIssue = detectUnusableDialogKeys(merged);
+  if (dialogKeysIssue) allIssues.push(dialogKeysIssue);
+
   return {
     global: globalConfig,
     project: projectConfig,
@@ -445,6 +460,30 @@ export function detectDeprecatedPreviewCaps(
   );
 }
 
+/**
+ * Detect a `permissionDialogKeys` entry the dialog cannot honor.
+ *
+ * Deliberately a warning rather than a fail-closed rejection: a mistyped hotkey
+ * is cosmetic, and clamping the session's `allow` rules to `ask` over one would
+ * make a display preference a policy event. The decision keeps its default
+ * letter, and the message names the entry, the reason, and the letter kept.
+ *
+ * Where that message surfaces is the caller's problem and is currently a narrow
+ * one: `ConfigStore` dedupes against a warning recorded by a factory-time
+ * refresh with no ctx to notify, so an issue already on disk reaches the debug
+ * log alone. That predates this detector and swallows its two siblings the same
+ * way (#933).
+ *
+ * Pure, following {@link detectPermissiveBashFallback}: it takes the merged
+ * config and returns a message; the caller owns pushing it onto the issue list.
+ */
+export function detectUnusableDialogKeys(
+  config: DialogKeysConfig,
+): string | undefined {
+  const { issues } = resolveDialogKeys(config);
+  return issues.length === 0 ? undefined : issues.join(" ");
+}
+
 /**
  * Load and normalize a unified config file.
  * Returns an empty config with no issues if the file does not exist.

package/src/config/config-schema.ts

@@ -245,6 +245,52 @@ function rejectUnusableSurfaceKeys(
   }
 }
 
+/**
+ * The inline dialog's hotkey bindings, one printable character per decision.
+ *
+ * The schema checks *shape* only — an unknown decision name or a non-string
+ * value is a load-time error like any other malformed field, because a
+ * misspelled key would otherwise sit inert with no feedback. Whether a
+ * well-formed string is a *usable* binding is `resolveDialogKeys`' question,
+ * and it answers tolerantly: an unusable, reserved, or colliding entry keeps
+ * its default letter and is reported, so a mistyped hotkey never reaches the
+ * permission policy.
+ */
+const dialogKeysSchema = z
+  .strictObject({
+    approve: z.string().optional().meta({
+      description: "Key that approves the pending call once. Default: y.",
+    }),
+    approveSession: z.string().optional().meta({
+      description: "Key that approves for the rest of the session. Default: s.",
+    }),
+    approveSessionBoth: z.string().optional().meta({
+      description:
+        "Key that approves for the session in both directions. Default: b.",
+    }),
+    deny: z.string().optional().meta({
+      description: "Key that denies the pending call. Default: n.",
+    }),
+    denyWithReason: z.string().optional().meta({
+      description: "Key that denies and opens the reason editor. Default: r.",
+    }),
+  })
+  .meta({
+    description:
+      "Remaps the inline TUI permission dialog's decision hotkeys. Each value is one printable character.",
+    markdownDescription:
+      "Remaps the inline **TUI** permission dialog's decision hotkeys, which default to `y` / `s` / `b` / `n` / `r`.\n\nEach value is a single printable character — a lowercase letter, a digit, or a symbol. Digits are the usual choice for input-method-editor (IME) users, whose composition mode swallows letter keys before they reach the terminal.\n\n`j` and `k` are reserved for moving the dialog's highlight, uppercase is rejected (pi lowercases a key identifier, so `\"Y\"` would answer to `y`), and two decisions may not share a character. An entry that breaks one of those rules is ignored with a warning and its decision keeps its default letter.\n\nA project config replaces a global one's map entirely rather than merging entry by entry.",
+    examples: [
+      {
+        approve: "1",
+        approveSession: "2",
+        approveSessionBoth: "3",
+        deny: "4",
+        denyWithReason: "5",
+      },
+    ],
+  });
+
 const shellToolAliasSchema = z
   .strictObject({
     commandArgument: z.string().min(1).meta({
@@ -322,6 +368,7 @@ export const unifiedConfigSchema = z
         "Require a confirming second press of a decision hotkey (`y`/`s`/`n`/`r`) in the inline permission dialog before it commits — the first press arms the action and shows a `Press y again to approve.` hint.\n\nApplies to interactive **TUI** sessions only; the non-TUI (RPC/frontend) prompt keeps its single-select flow. Set to `false` to commit decisions on the first hotkey press.",
       default: true,
     }),
+    permissionDialogKeys: dialogKeysSchema.optional(),
     forwardingTimeoutMs: z.number().int().min(1).optional().meta({
       description:
         "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds. Omit to use the default (600000, ten minutes).",

package/src/config/dialog-keys.ts

@@ -0,0 +1,172 @@
+/**
+ * The inline permission dialog's key bindings, and the defaults they start from.
+ *
+ * The action ids are the `permissionDialogKeys` config keys, so the config
+ * surface and the decision model speak one vocabulary rather than two that a
+ * translation layer has to keep in step.
+ */
+
+/**
+ * The dialog's five decisions, named by what they do.
+ *
+ * Distinct from the character that selects one: a binding is configurable and
+ * an identity is not, so a rebound dialog still decides the same five things.
+ */
+export type PromptAction =
+  | "approve"
+  | "approveSession"
+  | "approveSessionBoth"
+  | "deny"
+  | "denyWithReason";
+
+/** Every action's bound character, complete. */
+export type DialogKeyBindings = Readonly<Record<PromptAction, string>>;
+
+/** What a config file may say: any subset of the actions. */
+export type DialogKeyOverrides = Partial<Record<PromptAction, string>>;
+
+/** The config slice the resolver reads. */
+export interface DialogKeysConfig {
+  readonly permissionDialogKeys?: DialogKeyOverrides;
+}
+
+/** The bindings to use, and what had to be refused to arrive at them. */
+export interface DialogKeyResolution {
+  readonly keys: DialogKeyBindings;
+  /** One sentence per refused override; empty when every one applied. */
+  readonly issues: readonly string[];
+}
+
+/** The decisions in the order a config's overrides are considered. */
+const ACTION_ORDER: readonly PromptAction[] = [
+  "approve",
+  "approveSession",
+  "approveSessionBoth",
+  "deny",
+  "denyWithReason",
+];
+
+/** The shipped bindings, unchanged since the dialog was introduced. */
+export const DEFAULT_DIALOG_KEYS: DialogKeyBindings = {
+  approve: "y",
+  approveSession: "s",
+  approveSessionBoth: "b",
+  deny: "n",
+  denyWithReason: "r",
+};
+
+const LOWERCASE_LETTERS = "abcdefghijklmnopqrstuvwxyz";
+const DIGITS = "0123456789";
+
+/**
+ * pi-tui's symbol keys, minus `+`.
+ *
+ * `+` separates a modifier from its key in a key identifier, so pi-tui's
+ * parser splits `"+"` into two empty halves and the binding matches nothing.
+ * A parity test in `test/config/dialog-keys.test.ts` derives this roster from
+ * pi-tui's exported `Key` constant and fails if the two drift; keeping the
+ * literal here is what lets this module stay free of SDK imports.
+ */
+const SYMBOLS = "`-=[]\\;',./!@#$%^&*()_|~{}:<>?";
+
+/**
+ * Every character a decision may be bound to.
+ *
+ * Uppercase is excluded deliberately rather than normalized: pi-tui lowercases
+ * a key identifier, so a `"Y"` binding would answer to a lowercase `y` and
+ * never to the keystroke the user asked for.
+ */
+export const BINDABLE_DIALOG_KEY_CHARACTERS: ReadonlySet<string> = new Set(
+  Array.from(LOWERCASE_LETTERS + DIGITS + SYMBOLS),
+);
+
+/** Whether `value` is a single character the dialog can bind a decision to. */
+export function isBindableDialogKey(value: string): boolean {
+  return BINDABLE_DIALOG_KEY_CHARACTERS.has(value);
+}
+
+/**
+ * The characters the dialog answers to before any decision does.
+ *
+ * `handleInput` maps these to navigation ahead of the decision table, so a
+ * decision bound to one would simply never fire.
+ */
+export const RESERVED_DIALOG_KEYS: readonly string[] = ["j", "k"];
+
+/**
+ * The bindings a config asks for, reconciled against the defaults.
+ *
+ * Tolerant by design: an unusable, reserved, or colliding override is refused
+ * and its decision keeps the shipped letter, so a mistyped hotkey costs the
+ * user their remap and nothing else. The refusals come back as sentences for
+ * the caller to surface; the permission policy never sees them.
+ */
+export function resolveDialogKeys(
+  config: DialogKeysConfig,
+): DialogKeyResolution {
+  const overrides = config.permissionDialogKeys;
+  const issues: string[] = [];
+  const accepted = new Map<PromptAction, string>();
+
+  for (const action of ACTION_ORDER) {
+    const value = overrides?.[action];
+    if (value === undefined) continue;
+    if (!isBindableDialogKey(value)) {
+      issues.push(
+        refusal(
+          action,
+          value,
+          "is not a bindable key. Use one lowercase letter, digit, or symbol",
+        ),
+      );
+      continue;
+    }
+    if (RESERVED_DIALOG_KEYS.includes(value)) {
+      issues.push(
+        refusal(action, value, "is reserved for moving the dialog's highlight"),
+      );
+      continue;
+    }
+    accepted.set(action, value);
+  }
+
+  // Dropping an override restores its default, and that default can collide
+  // with an override that survived the previous look — so this settles rather
+  // than checks once. Each round drops at least one override and there are at
+  // most five, and the all-defaults state it terminates at is collision-free.
+  for (let round = ACTION_ORDER.length; round > 0; round--) {
+    const contested = contestedCharacters(accepted);
+    if (contested.size === 0) break;
+    for (const [action, value] of accepted) {
+      if (!contested.has(value)) continue;
+      accepted.delete(action);
+      issues.push(
+        refusal(action, value, "is already bound to another decision"),
+      );
+    }
+  }
+
+  const keys: Record<PromptAction, string> = { ...DEFAULT_DIALOG_KEYS };
+  for (const [action, value] of accepted) {
+    keys[action] = value;
+  }
+  return { keys, issues };
+}
+
+/** The characters two decisions would answer to, given the accepted overrides. */
+function contestedCharacters(
+  accepted: ReadonlyMap<PromptAction, string>,
+): ReadonlySet<string> {
+  const seen = new Set<string>();
+  const contested = new Set<string>();
+  for (const action of ACTION_ORDER) {
+    const value = accepted.get(action) ?? DEFAULT_DIALOG_KEYS[action];
+    if (seen.has(value)) contested.add(value);
+    seen.add(value);
+  }
+  return contested;
+}
+
+function refusal(action: PromptAction, value: string, why: string): string {
+  return `permissionDialogKeys.${action}: "${value}" ${why}; keeping the default "${DEFAULT_DIALOG_KEYS[action]}".`;
+}

package/src/config/extension-config.ts

@@ -9,6 +9,7 @@ import type {
   ShellToolsConfig,
   UnifiedPermissionConfig,
 } from "./config-loader";
+import type { DialogKeyOverrides } from "./dialog-keys";
 
 export const EXTENSION_ID = "pi-permission-system";
 
@@ -28,6 +29,8 @@ export interface PermissionSystemExtensionConfig {
   promptFieldMaxWidth?: number;
   /** Max characters of any one value written to the permission review log. Defaults to 1000. */
   reviewLogFieldMaxWidth?: number;
+  /** The inline dialog's hotkey bindings, as configured; resolved at prompt time. */
+  permissionDialogKeys?: DialogKeyOverrides;
   /** Non-bash tools that carry shell semantics, keyed by tool name. */
   shellTools?: ShellToolsConfig;
   /** Ordered names of registered live-authority chain links to consult before the terminal authorizer. */
@@ -91,6 +94,9 @@ export function normalizePermissionSystemConfig(
   // absent: the schema and the merge still accept them so the deprecation
   // detector can see an operator's setting, but no runtime consumer may read
   // one (ADR 0011 §5, #745).
+  if (raw.permissionDialogKeys !== undefined) {
+    result.permissionDialogKeys = raw.permissionDialogKeys;
+  }
   if (raw.shellTools !== undefined) {
     result.shellTools = raw.shellTools;
   }

package/src/index.ts

@@ -36,6 +36,7 @@ import { getSubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { registerPermissionSystemCommand } from "#src/config/config-modal";
 import { getGlobalConfigPath } from "#src/config/config-paths";
 import { ConfigStore } from "#src/config/config-store";
+import { resolveDialogKeys } from "#src/config/dialog-keys";
 import { isYoloModeEnabled } from "#src/config/extension-config";
 import { computeExtensionPaths } from "#src/config/extension-paths";
 import { GateRunner } from "#src/handlers/gates/runner";
@@ -150,6 +151,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     getPromptPreferences: () => ({
       doublePressToConfirm: configStore.current().doublePressToConfirm,
       budget: resolveRenderBudget(configStore.current()),
+      dialogKeys: resolveDialogKeys(configStore.current()).keys,
     }),
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,

package/src/policy/permission-manager.ts

@@ -1,10 +1,7 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "#src/access-intent/access-intent";
 import { normalizeInput } from "#src/access-intent/input-normalizer";
-import {
-  PATH_SURFACES,
-  surfaceFamilyOf,
-} from "#src/access-intent/path-surfaces";
+import { surfaceFamilyOf } from "#src/access-intent/path-surfaces";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import {
   getGlobalConfigPath,
@@ -29,7 +26,6 @@ import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import {
   evaluate,
   evaluateAnyValue,
-  evaluateFirst,
   floorAllowsToAsk,
   isSurfaceFullyDenied,
   rewriteAsksToYolo,
@@ -356,9 +352,10 @@ export class PermissionManager implements ScopedPermissionManager {
 /**
  * Evaluate a normalized surface/values triple and shape the result.
  *
- * Path surfaces use {@link evaluateAnyValue} (last-match-wins across equivalent
- * aliases); every other surface keeps {@link evaluateFirst}. Shared by the
- * `"tool"` and `"path-values"` branches of {@link PermissionManager.check}.
+ * Every surface resolves through {@link evaluateAnyValue}, so a rule's position
+ * in the config decides and the candidate list only determines which name the
+ * decision is reported under. Shared by the `"tool"` and `"path-values"`
+ * branches of {@link PermissionManager.check}.
  */
 function buildCheckResult(
   surface: string,
@@ -369,9 +366,7 @@ function buildCheckResult(
   fullRules: Ruleset,
   flavor: PathFlavor,
 ): PermissionCheckResult {
-  const { rule, value } = PATH_SURFACES.has(surface)
-    ? evaluateAnyValue(surface, values, fullRules, flavor)
-    : evaluateFirst(surface, values, fullRules, flavor);
+  const { rule, value } = evaluateAnyValue(surface, values, fullRules, flavor);
 
   // For MCP, replace the normalizer's fallback target with the actual
   // matched candidate value so PermissionCheckResult.target is accurate.

package/src/policy/rule.ts

@@ -216,45 +216,15 @@ export function evaluateMostRestrictive(
 }
 
 /**
- * Evaluate a surface against an ordered list of candidate values, stopping at
- * the first candidate that matches a non-default rule (last-match-wins within
- * each candidate, first-non-default-wins across candidates).
- *
- * Used by MCP (multi-candidate target list) and, uniformly, by all other
- * surfaces (single-element candidate list).
- *
- * Returns the matched rule and the candidate value that produced it.
- * When every candidate matches only the synthesized default, falls back to
- * evaluating the first candidate so the caller always receives a concrete
- * result.
- */
-export function evaluateFirst(
-  surface: string,
-  values: string[],
-  rules: Ruleset,
-  flavor: PathFlavor,
-): { rule: Rule; value: string } {
-  for (const value of values) {
-    const rule = evaluate(surface, value, rules, flavor);
-    if (rule.layer !== "default") {
-      return { rule, value };
-    }
-  }
-  // All candidates matched only the synthesized default — use the first.
-  const fallbackValue = values[0] ?? "*";
-  return {
-    rule: evaluate(surface, fallbackValue, rules, flavor),
-    value: fallbackValue,
-  };
-}
-
-/**
- * Evaluate equivalent lookup values as aliases of the same path.
- *
- * Unlike `evaluateFirst()`, this preserves rule ordering across aliases: the
- * last rule that matches any alias wins. This lets absolute allowlists and
- * legacy relative rules coexist without a catch-all match on the first alias
- * masking a later, more specific rule on another alias.
+ * Evaluate a set of lookup values as alternative names for one access.
+ *
+ * Preserves rule ordering across the whole set: the last rule matching **any**
+ * value wins, and the reported value is the first one that rule matches. This
+ * is last-match-wins (see `evaluate()`) lifted from a single value to a
+ * candidate list, so a catch-all matched by one value cannot mask a later, more
+ * specific rule matched by another — whether the values are spellings of one
+ * path (`/proj/src/a.ts` and `src/a.ts`) or names for one MCP call
+ * (`github_search_code`, `github`, `mcp_call`).
  */
 export function evaluateAnyValue(
   surface: string,