@gotgenes/pi-permission-system 32.1.0 → 33.0.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v33.0.0...pi-permission-system-v33.0.1) (2026-09-19)
+
+
+### Documentation
+
+* **pi-permission-system:** document the serving-liveness and bound-channel mechanism in the integration spec ([#942](https://github.com/gotgenes/pi-packages/issues/942)) ([2786acc](https://github.com/gotgenes/pi-packages/commit/2786accaf40136f192e6f8d187058ae60c7555b5)), closes [#942](https://github.com/gotgenes/pi-packages/issues/942)
+
+## [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)
 
 

package/docs/configuration.md

@@ -523,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/docs/subagent-integration.md

@@ -160,7 +160,9 @@ The polling session publishes the session id it polls, and a child checks that i
 
 The announcement goes out on two channels, because a child cannot always reach the same one.
 A child running inside its parent's process reads a process-global registry.
+A stale mark left in that registry by a session that died without `session_shutdown` suppresses the fast-fail and falls back to the timeout — the safe direction for that channel.
 A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) shares no memory with its parent, so it reads a heartbeat record the serving session refreshes under `<agent dir>/sessions/permission-forwarding/serving/`, holding the served session id, the serving process id, and the time it was last refreshed.
+That `serving/` directory is created on demand and never removed.
 
 For an out-of-process target, four things count as "not draining":
 
@@ -171,7 +173,7 @@ For an out-of-process target, four things count as "not draining":
 | A record nobody has refreshed for several seconds | The parent's process survives but has stopped polling                        |
 | A record for a different session id               | The child is forwarding somewhere nobody is listening                        |
 
-If the target is not draining its inbox, the child gives up after a two-second grace window rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
+If the target is not draining its inbox, the child gives up after a two-second grace window (`PERMISSION_FORWARDING_SERVING_GRACE_MS`) rather than waiting out `forwardingTimeoutMs`, and the tool is blocked with:
 
 ```text
 [pi-permission-system] Running bash command 'pwd' requires approval, but no
@@ -180,6 +182,7 @@ permission requests.
 ```
 
 The grace window exists so a request that arrives while the parent is switching sessions is not abandoned in the gap.
+Absence of a record is deliberately **not** read as unknown: a cleanly exited parent leaves nothing behind, so treating absence as "maybe serving" would restore the full-timeout stall that the heartbeat exists to end.
 A target that *is* draining its inbox is waited on for the full `forwardingTimeoutMs`, however long the human takes to decide.
 That includes a parent whose human is still deliberating at an earlier forwarded prompt: it keeps refreshing its heartbeat throughout, so a second child does not read it as gone.
 
@@ -188,6 +191,7 @@ None of them is reported as a user denial, because no user was ever asked.
 
 The two sides of the exchange are correlatable in the review log: the serving session writes `forwarded_permission.serving_started` with the id it polls, and the child writes `forwarded_permission.request_created` with the `targetSessionId` it forwarded to.
 When a forwarded request goes unanswered, comparing those two entries distinguishes a parent that was not polling from one polling a different session.
+The child's `forwarded_permission.no_serving_session` entry also records `servingChannel` and `servingState` beside the ids observed, since "exited", "killed", and "polling a different session id" are different diagnoses the shared denial string does not distinguish.
 
 When a forwarded request *is* answered, the child's own terminal entry names both which session answered and what within it decided.
 The serving node records its decider on the response — a rule of its own (with the surface, pattern, and origin that matched), the link that ruled, or the human who answered its dialog — and the child records it nested under a `forwarded` frame:

package/package.json

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

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/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,