@gotgenes/pi-permission-system 37.0.0 → 38.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).
 
+## [38.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v38.0.0...pi-permission-system-v38.0.1) (2026-10-02)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** tolerate a non-Pi before_agent_start payload ([#860](https://github.com/gotgenes/pi-packages/issues/860)) ([33f6a24](https://github.com/gotgenes/pi-packages/commit/33f6a24c820f23d43a56c9377245e804c2fd8ba2)), closes [#860](https://github.com/gotgenes/pi-packages/issues/860)
+
+## [38.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v37.0.0...pi-permission-system-v38.0.0) (2026-10-02)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** read MCP server names from the trusted project's .pi/mcp.json too ([780bc33](https://github.com/gotgenes/pi-packages/commit/780bc330274a86463e53edba3833f33db5427035)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+* **pi-permission-system:** **breaking:** gate Pi's built-in MCP tools on the mcp surface ([97eebdb](https://github.com/gotgenes/pi-packages/commit/97eebdb212f9fa0ceab3ac71c1fd095e4f94b9dc)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+* **pi-permission-system:** keep top-level mcp__ tool keys working and ask the operator to port them ([b0b9102](https://github.com/gotgenes/pi-packages/commit/b0b9102e4fd048e64203a39ae837d9da8d0a16b9)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+* **pi-permission-system:** withhold a Pi MCP tool exactly when its mcp rules deny it ([68d734a](https://github.com/gotgenes/pi-packages/commit/68d734afd72e295cd2b9ee7a75cd1d39b9ae8557)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+* **pi-permission-system:** resolve a forwarded or queried mcp target as itself, not as a status probe ([caa96f9](https://github.com/gotgenes/pi-packages/commit/caa96f90b699aa10b76ba6c208a64a295b43c829)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+
+### Documentation
+
+* **pi-permission-system:** document Pi MCP tools on the mcp surface and the top-level key port ([6bde6a1](https://github.com/gotgenes/pi-packages/commit/6bde6a187320eafc3489e7ea882bcd23e02f1de0)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+* **pi-permission-system:** note which top-level keys carry over to Pi MCP tools ([07e3287](https://github.com/gotgenes/pi-packages/commit/07e328779f332fa6c8f8a0296ae24086ae3167c1)), closes [#1001](https://github.com/gotgenes/pi-packages/issues/1001)
+
 ## [37.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.1...pi-permission-system-v37.0.0) (2026-10-02)
 
 

package/README.md

@@ -16,7 +16,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Hides disallowed tools** before the agent starts — no wasted turns probing for blocked tools
 - **Enforces allow / ask / deny** at tool-call time with UI confirmation dialogs
 - **Controls bash commands** with wildcard pattern matching (`git *: ask`, `rm -rf *: deny`)
-- **Gates MCP and skill access** at server, tool, and skill-name granularity
+- **Gates MCP and skill access** at server, tool, and skill-name granularity — Pi's built-in MCP tools and the `mcp` proxy alike
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and a bash command the parser could not resolve, in whole or in part — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently, unless the wrapped command is a pure reader whose direction is provable whatever it is fed (`xargs grep -l foo`); where a partial parse failure's own region re-parses cleanly on its own, the commands and paths it holds are recovered and gated rather than merely prompted for

package/docs/configuration.md

@@ -366,13 +366,13 @@ Omitting `"*"` defaults to `"ask"` (least privilege).
 Any registered tool name can be a surface key.
 A string value is a catch-all for that surface.
 
-| Surface example                               | Description                         |
-| --------------------------------------------- | ----------------------------------- |
-| `read`, `write`, `edit`, `grep`, `find`, `ls` | Canonical Pi built-in file tools    |
-| `bash`                                        | Shell command execution             |
-| `mcp`                                         | Registered MCP proxy tool           |
-| `task`                                        | Delegation tool                     |
-| `third_party_tool`                            | Any other registered extension tool |
+| Surface example                               | Description                                                 |
+| --------------------------------------------- | ----------------------------------------------------------- |
+| `read`, `write`, `edit`, `grep`, `find`, `ls` | Canonical Pi built-in file tools                            |
+| `bash`                                        | Shell command execution                                     |
+| `mcp`                                         | MCP calls: Pi's built-in MCP tools and the `mcp` proxy tool |
+| `task`                                        | Delegation tool                                             |
+| `third_party_tool`                            | Any other registered extension tool                         |
 
 ```jsonc
 {
@@ -543,7 +543,11 @@ To deliberately opt into permissive bash, set `"bash": { "*": "allow" }` explici
 
 ### `mcp` Surface
 
-MCP permissions match against derived targets from tool input:
+MCP permissions match against targets derived from each MCP call.
+Two kinds of tool make MCP calls, and both resolve on this one surface:
+
+- **Pi's built-in MCP** registers each server tool as its own tool, `mcp__<server>__<tool>` (for example `mcp__github__search_code`); see [Pi's built-in MCP tools](#pis-built-in-mcp-tools).
+- **The `mcp` proxy tool** (for example pi-mcp-adapter's) takes the call as input, `{"tool": …, "server": …}`.
 
 | Target type       | Examples                                                              |
 | ----------------- | --------------------------------------------------------------------- |
@@ -573,7 +577,7 @@ In that example `mcp_status` and `mcp_list` allow discovery, `myServer:*` prompt
 #### 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:
+When a proxied call carries no explicit `server`, the server is derived from the tool name against the servers in your MCP config (`~/.pi/agent/mcp.json`, plus `<project>/.pi/mcp.json` in a trusted project), 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>`.
@@ -594,6 +598,29 @@ Deriving a server from a name is a heuristic, and it can attach the wrong rule:
 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.
 
+#### Pi's built-in MCP tools
+
+Pi names each tool `mcp__<server>__<tool>`, replacing every character outside `[A-Za-z0-9_]` with `_`, so a server named `danger-srv` in `mcp.json` appears as `danger_srv` in the tool name.
+A call to such a tool is looked up under the same targets a proxied call gets, plus the tool's full Pi name, and the server is named in **both** spellings: the one in your `mcp.json` and the one in the tool name.
+Pi refuses two servers whose names differ only in `-` and `_`, so the two spellings always name the same server.
+
+| Call (`danger-srv` in `mcp.json`) | Targets                                                                                                                                             |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mcp__danger_srv__wipe`           | `danger-srv_wipe`, `danger-srv:wipe`, `danger-srv`, `danger_srv_wipe`, `danger_srv:wipe`, `danger_srv`, `wipe`, `mcp__danger_srv__wipe`, `mcp_call` |
+| `mcp__github__search` (`github`)  | `github_search`, `github:search`, `github`, `search`, `mcp__github__search`, `mcp_call`                                                             |
+
+So `"danger-srv": "deny"`, `"danger_srv": "deny"`, `"danger-srv:*": "deny"`, and `"mcp__danger_srv__*": "deny"` each deny every tool of that server.
+The server is the longest configured name whose Pi spelling starts the tool name; a server no `mcp.json` names, such as one an extension registers in code, is split at the first `__` and gets only Pi's spelling.
+A tool name over 64 characters, or two of a server's tools that sanitize to the same name, gets an 8-character hash suffix from Pi; the suffix is part of the tool target, so a server-level rule is the reliable way to name such a tool.
+
+The tool's arguments are its own input, unlike the proxy's: the ask prompt and the review log show them, and the [`path` and `external_directory`](#path-surface) gates read a top-level `path` argument.
+Approving such a tool "for this session" records its full Pi name on the `mcp` surface, so the approval covers exactly that tool.
+A Pi MCP tool is withheld from the model when its targets resolve to `deny`.
+
+> **Migrating:** a top-level key naming a Pi MCP tool (`"mcp__danger_srv__wipe": "deny"`) still applies, as an `mcp` rule, and raises a notice at session start asking you to move it under `mcp`.
+> A top-level wildcard of another shape (`"*__wipe"`) no longer reaches these tools.
+> See [the migration guide](migration/1001-pi-mcp-tools-on-mcp-surface.md).
+
 #### Which rule shape to write
 
 | Rule shape     | Matches                | Use it for                                                                                                                            |
@@ -1339,9 +1366,9 @@ Additional behaviors:
   A skill listed in text pi did not render, such as your own `SYSTEM.md`, is not edited out; using it is still gated.
 - The prompt options are recomputed on every turn but are stable across turns for a stable policy/agent, so the provider's prompt cache is preserved rather than rewritten each turn.
   A policy change is an intentional cache transition, as a mid-session agent switch already is.
-- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
+- Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name; Pi's built-in MCP tools (`mcp__<server>__<tool>`) resolve on the `mcp` surface instead (see [Pi's built-in MCP tools](#pis-built-in-mcp-tools))
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries
-- Permission review logs include `toolInputPreview` values for non-bash/non-MCP tool calls, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))
+- Permission review logs include `toolInputPreview` values for tool calls other than bash and the `mcp` proxy, with sensitive-keyed values masked and every value bounded by `reviewLogFieldMaxWidth` (see [Log file sensitivity](#log-file-sensitivity))
 - A tool whose path came from an extractor registered in an **ancestor** session rather than this one records `extractorSource: "inherited"` beside the decision; the field is absent for every path this session resolved itself.
   This happens in a subagent child when the extractor's provider was kept out of the child but the tool's own package was not — the child borrows the declaration so its `path` and `external_directory` gates still see the path (see [Subagent Integration](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/subagent-integration.md#loading-asymmetry))
 

package/docs/migration/1001-pi-mcp-tools-on-mcp-surface.md

@@ -0,0 +1,91 @@
+# Migration guide: Pi's built-in MCP tools are gated on the `mcp` surface
+
+Starting with the release that closes [#1001], `mcp` permission rules apply to the tools Pi's built-in MCP registers, `mcp__<server>__<tool>`.
+Before it, those tools were gated like any other extension tool, under their own name, and no `mcp` rule reached them.
+
+This is a **breaking change**: a config that already has `mcp` rules changes how Pi's MCP tools resolve on upgrade, with no edit.
+A config with no `mcp` rules and no top-level `mcp__…` keys is unaffected — both paths fall back to `"*"`.
+
+## What changes
+
+Each row is a policy for a server configured as `danger-srv` in `mcp.json`, whose `wipe` tool Pi registers as `mcp__danger_srv__wipe`.
+
+| Policy                                                        | Before  | After                                            |
+| ------------------------------------------------------------- | ------- | ------------------------------------------------ |
+| `"*": "allow"`, `"mcp": {"*": "allow", "danger-srv": "deny"}` | allowed | **denied**, by `danger-srv`                      |
+| `"*": "ask"`, `"mcp": "allow"`                                | asked   | **allowed**, by `mcp`'s catch-all                |
+| `"*": "allow"`, `"mcp__danger_srv__wipe": "deny"`             | denied  | denied, plus a notice asking you to port the key |
+| `"*": "allow"`, `"mcp__danger_srv__*": "deny"`                | denied  | denied, plus a notice asking you to port the key |
+| `"*": "ask"`                                                  | asked   | asked                                            |
+
+The *After* column is each policy resolved through the released permission manager; the first and third *Before* entries are the reproduction in [#1001], and the others follow from the tool falling back to `"*"` when no top-level key names it.
+
+A denied tool is also withheld from the model, so the first row now hides `mcp__danger_srv__wipe` where it used to be offered.
+
+A server rule matches in either spelling — `danger-srv` as in `mcp.json`, or `danger_srv` as in the tool name — because Pi refuses two servers whose names differ only in `-` and `_`.
+The full list of names a call is looked up under is in [Pi's built-in MCP tools](../configuration.md#pis-built-in-mcp-tools).
+
+## Porting a top-level `mcp__…` key
+
+A top-level key naming a Pi MCP tool was the only rule that reached it, so it keeps working: it is also applied as an `mcp` rule with the key as its pattern, after every other `mcp` rule.
+The key keeps its original meaning too, so `"mcp__*"` still covers a tool from another extension whose name merely starts with `mcp__`; a key that can name no Pi MCP tool, such as `"mcp__foo"`, is left alone and raises no notice.
+At session start you see a notice naming each such key:
+
+```text
+Top-level permission keys naming Pi MCP tools are applied as "mcp" rules: "mcp__danger_srv__wipe". Move them under "mcp" — see https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/migration/1001-pi-mcp-tools-on-mcp-surface.md
+```
+
+To port it, move the key under `mcp` unchanged — the full Pi name is one of the tool's `mcp` targets:
+
+```jsonc
+// Before
+{
+  "permission": {
+    "*": "allow",
+    "mcp__danger_srv__wipe": "deny"
+  }
+}
+
+// After
+{
+  "permission": {
+    "*": "allow",
+    "mcp": {
+      "*": "allow",
+      "mcp__danger_srv__wipe": "deny"
+    }
+  }
+}
+```
+
+Inside `mcp`, rule position decides: put the key **after** any `"*"` catch-all, or the catch-all wins.
+
+When the rule was meant for the whole server, a server rule says so directly and survives a tool being renamed:
+
+```jsonc
+{
+  "permission": {
+    "mcp": {
+      "*": "allow",
+      "danger-srv": "deny"
+    }
+  }
+}
+```
+
+A wildcard key such as `"mcp__danger_srv__*"` ports the same way, or becomes the server rule above.
+
+## Other top-level wildcards
+
+Only keys starting with `mcp__` carry over.
+A top-level wildcard of another shape that used to match a Pi MCP tool's name, such as `"mcp_*"` or `"*__wipe"`, no longer reaches it, because the tool now resolves on the `mcp` surface rather than under its own name.
+It raises no notice; rewrite it as an `mcp` rule (`"mcp": {"*__wipe": "deny"}`) if you relied on it.
+
+## Rules written for Pi 0.99.0 and 0.99.1
+
+Pi 0.99.0 and 0.99.1 kept `-` in the tool name (`mcp__danger-srv__wipe`); Pi 0.99.2 replaced it with `_`.
+A top-level key written with the old spelling has matched nothing since 0.99.2.
+It raises the notice like any other `mcp__…` key, but relocating it does not make it match: no tool carries that name anymore.
+Replace it with a server rule as above, which matches `danger-srv` in either spelling.
+
+[#1001]: https://github.com/gotgenes/pi-packages/issues/1001

package/package.json

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

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

@@ -15,11 +15,13 @@ export interface ToolAccessIntent {
 }
 
 /**
- * Precomputed equivalent policy values for a path-shaped surface.
+ * Precomputed equivalent policy values for a surface, evaluated as-is.
  *
  * Not gate-emitted: the resolver produces it internally by unwrapping an
  * `access-path` intent via `matchValues()`, keeping the low-level manager
  * string-based (it never imports `AccessPath`). See {@link ResolvedAccessIntent}.
+ * A forwarded or service `mcp` query also arrives in this form, carrying the
+ * MCP target it names; the name predates that second use.
  *
  * This string seam is a deliberate, formalized boundary — not transitional
  * scaffolding to collapse into the manager (ADR-0002,
@@ -27,7 +29,7 @@ export interface ToolAccessIntent {
  */
 export interface PathValuesAccessIntent {
   kind: "path-values";
-  /** `"path"` or `"external_directory"`. */
+  /** A path-shaped surface (`path`, `external_directory`, a path tool) or `mcp`. */
   surface: string;
   values: readonly string[];
   agentName?: string;

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

@@ -1,8 +1,15 @@
 import { stripBashCommentLines } from "#src/access-intent/bash/bash-arity";
 import type { PathNormalizer } from "#src/path/path-normalizer";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
-import type { AccessIntent, ResolvedAccessIntent } from "./access-intent";
-import { createMcpPermissionTargets } from "./mcp-targets";
+import type {
+  AccessIntent,
+  PathValuesAccessIntent,
+  ResolvedAccessIntent,
+} from "./access-intent";
+import {
+  createMcpPermissionTargets,
+  createPiMcpToolTargets,
+} from "./mcp-targets";
 import { PATH_SURFACES, surfaceFamilyOf } from "./path-surfaces";
 import { classifyToolKind } from "./tool-kind";
 
@@ -14,16 +21,19 @@ import { classifyToolKind } from "./tool-kind";
  * For a path-shaped surface (`path`, `external_directory`, or a path-bearing
  * tool) carrying a non-empty value, it builds an `AccessPath` and emits an
  * `access-path` intent, so the resolver matches the lexical aliases ∪ canonical
- * (symlink-resolved) set — at parity with the gates (#486, #502). Every other
- * surface, and any value-less surface-level query, keeps the `tool` intent so
- * the manager's `normalizeInput` `["*"]` fallback is preserved.
+ * (symlink-resolved) set — at parity with the gates (#486, #502). An `mcp`
+ * query carrying a value evaluates that value as-is: an MCP target is already
+ * a candidate name, and rebuilding proxy input from it would derive only the
+ * status probe `mcp_status`. Every other surface, and any value-less
+ * surface-level query, keeps the `tool` intent so the manager's
+ * `normalizeInput` `["*"]` fallback is preserved.
  */
 export function buildAccessIntentForSurface(
   surface: string,
   value: string | undefined,
   normalizer: PathNormalizer,
   agentName: string | undefined,
-): AccessIntent {
+): AccessIntent | PathValuesAccessIntent {
   const pathValue = getNonEmptyString(value);
   if (pathValue !== null && PATH_SURFACES.has(surface)) {
     return {
@@ -33,6 +43,9 @@ export function buildAccessIntentForSurface(
       agentName,
     };
   }
+  if (pathValue !== null && surface === "mcp") {
+    return { kind: "path-values", surface, values: [pathValue], agentName };
+  }
   return {
     kind: "tool",
     surface,
@@ -48,9 +61,11 @@ export function buildAccessIntentForSurface(
  *
  * Unlike {@link buildAccessIntentForSurface}, this never touches a
  * `PathNormalizer` and never rebuilds an `AccessPath` — a path-shaped surface
- * gets a `path-values` intent carrying `matchValues` as-is (the values the
- * child already fixed), and every other surface gets a `tool` intent built
- * from its single portable value. `agentName` is always the requester's
+ * or `mcp` gets a `path-values` intent carrying `matchValues` as-is (the values
+ * the child already fixed), and every other surface gets a `tool` intent built
+ * from its single portable value. An `mcp` request carries the child's target;
+ * evaluating it alone can only be stricter than the child, since what the
+ * serving node adds is session grants. `agentName` is always the requester's
  * `principal.agentName` (ADR 0008 §3, agent-scoped serving).
  */
 export function buildResolvedIntentFromMatchValues(
@@ -58,7 +73,7 @@ export function buildResolvedIntentFromMatchValues(
   matchValues: readonly string[],
   agentName: string,
 ): ResolvedAccessIntent {
-  if (PATH_SURFACES.has(surface)) {
+  if (PATH_SURFACES.has(surface) || surface === "mcp") {
     return {
       kind: "path-values",
       surface,
@@ -134,8 +149,8 @@ export interface NormalizedInput {
  *
  * @param toolName - Normalized (trimmed) tool name from the tool-call event.
  * @param input    - Raw input payload from the tool-call event.
- * @param configuredMcpServerNames - Ordered list of MCP server names from the
- *   global MCP config, used to derive server-qualified MCP targets.
+ * @param configuredMcpServerNames - Ordered list of MCP server names from
+ *   Pi's `mcp.json` files, used to derive server-qualified MCP targets.
  */
 export function normalizeInput(
   toolName: string,
@@ -172,18 +187,16 @@ export function normalizeInput(
     }
 
     // --- MCP ---
-    case "mcp": {
-      const mcpTargets = [
-        ...createMcpPermissionTargets(input, configuredMcpServerNames),
-        "mcp",
-      ];
-      const fallbackTarget = mcpTargets[0] ?? "mcp";
-      return {
-        surface: "mcp",
-        values: mcpTargets,
-        resultExtras: { target: fallbackTarget },
-      };
-    }
+    case "mcp":
+      return normalizeMcpTargets(
+        createMcpPermissionTargets(input, configuredMcpServerNames),
+      );
+
+    // A Pi MCP tool's identity is its name; its input is the MCP arguments.
+    case "mcp-tool":
+      return normalizeMcpTargets(
+        createPiMcpToolTargets(toolName, configuredMcpServerNames),
+      );
 
     // --- All other surfaces (path-bearing tools and extension tools) ---
     // Path-bearing tools with a present path never reach here — the gate emits
@@ -198,3 +211,17 @@ export function normalizeInput(
       };
   }
 }
+
+/**
+ * The `mcp` surface's normalized form: the derived candidates, then the
+ * surface-wide `mcp` name, reported under the most specific candidate until a
+ * rule match names the one it matched.
+ */
+function normalizeMcpTargets(targets: readonly string[]): NormalizedInput {
+  const values = [...targets, "mcp"];
+  return {
+    surface: "mcp",
+    values,
+    resultExtras: { target: values[0] },
+  };
+}

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

@@ -1,4 +1,5 @@
 import { getNonEmptyString, toRecord } from "#src/value-guards";
+import { PI_MCP_TOOL_PREFIX } from "./tool-kind";
 
 /**
  * An ordered accumulator that owns the uniqueness invariant.
@@ -222,3 +223,73 @@ export function createMcpPermissionTargets(
   targets.add("mcp_status");
   return targets.toArray();
 }
+
+/**
+ * Derive the ordered MCP permission-lookup candidates for a tool Pi's built-in
+ * MCP registered under its own name, `mcp__<server>__<tool>`.
+ *
+ * The candidates mirror a proxied call's (`<server>_<tool>`, `<server>:<tool>`,
+ * `<server>`, `<tool>`, `mcp_call`) plus the full Pi name, so an `mcp` rule
+ * written for either client names the same call. Pi rewrites every character
+ * outside `[A-Za-z0-9_]` to `_` in the name, so the server is emitted in both
+ * spellings: the configured one from `mcp.json` (`danger-srv`) and the one in
+ * the name (`danger_srv`). Pi rejects two servers that differ only in `-` and
+ * `_`, which is what makes treating the two spellings as one server safe.
+ *
+ * The server is the longest configured name whose sanitized form prefixes the
+ * tool name; with none, the name splits at its first `__`.
+ */
+export function createPiMcpToolTargets(
+  toolName: string,
+  configuredServerNames: readonly string[],
+): string[] {
+  const rest = toolName.trim().slice(PI_MCP_TOOL_PREFIX.length);
+  const { spellings, tool } = resolvePiMcpServer(rest, configuredServerNames);
+
+  const targets = new McpTargetList();
+  for (const server of spellings) {
+    targets.add(`${server}_${tool}`);
+    targets.add(`${server}:${tool}`);
+    targets.add(server);
+  }
+  targets.add(tool);
+  targets.add(toolName.trim());
+  targets.add("mcp_call");
+  return targets.toArray();
+}
+
+/** The server spellings and tool a Pi MCP tool name (prefix removed) holds. */
+function resolvePiMcpServer(
+  rest: string,
+  configuredServerNames: readonly string[],
+): { spellings: string[]; tool: string } {
+  let sanitizedServer: string | null = null;
+  let configured: string[] = [];
+
+  for (const serverName of configuredServerNames) {
+    const trimmed = serverName.trim();
+    const sanitized = sanitizePiMcpName(trimmed);
+    if (!trimmed || !rest.startsWith(`${sanitized}__`)) continue;
+    if (sanitizedServer === null || sanitized.length > sanitizedServer.length) {
+      sanitizedServer = sanitized;
+      configured = [trimmed];
+    } else if (sanitized === sanitizedServer) {
+      configured.push(trimmed);
+    }
+  }
+
+  if (sanitizedServer === null) {
+    const separator = rest.indexOf("__");
+    sanitizedServer = rest.slice(0, separator);
+  }
+
+  return {
+    spellings: [...new Set([...configured, sanitizedServer])],
+    tool: rest.slice(sanitizedServer.length + 2),
+  };
+}
+
+/** Pi's MCP name sanitization: every character outside `[A-Za-z0-9_]` becomes `_`. */
+function sanitizePiMcpName(name: string): string {
+  return name.replace(/[^A-Za-z0-9_]/g, "_");
+}

package/src/access-intent/tool-input-path.ts

@@ -62,6 +62,7 @@ export function getToolInputPath(
     case "mcp":
       return byConvention(getNonEmptyString(toRecord(record.arguments).path));
     case "skill":
+    case "mcp-tool":
     case "extension": {
       const custom = extractors?.resolve(toolName);
       if (custom) {

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

@@ -22,25 +22,57 @@ import { PATH_BEARING_TOOLS } from "./path-surfaces";
  * (`docs/decisions/0002-path-values-string-boundary.md`).
  *
  * - `bash` — its own token-based path gates; extraction product is the command.
- * - `mcp` — extraction product is the qualified target.
+ * - `mcp` — the `mcp` proxy tool (e.g. pi-mcp-adapter), whose input names the
+ *   MCP call (`{ tool, server, args }`); extraction product is the qualified
+ *   target.
+ * - `mcp-tool` — one MCP server tool registered under its own name,
+ *   `mcp__<server>__<tool>` (Pi's built-in MCP); its input is the MCP
+ *   arguments themselves, so it shares the extension tools' input shape while
+ *   resolving on the `mcp` surface.
  * - `skill` — a distinct surface `normalizeInput`/`deriveSource` treat specially.
  * - `path` — a path-bearing built-in (`read`/`write`/`edit`/`grep`/`find`/`ls`);
  *   extraction product is `input.path`.
  * - `extension` — every other tool, plus the `external_directory`/`path` special
  *   surfaces that reach `deriveSource` as normalized names.
  */
-export type ToolKind = "bash" | "mcp" | "skill" | "path" | "extension";
+export type ToolKind =
+  | "bash"
+  | "mcp"
+  | "mcp-tool"
+  | "skill"
+  | "path"
+  | "extension";
 
 /** Classify a tool name into its {@link ToolKind}. */
 export function classifyToolKind(toolName: string): ToolKind {
   const name = toolName.trim();
   if (name === "bash") return "bash";
   if (name === "mcp") return "mcp";
+  if (isPiMcpToolName(name)) return "mcp-tool";
   if (name === "skill") return "skill";
   if (PATH_BEARING_TOOLS.has(name)) return "path";
   return "extension";
 }
 
+/** The prefix Pi's built-in MCP gives every server tool it registers. */
+export const PI_MCP_TOOL_PREFIX = "mcp__";
+
+/**
+ * True when a tool name has the shape Pi's built-in MCP registers a server
+ * tool under: `mcp__<server>__<tool>`, with non-empty server and tool parts.
+ *
+ * Pi builds the name with every character outside `[A-Za-z0-9_]` replaced by
+ * `_`, and codemode scripts call the tool by the same identifier, so the name
+ * itself is the stable contract (`extensions/mcp/tools.ts`,
+ * `createMcpToolName`).
+ */
+export function isPiMcpToolName(toolName: string): boolean {
+  if (!toolName.startsWith(PI_MCP_TOOL_PREFIX)) return false;
+  const rest = toolName.slice(PI_MCP_TOOL_PREFIX.length);
+  const separator = rest.indexOf("__");
+  return separator > 0 && separator + 2 < rest.length;
+}
+
 /** A shell invocation's effective command and optional working directory. */
 export interface ShellInvocation {
   /** The shell command string to decompose and gate. */
@@ -101,12 +133,25 @@ interface McpKindFields {
 }
 
 /**
- * True when a resolved check concerns an MCP call — either the invoked tool is
- * `mcp`, or the winning rule matched on the `mcp` surface (`source`). The
- * `source` disjunct is why this cannot reduce to `classifyToolKind(toolName)`:
- * `deriveSource` can set `source` to `mcp` on a result whose `toolName` is a
- * server-qualified string.
+ * True when a resolved check concerns an MCP call — the invoked tool is the
+ * `mcp` proxy or a Pi MCP tool, or the winning rule matched on the `mcp`
+ * surface (`source`). The `source` disjunct is why this cannot reduce to
+ * `classifyToolKind(toolName)`: `deriveSource` can set `source` to `mcp` on a
+ * result whose `toolName` is a server-qualified string.
  */
 export function isMcpCheck(check: McpKindFields): boolean {
-  return check.source === "mcp" || classifyToolKind(check.toolName) === "mcp";
+  if (check.source === "mcp") return true;
+  const kind = classifyToolKind(check.toolName);
+  return kind === "mcp" || kind === "mcp-tool";
+}
+
+/**
+ * True when a check concerns an MCP call whose tool input is a request *about*
+ * the call (the proxy's `{ tool, server, args }`) rather than the MCP
+ * arguments themselves. Such input is not previewed — the target already
+ * names the call — while a Pi MCP tool's arguments are shown like any other
+ * tool's input.
+ */
+export function isProxyMcpCheck(check: McpKindFields): boolean {
+  return isMcpCheck(check) && classifyToolKind(check.toolName) !== "mcp-tool";
 }

package/src/config/policy-loader.ts

@@ -133,6 +133,12 @@ export interface PolicyLoaderOptions {
   projectGlobalConfigPath?: string;
   projectAgentsDir?: string;
   globalMcpConfigPath?: string;
+  /**
+   * The project's `.pi/mcp.json`, read beside the global file the way Pi's
+   * built-in MCP reads it. Set only for a trusted project: the manager derives
+   * it from a cwd, and an untrusted project's cwd is withheld.
+   */
+  projectMcpConfigPath?: string;
   mcpServerNames?: readonly string[];
 }
 
@@ -150,6 +156,7 @@ export class FilePolicyLoader implements PolicyLoader {
   private readonly projectGlobalConfigPath: string | null;
   private readonly projectAgentsDir: string | null;
   private readonly globalMcpConfigPath: string;
+  private readonly projectMcpConfigPath: string | null;
   private readonly configuredMcpServerNamesOverride: readonly string[] | null;
 
   private globalConfigCache: FileCacheEntry<ScopeConfig> | null = null;
@@ -175,6 +182,7 @@ export class FilePolicyLoader implements PolicyLoader {
     this.projectAgentsDir = options.projectAgentsDir ?? null;
     this.globalMcpConfigPath =
       options.globalMcpConfigPath ?? defaultGlobalMcpConfigPath();
+    this.projectMcpConfigPath = options.projectMcpConfigPath ?? null;
     this.configuredMcpServerNamesOverride = options.mcpServerNames
       ? [
           ...new Set(
@@ -316,7 +324,9 @@ export class FilePolicyLoader implements PolicyLoader {
       return this.configuredMcpServerNamesOverride;
     }
 
-    const paths = [this.globalMcpConfigPath];
+    const paths = this.projectMcpConfigPath
+      ? [this.globalMcpConfigPath, this.projectMcpConfigPath]
+      : [this.globalMcpConfigPath];
     const stamp = paths
       .map((path) => `${path}:${getFileStamp(path)}`)
       .join("|");

package/src/handlers/before-agent-start.ts

@@ -22,8 +22,8 @@ import type { TurnPreparation } from "./session-turn-prep";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
-  /** The prompt rendered from `systemPromptOptions` as it stands right now. */
-  readonly systemPrompt: string;
+  /** Pi renders a string; a host may supply ordered prompt fragments instead. */
+  readonly systemPrompt: string | readonly string[];
   /**
    * The mutable parts Pi renders the prompt from; later handlers, and Pi
    * itself, see what this handler writes here. `customPrompt` says whether Pi
@@ -32,7 +32,7 @@ interface BeforeAgentStartPayload {
    * renders from, and `sections` is where it is stated. `skills` is the
    * catalogue Pi renders, which policy narrows.
    */
-  systemPromptOptions: Pick<
+  systemPromptOptions?: Pick<
     NormalizedBuildSystemPromptOptions,
     "customPrompt" | "toolSnippets" | "promptGuidelines" | "sections" | "skills"
   >;
@@ -56,10 +56,12 @@ export function shouldExposeTool(
 /**
  * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
  *
- * Every change to the prompt is stated through `event.systemPromptOptions`,
+ * When provided, prompt changes are stated through `event.systemPromptOptions`,
  * never as a returned `systemPrompt`: a returned prompt is frozen for the run,
  * so the sections an extension later in the chain adds (Pi's own
  * `<mcp_servers>` among them) would never reach the provider (#999).
+ * Without those options, only tool filtering and skill path resolution run;
+ * there is no mutable section or skill catalogue to narrow.
  *
  * Narrowing the active set is enough for a prompt Pi wrote: Pi renders its
  * `<tools>` and `<rules>` from the reconciled active set. A subagent child's
@@ -97,7 +99,12 @@ export class AgentPrepHandler {
   ): Promise<BeforeAgentStartEventResult> {
     this.turnPrep.prepare(ctx);
 
-    const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
+    // Normalize once at the boundary, before either prompt consumer reads it.
+    const systemPrompt =
+      typeof event.systemPrompt === "string"
+        ? event.systemPrompt
+        : event.systemPrompt.join("\n");
+    const agentName = this.session.resolveAgentName(ctx, systemPrompt);
     const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
       this.observeToolSurface(registered),
@@ -118,7 +125,7 @@ export class AgentPrepHandler {
     }
 
     const options = event.systemPromptOptions;
-    if (this.isSubagentUnderCustomPrompt(event, ctx)) {
+    if (options && this.isSubagentUnderCustomPrompt(event, ctx)) {
       const sections = renderToolSurfaceSections({
         allowedTools,
         toolSnippets: options.toolSnippets,
@@ -134,12 +141,14 @@ export class AgentPrepHandler {
     // read before the skill list is narrowed.
     this.session.setActiveSkillEntries(
       visibleSkillPromptEntries(
-        event.systemPrompt,
+        systemPrompt,
         this.resolver,
         agentName,
         this.session.getPathNormalizer(),
       ),
     );
+    if (!options) return {};
+
     // Denials are judged on the list Pi renders `<skills>` from, not on the
     // rendered prompt: that prompt predates this turn's tool changes, and on
     // the turn `read`/`bash` return from a full denial it lists no catalogue.
@@ -181,5 +190,5 @@ export class AgentPrepHandler {
  * test, so an empty string reads here the way it reads there: as none.
  */
 function hasCustomPrompt(event: BeforeAgentStartPayload): boolean {
-  return Boolean(event.systemPromptOptions.customPrompt);
+  return Boolean(event.systemPromptOptions?.customPrompt);
 }

package/src/handlers/gates/helpers.ts

@@ -116,6 +116,7 @@ export function deriveDecisionValue(
     case "bash":
       return check.command ?? toolName;
     case "mcp":
+    case "mcp-tool":
       return check.target ?? toolName;
     case "path":
     case "skill":

package/src/handlers/gates/tool.ts

@@ -6,6 +6,8 @@ import {
   type ShellInvocation,
 } from "#src/access-intent/tool-kind";
 import {
+  type SessionApprovalSuggestion,
+  suggestExactSessionPattern,
   suggestPathSessionPattern,
   suggestSessionPattern,
 } from "#src/presentation/pattern-suggest";
@@ -56,6 +58,45 @@ function deriveSuggestionValue(
   }
 }
 
+/**
+ * The surface a tool call is gated on.
+ *
+ * A shell invocation (native `bash` or an aliased shell tool) is gated on the
+ * `bash` surface, and a Pi MCP tool on the `mcp` surface — their session rule,
+ * decision value, and suggestion are shaped by that surface — while the
+ * invoked tool name is preserved in the prompt and review log so a user sees
+ * which tool actually ran (#574).
+ */
+function gateSurfaceOf(
+  toolName: string,
+  shell: ShellInvocation | null | undefined,
+): string {
+  if (shell) return "bash";
+  if (classifyToolKind(toolName) === "mcp-tool") return "mcp";
+  return toolName;
+}
+
+/**
+ * The session approval for a gate whose value is not a path.
+ *
+ * A Pi MCP tool is approved by its own full name, which is one of its `mcp`
+ * candidates: exactly the tool asked about, never the wider server prefix the
+ * proxy target heuristic would suggest.
+ */
+function suggestValueSessionPattern(
+  toolName: string,
+  gateSurface: string,
+  check: PermissionCheckResult,
+): SessionApprovalSuggestion {
+  if (classifyToolKind(toolName) === "mcp-tool") {
+    return suggestExactSessionPattern(gateSurface, toolName.trim());
+  }
+  return suggestSessionPattern(
+    gateSurface,
+    deriveSuggestionValue(gateSurface, check),
+  );
+}
+
 /**
  * Build a pure descriptor for the normal tool permission gate.
  *
@@ -69,11 +110,7 @@ export function describeToolGate(
   pathAccess?: ToolPathAccess,
   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 gateSurface = gateSurfaceOf(tcc.toolName, shell);
 
   const permissionLogContext = formatter.getPermissionLogContext(
     check,
@@ -84,10 +121,7 @@ export function describeToolGate(
   // Compute session approval suggestion for the "for this session" option.
   const suggestion = pathAccess
     ? suggestPathSessionPattern(gateSurface, pathAccess.approvalPattern)
-    : suggestSessionPattern(
-        gateSurface,
-        deriveSuggestionValue(gateSurface, check),
-      );
+    : suggestValueSessionPattern(tcc.toolName, gateSurface, check);
 
   const payload = buildToolAskPayload({
     check,

package/src/policy/normalize.ts

@@ -1,4 +1,8 @@
 import { surfaceFamilyMembers } from "#src/access-intent/path-surfaces";
+import {
+  isPiMcpToolName,
+  PI_MCP_TOOL_PREFIX,
+} from "#src/access-intent/tool-kind";
 import type { FlatPermissionConfig, PatternValue } from "#src/types";
 import { isDenyWithReason, isPermissionState } from "#src/types";
 import type { Rule, Ruleset } from "./rule";
@@ -115,3 +119,46 @@ export function normalizeFlatConfig(permission: FlatPermissionConfig): Ruleset {
   }
   return rules;
 }
+
+/** The rules with relocated copies appended, and the keys that were copied. */
+export interface McpToolKeyRelocation {
+  rules: Ruleset;
+  /** Each relocated surface key, in rule order. */
+  relocatedKeys: string[];
+}
+
+/**
+ * Copy the catch-all rule of every top-level key that can name a Pi MCP tool
+ * onto the `mcp` surface, with the key as its pattern.
+ *
+ * A Pi MCP tool (`mcp__<server>__<tool>`) once resolved on its own name, so a
+ * top-level key naming it (or a surface wildcard such as `mcp__srv__*`) was the
+ * only rule that reached it. The tool now resolves on `mcp`, where its full
+ * name is one of its candidates, so the same key is the same rule there.
+ *
+ * The copies are appended after every other rule, in their original order:
+ * the key was the only rule that applied to the tool before, so it keeps the
+ * final say over the `mcp` rules that newly reach it. The original rule stays
+ * where it was, because a key such as `mcp__*` also matches tools that still
+ * resolve on their own name (`mcp__foo`), and moving it would drop them. A key
+ * that can name no Pi MCP tool (`mcp__foo`) is not copied, and a non-`*`
+ * pattern under any key never matched (a tool surface is evaluated with `*`).
+ */
+export function relocateMcpToolKeyRules(rules: Ruleset): McpToolKeyRelocation {
+  const relocated = rules
+    .filter((rule) => rule.pattern === "*" && canNamePiMcpTool(rule.surface))
+    .map((rule): Rule => ({ ...rule, surface: "mcp", pattern: rule.surface }));
+  return {
+    rules: [...rules, ...relocated],
+    relocatedKeys: relocated.map((rule) => rule.pattern),
+  };
+}
+
+/**
+ * Whether a top-level surface key can match a Pi MCP tool name: the name
+ * itself, or an `mcp__`-prefixed wildcard.
+ */
+function canNamePiMcpTool(surfaceKey: string): boolean {
+  if (isPiMcpToolName(surfaceKey)) return true;
+  return surfaceKey.startsWith(PI_MCP_TOOL_PREFIX) && /[*?]/.test(surfaceKey);
+}

package/src/policy/permission-manager.ts

@@ -21,7 +21,7 @@ import type {
   PermissionState,
 } from "#src/types";
 import { isPermissionState } from "#src/types";
-import { normalizeFlatConfig } from "./normalize";
+import { normalizeFlatConfig, relocateMcpToolKeyRules } from "./normalize";
 import type { Rule, RuleOrigin, Ruleset } from "./rule";
 import {
   evaluate,
@@ -30,7 +30,7 @@ import {
   isSurfaceFullyDenied,
   rewriteAsksToYolo,
 } from "./rule";
-import { mergeScopesWithOrigins } from "./scope-merge";
+import { type MergedScopes, mergeScopesWithOrigins } from "./scope-merge";
 import {
   composeRuleset,
   synthesizeBaseline,
@@ -62,6 +62,11 @@ type ResolvedPermissions = {
    * names also drive the fail-closed notice in {@link getConfigIssues}.
    */
   failClosedScopes: RuleOrigin[];
+  /**
+   * Top-level permission keys naming Pi MCP tools, relocated onto the `mcp`
+   * surface; they drive the port notice in {@link getConfigIssues}.
+   */
+  legacyMcpToolKeys: string[];
 };
 
 /**
@@ -152,7 +157,8 @@ export class PermissionManager implements ScopedPermissionManager {
 
   getConfigIssues(agentName?: string): string[] {
     // Trigger a load/resolve to ensure issues are collected.
-    const { failClosedScopes } = this.resolvePermissions(agentName);
+    const { failClosedScopes, legacyMcpToolKeys } =
+      this.resolvePermissions(agentName);
     const issues = [...this.loader.getConfigIssues()];
     if (failClosedScopes.length > 0) {
       issues.push(
@@ -161,6 +167,9 @@ export class PermissionManager implements ScopedPermissionManager {
           `until the configuration is corrected.`,
       );
     }
+    if (legacyMcpToolKeys.length > 0) {
+      issues.push(formatMcpToolKeyPortNotice(legacyMcpToolKeys));
+    }
     return issues;
   }
 
@@ -201,26 +210,16 @@ export class PermissionManager implements ScopedPermissionManager {
     const universalFallbackOrigin: RuleOrigin =
       origins.get("*")?.get("*") ?? "builtin";
 
-    // Build config rules from everything except the universal "*" key.
-    const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
-      Object.entries(mergedPermission).filter(([k]) => k !== "*"),
-    );
-
-    // Normalize to config rules, tagged with "config" layer and their origin.
-    const configRules: Ruleset = normalizeFlatConfig(
-      permissionWithoutUniversal,
-    ).map(
-      (r): Rule => ({
-        ...r,
-        layer: "config",
-        origin: origins.get(r.surface)?.get(r.pattern) ?? "builtin",
-      }),
-    );
+    const configRules = buildConfigRules(mergedPermission, origins);
+    // A top-level `mcp__…` key now names an `mcp` candidate. The baseline reads
+    // the rules as written, so a relocated `allow` on one Pi MCP tool does not
+    // newly open the proxy's discovery targets.
+    const relocation = relocateMcpToolKeyRules(configRules);
 
     const composedRules = composeRuleset(
       synthesizeDefaults(universalFallback, universalFallbackOrigin),
       synthesizeBaseline(configRules),
-      configRules,
+      relocation.rules,
     );
 
     // Fail closed when a non-global scope's config is invalid: floor every
@@ -241,6 +240,7 @@ export class PermissionManager implements ScopedPermissionManager {
     const value: ResolvedPermissions = {
       composedRules: effectiveRules,
       failClosedScopes,
+      legacyMcpToolKeys: [...new Set(relocation.relocatedKeys)],
     };
     this.resolvedPermissionsCache.set(cacheKey, { stamp, value });
     return value;
@@ -263,10 +263,14 @@ export class PermissionManager implements ScopedPermissionManager {
    */
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     const { composedRules } = this.resolvePermissions(agentName);
-    // Every surface (special, bash, mcp, skill, path-bearing, and extension
-    // tools) resolves its tool-level state identically: evaluate the surface
-    // name against the "*" catch-all value. There is no per-kind branch.
-    return evaluate(toolName.trim(), "*", composedRules, this.flavor).action;
+    const name = toolName.trim();
+    if (classifyToolKind(name) === "mcp-tool") {
+      return this.resolvePiMcpTool(name, composedRules);
+    }
+    // Every other surface (special, bash, mcp, skill, path-bearing, and
+    // extension tools) resolves its tool-level state identically: evaluate the
+    // surface name against the "*" catch-all value.
+    return evaluate(name, "*", composedRules, this.flavor).action;
   }
 
   /**
@@ -284,7 +288,30 @@ export class PermissionManager implements ScopedPermissionManager {
    */
   isToolFullyDenied(toolName: string, agentName?: string): boolean {
     const { composedRules } = this.resolvePermissions(agentName);
-    return isSurfaceFullyDenied(toolName.trim(), composedRules, this.flavor);
+    const name = toolName.trim();
+    if (classifyToolKind(name) === "mcp-tool") {
+      return this.resolvePiMcpTool(name, composedRules) === "deny";
+    }
+    return isSurfaceFullyDenied(name, composedRules, this.flavor);
+  }
+
+  /**
+   * The action a Pi MCP tool resolves to on the `mcp` surface.
+   *
+   * Its candidates come from its name alone, never its input, so this one
+   * answer is both its tool-level state and whether it is fully denied.
+   */
+  private resolvePiMcpTool(
+    toolName: string,
+    composedRules: Ruleset,
+  ): PermissionState {
+    const { surface, values } = normalizeInput(
+      toolName,
+      undefined,
+      this.loader.getConfiguredMcpServerNames(),
+    );
+    return evaluateAnyValue(surface, values, composedRules, this.flavor).rule
+      .action;
   }
 
   /**
@@ -389,6 +416,39 @@ function buildCheckResult(
   };
 }
 
+const MCP_TOOL_KEY_MIGRATION_GUIDE =
+  "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/migration/1001-pi-mcp-tools-on-mcp-surface.md";
+
+/** The notice asking the operator to move top-level `mcp__…` keys under `mcp`. */
+function formatMcpToolKeyPortNotice(keys: readonly string[]): string {
+  const named = keys.map((key) => `"${key}"`).join(", ");
+  return (
+    `Top-level permission keys naming Pi MCP tools are applied as "mcp" rules: ${named}. ` +
+    `Move them under "mcp" — see ${MCP_TOOL_KEY_MIGRATION_GUIDE}`
+  );
+}
+
+/**
+ * Build the config-layer rules from the merged permission object: every key
+ * except the universal `"*"` (which feeds `synthesizeDefaults` only), each
+ * rule tagged with the `config` layer and the scope that contributed it.
+ */
+function buildConfigRules(
+  mergedPermission: FlatPermissionConfig,
+  origins: MergedScopes["origins"],
+): Ruleset {
+  const permissionWithoutUniversal: FlatPermissionConfig = Object.fromEntries(
+    Object.entries(mergedPermission).filter(([k]) => k !== "*"),
+  );
+  return normalizeFlatConfig(permissionWithoutUniversal).map(
+    (r): Rule => ({
+      ...r,
+      layer: "config",
+      origin: origins.get(r.surface)?.get(r.pattern) ?? "builtin",
+    }),
+  );
+}
+
 /**
  * Derive `PolicyLoaderOptions` from an agentDir + an optional cwd.
  * Setting agentsDir explicitly from agentDir removes the hidden
@@ -403,6 +463,9 @@ function derivePolicyLoaderOptions(
     agentsDir: join(agentDir, "agents"),
     projectGlobalConfigPath: cwd ? getProjectConfigPath(cwd) : undefined,
     projectAgentsDir: cwd ? getProjectAgentsDir(cwd) : undefined,
+    // Pi's built-in MCP reads these two files (`extensions/mcp/config.ts`).
+    globalMcpConfigPath: join(agentDir, "mcp.json"),
+    projectMcpConfigPath: cwd ? join(cwd, ".pi", "mcp.json") : undefined,
   };
 }
 
@@ -414,7 +477,7 @@ function derivePolicyLoaderOptions(
  *
  * - session          → "session" (always, all surfaces)
  * - mcp + default    → "default"
- * - mcp + other      → "mcp"
+ * - mcp + other      → "mcp" (the proxy and Pi MCP tools alike)
  * - special          → "special" (always)
  * - skill            → "skill" (always)
  * - bash             → "bash" (always)
@@ -431,6 +494,7 @@ function deriveSource(
 
   switch (classifyToolKind(toolName)) {
     case "mcp":
+    case "mcp-tool":
       return rule.layer === "default" ? "default" : "mcp";
     case "skill":
       return "skill";

package/src/presentation/pattern-suggest.ts

@@ -233,9 +233,16 @@ export function suggestPathSessionPattern(
   surface: string,
   approvalPattern: string,
 ): SessionApprovalSuggestion {
-  return {
-    surface,
-    pattern: approvalPattern,
-    label: buildLabel(approvalPattern, surface),
-  };
+  return suggestExactSessionPattern(surface, approvalPattern);
+}
+
+/**
+ * Build the suggestion for a pattern the caller already holds verbatim, such
+ * as a Pi MCP tool's full name on the `mcp` surface: no wildcard is derived.
+ */
+export function suggestExactSessionPattern(
+  surface: string,
+  pattern: string,
+): SessionApprovalSuggestion {
+  return { surface, pattern, label: buildLabel(pattern, surface) };
 }

package/src/presentation/permission-prompts.ts

@@ -18,8 +18,9 @@ export function formatUnknownToolReason(
   const availableList =
     preview.length > 0 ? `${preview.join(", ")}${suffix}` : "none";
 
+  const kind = classifyToolKind(toolName);
   const mcpHint =
-    classifyToolKind(toolName) === "mcp"
+    kind === "mcp" || kind === "mcp-tool"
       ? ""
       : ' If this was intended as an MCP server tool, call the registered \'mcp\' tool when available (for example: {"tool":"server:tool"}).';
 

package/src/presentation/tool-ask-payload.ts

@@ -1,4 +1,8 @@
-import { classifyToolKind, isMcpCheck } from "#src/access-intent/tool-kind";
+import {
+  classifyToolKind,
+  isMcpCheck,
+  isProxyMcpCheck,
+} from "#src/access-intent/tool-kind";
 import type { ToolPreviewFormatter } from "#src/tool-input/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
@@ -45,7 +49,7 @@ export function buildToolAskPayload(facts: ToolAskFacts): PromptPayload {
     },
     evidence: bash
       ? fullCommandEvidence(facts)
-      : inputPreviewEvidence(facts, mcp),
+      : inputPreviewEvidence(facts, isProxyMcpCheck(check)),
     annotations: [],
   };
 }
@@ -86,15 +90,16 @@ function fullCommandEvidence(facts: ToolAskFacts): PromptEvidence[] {
 /**
  * The per-tool input preview, when a formatter is registered and produces one.
  *
- * An MCP ask previews under the `mcp` key rather than the qualified target, so
- * a registered MCP formatter is consulted for every server.
+ * A proxied MCP ask previews under the `mcp` key rather than the qualified
+ * target, so a registered MCP formatter is consulted for every server. A Pi
+ * MCP tool's input is its own arguments, so it previews under its own name.
  */
 function inputPreviewEvidence(
   facts: ToolAskFacts,
-  mcp: boolean,
+  proxyMcp: boolean,
 ): PromptEvidence[] {
   const preview = facts.formatter?.formatToolInputForPrompt(
-    mcp ? "mcp" : facts.check.toolName,
+    proxyMcp ? "mcp" : facts.check.toolName,
     facts.input,
   );
   return preview ? [{ label: "input", text: preview, detail: null }] : [];

package/src/service/permissions-service.ts

@@ -1,4 +1,7 @@
-import type { AccessIntent } from "#src/access-intent/access-intent";
+import type {
+  AccessIntent,
+  PathValuesAccessIntent,
+} from "#src/access-intent/access-intent";
 import { buildAccessIntentForSurface } from "#src/access-intent/input-normalizer";
 import type { Authorizer } from "#src/authority/authorizer";
 import type { AuthorizerRegistrar } from "#src/authority/authorizer-registry";
@@ -23,7 +26,7 @@ import { resolveBashAdvisoryCheck } from "./bash-advisory-check";
  * `PermissionResolver` satisfies it.
  */
 interface ResolverForService {
-  resolve(intent: AccessIntent): PermissionCheckResult;
+  resolve(intent: AccessIntent | PathValuesAccessIntent): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   isToolFullyDenied(toolName: string, agentName?: string): boolean;
 }

package/src/tool-input/tool-preview-formatter.ts

@@ -1,4 +1,7 @@
-import { classifyToolKind, isMcpCheck } from "#src/access-intent/tool-kind";
+import {
+  classifyToolKind,
+  isProxyMcpCheck,
+} from "#src/access-intent/tool-kind";
 import type { PermissionCheckResult } from "#src/types";
 import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
@@ -157,7 +160,10 @@ export class ToolPreviewFormatter {
     input: unknown,
     pathBearingTools: ReadonlySet<string>,
   ): string | undefined {
-    if (classifyToolKind(result.toolName) === "bash" || isMcpCheck(result)) {
+    if (
+      classifyToolKind(result.toolName) === "bash" ||
+      isProxyMcpCheck(result)
+    ) {
       return undefined;
     }