@gotgenes/pi-permission-system 36.2.1 → 38.0.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.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)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** require Pi 1.0.0 or later ([9c76ae3](https://github.com/gotgenes/pi-packages/commit/9c76ae30dd58b0a94524f753f7c72ff356231294)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+
+### Bug Fixes
+
+* **pi-permission-system:** keep prompt sections other extensions add, such as <mcp_servers> ([1abdfe4](https://github.com/gotgenes/pi-packages/commit/1abdfe4901a27cb8ff3d85a965fc07b3be874624)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+* **pi-permission-system:** keep later prompt sections when a skill is denied ([dafd83b](https://github.com/gotgenes/pi-packages/commit/dafd83b075b01ef39335822f8b5122c56ee00b97)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
+### Documentation
+
+* **pi-permission-system:** note the Pi 1.0.0 requirement under Upgrading ([5bc932c](https://github.com/gotgenes/pi-packages/commit/5bc932cf9936728c0e3c551fdbea6a7009108958)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+* **pi-permission-system:** record prompt changes through systemPromptOptions ([b11051f](https://github.com/gotgenes/pi-packages/commit/b11051f1365a635b67e70dea126c8a49ff9ef31b)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
 ## [36.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.0...pi-permission-system-v36.2.1) (2026-10-01)
 
 

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
@@ -155,6 +155,12 @@ Third-party packages are maintained by their authors; review one before granting
 
 ## Upgrading
 
+### The major after 36.x — requires Pi 1.0.0
+
+The extension now requires `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 1.0.0 or later.
+Upgrade Pi to 1.0.0 before upgrading this package; on an older Pi, stay on the 36.x line.
+No configuration change is needed.
+
 ### 22.0.0 — project config requires project trust
 
 Project-scoped configuration (the project `config.json` and project-agent frontmatter — both permission policy and runtime knobs such as `yoloMode`) is now loaded only when Pi reports the project as trusted.

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                                                                                                                            |
@@ -1314,11 +1341,11 @@ permission:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                                                                                                                                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `before_agent_start` | Filters the active tool set (restrict-only), restates the tool list and guidelines at the end of the system prompt to match (except under a custom system prompt outside a subagent), and hides denied skills |
-| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                                                |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                                                 |
+| Hook                 | Behavior                                                                                                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `before_agent_start` | Filters the active tool set (restrict-only), states a subagent child's own tool list and rules, and hides denied skills, all through pi's prompt options rather than a rewritten prompt |
+| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                          |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                           |
 
 Additional behaviors:
 
@@ -1326,20 +1353,22 @@ Additional behaviors:
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
 - Policy is applied to the tool surface pi has activated over the session, not to the previous turn's filtered result, so removing a `deny` rule restores the tool it had hidden without restarting pi.
   A tool that stops being active for any other reason (another extension deactivating it, pi unregistering it) is not restored.
-- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt parts an extension receives before the extension runs, so the restored tool has no one-line description to render until it is already active
 - A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
-- The tool list and guidelines are **relocated** rather than edited in place: the copies pi wrote are removed, and this session's own are rendered at the end of the system prompt, after the working directory pi states last.
-  They take the shape pi writes them in: `Available tools:` and `Guidelines:` sections after a `Current working directory:` footer through pi 0.85, and `<tools>` and `<rules>` sections after a `<cwd>` section from pi 0.86.
-  Each session states its own tool surface, which is what keeps a subagent child's inherited prompt byte-identical to its parent's (see [ADR 0014](decisions/0014-tool-surface-is-node-local-prose.md)); the tool list moves to the end of the prompt for every session on pi's default prompt, whether or not anything is denied.
-  A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
+- Every change this extension makes to the system prompt goes through pi's `systemPromptOptions`; it never returns a rewritten prompt.
+  A returned prompt is sent as the whole prompt, which would drop the sections other extensions add after this one runs, such as pi's `<mcp_servers>` list of `codemode` and `deferred` MCP servers (see [ADR 0015](decisions/0015-prompt-changes-through-system-prompt-options.md)).
+- On pi's default prompt, the tool list and guidelines stay where pi writes them, as its `<tools>` and `<rules>` sections, and pi renders them from the filtered active set, so a denied tool and its guidelines are absent and a restored tool is listed on the turn it returns.
+- A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
   Tool filtering and enforcement still apply, and the model still receives only the allowed tools in the request's tool list.
-  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it still gets its own tool list and rules at the end, while any custom text it inherited stays untouched.
-- The rendered sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones
-- The prompt is recomputed and returned on every turn but is stable across turns for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn.
+  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it gets its own `<tools>` and `<rules>` sections, placed after the working directory, while any custom text it inherited stays untouched.
+  The child's sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones.
+- A subagent child running with `@gotgenes/pi-subagents` needs a release that drops the parent's `<tools>` and `<rules>` from the prompt the child inherits; with an older one, the child shows the parent's tool list as well as its own.
+- A denied skill is removed from the skills catalogue pi renders.
+  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": "36.2.1",
+  "version": "38.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -63,13 +63,13 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.79.0",
-    "@earendil-works/pi-tui": ">=0.79.0"
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.11",
-    "@earendil-works/pi-coding-agent": "0.79.1",
-    "@earendil-works/pi-tui": "0.79.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/node": "^22.15.3",
     "rollup": "^4.63.1",
     "rollup-plugin-dts": "^6.5.1",

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) {